Skip to content
Effect V4 Docs

RpcMessage.ts

RpcMessage.ts overview

Section titled “RpcMessage.ts overview”

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.

Since v4.0.0

Exports Grouped by Category

Section titled “Exports Grouped by Category”

guards

Section titled “guards”

isTerminalResponse

Section titled “isTerminalResponse”

Checks if the response type is terminal.

Signature

declare const isTerminalResponse: (response: FromServerEncoded) => boolean

Source

Since v4.0.0

request

Section titled “request”

Ack (interface)

Section titled “Ack (interface)”

A decoded acknowledgement for a streamed RPC response chunk.

Signature

export interface Ack {
  readonly _tag: "Ack"
  readonly requestId: RequestId
}

Source

Since v4.0.0

AckEncoded (interface)

Section titled “AckEncoded (interface)”

The transport-encoded acknowledgement for a streamed RPC response chunk.

Signature

export interface AckEncoded {
  readonly _tag: "Ack"
  readonly requestId: string
}

Source

Since v4.0.0

Eof (interface)

Section titled “Eof (interface)”

A client-to-server message indicating that the client has finished sending input for the current connection or request batch.

Signature

export interface Eof {
  readonly _tag: "Eof"
}

Source

Since v4.0.0

FromClient (type alias)

Section titled “FromClient (type alias)”

Decoded messages that can be sent from an RPC client to a server.

Signature

type FromClient<A> = Request<A> | Ack | Interrupt | Eof

Source

Since v4.0.0

FromClientEncoded (type alias)

Section titled “FromClientEncoded (type alias)”

Transport-encoded messages that can be sent from an RPC client to a server.

Signature

type FromClientEncoded = RequestEncoded | AckEncoded | InterruptEncoded | Ping | Eof

Source

Since v4.0.0

Interrupt (interface)

Section titled “Interrupt (interface)”

A decoded request to interrupt an in-flight RPC, carrying the request id and interrupting fiber ids.

Signature

export interface Interrupt {
  readonly _tag: "Interrupt"
  readonly requestId: RequestId
  readonly interruptors: ReadonlyArray<number>
}

Source

Since v4.0.0

InterruptEncoded (interface)

Section titled “InterruptEncoded (interface)”

The transport-encoded request to interrupt an in-flight RPC.

Signature

export interface InterruptEncoded {
  readonly _tag: "Interrupt"
  readonly requestId: string
}

Source

Since v4.0.0

Ping (interface)

Section titled “Ping (interface)”

A client-to-server keepalive message used by protocols that monitor connection liveness.

Signature

export interface Ping {
  readonly _tag: "Ping"
}

Source

Since v4.0.0

Request (interface)

Section titled “Request (interface)”

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

export interface Request<A extends Rpc.Any> {
  readonly _tag: "Request"
  readonly id: RequestId
  readonly tag: Rpc.Tag<A>
  readonly payload: Rpc.Payload<A>
  readonly headers: Headers
  readonly traceId?: string
  readonly spanId?: string
  readonly sampled?: boolean
}

Source

Since v4.0.0

RequestEncoded (interface)

Section titled “RequestEncoded (interface)”

The transport-encoded RPC request envelope, including the string request id, RPC tag, encoded payload, headers, and optional trace context.

Signature

export interface RequestEncoded {
  readonly _tag: "Request"
  readonly id: string
  readonly tag: string
  readonly payload: unknown
  readonly headers: ReadonlyArray<[string, string]>
  readonly traceId?: string
  readonly spanId?: string
  readonly sampled?: boolean
}

Source

Since v4.0.0

RequestId

Section titled “RequestId”

Converts a bigint or string request id into the branded RequestId type.

Signature

declare const RequestId: (id: bigint | string) => RequestId

Source

Since v4.0.0

RequestId (type alias)

Section titled “RequestId (type alias)”

A branded request identifier used to correlate RPC requests, responses, chunks, acknowledgements, and interrupts.

Signature

type RequestId = Branded<bigint, "~effect/rpc/RpcMessage/RequestId">

Source

Since v4.0.0

constEof

Section titled “constEof”

Represents the reusable Eof message value.

Signature

declare const constEof: Eof

Source

Since v4.0.0

constPing

Section titled “constPing”

Represents the reusable Ping message value.

Signature

declare const constPing: Ping

Source

Since v4.0.0

response

Section titled “response”

ClientEnd (interface)

Section titled “ClientEnd (interface)”

A server message indicating that the client connection has ended.

Signature

export interface ClientEnd {
  readonly _tag: "ClientEnd"
  readonly clientId: number
}

Source

Since v4.0.0

ClientProtocolError (interface)

Section titled “ClientProtocolError (interface)”

A server-to-client protocol message reporting a client protocol error to all affected in-flight requests.

Signature

export interface ClientProtocolError {
  readonly _tag: "ClientProtocolError"
  readonly error: RpcClientError
}

Source

Since v4.0.0

ExitEncoded (type alias)

Section titled “ExitEncoded (type alias)”

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

Source

Since v4.0.0

FromServer (type alias)

Section titled “FromServer (type alias)”

Decoded messages that can be sent from an RPC server to a client.

Signature

type FromServer<A> = ResponseChunk<A> | ResponseExit<A> | ResponseDefect | ClientEnd

Source

Since v4.0.0

FromServerEncoded (type alias)

Section titled “FromServerEncoded (type alias)”

Transport-encoded messages that can be sent from an RPC server to a client.

Signature

type FromServerEncoded = ResponseChunkEncoded | ResponseExitEncoded | ResponseDefectEncoded | Pong | ClientProtocolError

Source

Since v4.0.0

Pong (interface)

Section titled “Pong (interface)”

A server-to-client keepalive response to a Ping message.

Signature

export interface Pong {
  readonly _tag: "Pong"
}

Source

Since v4.0.0

ResponseChunk (interface)

Section titled “ResponseChunk (interface)”

The decoded response message containing a non-empty batch of stream chunk values for a specific client and request.

Signature

export interface ResponseChunk<A extends Rpc.Any> {
  readonly _tag: "Chunk"
  readonly clientId: number
  readonly requestId: RequestId
  readonly values: NonEmptyReadonlyArray<Rpc.SuccessChunk<A>>
}

Source

Since v4.0.0

ResponseChunkEncoded (interface)

Section titled “ResponseChunkEncoded (interface)”

The transport-encoded response message containing a non-empty batch of stream chunk values for a request.

Signature

export interface ResponseChunkEncoded {
  readonly _tag: "Chunk"
  readonly requestId: string
  readonly values: NonEmptyReadonlyArray<unknown>
}

Source

Since v4.0.0

ResponseDefect (interface)

Section titled “ResponseDefect (interface)”

The decoded server defect message for a client connection.

Signature

export interface ResponseDefect {
  readonly _tag: "Defect"
  readonly clientId: number
  readonly defect: unknown
}

Source

Since v4.0.0

ResponseDefectEncoded

Section titled “ResponseDefectEncoded”

Creates a transport-encoded defect response by encoding the input with Schema.Defect().

Signature

declare const ResponseDefectEncoded: (input: unknown) => ResponseDefectEncoded

Source

Since v4.0.0

ResponseDefectEncoded (interface)

Section titled “ResponseDefectEncoded (interface)”

The transport-encoded server defect message used for protocol-level defects that affect the client connection.

Signature

export interface ResponseDefectEncoded {
  readonly _tag: "Defect"
  readonly defect: unknown
}

Source

Since v4.0.0

ResponseExit (interface)

Section titled “ResponseExit (interface)”

The decoded terminal response for a request, carrying the typed Rpc.Exit for the RPC.

Signature

export interface ResponseExit<A extends Rpc.Any> {
  readonly _tag: "Exit"
  readonly clientId: number
  readonly requestId: RequestId
  readonly exit: Rpc.Exit<A>
}

Source

Since v4.0.0

ResponseExitDieEncoded

Section titled “ResponseExitDieEncoded”

Creates an encoded terminal response for a request whose exit is a defect encoded with Schema.Defect().

Signature

declare const ResponseExitDieEncoded: (options: {
  readonly requestId: RequestId
  readonly defect: unknown
}) => ResponseExitEncoded

Source

Since v4.0.0

ResponseExitEncoded (interface)

Section titled “ResponseExitEncoded (interface)”

The transport-encoded terminal response for a request, carrying the encoded Exit.

Signature

export interface ResponseExitEncoded {
  readonly _tag: "Exit"
  readonly requestId: string
  readonly exit: ExitEncoded<unknown, unknown>
}

Source

Since v4.0.0

ResponseId (type alias)

Section titled “ResponseId (type alias)”

A branded numeric identifier for server responses.

Signature

type ResponseId = Branded<number, ResponseIdTypeId>

Source

Since v4.0.0

constPong

Section titled “constPong”

Represents the reusable Pong message value.

Signature

declare const constPong: Pong

Source

Since v4.0.0

type IDs

Section titled “type IDs”

ResponseIdTypeId

Section titled “ResponseIdTypeId”

The brand identifier used by the ResponseId type.

Signature

declare const ResponseIdTypeId: "~effect//rpc/RpcServer/ResponseId"

Source

Since v4.0.0

ResponseIdTypeId (type alias)

Section titled “ResponseIdTypeId (type alias)”

The literal type of the ResponseId brand identifier.

Signature

type ResponseIdTypeId = typeof ResponseIdTypeId

Source

Since v4.0.0