effect 4.0.0-beta.66 → 4.0.0-beta.67

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"
 
 /**
- * @since 4.0.0
+ * Type identifier used to mark runtime cluster envelope values.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 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

package/src/unstable/cluster/HttpRunner.ts

@@ -1,4 +1,27 @@
 /**
+ * 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`.
+ *
+ * **Common tasks**
+ *
+ * - Serve runner RPC routes with {@link layerHttp} or {@link layerWebsocket}
+ * - Configure client-only runner communication with {@link layerHttpClientOnly}
+ *   or {@link layerWebsocketClientOnly}
+ * - Use custom route paths with {@link layerHttpOptions},
+ *   {@link layerWebsocketOptions}, {@link layerClientProtocolHttp}, or
+ *   {@link layerClientProtocolWebsocket}
+ *
+ * **Transport 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
+ *   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
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -24,8 +47,14 @@ import * as Sharding from "./Sharding.ts"
 import type * as ShardingConfig from "./ShardingConfig.ts"
 
 /**
- * @since 4.0.0
+ * Provides a runner RPC client protocol that connects to runner addresses over
+ * HTTP.
+ *
+ * The configured path is appended to each runner address, and `https` switches
+ * the generated URL from `http` to `https`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerClientProtocolHttp = (options: {
   readonly path: string
@@ -53,8 +82,10 @@ export const layerClientProtocolHttp = (options: {
   )
 
 /**
- * @since 4.0.0
+ * Default HTTP runner client protocol layer using path `/`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerClientProtocolHttpDefault: Layer.Layer<
   Runners.RpcClientProtocol,
@@ -63,8 +94,14 @@ export const layerClientProtocolHttpDefault: Layer.Layer<
 > = layerClientProtocolHttp({ path: "/" })
 
 /**
- * @since 4.0.0
+ * Provides a runner RPC client protocol that connects to runner addresses over
+ * WebSocket.
+ *
+ * The configured path is appended to each runner address, and `https` switches
+ * the generated URL from `ws` to `wss`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerClientProtocolWebsocket = (options: {
   readonly path: string
@@ -94,8 +131,10 @@ export const layerClientProtocolWebsocket = (options: {
   )
 
 /**
- * @since 4.0.0
+ * Default WebSocket runner client protocol layer using path `/`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerClientProtocolWebsocketDefault: Layer.Layer<
   Runners.RpcClientProtocol,
@@ -104,8 +143,13 @@ export const layerClientProtocolWebsocketDefault: Layer.Layer<
 > = layerClientProtocolWebsocket({ path: "/" })
 
 /**
- * @since 4.0.0
+ * Builds an HTTP effect that serves runner RPCs over the HTTP protocol.
+ *
+ * The returned effect is produced from `RunnerServer.layerHandlers` and the
+ * cluster runner RPC group.
+ *
  * @category Http App
+ * @since 4.0.0
  */
 export const toHttpEffect: Effect.Effect<
   Effect.Effect<HttpServerResponse, never, Scope | HttpServerRequest>,
@@ -120,8 +164,13 @@ export const toHttpEffect: Effect.Effect<
 })
 
 /**
- * @since 4.0.0
+ * Builds an HTTP effect that serves runner RPCs over WebSocket.
+ *
+ * The returned effect is produced from `RunnerServer.layerHandlers` and the
+ * cluster runner RPC group.
+ *
  * @category Http App
+ * @since 4.0.0
  */
 export const toHttpEffectWebsocket: Effect.Effect<
   Effect.Effect<HttpServerResponse, never, Scope | HttpServerRequest>,
@@ -136,8 +185,11 @@ export const toHttpEffectWebsocket: Effect.Effect<
 })
 
 /**
- * @since 4.0.0
+ * Layer that provides `Sharding` and `Runners` using the configured runner RPC
+ * client protocol and storage services.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerClient: Layer.Layer<
   Sharding.Sharding | Runners.Runners,
@@ -151,8 +203,8 @@ export const layerClient: Layer.Layer<
  * A HTTP layer for the `Runners` services, that adds a route to the provided
  * `HttpRouter`.
  *
- * @since 4.0.0
  * @category Layers
+ * @since 4.0.0
  */
 export const layerHttpOptions = (options: {
   readonly path: HttpRouter.PathInput
@@ -172,8 +224,11 @@ export const layerHttpOptions = (options: {
   )
 
 /**
- * @since 4.0.0
+ * WebSocket layer for the `Runners` services that adds a route to the provided
+ * `HttpRouter`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerWebsocketOptions = (options: {
   readonly path: HttpRouter.PathInput
@@ -193,8 +248,13 @@ export const layerWebsocketOptions = (options: {
   )
 
 /**
- * @since 4.0.0
+ * Complete HTTP runner layer.
+ *
+ * It serves runner routes at `/` and configures runner clients to communicate
+ * over HTTP.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerHttp: Layer.Layer<
   Sharding.Sharding | Runners.Runners,
@@ -211,8 +271,13 @@ export const layerHttp: Layer.Layer<
 )
 
 /**
- * @since 4.0.0
+ * Client-only HTTP runner layer.
+ *
+ * It configures runner clients to communicate over HTTP without serving runner
+ * HTTP routes.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerHttpClientOnly: Layer.Layer<
   Sharding.Sharding | Runners.Runners,
@@ -227,8 +292,13 @@ export const layerHttpClientOnly: Layer.Layer<
 )
 
 /**
- * @since 4.0.0
+ * Complete WebSocket runner layer.
+ *
+ * It serves runner routes at `/` and configures runner clients to communicate
+ * over WebSocket.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerWebsocket: Layer.Layer<
   Sharding.Sharding | Runners.Runners,
@@ -245,8 +315,13 @@ export const layerWebsocket: Layer.Layer<
 )
 
 /**
- * @since 4.0.0
+ * Client-only WebSocket runner layer.
+ *
+ * It configures runner clients to communicate over WebSocket without serving
+ * runner WebSocket routes.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerWebsocketClientOnly: Layer.Layer<
   Sharding.Sharding | Runners.Runners,

package/src/unstable/cluster/K8sHttpClient.ts

@@ -1,4 +1,22 @@
 /**
+ * The `K8sHttpClient` module provides an HTTP client service for talking to the
+ * Kubernetes API from code running inside a cluster.
+ *
+ * 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.
+ *
+ * **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.
+ *
  * @since 4.0.0
  */
 import type * as v1 from "kubernetes-types/core/v1.d.ts"
@@ -17,8 +35,10 @@ import * as HttpClientRequest from "../http/HttpClientRequest.ts"
 import * as HttpClientResponse from "../http/HttpClientResponse.ts"
 
 /**
- * @since 4.0.0
+ * Service tag for the HTTP client used to call the Kubernetes API.
+ *
  * @category Tags
+ * @since 4.0.0
  */
 export class K8sHttpClient extends Context.Service<
   K8sHttpClient,
@@ -26,8 +46,14 @@ export class K8sHttpClient extends Context.Service<
 >()("effect/cluster/K8sHttpClient") {}
 
 /**
- * @since 4.0.0
+ * Layer that configures `K8sHttpClient` for the in-cluster Kubernetes API.
+ *
+ * It targets `https://kubernetes.default.svc/api`, adds the service-account
+ * bearer token when available, requires successful HTTP statuses, and retries
+ * transient failures.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<
   K8sHttpClient,
@@ -52,8 +78,13 @@ export const layer: Layer.Layer<
 )
 
 /**
- * @since 4.0.0
+ * Creates a cached effect that fetches running Kubernetes pods.
+ *
+ * The request can be limited by namespace and label selector, and the result is a
+ * map keyed by pod IP address.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const makeGetPods: (
   options?: {
@@ -93,8 +124,14 @@ export const makeGetPods: (
 })
 
 /**
- * @since 4.0.0
+ * Creates a scoped function that ensures a Kubernetes pod exists and waits until
+ * it is ready.
+ *
+ * The pod defaults to the `default` namespace and is deleted when the surrounding
+ * scope closes.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const makeCreatePod = Effect.gen(function*() {
   const client = yield* K8sHttpClient
@@ -195,8 +232,10 @@ export const makeCreatePod = Effect.gen(function*() {
 })
 
 /**
- * @since 4.0.0
+ * Schema for the subset of Kubernetes Pod status used by cluster helpers.
+ *
  * @category Schemas
+ * @since 4.0.0
  */
 export class PodStatus extends Schema.Class<PodStatus>("@effect/cluster/K8sHttpClient/PodStatus")({
   phase: Schema.String,
@@ -210,8 +249,12 @@ export class PodStatus extends Schema.Class<PodStatus>("@effect/cluster/K8sHttpC
 }) {}
 
 /**
- * @since 4.0.0
+ * Schema for Kubernetes Pod values used by cluster helpers.
+ *
+ * The model exposes readiness helpers derived from the pod status conditions.
+ *
  * @category Schemas
+ * @since 4.0.0
  */
 export class Pod extends Schema.Class<Pod>("@effect/cluster/K8sHttpClient/Pod")({
   status: PodStatus

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