effect-rpc-client
/effect-rpc-client
Wywołuje usługi RPC w Effect z klienta: warstwy transportu i serializacji, nagłówki, strumienie, przerwania i ponowne połączenia.
- Autor
- mpsuesser ↗
- Repozytorium
- opencode-effect-enforcer ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 02.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 1
- Adresy URL w SKILL.md
- 3
Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
Co robi i kiedy
Wywołuje usługi RPC w Effect z klienta: warstwy transportu i serializacji, nagłówki, strumienie, przerwania i ponowne połączenia.
Oryginalny opis (EN)
Consume typed RPC services with Effect's RpcClient — protocol layers (HTTP, WebSocket, TCP, worker, in-memory), RpcSerialization codecs, per-call and ambient headers, streaming calls, interruption, reconnection, and RpcClientError handling. Use when calling an RpcGroup from a client, wiring a client transport + serialization stack, debugging RPC transport failures or reconnects, or testing RPC consumers with RpcTest.
Jak działa
- Effect Source Reference
- Core Model
- 1. Creating a Client — RpcClient.make
- 2. Calling RPCs — Per-Call Options and Error Channels
- 3. Headers
- 4. Protocol Layers — Picking a Transport
- 5. Serialization — Pairing Codecs with Transports
- 6. Consuming Streaming RPCs
- 7. Interruption and Abort Propagation
- 8. Error Handling — the RpcClientError Taxonomy
Podgląd SKILL.md
---
name: effect-rpc-client
description: Consume typed RPC services with Effect's RpcClient — protocol layers (HTTP, WebSocket, TCP, worker, in-memory), RpcSerialization codecs, per-call and ambient headers, streaming calls, interruption, reconnection, and RpcClientError handling. Use when calling an RpcGroup from a client, wiring a client transport + serialization stack, debugging RPC transport failures or reconnects, or testing RPC consumers with RpcTest.
---
You are an Effect TypeScript expert specializing in consuming RPC services with `RpcClient` from `effect/rpc`.
This skill covers the client side only: building clients, transports, serialization, headers, streaming consumption, interruption, errors, and testing. Defining `Rpc`/`RpcGroup` contracts is the `effect-rpc-api` skill; serving them is the `effect-rpc-server` skill; cluster entity clients are the `effect-rpc-cluster` skill.
## Effect Source Reference
The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read the `effect@4.1.0` tag for this skill; main may be newer. These APIs remain `@stability unstable` and may break in minor releases. Keep Effect-family packages on the same release.
Key files:
- `packages/effect/src/rpc/RpcClient.ts` — `make`, `makeNoSerialization`, the `Protocol` service, `layerProtocolHttp`/`layerProtocolSocket`/`layerProtocolWorker` (+ `makeProtocol*`), `CurrentHeaders`, `withHeaders`, `ConnectionHooks`
- `packages/effect/src/rpc/RpcClientError.ts` — `RpcClientError` and `RpcClientDefect`
- `packages/effect/src/rpc/RpcSerialization.ts` — JSON, NDJSON, JSON-RPC, SchemaBinary codecs, their layers, the `Parser` interface and `includesFraming`
- `packages/effect/src/rpc/RpcTest.ts` — `makeClient` in-process test client
- `packages/effect/src/rpc/RpcWorker.ts` — `InitialMessage`, `layerInitialMessage`, `initialMessage`
- `packages/effect/src/rpc/RpcMessage.ts` — wire vocabulary: `Request`, `Ack`, `Interrupt`, `Chunk`, `Exit`, `Defect`, `Ping`/`Pong`, `ClientProtocolError`, `RequestId`
- `packages/effect/src/socket/Socket.ts` — `Socket` service, `layerWebSocket`, `WebSocketConstructor`
- `packages/platform/node/test/RpcServer.test.ts` + `test/fixtures/rpc-e2e.ts` + `test/fixtures/rpc-schemas.ts` — the best end-to-end reference: every transport × serialization combination, headers, streams, interrupts, defects
- `packages/platform/browser/test/RpcWorker.test.ts` + `test/fixtures/rpc-worker.ts` — worker transport end to end
## Core Model
A client is assembled from three replaceable layers plus your shared `RpcGroup` definition:
```
RpcClient.make(group) typed methods, spans, request ids
requires: Protocol ← RpcClient.layerProtocolHttp / Socket / Worker
requires: RpcSerialization ← JSON / NDJSON / SchemaBinary / JSON-RPC layer
requires: transport service ← HttpClient | Socket.Socket | WorkerPlatform + Spawner
```
`RpcClient.make(group)` returns an `Effect` producing an object with one method per rpc tag. Each method encodes the payload with the rpc's schema, sends a `Request` envelope through the `Protocol`, and decodes the server's `Exit` (or stream `Chunk`s) back into a typed `Effect` or `Stream`:
```ts
// The generated client type — one method per tag
type RpcClient<Rpcs extends Rpc.Any, E = never> = {
readonly [Tag in Rpcs['_tag']]: (payload, options?) => Effect<Success, RpcError | E | MiddlewareErrors, R>;
// stream rpcs return Stream<A, E', R> instead (or Effect<Queue.Dequeue<...>> with asQueue)
};
```
`E` is the transport error — `RpcClientError` for every real transport (`RpcClient.make`), `never` for `RpcTest.makeClient`.
Imports used throughout this skill (all rpc modules ship from the `effect` package — there is no `@effect/rpc` in v4):
```ts
import { Cause, Context, Effect, Fiber, Layer, Queue, Schedule, Schema, Stream } from 'effect';
import {
Rpc,
RpcClient,
RpcGroup,
RpcMiddleware,
RpcSerialization,
RpcTest,
RpcWorker
} from 'effect/rpc';
import { RpcClientError } from 'effect/rpc/RpcClientError';
import { FetchHttpClient, Headers, HttpClient, HttpClientRequest } from 'effect/http';
import { Socket } from 'effect/socket';
// Platform transports:
import { NodeSocket, NodeWorker } from '@effect/platform-node';
import { BrowserWorker } from '@effect/platform-browser';
```
Note the `RpcClientError` import: the `effect/rpc` barrel exports `RpcClientError` as a *namespace*; import the class from the module path `effect/rpc/RpcClientError` (this is what the upstream tests do).
---
## 1. Creating a Client — `RpcClient.make`
```ts
const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>(
group: RpcGroup.RpcGroup<Rpcs>,
options?: {
readonly spanPrefix?: string; // absent: tag alone; explicit prefix: `${spanPrefix}.${tag}`
readonly spanAttributes?: Record<string, unknown>;
readonly generateRequestId?: () => RequestId; // default: shared module-level numeric counter
readonly disableTracing?: boolean; // default false
readonly flatten?: Flatten; // default false
}
) => Effect.Effect<
Flatten extends true ? RpcClient.RpcClient.Flat<Rpcs, RpcClientError> : RpcClient.RpcClient<Rpcs, RpcClientError>,
never,
RpcClient.Protocol | Rpc.MiddlewareClient<Rpcs> | Scope
>;
```
Three things to internalize about the requirements:
- **`Protocol`** — provide exactly one `layerProtocol*` (section 4).
- **`Rpc.MiddlewareClient<Rpcs>`** — if any rpc in the group has a middleware declared with `requiredForClient: true`, you must provide its `RpcMiddleware.layerClient(...)` or the `Effect.provide` will not compile.
- **`Scope`** — the client registers a finalizer that interrupts all in-flight requests on close and makes later calls interrupt immediately. Build it inside `Layer.effect` (which supplies the layer's scope) or `Effect.scoped`.
The canonical wrapping is a `Context.Service` so consumers resolve the client by name:
```ts
export class UsersClient extends Context.Service<
UsersClient,
RpcClient.RpcClient<RpcGroup.Rpcs<typeof UserRpcs>, RpcClientError>
>()('UsersClient') {
static readonly layer = Layer.effect(UsersClient)(RpcClient.make(UserRpcs)).pipe(
Layer.provide(AuthClient) // RpcMiddleware.layerClient for requiredForClient middleware
);
}
```
`RpcClient.FromGroup<typeof UserRpcs, RpcClientError>` is shorthand for the same client type.
### `flatten: true` — single-function client
The client becomes one function `(tag, payload, options?)` instead of a property-per-tag object. Useful for generic proxying (this is what `AtomRpc` uses internally). Union-valued tags infer payloads/results from the selected RPCs rather than `never`; retain tag/payload correlation in application dispatch:
```ts
const client = yield* RpcClient.make(UserRpcs, { flatten: true });
const user = yield* client('GetUser', { id: 'u1' });
```
### `generateRequestId`
Request ids correlate requests with responses on a shared connection. The default is a process-wide incrementing `number`. Override only when ids need application-specific generation. The function must return `RequestId`, a branded `string | number`; construct it with `RequestId(1)` or `RequestId('1')` from `effect/rpc/RpcMessage`. `bigint` is not accepted.
### Tracing
Unless `disableTracing: true`, every call runs in a client-kind span named after
the RPC tag alone, or `${spanPrefix}.${tag}` when a prefix is supplied. Defaults
include `rpc.system.name: 'effect_rpc'` and `rpc.method`; `spanAttributes` can
override them. The request envelope carries `traceId`/`spanId`/`sampled` so the
server can continue the trace when the transport supports propagation.
`Rpc.ParseOptions` annotations control payload/result/chunk/exit codecs on both
peers, including effectful decode concurrency (see `effect-rpc-api`).
---
## 2. Calling RPCs — Per-Call Options and Error Channels
Each generated method takes the rpc's payload, then an options bag whose shape differs for stream vs non-stream rpcs:
```ts
// Non-stream rpc
client.GetUser(
{ id: 'u1' },
{
headers: { 'x-tenant': 't1' }, // Headers.Input — per-call headers
context: Context.empty(), // Context<never> — rarely needed (cluster plumbing)
discard: true // waits for acknowledgement, discards result: see below
}
);
// Stream rpc
client.StreamUsers(
{ id: 'u1' },
{
headers: { 'x-tenant': 't1' },
context: Context.empty(),
asQueue: true, // return Effect<Queue.Dequeue<...>> instead of Stream
streamBufferSize: 16 // default 16 — client-side bounded buffer
}
);
```
A void-payload rpc is callable with no arguments: `client.Ping()`, `client.GetInterrupts()`. The payload parameter is `Rpc.PayloadConstructor<R>` — the payload schema's constructor input, so `Schema.Class` payloads accept plain field objects. Tags containing dots — from `group.prefix('nested.')` or cluster `EntityProxy` groups — need bracket access: `client['nested.test']()` (or use `flatten: true`).
### The full error channel
```
Rpc.Error<R> your declared rpc error (decoded)
| MiddlewareError wire errors added by server middleware (e.g. Unauthorized)
| MiddlewareClientError errors a client-side middleware can produce
| RpcClientError transport failure (section 8)
```
Server-side defects are *not* in the error channel — they arrive as `Cause.Die` in the failure cause. Inspect with `Effect.sandbox` / `Effect.catchCause`, e.g. `Cause.squash(cause)` after `Effect.sandbox` + `Effect.flip`.
The requirements channel of each call is the payload schema's `EncodingServices` plus the success/error schemas' `DecodingServices` (plus any middleware error schemas' `DecodingServices`) — `never` for plain schemas.
### `discard: true`
Sends the request and waits for the server acknowledgement: the method returns `Effect<void, RpcClientError | MiddlewareErrors>`. The rpc's *declared* error disappears from the channel, but transport and middleware errors remain. A pending client entry tracks the acknowledgement, while the server's result is discarded. Completion confirms acknowledgement, not handler completion. SchemaBinary peers must be upgraded together because the new discard field changes the envelope fingerprint.
---
## 3. Headers
Three layers of headers, merged in this order (later wins on conflict):
1. **Ambient** — the `RpcClient.CurrentHeaders` reference (default `Headers.empty`)
2. **Per-call** — the `headers` option on the method call
3. **Client middleware** — `RpcMiddleware.layerClient` can rewrite `request.headers` last, as the request passes through it
```ts
// Region-scoped ambient headers — merged into CurrentHeaders for the wrapped effect
yield* program.pipe(
RpcClient.withHeaders({ authorization: `Bearer ${token}`, 'x-tenant': 't1' })
);
// withHeaders is dual: data-first works too
RpcClient.withHeaders(program, { 'x-tenant': 't1' });
// CurrentHeaders is a Context.Reference<Headers.Headers> — set directly if needed
Effect.updateService(program, RpcClient.CurrentHeaders, Headers.merge(Headers.fromInput({ a: 'b' })));
```
**Header names are normalized to lowercase** by `Headers.fromInput`. If you send `{ userId: '123' }`, server middleware must read `headers.userid`. The upstream e2e fixture depends on exactly this.
### Client-side middleware (auth headers and friends)
For middleware declared with `requiredForClient: true`, the client will not compile without a `layerClient`:
```ts
export const AuthClient = RpcMiddleware.layerClient(AuthMiddleware, ({ next, request }) =>
next({
...request,
headers: Headers.set(request.headers, 'authorization', `Bearer ${getToken()}`)
}));
```
You must call `next(request)`; the middleware wraps the send, it does not replace it. Defining middleware services is covered by the effect-rpc-api skill.
---
## 4. Protocol Layers — Picking a Transport
Provide exactly one of these to satisfy `RpcClient.Protocol`:
| Layer | Requires | supportsAck | Notes |
|---|---|---|---|
| `RpcClient.layerProtocolHttp({ url, transformClient?, batch? })` | `RpcSerialization`, `HttpClient` | no | One POST per request unless batching is enabled. Framed serializations stream responses |
| `RpcClient.layerProtocolSocket({ retryPolicy?, pingInterval?, pingTimeout?, onPingTimeout?, retryTransientErrors?, onTransientError? })` | `RpcSerialization`, `Socket.Socket` | yes | Full duplex; configurable liveness and reconnects (section 9). Works for WebSocket and raw TCP |
| `RpcClient.layerProtocolWorker(poolOptions)` | `Worker.WorkerPlatform`, `Worker.Spawner` | yes | Pool of workers; supports transferables and `RpcWorker.InitialMessage`; the only protocol layer with an error channel — `WorkerError` (section 10) |
Each has a `makeProtocol*` Effect counterpart (`makeProtocolHttp(client, options?)`,
`makeProtocolSocket(options?)`, `makeProtocolWorker(options)`) for inline
composition. Both socket constructors expose the same liveness/retry options.
### HTTP
```ts
const ProtocolLive = RpcClient.layerProtocolHttp({
url: 'http://localhost:3000/rpc', // the full endpoint URL
// optional: rewrite the underlying HttpClient (retries, extra headers, url tweaks)
transformClient: HttpClient.mapRequest(HttpClientRequest.setHeader('x-api-key', key))
}).pipe(
Layer.provide(RpcSerialization.layerNdjson),
Layer.provide(FetchHttpClient.layer) // or NodeHttpClient.layerUndici etc.
);
```
`url` is prepended to an empty path, so it must be the complete endpoint. `transformClient` receives the client *after* the url is attached; its request transformations run before the prepend (the upstream test uses `url: ''` + `transformClient: HttpClient.mapRequest(HttpClientRequest.appendUrl('/rpc'))`).
An empty HTTP response body fails the call with `RpcClientDefect` (`'Received empty HTTP response from RPC server'`) rather than hanging.
Opt into per-client batching with `batch: { window: Duration.Input, maxSize? }`
on either HTTP constructor. Requests flush at the window or size boundary and
share one POST. The **client scope** owns a batch, not one caller: interruption
of a member must not abort unrelated requests in that POST. This is transport
batching, not automatic retry/idempotency of the application calls.
<!-- typecheck -->
```ts
import { RpcClient, RpcSerialization } from 'effect/rpc';
import { Layer } from 'effect';
import { FetchHttpClient } from 'effect/http';
const HttpProtocol = RpcClient.layerProtocolHttp({
url: 'https://example.com/rpc',
batch: { window: '5 millis', maxSize: 32 }
}).pipe(Layer.provide([RpcSerialization.layerNdjson, FetchHttpClient.layer]));
```
### WebSocket
```ts
// Node
const ProtocolLive = RpcClient.layerProtocolSocket().pipe(
Layer.provide(NodeSocket.layerWebSocket('ws://localhost:3000/rpc')),
Layer.provide(RpcSerialization.layerNdjson)
);
// Browser / anywhere with a global WebSocket
const BrowserProtocolLive = RpcClient.layerProtocolSocket().pipe(
Layer.provide(Socket.layerWebSocket('wss://api.example.com/rpc')),
Layer.provide(Socket.layerWebSocketConstructorGlobal),
Layer.provide(RpcSerialization.layerNdjson)
);
```
`Socket.layerWebSocket(url, { openTimeout?, protocols?, highWaterMark? })` requires a `WebSocketConstructor`; `layerWebSocketConstructorGlobal` uses `globalThis.WebSocket`. `NodeSocket.layerWebSocket` bundles the constructor. Close is a typed failure; reconnect policies reacquire the scoped reader.
### Raw TCP
```ts
const TcpProtocolLive = RpcClient.layerProtocolSocket().pipe(
Layer.provide(NodeSocket.layerNet({ port: 9000 })),
Layer.provide(RpcSerialization.layerSchemaBinary())
);
```
`Socket.Socket` layer construction, the `SocketError` taxonomy, and reconnect internals are covered by the effect-socket skill.
### The `Protocol` service (custom transports)
`RpcClient.Protocol` is a `Context.Service` with this surface:
```ts
{
readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
readonly send: (clientId: number, request: FromClientEncoded, transferables?) => Effect<void, RpcClientError>;
readonly supportsAck: boolean; // chunk acks → server-side stream backpressure
readonly supportsTransferables: boolean; // worker-only
}
```
`FromServerEncoded` now also includes `RequestEncoded` for server-originated requests and notifications. The ordinary generated RPC client ignores these requests; reverse-protocol adapters such as MCP build a matching client contract to handle them. A notification has `isNotification: true`, and JSON-RPC omits its id.
Build your own with `RpcClient.Protocol.make((writeResponse, clientIds) => Effect<Omit<Service, 'run'>>)` — it buffers server responses per client until that client's `run` loop is installed. You rarely need this; prefer `RpcTest` for in-memory wiring (section 11).
The returned service must include `codecFor`, normally forwarded
from the selected `RpcSerialization` service. It chooses the schema codec for
RPC payloads/results while the protocol handles envelopes. JSON-compatible
custom transports can use `codecFor: Schema.toCodecJson`. Preserve the schema's
decoding and encoding service requirements; see `effect-rpc-server` for the
full `RpcSerialization.CodecFor` contract.
---
## 5. Serialization — Pairing Codecs with Transports
`RpcSerialization` is the shared codec service. The load-bearing property is `includesFraming`: framed codecs can split a byte stream into messages; unframed codecs assume the transport delivers whole messages.
| Layer | Content-Type | Framed | Pair with |
|---|---|---|---|
| `RpcSerialization.layerJson` | `application/json` | no | HTTP (response decoded once, as an array); WebSocket (each ws message is one frame already) |
| `RpcSerialization.layerNdjson` | `application/x-ndjson` | yes (newline) | anything — the safe default; enables streaming over HTTP |
| `RpcSerialization.layerSchemaBinary(options?)` | `application/vnd.effect.rpc+schema-binary` | yes | schema-derived binary framing and payload codecs; pair on both peers |
| `RpcSerialization.layerJsonRpc({ contentType? })` | `application/json` | no | JSON-RPC 2.0 interop over HTTP/WebSocket; maps rpc tag ↔ `method`, supports batch arrays |
| `RpcSerialization.layerNdJsonRpc({ contentType? })` | `application/json-rpc` | yes (newline) | JSON-RPC 2.0 over sockets |
`layerSchemaBinary({ maxFrameSize?, fingerprintPayloads? })` defaults to a
16 MiB frame limit and no payload fingerprint. Envelopes are fingerprinted and
dictionary-enabled; payload fingerprints opt into strict layout agreement.
Workers use
`Schema.toCodecJson` with structured clone without a serialization layer.
NDJSON skips empty LF/CRLF lines, but a malformed **nonempty** line throws
`RpcSerialization.NdjsonDecodeError` preserving the parse `cause`; it no longer
silently loses that frame. The corrected `application/x-ndjson` header still
interoperates with older Effect HTTP peers.
JSON-RPC decoding skips non-object values (including batch entries), and guards
non-string notification methods before interpreting internal protocol methods.
This framing recovery does not replace payload/schema validation.
A failed stream-chunk schema decode terminates and interrupts only the affected
request. Interruption while its bounded buffer is full releases the delivery
wait instead of stalling the shared receive loop. Terminal error/defect broadcasts
snapshot pending requests so newly started calls are not swept into that failure.
Choose serialization according to transport framing:
- **Raw TCP needs a framed codec** (NDJSON, SchemaBinary, or newline JSON-RPC) — plain JSON cannot find message boundaries in a byte stream.
- **WebSocket works with any codec** including plain `json`, because the ws transport frames messages itself.
- **HTTP + unframed (`json`/`jsonRpc`)**: the client buffers the whole response and expects a JSON array of response messages — streaming rpcs only flush when the response ends.
- **HTTP + framed serialization**: the client incrementally parses the response body — streaming rpc chunks arrive as the server emits them, over a single POST.
- **Client and server must use the same codec.** SchemaBinary and JSON are distinct wire contracts.
Use `layerSchemaBinary()` for schema-derived binary transport, and coordinate
both peers when changing formats. Do not treat a serialization change as a
transparent migration of persisted data.
---
## 6. Consuming Streaming RPCs
A `stream: true` rpc produces a `Stream` on the client (no `Effect` wrapper — run it directly):
```ts
const users = yield* client.StreamUsers({ id: '1' }).pipe(
Stream.take(5),
Stream.runCollect
);
```
Mechanics worth knowing:
- Chunks are buffered client-side in a bounded queue (`streamBufferSize`, default 16).
- On transports with `supportsAck` (socket, worker), the client sends an `Ack` after delivering each chunk to the buffer — the server will not emit past the in-flight window, so slow consumers backpressure the producer end to end. Over HTTP there are no acks; the server streams freely.
- Ending consumption early (e.g. `Stream.take`, interruption) closes the stream's scope, which sends an `Interrupt` for the request — the server-side handler is interrupted and its finalizers run.
- The stream fails with the same error channel as effect rpcs (declared error | middleware errors | `RpcClientError`).
### `asQueue: true`
Returns `Effect<Queue.Dequeue<A, E | Cause.Done>, never, Scope | ...>` instead of a `Stream` — use when you need manual chunk-level control:
```ts
const program = Effect.scoped(
Effect.gen(function* () {
const queue = yield* client.StreamUsers({ id: '1' }, { asQueue: true });
const users: Array<User> = [];
// drain: Queue.take fails with Cause.Done when the stream ends
yield* Queue.take(queue).pipe(
Effect.flatMap((user) => Effect.sync(() => users.push(user))),
Effect.forever,
Effect.catchIf(Cause.isDone, () => Effect.void)
);
// closing the scope early interrupts the request server-side
return users;
})
);
```
End-of-stream is signaled as `Cause.Done` in the queue's error channel, not as a value — guard with `Cause.isDone`, or `Effect.catchTag('Done', ...)` (`Done` is tagged; this is how the cluster `Runners` module drains upstream). The `Scope` requirement is how the request's lifetime is tied to your code — keep the scope open while consuming.
---
## 7. Interruption and Abort Propagation
Interruption is a first-class protocol message, not just a local cancel:
- **Effect rpcs** — interrupting the calling fiber interrupts the in-flight send and dispatches an `Interrupt` envelope to the server (best-effort, with a 1-second internal timeout so shutdown never hangs on a dead connection).
- **Stream rpcs** — the `Interrupt` is sent from a scope finalizer when the stream/queue scope closes for any reason (early `Stream.take`, fiber interrupt, error).
- **HTTP transport** — the protocol drops `Interrupt` messages (`send` ignores everything but `Request`). Interruption still propagates: interrupting the fiber aborts the underlying HTTP request, and the server interrupts the handler when the connection drops. The observable difference: there is no graceful interrupt message, just an aborted request.
- **Client scope close** — all in-flight requests resume as interrupted, `Interrupt`s are sent where the transport supports it, and any later call on the client returns `Effect.interrupt`.
```ts
const fiber = yield* client.Never().pipe(Effect.forkChild);
yield* Effect.sleep('500 millis');
yield* Fiber.interrupt(fiber); // server-side handler's onInterrupt/finalizers run
```
On the server, a client-initiated interrupt carries the `RpcSchema.ClientAbort` annotation in the cause so handlers can distinguish client cancel from server shutdown — see the effect-rpc-server skill.
---
## 8. Error Handling — the `RpcClientError` Taxonomy
`RpcClientError` is a `Schema.Error` with `_tag: 'RpcClientError'` and a `reason` union. Its `message` is `` `${reason._tag}: ${reason.message}` ``.
| `reason._tag` | Transport | Meaning |
|---|---|---|
| `'HttpError'` | HTTP | `HttpClientErrorSchema`: has `kind: 'EncodeError' \| 'DecodeError' \| 'TransportError' \| 'InvalidUrlError' \| 'StatusCodeError' \| 'EmptyBodyError'` and optional `cause` |
| `'SocketOpenError'` | socket | failed to (re)connect, including opening-handshake timeouts |
| `'SocketReadError'` / `'SocketWriteError'` | socket | I/O failure on a live connection; a liveness timeout is a read error |
| `'SocketCloseError'` | socket | connection closed (has `code`) |
| `'WorkerSpawnError'` / `'WorkerSendError'` / `'WorkerReceiveError'` / `'WorkerUnknownError'` | worker | worker lifecycle failures |
| `'RpcClientDefect'` | any | protocol bug: undecodable message, empty HTTP response, non-array unframed response; has `message` + `cause` |
Handling strategy — recover from your domain errors by tag, treat `RpcClientError` as retryable-or-fatal at the edge:
```ts
const getUser = (id: string) =>
client.GetUser({ id }).pipe(
Effect.catchTag('UserNotFound', () => Effect.succeed(guestUser)), // domain error
Effect.retry({
// transport-only retry with backoff
while: (e) => e._tag === 'RpcClientError' && e.reason._tag !== 'RpcClientDefect',
schedule: Schedule.exponential('200 millis').pipe(
Schedule.upTo({ times: 3 })
)
})
);
```
Semantics to remember:
- **`ClientProtocolError` fails everything in flight.** When a socket dies or a worker crashes, every pending request on that connection fails with the same `RpcClientError`. Requests are *not* replayed after reconnect — retry at the call site.
- **Server defects are `Cause.Die`, not typed failures.** `Effect.catchTag` will not see them; use `Effect.sandbox`/`Effect.catchCause`. What survives the wire depends on the rpc's `defect` schema (see the effect-rpc-api skill).
- **Whole-connection defects** (server-side fatal defects when the server runs without `disableFatalDefects`) arrive as a `Defect` message and kill every in-flight request on the connection as `Cause.Die`.
- `RpcTest.makeClient` clients have `E = never` — no transport error channel, only your rpc errors and middleware errors.
---
## 9. Connection Lifecycle, Reconnection, and `ConnectionHooks`
The socket protocol owns a long-lived connection loop:
- **Keepalive** — `pingInterval` defaults to 5s and `pingTimeout` defaults to that interval. Liveness is time since **any decoded server frame**, not just Pong. Timeouts are checked on ping ticks; a late first tick sends a ping before declaring silence. Timeout fails the open connection with `SocketReadError` and reconnects; all in-flight calls fail even with `retryTransientErrors: true` and are not replayed.
- **Timeout hook** — `onPingTimeout: Effect<void>` runs before `ConnectionHooks.onDisconnect` and before in-flight calls fail. It must be service-free/infallible; defects are logged and ignored, as with `onTransientError`.
- **Reconnect policy** — the loop retries with `Schedule.min([Schedule.exponential("500 millis", 1.5), Schedule.spaced("5 seconds")])`, capped at 5s between attempts, forever, by default. Both `layerProtocolSocket({ retryPolicy })` and `makeProtocolSocket({ retryPolicy })` accept a custom schedule, plus `retryTransientErrors` and `onTransientError`.
- **Failure broadcast** — on a connection error, all in-flight requests fail with `RpcClientError`, and subsequent `send`s fail fast with the same error until the socket reopens.
- **`retryTransientErrors: true`** — connection-establishment `SocketOpenError` failures are not broadcast: pending requests stay pending across those reconnect attempts instead of failing. Established-connection read/write/close errors, including liveness timeouts, still fail in-flight requests.
- **`onTransientError`** — called for every retried `SocketOpenError` while `retryTransientErrors` is enabled. Liveness timeouts do **not** invoke it. Its infallible, service-free effect is for logging/metrics; defects in the hook are logged and ignored.
```ts
const ProtocolLive = RpcClient.layerProtocolSocket({ retryTransientErrors: true }).pipe(
Layer.provide(NodeSocket.layerWebSocket('ws://localhost:3000/rpc')),
Layer.provide(RpcSerialization.layerNdjson)
);
```
### `ConnectionHooks`
An optional `Context.Service` the socket and worker protocols pick up if present:
```ts
const HooksLive = Layer.succeed(RpcClient.ConnectionHooks)({
onConnect: Effect.logInfo('rpc connected'), // socket: every (re)connect; worker: once after pool warm-up
onDisconnect: Effect.logWarning('rpc disconnected') // socket only; runs when a connection ends
});
// Provide it alongside the protocol layer:
const ProtocolWithHooks = ProtocolLive.pipe(Layer.provideMerge(HooksLive));
```
Use `onConnect` to refresh auth state or re-subscribe after a reconnect. The HTTP protocol never invokes hooks (there is no connection).
---
## 10. Worker Transports and `RpcWorker.InitialMessage`
`layerProtocolWorker` runs the *server* inside workers and the client in the parent. Pool options come in two shapes:
```ts
// Fixed-size pool
RpcClient.layerProtocolWorker({ size: 4, concurrency: 1, targetUtilization: 1 });
// Elastic pool
RpcClient.layerProtocolWorker({
minSize: 1,
maxSize: 8,
timeToLive: '60 seconds', // idle workers above minSize are released
concurrency: 1
});
```
`concurrency` is requests-per-worker; a request checks a worker out of the pool until its `Exit` arrives. The protocol supports transferables (below) and acks. The pool spawns its minimum eagerly at startup via a background fiber — all `size` workers for the fixed pool, `minSize` for the elastic pool — and protocol initialization blocks until the first worker is ready (then `ConnectionHooks.onConnect` runs). That eager first spawn is why `layerProtocolWorker` is the only protocol layer with a non-`never` error channel: handle or `Layer.orDie` the `WorkerError` when composing the final layer. On worker crash, a `ClientProtocolError` is broadcast — every in-flight request on the protocol fails, not just the crashed worker's — and the worker is respawned (retried every second).
```ts
// Node parent
const WorkerClient = UsersClient.layer.pipe(
Layer.provide(RpcClient.layerProtocolWorker({ size: 1 })),
Layer.provide(NodeWorker.layer((id) => new WorkerThreads.Worker('./worker.js')))
);
// Browser parent
const BrowserClient = UsersClient.layer.pipe(
Layer.provide(RpcClient.layerProtocolWorker({ size: 1 })),
Layer.provide(BrowserWorker.layer(() => new Worker(new URL('./worker.ts', import.meta.url))))
);
```
No `RpcSerialization` is needed — structured clone carries the messages. The worker side runs `RpcServer.layerProtocolWorkerRunner` (see the effect-rpc-server skill).
Transferables: to move binary data instead of copying it, wrap fields in the shared contract with `Transferable` from `effect/workers` — `Transferable.Uint8Array` transfers the backing `ArrayBuffer`, `Transferable.ImageData`/`Transferable.MessagePort` are prebuilt, and `Transferable.schema(s, (encoded) => [encoded.buffer])` wraps any schema with a custom transfer-list extractor. Transfer only happens on protocols with `supportsTransferables: true` — the worker protocol only.
### Typed startup config — `RpcWorker.InitialMessage`
Send one schema-encoded value at spawn time, before any rpc traffic:
```ts
class WorkerConfig extends Schema.Class<WorkerConfig>('WorkerConfig')({
apiUrl: Schema.String,
tenantId: Schema.String
}) {}
// Parent: provide alongside the worker protocol
const InitialMessageLive = RpcWorker.layerInitialMessage(
WorkerConfig,
Effect.succeed(new WorkerConfig({ apiUrl: '/api', tenantId: 't1' }))
);
const ClientLive = UsersClient.layer.pipe(
Layer.provide(RpcClient.layerProtocolWorker({ size: 4 })),
Layer.provide(InitialMessageLive),
Layer.provide(NodeWorker.layer(spawnWorker))
);
```
The build effect runs once per spawned worker and its result is encoded with the schema's JSON codec (transferables are collected automatically). Inside the worker, read it with `RpcWorker.initialMessage(WorkerConfig)` — server-side detail, see the effect-rpc-server skill.
---
## 11. Testing — `RpcTest.makeClient`
In-process client + server pair over the no-serialization path. Requests, stream chunks, acks, interrupts, headers, and middleware all flow through the real machinery — no network, no codecs:
```ts
import { it } from '@effect/vitest';
export class UsersClient extends Context.Service<
UsersClient,
RpcClient.RpcClient<RpcGroup.Rpcs<typeof UserRpcs>, RpcClientError>
>()('UsersClient') {
static readonly layer = Layer.effect(UsersClient)(RpcClient.make(UserRpcs)).pipe(
Layer.provide(AuthClient)
);
// Same service shape — swap the layer, not the call sites
static readonly layerTest = Layer.effect(UsersClient)(RpcTest.makeClient(UserRpcs)).pipe(
Layer.provide([UsersLive, AuthLive, AuthClient])
);
}
it.effect('GetUser', () =>
Effect.gen(function* () {
const client = yield* UsersClient;
const user = yield* client.GetUser({ id: '1' });
expect(user.id).toBe('1');
}).pipe(Effect.provide(UsersClient.layerTest)));
```
Signature: `RpcTest.makeClient(group, options?: { flatten? })` with required context `Scope | Rpc.ToHandler<Rpcs> | Rpc.Middleware<Rpcs> | Rpc.MiddlewareClient<Rpcs>` — i.e. the handler layers, any *server* middleware layers, **and** any client middleware layers. Forgetting the client middleware layer is the classic confusing type error.
The test client's `E` is `never`: transport errors cannot occur, so tests exercise only your declared errors, middleware errors, and defects. To also test serialization and transport semantics, build a real client+server pair against `NodeHttpServer.layerTest` exactly as `packages/platform/node/test/RpcServer.test.ts` does.
### `RpcClient.makeNoSerialization` (advanced)
The primitive under `RpcTest`: builds a client from a raw decoded-message channel and returns `{ client, write }`, where you implement `onFromClient` (deliver messages toward a server) and call `write` with `FromServer` messages. Extra options over `make`: `supportsAck` (default `true`). Use it to bridge a client onto an exotic in-process channel; otherwise prefer `RpcTest.makeClient`.
---
## Key Patterns
### HTTP client service, end to end
```ts
// client.ts — UserRpcs comes from the shared contract module (effect-rpc-api skill)
import { Context, Effect, Layer } from 'effect';
import { FetchHttpClient } from 'effect/http';
import { RpcClient, RpcGroup, RpcSerialization } from 'effect/rpc';
import { RpcClientError } from 'effect/rpc/RpcClientError';
import { AuthClient, UserRpcs } from './contract.ts';
export class UsersClient extends Context.Service<
UsersClient,
RpcClient.RpcClient<RpcGroup.Rpcs<typeof UserRpcs>, RpcClientError>
>()('UsersClient') {
static readonly layer = Layer.effect(UsersClient)(
RpcClient.make(UserRpcs, { spanPrefix: 'UsersClient' })
).pipe(
Layer.provide(AuthClient),
Layer.provide(RpcClient.layerProtocolHttp({ url: 'https://api.example.com/rpc' })),
Layer.provide(RpcSerialization.layerNdjson), // framed → streaming rpcs work over HTTP
Layer.provide(FetchHttpClient.layer)
);
}
const program = Effect.gen(function* () {
const client = yield* UsersClient;
const user = yield* client.GetUser({ id: 'u1' });
yield* Effect.logInfo('got', user);
}).pipe(RpcClient.withHeaders({ 'x-request-source': 'cli' }));
```
### Resilient WebSocket client with reconnect hooks
```ts
const ProtocolLive = RpcClient.layerProtocolSocket({ retryTransientErrors: true }).pipe(
Layer.provide(NodeSocket.layerWebSocket('wss://api.example.com/rpc')),
Layer.provide(RpcSerialization.layerNdjson),
Layer.provideMerge(
Layer.succeed(RpcClient.ConnectionHooks)({
onConnect: refreshAuthToken,
onDisconnect: Effect.logWarning('rpc disconnected')
})
)
);
export const UsersClientLive = UsersClient.layer.pipe(Layer.provide(ProtocolLive));
```
### Consume a streaming rpc with early exit and call-site retry
```ts
const firstFive = client.StreamUsers({ id: '1' }).pipe(
Stream.take(5), // closing the stream sends Interrupt to the server
Stream.runCollect,
Effect.retry({
while: (e) => e._tag === 'RpcClientError',
schedule: Schedule.exponential('250 millis').pipe(
Schedule.upTo({ times: 5 })
)
})
);
```
### Fire-and-forget command with ambient tenant headers
```ts
const enqueue = (job: JobInput) =>
client.EnqueueJob(job, { discard: true }).pipe(
// declared rpc error is gone; transport errors remain
Effect.catchTag('RpcClientError', (e) => Effect.logError('enqueue failed', e.reason))
);
yield* Effect.forEach(jobs, enqueue, { concurrency: 8 }).pipe(
RpcClient.withHeaders({ 'x-tenant': tenantId })
);
```
### Worker pool with typed startup config
```ts
const WorkerClientLive = UsersClient.layer.pipe(
Layer.provide(RpcClient.layerProtocolWorker({ minSize: 1, maxSize: 4, timeToLive: '30 seconds' })),
Layer.provide(RpcWorker.layerInitialMessage(WorkerConfig, loadWorkerConfig)),
Layer.provide(BrowserWorker.layer(() => new Worker(new URL('./rpc-worker.ts', import.meta.url))))
);
```
---
## Common Mistakes
1. **Importing from `@effect/rpc`.** Gone in v4 — everything is `effect/rpc`. And `import { RpcClientError } from 'effect/rpc'` gives you a *namespace*; import the class from `effect/rpc/RpcClientError`.
2. **Missing `Scope` for `RpcClient.make`.** The constructor is scoped. Build clients inside `Layer.effect(Tag)(RpcClient.make(group))` or under `Effect.scoped` — providing protocol layers alone will not discharge `Scope`.
3. **Forgetting the client middleware layer.** A group with a `requiredForClient: true` middleware needs `Layer.provide(RpcMiddleware.layerClient(M, ...))` on the client (and in `RpcTest.makeClient`'s context). The compile error points at an unsatisfied `ForClient<M>` requirement — provide the layer, don't cast.
4. **Wrong codec/transport pairing.** Raw TCP requires `layerNdjson`, `layerSchemaBinary()`, or `layerNdJsonRpc()`. HTTP with unframed JSON buffers the response; use a framed codec for streaming. WebSocket supplies its own framing.
5. **Mismatched client/server serialization.** Both sides share one `RpcSerialization` choice; there is no negotiation. Garbled `RpcClientDefect: Error decoding ...` errors usually mean the codecs differ.
6. **Reading mixed-case header names server-side.** `Headers.fromInput` lowercases keys: send `{ userId: '123' }`, read `headers.userid`. Same for `withHeaders` and middleware `Headers.set`.
7. **Expecting `discard: true` to be error-free.** It only removes the rpc's *declared* error; `RpcClientError` and middleware errors remain, and over HTTP the POST round-trip is still awaited.
8. **Catching server defects with `catchTag`.** Handler `Effect.die`s arrive as `Cause.Die`, not typed failures. Use `Effect.sandbox`/`Effect.catchCause`, and remember one server fatal defect can fail *all* in-flight requests on the connection.
9. **Assuming requests survive a reconnect.** A socket/worker failure fails every in-flight call with `RpcClientError`; after reconnect nothing is replayed. Add `Effect.retry` at call sites; `retryTransientErrors: true` only keeps requests pending across *connection-establishment* failures.
10. **Treating only Pong as liveness.** Both socket constructors accept `pingInterval`, `pingTimeout`, `onPingTimeout`, and `retryPolicy`; every decoded server frame resets the liveness clock. Reconnection never replays failed calls.
11. **Treating a flattened client like an object client.** With `flatten: true` you call `client('GetUser', payload)`; `client.GetUser(payload)` is not a function. Pick one shape per client.
12. **Waiting for a queue value to signal end-of-stream.** With `asQueue: true`, completion is `Cause.Done` in the `Queue.take` error channel, and the `Dequeue` lives in a `Scope` — closing that scope interrupts the request on the server.
13. **Expecting a graceful interrupt over HTTP.** The HTTP protocol drops `Interrupt` messages; interruption aborts the in-flight POST instead. Server handlers are still interrupted, but only when the connection abort is observed.
14. **`RpcSerialization` provided to the worker protocol.** Worker transports use structured clone — no serialization layer is needed (or used); `RpcSerialization` is for HTTP and socket protocols.
15. **Wrong option key names on `make`.** They are `spanPrefix`, `spanAttributes`, `disableTracing`, `generateRequestId`, `flatten` — there is no `baseUrl`, `headers`, or `serialization` option on `RpcClient.make`; those live on the protocol/serialization layers and per-call options.
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · mpsuesser/opencode-effect-enforcer | 95 | MIT |
| mpsuesser/opencode-effect-enforcer | 95 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki bdcc2750e186 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 95effect-rpc-server
Obsługuje grupy RPC w Effect po stronie serwera: warstwy handlerów, middleware, strumienie, zamykanie i testy RpcTest. - 95effect-rpc-server
Udostępnia kontrakty RPC w Effect po stronie serwera: warstwy obsługi, transporty HTTP i WebSocket, middleware i zamykanie. - 100effect-ts
Pomaga pisać, debugować, refaktoryzować i wyjaśniać kod w ekosystemie Effect-TS: serwisy, warstwy, fibery, strumienie, harmonogramy i migrację do Effect. - 100effect-ts
Pomaga pisać, debugować, refaktoryzować i wyjaśniać kod w ekosystemie Effect-TS: serwisy, warstwy, fibery, strumienie, harmonogramy i migrację do Effect. - 100add-rpc
Prowadzi przez dodawanie nowych wywołań RPC do Wave Terminal: nowe polecenia RPC, metody komunikacji serwer-klient i rozszerzanie interfejsu RPC. - 100eventa
Opisuje użycie biblioteki @moeru/eventa do komunikacji zdarzeniowej między procesami i wątkami (Electron IPC, Web Workers, WebSocket), z typowanym RPC i streamingiem.