effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/rpc/RpcSchema.ts

@@ -1,4 +1,26 @@
 /**
+ * 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.
+ *
+ * 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
+ * closing or cancelling a request.
+ *
  * @since 4.0.0
  */
 import * as Cause from "../../Cause.ts"
@@ -13,8 +35,11 @@ import * as Stream_ from "../../Stream.ts"
 const StreamSchemaTypeId = "~effect/rpc/RpcSchema/StreamSchema"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a schema is an RPC stream schema created by
+ * `RpcSchema.Stream`.
+ *
  * @category Stream
+ * @since 4.0.0
  */
 export function isStreamSchema(schema: Schema.Top): schema is Stream<Schema.Top, Schema.Top> {
   return Predicate.hasProperty(schema, StreamSchemaTypeId)
@@ -34,8 +59,11 @@ export function getStreamSchemas(schema: Schema.Top): Option.Option<{
 }
 
 /**
- * @since 4.0.0
+ * A schema marker for RPC streaming responses, storing the success element
+ * schema and stream error schema used for encoding and decoding stream chunks.
+ *
  * @category Stream
+ * @since 4.0.0
  */
 export interface Stream<A extends Schema.Top, E extends Schema.Top> extends
   Schema.Bottom<
@@ -56,16 +84,22 @@ export interface Stream<A extends Schema.Top, E extends Schema.Top> extends
 const schema = Schema.declare(Stream_.isStream)
 
 /**
- * @since 4.0.0
+ * Creates an RPC stream schema from a stream element success schema and stream
+ * error schema.
+ *
  * @category Stream
+ * @since 4.0.0
  */
 export function Stream<A extends Schema.Top, E extends Schema.Top>(success: A, error: E): Stream<A, E> {
   return Schema.make(schema.ast, { [StreamSchemaTypeId]: StreamSchemaTypeId, success, error })
 }
 
 /**
- * @since 4.0.0
+ * Cause annotation used to mark interruptions that originate from an RPC client
+ * abort.
+ *
  * @category Cause annotations
+ * @since 4.0.0
  */
 export class ClientAbort extends Context.Service<ClientAbort, true>()("effect/rpc/RpcSchema/ClientAbort") {
   static annotation = this.context(true).pipe(

package/src/unstable/rpc/RpcSerialization.ts

@@ -1,4 +1,28 @@
 /**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Msgpackr from "msgpackr"
@@ -9,8 +33,12 @@ import { hasProperty } from "../../Predicate.ts"
 import type * as RpcMessage from "./RpcMessage.ts"
 
 /**
- * @since 4.0.0
+ * Service describing how RPC protocol messages are encoded and decoded,
+ * including the content type and whether the serialization format provides
+ * message framing.
+ *
  * @category serialization
+ * @since 4.0.0
  */
 export class RpcSerialization extends Context.Service<RpcSerialization, {
   makeUnsafe(): Parser
@@ -19,8 +47,11 @@ export class RpcSerialization extends Context.Service<RpcSerialization, {
 }>()("effect/rpc/RpcSerialization") {}
 
 /**
- * @since 4.0.0
+ * A stateful parser for an RPC serialization format, able to decode input
+ * chunks into protocol messages and encode messages for transport.
+ *
  * @category serialization
+ * @since 4.0.0
  */
 export interface Parser {
   readonly decode: (data: Uint8Array | string) => ReadonlyArray<unknown>
@@ -28,8 +59,12 @@ export interface Parser {
 }
 
 /**
- * @since 4.0.0
+ * JSON RPC serialization for whole message payloads. It does not include
+ * message framing, so it is intended for transports that frame responses
+ * themselves.
+ *
  * @category serialization
+ * @since 4.0.0
  */
 export const json: RpcSerialization["Service"] = RpcSerialization.of({
   contentType: "application/json",
@@ -47,8 +82,11 @@ export const json: RpcSerialization["Service"] = RpcSerialization.of({
 })
 
 /**
- * @since 4.0.0
+ * Newline-delimited JSON RPC serialization that frames each protocol message
+ * with a trailing newline.
+ *
  * @category serialization
+ * @since 4.0.0
  */
 export const ndjson: RpcSerialization["Service"] = RpcSerialization.of({
   contentType: "application/ndjson",
@@ -87,8 +125,11 @@ export const ndjson: RpcSerialization["Service"] = RpcSerialization.of({
 })
 
 /**
- * @since 4.0.0
+ * Creates a JSON-RPC 2.0 serialization for RPC protocol messages without
+ * additional message framing.
+ *
  * @category serialization
+ * @since 4.0.0
  */
 export const jsonRpc = (options?: {
   readonly contentType?: string | undefined
@@ -118,8 +159,11 @@ export const jsonRpc = (options?: {
   })
 
 /**
- * @since 4.0.0
+ * Creates a newline-delimited JSON-RPC 2.0 serialization for RPC protocol
+ * messages.
+ *
  * @category serialization
+ * @since 4.0.0
  */
 export const ndJsonRpc = (options?: {
   readonly contentType?: string | undefined
@@ -402,8 +446,8 @@ type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse
 /**
  * Create a MessagePack serialization with custom msgpackr options.
  *
- * @since 4.0.0
  * @category serialization
+ * @since 4.0.0
  */
 export const makeMsgPack = (options?: Msgpackr.Options | undefined): RpcSerialization["Service"] =>
   RpcSerialization.of({
@@ -442,8 +486,11 @@ export const makeMsgPack = (options?: Msgpackr.Options | undefined): RpcSerializ
   })
 
 /**
- * @since 4.0.0
+ * Default MessagePack RPC serialization using record support and built-in
+ * message framing.
+ *
  * @category serialization
+ * @since 4.0.0
  */
 export const msgPack: RpcSerialization["Service"] = makeMsgPack({ useRecords: true })
 
@@ -453,8 +500,8 @@ export const msgPack: RpcSerialization["Service"] = makeMsgPack({ useRecords: tr
  * Use this if your protocol supports framing for messages, otherwise use
  * {@link layerNdjson}.
  *
- * @since 4.0.0
  * @category serialization
+ * @since 4.0.0
  */
 export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(json)
 
@@ -464,16 +511,16 @@ export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSeriali
  * Use this if your protocol does not support framing for messages, otherwise
  * use {@link layerJson}.
  *
- * @since 4.0.0
  * @category serialization
+ * @since 4.0.0
  */
 export const layerNdjson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(ndjson)
 
 /**
  * A rpc serialization layer that uses JSON-RPC for serialization.
  *
- * @since 4.0.0
  * @category serialization
+ * @since 4.0.0
  */
 export const layerJsonRpc = (options?: {
   readonly contentType?: string | undefined
@@ -483,8 +530,8 @@ export const layerJsonRpc = (options?: {
  * A rpc serialization layer that uses JSON-RPC for serialization seperated by
  * new lines.
  *
- * @since 4.0.0
  * @category serialization
+ * @since 4.0.0
  */
 export const layerNdJsonRpc = (options?: {
   readonly contentType?: string | undefined
@@ -496,7 +543,7 @@ export const layerNdJsonRpc = (options?: {
  * MessagePack has a more compact binary format compared to JSON and NDJSON. It
  * also has better support for binary data.
  *
- * @since 4.0.0
  * @category serialization
+ * @since 4.0.0
  */
 export const layerMsgPack: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(msgPack)

package/src/unstable/rpc/RpcServer.ts

@@ -1,4 +1,38 @@
 /**
+ * Server-side support for running RPCs defined in an `RpcGroup`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * **Handler 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
+ *   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
+ *   acknowledgement support wait for client acknowledgements between chunks to
+ *   provide back pressure
+ * - Fatal handler defects are sent as protocol defects by default; set
+ *   `disableFatalDefects` when defects should remain ordinary request exits
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -51,8 +85,11 @@ import type { InitialMessage } from "./RpcWorker.ts"
 import { withRun } from "./Utils.ts"
 
 /**
- * @since 4.0.0
+ * The decoded RPC server boundary, accepting client messages for a client id
+ * and allowing that client to be disconnected.
+ *
  * @category server
+ * @since 4.0.0
  */
 export interface RpcServer<A extends Rpc.Any> {
   readonly write: (clientId: number, message: FromClient<A>) => Effect.Effect<void>
@@ -60,8 +97,12 @@ export interface RpcServer<A extends Rpc.Any> {
 }
 
 /**
- * @since 4.0.0
+ * Creates an RPC server for an already-decoded message channel, running
+ * handlers for a group and sending decoded server responses through
+ * `onFromServer`.
+ *
  * @category server
+ * @since 4.0.0
  */
 export const makeNoSerialization: <Rpcs extends Rpc.Any>(
   group: RpcGroup.RpcGroup<Rpcs>,
@@ -457,8 +498,12 @@ const applyMiddleware = <A, E, R>(
 }
 
 /**
- * @since 4.0.0
+ * Runs an RPC server for a group using the current server `Protocol`, decoding
+ * requests, invoking handlers, encoding responses, and managing in-flight
+ * request lifetime.
+ *
  * @category server
+ * @since 4.0.0
  */
 export const make: <Rpcs extends Rpc.Any>(
   group: RpcGroup.RpcGroup<Rpcs>,
@@ -733,8 +778,11 @@ export const make: <Rpcs extends Rpc.Any>(
 })
 
 /**
- * @since 4.0.0
+ * Provides a scoped layer that starts an RPC server for a group using the
+ * current server `Protocol`.
+ *
  * @category server
+ * @since 4.0.0
  */
 export const layer = <Rpcs extends Rpc.Any>(
   group: RpcGroup.RpcGroup<Rpcs>,
@@ -760,8 +808,8 @@ export const layer = <Rpcs extends Rpc.Any>(
  * It defaults to using websockets for communication, but can be configured to
  * use HTTP.
  *
- * @since 4.0.0
  * @category protocol
+ * @since 4.0.0
  */
 export const layerHttp = <Rpcs extends Rpc.Any>(options: {
   readonly group: RpcGroup.RpcGroup<Rpcs>
@@ -790,8 +838,12 @@ export const layerHttp = <Rpcs extends Rpc.Any>(options: {
   )
 
 /**
- * @since 4.0.0
+ * Service interface for an RPC server transport, responsible for receiving
+ * encoded client messages, sending encoded responses, tracking clients, and
+ * declaring transport capabilities.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class Protocol extends Context.Service<
   Protocol,
@@ -814,14 +866,19 @@ export class Protocol extends Context.Service<
   }
 >()("effect/rpc/RpcServer/Protocol") {
   /**
+   * Creates a server protocol service from the supplied RPC implementation.
+   *
    * @since 4.0.0
    */
   static make = withRun<Protocol["Service"]>()
 }
 
 /**
- * @since 4.0.0
+ * Creates a server `Protocol` backed by the current `SocketServer`, accepting
+ * socket connections and routing decoded RPC messages.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolSocketServer = Effect.gen(function*() {
   const server = yield* SocketServer.SocketServer
@@ -835,8 +892,8 @@ export const makeProtocolSocketServer = Effect.gen(function*() {
 /**
  * A rpc protocol that uses `SocketServer` for communication.
  *
- * @since 4.0.0
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolSocketServer: Layer.Layer<
   Protocol,
@@ -845,8 +902,11 @@ export const layerProtocolSocketServer: Layer.Layer<
 > = Layer.effect(Protocol)(makeProtocolSocketServer)
 
 /**
- * @since 4.0.0
+ * Creates a websocket server `Protocol` together with an HTTP effect that
+ * upgrades the current request to a websocket and attaches it to the protocol.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolWithHttpEffectWebsocket: Effect.Effect<
   {
@@ -877,8 +937,11 @@ export const makeProtocolWithHttpEffectWebsocket: Effect.Effect<
 })
 
 /**
- * @since 4.0.0
+ * Creates a websocket server `Protocol` and registers its upgrade handler as a
+ * GET route on the current `HttpRouter`.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolWebsocket: (options: {
   readonly path: HttpRouter.PathInput
@@ -896,8 +959,8 @@ export const makeProtocolWebsocket: (options: {
 /**
  * A rpc protocol that uses websockets for communication.
  *
- * @since 4.0.0
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolWebsocket = (options: {
   readonly path: HttpRouter.PathInput
@@ -910,8 +973,12 @@ export const layerProtocolWebsocket = (options: {
 }
 
 /**
- * @since 4.0.0
+ * Creates an HTTP request/response server `Protocol` together with an HTTP
+ * effect that decodes the current request and streams or returns encoded RPC
+ * responses.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolWithHttpEffect: Effect.Effect<
   {
@@ -961,6 +1028,7 @@ export const makeProtocolWithHttpEffect: Effect.Effect<
     const id = clientId++
     const queue = yield* Queue.make<Uint8Array | FromServerEncoded, Cause.Done>()
     const parser = serialization.makeUnsafe()
+    const requestIds: Array<RequestId> = []
 
     const offer = (data: Uint8Array | string) =>
       typeof data === "string" ? Queue.offer(queue, encoder.encode(data)) : Queue.offer(queue, data)
@@ -993,8 +1061,6 @@ export const makeProtocolWithHttpEffect: Effect.Effect<
     clients.set(id, client)
     clientIds.add(id)
 
-    const requestIds: Array<RequestId> = []
-
     // @effect-diagnostics-next-line tryCatchInEffectGen:off
     try {
       const decoded = parser.decode(data) as ReadonlyArray<FromClientEncoded>
@@ -1075,8 +1141,11 @@ const mergeUint8Arrays = (arrays: ReadonlyArray<Uint8Array>) => {
 }
 
 /**
- * @since 4.0.0
+ * Creates an HTTP server `Protocol` and registers its request handler as a POST
+ * route on the current `HttpRouter`.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolHttp: (options: {
   readonly path: HttpRouter.PathInput
@@ -1092,10 +1161,11 @@ export const makeProtocolHttp: (options: {
 })
 
 /**
- * A rpc protocol that uses websockets for communication.
+ * Provides a server `Protocol` that uses HTTP POST requests for RPC
+ * communication.
  *
- * @since 4.0.0
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolHttp = (options: {
   readonly path: HttpRouter.PathInput
@@ -1104,8 +1174,11 @@ export const layerProtocolHttp = (options: {
 }
 
 /**
- * @since 4.0.0
+ * Starts an RPC server for a group and returns the HTTP request/response effect
+ * that serves the non-websocket HTTP RPC protocol.
+ *
  * @category http app
+ * @since 4.0.0
  */
 export const toHttpEffect: <Rpcs extends Rpc.Any>(
   group: RpcGroup.RpcGroup<Rpcs>,
@@ -1142,8 +1215,11 @@ export const toHttpEffect: <Rpcs extends Rpc.Any>(
 })
 
 /**
- * @since 4.0.0
+ * Starts an RPC server for a group and returns the HTTP effect that upgrades
+ * requests to the websocket RPC protocol.
+ *
  * @category http app
+ * @since 4.0.0
  */
 export const toHttpEffectWebsocket: <Rpcs extends Rpc.Any>(
   group: RpcGroup.RpcGroup<Rpcs>,
@@ -1180,10 +1256,11 @@ export const toHttpEffectWebsocket: <Rpcs extends Rpc.Any>(
 })
 
 /**
- * Create a protocol that uses the provided `Stream` and `Sink` for communication.
+ * Creates a server `Protocol` that reads RPC messages from `Stdio.stdin` and
+ * writes encoded responses to `Stdio.stdout`.
  *
- * @since 4.0.0
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolStdio = Effect.gen(function*() {
   const stdio = yield* Stdio
@@ -1240,10 +1317,11 @@ export const makeProtocolStdio = Effect.gen(function*() {
 })
 
 /**
- * Create a protocol that uses the provided `Stream` and `Sink` for communication.
+ * Provides a server `Protocol` that reads RPC messages from `Stdio.stdin` and
+ * writes encoded responses to `Stdio.stdout`.
  *
- * @since 4.0.0
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolStdio: Layer.Layer<
   Protocol,
@@ -1252,8 +1330,11 @@ export const layerProtocolStdio: Layer.Layer<
 > = Layer.effect(Protocol, makeProtocolStdio)
 
 /**
- * @since 4.0.0
+ * Creates a server `Protocol` backed by `WorkerRunnerPlatform`, routing worker
+ * messages to the RPC server and server responses back to workers.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolWorkerRunner: Effect.Effect<
   Protocol["Service"],
@@ -1308,8 +1389,10 @@ export const makeProtocolWorkerRunner: Effect.Effect<
 }))
 
 /**
- * @since 4.0.0
+ * Provides a server `Protocol` backed by the current `WorkerRunnerPlatform`.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolWorkerRunner: Layer.Layer<
   Protocol,

package/src/unstable/rpc/RpcTest.ts

@@ -1,4 +1,20 @@
 /**
+ * Utilities for testing RPC groups without opening a network transport.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -9,8 +25,11 @@ import type * as RpcGroup from "./RpcGroup.ts"
 import * as RpcServer from "./RpcServer.ts"
 
 /**
- * @since 4.0.0
+ * Creates an in-memory RPC client for a group, backed by the group's handlers
+ * from the environment and using the no-serialization test transport.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeClient: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>(
   group: RpcGroup.RpcGroup<Rpcs>,