RpcMessage
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
Signature
declare const constEof: Eof;Represents the reusable Ping message value.
Signature
declare const constPing: Ping;Represents the reusable Pong message value.
Signature
declare const constPong: Pong;Constructors
Converts a bigint or string request id into the branded RequestId type.
Signature
declare const RequestId: (id: string | number) => RequestId;ResponseDefectEncoded
Creates a transport-encoded defect response by encoding the input with Schema.Defect().
Signature
declare const ResponseDefectEncoded: (input: unknown) => ResponseDefectEncoded;ResponseExitDieEncoded
Creates an encoded terminal response for a request whose exit is a defect encoded with Schema.Defect().
Signature
declare function ResponseExitDieEncoded(options: {
readonly defect: unknown;
readonly requestId: RequestId;
}): ResponseExitEncoded;Guards
isTerminalResponse
Checks if the response type is terminal.
Signature
declare function isTerminalResponse(response: FromServerEncoded): boolean;Models
A decoded acknowledgement for a streamed RPC response chunk.
Signature
interface Ack {
readonly _tag: "Ack";
readonly requestId: RequestId;
}AckEncoded interface
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;
}ClientProtocolError interface
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";
}ExitEncoded type
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 | undefined;
}
>;
};FromClient type
Decoded messages that can be sent from an RPC client to a server.
Signature
type FromClient<A extends Rpc.Any> = Request<A> | Ack | Interrupt | Eof;FromClientEncoded type
Transport-encoded messages that can be sent from an RPC client to a server.
Signature
type FromClientEncoded = RequestEncoded | AckEncoded | InterruptEncoded | Ping | Eof;FromServer type
Decoded messages that can be sent from an RPC server to a client.
Signature
type FromServer<A extends Rpc.Any> =
| ResponseChunk<A>
| ResponseExit<A>
| ResponseDefect
| ClientEnd;FromServerEncoded type
Transport-encoded messages that can be sent from an RPC server to a client.
Signature
type FromServerEncoded =
| ResponseChunkEncoded
| ResponseExitEncoded
| ResponseDefectEncoded
| Pong
| ClientProtocolError;A 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;
}InterruptEncoded interface
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;
}RequestEncoded interface
The transport-encoded RPC request envelope, including the string request id, RPC tag, encoded payload, headers, and optional trace context.
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">;ResponseChunk interface
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>];
}ResponseChunkEncoded interface
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];
}ResponseDefect interface
The decoded server defect message for a client connection.
Signature
interface ResponseDefect {
readonly _tag: "Defect";
readonly clientId: number;
readonly defect: unknown;
}ResponseDefectEncoded interface
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;
}ResponseExit interface
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;
}ResponseExitEncoded interface
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;
}ResponseId type
A branded numeric identifier for server responses.
Signature
type ResponseId = Branded<number, ResponseIdTypeId>;Type IDs
ResponseIdTypeId
The brand identifier used by the ResponseId type.
Signature
declare const ResponseIdTypeId: "~effect//rpc/RpcServer/ResponseId";ResponseIdTypeId type
The literal type of the ResponseId brand identifier.
Signature
type ResponseIdTypeId = typeof ResponseIdTypeId;
Represents the reusable
Eofmessage value.