Skip to content

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.

23 exports Added in v4.0.0 Source

Constructors

makeRequest

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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;
}): string;

Getters

primaryKey

Added in v4.0.0 Source

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 | null;

Guards

isEnvelope

Added in v4.0.0 Source

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

AckChunk

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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;
}

Encoded type

Added in v4.0.0 Source

JSON-serializable form of a cluster envelope.

Signature

type Encoded = PartialRequestEncoded | AckChunkEncoded | InterruptEncoded;

Envelope type

Added in v4.0.0 Source

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 extends Rpc.Any> = Request<R> | AckChunk | Interrupt;

Interrupt

Added in v4.0.0 Source

Represents 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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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;
}

Request interface

Added in v4.0.0 Source

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

Envelope

Added in v4.0.0 Source

Helper types associated with cluster envelopes.

Request

Added in v4.0.0 Source

Helper types associated with request envelopes.

Schemas

Partial

Added in v4.0.0 Source

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]
>;

Partial type

Added in v4.0.0 Source

Decoded value type produced by the Partial envelope schema.

Signature

type Partial = typeof Partial.Type;

PartialArray

Added in v4.0.0 Source

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

Added in v4.0.0 Source

JSON codec for partial cluster envelopes.

Signature

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

Serialization

Envelope

Added in v4.0.0 Source

Schema for runtime cluster envelopes recognized by their type identifier.

Signature

declare const Envelope: declare<Envelope<any>, Envelope<any>>;

Request

Added in v4.0.0 Source

Schema for runtime request envelopes.

Signature

declare const Request: declare<Any, Any>;

RequestTransform

Added in v4.0.0 Source

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

Signature

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

Type IDs

TypeId

Added in v4.0.0 Source

Type identifier used to mark runtime cluster envelope values.

Signature

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