RpcClient unstable

Runs typed RPC calls from the client side.

This module turns RPC definitions from an RpcGroup into callable client methods. Each call encodes its payload, sends a message through the active Protocol, decodes exits or stream chunks from the server, and routes the response back to the waiting Effect, Stream, or queue. It also defines the protocol service and includes protocol layers for HTTP, sockets, and workers.

15 exports Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

Creates a schema-aware RPC client for a group using the current client Protocol, encoding requests and decoding server responses.

Signature

declare const make: <Rpcs extends Rpc.Any, Flatten extends boolean = false>(group: RpcGroup.RpcGroup<Rpcs>, options?: {
  readonly disableTracing?: boolean;
  readonly flatten?: Flatten;
  readonly generateRequestId?: () => RequestId;
  readonly spanAttributes?: Record<string, unknown>;
  readonly spanPrefix?: string;
}) => Effect.Effect<Flatten extends true ? RpcClient.Flat<Rpcs, RpcClientError> : RpcClient<Rpcs, RpcClientError>, never, Protocol | Rpc.MiddlewareClient<Rpcs> | Scope.Scope>

makeNoSerialization

unstable

Since v4.0.0

Creates an RPC client for an already-decoded message channel, returning the client API together with a write function for delivering server messages back to the client.

Signature

declare const makeNoSerialization: <Rpcs extends Rpc.Any, E, Flatten extends boolean = false>(group: RpcGroup.RpcGroup<Rpcs>, options: {
  readonly disableTracing?: boolean;
  readonly flatten?: Flatten;
  readonly generateRequestId?: () => RequestId;
  readonly onFromClient: (options: {
    readonly context: Context.Context<never>;
    readonly message: FromClient<Rpcs>;
  }) => Effect.Effect<void, E>;
  readonly spanAttributes?: Record<string, unknown>;
  readonly spanPrefix?: string;
  readonly supportsAck?: boolean;
}) => Effect.Effect<{
  readonly client: Flatten extends true ? RpcClient.Flat<Rpcs, E> : RpcClient<Rpcs, E>;
  readonly write: (message: FromServer<Rpcs>) => Effect.Effect<void>;
}, never, Scope.Scope | Rpc.MiddlewareClient<Rpcs>>

Headers

withHeaders

unstable

Since v4.0.0

Runs an effect with additional RPC client headers, merging them with the current CurrentHeaders value for outgoing requests.

Signature

declare const withHeaders: {
  (headers: Input): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
  <A, E, R>(effect: Effect<A, E, R>, headers: Input): Effect<A, E, R>;
}

Layers

layerProtocolHttp

unstable

Since v4.0.0

Provides a client Protocol backed by HttpClient, targeting the configured URL and optionally transforming the client before use.

Details

Set batch to send concurrent requests from the same client in a single HTTP request. The first request for a client opens a batch. Requests from the same client made before window elapses join it, and the batch is sent once the window elapses or it reaches maxSize requests, whichever comes first.

Signature

declare function layerProtocolHttp(options: {
  readonly batch?: {
    readonly maxSize?: number;
    readonly window: Input;
  };
  readonly transformClient?: <E, R>(client: With<E, R>) => With<E, R>;
  readonly url: string;
}): Layer<Protocol, never, HttpClient | RpcSerialization>

layerProtocolSocket

unstable

Since v4.0.0

Provides a client Protocol backed by the current Socket and RpcSerialization services.

Details

pingInterval defaults to 5 seconds. pingTimeout defaults to the interval and measures time since the last decoded server frame, not the last pong. The timeout is checked on each ping tick; any decoded frame counts as liveness. retryPolicy configures retries after socket errors.

Signature

declare function layerProtocolSocket(options?: {
  readonly onPingTimeout?: Effect<void, never, never>;
  readonly onTransientError?: (error: RpcClientError) => Effect<void>;
  readonly pingInterval?: Input;
  readonly pingTimeout?: Input;
  readonly retryPolicy?: Schedule<any, SocketError, never, never>;
  readonly retryTransientErrors?: boolean;
}): Layer<Protocol, never, RpcSerialization | Socket>

layerProtocolWorker

unstable

Since v4.0.0

Provides a client Protocol backed by a worker pool using the current worker platform and spawner services.

Signature

declare const layerProtocolWorker: (options: {
  readonly concurrency?: number;
  readonly size: number;
  readonly targetUtilization?: number;
} | {
  readonly concurrency?: number;
  readonly maxSize: number;
  readonly minSize: number;
  readonly targetUtilization?: number;
  readonly timeToLive: Duration.Input;
}) => Layer.Layer<Protocol, WorkerError, Worker.WorkerPlatform | Worker.Spawner>

Other

RpcClient

unstable

Since v4.0.0

Type-level helpers for deriving RPC client call signatures from RPC definitions.

Protocols

makeProtocolHttp

unstable

Since v4.0.0

Creates a client Protocol that sends RPC requests through the supplied HttpClient and decodes responses with the current RpcSerialization.

Details

Each request is sent as its own HTTP request unless batch is set. With batch, the first request for a client opens a batch. Requests from the same client made before window elapses join it, and the batch is sent once the window elapses or it reaches maxSize requests, whichever comes first.

Signature

declare function makeProtocolHttp(client: HttpClient, options?: {
  readonly batch?: {
    readonly maxSize?: number;
    readonly window: Input;
  };
}): Effect<{
  readonly codecFor: CodecFor;
  readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
  readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>;
  readonly supportsAck: boolean;
  readonly supportsTransferables: boolean;
}, never, RpcSerialization>

makeProtocolSocket

unstable

Since v4.0.0

Creates a client Protocol over the current Socket, using the current RpcSerialization, connection hooks, ping timeouts, and the configured retry policy.

Details

Signature

declare function makeProtocolSocket(options?: {
  readonly onPingTimeout?: Effect<void, never, never>;
  readonly onTransientError?: (error: RpcClientError) => Effect<void>;
  readonly pingInterval?: Input;
  readonly pingTimeout?: Input;
  readonly retryPolicy?: Schedule<any, SocketError, never, never>;
  readonly retryTransientErrors?: boolean;
}): Effect<{
  readonly codecFor: CodecFor;
  readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
  readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>;
  readonly supportsAck: boolean;
  readonly supportsTransferables: boolean;
}, never, Scope | RpcSerialization | Socket>

makeProtocolWorker

unstable

Since v4.0.0

Creates a client Protocol backed by a pool of workers, routing RPC requests to workers and supporting transferable values when the platform does.

Signature

declare function makeProtocolWorker(options: {
  readonly concurrency?: number;
  readonly size: number;
  readonly targetUtilization?: number;
} | {
  readonly concurrency?: number;
  readonly maxSize: number;
  readonly minSize: number;
  readonly targetUtilization?: number;
  readonly timeToLive: Input;
}): Effect<{
  readonly codecFor: CodecFor;
  readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
  readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>;
  readonly supportsAck: boolean;
  readonly supportsTransferables: boolean;
}, WorkerError, Scope | WorkerPlatform | Spawner>

Services

ConnectionHooks

unstable

Since v4.0.0

Represents optional client protocol hooks that run when a transport connects and disconnects.

When to use

Use to run setup or cleanup effects when an RPC client transport opens or closes.

Signature

declare class ConnectionHooks extends Shape<"effect/rpc/RpcClient/ConnectionHooks", {
  readonly onConnect: Effect<void>;
  readonly onDisconnect: Effect<void>;
}, this> {
  constructor(_: never);
}

CurrentHeaders

unstable

Since v4.0.0

Fiber reference containing headers that are merged into outgoing RPC client requests.

When to use

Use to set request headers that should be automatically merged into outgoing RPC client messages.

Signature

declare const CurrentHeaders: Reference<Headers>

Protocol

unstable

Since v4.0.0

Defines the service interface for an RPC client transport, responsible for running the receive loop and sending encoded client messages.

When to use

Use to provide the transport boundary for RPC clients over HTTP, WebSocket, workers, sockets, or custom protocols.

Details

A Request that send accepts stays pending until a reply names its id: an Exit, or a ClientProtocolError that lists it in requestIds. Until then the client keeps the request and the caller's context, unless the caller is interrupted, the client closes or the connection fails. A transport that only delivers requests, such as a message queue, writes a void Exit for a discard request once the request is delivered, and fails send with an RpcClientError for any other request.

Signature

declare class Protocol extends Shape<"effect/rpc/RpcClient/Protocol", {
  readonly codecFor: CodecFor;
  readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
  readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>;
  readonly supportsAck: boolean;
  readonly supportsTransferables: boolean;
}, this> {
  constructor(_: never);
  static make: <EX, RX>(f: (write: (clientId: number, response: FromServerEncoded) => Effect<void>, clientIds: ReadonlySet<number>) => Effect<Omit<{
    readonly codecFor: CodecFor;
    readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
    readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>;
    readonly supportsAck: boolean;
    readonly supportsTransferables: boolean;
  }, "run">, EX, RX>) => Effect<{
    readonly codecFor: CodecFor;
    readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
    readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>;
    readonly supportsAck: boolean;
    readonly supportsTransferables: boolean;
  }, EX, RX>;
}

Utility Types

FromGroup

type unstable

Since v4.0.0

Derives the object-shaped RPC client type for all RPCs contained in an RpcGroup.

Signature

type FromGroup<Group, E = never> = RpcClient<RpcGroup.Rpcs<Group>, E>

RpcClient

type unstable

Since v4.0.0

The object-shaped client generated from a union of RPC definitions, with one method per RPC tag.

Signature

type RpcClient<Rpcs extends Rpc.Any, E = never> = Struct.Simplify<RpcClient.From<Rpcs, E>>