Envelope
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.
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 function makeRequest<Rpc extends Any>(options: { readonly address: EntityAddress; readonly headers: Headers; readonly payload: Payload<Rpc>; readonly requestId: Snowflake; readonly sampled?: boolean; readonly spanId?: string; readonly tag: Tag<Rpc>; readonly traceId?: string;}): Request<Rpc>primaryKeyByAddress
Builds a storage primary-key string from an entity address, RPC tag, and payload primary-key ID.
Signature
declare function primaryKeyByAddress(options: { readonly address: EntityAddress; readonly id: string; readonly tag: string;}): stringGetters
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 function primaryKey<R extends Any>(envelope: Envelope<R>): string | nullGuards
isEnvelope
Returns true when the supplied value is a runtime cluster envelope.
Details
The check is based on the envelope type identifier.
Signature
declare function isEnvelope(u: unknown): u is Envelope<any>Models
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 extends { readonly _tag: "AckChunk"; readonly address: EntityAddress; readonly id: bigint & Brand<"~effect/cluster/Snowflake">; readonly replyId: bigint & Brand<"~effect/cluster/Snowflake">; readonly requestId: bigint & Brand<"~effect/cluster/Snowflake">;} { constructor(...args: [props: { readonly _tag?: "AckChunk"; readonly address: EntityAddress; readonly id: bigint & Brand<"~effect/cluster/Snowflake">; readonly replyId: bigint & Brand<"~effect/cluster/Snowflake">; readonly requestId: bigint & Brand<"~effect/cluster/Snowflake">; }, options?: MakeOptions]); readonly "~effect/cluster/Envelope": "~effect/cluster/Envelope"; withRequestId(requestId: Snowflake): AckChunk;}AckChunkEncoded interface
Serialized JSON shape of an AckChunk envelope.
Signature
interface AckChunkEncoded { readonly _tag: "AckChunk"; readonly address: { readonly entityId: string; readonly entityType: string; readonly shardId: { readonly group: string; readonly id: number; }; }; readonly id: string; readonly replyId: string; readonly requestId: string;}JSON-serializable form of a cluster envelope.
Signature
type Encoded = PartialRequestEncoded | AckChunkEncoded | InterruptEncodedUnion 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 extends Rpc.Any> = Request<R> | AckChunk | InterruptRepresents an envelope used to interrupt an in-flight entity request.
Signature
declare class Interrupt extends { readonly _tag: "Interrupt"; readonly address: EntityAddress; readonly id: bigint & Brand<"~effect/cluster/Snowflake">; readonly requestId: bigint & Brand<"~effect/cluster/Snowflake">;} { constructor(...args: [props: { readonly _tag?: "Interrupt"; readonly address: EntityAddress; readonly id: bigint & Brand<"~effect/cluster/Snowflake">; readonly requestId: bigint & Brand<"~effect/cluster/Snowflake">; }, options?: MakeOptions]); readonly "~effect/cluster/Envelope": "~effect/cluster/Envelope"; withRequestId(requestId: Snowflake): Interrupt;}InterruptEncoded interface
Serialized JSON shape of an Interrupt envelope.
Signature
interface InterruptEncoded { readonly _tag: "Interrupt"; readonly address: { readonly entityId: string; readonly entityType: string; readonly shardId: { readonly group: string; readonly id: number; }; }; readonly id: string; readonly requestId: string;}PartialRequest
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 extends { readonly _tag: "Request"; readonly address: EntityAddress; readonly headers: Headers; readonly payload: any; readonly requestId: bigint & Brand<"~effect/cluster/Snowflake">; readonly sampled?: boolean; readonly spanId?: string; readonly tag: string; readonly traceId?: string;} { constructor(_: never);}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
interface PartialRequestEncoded { readonly _tag: "Request"; readonly address: { readonly entityId: string; readonly entityType: string; readonly shardId: { readonly group: string; readonly id: number; }; }; readonly headers: ReadonlyRecord<string, string>; readonly payload: unknown; readonly requestId: string; readonly sampled?: boolean; readonly spanId?: string; readonly tag: string; readonly traceId?: string;}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
interface Request<in out Rpc extends Rpc.Any> { readonly _tag: "Request"; readonly "~effect/cluster/Envelope": "~effect/cluster/Envelope"; readonly address: EntityAddress; readonly headers: Headers; readonly payload: Payload<Rpc>; readonly requestId: Snowflake; readonly sampled?: boolean; readonly spanId?: string; readonly tag: Tag<Rpc>; readonly traceId?: string;}Other
Schemas
OpaqueHole
Schema for a value that has already been encoded by the transport's hole codec.
Details
Cluster payloads are encoded twice: the entity payload is encoded with the
entity RPC schema, and the result is carried opaquely inside the runner
envelope. This schema names that hole so the outer runner encode leaves it
alone. It is the identity under Schema.toCodecJson, so JSON, NDJSON, and
MessagePack transports stay wire-compatible. A binary codec compiles it as a
bytes leaf.
Signature
declare const OpaqueHole: Schema.declare<any>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]>Decoded value type produced by the Partial envelope schema.
Signature
type Partial = typeof Partial.TypePartialArray
Schema for mutable arrays of JSON-encoded partial cluster envelopes.
Signature
declare const PartialArray: Schema.mutable<Schema.$Array<Schema.Codec<AckChunk | Interrupt | PartialRequest, Encoded>>>PartialJson
JSON codec for partial cluster envelopes.
Signature
declare const PartialJson: Schema.Codec<AckChunk | Interrupt | PartialRequest, Encoded>Serialization
Schema for runtime cluster envelopes recognized by their type identifier.
Signature
declare const Envelope: declare<Envelope<any>, Envelope<any>>Schema for runtime request envelopes.
Signature
declare const Request: declare<Any, Any>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>