Envelope.ts

Envelope.ts overview

Defines the transport envelopes exchanged by cluster entities.

Request envelopes wrap decoded RPC payloads with the target entity address, RPC tag, request id, headers, and optional tracing context. The module also includes acknowledgement envelopes for streamed reply chunks, interrupt envelopes for in-flight requests, JSON codecs for partially decoded envelopes, guards, request constructors, and storage primary-key helpers.

Since v4.0.0

---

Exports Grouped by Category

• constructors
  • makeRequest
• models
  • AckChunk (class)
    • withRequestId (method)
    • [TypeId] (property)
  • AckChunkEncoded (interface)
  • Encoded (type alias)
  • Envelope (type alias)
  • Interrupt (class)
    • withRequestId (method)
    • [TypeId] (property)
  • InterruptEncoded (interface)
  • PartialRequest (class)
  • PartialRequestEncoded (interface)
  • Request (interface)
• primary key
  • primaryKey
  • primaryKeyByAddress
• refinements
  • isEnvelope
• schemas
  • Partial
  • Partial (type alias)
  • PartialArray
  • PartialJson
• serialization
  • Envelope
  • Request
  • RequestTransform
• type IDs
  • TypeId
• utils
  • Envelope (namespace)
    • Any (type alias)
  • Request (namespace)
    • Any (type alias)

---

constructors

makeRequest

Constructs a runtime request envelope and attaches the envelope type identifier.

Details

Tracing fields are included only when a traceId is provided.

Signature

declare const makeRequest: <Rpc extends Rpc.Any>(options: {
  readonly requestId: Snowflake
  readonly address: EntityAddress
  readonly tag: Rpc.Tag<Rpc>
  readonly payload: Rpc.Payload<Rpc>
  readonly headers: Headers.Headers
  readonly traceId?: string | undefined
  readonly spanId?: string | undefined
  readonly sampled?: boolean | undefined
}) => Request<Rpc>

Source

Since v4.0.0

models

AckChunk (class)

Represents an envelope acknowledging receipt of a streamed reply chunk for a request.

Details

The replyId identifies the chunk reply that has been received.

Signature

declare class AckChunk

Source

Since v4.0.0

withRequestId (method)

Returns a copy of this acknowledgement associated with the supplied request id.

Signature

declare const withRequestId: (requestId: Snowflake) => AckChunk

Source

Since v4.0.0

[TypeId] (property)

Marks this value as a cluster envelope for runtime guards.

Signature

readonly [TypeId]: "~effect/cluster/Envelope"

Source

Since v4.0.0

AckChunkEncoded (interface)

Serialized JSON shape of an AckChunk envelope.

Signature

export interface AckChunkEncoded {
  readonly _tag: "AckChunk"
  readonly id: string
  readonly address: {
    readonly shardId: {
      readonly group: string
      readonly id: number
    }
    readonly entityType: string
    readonly entityId: string
  }
  readonly requestId: string
  readonly replyId: string
}

Source

Since v4.0.0

Encoded (type alias)

JSON-serializable form of a cluster envelope.

Signature

type Encoded = PartialRequestEncoded | AckChunkEncoded | InterruptEncoded

Source

Since v4.0.0

Envelope (type alias)

Union of cluster envelopes exchanged for an RPC request.

Details

An envelope is either a request, an acknowledgement for a streamed reply chunk, or an interrupt signal.

Signature

type Envelope<R> = Request<R> | AckChunk | Interrupt

Source

Since v4.0.0

Interrupt (class)

Represents an envelope used to interrupt an in-flight entity request.

Signature

declare class Interrupt

Source

Since v4.0.0

withRequestId (method)

Returns a copy of this interrupt associated with the supplied request id.

Signature

declare const withRequestId: (requestId: Snowflake) => Interrupt

Source

Since v4.0.0

[TypeId] (property)

Marks this value as a cluster envelope for runtime guards.

Signature

readonly [TypeId]: "~effect/cluster/Envelope"

Source

Since v4.0.0

InterruptEncoded (interface)

Serialized JSON shape of an Interrupt envelope.

Signature

export interface InterruptEncoded {
  readonly _tag: "Interrupt"
  readonly id: string
  readonly address: {
    readonly shardId: {
      readonly group: string
      readonly id: number
    }
    readonly entityType: string
    readonly entityId: string
  }
  readonly requestId: string
}

Source

Since v4.0.0

PartialRequest (class)

Schema for a request envelope before its RPC payload has been decoded.

Details

The envelope metadata is decoded, while the payload remains unknown until it is decoded with the target RPC payload schema.

Signature

declare class PartialRequest

Source

Since v4.0.0

PartialRequestEncoded (interface)

Serialized JSON shape of a request envelope.

Details

Identifiers are encoded as strings and the RPC payload remains unknown until decoded with the RPC schema.

Signature

export interface PartialRequestEncoded {
  readonly _tag: "Request"
  readonly requestId: string
  readonly address: {
    readonly shardId: {
      readonly group: string
      readonly id: number
    }
    readonly entityType: string
    readonly entityId: string
  }
  readonly tag: string
  readonly payload: unknown
  readonly headers: ReadonlyRecord<string, string>
  readonly traceId?: string
  readonly spanId?: string
  readonly sampled?: boolean
}

Source

Since v4.0.0

Request (interface)

Runtime envelope for an RPC request addressed to a specific entity.

Details

It carries the request ID, entity address, RPC tag, decoded payload, request headers, and optional tracing context.

Signature

export interface Request<in out Rpc extends Rpc.Any> {
  readonly [TypeId]: typeof TypeId
  readonly _tag: "Request"
  readonly requestId: Snowflake
  readonly address: EntityAddress
  readonly tag: Rpc.Tag<Rpc>
  readonly payload: Rpc.Payload<Rpc>
  readonly headers: Headers.Headers
  readonly traceId?: string
  readonly spanId?: string
  readonly sampled?: boolean
}

Source

Since v4.0.0

primary key

primaryKey

Returns the storage primary key for a request envelope whose payload has a primary key, or null when the envelope is not a keyed request.

Signature

declare const primaryKey: <R extends Rpc.Any>(envelope: Envelope<R>) => string | null

Source

Since v4.0.0

primaryKeyByAddress

Builds a storage primary-key string from an entity address, RPC tag, and payload primary-key ID.

Signature

declare const primaryKeyByAddress: (options: {
  readonly address: EntityAddress
  readonly tag: string
  readonly id: string
}) => string

Source

Since v4.0.0

refinements

isEnvelope

Returns true when the supplied value is a runtime cluster envelope.

Details

The check is based on the envelope type identifier.

Signature

declare const isEnvelope: (u: unknown) => u is Envelope<any>

Source

Since v4.0.0

schemas

Partial

Schema for partially decoded cluster envelopes.

Details

It accepts PartialRequest, AckChunk, and Interrupt envelope values.

Signature

declare const Partial: Schema.Union<readonly [typeof PartialRequest, typeof AckChunk, typeof Interrupt]>

Source

Since v4.0.0

Partial (type alias)

Decoded value type produced by the Partial envelope schema.

Signature

type Partial = typeof Partial.Type

Source

Since v4.0.0

PartialArray

Schema for mutable arrays of JSON-encoded partial cluster envelopes.

Signature

declare const PartialArray: Schema.mutable<
  Schema.$Array<Schema.Codec<PartialRequest | AckChunk | Interrupt, Encoded, never, never>>
>

Source

Since v4.0.0

PartialJson

JSON codec for partial cluster envelopes.

Signature

declare const PartialJson: Schema.Codec<PartialRequest | AckChunk | Interrupt, Encoded, never, never>

Source

Since v4.0.0

serialization

Envelope

Schema for runtime cluster envelopes recognized by their type identifier.

Signature

declare const Envelope: Schema.declare<Envelope<any>, Envelope<any>>

Source

Since v4.0.0

Request

Schema for runtime request envelopes.

Signature

declare const Request: Schema.declare<Request.Any, Request.Any>

Source

Since v4.0.0

RequestTransform

Transforms plain request data with makeRequest and encodes request envelopes back to their raw representation.

Signature

declare const RequestTransform: SchemaTransformation.Transformation<Request.Any, any, never, never>

Source

Since v4.0.0

type IDs

TypeId

Type identifier used to mark runtime cluster envelope values.

Signature

declare const TypeId: "~effect/cluster/Envelope"

Source

Since v4.0.0

utils

Envelope (namespace)

Helper types associated with cluster envelopes.

Source

Since v4.0.0

Any (type alias)

Envelope type for any RPC protocol.

Signature

type Any = Envelope<any>

Source

Since v4.0.0

Request (namespace)

Helper types associated with request envelopes.

Source

Since v4.0.0

Any (type alias)

Request envelope type for any RPC protocol.

Signature

type Any = Request<any>

Source

Since v4.0.0