effect 4.0.0-beta.71 → 4.0.0-beta.73

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

@@ -480,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
@@ -491,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
@@ -557,7 +567,7 @@ export declare namespace Replier {
 }
 
 /**
- * Entity request envelope delivered to entity handlers.
+ * Represents an entity request envelope delivered to entity handlers.
  *
  * **Details**
  *
@@ -604,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>(
@@ -762,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/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**
  *
@@ -103,6 +102,7 @@ export class CloseScope extends Context.Service<
 export const make: <A, E, R>(options: {
   readonly acquire: Effect.Effect<A, E, R>
   readonly idleTimeToLive?: Duration.Input | undefined
+  readonly acquireEagerly?: boolean | undefined
 }) => Effect.Effect<
   EntityResource<A, E>,
   E,
@@ -110,13 +110,14 @@ export const make: <A, E, R>(options: {
 > = Effect.fnUntraced(function*<A, E, R>(options: {
   readonly acquire: Effect.Effect<A, E, R>
   readonly idleTimeToLive?: Duration.Input | undefined
+  readonly acquireEagerly?: boolean | undefined
 }) {
   let shuttingDown = false
 
-  yield* Entity.keepAlive(true)
-
   const ref = yield* RcRef.make({
     acquire: Effect.gen(function*() {
+      yield* Entity.keepAlive(true)
+
       const closeable = yield* Scope.make()
 
       yield* Effect.addFinalizer(
@@ -139,8 +140,10 @@ export const make: <A, E, R>(options: {
     return Effect.void
   })
 
-  // Initialize the resource
-  yield* Effect.scoped(RcRef.get(ref))
+  if (options.acquireEagerly) {
+    // Initialize the resource
+    yield* Effect.scoped(RcRef.get(ref))
+  }
 
   return identity<EntityResource<A, E>>({
     [TypeId]: TypeId,

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

@@ -220,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
@@ -244,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
@@ -268,7 +266,7 @@ export const layerWebsocketOptions = (options: {
   )
 
 /**
- * Complete HTTP runner layer.
+ * Layer that serves runner routes at `/` and configures HTTP runner clients.
  *
  * **Details**
  *
@@ -293,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**
  *
@@ -316,7 +319,7 @@ export const layerHttpClientOnly: Layer.Layer<
 )
 
 /**
- * Complete WebSocket runner layer.
+ * Layer that serves runner routes at `/` and configures WebSocket runner clients.
  *
  * **Details**
  *
@@ -341,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/Message.ts

@@ -91,7 +91,7 @@ export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>):
 }
 
 /**
- * Incoming persisted request whose payload has not yet been decoded with the RPC
+ * Represents an incoming persisted request whose payload has not yet been decoded with the RPC
  * schema.
  *
  * **Details**
@@ -109,14 +109,14 @@ export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("Incomi
 }> {}
 
 /**
- * Incoming request for local delivery with a decoded payload.
+ * Represents an incoming request for local delivery with a decoded payload.
  *
  * **Details**
  *
  * It includes dynamic annotations, the last sent reply, and a callback for
  * replying with decoded replies.
  *
- * @category outgoing
+ * @category incoming
  * @since 4.0.0
  */
 export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("IncomingRequestLocal")<{
@@ -127,7 +127,7 @@ export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("I
 }> {}
 
 /**
- * Incoming control envelope carrying an `AckChunk` or `Interrupt`.
+ * Represents an incoming control envelope carrying an `AckChunk` or `Interrupt`.
  *
  * @category incoming
  * @since 4.0.0
@@ -150,7 +150,7 @@ export class IncomingEnvelope extends Data.TaggedClass("IncomingEnvelope")<{
 export type Outgoing<R extends Rpc.Any> = OutgoingRequest<R> | OutgoingEnvelope
 
 /**
- * Outgoing entity request with decoded payload and RPC metadata.
+ * Represents an outgoing entity request with decoded payload and RPC metadata.
  *
  * **Details**
  *
@@ -177,7 +177,7 @@ export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("Outgoi
 }
 
 /**
- * Outgoing control envelope paired with RPC metadata.
+ * Represents an outgoing control envelope paired with RPC metadata.
  *
  * **When to use**
  *
@@ -222,7 +222,7 @@ const neverRpc = Rpc.make("Never", {
  * Control envelopes pass through unchanged. Requests are encoded with their RPC
  * payload schema, reusing the cached encoded request when available.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serialize = <Rpc extends Rpc.Any>(
@@ -245,7 +245,7 @@ export const serialize = <Rpc extends Rpc.Any>(
  *
  * Schema encoding failures are converted to `MalformedMessage`.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serializeEnvelope = <Rpc extends Rpc.Any>(
@@ -264,7 +264,7 @@ export const serializeEnvelope = <Rpc extends Rpc.Any>(
  *
  * The result is a `PartialRequest` suitable for storage or transport.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serializeRequest = <Rpc extends Rpc.Any>(
@@ -290,7 +290,7 @@ export const serializeRequest = <Rpc extends Rpc.Any>(
  * `OutgoingRequest` so the payload can be decoded with the correct RPC schema and
  * context.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const deserializeLocal = <Rpc extends Rpc.Any>(

package/src/unstable/cluster/MessageStorage.ts

@@ -215,7 +215,7 @@ export class MessageStorage extends Context.Service<MessageStorage, {
 export type SaveResult<R extends Rpc.Any> = SaveResult.Success | SaveResult.Duplicate<R>
 
 /**
- * Tagged enum constructor for creating and matching `SaveResult` values.
+ * Constructors and matchers for decoded save results.
  *
  * @category SaveResult
  * @since 4.0.0
@@ -223,7 +223,7 @@ export type SaveResult<R extends Rpc.Any> = SaveResult.Success | SaveResult.Dupl
 export const SaveResult = Data.taggedEnum<SaveResult.Constructor>()
 
 /**
- * Tagged enum constructor for encoded save results returned by encoded storage
+ * Constructors and matchers for encoded save results returned by storage
  * drivers.
  *
  * @category SaveResult
@@ -822,7 +822,7 @@ export const noop: MessageStorage["Service"] = Effect.runSync(make({
  * It stores the encoded envelope, last acknowledged chunk, accumulated replies,
  * and optional delivery time.
  *
- * @category Memory
+ * @category memory
  * @since 4.0.0
  */
 export type MemoryEntry = {
@@ -833,9 +833,9 @@ export type MemoryEntry = {
 }
 
 /**
- * Can be used in tests to simulate a transaction.
+ * Provides a context reference used in tests to simulate a transaction.
  *
- * @category Memory
+ * @category memory
  * @since 4.0.0
  */
 export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/MessageStorage/MemoryTransaction", {
@@ -843,7 +843,7 @@ export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/Mess
 })
 
 /**
- * In-memory message storage driver with inspectable backing state.
+ * Service that provides an in-memory message storage driver with inspectable backing state.
  *
  * **Details**
  *
@@ -851,7 +851,7 @@ export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/Mess
  * maps used to track requests, primary keys, unprocessed envelopes, reply IDs,
  * and the journal.
  *
- * @category Memory
+ * @category memory
  * @since 4.0.0
  */
 export class MemoryDriver extends Context.Service<MemoryDriver>()("effect/cluster/MessageStorage/MemoryDriver", {

package/src/unstable/cluster/Reply.ts

@@ -69,21 +69,26 @@ export type Reply<R extends Rpc.Any> = WithExit<R> | Chunk<R>
 export type Encoded = WithExitEncoded | ChunkEncoded
 
 /**
- * Codec used for reply values that are already in encoded form.
+ * Schema for reply values that are already in encoded form.
  *
  * **Details**
  *
  * Per-RPC payload validation is performed by `Reply(rpc)`.
  *
- * @category models
+ * @category schemas
  * @since 4.0.0
  */
 export const Encoded: Schema.Codec<Encoded> = Schema.Any as any
 
 /**
- * A cluster reply paired with the RPC definition and service context required to
+ * Represents a cluster reply paired with the RPC definition and service context required to
  * serialize it for transport.
  *
+ * **When to use**
+ *
+ * Use to carry a runtime reply together with the RPC schema and services needed
+ * to encode it for storage or transport.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -171,8 +176,8 @@ export interface ChunkEncoded {
 const schemaCache = new WeakMap<Rpc.Any, Schema.Top>()
 
 /**
- * A streaming RPC reply chunk for a request, carrying a non-empty batch of success
- * values together with the reply id and sequence number.
+ * Represents a streaming RPC reply chunk for a request, carrying a non-empty
+ * batch of success values together with the reply id and sequence number.
  *
  * @category models
  * @since 4.0.0
@@ -290,9 +295,14 @@ export class Chunk<R extends Rpc.Any> extends Data.TaggedClass("Chunk")<{
 }
 
 /**
- * A terminal RPC reply for a request, carrying the final `Exit` for the remote
+ * Represents a terminal RPC reply for a request, carrying the final `Exit` for the remote
  * call.
  *
+ * **When to use**
+ *
+ * Use to represent the final success, typed failure, defect, or interruption
+ * for a clustered RPC request.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -416,7 +426,7 @@ export const Reply = <R extends Rpc.Any>(
  * reply's RPC schema and context and refailing encoding errors as
  * `MalformedMessage`.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serialize = <R extends Rpc.Any>(
@@ -436,7 +446,7 @@ export const serialize = <R extends Rpc.Any>(
  * `None` when no reply has been received and refailing encoding errors as
  * `MalformedMessage`.
  *
- * @category serialization / deserialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serializeLastReceived = <R extends Rpc.Any>(

package/src/unstable/cluster/Runner.ts

@@ -48,7 +48,7 @@ import { RunnerAddress } from "./RunnerAddress.ts"
 const TypeId = "~effect/cluster/Runner"
 
 /**
- * A cluster runner that can host entities.
+ * Represents a cluster runner that can host entities.
  *
  * **Details**
  *

package/src/unstable/cluster/RunnerAddress.ts

@@ -43,7 +43,13 @@ import * as Schema from "../../Schema.ts"
 const TypeId = "~effect/cluster/RunnerAddress"
 
 /**
- * Network address of a cluster runner, identified by host and port.
+ * Represents the network address of a cluster runner, identified by host and
+ * port.
+ *
+ * **When to use**
+ *
+ * Use to represent the host and port that identify a runner in cluster routing,
+ * registration, and health checks.
  *
  * @category models
  * @since 4.0.0

package/src/unstable/cluster/RunnerHealth.ts

@@ -67,11 +67,11 @@ export class RunnerHealth extends Context.Service<
 >()("effect/cluster/RunnerHealth") {}
 
 /**
- * A layer which will **always** consider a Runner healthy.
+ * Layer that always considers a runner healthy.
  *
  * **When to use**
  *
- * Use when this is useful for testing.
+ * Use when tests or local development do not need active runner health checks.
  *
  * @category layers
  * @since 4.0.0
@@ -108,7 +108,7 @@ export const makePing: Effect.Effect<
 })
 
 /**
- * A layer which will ping a Runner directly to check if it is healthy.
+ * Layer that pings runners directly to check whether they are healthy.
  *
  * @category layers
  * @since 4.0.0
@@ -146,7 +146,7 @@ export const makeK8s = Effect.fnUntraced(function*(options?: {
 })
 
 /**
- * A layer which checks Kubernetes pod readiness to determine whether a runner is
+ * Layer that checks Kubernetes pod readiness to determine whether a runner is
  * healthy.
  *
  * **Details**