@effect/platform-node 4.0.0-beta.66 → 4.0.0-beta.68

package/src/NodeClusterSocket.ts

@@ -1,5 +1,34 @@
 /**
- * @since 1.0.0
+ * The `NodeClusterSocket` module provides the Node.js socket transport for
+ * Effect Cluster runners. It wires `SocketRunner` to Node TCP sockets, supplies
+ * RPC client and server protocol layers, and builds a complete sharding layer
+ * with serialization, runner health, runner storage, and message storage.
+ *
+ * **Common tasks**
+ *
+ * - Run a Node process as a cluster runner over raw TCP sockets with
+ *   {@link layer}
+ * - Connect a client-only process to an existing socket cluster without
+ *   starting a runner server
+ * - Use SQL-backed storage for durable multi-process clusters, `local` storage
+ *   for short-lived development, or `byo` storage when the deployment owns the
+ *   persistence boundary
+ * - Check runner health with socket pings or Kubernetes pod readiness through
+ *   {@link layerK8sHttpClient}
+ *
+ * **Gotchas**
+ *
+ * - `runnerAddress` is the host and port advertised to other runners; set
+ *   `runnerListenAddress` when the local bind address differs from the
+ *   externally reachable address
+ * - The socket transport is point-to-point RPC, not cluster gossip: runner
+ *   membership, shard ownership, and persisted delivery are coordinated through
+ *   `RunnerStorage`, `MessageStorage`, and `RunnerHealth`
+ * - `clientOnly` does not start a socket server or receive shard assignments
+ * - Ping health checks use the same socket protocol, so unreachable ports,
+ *   firewalls, or serialization mismatches can make a runner appear unhealthy
+ *
+ * @since 4.0.0
  */
 import { layerClientProtocol, layerSocketServer } from "@effect/platform-node-shared/NodeClusterSocket"
 import type { ConfigError } from "effect/Config"
@@ -25,20 +54,24 @@ import * as Undici from "./Undici.ts"
 
 export {
   /**
-   * @since 1.0.0
-   * @category Re-exports
+   * @category re-exports
+   * @since 4.0.0
    */
   layerClientProtocol,
   /**
-   * @since 1.0.0
-   * @category Re-exports
+   * @category re-exports
+   * @since 4.0.0
    */
   layerSocketServer
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Builds the Node cluster socket sharding layer, configuring RPC
+ * serialization, message storage, runner health checks, and optional
+ * client-only mode.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = <
   const ClientOnly extends boolean = false,
@@ -111,8 +144,12 @@ export const layer = <
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides an Undici dispatcher for Kubernetes API calls, using the service
+ * account CA certificate when it is available and falling back to the default
+ * dispatcher otherwise.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerDispatcherK8s: Layer.Layer<NodeHttpClient.Dispatcher> = Layer.effect(NodeHttpClient.Dispatcher)(
   Effect.gen(function*() {
@@ -140,8 +177,11 @@ export const layerDispatcherK8s: Layer.Layer<NodeHttpClient.Dispatcher> = Layer.
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides a `K8sHttpClient` backed by the Undici HTTP client and the
+ * Kubernetes-aware dispatcher.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerK8sHttpClient: Layer.Layer<K8sHttpClient.K8sHttpClient> = K8sHttpClient.layer.pipe(
   Layer.provide(Layer.fresh(NodeHttpClient.layerUndiciNoDispatcher)),

package/src/NodeCrypto.ts

@@ -0,0 +1,16 @@
+/**
+ * Node.js platform Crypto service layer.
+ *
+ * @since 1.0.0
+ */
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+import type * as Crypto from "effect/Crypto"
+import type * as Layer from "effect/Layer"
+
+/**
+ * A layer that provides the Node.js Crypto service implementation.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer: Layer.Layer<Crypto.Crypto> = NodeCrypto.layer

package/src/NodeFileSystem.ts

@@ -1,12 +1,31 @@
 /**
- * @since 1.0.0
+ * Provides the Node.js `FileSystem` layer for Effect programs.
+ *
+ * Use this module when a Node application, CLI, script, or test needs to
+ * satisfy the `FileSystem` service with real filesystem access for reading and
+ * writing files, creating directories and temporary files, inspecting metadata,
+ * managing links, or watching paths for changes.
+ *
+ * This module only exposes the Node-backed layer; filesystem operations are
+ * accessed through the `FileSystem` service from `effect/FileSystem`. Provide
+ * `NodeFileSystem.layer` at the edge of the program, or use
+ * `NodeServices.layer` when you also want the standard Node path, stdio,
+ * terminal, and child process services. The implementation is shared with
+ * other Node-compatible platform packages, so optional services such as
+ * `FileSystem.WatchBackend` are honored when present; otherwise file watching
+ * follows Node's `node:fs.watch` behavior. Paths are interpreted by Node, so
+ * relative paths use the current working directory and platform path rules.
+ *
+ * @since 4.0.0
  */
 import * as NodeFileSystem from "@effect/platform-node-shared/NodeFileSystem"
 import type { FileSystem } from "effect/FileSystem"
 import type * as Layer from "effect/Layer"
 
 /**
- * @since 1.0.0
- * @category layer
+ * Provides the `FileSystem` service backed by Node filesystem APIs.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<FileSystem> = NodeFileSystem.layer

package/src/NodeHttpClient.ts

@@ -1,5 +1,31 @@
 /**
- * @since 1.0.0
+ * Node.js implementations of the Effect `HttpClient`.
+ *
+ * This module provides the Node-specific layers and constructors for sending
+ * Effect HTTP client requests. It re-exports the fetch-based client for
+ * programs that want to use `globalThis.fetch`, provides an Undici-backed
+ * client for applications that need Undici dispatcher control, and provides a
+ * lower-level `node:http` / `node:https` client for integrations that need
+ * native Node agent configuration.
+ *
+ * Use these clients in server-side applications, CLIs, tests, and integrations
+ * where requests should participate in Effect resource management, interruption,
+ * streaming, and typed transport / decode errors. The Undici path sends each
+ * request through the current `Dispatcher`; `layerUndici` owns a scoped
+ * `Agent`, while `dispatcherLayerGlobal` uses Undici's process-global dispatcher
+ * without destroying it. The `node:http` path uses separate scoped HTTP and
+ * HTTPS agents, making it the right choice when native agent options such as
+ * TLS, proxy, keep-alive, or socket behavior need to be configured directly.
+ *
+ * The backends are not completely interchangeable. Fetch, Undici, and
+ * `node:http` expose different agent and dispatcher hooks, body implementations,
+ * abort behavior, upgrade support, and response body readers. This module
+ * converts Effect request bodies to the selected runtime representation:
+ * streams remain streaming, `FormData` may contribute generated content headers,
+ * and body read failures are reported as `HttpClientError` decode or transport
+ * errors.
+ *
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -36,18 +62,18 @@ import * as Undici from "./Undici.ts"
 
 export {
   /**
-   * @since 1.0.0
    * @category Fetch
+   * @since 4.0.0
    */
   Fetch,
   /**
-   * @since 1.0.0
    * @category Fetch
+   * @since 4.0.0
    */
   layer as layerFetch,
   /**
-   * @since 1.0.0
    * @category Fetch
+   * @since 4.0.0
    */
   RequestInit
 } from "effect/unstable/http/FetchHttpClient"
@@ -57,16 +83,22 @@ export {
 // -----------------------------------------------------------------------------
 
 /**
- * @since 1.0.0
+ * Service tag for the Undici `Dispatcher` used by the Undici-backed HTTP
+ * client.
+ *
  * @category Dispatcher
+ * @since 4.0.0
  */
 export class Dispatcher extends Context.Service<Dispatcher, Undici.Dispatcher>()(
   "@effect/platform-node/NodeHttpClient/Dispatcher"
 ) {}
 
 /**
- * @since 1.0.0
+ * Acquires a new Undici `Agent` dispatcher and destroys it when the enclosing
+ * scope is finalized.
+ *
  * @category Dispatcher
+ * @since 4.0.0
  */
 export const makeDispatcher: Effect.Effect<Undici.Dispatcher, never, Scope.Scope> = Effect.acquireRelease(
   Effect.sync(() => new Undici.Agent()),
@@ -74,20 +106,28 @@ export const makeDispatcher: Effect.Effect<Undici.Dispatcher, never, Scope.Scope
 )
 
 /**
- * @since 1.0.0
+ * Provides the `Dispatcher` service using a scoped Undici `Agent`.
+ *
  * @category Dispatcher
+ * @since 4.0.0
  */
 export const layerDispatcher: Layer.Layer<Dispatcher> = Layer.effect(Dispatcher)(makeDispatcher)
 
 /**
- * @since 1.0.0
+ * Provides the `Dispatcher` service from Undici's process-global dispatcher,
+ * without creating or owning a new agent.
+ *
  * @category Dispatcher
+ * @since 4.0.0
  */
 export const dispatcherLayerGlobal: Layer.Layer<Dispatcher> = Layer.sync(Dispatcher)(() => Undici.getGlobalDispatcher())
 
 /**
- * @since 1.0.0
+ * Fiber reference containing default Undici request options applied to requests
+ * sent by `makeUndici`.
+ *
  * @category undici
+ * @since 4.0.0
  */
 export const UndiciOptions = Context.Reference<Partial<Undici.Dispatcher.RequestOptions>>(
   "@effect/platform-node/NodeHttpClient/UndiciOptions",
@@ -95,8 +135,12 @@ export const UndiciOptions = Context.Reference<Partial<Undici.Dispatcher.Request
 )
 
 /**
- * @since 1.0.0
+ * Creates an `HttpClient` that sends requests through the current Undici
+ * `Dispatcher`, converts Effect HTTP bodies to Undici bodies, and maps
+ * transport and decode failures to `HttpClientError`.
+ *
  * @category undici
+ * @since 4.0.0
  */
 export const makeUndici = Effect.gen(function*() {
   const dispatcher = yield* Dispatcher
@@ -309,8 +353,11 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse, Pi
 }
 
 /**
- * @since 1.0.0
+ * Provides an Undici-backed `HttpClient` using the current `Dispatcher`
+ * service.
+ *
  * @category Undici
+ * @since 4.0.0
  */
 export const layerUndiciNoDispatcher: Layer.Layer<
   Client.HttpClient,
@@ -319,8 +366,11 @@ export const layerUndiciNoDispatcher: Layer.Layer<
 > = Client.layerMergedContext(makeUndici)
 
 /**
- * @since 1.0.0
+ * Provides an Undici-backed `HttpClient` together with a scoped default
+ * Undici `Agent` dispatcher.
+ *
  * @category Undici
+ * @since 4.0.0
  */
 export const layerUndici: Layer.Layer<Client.HttpClient> = Layer.provide(layerUndiciNoDispatcher, layerDispatcher)
 
@@ -329,8 +379,11 @@ export const layerUndici: Layer.Layer<Client.HttpClient> = Layer.provide(layerUn
 // -----------------------------------------------------------------------------
 
 /**
- * @since 1.0.0
+ * Service tag for the paired Node `http` and `https` agents used by the
+ * node:http-backed HTTP client.
+ *
  * @category HttpAgent
+ * @since 4.0.0
  */
 export class HttpAgent extends Context.Service<HttpAgent, {
   readonly http: Http.Agent
@@ -338,8 +391,11 @@ export class HttpAgent extends Context.Service<HttpAgent, {
 }>()("@effect/platform-node/NodeHttpClient/HttpAgent") {}
 
 /**
- * @since 1.0.0
+ * Acquires Node `http` and `https` agents with the supplied options and
+ * destroys both agents when the enclosing scope is finalized.
+ *
  * @category HttpAgent
+ * @since 4.0.0
  */
 export const makeAgent = (options?: Https.AgentOptions): Effect.Effect<HttpAgent["Service"], never, Scope.Scope> =>
   Effect.zipWith(
@@ -355,22 +411,32 @@ export const makeAgent = (options?: Https.AgentOptions): Effect.Effect<HttpAgent
   )
 
 /**
- * @since 1.0.0
+ * Provides the `HttpAgent` service using scoped Node `http` and `https`
+ * agents configured with the supplied options.
+ *
  * @category HttpAgent
+ * @since 4.0.0
  */
 export const layerAgentOptions: (options?: Https.AgentOptions | undefined) => Layer.Layer<
   HttpAgent
 > = flow(makeAgent, Layer.effect(HttpAgent))
 
 /**
- * @since 1.0.0
+ * Provides the `HttpAgent` service using default scoped Node `http` and
+ * `https` agents.
+ *
  * @category HttpAgent
+ * @since 4.0.0
  */
 export const layerAgent: Layer.Layer<HttpAgent> = layerAgentOptions()
 
 /**
- * @since 1.0.0
+ * Creates an `HttpClient` backed by Node `http` and `https`, using the
+ * current `HttpAgent`, streaming request bodies, and wrapping Node responses
+ * as `HttpClientResponse` values.
+ *
  * @category node:http
+ * @since 4.0.0
  */
 export const makeNodeHttp = Effect.gen(function*() {
   const agent = yield* HttpAgent
@@ -579,8 +645,11 @@ class NodeHttpResponse extends NodeHttpIncomingMessage<Error.HttpClientError> im
 }
 
 /**
- * @since 1.0.0
+ * Provides a node:http-backed `HttpClient` using the current `HttpAgent`
+ * service.
+ *
  * @category node:http
+ * @since 4.0.0
  */
 export const layerNodeHttpNoAgent: Layer.Layer<
   Client.HttpClient,
@@ -589,7 +658,10 @@ export const layerNodeHttpNoAgent: Layer.Layer<
 > = Client.layerMergedContext(makeNodeHttp)
 
 /**
- * @since 1.0.0
+ * Provides a node:http-backed `HttpClient` together with default scoped Node
+ * `http` and `https` agents.
+ *
  * @category node:http
+ * @since 4.0.0
  */
 export const layerNodeHttp: Layer.Layer<Client.HttpClient> = Layer.provide(layerNodeHttpNoAgent, layerAgent)

package/src/NodeHttpIncomingMessage.ts

@@ -1,5 +1,17 @@
 /**
- * @since 1.0.0
+ * Utilities for adapting Node `http.IncomingMessage` values to the Effect HTTP
+ * incoming message interface used by the platform Node server and client
+ * implementations.
+ *
+ * This module is useful when code needs to keep access to Node's request or
+ * response object while also exposing Effect's typed headers, remote address,
+ * body decoders, and stream interface. The body helpers consume Node's readable
+ * stream, cache decoded text and array-buffer results, and honor the
+ * `HttpIncomingMessage.MaxBodySize` fiber ref. Prefer a single body access
+ * strategy per message: raw `stream` access is not cached, and Node request
+ * bodies cannot be replayed once the underlying stream has been consumed.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Inspectable from "effect/Inspectable"
@@ -13,14 +25,20 @@ import type * as Http from "node:http"
 import * as NodeStream from "./NodeStream.ts"
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Base adapter from Node `IncomingMessage` to Effect HTTP incoming messages,
+ * exposing headers, remote address, stream access, and cached text, JSON, URL
+ * parameter, and array-buffer body decoders with caller-provided error mapping.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export abstract class NodeHttpIncomingMessage<E> extends Inspectable.Class
   implements IncomingMessage.HttpIncomingMessage<E>
 {
   /**
-   * @since 1.0.0
+   * Marks this value as an HTTP incoming message for runtime guards.
+   *
+   * @since 4.0.0
    */
   readonly [IncomingMessage.TypeId]: typeof IncomingMessage.TypeId
   readonly source: Http.IncomingMessage

package/src/NodeHttpPlatform.ts

@@ -1,5 +1,26 @@
 /**
- * @since 1.0.0
+ * Node.js implementation of the Effect HTTP platform service.
+ *
+ * This module connects the portable `HttpPlatform` file response helpers to
+ * Node runtime primitives. It is used by Node HTTP servers and static file
+ * handlers when returning local files, public assets, downloads, byte ranges,
+ * or Web `File` values as `HttpServerResponse` bodies.
+ *
+ * Path-based responses are served with `node:fs.createReadStream`; Web `File`
+ * responses are bridged with `Readable.fromWeb`. The implementation fills in
+ * `content-type` from `Mime`, falls back to `application/octet-stream`, and
+ * writes the `content-length` for the selected range or whole file. Node's
+ * stream `end` option is inclusive, so the platform converts Effect's half-open
+ * range before reading. Empty bodies use an empty readable stream.
+ *
+ * Provide `layer` at the Node runtime edge when file responses, static serving,
+ * or response bodies created from files need real filesystem and ETag support.
+ * These responses are raw Node streams, so they are intended for the Node HTTP
+ * server adapter; keep files available until the response body has been
+ * consumed and prefer the portable `HttpServerResponse` constructors when a
+ * response does not depend on Node file or stream behavior.
+ *
+ * @since 4.0.0
  */
 import { pipe } from "effect/Function"
 import * as Layer from "effect/Layer"
@@ -13,8 +34,11 @@ import Mime from "./Mime.ts"
 import * as NodeFileSystem from "./NodeFileSystem.ts"
 
 /**
- * @since 1.0.0
- * @category Constructors
+ * Creates the Node `HttpPlatform`, serving file responses from Node readable
+ * streams and adding MIME type and content-length headers when needed.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = Platform.make({
   fileResponse(path, status, statusText, headers, start, end, contentLength) {
@@ -47,8 +71,11 @@ export const make = Platform.make({
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the Node `HttpPlatform` together with the filesystem and ETag
+ * services it needs for file responses.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Platform.HttpPlatform> = pipe(
   Layer.effect(Platform.HttpPlatform)(make),

package/src/NodeHttpServer.ts

@@ -1,5 +1,34 @@
 /**
- * @since 1.0.0
+ * Node.js implementation of the Effect `HttpServer`.
+ *
+ * This module adapts a supplied Node `http.Server` into Effect's
+ * platform-independent HTTP server service. It starts the server with Node
+ * `listen` options, converts `request` events into `HttpServerRequest` values,
+ * writes `HttpServerResponse` bodies through Node's `ServerResponse`, and
+ * handles `upgrade` events by exposing the upgraded socket through
+ * `HttpServerRequest.upgrade`.
+ *
+ * Common use cases include serving an Effect HTTP application with {@link layer}
+ * or {@link layerConfig}, embedding request or upgrade handlers into an
+ * existing Node server with {@link makeHandler} and {@link makeUpgradeHandler},
+ * and using {@link layerTest} for integration tests that need an ephemeral
+ * listening port and a client pointed at it.
+ *
+ * Listen options are passed directly to Node, so host, port, backlog, and Unix
+ * socket path behavior follow `node:http`. The server begins listening when the
+ * `HttpServer` is acquired, and handlers are installed when `serve` is run.
+ * Request fibers are interrupted with `ClientAbort` when the client disconnects
+ * before a response finishes. WebSocket support only applies to Node `upgrade`
+ * requests, and ordinary HTTP requests fail if their application attempts to use
+ * `HttpServerRequest.upgrade`.
+ *
+ * Scope ownership is important: the server is closed when the acquiring scope
+ * finalizes, while each `serve` call installs its own request and upgrade
+ * listeners and removes them on finalization. Unless preemptive shutdown is
+ * disabled, finalizing a serve scope also starts a graceful server close, using
+ * the configured timeout or the default timeout.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Config from "effect/Config"
@@ -52,8 +81,12 @@ import * as NodeServices from "./NodeServices.ts"
 import { NodeWS } from "./NodeSocket.ts"
 
 /**
- * @since 1.0.0
+ * Creates a scoped `HttpServer` from a Node `http.Server`, starts listening
+ * with the supplied options, registers request and upgrade handling, and closes
+ * the server during scope finalization with optional graceful-shutdown control.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*(
   evaluate: LazyArg<Http.Server>,
@@ -145,8 +178,12 @@ export const make = Effect.fnUntraced(function*(
 })
 
 /**
- * @since 1.0.0
+ * Creates a Node `request` event handler for an Effect HTTP application,
+ * injecting a `HttpServerRequest` and interrupting the request fiber if the
+ * client closes the response before it finishes.
+ *
  * @category Handlers
+ * @since 4.0.0
  */
 export const makeHandler = <
   R,
@@ -183,8 +220,12 @@ export const makeHandler = <
 }
 
 /**
- * @since 1.0.0
+ * Creates a Node `upgrade` event handler for an Effect HTTP application,
+ * exposing the upgraded WebSocket as the request's `upgrade` effect and
+ * interrupting the request fiber when the socket closes early.
+ *
  * @category Handlers
+ * @since 4.0.0
  */
 export const makeUpgradeHandler = <
   R,
@@ -366,8 +407,11 @@ class ServerRequestImpl extends NodeHttpIncomingMessage<HttpServerError> impleme
 }
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides an `HttpServer` by creating and managing a scoped Node
+ * `http.Server` with the supplied listen and shutdown options.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerServer: (
   evaluate: LazyArg<Http.Server<typeof Http.IncomingMessage, typeof Http.ServerResponse>>,
@@ -378,8 +422,11 @@ export const layerServer: (
 ) => Layer.Layer<HttpServer.HttpServer, ServeError> = flow(make, Layer.effect(HttpServer.HttpServer))
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the Node HTTP support services used by `NodeHttpServer`, including
+ * the HTTP platform, ETag generator, and core Node platform services.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerHttpServices: Layer.Layer<
   NodeServices.NodeServices | HttpPlatform.HttpPlatform | Etag.Generator
@@ -390,8 +437,11 @@ export const layerHttpServices: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides a Node `HttpServer` together with the Node HTTP platform, ETag, and
+ * core platform services required to serve requests.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   evaluate: LazyArg<Http.Server>,
@@ -409,8 +459,11 @@ export const layer = (
   )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides a Node `HttpServer` and HTTP support services, reading the listen
+ * and shutdown options from a `Config` value.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (
   evaluate: LazyArg<Http.Server>,
@@ -432,8 +485,11 @@ export const layerConfig = (
   )
 
 /**
- * @since 1.0.0
+ * Provides a test HTTP server listening on an ephemeral port together with a
+ * Fetch-backed `HttpClient` configured for server integration tests.
+ *
  * @category Testing
+ * @since 4.0.0
  */
 export const layerTest: Layer.Layer<
   | HttpServer.HttpServer

package/src/NodeHttpServerRequest.ts

@@ -1,18 +1,44 @@
 /**
- * @since 1.0.0
+ * Accessors for the Node.js objects backing a platform Node
+ * `HttpServerRequest`.
+ *
+ * Use this module at interop boundaries when an Effect HTTP handler needs the
+ * original `http.IncomingMessage` or `http.ServerResponse` for APIs that are
+ * specific to Node, such as existing middleware, socket inspection, raw stream
+ * piping, or response customization that cannot be expressed with the portable
+ * `HttpServerRequest` and `HttpServerResponse` interfaces.
+ *
+ * The returned request is the original Node request supplied to the server. It
+ * does not reflect Effect request overrides made by middleware, such as a
+ * rewritten URL, adjusted headers, or a substituted remote address. Its body is
+ * also Node's one-shot readable stream, so avoid mixing raw stream consumption
+ * with Effect body, multipart, or stream helpers unless ownership of the body
+ * is clear. The returned response is the Node response owned by the platform
+ * server; writing to it directly bypasses the usual Effect response writer and
+ * must be coordinated carefully to avoid duplicate writes. Upgrade requests may
+ * create that response lazily when it is first requested.
+ *
+ * @since 4.0.0
  */
 import type { HttpServerRequest } from "effect/unstable/http/HttpServerRequest"
 import type * as Http from "node:http"
 
 /**
- * @since 1.0.0
+ * Returns the underlying Node `IncomingMessage` for a platform Node
+ * `HttpServerRequest`.
+ *
  * @category Accessors
+ * @since 4.0.0
  */
 export const toIncomingMessage = (self: HttpServerRequest): Http.IncomingMessage => self.source as any
 
 /**
- * @since 1.0.0
+ * Returns the underlying Node `ServerResponse` for a platform Node
+ * `HttpServerRequest`, evaluating the stored response thunk when the response
+ * was created lazily.
+ *
  * @category Accessors
+ * @since 4.0.0
  */
 export const toServerResponse = (self: HttpServerRequest): Http.ServerResponse => {
   const res = (self as any).response