effect 4.0.0-beta.66 → 4.0.0-beta.68

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"
 
 /**
+ * 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
- * @category Layers
  */
 export const layerClientProtocolHttp = (options: {
   readonly path: string
@@ -53,8 +82,10 @@ export const layerClientProtocolHttp = (options: {
   )
 
 /**
+ * Default HTTP runner client protocol layer using path `/`.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerClientProtocolHttpDefault: Layer.Layer<
   Runners.RpcClientProtocol,
@@ -63,8 +94,14 @@ export const layerClientProtocolHttpDefault: Layer.Layer<
 > = layerClientProtocolHttp({ path: "/" })
 
 /**
+ * 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
- * @category Layers
  */
 export const layerClientProtocolWebsocket = (options: {
   readonly path: string
@@ -94,8 +131,10 @@ export const layerClientProtocolWebsocket = (options: {
   )
 
 /**
+ * Default WebSocket runner client protocol layer using path `/`.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 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<
 })
 
 /**
+ * Layer that provides `Sharding` and `Runners` using the configured runner RPC
+ * client protocol and storage services.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 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`.
  *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerHttpOptions = (options: {
   readonly path: HttpRouter.PathInput
@@ -172,8 +224,11 @@ export const layerHttpOptions = (options: {
   )
 
 /**
+ * WebSocket layer for the `Runners` services that adds a route to the provided
+ * `HttpRouter`.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerWebsocketOptions = (options: {
   readonly path: HttpRouter.PathInput
@@ -193,8 +248,13 @@ export const layerWebsocketOptions = (options: {
   )
 
 /**
+ * Complete HTTP runner layer.
+ *
+ * It serves runner routes at `/` and configures runner clients to communicate
+ * over HTTP.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerHttp: Layer.Layer<
   Sharding.Sharding | Runners.Runners,
@@ -211,8 +271,13 @@ export const layerHttp: Layer.Layer<
 )
 
 /**
+ * Client-only HTTP runner layer.
+ *
+ * It configures runner clients to communicate over HTTP without serving runner
+ * HTTP routes.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerHttpClientOnly: Layer.Layer<
   Sharding.Sharding | Runners.Runners,
@@ -227,8 +292,13 @@ export const layerHttpClientOnly: Layer.Layer<
 )
 
 /**
+ * Complete WebSocket runner layer.
+ *
+ * It serves runner routes at `/` and configures runner clients to communicate
+ * over WebSocket.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerWebsocket: Layer.Layer<
   Sharding.Sharding | Runners.Runners,
@@ -245,8 +315,13 @@ export const layerWebsocket: Layer.Layer<
 )
 
 /**
+ * Client-only WebSocket runner layer.
+ *
+ * It configures runner clients to communicate over WebSocket without serving
+ * runner WebSocket routes.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 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") {}
 
 /**
+ * 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
- * @category Layers
  */
 export const layer: Layer.Layer<
   K8sHttpClient,
@@ -52,8 +78,13 @@ export const layer: Layer.Layer<
 )
 
 /**
+ * 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
- * @category Constructors
  */
 export const makeGetPods: (
   options?: {
@@ -93,8 +124,14 @@ export const makeGetPods: (
 })
 
 /**
+ * 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
- * @category Constructors
  */
 export const makeCreatePod = Effect.gen(function*() {
   const client = yield* K8sHttpClient
@@ -195,8 +232,10 @@ export const makeCreatePod = Effect.gen(function*() {
 })
 
 /**
+ * Schema for the subset of Kubernetes Pod status used by cluster helpers.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 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
 }) {}
 
 /**
+ * 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
- * @category Schemas
  */
 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
 
 /**
+ * Brands a number as a `MachineId`.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 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>,