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

package/src/unstable/rpc/RpcMessage.ts

@@ -1,4 +1,21 @@
 /**
+ * Defines the protocol message envelopes shared by unstable RPC clients,
+ * servers, and transports.
+ *
+ * This module is used when implementing or testing RPC transports, codecs, and
+ * protocol handlers. It separates decoded messages, which carry typed RPC tags,
+ * payloads, headers, exits, and branded request identifiers, from encoded
+ * messages, which are suitable for transport boundaries where request ids and
+ * payloads have already been serialized.
+ *
+ * Request identifiers are the correlation point for requests, response chunks,
+ * terminal exits, acknowledgements, and interrupts, so transports must preserve
+ * them across the encoded string form and the decoded branded form. Streaming
+ * responses can send one or more `Chunk` batches before a terminal `Exit`; use
+ * `Ack` messages only for transports that require backpressure, treat `Eof` as
+ * the end of client input, and reserve `Ping`/`Pong` for connection liveness
+ * rather than RPC completion.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -9,33 +26,45 @@ import type * as Rpc from "./Rpc.ts"
 import type { RpcClientError } from "./RpcClientError.ts"
 
 /**
- * @since 4.0.0
+ * Decoded messages that can be sent from an RPC client to a server.
+ *
  * @category request
+ * @since 4.0.0
  */
 export type FromClient<A extends Rpc.Any> = Request<A> | Ack | Interrupt | Eof
 
 /**
- * @since 4.0.0
+ * Transport-encoded messages that can be sent from an RPC client to a server.
+ *
  * @category request
+ * @since 4.0.0
  */
 export type FromClientEncoded = RequestEncoded | AckEncoded | InterruptEncoded | Ping | Eof
 
 /**
- * @since 4.0.0
+ * A branded request identifier used to correlate RPC requests, responses,
+ * chunks, acknowledgements, and interrupts.
+ *
  * @category request
+ * @since 4.0.0
  */
 export type RequestId = Branded<bigint, "~effect/rpc/RpcMessage/RequestId">
 
 /**
- * @since 4.0.0
+ * Converts a bigint or string request id into the branded `RequestId` type.
+ *
  * @category request
+ * @since 4.0.0
  */
 export const RequestId = (id: bigint | string): RequestId =>
   typeof id === "bigint" ? id as RequestId : BigInt(id) as RequestId
 
 /**
- * @since 4.0.0
+ * The transport-encoded RPC request envelope, including the string request id,
+ * RPC tag, encoded payload, headers, and optional trace context.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface RequestEncoded {
   readonly _tag: "Request"
@@ -49,8 +78,11 @@ export interface RequestEncoded {
 }
 
 /**
- * @since 4.0.0
+ * The decoded RPC request envelope for an RPC union, carrying a branded request
+ * id, typed RPC tag, decoded payload, headers, and optional trace context.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface Request<A extends Rpc.Any> {
   readonly _tag: "Request"
@@ -64,8 +96,10 @@ export interface Request<A extends Rpc.Any> {
 }
 
 /**
- * @since 4.0.0
+ * A decoded acknowledgement for a streamed RPC response chunk.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface Ack {
   readonly _tag: "Ack"
@@ -73,8 +107,11 @@ export interface Ack {
 }
 
 /**
- * @since 4.0.0
+ * A decoded request to interrupt an in-flight RPC, carrying the request id and
+ * interrupting fiber ids.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface Interrupt {
   readonly _tag: "Interrupt"
@@ -83,8 +120,10 @@ export interface Interrupt {
 }
 
 /**
- * @since 4.0.0
+ * The transport-encoded acknowledgement for a streamed RPC response chunk.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface AckEncoded {
   readonly _tag: "Ack"
@@ -92,8 +131,10 @@ export interface AckEncoded {
 }
 
 /**
- * @since 4.0.0
+ * The transport-encoded request to interrupt an in-flight RPC.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface InterruptEncoded {
   readonly _tag: "Interrupt"
@@ -101,36 +142,48 @@ export interface InterruptEncoded {
 }
 
 /**
- * @since 4.0.0
+ * A client-to-server message indicating that the client has finished sending
+ * input for the current connection or request batch.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface Eof {
   readonly _tag: "Eof"
 }
 
 /**
- * @since 4.0.0
+ * A client-to-server keepalive message used by protocols that monitor
+ * connection liveness.
+ *
  * @category request
+ * @since 4.0.0
  */
 export interface Ping {
   readonly _tag: "Ping"
 }
 
 /**
- * @since 4.0.0
+ * The reusable `Eof` message value.
+ *
  * @category request
+ * @since 4.0.0
  */
 export const constEof: Eof = { _tag: "Eof" }
 
 /**
- * @since 4.0.0
+ * The reusable `Ping` message value.
+ *
  * @category request
+ * @since 4.0.0
  */
 export const constPing: Ping = { _tag: "Ping" }
 
 /**
- * @since 4.0.0
+ * Decoded messages that can be sent from an RPC server to a client.
+ *
  * @category response
+ * @since 4.0.0
  */
 export type FromServer<A extends Rpc.Any> =
   | ResponseChunk<A>
@@ -139,8 +192,10 @@ export type FromServer<A extends Rpc.Any> =
   | ClientEnd
 
 /**
- * @since 4.0.0
+ * Transport-encoded messages that can be sent from an RPC server to a client.
+ *
  * @category response
+ * @since 4.0.0
  */
 export type FromServerEncoded =
   | ResponseChunkEncoded
@@ -150,26 +205,35 @@ export type FromServerEncoded =
   | ClientProtocolError
 
 /**
- * @since 4.0.0
+ * The brand identifier used by the `ResponseId` type.
+ *
  * @category response
+ * @since 4.0.0
  */
 export const ResponseIdTypeId = "~effect//rpc/RpcServer/ResponseId"
 
 /**
- * @since 4.0.0
+ * The literal type of the `ResponseId` brand identifier.
+ *
  * @category response
+ * @since 4.0.0
  */
 export type ResponseIdTypeId = typeof ResponseIdTypeId
 
 /**
- * @since 4.0.0
+ * A branded numeric identifier for server responses.
+ *
  * @category response
+ * @since 4.0.0
  */
 export type ResponseId = Branded<number, ResponseIdTypeId>
 
 /**
- * @since 4.0.0
+ * The transport-encoded response message containing a non-empty batch of stream
+ * chunk values for a request.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ResponseChunkEncoded {
   readonly _tag: "Chunk"
@@ -178,8 +242,11 @@ export interface ResponseChunkEncoded {
 }
 
 /**
- * @since 4.0.0
+ * The decoded response message containing a non-empty batch of stream chunk
+ * values for a specific client and request.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ResponseChunk<A extends Rpc.Any> {
   readonly _tag: "Chunk"
@@ -189,8 +256,11 @@ export interface ResponseChunk<A extends Rpc.Any> {
 }
 
 /**
- * @since 4.0.0
+ * The transport representation of an RPC `Exit`, encoding success values or a
+ * failure cause made of failures, defects, and interrupts.
+ *
  * @category response
+ * @since 4.0.0
  */
 export type ExitEncoded<A, E> = {
   readonly _tag: "Success"
@@ -212,8 +282,11 @@ export type ExitEncoded<A, E> = {
 }
 
 /**
- * @since 4.0.0
+ * The transport-encoded terminal response for a request, carrying the encoded
+ * `Exit`.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ResponseExitEncoded {
   readonly _tag: "Exit"
@@ -222,8 +295,11 @@ export interface ResponseExitEncoded {
 }
 
 /**
- * @since 4.0.0
+ * A server-to-client protocol message reporting a client protocol error to all
+ * affected in-flight requests.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ClientProtocolError {
   readonly _tag: "ClientProtocolError"
@@ -231,8 +307,11 @@ export interface ClientProtocolError {
 }
 
 /**
- * @since 4.0.0
+ * The decoded terminal response for a request, carrying the typed `Rpc.Exit`
+ * for the RPC.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ResponseExit<A extends Rpc.Any> {
   readonly _tag: "Exit"
@@ -242,8 +321,11 @@ export interface ResponseExit<A extends Rpc.Any> {
 }
 
 /**
- * @since 4.0.0
+ * The transport-encoded server defect message used for protocol-level defects
+ * that affect the client connection.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ResponseDefectEncoded {
   readonly _tag: "Defect"
@@ -253,8 +335,11 @@ export interface ResponseDefectEncoded {
 const encodeDefect = Schema.encodeSync(Schema.Defect)
 
 /**
- * @since 4.0.0
+ * Creates an encoded terminal response for a request whose exit is a defect
+ * encoded with `Schema.Defect`.
+ *
  * @category response
+ * @since 4.0.0
  */
 export const ResponseExitDieEncoded = (options: {
   readonly requestId: RequestId
@@ -272,8 +357,11 @@ export const ResponseExitDieEncoded = (options: {
 })
 
 /**
- * @since 4.0.0
+ * Creates a transport-encoded defect response by encoding the input with
+ * `Schema.Defect`.
+ *
  * @category response
+ * @since 4.0.0
  */
 export const ResponseDefectEncoded = (input: unknown): ResponseDefectEncoded => ({
   _tag: "Defect",
@@ -281,8 +369,10 @@ export const ResponseDefectEncoded = (input: unknown): ResponseDefectEncoded =>
 })
 
 /**
- * @since 4.0.0
+ * The decoded server defect message for a client connection.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ResponseDefect {
   readonly _tag: "Defect"
@@ -291,8 +381,10 @@ export interface ResponseDefect {
 }
 
 /**
- * @since 4.0.0
+ * A server message indicating that the client connection has ended.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface ClientEnd {
   readonly _tag: "ClientEnd"
@@ -300,15 +392,19 @@ export interface ClientEnd {
 }
 
 /**
- * @since 4.0.0
+ * A server-to-client keepalive response to a `Ping` message.
+ *
  * @category response
+ * @since 4.0.0
  */
 export interface Pong {
   readonly _tag: "Pong"
 }
 
 /**
- * @since 4.0.0
+ * The reusable `Pong` message value.
+ *
  * @category response
+ * @since 4.0.0
  */
 export const constPong: Pong = { _tag: "Pong" }

package/src/unstable/rpc/RpcMiddleware.ts

@@ -1,4 +1,30 @@
 /**
+ * The `RpcMiddleware` module defines middleware services that can wrap RPC
+ * handler execution on the server and request execution in generated clients.
+ *
+ * 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`.
+ *
+ * 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.
+ *
+ * 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
+ * client-side call error channel, while the middleware `error` schema is shared
+ * with server failures.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -12,20 +38,28 @@ import type * as Rpc from "./Rpc.ts"
 import type { Request, RequestId } from "./RpcMessage.ts"
 
 /**
- * @since 4.0.0
+ * The literal type id used to identify RPC middleware service classes.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~effect/rpc/RpcMiddleware"
 
 /**
- * @since 4.0.0
+ * The runtime type id used to attach and inspect RPC middleware metadata.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/rpc/RpcMiddleware"
 
 /**
- * @since 4.0.0
+ * The server-side RPC middleware function shape, wrapping a handler effect with
+ * access to request metadata and translating provided services into required
+ * services.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface RpcMiddleware<Provides, E, Requires> {
   (
@@ -41,16 +75,22 @@ export interface RpcMiddleware<Provides, E, Requires> {
 }
 
 /**
- * @since 4.0.0
+ * Marker success type used by RPC middleware to represent successful completion
+ * without exposing the handler's concrete success value.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface SuccessValue {
   readonly _: unique symbol
 }
 
 /**
- * @since 4.0.0
+ * The client-side RPC middleware function shape, allowing outgoing requests to
+ * be inspected or modified before calling `next`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface RpcMiddlewareClient<E, CE, R> {
   (options: {
@@ -61,8 +101,11 @@ export interface RpcMiddlewareClient<E, CE, R> {
 }
 
 /**
- * @since 4.0.0
+ * Marker service requirement indicating that a middleware has a client-side
+ * implementation available for an RPC client.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ForClient<Id> {
   readonly _: unique symbol
@@ -70,8 +113,11 @@ export interface ForClient<Id> {
 }
 
 /**
- * @since 4.0.0
+ * An erased server-side RPC middleware function, useful when the concrete
+ * provided services, errors, and requirements are not needed.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any {
   (
@@ -87,8 +133,11 @@ export interface Any {
 }
 
 /**
- * @since 4.0.0
+ * A type-level carrier for RPC middleware metadata, including provided
+ * services, required services, error schema, and client error type.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyId {
   readonly [TypeId]: {
@@ -100,8 +149,11 @@ export interface AnyId {
 }
 
 /**
- * @since 4.0.0
+ * The `Context.Service` class shape created for an RPC middleware, including
+ * its error schema, service metadata, and client-side requirement marker.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ServiceClass<
   Self,
@@ -127,52 +179,69 @@ export interface ServiceClass<
 }
 
 /**
- * @since 4.0.0
+ * Extracts the services provided by an RPC middleware.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: infer P } } ? P : never
 
 /**
- * @since 4.0.0
+ * Extracts the services required by an RPC middleware.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: infer R } } ? R : never
 
 /**
- * @since 4.0.0
+ * Applies a middleware's service transformation to an RPC environment by
+ * removing services the middleware provides and adding services it requires.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ApplyServices<A, R> = Exclude<R, Provides<A>> | Requires<A>
 
 /**
- * @since 4.0.0
+ * Extracts the error schema associated with an RPC middleware.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: infer E } }
   ? E extends Schema.Top ? E : never
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the decoded error type produced by an RPC middleware.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Error<A> = ErrorSchema<A>["Type"]
 
 /**
- * @since 4.0.0
+ * Extracts the encoding services required by a middleware's error schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
 
 /**
- * @since 4.0.0
+ * Extracts the decoding services required by a middleware's error schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
 
 /**
- * @since 4.0.0
+ * An erased RPC middleware context key carrying middleware metadata.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyService extends Context.Key<any, any> {
   readonly [TypeId]: typeof TypeId
@@ -182,8 +251,11 @@ export interface AnyService extends Context.Key<any, any> {
 }
 
 /**
- * @since 4.0.0
+ * An erased RPC middleware context key whose service value is a server-side
+ * middleware function.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyServiceWithProps extends Context.Key<any, RpcMiddleware<any, any, any>> {
   readonly [TypeId]: typeof TypeId
@@ -193,8 +265,12 @@ export interface AnyServiceWithProps extends Context.Key<any, RpcMiddleware<any,
 }
 
 /**
- * @since 4.0.0
+ * Creates a typed RPC middleware service class, with optional service
+ * requirements, provided services, error schema, and client-side requirement
+ * metadata.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export const Service = <
   Self,
@@ -255,8 +331,12 @@ export const Service = <
 }
 
 /**
- * @since 4.0.0
+ * Provides the client-side implementation for an RPC middleware service,
+ * capturing the layer's environment and merging it into each middleware
+ * invocation.
+ *
  * @category client
+ * @since 4.0.0
  */
 export const layerClient = <Id extends AnyId, S, R, EX = never, RX = never>(
   tag: Context.Key<Id, S>,