RpcMessage unstable
Message envelopes shared by unstable RPC clients, servers, serializers, and transports.
RpcMessage is the protocol vocabulary below RpcClient and RpcServer.
It defines decoded messages for in-process channels and encoded messages for
transport boundaries, so custom protocols can move the same request,
streaming, acknowledgement, interrupt, keepalive, and defect signals as the
built-in HTTP, socket, worker, and test transports.
Constants
Represents the reusable Eof message value.
Signature
declare const constEof: EofRepresents the reusable Ping message value.
Signature
declare const constPing: PingRepresents the reusable Pong message value.
Signature
declare const constPong: PongConstructors
Converts a bigint or string request id into the branded RequestId type.
Signature
declare const RequestId: (id: string | number) => RequestIdResponseDefectEncoded
unstableCreates a transport-encoded defect response around an already-encoded defect.
Details
Encode the defect with protocol.codecFor(Schema.Defect()) before wrapping
it, because the codec that fills the defect hole belongs to the protocol.
Signature
declare const ResponseDefectEncoded: (encodedDefect: unknown) => ResponseDefectEncodedResponseExitDieEncoded
unstableCreates an encoded terminal response for a request whose exit is a defect.
Details
The defect must already be encoded, because the codec that fills the defect
hole belongs to the protocol. Encode it with
protocol.codecFor(Schema.Defect()) first.
This constructor produces the structured exit used by JSON-compatible
protocols. Serializations whose codecFor returns bytes must encode the
complete RPC exit before placing it in the response envelope instead.
Signature
declare function ResponseExitDieEncoded(options: { readonly encodedDefect: unknown; readonly requestId: RequestId;}): ResponseExitEncodedGuards
isTerminalResponse
unstableChecks if the response type is terminal.
Signature
declare function isTerminalResponse(response: FromServerEncoded): booleanModels
A decoded acknowledgement for a streamed RPC response chunk.
Signature
interface Ack { readonly _tag: "Ack"; readonly requestId: RequestId;}The transport-encoded acknowledgement for a streamed RPC response chunk.
Signature
interface AckEncoded { readonly _tag: "Ack"; readonly requestId: string | number;}A server message indicating that the client connection has ended.
Signature
interface ClientEnd { readonly _tag: "ClientEnd"; readonly clientId: number;}A server-to-client protocol message reporting a client protocol error to all affected in-flight requests.
Signature
interface ClientProtocolError { readonly _tag: "ClientProtocolError"; readonly error: RpcClientError;}A client-to-server message indicating that the client has finished sending input for the current connection or request batch.
Signature
interface Eof { readonly _tag: "Eof";}The transport representation of an RPC Exit, encoding success values or a
failure cause made of failures, defects, and interrupts.
Signature
type ExitEncoded<A, E> = { readonly _tag: "Success"; readonly value: A;} | { readonly _tag: "Failure"; readonly cause: ReadonlyArray<{ readonly _tag: "Fail"; readonly error: E; } | { readonly _tag: "Die"; readonly defect: unknown; } | { readonly _tag: "Interrupt"; readonly fiberId: number | null | undefined; }>;}Decoded messages that can be sent from an RPC client to a server.
Signature
type FromClient<A extends Rpc.Any> = Request<A> | Ack | Interrupt | EofTransport-encoded messages that can be sent from an RPC client to a server.
Signature
type FromClientEncoded = RequestEncoded | AckEncoded | InterruptEncoded | Ping | EofDecoded messages that can be sent from an RPC server to a client.
Signature
type FromServer<A extends Rpc.Any> = ResponseChunk<A> | ResponseExit<A> | ResponseDefect | ClientEndTransport-encoded messages that can be sent from an RPC server to a client.
Signature
type FromServerEncoded = ResponseChunkEncoded | ResponseExitEncoded | ResponseDefectEncoded | Pong | ClientProtocolError | RequestEncodedA decoded request to interrupt an in-flight RPC, carrying the request id and interrupting fiber ids.
Signature
interface Interrupt { readonly _tag: "Interrupt"; readonly interruptors: readonly Array<number>; readonly requestId: RequestId;}The transport-encoded request to interrupt an in-flight RPC.
Signature
interface InterruptEncoded { readonly _tag: "Interrupt"; readonly requestId: string | number;}A client-to-server keepalive message used by protocols that monitor connection liveness.
Signature
interface Ping { readonly _tag: "Ping";}A server-to-client keepalive response to a Ping message.
Signature
interface Pong { readonly _tag: "Pong";}The decoded RPC request envelope for an RPC union, carrying a branded request id, typed RPC tag, decoded payload, headers, and optional trace context.
Signature
interface Request<A extends Rpc.Any> { readonly _tag: "Request"; readonly headers: Headers; readonly id: RequestId; readonly payload: Payload<A>; readonly sampled?: boolean; readonly spanId?: string; readonly tag: Tag<A>; readonly traceId?: string;}The transport-encoded RPC request envelope, including the string request id, RPC tag, encoded payload, headers, and optional trace context.
Details
Requests flow in both directions: servers use them for server-originated
requests and, with isNotification set, for server notifications.
Signature
interface RequestEncoded { readonly _tag: "Request"; readonly headers: readonly Array<[string, string]>; readonly id: string | number; readonly isNotification?: true; readonly payload: unknown; readonly sampled?: boolean; readonly spanId?: string; readonly tag: string; readonly traceId?: string;}A branded request identifier used to correlate RPC requests, responses, chunks, acknowledgements, and interrupts.
Signature
type RequestId = Branded<string | number, "~effect/rpc/RpcMessage/RequestId">The decoded response message containing a non-empty batch of stream chunk values for a specific client and request.
Signature
interface ResponseChunk<A extends Rpc.Any> { readonly _tag: "Chunk"; readonly clientId: number; readonly requestId: RequestId; readonly values: readonly [SuccessChunk<A>, SuccessChunk<A>];}The transport-encoded response message containing a non-empty batch of stream chunk values for a request.
Signature
interface ResponseChunkEncoded { readonly _tag: "Chunk"; readonly requestId: string | number; readonly values: readonly [unknown, unknown];}The decoded server defect message for a client connection.
Signature
interface ResponseDefect { readonly _tag: "Defect"; readonly clientId: number; readonly defect: unknown;}The transport-encoded server defect message used for protocol-level defects that affect the client connection.
Signature
interface ResponseDefectEncoded { readonly _tag: "Defect"; readonly defect: unknown;}The decoded terminal response for a request, carrying the typed Rpc.Exit
for the RPC.
Signature
interface ResponseExit<A extends Rpc.Any> { readonly _tag: "Exit"; readonly clientId: number; readonly exit: Exit<A>; readonly requestId: RequestId;}The transport-encoded terminal response for a request, carrying the encoded
Exit.
Signature
interface ResponseExitEncoded { readonly _tag: "Exit"; readonly exit: ExitEncoded<unknown, unknown>; readonly requestId: string | number;}A branded numeric identifier for server responses.
Signature
type ResponseId = Branded<number, ResponseIdTypeId>Schemas
EncodedSchema
unstableSchema for every transport-encoded RPC envelope that crosses the wire.
Binary serializers use it only after each schema-dependent hole has been
encoded as bytes. ClientProtocolError is excluded because clients create
it locally rather than receiving it from a server.
Signature
declare const EncodedSchema: Union<readonly [Struct<{ readonly _tag: tag<"Request">; readonly headers: $Array<Tuple<readonly [String, String]>>; readonly id: Union<readonly [String, Number]>; readonly isNotification: optional<Literal<true>>; readonly payload: Uint8Array; readonly sampled: optional<Boolean>; readonly spanId: optional<String>; readonly tag: String; readonly traceId: optional<String>;}>, Struct<{ readonly _tag: tag<"Ack">; readonly requestId: Union<readonly [String, Number]>;}>, Struct<{ readonly _tag: tag<"Interrupt">; readonly requestId: Union<readonly [String, Number]>;}>, Struct<{ readonly _tag: tag<"Ping">;}>, Struct<{ readonly _tag: tag<"Eof">;}>, Struct<{ readonly _tag: tag<"Chunk">; readonly requestId: Union<readonly [String, Number]>; readonly values: Uint8Array;}>, Struct<{ readonly _tag: tag<"Exit">; readonly exit: Uint8Array; readonly requestId: Union<readonly [String, Number]>;}>, Struct<{ readonly _tag: tag<"Defect">; readonly defect: Uint8Array;}>, Struct<{ readonly _tag: tag<"Pong">;}>]>Type IDs
ResponseIdTypeId
unstableThe brand identifier used by the ResponseId type.
Signature
declare const ResponseIdTypeId: "~effect/rpc/RpcMessage/ResponseId"The literal type of the ResponseId brand identifier.
Signature
type ResponseIdTypeId = typeof ResponseIdTypeId