@effect/platform-node 4.0.0-beta.7 → 4.0.0-beta.71

package/src/NodeHttpClient.ts

@@ -1,12 +1,50 @@
 /**
- * @since 1.0.0
+ * Node.js implementations of the Effect `HttpClient`.
+ *
+ * This module supplies Node runtime backends for the platform-independent
+ * Effect HTTP client API. It re-exports the fetch-based client, defines an
+ * Undici-backed client, and defines a lower-level `node:http` / `node:https`
+ * client for integrations that need native agent configuration.
+ *
+ * **Mental model**
+ *
+ * All backends provide the same `HttpClient` service, so application code can
+ * depend on the Effect HTTP client interface while the layer chooses the Node
+ * implementation. The difference is where request execution and connection
+ * ownership live: fetch uses `globalThis.fetch`, Undici sends through a
+ * `Dispatcher`, and the `node:http` backend sends through scoped HTTP and HTTPS
+ * agents.
+ *
+ * **Common tasks**
+ *
+ * Use `layerFetch` when the built-in fetch implementation is enough. Use
+ * `layerUndici` for a scoped Undici `Agent`, or `layerUndiciNoDispatcher` when
+ * the caller provides the `Dispatcher` service, including the process-global
+ * dispatcher from `dispatcherLayerGlobal`. Use `layerNodeHttp` or
+ * `layerAgentOptions` when TLS, proxy, keep-alive, socket, or other native
+ * Node agent options must be configured directly.
+ *
+ * **Gotchas**
+ *
+ * Fetch, Undici, and `node:http` are not exact substitutes. They differ in
+ * dispatcher and agent hooks, request body support, abort behavior, upgrade
+ * support, and response body readers. Scoped layers destroy the agents or
+ * dispatchers they create when the layer scope ends; `dispatcherLayerGlobal`
+ * intentionally does not own or destroy Undici's process-global dispatcher.
+ * 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"
 import { flow } from "effect/Function"
 import * as Inspectable from "effect/Inspectable"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import { type Pipeable, pipeArguments } from "effect/Pipeable"
+import type * as Schema from "effect/Schema"
 import type * as Scope from "effect/Scope"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import * as Cookies from "effect/unstable/http/Cookies"
 import * as Headers from "effect/unstable/http/Headers"
@@ -33,18 +71,24 @@ import * as Undici from "./Undici.ts"
 
 export {
   /**
-   * @since 1.0.0
+   * Fetch-based HTTP client implementation for Node.js.
+   *
    * @category Fetch
+   * @since 4.0.0
    */
   Fetch,
   /**
-   * @since 1.0.0
+   * Layer that provides the fetch-based HTTP client implementation.
+   *
    * @category Fetch
+   * @since 4.0.0
    */
   layer as layerFetch,
   /**
-   * @since 1.0.0
+   * Request initialization options accepted by the fetch-based HTTP client.
+   *
    * @category Fetch
+   * @since 4.0.0
    */
   RequestInit
 } from "effect/unstable/http/FetchHttpClient"
@@ -54,16 +98,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 ServiceMap.Service<Dispatcher, Undici.Dispatcher>()(
+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()),
@@ -71,29 +121,41 @@ 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 = ServiceMap.Reference<Partial<Undici.Dispatcher.RequestOptions>>(
+export const UndiciOptions = Context.Reference<Partial<Undici.Dispatcher.RequestOptions>>(
   "@effect/platform-node/NodeHttpClient/UndiciOptions",
   { defaultValue: () => ({}) }
 )
 
 /**
- * @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
@@ -150,7 +212,7 @@ function convertBody(
 
 function noopErrorHandler(_: any) {}
 
-class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
+class UndiciResponse extends Inspectable.Class implements HttpClientResponse, Pipeable {
   readonly [IncomingMessage.TypeId]: typeof IncomingMessage.TypeId
   readonly [Response.TypeId]: typeof Response.TypeId
   readonly request: HttpClientRequest
@@ -189,8 +251,8 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
     return this.cachedCookies = header ? Cookies.fromSetCookie(header) : Cookies.empty
   }
 
-  get remoteAddress(): string | undefined {
-    return undefined
+  get remoteAddress(): Option.Option<string> {
+    return Option.none()
   }
 
   get stream(): Stream.Stream<Uint8Array, Error.HttpClientError> {
@@ -207,10 +269,10 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
     })
   }
 
-  get json(): Effect.Effect<unknown, Error.HttpClientError> {
+  get json(): Effect.Effect<Schema.Json, Error.HttpClientError> {
     return Effect.flatMap(this.text, (text) =>
       Effect.try({
-        try: () => text === "" ? null : JSON.parse(text) as unknown,
+        try: () => text === "" ? null : JSON.parse(text),
         catch: (cause) =>
           new Error.HttpClientError({
             reason: new Error.DecodeError({
@@ -224,7 +286,10 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
 
   private textBody?: Effect.Effect<string, Error.HttpClientError>
   get text(): Effect.Effect<string, Error.HttpClientError> {
-    return this.textBody ??= Effect.tryPromise({
+    if (this.textBody) {
+      return this.textBody
+    }
+    this.textBody = Effect.tryPromise({
       try: () => this.source.body.text(),
       catch: (cause) =>
         new Error.HttpClientError({
@@ -235,6 +300,8 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
           })
         })
     }).pipe(Effect.cached, Effect.runSync)
+    this.arrayBufferBody = Effect.map(this.textBody, (_) => new TextEncoder().encode(_).buffer)
+    return this.textBody
   }
 
   get urlParamsBody(): Effect.Effect<UrlParams.UrlParams, Error.HttpClientError> {
@@ -269,7 +336,10 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
 
   private arrayBufferBody?: Effect.Effect<ArrayBuffer, Error.HttpClientError>
   get arrayBuffer(): Effect.Effect<ArrayBuffer, Error.HttpClientError> {
-    return this.arrayBufferBody ??= Effect.tryPromise({
+    if (this.arrayBufferBody) {
+      return this.arrayBufferBody
+    }
+    this.arrayBufferBody = Effect.tryPromise({
       try: () => this.source.body.arrayBuffer(),
       catch: (cause) =>
         new Error.HttpClientError({
@@ -280,6 +350,8 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
           })
         })
     }).pipe(Effect.cached, Effect.runSync)
+    this.textBody = Effect.map(this.arrayBufferBody, (_) => new TextDecoder().decode(_))
+    return this.arrayBufferBody
   }
 
   toJSON(): unknown {
@@ -289,21 +361,31 @@ class UndiciResponse extends Inspectable.Class implements HttpClientResponse {
       status: this.status
     })
   }
+
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
 }
 
 /**
- * @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,
   never,
   Dispatcher
-> = Client.layerMergedServices(makeUndici)
+> = 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)
 
@@ -312,17 +394,23 @@ 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 ServiceMap.Service<HttpAgent, {
+export class HttpAgent extends Context.Service<HttpAgent, {
   readonly http: Http.Agent
   readonly https: Https.Agent
 }>()("@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(
@@ -338,22 +426,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
@@ -490,7 +588,7 @@ const waitForFinish = (nodeRequest: Http.ClientRequest, request: HttpClientReque
     })
   })
 
-class NodeHttpResponse extends NodeHttpIncomingMessage<Error.HttpClientError> implements HttpClientResponse {
+class NodeHttpResponse extends NodeHttpIncomingMessage<Error.HttpClientError> implements HttpClientResponse, Pipeable {
   readonly [Response.TypeId]: typeof Response.TypeId
   readonly request: HttpClientRequest
 
@@ -555,20 +653,30 @@ class NodeHttpResponse extends NodeHttpIncomingMessage<Error.HttpClientError> im
       status: this.status
     })
   }
+
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
 }
 
 /**
- * @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,
   never,
   HttpAgent
-> = Client.layerMergedServices(makeNodeHttp)
+> = 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,8 +1,35 @@
 /**
- * @since 1.0.0
+ * Adapter base for exposing Node `http.IncomingMessage` values as Effect HTTP
+ * incoming messages.
+ *
+ * Server requests and Node client responses both arrive as Node readable
+ * streams with raw header objects, socket metadata, and one-shot body
+ * consumption. This module's `NodeHttpIncomingMessage` class keeps the original
+ * Node message available while presenting Effect's `HttpIncomingMessage` shape:
+ * typed headers, remote address lookup, stream access, and text, JSON,
+ * URL-encoded, and array-buffer body readers.
+ *
+ * **Mental model**
+ *
+ * The Node message remains the source of truth. The adapter translates headers
+ * and remote address on demand, delegates raw streaming to `NodeStream`, and
+ * lets subclasses choose how unknown Node errors are mapped into their HTTP
+ * error type.
+ *
+ * **Gotchas**
+ *
+ * Node request and response bodies are one-shot streams. The `text` and
+ * `arrayBuffer` readers are cached and share decoded values with each other,
+ * but direct `stream` access is not cached and can consume the underlying Node
+ * stream before a decoder reads it. Body readers honor
+ * `HttpIncomingMessage.MaxBodySize`.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Inspectable from "effect/Inspectable"
+import * as Option from "effect/Option"
+import type * as Schema from "effect/Schema"
 import type * as Stream from "effect/Stream"
 import * as Headers from "effect/unstable/http/Headers"
 import * as IncomingMessage from "effect/unstable/http/HttpIncomingMessage"
@@ -11,24 +38,30 @@ 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
   readonly onError: (error: unknown) => E
-  readonly remoteAddressOverride?: string | undefined
+  readonly remoteAddressOverride?: Option.Option<string> | undefined
 
   constructor(
     source: Http.IncomingMessage,
     onError: (error: unknown) => E,
-    remoteAddressOverride?: string
+    remoteAddressOverride?: Option.Option<string>
   ) {
     super()
     this[IncomingMessage.TypeId] = IncomingMessage.TypeId
@@ -42,7 +75,7 @@ export abstract class NodeHttpIncomingMessage<E> extends Inspectable.Class
   }
 
   get remoteAddress() {
-    return this.remoteAddressOverride ?? this.source.socket.remoteAddress
+    return this.remoteAddressOverride ?? Option.fromNullishOr(this.source.socket.remoteAddress)
   }
 
   private textEffect: Effect.Effect<string, E> | undefined
@@ -52,7 +85,7 @@ export abstract class NodeHttpIncomingMessage<E> extends Inspectable.Class
     }
     this.textEffect = Effect.runSync(Effect.cached(
       Effect.flatMap(
-        IncomingMessage.MaxBodySize.asEffect(),
+        IncomingMessage.MaxBodySize,
         (maxBodySize) =>
           NodeStream.toString(() => this.source, {
             onError: this.onError,
@@ -60,6 +93,7 @@ export abstract class NodeHttpIncomingMessage<E> extends Inspectable.Class
           })
       )
     ))
+    this.arrayBufferEffect = Effect.map(this.textEffect, (_) => new TextEncoder().encode(_).buffer)
     return this.textEffect
   }
 
@@ -67,15 +101,15 @@ export abstract class NodeHttpIncomingMessage<E> extends Inspectable.Class
     return Effect.runSync(this.text)
   }
 
-  get json(): Effect.Effect<unknown, E> {
+  get json(): Effect.Effect<Schema.Json, E> {
     return Effect.flatMap(this.text, (text) =>
       Effect.try({
-        try: () => text === "" ? null : JSON.parse(text) as unknown,
+        try: () => text === "" ? null : JSON.parse(text),
         catch: this.onError
       }))
   }
 
-  get jsonUnsafe(): unknown {
+  get jsonUnsafe(): Schema.Json {
     return Effect.runSync(this.json)
   }
 
@@ -94,12 +128,21 @@ export abstract class NodeHttpIncomingMessage<E> extends Inspectable.Class
     })
   }
 
+  private arrayBufferEffect: Effect.Effect<ArrayBuffer, E> | undefined
   get arrayBuffer(): Effect.Effect<ArrayBuffer, E> {
-    return Effect.withFiber((fiber) =>
+    if (this.arrayBufferEffect) {
+      return this.arrayBufferEffect
+    }
+    this.arrayBufferEffect = Effect.withFiber((fiber) =>
       NodeStream.toArrayBuffer(() => this.source, {
         onError: this.onError,
         maxBytes: fiber.getRef(IncomingMessage.MaxBodySize)
       })
+    ).pipe(
+      Effect.cached,
+      Effect.runSync
     )
+    this.textEffect = Effect.map(this.arrayBufferEffect, (_) => new TextDecoder().decode(_))
+    return this.arrayBufferEffect
   }
 }

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,12 +34,17 @@ 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) {
-    const stream = Fs.createReadStream(path, { start, end })
+    const stream = contentLength === 0
+      ? Readable.from([])
+      : Fs.createReadStream(path, { start, end: end === undefined ? undefined : end - 1 })
     return ServerResponse.raw(stream, {
       headers: {
         ...headers,
@@ -45,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),