effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/cluster/EntityProxy.ts

@@ -1,4 +1,26 @@
 /**
+ * The `EntityProxy` module derives external RPC and HTTP API surfaces from a
+ * clustered {@link Entity.Entity}. It is used when callers should communicate
+ * with entities through ordinary RPC clients or HTTP routes while the cluster
+ * runtime keeps responsibility for locating, routing, and delivering messages
+ * to the entity instance identified by `entityId`.
+ *
+ * **Common tasks**
+ *
+ * - Derive an `RpcGroup` from an entity with {@link toRpcGroup}
+ * - Derive an `HttpApiGroup` from an entity with {@link toHttpApiGroup}
+ * - Expose both request/response calls and discard variants for fire-and-forget
+ *   delivery
+ *
+ * **Gotchas**
+ *
+ * - Proxy RPC payloads wrap the original RPC payload with an `entityId`; HTTP
+ *   endpoints place the same identifier in the route path.
+ * - Generated RPC names are prefixed with the entity type, while HTTP endpoint
+ *   paths are based on lower-cased RPC tags.
+ * - Proxy errors include cluster delivery errors such as mailbox saturation,
+ *   duplicate in-flight messages, and persistence failures.
+ *
  * @since 4.0.0
  */
 import * as Schema from "../../Schema.ts"
@@ -19,14 +41,11 @@ const clientErrors = [
 /**
  * Derives an `RpcGroup` from an `Entity`.
  *
+ * **Example** (Deriving RPC endpoints from an entity)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
- * import {
- *   ClusterSchema,
- *   Entity,
- *   EntityProxy,
- *   EntityProxyServer
- * } from "effect/unstable/cluster"
+ * import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
  * import { Rpc, RpcServer } from "effect/unstable/rpc"
  *
  * export const Counter = Entity.make("Counter", [
@@ -47,8 +66,8 @@ const clientErrors = [
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
   entity: Entity.Entity<Type, Rpcs>
@@ -82,6 +101,12 @@ export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
 }
 
 /**
+ * Type-level conversion used by `toRpcGroup`.
+ *
+ * For each entity RPC it creates a prefixed request RPC and a discard RPC whose
+ * payload includes `entityId`, and whose errors include cluster client errors.
+ *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertRpcs<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs extends Rpc.Rpc<
@@ -131,14 +156,11 @@ const entityIdPath = {
 /**
  * Derives an `HttpApiGroup` from an `Entity`.
  *
+ * **Example** (Deriving HTTP API endpoints from an entity)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
- * import {
- *   ClusterSchema,
- *   Entity,
- *   EntityProxy,
- *   EntityProxyServer
- * } from "effect/unstable/cluster"
+ * import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
  * import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi"
  * import { Rpc } from "effect/unstable/rpc"
  *
@@ -166,8 +188,8 @@ const entityIdPath = {
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const toHttpApiGroup = <const Name extends string, Type extends string, Rpcs extends Rpc.Any>(
   name: Name,
@@ -205,6 +227,12 @@ const tagToPath = (tag: string): string =>
     .toLowerCase()
 
 /**
+ * Type-level conversion used by `toHttpApiGroup`.
+ *
+ * For each entity RPC it creates a POST endpoint at `/<tag>/:entityId` and a
+ * discard endpoint at `/<tag>/:entityId/discard`, including cluster client errors.
+ *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertHttpApi<Rpcs extends Rpc.Any> = Rpcs extends Rpc.Rpc<

package/src/unstable/cluster/EntityProxyServer.ts

@@ -1,4 +1,25 @@
 /**
+ * The `EntityProxyServer` module provides server-side layers for exposing
+ * clustered entities through proxy APIs. It connects proxy requests to an
+ * entity client, extracts the target `entityId`, and forwards the payload to
+ * the matching entity RPC method.
+ *
+ * **Common tasks**
+ *
+ * - Serve an entity proxy over an HTTP API group with {@link layerHttpApi}
+ * - Serve the RPC group produced by an entity proxy with {@link layerRpcHandlers}
+ * - Route both normal calls and discard calls to the same underlying entity
+ *   method
+ *
+ * **Gotchas**
+ *
+ * - HTTP proxy endpoints expect the `entityId` path parameter to identify the
+ *   target entity instance
+ * - RPC proxy handlers use tags prefixed with the entity type, matching the
+ *   group generated by `EntityProxy.toRpcGroup`
+ * - Both layers require `Sharding` and the entity RPC server services in the
+ *   environment so requests can be routed to the owning shard
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -12,8 +33,14 @@ import type * as Entity from "./Entity.ts"
 import type { Sharding } from "./Sharding.ts"
 
 /**
+ * Creates HTTP API handlers for an entity proxy group.
+ *
+ * Each generated endpoint reads the `entityId` path parameter and forwards the
+ * request payload to the corresponding entity client method, including discard
+ * endpoints.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerHttpApi = <
   ApiId extends string,
@@ -37,23 +64,23 @@ export const layerHttpApi = <
         handlers = handlers
           .handle(
             parentRpc._tag as any,
-            (({ path, payload }: { path: { entityId: string }; payload: any }) =>
-              (client(path.entityId) as any as Record<string, (p: any) => Effect.Effect<any>>)[parentRpc._tag](
+            (({ params, payload }: { params: { entityId: string }; payload: any }) =>
+              (client(params.entityId) as any as Record<string, (p: any) => Effect.Effect<any>>)[parentRpc._tag](
                 payload
               ).pipe(
                 Effect.tapDefect(Effect.logError),
                 Effect.annotateLogs({
                   module: "EntityProxyServer",
                   entity: entity.type,
-                  entityId: path.entityId,
+                  entityId: params.entityId,
                   method: parentRpc._tag
                 })
               )) as any
           )
           .handle(
             `${parentRpc._tag}Discard` as any,
-            (({ path, payload }: { path: { entityId: string }; payload: any }) =>
-              (client(path.entityId) as any as Record<string, (p: any, o: {}) => Effect.Effect<any>>)[parentRpc._tag](
+            (({ params, payload }: { params: { entityId: string }; payload: any }) =>
+              (client(params.entityId) as any as Record<string, (p: any, o: {}) => Effect.Effect<any>>)[parentRpc._tag](
                 payload,
                 { discard: true }
               ).pipe(
@@ -61,7 +88,7 @@ export const layerHttpApi = <
                 Effect.annotateLogs({
                   module: "EntityProxyServer",
                   entity: entity.type,
-                  entityId: path.entityId,
+                  entityId: params.entityId,
                   method: `${parentRpc._tag}Discard`
                 })
               )) as any
@@ -72,8 +99,13 @@ export const layerHttpApi = <
   )
 
 /**
+ * Creates RPC handlers for the group produced by `EntityProxy.toRpcGroup`.
+ *
+ * The handlers forward each prefixed proxy RPC to the target entity client using
+ * the `entityId` embedded in the proxy payload.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerRpcHandlers = <
   const Type extends string,
@@ -105,6 +137,11 @@ export const layerRpcHandlers = <
   }))
 
 /**
+ * Union of RPC handler services required to serve the proxy RPCs for an entity.
+ *
+ * Includes both the normal prefixed RPC handler and its discard variant.
+ *
+ * @category services
  * @since 4.0.0
  */
 export type RpcHandlers<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs extends Rpc.Rpc<

package/src/unstable/cluster/EntityResource.ts

@@ -1,4 +1,27 @@
 /**
+ * The `EntityResource` module provides helpers for acquiring resources inside a
+ * cluster entity and keeping them available across entity restarts. It is useful
+ * for long-lived resources tied to an entity address, such as external
+ * processes, network clients, Kubernetes Pods, or other handles that should not
+ * be torn down during routine shard movement.
+ *
+ * **Common tasks**
+ *
+ * - Create a reusable entity-scoped resource with {@link make}
+ * - Keep an entity alive while the resource is acquired
+ * - Explicitly release the resource with `EntityResource.close`
+ * - Attach cleanup work to the resource close scope with {@link CloseScope}
+ * - Create and manage a Kubernetes Pod resource with {@link makeK8sPod}
+ *
+ * **Lifecycle gotchas**
+ *
+ * - Resources are retained by an `RcRef` and are only fully released after
+ *   `idleTimeToLive` expires or `close` is called
+ * - The default idle time to live is infinite, so resources remain alive until
+ *   explicitly closed
+ * - `CloseScope` is separate from the caller scope and is not closed by entity
+ *   restarts, shard movement, or node shutdown finalization
+ *
  * @since 4.0.0
  */
 import type * as v1 from "kubernetes-types/core/v1.d.ts"
@@ -13,20 +36,29 @@ import * as K8sHttpClient from "./K8sHttpClient.ts"
 import type { Sharding } from "./Sharding.ts"
 
 /**
- * @since 4.0.0
+ * Type identifier used to brand `EntityResource` values.
+ *
  * @category Type ids
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/cluster/EntityResource"
 
 /**
- * @since 4.0.0
+ * Literal type of the `EntityResource` type identifier.
+ *
  * @category Type ids
+ * @since 4.0.0
  */
 export type TypeId = "~effect/cluster/EntityResource"
 
 /**
+ * A resource acquired inside a cluster entity and kept alive across restarts.
+ *
+ * `get` acquires or reuses the resource in the caller's scope, while `close`
+ * invalidates it so its close scope can be released.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface EntityResource<out A, out E = never> {
   readonly [TypeId]: TypeId
@@ -39,8 +71,8 @@ export interface EntityResource<out A, out E = never> {
  *
  * It is not closed during restarts, due to shard movement or node shutdowns.
  *
- * @since 4.0.0
  * @category Scope
+ * @since 4.0.0
  */
 export class CloseScope extends Context.Service<
   CloseScope,
@@ -57,8 +89,8 @@ export class CloseScope extends Context.Service<
  * By default, the `idleTimeToLive` is infinite, meaning the resource will only
  * be released when `close` is called.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make: <A, E, R>(options: {
   readonly acquire: Effect.Effect<A, E, R>
@@ -110,8 +142,13 @@ export const make: <A, E, R>(options: {
 })
 
 /**
- * @since 4.0.0
+ * Creates an `EntityResource` backed by a Kubernetes Pod.
+ *
+ * The pod is created and waited on through `K8sHttpClient`, and is kept alive
+ * until the resource is closed or its idle time to live expires.
+ *
  * @category Kubernetes
+ * @since 4.0.0
  */
 export const makeK8sPod: (
   spec: v1.Pod,

package/src/unstable/cluster/EntityType.ts

@@ -1,22 +1,46 @@
 /**
+ * The `EntityType` module defines the branded string used to identify a kind of
+ * entity in an Effect cluster. Entity type names are part of the cluster routing
+ * identity: they distinguish one family of entities from another before an
+ * individual entity id is considered.
+ *
+ * **Common tasks**
+ *
+ * - Declare the stable name for an entity family handled by a cluster service
+ * - Brand a string literal as an {@link EntityType} with {@link make}
+ * - Validate or encode entity type names with the {@link EntityType} schema
+ *
+ * **Gotchas**
+ *
+ * - Entity type names should be stable and unique within the cluster because
+ *   changing them changes where entity messages are routed
+ * - The entity type name identifies the entity family, not a specific entity
+ *   instance; combine it with the entity id at the call site that routes work
+ *
  * @since 4.0.0
  */
 import * as Schema from "../../Schema.ts"
 
 /**
- * @since 4.0.0
+ * Schema for branded string names that identify entity types in the cluster.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const EntityType = Schema.String.pipe(Schema.brand("~effect/cluster/EntityType"))
 
 /**
- * @since 4.0.0
+ * Branded string type representing an entity type name.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type EntityType = typeof EntityType.Type
 
 /**
- * @since 4.0.0
+ * Brands a string as an `EntityType`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (value: string): EntityType => value as EntityType

package/src/unstable/cluster/Envelope.ts

@@ -1,4 +1,27 @@
 /**
+ * The `Envelope` module defines the transport messages exchanged by Effect
+ * cluster entities while processing RPC requests. Envelopes wrap decoded
+ * request payloads with routing metadata, trace context, and request ids, and
+ * also model delivery-control messages such as streamed-reply acknowledgements
+ * and request interrupts.
+ *
+ * **Common use cases**
+ *
+ * - Construct a runtime request envelope with {@link makeRequest}
+ * - Decode or encode envelopes crossing a network or durable queue with {@link PartialJson}
+ * - Batch encoded envelopes with {@link PartialArray}
+ * - Detect envelope values at runtime with {@link isEnvelope}
+ * - Build storage keys for keyed request payloads with {@link primaryKey}
+ *
+ * **Serialization and delivery notes**
+ *
+ * Request envelopes are decoded in two phases: the envelope metadata is parsed
+ * first, while the RPC payload remains `unknown` until the receiving side knows
+ * the target RPC schema. Snowflake identifiers are encoded as strings for JSON
+ * transport, and acknowledgement / interrupt envelopes carry the original
+ * request id so delivery protocols can correlate control messages with the
+ * in-flight request.
+ *
  * @since 4.0.0
  */
 import * as Predicate from "../../Predicate.ts"
@@ -12,37 +35,55 @@ import { EntityAddress } from "./EntityAddress.ts"
 import { type Snowflake, SnowflakeFromBigInt } from "./Snowflake.ts"
 
 /**
+ * Type identifier used to mark runtime cluster envelope values.
+ *
+ * @category type IDs
  * @since 4.0.0
- * @category Type IDs
  */
 export const TypeId = "~effect/cluster/Envelope"
 
 /**
- * @since 4.0.0
+ * Union of cluster envelopes exchanged for an RPC request.
+ *
+ * An envelope is either a request, an acknowledgement for a streamed reply chunk,
+ * or an interrupt signal.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Envelope<R extends Rpc.Any> = Request<R> | AckChunk | Interrupt
 
 /**
- * @since 4.0.0
+ * JSON-serializable form of a cluster envelope.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Encoded = PartialRequestEncoded | AckChunkEncoded | InterruptEncoded
 
 /**
+ * Helper types associated with cluster envelopes.
+ *
  * @since 4.0.0
  */
 export declare namespace Envelope {
   /**
-   * @since 4.0.0
+   * Envelope type for any RPC protocol.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type Any = Envelope<any>
 }
 
 /**
- * @since 4.0.0
+ * Runtime envelope for an RPC request addressed to a specific entity.
+ *
+ * It carries the request ID, entity address, RPC tag, decoded payload, request
+ * headers, and optional tracing context.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Request<in out Rpc extends Rpc.Any> {
   readonly [TypeId]: typeof TypeId
@@ -58,8 +99,13 @@ export interface Request<in out Rpc extends Rpc.Any> {
 }
 
 /**
- * @since 4.0.0
+ * Schema for a request envelope before its RPC payload has been decoded.
+ *
+ * The envelope metadata is decoded, while the payload remains `unknown` until it
+ * is decoded with the target RPC payload schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class PartialRequest extends Schema.Opaque<PartialRequest>()(Schema.Struct({
   _tag: Schema.tag("Request"),
@@ -74,8 +120,13 @@ export class PartialRequest extends Schema.Opaque<PartialRequest>()(Schema.Struc
 })) {}
 
 /**
- * @since 4.0.0
+ * Serialized JSON shape of a request envelope.
+ *
+ * Identifiers are encoded as strings and the RPC payload remains unknown until
+ * decoded with the RPC schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface PartialRequestEncoded {
   readonly _tag: "Request"
@@ -97,8 +148,12 @@ export interface PartialRequestEncoded {
 }
 
 /**
- * @since 4.0.0
+ * Envelope acknowledging receipt of a streamed reply chunk for a request.
+ *
+ * The `replyId` identifies the chunk reply that has been received.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class AckChunk extends Schema.Class<AckChunk>("effect/cluster/Envelope/AckChunk")({
   _tag: Schema.tag("AckChunk"),
@@ -108,11 +163,15 @@ export class AckChunk extends Schema.Class<AckChunk>("effect/cluster/Envelope/Ac
   replyId: SnowflakeFromBigInt
 }) {
   /**
+   * Marks this value as a cluster envelope for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Returns a copy of this acknowledgement associated with the supplied request id.
+   *
    * @since 4.0.0
    */
   withRequestId(requestId: Snowflake): AckChunk {
@@ -124,8 +183,10 @@ export class AckChunk extends Schema.Class<AckChunk>("effect/cluster/Envelope/Ac
 }
 
 /**
- * @since 4.0.0
+ * Serialized JSON shape of an `AckChunk` envelope.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AckChunkEncoded {
   readonly _tag: "AckChunk"
@@ -143,8 +204,10 @@ export interface AckChunkEncoded {
 }
 
 /**
- * @since 4.0.0
+ * Envelope used to interrupt an in-flight entity request.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class Interrupt extends Schema.Class<Interrupt>("effect/cluster/Envelope/Interrupt")({
   _tag: Schema.tag("Interrupt"),
@@ -153,11 +216,15 @@ export class Interrupt extends Schema.Class<Interrupt>("effect/cluster/Envelope/
   requestId: SnowflakeFromBigInt
 }) {
   /**
+   * Marks this value as a cluster envelope for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Returns a copy of this interrupt associated with the supplied request id.
+   *
    * @since 4.0.0
    */
   withRequestId(requestId: Snowflake): Interrupt {
@@ -169,8 +236,10 @@ export class Interrupt extends Schema.Class<Interrupt>("effect/cluster/Envelope/
 }
 
 /**
- * @since 4.0.0
+ * Serialized JSON shape of an `Interrupt` envelope.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface InterruptEncoded {
   readonly _tag: "Interrupt"
@@ -187,8 +256,12 @@ export interface InterruptEncoded {
 }
 
 /**
- * @since 4.0.0
+ * Schema union for partially decoded cluster envelopes.
+ *
+ * It accepts `PartialRequest`, `AckChunk`, and `Interrupt` envelope values.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const Partial: Schema.Union<
   readonly [
@@ -199,14 +272,18 @@ export const Partial: Schema.Union<
 > = Schema.Union([PartialRequest, AckChunk, Interrupt])
 
 /**
- * @since 4.0.0
+ * Decoded value type produced by the `Partial` envelope schema.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export type Partial = typeof Partial.Type
 
 /**
- * @since 4.0.0
+ * JSON codec for partial cluster envelopes.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const PartialJson: Schema.Codec<
   AckChunk | Interrupt | PartialRequest,
@@ -214,33 +291,47 @@ export const PartialJson: Schema.Codec<
 > = Schema.toCodecJson(Partial) as any
 
 /**
- * @since 4.0.0
+ * Mutable array schema for JSON-encoded partial cluster envelopes.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const PartialArray: Schema.mutable<
   Schema.$Array<Schema.Codec<AckChunk | Interrupt | PartialRequest, Encoded>>
 > = Schema.mutable(Schema.Array(PartialJson))
 
 /**
+ * Helper types associated with request envelopes.
+ *
  * @since 4.0.0
  */
 export declare namespace Request {
   /**
-   * @since 4.0.0
+   * Request envelope type for any RPC protocol.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type Any = Request<any>
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when the supplied value is a runtime cluster envelope.
+ *
+ * The check is based on the envelope type identifier.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isEnvelope = (u: unknown): u is Envelope<any> => Predicate.hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Constructs a runtime request envelope and attaches the envelope type identifier.
+ *
+ * Tracing fields are included only when a `traceId` is provided.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeRequest = <Rpc extends Rpc.Any>(
   options: {
@@ -271,16 +362,21 @@ export const makeRequest = <Rpc extends Rpc.Any>(
 })
 
 /**
- * @since 4.0.0
+ * Schema declaration that recognizes runtime `Envelope` values by their type
+ * identifier.
+ *
  * @category serialization / deserialization
+ * @since 4.0.0
  */
 export const Envelope = Schema.declare(isEnvelope, {
   identifier: "Envelope"
 })
 
 /**
- * @since 4.0.0
+ * Schema declaration that recognizes runtime request envelopes.
+ *
  * @category serialization / deserialization
+ * @since 4.0.0
  */
 export const Request = Schema.declare(
   (u): u is Request.Any => isEnvelope(u) && u._tag === "Request",
@@ -288,8 +384,11 @@ export const Request = Schema.declare(
 )
 
 /**
- * @since 4.0.0
+ * Transformation that decodes plain request data with `makeRequest` and encodes
+ * request envelopes back to their raw representation.
+ *
  * @category serialization / deserialization
+ * @since 4.0.0
  */
 export const RequestTransform: Transformation.Transformation<
   Request.Any,
@@ -300,8 +399,11 @@ export const RequestTransform: Transformation.Transformation<
 })
 
 /**
- * @since 4.0.0
+ * Returns the storage primary key for a request envelope whose payload has a
+ * primary key, or `null` when the envelope is not a keyed request.
+ *
  * @category primary key
+ * @since 4.0.0
  */
 export const primaryKey = <R extends Rpc.Any>(envelope: Envelope<R>): string | null => {
   if (envelope._tag !== "Request" || !PrimaryKey.isPrimaryKey(envelope.payload)) {
@@ -315,8 +417,11 @@ export const primaryKey = <R extends Rpc.Any>(envelope: Envelope<R>): string | n
 }
 
 /**
- * @since 4.0.0
+ * Builds a storage primary-key string from an entity address, RPC tag, and
+ * payload primary-key ID.
+ *
  * @category primary key
+ * @since 4.0.0
  */
 export const primaryKeyByAddress = (options: {
   readonly address: EntityAddress