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

package/src/unstable/cluster/MachineId.ts

@@ -1,11 +1,28 @@
 /**
+ * The `MachineId` module provides the branded integer identifier used to
+ * distinguish cluster runners when generating distributed ids and coordinating
+ * runner state.
+ *
+ * **When to use**
+ *
+ * - Persisting or exchanging the machine id assigned to a cluster runner
+ * - Passing a runner-specific identity to the cluster snowflake generator
+ * - Decoding machine ids from storage while keeping them distinct from plain numbers
+ *
+ * **Gotchas**
+ *
+ * - Machine ids must be unique for concurrently active runners that generate snowflakes
+ * - Snowflake ids store the machine component in 10 bits, so only the value modulo 1024 is encoded
+ *
  * @since 4.0.0
  */
 import * as Schema from "../../Schema.ts"
 
 /**
- * @since 4.0.0
+ * Schema for branded integer machine identifiers used by the cluster.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const MachineId = Schema.Int.pipe(
   Schema.brand("~effect/cluster/MachineId"),
@@ -15,13 +32,17 @@ export const MachineId = Schema.Int.pipe(
 )
 
 /**
- * @since 4.0.0
+ * Branded integer type representing a cluster machine ID.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MachineId = typeof MachineId.Type
 
 /**
- * @since 4.0.0
+ * Brands a number as a `MachineId`.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = (id: number): MachineId => id as MachineId

package/src/unstable/cluster/Message.ts

@@ -1,4 +1,28 @@
 /**
+ * The cluster `Message` module defines the in-memory shapes used while moving
+ * requests and control envelopes between callers, durable storage, transports,
+ * and entity runners.
+ *
+ * **Common use cases**
+ *
+ * - Representing outgoing entity requests before they are stored or sent
+ * - Reconstructing incoming requests that runners read from storage or transport
+ * - Converting outgoing messages into local, in-process deliveries
+ * - Serializing request payloads with the associated RPC schema and context
+ * - Passing control envelopes such as acknowledgements and interrupts through
+ *   without payload decoding
+ *
+ * **Gotchas**
+ *
+ * - Requests can exist in decoded local form or encoded persisted form; choose
+ *   `IncomingLocal` / `OutgoingRequest` for local delivery and `IncomingRequest`
+ *   / `Envelope.PartialRequest` for storage or transport boundaries.
+ * - Request payloads must be encoded and decoded with the matching RPC payload
+ *   schema and service context, otherwise failures are surfaced as
+ *   `MalformedMessage`.
+ * - Delivery state such as the last sent or received reply is carried alongside
+ *   messages so retries and persisted replies can preserve cluster semantics.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -16,20 +40,34 @@ import type * as Reply from "./Reply.ts"
 import type { Snowflake } from "./Snowflake.ts"
 
 /**
- * @since 4.0.0
+ * Message read by a runner from storage or transport.
+ *
+ * An incoming message is either a persisted request with an encoded payload or an
+ * incoming control envelope.
+ *
  * @category incoming
+ * @since 4.0.0
  */
 export type Incoming<R extends Rpc.Any> = IncomingRequest<R> | IncomingEnvelope
 
 /**
- * @since 4.0.0
+ * Locally decoded incoming message for in-process delivery.
+ *
+ * It is either a request with a decoded payload or an incoming control envelope.
+ *
  * @category incoming
+ * @since 4.0.0
  */
 export type IncomingLocal<R extends Rpc.Any> = IncomingRequestLocal<R> | IncomingEnvelope
 
 /**
- * @since 4.0.0
+ * Converts an outgoing message into a locally deliverable incoming message.
+ *
+ * Request messages keep their decoded payload and response callback, while
+ * control envelopes are wrapped as incoming envelopes.
+ *
  * @category incoming
+ * @since 4.0.0
  */
 export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>): IncomingLocal<R> => {
   if (self._tag === "OutgoingEnvelope") {
@@ -47,8 +85,14 @@ export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>):
 }
 
 /**
- * @since 4.0.0
+ * Incoming persisted request whose payload has not yet been decoded with the RPC
+ * schema.
+ *
+ * It carries the last reply that was sent and a callback for persisting encoded
+ * replies.
+ *
  * @category incoming
+ * @since 4.0.0
  */
 export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("IncomingRequest")<{
   readonly envelope: Envelope.PartialRequest
@@ -57,8 +101,13 @@ export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("Incomi
 }> {}
 
 /**
- * @since 4.0.0
+ * Incoming request for local delivery with a decoded payload.
+ *
+ * It includes dynamic annotations, the last sent reply, and a callback for
+ * replying with decoded replies.
+ *
  * @category outgoing
+ * @since 4.0.0
  */
 export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("IncomingRequestLocal")<{
   readonly envelope: Envelope.Request<R>
@@ -68,8 +117,10 @@ export class IncomingRequestLocal<R extends Rpc.Any> extends Data.TaggedClass("I
 }> {}
 
 /**
- * @since 4.0.0
+ * Incoming control envelope carrying an `AckChunk` or `Interrupt`.
+ *
  * @category incoming
+ * @since 4.0.0
  */
 export class IncomingEnvelope extends Data.TaggedClass("IncomingEnvelope")<{
   readonly _tag: "IncomingEnvelope"
@@ -77,14 +128,23 @@ export class IncomingEnvelope extends Data.TaggedClass("IncomingEnvelope")<{
 }> {}
 
 /**
- * @since 4.0.0
+ * Message produced for storage or transport.
+ *
+ * An outgoing message is either an entity request or a control envelope.
+ *
  * @category outgoing
+ * @since 4.0.0
  */
 export type Outgoing<R extends Rpc.Any> = OutgoingRequest<R> | OutgoingEnvelope
 
 /**
- * @since 4.0.0
+ * Outgoing entity request with decoded payload and RPC metadata.
+ *
+ * It carries the service context used for serialization, the last received reply,
+ * the reply callback, dynamic annotations, and an optional encoded request cache.
+ *
  * @category outgoing
+ * @since 4.0.0
  */
 export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("OutgoingRequest")<{
   readonly envelope: Envelope.Request<R>
@@ -95,20 +155,29 @@ export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("Outgoi
   readonly annotations: Context.Context<never>
 }> {
   /**
+   * Cached encoded envelope payload reused when sending the request.
+   *
    * @since 4.0.0
    */
   public encodedCache?: Envelope.PartialRequest
 }
 
 /**
- * @since 4.0.0
+ * Outgoing control envelope paired with RPC metadata.
+ *
+ * Use `OutgoingEnvelope.interrupt` to construct an interrupt envelope for an
+ * in-flight request.
+ *
  * @category outgoing
+ * @since 4.0.0
  */
 export class OutgoingEnvelope extends Data.TaggedClass("OutgoingEnvelope")<{
   readonly envelope: Envelope.AckChunk | Envelope.Interrupt
   readonly rpc: Rpc.AnyWithProps
 }> {
   /**
+   * Creates an outgoing interrupt envelope for the supplied request.
+   *
    * @since 4.0.0
    */
   static interrupt(options: {
@@ -130,8 +199,13 @@ const neverRpc = Rpc.make("Never", {
 })
 
 /**
- * @since 4.0.0
+ * Serializes an outgoing message into a partial envelope.
+ *
+ * Control envelopes pass through unchanged. Requests are encoded with their RPC
+ * payload schema, reusing the cached encoded request when available.
+ *
  * @category serialization / deserialization
+ * @since 4.0.0
  */
 export const serialize = <Rpc extends Rpc.Any>(
   message: Outgoing<Rpc>
@@ -147,8 +221,12 @@ export const serialize = <Rpc extends Rpc.Any>(
 }
 
 /**
- * @since 4.0.0
+ * Serializes an outgoing message into its JSON envelope representation.
+ *
+ * Schema encoding failures are converted to `MalformedMessage`.
+ *
  * @category serialization / deserialization
+ * @since 4.0.0
  */
 export const serializeEnvelope = <Rpc extends Rpc.Any>(
   message: Outgoing<Rpc>
@@ -159,8 +237,13 @@ export const serializeEnvelope = <Rpc extends Rpc.Any>(
   )
 
 /**
- * @since 4.0.0
+ * Encodes the payload of an `OutgoingRequest` with the request's RPC payload
+ * schema and service context.
+ *
+ * The result is a `PartialRequest` suitable for storage or transport.
+ *
  * @category serialization / deserialization
+ * @since 4.0.0
  */
 export const serializeRequest = <Rpc extends Rpc.Any>(
   self: OutgoingRequest<Rpc>
@@ -177,8 +260,14 @@ export const serializeRequest = <Rpc extends Rpc.Any>(
 }
 
 /**
- * @since 4.0.0
+ * Decodes a partial envelope back into a locally deliverable incoming message.
+ *
+ * Control envelopes pass through directly. Request envelopes require the original
+ * `OutgoingRequest` so the payload can be decoded with the correct RPC schema and
+ * context.
+ *
  * @category serialization / deserialization
+ * @since 4.0.0
  */
 export const deserializeLocal = <Rpc extends Rpc.Any>(
   self: Outgoing<Rpc>,

package/src/unstable/cluster/MessageStorage.ts

@@ -1,4 +1,28 @@
 /**
+ * The `MessageStorage` module defines the persistence boundary used by Effect
+ * Cluster to store mailbox messages and replies. Storage implementations keep
+ * requests, envelopes, and reply chunks durable enough for runners to recover
+ * work after restarts, replay unprocessed messages for assigned shards, and
+ * deliver replies back to locally registered handlers.
+ *
+ * **Common use cases**
+ *
+ * - Persist outgoing requests and control envelopes before delivery
+ * - Detect duplicate requests by primary key and resume from an existing reply
+ * - Query unprocessed messages when shards are assigned to a runner
+ * - Store, load, and clear replies for request streams and completions
+ * - Reset or clear mailbox state during shard or address lifecycle changes
+ *
+ * **Gotchas**
+ *
+ * - Implementations should make save and reply operations transactional when
+ *   possible so recovery does not observe partial mailbox state
+ * - Duplicate detection depends on stable request primary keys and persisted
+ *   request ids
+ * - Reply handlers are local process state; persisted replies may need to be
+ *   loaded again after restarts or reassignment
+ * - Concurrent runners must only process messages for shards they currently own
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -25,8 +49,14 @@ import type { ShardingConfig } from "./ShardingConfig.ts"
 import * as Snowflake from "./Snowflake.ts"
 
 /**
- * @since 4.0.0
+ * Service for cluster mailbox persistence and reply delivery.
+ *
+ * It stores outgoing requests, control envelopes, and replies; reads unprocessed
+ * messages; manages reply handlers; and provides transaction wrapping for storage
+ * operations.
+ *
  * @category context
+ * @since 4.0.0
  */
 export class MessageStorage extends Context.Service<MessageStorage, {
   /**
@@ -151,45 +181,69 @@ export class MessageStorage extends Context.Service<MessageStorage, {
 }>()("effect/cluster/MessageStorage") {}
 
 /**
- * @since 4.0.0
+ * Result of saving a request or envelope into message storage.
+ *
+ * A duplicate result carries the original request ID and the last reply already
+ * received for the duplicated request.
+ *
  * @category SaveResult
+ * @since 4.0.0
  */
 export type SaveResult<R extends Rpc.Any> = SaveResult.Success | SaveResult.Duplicate<R>
 
 /**
- * @since 4.0.0
+ * Tagged enum constructor for creating and matching `SaveResult` values.
+ *
  * @category SaveResult
+ * @since 4.0.0
  */
 export const SaveResult = Data.taggedEnum<SaveResult.Constructor>()
 
 /**
- * @since 4.0.0
+ * Tagged enum constructor for encoded save results returned by encoded storage
+ * drivers.
+ *
  * @category SaveResult
+ * @since 4.0.0
  */
 export const SaveResultEncoded = Data.taggedEnum<SaveResult.Encoded>()
 
 /**
- * @since 4.0.0
+ * Variants and helper types for `SaveResult`.
+ *
  * @category SaveResult
+ * @since 4.0.0
  */
 export declare namespace SaveResult {
   /**
-   * @since 4.0.0
+   * Encoded storage-driver form of `SaveResult`.
+   *
+   * Duplicate results contain an encoded last received reply instead of a decoded
+   * reply.
+   *
    * @category SaveResult
+   * @since 4.0.0
    */
   export type Encoded = SaveResult.Success | SaveResult.DuplicateEncoded
 
   /**
-   * @since 4.0.0
+   * Variant indicating that the message was saved as a new storage entry.
+   *
    * @category SaveResult
+   * @since 4.0.0
    */
   export interface Success {
     readonly _tag: "Success"
   }
 
   /**
-   * @since 4.0.0
+   * Variant indicating that the request duplicates an existing stored request.
+   *
+   * It carries the original request ID and the latest decoded reply, when one is
+   * available.
+   *
    * @category SaveResult
+   * @since 4.0.0
    */
   export interface Duplicate<R extends Rpc.Any> {
     readonly _tag: "Duplicate"
@@ -198,8 +252,13 @@ export declare namespace SaveResult {
   }
 
   /**
-   * @since 4.0.0
+   * Encoded duplicate-save variant returned by lower-level storage drivers.
+   *
+   * It carries the original request ID and the latest encoded reply, when one is
+   * available.
+   *
    * @category SaveResult
+   * @since 4.0.0
    */
   export interface DuplicateEncoded {
     readonly _tag: "Duplicate"
@@ -208,8 +267,10 @@ export declare namespace SaveResult {
   }
 
   /**
-   * @since 4.0.0
+   * Generic tagged enum constructor type for `SaveResult`.
+   *
    * @category SaveResult
+   * @since 4.0.0
    */
   export interface Constructor extends Data.TaggedEnum.WithGenerics<1> {
     readonly taggedEnum: SaveResult<this["A"] extends Rpc.Any ? this["A"] : never>
@@ -217,8 +278,13 @@ export declare namespace SaveResult {
 }
 
 /**
- * @since 4.0.0
+ * Low-level storage-driver contract for encoded envelopes and replies.
+ *
+ * Implementations persist encoded messages, track primary keys and delayed
+ * delivery, read unprocessed messages, and provide transaction wrapping.
+ *
  * @category Encoded
+ * @since 4.0.0
  */
 export type Encoded = {
   /**
@@ -333,8 +399,13 @@ export type Encoded = {
 }
 
 /**
- * @since 4.0.0
+ * Cursor options for reading encoded unprocessed messages across shard sets.
+ *
+ * The fields distinguish existing shards from newly assigned shards and carry the
+ * driver-specific pagination cursor.
+ *
  * @category Encoded
+ * @since 4.0.0
  */
 export type EncodedUnprocessedOptions<A> = {
   readonly existingShards: Array<number>
@@ -343,8 +414,13 @@ export type EncodedUnprocessedOptions<A> = {
 }
 
 /**
- * @since 4.0.0
+ * Cursor options for reading encoded replies across request sets.
+ *
+ * The fields distinguish existing requests from new requests and carry the
+ * driver-specific pagination cursor.
+ *
  * @category Encoded
+ * @since 4.0.0
  */
 export type EncodedRepliesOptions<A> = {
   readonly existingRequests: Array<string>
@@ -353,8 +429,13 @@ export type EncodedRepliesOptions<A> = {
 }
 
 /**
- * @since 4.0.0
+ * Wraps a concrete message storage implementation with reply-handler management.
+ *
+ * The returned service can register waiting reply handlers, notify them when
+ * replies are saved, and fail them when a request or shard is unregistered.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (
   storage: Omit<
@@ -455,8 +536,14 @@ export const make = (
   })
 
 /**
- * @since 4.0.0
+ * Builds a `MessageStorage` service from an encoded storage driver.
+ *
+ * The adapter handles envelope and reply encoding and decoding, primary-key
+ * generation, delayed delivery checks, duplicate decoding, and malformed-message
+ * defect replies.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeEncoded: (encoded: Encoded) => Effect.Effect<
   MessageStorage["Service"],
@@ -663,8 +750,10 @@ export const makeEncoded: (encoded: Encoded) => Effect.Effect<
 })
 
 /**
- * @since 4.0.0
+ * No-op `MessageStorage` service that does not persist messages or replies.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const noop: MessageStorage["Service"] = Effect.runSync(make({
   saveRequest: () => Effect.succeed(SaveResult.Success()),
@@ -683,8 +772,13 @@ export const noop: MessageStorage["Service"] = Effect.runSync(make({
 }))
 
 /**
- * @since 4.0.0
+ * In-memory storage entry for a request envelope.
+ *
+ * It stores the encoded envelope, last acknowledged chunk, accumulated replies,
+ * and optional delivery time.
+ *
  * @category Memory
+ * @since 4.0.0
  */
 export type MemoryEntry = {
   readonly envelope: Envelope.Encoded
@@ -696,16 +790,22 @@ export type MemoryEntry = {
 /**
  * Can be used in tests to simulate a transaction.
  *
- * @since 4.0.0
  * @category Memory
+ * @since 4.0.0
  */
 export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/MessageStorage/MemoryTransaction", {
   defaultValue: constFalse
 })
 
 /**
- * @since 4.0.0
+ * In-memory message storage driver with inspectable backing state.
+ *
+ * It provides a `MessageStorage` service, the encoded driver implementation, and
+ * maps used to track requests, primary keys, unprocessed envelopes, reply IDs,
+ * and the journal.
+ *
  * @category Memory
+ * @since 4.0.0
  */
 export class MemoryDriver extends Context.Service<MemoryDriver>()("effect/cluster/MessageStorage/MemoryDriver", {
   make: Effect.gen(function*() {
@@ -908,6 +1008,8 @@ export class MemoryDriver extends Context.Service<MemoryDriver>()("effect/cluste
   })
 }) {
   /**
+   * Layer that provides the in-memory message storage driver.
+   *
    * @since 4.0.0
    */
   static readonly layer: Layer.Layer<MemoryDriver> = Layer.effect(this)(this.make).pipe(
@@ -916,20 +1018,24 @@ export class MemoryDriver extends Context.Service<MemoryDriver>()("effect/cluste
 }
 
 /**
- * @since 4.0.0
+ * Layer that provides the no-op `MessageStorage` service.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerNoop: Layer.Layer<MessageStorage> = Layer.succeed(MessageStorage, noop)
 
 /**
- * @since 4.0.0
+ * Layer that provides in-memory message storage and its backing `MemoryDriver`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerMemory: Layer.Layer<
   MessageStorage | MemoryDriver,
   never,
   ShardingConfig
-> = Layer.effect(MessageStorage, Effect.map(MemoryDriver.asEffect(), (_) => _.storage)).pipe(
+> = Layer.effect(MessageStorage, Effect.map(MemoryDriver, (_) => _.storage)).pipe(
   Layer.provideMerge(MemoryDriver.layer)
 )