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

package/src/unstable/cluster/Entity.ts

@@ -1,4 +1,36 @@
 /**
+ * The `Entity` module defines sharded, addressable actors for Effect Cluster.
+ * An entity type pairs a stable entity name with an RPC protocol and describes
+ * how requests for individual entity ids are routed to shard groups and
+ * runners.
+ *
+ * **Mental model**
+ *
+ * - An `Entity` is the cluster-facing definition for one logical actor type
+ * - Each entity id maps deterministically to a shard group and shard id
+ * - Clients are created per entity id and send typed RPC messages through the
+ *   cluster sharding layer
+ * - Server layers register handlers or mailbox processors for the entity type
+ *
+ * **Common tasks**
+ *
+ * - Define an entity protocol with RPCs and create an entity with {@link make}
+ * - Send messages to a specific entity id with {@link Entity.client}
+ * - Register typed RPC handlers with {@link Entity.toLayer}
+ * - Process envelopes directly with {@link Entity.toLayerQueue}
+ * - Access the current entity or runner address with {@link CurrentAddress} and
+ *   {@link CurrentRunnerAddress}
+ *
+ * **Gotchas**
+ *
+ * - Entity ids are part of routing: changing id formats can move work to
+ *   different shards
+ * - Entity type names should be stable and unique within a cluster deployment
+ * - Mailbox capacity and concurrency determine back pressure and duplicate
+ *   processing behavior
+ * - Persistence, mailbox, and already-processing failures are surfaced through
+ *   the generated clients
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -44,8 +76,13 @@ import * as Snowflake from "./Snowflake.ts"
 const TypeId = "~effect/cluster/Entity"
 
 /**
- * @since 4.0.0
+ * Represents a cluster entity type and the RPC protocol it can handle.
+ *
+ * An entity defines how ids map to shard groups, exposes a sharded client, and
+ * can be registered as a layer using RPC handlers or a mailbox queue.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Entity<
   in out Type extends string,
@@ -179,14 +216,23 @@ export interface Entity<
   >
 }
 /**
- * @since 4.0.0
+ * Type alias for any cluster `Entity`, regardless of entity type or RPC
+ * protocol.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Any = Entity<string, Rpc.Any>
 
 /**
- * @since 4.0.0
+ * Maps each RPC in an entity protocol to the handler function expected by
+ * `Entity.toLayer`.
+ *
+ * Each handler receives the entity request envelope for that RPC and returns the
+ * RPC result or a supported RPC wrapper.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HandlersFrom<Rpc extends Rpc.Any> = {
   readonly [Current in Rpc as Current["_tag"]]: (
@@ -195,8 +241,12 @@ export type HandlersFrom<Rpc extends Rpc.Any> = {
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when the supplied value is a cluster `Entity`.
+ *
+ * The check is based on the internal entity type identifier.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isEntity = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
 
@@ -221,10 +271,10 @@ const Proto = {
     return fromRpcGroup(this.type, this.protocol.annotateRpcsMerge(annotations))
   },
   getShardId(this: Entity<string, any>, entityId: EntityId) {
-    return Effect.map(shardingTag.asEffect(), (sharding) => sharding.getShardId(entityId, this.getShardGroup(entityId)))
+    return Effect.map(shardingTag, (sharding) => sharding.getShardId(entityId, this.getShardGroup(entityId)))
   },
   get client() {
-    return shardingTag.asEffect().pipe(
+    return shardingTag.pipe(
       Effect.flatMap((sharding) => sharding.makeClient(this as any))
     )
   },
@@ -253,7 +303,7 @@ const Proto = {
     | Rpc.Middleware<Rpcs>
     | Sharding
   > {
-    return shardingTag.asEffect().pipe(
+    return shardingTag.pipe(
       Effect.flatMap((sharding) =>
         sharding.registerEntity(
           this,
@@ -362,8 +412,8 @@ const Proto = {
  * Creates a new `Entity` of the specified `type` which will accept messages
  * that adhere to the provided `RpcGroup`.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromRpcGroup = <const Type extends string, Rpcs extends Rpc.Any>(
   /**
@@ -387,8 +437,8 @@ export const fromRpcGroup = <const Type extends string, Rpcs extends Rpc.Any>(
  * Creates a new `Entity` of the specified `type` which will accept messages
  * that adhere to the provided schemas.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <const Type extends string, Rpcs extends ReadonlyArray<Rpc.Any>>(
   /**
@@ -405,8 +455,8 @@ export const make = <const Type extends string, Rpcs extends ReadonlyArray<Rpc.A
 /**
  * A Context.Tag to access the current entity address.
  *
- * @since 4.0.0
  * @category context
+ * @since 4.0.0
  */
 export class CurrentAddress extends Context.Service<
   CurrentAddress,
@@ -416,8 +466,8 @@ export class CurrentAddress extends Context.Service<
 /**
  * A Context.Tag to access the current Runner address.
  *
- * @since 4.0.0
  * @category context
+ * @since 4.0.0
  */
 export class CurrentRunnerAddress extends Context.Service<
   CurrentRunnerAddress,
@@ -425,8 +475,13 @@ export class CurrentRunnerAddress extends Context.Service<
 >()("effect/cluster/Entity/RunnerAddress") {}
 
 /**
- * @since 4.0.0
+ * Reply API passed to queue-based entity handlers.
+ *
+ * Use it to complete an entity request by succeeding, failing, failing with a
+ * cause, or supplying an explicit `Exit`.
+ *
  * @category Replier
+ * @since 4.0.0
  */
 export interface Replier<Rpcs extends Rpc.Any> {
   readonly succeed: <R extends Rpcs>(
@@ -451,13 +506,20 @@ export interface Replier<Rpcs extends Rpc.Any> {
 }
 
 /**
- * @since 4.0.0
+ * Helper types used by the `Replier` API.
+ *
  * @category Replier
+ * @since 4.0.0
  */
 export declare namespace Replier {
   /**
-   * @since 4.0.0
+   * Success value accepted by a `Replier` for a single RPC.
+   *
+   * For streaming RPCs this may be either a stream of success chunks or a dequeue
+   * of success chunks. For non-streaming RPCs it is the RPC success value.
+   *
    * @category Replier
+   * @since 4.0.0
    */
   export type Success<R extends Rpc.Any> = Rpc.Success<R> extends Stream.Stream<infer _A, infer _E, infer _R> ?
     Stream.Stream<_A, _E | Rpc.Error<R>, _R> | Queue.Dequeue<_A, _E | Rpc.Error<R> | Cause.Done>
@@ -465,8 +527,13 @@ export declare namespace Replier {
 }
 
 /**
- * @since 4.0.0
+ * Entity request envelope delivered to entity handlers.
+ *
+ * It includes the underlying request envelope plus the last stream reply chunk
+ * that was sent, allowing handlers to resume chunk sequencing after a restart.
+ *
  * @category Request
+ * @since 4.0.0
  */
 export class Request<Rpc extends Rpc.Any> extends Data.Class<
   Envelope.Request<Rpc> & {
@@ -474,6 +541,8 @@ export class Request<Rpc extends Rpc.Any> extends Data.Class<
   }
 > {
   /**
+   * Most recent success chunk value sent by the entity, when one exists.
+   *
    * @since 4.0.0
    */
   get lastSentChunkValue(): Option.Option<Rpc.SuccessChunk<Rpc>> {
@@ -481,6 +550,8 @@ export class Request<Rpc extends Rpc.Any> extends Data.Class<
   }
 
   /**
+   * Sequence number to use for the entity's next outgoing success chunk.
+   *
    * @since 4.0.0
    */
   get nextSequence(): number {
@@ -494,8 +565,13 @@ export class Request<Rpc extends Rpc.Any> extends Data.Class<
 const shardingTag = Context.Service<Sharding, Sharding["Service"]>("effect/cluster/Sharding")
 
 /**
- * @since 4.0.0
+ * Builds an in-memory test client for an entity layer.
+ *
+ * The returned function creates a no-serialization RPC client for each entity ID,
+ * using a test sharding service instead of the cluster transport.
+ *
  * @category Testing
+ * @since 4.0.0
  */
 export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE, LR>(
   entity: Entity<Type, Rpcs>,
@@ -596,8 +672,13 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
 })
 
 /**
- * @since 4.0.0
+ * Enables or disables keep-alive for the current entity.
+ *
+ * When enabled it sends the internal keep-alive RPC for the current address; when
+ * disabled it releases the keep-alive latch if one is present.
+ *
  * @category Keep alive
+ * @since 4.0.0
  */
 export const keepAlive: (
   enabled: boolean
@@ -645,16 +726,26 @@ export const keepAlive: (
   ))
 
 /**
- * @since 4.0.0
+ * Internal persisted RPC used to keep an entity active while a resource is held.
+ *
+ * The RPC is marked as persisted and uninterruptible so the keep-alive signal
+ * survives normal entity restarts.
+ *
  * @category Keep alive
+ * @since 4.0.0
  */
 export const KeepAliveRpc = Rpc.make("Cluster/Entity/keepAlive")
   .annotate(Persisted, true)
   .annotate(Uninterruptible, true)
 
 /**
- * @since 4.0.0
+ * Service tag for the latch that coordinates entity keep-alive state.
+ *
+ * `keepAlive` closes the latch when keep-alive is active and opens it again when
+ * the resource no longer needs to keep the entity alive.
+ *
  * @category Keep alive
+ * @since 4.0.0
  */
 export class KeepAliveLatch extends Context.Service<KeepAliveLatch, Latch.Latch>()(
   "effect/cluster/Entity/KeepAliveLatch"

package/src/unstable/cluster/EntityAddress.ts

@@ -1,4 +1,22 @@
 /**
+ * The `EntityAddress` module defines the value used to locate an entity within
+ * a cluster. An address combines the entity type, entity id, and shard id so
+ * messages, persisted envelopes, workflow executions, and entity managers can
+ * agree on the same routing target.
+ *
+ * **Common tasks**
+ *
+ * - Build an address after resolving an entity id to a shard with `Sharding`
+ * - Attach an address to cluster envelopes and persisted messages
+ * - Compare or hash addresses when tracking active or resuming entities
+ *
+ * **Gotchas**
+ *
+ * - The shard id is part of the address identity; the same entity type and id
+ *   on a different shard is a different address.
+ * - Entity ids should be routed through the same shard group logic used by the
+ *   entity definition so messages are sent to the runner that owns the shard.
+ *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.ts"
@@ -13,8 +31,8 @@ const TypeId = "~effect/cluster/EntityAddress"
 /**
  * Represents the unique address of an entity within the cluster.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   shardId: ShardId,
@@ -22,11 +40,15 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   entityId: EntityId
 }) {
   /**
+   * Marks this value as a cluster entity address for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Formats the entity type, entity id, and shard id as a readable address.
+   *
    * @since 4.0.0
    */
   override toString() {
@@ -34,6 +56,8 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   }
 
   /**
+   * Compares entity addresses by entity type, entity id, and shard id.
+   *
    * @since 4.0.0
    */
   [Equal.symbol](that: EntityAddress): boolean {
@@ -42,6 +66,8 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   }
 
   /**
+   * Computes a structural hash from the entity type, entity id, and shard id.
+   *
    * @since 4.0.0
    */
   [Hash.symbol]() {
@@ -49,8 +75,10 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   }
 }
 /**
- * @since 4.0.0
+ * Constructs an `EntityAddress` from a shard ID, entity type, and entity ID.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (options: {
   readonly shardId: ShardId

package/src/unstable/cluster/EntityId.ts

@@ -1,22 +1,37 @@
 /**
+ * The `EntityId` module provides a branded string identifier for addressing a
+ * specific entity instance inside the cluster. Entity ids are commonly used as
+ * stable routing keys when sending messages to an entity, looking up its state,
+ * or deriving the shard responsible for that entity.
+ *
+ * Because routing is based on the exact string value, choose ids that are
+ * deterministic, normalized, and unique within the entity type you are
+ * addressing. Avoid display names or other values that may change over time.
+ *
  * @since 4.0.0
  */
 import * as Schema from "../../Schema.ts"
 
 /**
- * @since 4.0.0
+ * Schema for branded string entity identifiers used inside the cluster.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const EntityId = Schema.String.pipe(Schema.brand("~effect/cluster/EntityId"))
 
 /**
- * @since 4.0.0
+ * Branded string type representing the ID of an entity instance.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type EntityId = typeof EntityId.Type
 
 /**
- * @since 4.0.0
+ * Brands a string as an `EntityId`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (id: string): EntityId => id as EntityId

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"
@@ -47,8 +69,8 @@ const clientErrors = [
  * )
  * ```
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
   entity: Entity.Entity<Type, Rpcs>
@@ -82,6 +104,11 @@ 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.
+ *
  * @since 4.0.0
  */
 export type ConvertRpcs<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs extends Rpc.Rpc<
@@ -166,8 +193,8 @@ const entityIdPath = {
  * )
  * ```
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export const toHttpApiGroup = <const Name extends string, Type extends string, Rpcs extends Rpc.Any>(
   name: Name,
@@ -205,6 +232,11 @@ 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.
+ *
  * @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"
 
 /**
- * @since 4.0.0
+ * 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
  */
 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 = <
   )
 
 /**
- * @since 4.0.0
+ * 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
  */
 export const layerRpcHandlers = <
   const Type extends string,
@@ -105,6 +137,10 @@ 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.
+ *
  * @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"
 
 /**
- * @since 4.0.0
+ * 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
  */
 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.
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 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,