effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -37,6 +37,7 @@ import type * as Record from "../../Record.ts"
 import * as Schedule from "../../Schedule.ts"
 import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
+import * as Headers from "../http/Headers.ts"
 import * as Rpc from "../rpc/Rpc.ts"
 import { ClientAbort } from "../rpc/RpcSchema.ts"
 import * as Activity from "../workflow/Activity.ts"
@@ -159,8 +160,6 @@ export const make = Effect.gen(function*() {
     }),
     idleTimeToLive: "5 minutes"
   })
-  const clockClient = yield* ClockEntity.client
-
   const entityAddressFor = (options: {
     readonly workflow: Workflow.Any
     readonly entityType: string
@@ -177,6 +176,35 @@ export const make = Effect.gen(function*() {
     })
   }
 
+  const sendDiscard = Effect.fnUntraced(function*(options: {
+    readonly rpc: Rpc.AnyWithProps
+    readonly address: EntityAddress.EntityAddress
+    readonly payload: unknown
+  }) {
+    const payload = (options.rpc.payloadSchema as any).make(options.payload)
+    const envelope = Envelope.makeRequest<any>({
+      requestId: yield* sharding.getSnowflake,
+      address: options.address,
+      tag: options.rpc._tag as any,
+      payload,
+      headers: Headers.empty
+    })
+    yield* sharding.sendOutgoing(
+      new Message.OutgoingRequest({
+        envelope,
+        context: Context.empty() as Context.Context<any>,
+        lastReceivedReply: Option.none(),
+        rpc: options.rpc,
+        respond: () => Effect.void,
+        annotations: Context.get(options.rpc.annotations, ClusterSchema.Dynamic)(
+          options.rpc.annotations,
+          envelope as any
+        )
+      }),
+      true
+    )
+  })
+
   const requestIdFor = Effect.fnUntraced(function*(options: {
     readonly workflow: Workflow.Any
     readonly entityType: string
@@ -562,6 +590,21 @@ export const make = Effect.gen(function*() {
 
     deferredDone: Effect.fnUntraced(
       function*({ deferredName, executionId, exit, workflowName }) {
+        const workflow = workflows.get(workflowName)
+        if (workflow) {
+          return yield* Effect.orDie(sendDiscard({
+            rpc: DeferredRpc,
+            address: entityAddressFor({
+              workflow,
+              entityType: `Workflow/${workflowName}`,
+              executionId
+            }),
+            payload: {
+              name: deferredName,
+              exit
+            }
+          }))
+        }
         const client = yield* RcMap.get(clientsPartial, workflowName)
         return yield* Effect.orDie(
           client(executionId).deferred({
@@ -574,14 +617,21 @@ export const make = Effect.gen(function*() {
     ),
 
     scheduleClock(workflow, options) {
-      const client = clockClient(options.executionId)
       return DateTime.now.pipe(
         Effect.flatMap((now) =>
-          client.run({
-            name: options.clock.name,
-            workflowName: workflow.name,
-            wakeUp: DateTime.addDuration(now, options.clock.duration)
-          }, { discard: true })
+          sendDiscard({
+            rpc: ClockRpc,
+            address: entityAddressFor({
+              workflow,
+              entityType: ClockEntity.type,
+              executionId: options.executionId
+            }),
+            payload: {
+              name: options.clock.name,
+              workflowName: workflow.name,
+              wakeUp: DateTime.addDuration(now, options.clock.duration)
+            }
+          })
         ),
         Effect.orDie
       )
@@ -696,10 +746,12 @@ class ClockPayload extends Schema.Class<ClockPayload>(`Workflow/DurableClock/Run
   }
 }
 
+const ClockRpc = Rpc.make("run", { payload: ClockPayload })
+  .annotate(ClusterSchema.Persisted, true)
+  .annotate(ClusterSchema.Uninterruptible, true)
+
 const ClockEntity = Entity.make("Workflow/-/DurableClock", [
-  Rpc.make("run", { payload: ClockPayload })
-    .annotate(ClusterSchema.Persisted, true)
-    .annotate(ClusterSchema.Uninterruptible, true)
+  ClockRpc
 ])
 
 const ClockEntityLayer = ClockEntity.toLayer(Effect.gen(function*() {

package/src/unstable/cluster/DeliverAt.ts

@@ -27,7 +27,12 @@ import type { DateTime } from "../../DateTime.ts"
 import { hasProperty } from "../../Predicate.ts"
 
 /**
- * Property key used by values that provide a scheduled delivery time.
+ * Defines the property key used by values that provide a scheduled delivery time.
+ *
+ * **When to use**
+ *
+ * Use to implement the scheduled-delivery protocol on cluster message payloads
+ * by defining a method at this property key.
  *
  * @category symbols
  * @since 4.0.0

package/src/unstable/cluster/Entity.ts

@@ -447,6 +447,23 @@ 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.
  *
+ * **When to use**
+ *
+ * Use to define a cluster entity from individual `Rpc` definitions, giving the
+ * cluster runtime a typed protocol for handlers and per-entity clients.
+ *
+ * **Details**
+ *
+ * The `type` argument is stored as the entity `EntityType`, and the RPC array
+ * is grouped into the entity's `protocol`.
+ *
+ * **Gotchas**
+ *
+ * RPC tags should be unique within the array. If multiple definitions use the
+ * same tag, the resulting protocol keeps the later definition for that tag.
+ *
+ * @see {@link fromRpcGroup} for creating an entity from an existing `RpcGroup`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -463,7 +480,12 @@ export const make = <const Type extends string, Rpcs extends ReadonlyArray<Rpc.A
 ): Entity<Type, Rpcs[number]> => fromRpcGroup(type, RpcGroup.make(...protocol))
 
 /**
- * A Context.Tag to access the current entity address.
+ * Service tag for the entity address currently being processed.
+ *
+ * **When to use**
+ *
+ * Use to read the current entity identity and shard address from entity
+ * handlers and keep-alive logic.
  *
  * @category context
  * @since 4.0.0
@@ -474,7 +496,12 @@ export class CurrentAddress extends Context.Service<
 >()("effect/cluster/Entity/EntityAddress") {}
 
 /**
- * A Context.Tag to access the current Runner address.
+ * Service tag for the runner address currently registering entity handlers.
+ *
+ * **When to use**
+ *
+ * Use to read the runner address associated with the current entity handler
+ * registration.
  *
  * @category context
  * @since 4.0.0
@@ -489,7 +516,7 @@ export class CurrentRunnerAddress extends Context.Service<
  *
  * **When to use**
  *
- * Use it to complete an entity request by succeeding, failing, failing with a
+ * Use when you use it to complete an entity request by succeeding, failing, failing with a
  * cause, or supplying an explicit `Exit`.
  *
  * @category Replier
@@ -540,7 +567,7 @@ export declare namespace Replier {
 }
 
 /**
- * Entity request envelope delivered to entity handlers.
+ * Represents an entity request envelope delivered to entity handlers.
  *
  * **Details**
  *
@@ -587,7 +614,7 @@ const shardingTag = Context.Service<Sharding, Sharding["Service"]>("effect/clust
  * 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
+ * @category testing
  * @since 4.0.0
  */
 export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE, LR>(
@@ -745,7 +772,7 @@ export const keepAlive: (
   ))
 
 /**
- * Internal persisted RPC used to keep an entity active while a resource is held.
+ * RPC used internally to keep an entity active while a resource is held.
  *
  * **Details**
  *

package/src/unstable/cluster/EntityAddress.ts

@@ -77,6 +77,25 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
 /**
  * Constructs an `EntityAddress` from a shard ID, entity type, and entity ID.
  *
+ * **When to use**
+ *
+ * Use to create the routing target for a known entity type and entity id after
+ * resolving that id to the `ShardId` assigned by the entity's shard group.
+ *
+ * **Details**
+ *
+ * The returned `EntityAddress` stores the supplied `shardId`, `entityType`, and
+ * `entityId`. Equality and hashing include all three fields.
+ *
+ * **Gotchas**
+ *
+ * `make` does not choose the shard for an entity. Use the same shard group
+ * logic as the entity definition; a different `shardId` makes a different
+ * address even when the entity type and entity id match.
+ *
+ * @see {@link EntityAddress} for the equality, hashing, and string formatting behavior of constructed addresses
+ * @see {@link ShardId} for the shard identifier included in the address
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityId.ts

@@ -1,12 +1,32 @@
 /**
- * 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.
+ * The `EntityId` module defines the branded string used to identify one entity
+ * instance within an entity type. The value is the routing key that sharding
+ * hashes, stores in entity addresses, and uses when sending messages to a
+ * running 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.
+ * **Mental model**
+ *
+ * - An entity id is a stable string with a brand; at runtime it is still the
+ *   original string
+ * - Uniqueness is scoped by entity type, so two different entity types may use
+ *   the same id without addressing the same entity
+ * - Routing depends on the exact string value, including casing and
+ *   normalization
+ *
+ * **Common tasks**
+ *
+ * - Brand trusted ids with {@link make} before passing them to cluster APIs
+ * - Use the {@link EntityId} schema when decoding or encoding ids at
+ *   boundaries
+ * - Store ids alongside entity type and shard id when building entity
+ *   addresses
+ *
+ * **Gotchas**
+ *
+ * - {@link make} does not validate, normalize, or ensure uniqueness
+ * - Avoid display names, emails that may change, or values with inconsistent
+ *   casing or whitespace
+ * - Changing an id changes the shard routing target for that entity
  *
  * @since 4.0.0
  */
@@ -31,6 +51,23 @@ export type EntityId = typeof EntityId.Type
 /**
  * Brands a string as an `EntityId`.
  *
+ * **When to use**
+ *
+ * Use to turn a trusted, stable entity routing key into an `EntityId` before
+ * passing it to cluster APIs.
+ *
+ * **Details**
+ *
+ * The branded value is the original string at runtime.
+ *
+ * **Gotchas**
+ *
+ * `make` does not validate, normalize, or make the value unique. Choose
+ * deterministic strings because cluster routing hashes the exact entity id
+ * value.
+ *
+ * @see {@link EntityId} for the schema that validates and encodes branded entity identifiers
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/EntityResource.ts

@@ -38,7 +38,7 @@ import type { Sharding } from "./Sharding.ts"
 /**
  * Type identifier used to brand `EntityResource` values.
  *
- * @category Type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/cluster/EntityResource"
@@ -46,7 +46,7 @@ export const TypeId: TypeId = "~effect/cluster/EntityResource"
 /**
  * Literal type of the `EntityResource` type identifier.
  *
- * @category Type ids
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/cluster/EntityResource"
@@ -69,13 +69,13 @@ export interface EntityResource<out A, out E = never> {
 }
 
 /**
- * A `Scope` that is only closed when the resource is explicitly closed.
+ * Context service for a Scope that is only closed when the resource is explicitly closed.
  *
  * **Gotchas**
  *
  * It is not closed during restarts, due to shard movement or node shutdowns.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export class CloseScope extends Context.Service<
@@ -84,8 +84,7 @@ export class CloseScope extends Context.Service<
 >()("effect/cluster/EntityResource/CloseScope") {}
 
 /**
- * A `EntityResource` is a resource that can be acquired inside a cluster
- * entity, which will keep the entity alive even across restarts.
+ * Creates an `EntityResource` that can be acquired inside a cluster entity.
  *
  * **Details**
  *

package/src/unstable/cluster/EntityType.ts

@@ -40,6 +40,25 @@ export type EntityType = typeof EntityType.Type
 /**
  * Brands a string as an `EntityType`.
  *
+ * **When to use**
+ *
+ * Use to brand a stable entity family name before passing it to cluster APIs
+ * that require an `EntityType`, such as entity addresses.
+ *
+ * **Details**
+ *
+ * The returned value is the same runtime string with the `EntityType` brand
+ * applied by TypeScript.
+ *
+ * **Gotchas**
+ *
+ * `make` only applies the brand at the type level; it does not validate,
+ * normalize, or check uniqueness. Use the `EntityType` schema when you need
+ * schema-based decoding or validation, and keep names stable because the exact
+ * string participates in routing identity.
+ *
+ * @see {@link EntityType} for schema-based decoding, validation, and encoding of entity type names
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cluster/Envelope.ts

@@ -156,7 +156,8 @@ export interface PartialRequestEncoded {
 }
 
 /**
- * Envelope acknowledging receipt of a streamed reply chunk for a request.
+ * Represents an envelope acknowledging receipt of a streamed reply chunk for a
+ * request.
  *
  * **Details**
  *
@@ -214,7 +215,7 @@ export interface AckChunkEncoded {
 }
 
 /**
- * Envelope used to interrupt an in-flight entity request.
+ * Represents an envelope used to interrupt an in-flight entity request.
  *
  * @category models
  * @since 4.0.0
@@ -266,7 +267,7 @@ export interface InterruptEncoded {
 }
 
 /**
- * Schema union for partially decoded cluster envelopes.
+ * Schema for partially decoded cluster envelopes.
  *
  * **Details**
  *
@@ -303,7 +304,7 @@ export const PartialJson: Schema.Codec<
 > = Schema.toCodecJson(Partial) as any
 
 /**
- * Mutable array schema for JSON-encoded partial cluster envelopes.
+ * Schema for mutable arrays of JSON-encoded partial cluster envelopes.
  *
  * @category schemas
  * @since 4.0.0
@@ -378,10 +379,9 @@ export const makeRequest = <Rpc extends Rpc.Any>(
 })
 
 /**
- * Schema declaration that recognizes runtime `Envelope` values by their type
- * identifier.
+ * Schema for runtime cluster envelopes recognized by their type identifier.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const Envelope = Schema.declare(isEnvelope, {
@@ -389,9 +389,9 @@ export const Envelope = Schema.declare(isEnvelope, {
 })
 
 /**
- * Schema declaration that recognizes runtime request envelopes.
+ * Schema for runtime request envelopes.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const Request = Schema.declare(
@@ -400,10 +400,10 @@ export const Request = Schema.declare(
 )
 
 /**
- * Transformation that decodes plain request data with `makeRequest` and encodes
+ * Transforms plain request data with `makeRequest` and encodes
  * request envelopes back to their raw representation.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const RequestTransform: Transformation.Transformation<

package/src/unstable/cluster/HttpRunner.ts

@@ -1,26 +1,38 @@
 /**
- * The `HttpRunner` module wires cluster runner RPCs to HTTP transports. It
- * provides client protocol layers for contacting runners over HTTP or
- * WebSocket, server-side HTTP effects for exposing runner RPC handlers, and
- * complete layers that install those routes into an `HttpRouter`.
+ * HTTP and WebSocket transport layers for cluster runner RPCs.
+ *
+ * Runner nodes communicate through the `Runners.Rpcs` protocol. This module
+ * connects that protocol to HTTP transports by providing client protocols for
+ * dialing runner addresses, HTTP effects for serving runner RPC handlers, and
+ * complete layers that install runner routes into an `HttpRouter`.
+ *
+ * **Mental model**
+ *
+ * Runner communication has two sides: a client protocol that knows how to turn a
+ * runner address into an RPC connection, and a server route that exposes the
+ * runner RPC handlers. The complete layers provide both sides with matching
+ * defaults, while the `Options` and `ClientOnly` variants let applications wire
+ * only the pieces they need.
  *
  * **Common tasks**
  *
- * - Serve runner RPC routes with {@link layerHttp} or {@link layerWebsocket}
- * - Configure client-only runner communication with {@link layerHttpClientOnly}
+ * - Serve runners over HTTP with {@link layerHttp} or {@link layerHttpOptions}
+ * - Serve runners over WebSocket with {@link layerWebsocket} or
+ *   {@link layerWebsocketOptions}
+ * - Configure clients without serving routes with {@link layerHttpClientOnly}
  *   or {@link layerWebsocketClientOnly}
- * - Use custom route paths with {@link layerHttpOptions},
- *   {@link layerWebsocketOptions}, {@link layerClientProtocolHttp}, or
+ * - Build custom client protocols with {@link layerClientProtocolHttp} or
  *   {@link layerClientProtocolWebsocket}
  *
- * **Transport gotchas**
+ * **Gotchas**
  *
- * - Client protocol paths are appended to each runner address when building the
- *   target URL
- * - `https: true` switches HTTP clients from `http` to `https`, and WebSocket
+ * - Server route paths and client protocol paths must match
+ * - `https: true` switches HTTP clients from `http` to `https` and WebSocket
  *   clients from `ws` to `wss`
- * - The default complete layers serve and connect at `/`; use the `Options`
- *   variants when your runner routes live under a different path
+ * - The complete layers serve and connect at `/`; use the `Options` variants
+ *   when runner routes live under another path
+ * - {@link toHttpEffect} and {@link toHttpEffectWebsocket} expose raw HTTP
+ *   effects for adapters that do not use `HttpRouter.serve`
  *
  * @since 4.0.0
  */
@@ -208,8 +220,7 @@ export const layerClient: Layer.Layer<
 )
 
 /**
- * A HTTP layer for the `Runners` services, that adds a route to the provided
- * `HttpRouter`.
+ * Layer that adds HTTP runner routes to the provided `HttpRouter`.
  *
  * @category layers
  * @since 4.0.0
@@ -232,8 +243,7 @@ export const layerHttpOptions = (options: {
   )
 
 /**
- * WebSocket layer for the `Runners` services that adds a route to the provided
- * `HttpRouter`.
+ * Layer that adds WebSocket runner routes to the provided `HttpRouter`.
  *
  * @category layers
  * @since 4.0.0
@@ -256,7 +266,7 @@ export const layerWebsocketOptions = (options: {
   )
 
 /**
- * Complete HTTP runner layer.
+ * Layer that serves runner routes at `/` and configures HTTP runner clients.
  *
  * **Details**
  *
@@ -281,7 +291,12 @@ export const layerHttp: Layer.Layer<
 )
 
 /**
- * Client-only HTTP runner layer.
+ * Provides a client-only HTTP runner layer.
+ *
+ * **When to use**
+ *
+ * Use to provide runner clients over HTTP from a process that should not serve
+ * runner routes.
  *
  * **Details**
  *
@@ -304,7 +319,7 @@ export const layerHttpClientOnly: Layer.Layer<
 )
 
 /**
- * Complete WebSocket runner layer.
+ * Layer that serves runner routes at `/` and configures WebSocket runner clients.
  *
  * **Details**
  *
@@ -329,7 +344,12 @@ export const layerWebsocket: Layer.Layer<
 )
 
 /**
- * Client-only WebSocket runner layer.
+ * Provides a client-only WebSocket runner layer.
+ *
+ * **When to use**
+ *
+ * Use to provide runner clients over WebSocket from a process that should not
+ * serve runner routes.
  *
  * **Details**
  *

package/src/unstable/cluster/K8sHttpClient.ts

@@ -1,21 +1,40 @@
 /**
- * The `K8sHttpClient` module provides an HTTP client service for talking to the
- * Kubernetes API from code running inside a cluster.
+ * HTTP client support for talking to the Kubernetes API from code running
+ * inside a cluster. The module builds a `K8sHttpClient` service on top of the
+ * shared HTTP client, points requests at the in-cluster API endpoint, and uses
+ * the mounted service-account token when one is available.
  *
- * It configures requests for the in-cluster service endpoint, attaches the
- * mounted service-account token when present, and exposes helpers for common
- * cluster tasks such as discovering running pods by namespace or label selector
- * and creating scoped pods that are cleaned up automatically.
+ * **Mental model**
+ *
+ * - {@link layer} adapts an existing `HttpClient` so relative requests target
+ *   `https://kubernetes.default.svc/api`.
+ * - {@link K8sHttpClient} is the service tag consumed by the cluster helpers in
+ *   this module.
+ * - {@link makeGetPods} returns a cached effect that lists running pods and
+ *   indexes them by pod IP address.
+ * - {@link makeCreatePod} returns a scoped creator that creates a pod when it
+ *   is missing, waits for readiness, and deletes it when the scope closes.
+ * - {@link Pod} and {@link PodStatus} model only the status fields needed by
+ *   these helpers.
+ *
+ * **Common tasks**
+ *
+ * - Discover running pods in a namespace or behind a label selector.
+ * - Create short-lived pods for cluster workflows and let scope finalization
+ *   clean them up.
+ * - Reuse the configured `K8sHttpClient` for Kubernetes API calls that share
+ *   the same in-cluster endpoint, token, status filtering, and retry policy.
  *
  * **Gotchas**
  *
- * - The default layer targets `https://kubernetes.default.svc/api`, so it is
- *   intended for workloads with Kubernetes DNS and service-account mounts.
- * - Pod discovery is keyed by pod IP address and only includes pods whose phase
- *   is `Running`; callers should choose selectors that match the intended
- *   service topology.
- * - Network policies, RBAC, and service-account token availability can all
- *   prevent the client from reaching or authorizing with the Kubernetes API.
+ * - The default layer assumes Kubernetes DNS and the standard service-account
+ *   mount path used by in-cluster workloads.
+ * - Pod discovery filters to `status.phase=Running`; pods without the expected
+ *   status shape fail schema decoding.
+ * - Pod maps are keyed by pod IP address, so selectors should match the service
+ *   topology the caller actually wants to route to.
+ * - RBAC, network policies, and missing service-account tokens can still block
+ *   requests even when the layer is present.
  *
  * @since 4.0.0
  */