effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/rpc/RpcMiddleware.ts

@@ -1,29 +1,39 @@
 /**
- * The `RpcMiddleware` module defines middleware services that can wrap RPC
- * handler execution on the server and request execution in generated clients.
+ * Middleware services for the unstable RPC runtime.
  *
- * Use middleware to attach cross-cutting behavior to individual RPCs or whole
- * `RpcGroup`s, such as authentication, authorization, request logging, tracing,
- * metrics, rate limiting, header propagation, or adding request-scoped services
- * to the handler context. A middleware service records the services it requires
- * and provides, the schema for errors it can fail with, and whether clients must
- * install a matching middleware via `layerClient`.
+ * A middleware service wraps server handler execution and can also install a
+ * client-side wrapper for generated clients. Its metadata records the services
+ * provided to downstream handlers, the services required by the middleware
+ * implementation, the schema for server-visible failures, the client-only error
+ * type, and whether generated clients must require the matching client layer.
  *
- * Server middleware receives the target `rpc`, decoded `payload`, request
- * `headers`, `requestId`, and `Rpc.ServerClient`, then wraps the handler effect.
- * Its `provides` type removes services from the downstream handler requirement,
- * while `requires` adds the services needed by the middleware implementation.
- * Middleware errors must be declared with a `Schema` so they can be encoded as
- * RPC failures, and any schema encoding or decoding services remain part of the
- * generated RPC environments.
+ * **Mental model**
  *
- * Client middleware is installed with `layerClient`, captures the surrounding
- * layer context, and can inspect, rewrite, retry, or short-circuit outgoing
- * requests before calling `next`. Set `requiredForClient` when an RPC's typed
- * client must require that `ForClient` layer; otherwise a client implementation
- * is used only when one is present. `clientError` contributes only to the
+ * A server {@link RpcMiddleware} receives the target RPC, decoded payload,
+ * request headers, request id, and `Rpc.ServerClient`, then wraps the handler
+ * effect. `provides` removes services from the downstream handler requirement,
+ * while `requires` adds the services needed by the middleware. A client
+ * {@link RpcMiddlewareClient} is installed with {@link layerClient}; it can
+ * inspect, rewrite, retry, or short-circuit outgoing requests before calling
+ * `next`.
+ *
+ * **Common tasks**
+ *
+ * Use {@link Service} to define authentication, authorization, logging,
+ * tracing, metrics, rate limiting, header propagation, or request-scoped
+ * service injection. Attach the service to individual RPCs or whole groups,
+ * then provide the server implementation like any other `Context.Service`.
+ * Provide a client implementation with {@link layerClient} when outgoing
+ * requests need matching behavior.
+ *
+ * **Gotchas**
+ *
+ * Middleware failures that cross the RPC boundary must be declared with a
+ * `Schema`, and any encoding or decoding services required by that schema stay
+ * in the generated RPC environments. `clientError` contributes only to the
  * client-side call error channel, while the middleware `error` schema is shared
- * with server failures.
+ * with server failures. Set `requiredForClient` only when typed clients must
+ * reject calls unless the matching client middleware layer is installed.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcSchema.ts

@@ -1,26 +1,36 @@
 /**
- * The `RpcSchema` module contains the RPC-specific schema markers and cause
- * annotations shared by the RPC declaration, client, and server layers. It is
- * used when an RPC response is a `Stream`, and when server-side interruption
- * logic needs to identify a client-initiated abort.
+ * RPC schema markers and interruption annotations.
  *
- * Use {@link Stream} to mark an RPC success schema as a streamed response,
- * {@link isStreamSchema} to detect that marker, and the stored success and
- * error schemas to encode or decode stream chunks. Request payload schemas live
- * on the `Rpc` definition itself; this module only describes the streamed
- * response shape. For streaming RPCs, the success schema passed to
- * `RpcSchema.Stream` is the stream element schema, while the error schema is
- * the stream error schema. When the marker is installed by the `Rpc`
- * constructor's `stream` option, the immediate RPC exit succeeds with `void`,
- * the ordinary RPC error schema is set to `Schema.Never`, and the stream error
- * schema is used for stream failures.
- *
- * Streaming schemas are not general-purpose codecs for arbitrary stream values:
- * they are RPC metadata that lets the protocol distinguish one-shot successes
- * from streamed elements and keep stream errors on the chunk stream. Use
- * {@link ClientAbort} when annotating interruptions caused by a remote client
+ * This module contains the small pieces of schema metadata that the RPC
+ * declaration, client, server, cluster, and reactivity layers share. It marks
+ * streamed responses and annotates interruptions that came from a remote client
  * closing or cancelling a request.
  *
+ * **Mental model**
+ *
+ * A streaming RPC still has a normal RPC exit, but its success schema is marked
+ * with {@link Stream}. The marker stores the stream element schema and the
+ * stream error schema so transports can encode and decode each chunk while
+ * keeping stream failures on the chunk stream.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link Stream} when constructing RPC metadata directly
+ * - Use {@link isStreamSchema} to branch between one-shot and streaming
+ *   responses in protocol implementations
+ * - Read the stored `success` and `error` schemas when encoding or decoding
+ *   stream chunks
+ * - Use {@link ClientAbort} to tag interruptions caused by client disconnects
+ *
+ * **Gotchas**
+ *
+ * - `Rpc.make(..., { stream: true })` installs this marker for you
+ * - For streaming RPCs, the immediate RPC exit succeeds with `void`; stream
+ *   elements and stream errors are encoded separately
+ * - Request payload schemas live on the `Rpc` definition, not in this module
+ * - `Stream` is RPC metadata, not a general-purpose codec for arbitrary
+ *   `Stream` values
+ *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"

package/src/unstable/rpc/RpcSerialization.ts

@@ -1,27 +1,37 @@
 /**
  * Serialization support for the unstable RPC protocol.
  *
- * This module provides the `RpcSerialization` service used by RPC clients and
- * servers to encode and decode transport-level `RpcMessage` envelopes. Use the
- * built-in JSON, newline-delimited JSON, JSON-RPC 2.0, and MessagePack
- * implementations when wiring HTTP, sockets, workers, or custom transports, or
- * provide a custom service when a transport needs a different content type,
- * frame format, or binary codec.
+ * `RpcSerialization` is the boundary between encoded RPC protocol messages and
+ * the bytes or strings carried by a transport. RPC clients and servers use the
+ * service to turn `RpcMessage` envelopes into JSON, newline-delimited JSON,
+ * JSON-RPC 2.0, or MessagePack payloads, and to parse those payloads back into
+ * protocol messages.
  *
- * Serialization runs after RPC schemas have encoded payloads, successes,
- * failures, and stream chunks into transport-safe values, and before schemas
- * decode those values on the other side. Choose a format that can represent the
- * schema-encoded data: JSON is easy to inspect but needs schema encodings for
- * arbitrary binary values, while MessagePack is more compact and carries binary
- * data more naturally.
+ * **Mental model**
  *
- * Transport framing is significant. `json` and `jsonRpc` expect a complete
- * payload for each decode call and are intended for transports such as HTTP
- * that already delimit message bodies. `ndjson`, `ndJsonRpc`, and `msgPack`
- * maintain parser state for chunked streams, so they can decode multiple
- * messages or incomplete fragments from sockets and other streaming transports.
- * Match the serialization layer to the transport boundary, otherwise messages
- * may be buffered, split, or parsed at the wrong frame.
+ * RPC schemas are responsible for encoding payloads, successes, failures, and
+ * stream chunks into transport-safe values. This module then chooses how those
+ * values are represented on the wire and whether message boundaries are part of
+ * that representation. The parser returned by `makeUnsafe` may be stateful, so
+ * transports should create a parser for the lifetime of the stream, connection,
+ * or request body they are decoding.
+ *
+ * **Common tasks**
+ *
+ * Use `layerJson` or `layerJsonRpc` when the transport already frames each
+ * payload, such as ordinary HTTP request and response bodies. Use
+ * `layerNdjson`, `layerNdJsonRpc`, or `layerMsgPack` for sockets, workers, and
+ * other streaming transports that can receive partial chunks or several
+ * messages in one chunk. Provide a custom `RpcSerialization` service when a
+ * transport requires a different content type, frame format, or binary codec.
+ *
+ * **Gotchas**
+ *
+ * Both ends of the connection must use compatible serialization and framing.
+ * `json` and `jsonRpc` expect a complete payload for each decode call, while
+ * `ndjson`, `ndJsonRpc`, and `msgPack` keep parser state for incomplete input.
+ * JSON is easy to inspect but needs schema encodings for arbitrary binary
+ * values; MessagePack is more compact and carries binary data more naturally.
  *
  * @since 4.0.0
  */
@@ -499,7 +509,7 @@ export const msgPack: RpcSerialization["Service"] = makeMsgPack({ useRecords: tr
  *
  * **When to use**
  *
- * Use this if your protocol supports framing for messages, otherwise use
+ * Use when you use this if your protocol supports framing for messages, otherwise use
  * {@link layerNdjson}.
  *
  * @category serialization
@@ -512,7 +522,7 @@ export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSeriali
  *
  * **When to use**
  *
- * Use this if your protocol does not support framing for messages, otherwise
+ * Use when you use this if your protocol does not support framing for messages, otherwise
  * use {@link layerJson}.
  *
  * @category serialization

package/src/unstable/rpc/RpcServer.ts

@@ -1,33 +1,41 @@
 /**
- * Server-side support for running RPCs defined in an `RpcGroup`.
+ * Server-side runtime for RPC groups.
  *
- * This module connects typed RPC handlers to an encoded or already-decoded
- * transport, decodes client requests, invokes the matching handler, and sends
- * exits, stream chunks, defects, interrupts, and client-end notifications back
- * through the active server protocol. Use it to expose an RPC group through
- * `layerHttp`, standalone HTTP effects, websocket or socket servers, stdio,
- * worker runners, or a custom `Protocol`; use `makeNoSerialization` when the
- * surrounding system already owns message serialization.
+ * This module connects typed handlers for an RPC group to a transport. It
+ * receives client messages, decodes request payloads, runs the matching
+ * handler, and writes exits, stream chunks, defects, interrupts, and client-end
+ * notifications back through the active server protocol. It supports encoded
+ * protocols such as HTTP, websocket, socket, stdio, and worker transports, plus
+ * already-decoded channels through {@link makeNoSerialization}.
  *
- * The `Protocol` service is the transport boundary. It declares how encoded
- * client messages are received and how encoded responses are written, plus
- * whether the transport supports stream acknowledgements, transferable
- * objects, and span propagation. HTTP request/response serving is useful for
- * simple calls and response streaming, but it does not provide client
- * acknowledgements or span propagation; websocket, socket, stdio, and worker
- * protocols keep a live channel and can participate in the streaming
- * acknowledgement lifecycle.
+ * **Mental model**
  *
- * **Handler gotchas**
+ * {@link Protocol} is the transport boundary. It owns how encoded client
+ * messages arrive, how encoded server responses are written, and whether the
+ * channel supports acknowledgements, transferable objects, or span
+ * propagation. {@link make} and {@link layer} combine that protocol with an RPC
+ * group and the handler context required by `Rpc.ToHandler` and
+ * `Rpc.Middleware`.
+ *
+ * **Common tasks**
+ *
+ * Use {@link layerHttp} for route-mounted HTTP or websocket serving,
+ * {@link toHttpEffect} and {@link toHttpEffectWebsocket} for standalone HTTP
+ * effects, the `layerProtocol*` constructors for socket, stdio, or worker
+ * transports, and {@link makeNoSerialization} when another component already
+ * owns message serialization.
+ *
+ * **Gotchas**
  *
  * - Server handlers are looked up from `Rpc.ToHandler`, while RPC middleware
- *   is looked up from `Rpc.Middleware` and wraps the handler with metadata
- *   containing the `Rpc.ServerClient`, request id, headers, and decoded payload
- * - Payloads are decoded on the server and exits, stream chunks, and request
+ *   is looked up from `Rpc.Middleware` and wraps handlers with metadata that
+ *   includes `Rpc.ServerClient`, request id, headers, and decoded payload
+ * - Payloads are decoded on the server; exits, stream chunks, and request
  *   defects are encoded on the server using the RPC schemas and the handler's
- *   schema services; encode failures are reported as request defects and the
- *   in-flight request is interrupted
- * - Streaming RPCs send chunks before the final exit, and transports with
+ *   schema services
+ * - Encode failures are reported as request defects and interrupt the
+ *   in-flight request
+ * - Streaming RPCs send chunks before the final exit, and protocols with
  *   acknowledgement support wait for client acknowledgements between chunks to
  *   provide back pressure
  * - Fatal handler defects are sent as protocol defects by default; set

package/src/unstable/rpc/RpcTest.ts

@@ -1,19 +1,35 @@
 /**
- * Utilities for testing RPC groups without opening a network transport.
+ * In-memory test harness for RPC groups.
  *
- * This module connects a generated RPC client directly to an in-memory
- * `RpcServer` for the same group, using the group's handlers from the Effect
- * environment and the no-serialization message path. It is intended for tests
- * that need to exercise client calls, server handlers, middleware, request
- * routing, and streaming behavior without standing up HTTP, sockets, workers,
- * or a serializer.
+ * `RpcTest` connects a generated client directly to `RpcServer` handlers for
+ * the same `RpcGroup`. It uses the no-serialization path, so requests,
+ * responses, stream chunks, acknowledgements, interrupts, headers, and
+ * middleware metadata travel through the normal client/server machinery without
+ * opening HTTP, socket, worker, or serializer infrastructure.
  *
- * Because messages stay decoded in memory, this module is not a substitute for
- * transport or schema-encoding tests. Callers still need to provide the handler
- * layer, any client/server middleware services, and a `Scope`; the returned
- * client is scoped to that in-memory connection. The `flatten` option follows
- * `RpcClient.makeNoSerialization`, and acknowledgements are enabled to match
- * the normal bidirectional client/server protocol used by the test harness.
+ * **Mental model**
+ *
+ * `makeClient` builds an in-memory server, wires the client and server write
+ * callbacks together, and returns the scoped generated client. The handlers,
+ * server middleware, client middleware, and `Scope` still come from the Effect
+ * environment just as they would for a real transport; only the byte-level
+ * protocol is skipped.
+ *
+ * **Common tasks**
+ *
+ * Use this module for tests that should exercise RPC routing, handler lookup,
+ * middleware, headers, typed errors, interruptions, and streaming behavior
+ * quickly. Use a real transport plus `RpcSerialization` coverage when you need
+ * to test HTTP status handling, socket framing, worker transferables, schema
+ * encoding or decoding, or wire compatibility.
+ *
+ * **Gotchas**
+ *
+ * Because no serialization happens, invalid wire payloads and mismatched codecs
+ * will not be discovered here. The client is scoped to the in-memory
+ * connection; acquire it inside a scoped test or provide `Scope` explicitly.
+ * The `flatten` option matches `RpcClient.makeNoSerialization`, and
+ * acknowledgements are enabled to mirror the bidirectional streaming protocol.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcWorker.ts

@@ -1,20 +1,35 @@
 /**
- * Helpers for passing a schema-encoded bootstrap message to worker-backed RPC
- * protocols.
+ * Bootstrap messages for worker-backed RPC protocols.
  *
- * Worker RPC protocols can send one initial message when each worker starts,
- * before ordinary RPC requests begin flowing. Use this module to build and
- * provide that message from the client side, and to decode it inside the
- * worker-side server. Common payloads include per-worker configuration,
- * credentials or session metadata, feature flags, preloaded data, or
- * transferable resources such as `ArrayBuffer` and `MessagePort` values.
+ * Worker-backed RPC clients sometimes need to send data before the first RPC
+ * request is handled: per-worker configuration, credentials, feature flags,
+ * preloaded caches, or transferable handles. This module defines the
+ * {@link InitialMessage} service plus helpers that encode that bootstrap value
+ * on the client side and decode it on the worker server side.
  *
- * The initial message uses the supplied schema's JSON codec and is posted as a
- * worker message, so it is separate from the normal `RpcSerialization` used for
- * RPC request and response traffic. Values still need to be valid for the
- * worker transport's structured clone boundary. Transferable annotations can
- * collect objects for the `postMessage` transfer list, but transferring moves
- * ownership to the worker and may detach buffers from the sender.
+ * **Mental model**
+ *
+ * The initial message is a one-time envelope outside the normal RPC request and
+ * response stream. {@link makeInitialMessage} runs the build effect, encodes
+ * its value with the supplied schema's JSON codec, and collects transferables.
+ * {@link layerInitialMessage} stores that encoded payload in context for the
+ * RPC client runtime. Inside the worker, {@link initialMessage} reads the
+ * protocol's bootstrap payload and decodes it with the same schema.
+ *
+ * **Common tasks**
+ *
+ * - Provide typed worker startup data with {@link layerInitialMessage}
+ * - Precompute encoded data and transfer lists with {@link makeInitialMessage}
+ * - Read typed startup data in the worker with {@link initialMessage}
+ *
+ * **Gotchas**
+ *
+ * The payload is posted with worker `postMessage`, so encoded values still must
+ * cross the structured clone boundary. Transferables collected during encoding
+ * are moved to the worker; buffers and ports may no longer be usable by the
+ * sender after transfer. The initial message is separate from
+ * `RpcSerialization`, so changing request/response serialization does not
+ * change how this bootstrap payload is encoded.
  *
  * @since 4.0.0
  */