@effect/platform-node 4.0.0-beta.1 → 4.0.0-beta.100

package/src/NodeHttpServer.ts

@@ -1,17 +1,31 @@
 /**
- * @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`. It also exports request and upgrade handler
+ * constructors plus layers for the server alone, HTTP support services, the
+ * combined server, configurable options, and tests.
+ *
+ * @since 4.0.0
  */
 import * as Cause from "effect/Cause"
 import * as Config from "effect/Config"
+import * as Context from "effect/Context"
+import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Fiber from "effect/Fiber"
 import type * as FileSystem from "effect/FileSystem"
 import { flow, type LazyArg } from "effect/Function"
+import * as Latch from "effect/Latch"
 import * as Layer from "effect/Layer"
+import type * as Option from "effect/Option"
 import type * as Path from "effect/Path"
 import type * as Record from "effect/Record"
 import * 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 Etag from "effect/unstable/http/Etag"
@@ -26,7 +40,7 @@ import type * as HttpPlatform from "effect/unstable/http/HttpPlatform"
 import * as HttpServer from "effect/unstable/http/HttpServer"
 import {
   causeResponse,
-  clientAbortFiberId,
+  ClientAbort,
   HttpServerError,
   RequestParseError,
   ResponseError,
@@ -49,30 +63,44 @@ 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>,
-  options: Net.ListenOptions
+  options: Net.ListenOptions & {
+    readonly disablePreemptiveShutdown?: boolean | undefined
+    readonly gracefulShutdownTimeout?: Duration.Input | undefined
+  }
 ) {
   const scope = yield* Effect.scope
   const server = evaluate()
-  yield* Scope.addFinalizer(
-    scope,
-    Effect.callback<void>((resume) => {
-      if (!server.listening) {
-        return resume(Effect.void)
+
+  const shutdown = yield* Effect.callback<void>((resume) => {
+    if (!server.listening) {
+      return resume(Effect.void)
+    }
+    server.close((error) => {
+      if (error) {
+        resume(Effect.die(error))
+      } else {
+        resume(Effect.void)
       }
-      server.close((error) => {
-        if (error) {
-          resume(Effect.die(error))
-        } else {
-          resume(Effect.void)
-        }
-      })
     })
-  )
+  }).pipe(Effect.cached)
+
+  const preemptiveShutdown = options.disablePreemptiveShutdown ?
+    Effect.void :
+    Effect.timeoutOrElse(shutdown, {
+      duration: options.gracefulShutdownTimeout ?? Duration.seconds(20),
+      orElse: () => Effect.void
+    })
+
+  yield* Scope.addFinalizer(scope, shutdown)
 
   yield* Effect.callback<void, ServeError>((resume) => {
     function onError(cause: Error) {
@@ -110,7 +138,8 @@ export const make = Effect.fnUntraced(function*(
         port: address.port
       },
     serve: Effect.fnUntraced(function*(httpApp, middleware) {
-      const scope = yield* Effect.scope
+      const serveScope = yield* Effect.scope
+      const scope = Scope.forkUnsafe(serveScope, "parallel")
       const handler = yield* (makeHandler(httpApp, {
         middleware: middleware as any,
         scope
@@ -119,12 +148,11 @@ export const make = Effect.fnUntraced(function*(
         middleware: middleware as any,
         scope
       })
-      yield* Effect.addFinalizer(() =>
-        Effect.sync(() => {
-          server.off("request", handler)
-          server.off("upgrade", upgradeHandler)
-        })
-      )
+      yield* Scope.addFinalizerExit(serveScope, () => {
+        server.off("request", handler)
+        server.off("upgrade", upgradeHandler)
+        return preemptiveShutdown
+      })
       server.on("request", handler)
       server.on("upgrade", upgradeHandler)
     })
@@ -132,8 +160,12 @@ export const make = Effect.fnUntraced(function*(
 })
 
 /**
- * @since 1.0.0
- * @category Handlers
+ * 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,
@@ -151,26 +183,31 @@ export const makeHandler = <
   Exclude<Effect.Services<App>, HttpServerRequest | Scope.Scope>
 > => {
   const handled = HttpEffect.toHandled(httpEffect, handleResponse, options.middleware as any)
-  return Effect.map(Effect.services<any>(), (services) => {
-    return function handler(
+  return Effect.withFiber((parent) => {
+    const services = parent.context
+    return Effect.succeed(function handler(
       nodeRequest: Http.IncomingMessage,
       nodeResponse: Http.ServerResponse
     ) {
       const map = new Map(services.mapUnsafe)
       map.set(HttpServerRequest.key, new ServerRequestImpl(nodeRequest, nodeResponse))
-      const fiber = Fiber.runIn(Effect.runForkWith(ServiceMap.makeUnsafe<any>(map))(handled), options.scope)
+      const fiber = Fiber.runIn(Effect.runForkWith(Context.makeUnsafe<any>(map))(handled), options.scope)
       nodeResponse.on("close", () => {
         if (!nodeResponse.writableEnded) {
-          fiber.interruptUnsafe(clientAbortFiberId)
+          fiber.interruptUnsafe(parent.id, ClientAbort.annotation)
         }
       })
-    }
+    })
   })
 }
 
 /**
- * @since 1.0.0
- * @category Handlers
+ * 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,
@@ -189,8 +226,13 @@ export const makeUpgradeHandler = <
   Exclude<Effect.Services<App>, HttpServerRequest | Scope.Scope>
 > => {
   const handledApp = HttpEffect.toHandled(httpEffect, handleResponse, options.middleware as any)
-  return Effect.map(Effect.services<any>(), (services) =>
-    (function handler(nodeRequest: Http.IncomingMessage, socket: Duplex, head: Buffer) {
+  return Effect.withFiber((parent) => {
+    const services = parent.context
+    return Effect.succeed(function handler(
+      nodeRequest: Http.IncomingMessage,
+      socket: Duplex,
+      head: Buffer
+    ) {
       let nodeResponse_: Http.ServerResponse | undefined = undefined
       const nodeResponse = () => {
         if (nodeResponse_ === undefined) {
@@ -216,13 +258,14 @@ export const makeUpgradeHandler = <
       ))
       const map = new Map(services.mapUnsafe)
       map.set(HttpServerRequest.key, new ServerRequestImpl(nodeRequest, nodeResponse, upgradeEffect))
-      const fiber = Fiber.runIn(Effect.runForkWith(ServiceMap.makeUnsafe<any>(map))(handledApp), options.scope)
+      const fiber = Fiber.runIn(Effect.runForkWith(Context.makeUnsafe<any>(map))(handledApp), options.scope)
       socket.on("close", () => {
         if (!socket.writableEnded) {
-          fiber.interruptUnsafe(clientAbortFiberId)
+          fiber.interruptUnsafe(parent.id, ClientAbort.annotation)
         }
       })
-    }));
+    })
+  })
 }
 
 class ServerRequestImpl extends NodeHttpIncomingMessage<HttpServerError> implements HttpServerRequest {
@@ -238,7 +281,7 @@ class ServerRequestImpl extends NodeHttpIncomingMessage<HttpServerError> impleme
     upgradeEffect?: Effect.Effect<Socket.Socket, HttpServerError>,
     url = source.url!,
     headersOverride?: Headers.Headers,
-    remoteAddressOverride?: string
+    remoteAddressOverride?: Option.Option<string>
   ) {
     super(source, (cause) =>
       new HttpServerError({
@@ -270,7 +313,7 @@ class ServerRequestImpl extends NodeHttpIncomingMessage<HttpServerError> impleme
     options: {
       readonly url?: string | undefined
       readonly headers?: Headers.Headers | undefined
-      readonly remoteAddress?: string | undefined
+      readonly remoteAddress?: Option.Option<string> | undefined
     }
   ) {
     return new ServerRequestImpl(
@@ -279,7 +322,7 @@ class ServerRequestImpl extends NodeHttpIncomingMessage<HttpServerError> impleme
       this.upgradeEffect,
       options.url ?? this.url,
       options.headers ?? this.headersOverride,
-      options.remoteAddress ?? this.remoteAddressOverride
+      "remoteAddress" in options ? options.remoteAddress : this.remoteAddressOverride
     )
   }
 
@@ -346,17 +389,26 @@ 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>>,
-  options: Net.ListenOptions
+  options: Net.ListenOptions & {
+    readonly disablePreemptiveShutdown?: boolean | undefined
+    readonly gracefulShutdownTimeout?: Duration.Input | undefined
+  }
 ) => 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
@@ -367,12 +419,18 @@ 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>,
-  options: Net.ListenOptions
+  options: Net.ListenOptions & {
+    readonly disablePreemptiveShutdown?: boolean | undefined
+    readonly gracefulShutdownTimeout?: Duration.Input | undefined
+  }
 ): Layer.Layer<
   HttpServer.HttpServer | NodeServices.NodeServices | HttpPlatform.HttpPlatform | Etag.Generator,
   ServeError
@@ -383,26 +441,38 @@ export const layer = (
   )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides a Node `HttpServer` together with the Node HTTP platform, ETag,
+ * and core Node platform services, reading the listen and shutdown options from
+ * a `Config` value.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (
   evaluate: LazyArg<Http.Server>,
-  options: Config.Wrap<Net.ListenOptions>
+  options: Config.Wrap<
+    Net.ListenOptions & {
+      readonly disablePreemptiveShutdown?: boolean | undefined
+      readonly gracefulShutdownTimeout?: Duration.Input | undefined
+    }
+  >
 ): Layer.Layer<
-  HttpServer.HttpServer | FileSystem.FileSystem | Path.Path | HttpPlatform.HttpPlatform | Etag.Generator,
+  HttpServer.HttpServer | NodeServices.NodeServices | HttpPlatform.HttpPlatform | Etag.Generator,
   ServeError | Config.ConfigError
 > =>
   Layer.mergeAll(
     Layer.effect(HttpServer.HttpServer)(
-      Effect.flatMap(Config.unwrap(options).asEffect(), (options) => make(evaluate, options))
+      Effect.flatMap(Config.unwrap(options), (options) => make(evaluate, options))
     ),
     layerHttpServices
   )
 
 /**
- * @since 1.0.0
- * @category Testing
+ * 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
@@ -448,7 +518,12 @@ const handleResponse = (
   if (request.method === "HEAD") {
     nodeResponse.writeHead(response.status, headers)
     return Effect.callback<void>((resume) => {
-      nodeResponse.end(() => resume(Effect.void))
+      const done = () => {
+        nodeResponse.off("close", done)
+        resume(Effect.void)
+      }
+      nodeResponse.once("close", done)
+      nodeResponse.end(done)
     })
   }
   const body = response.body
@@ -528,7 +603,7 @@ const handleResponse = (
     }
     case "Stream": {
       nodeResponse.writeHead(response.status, headers)
-      const drainLatch = Effect.makeLatchUnsafe()
+      const drainLatch = Latch.makeUnsafe()
       nodeResponse.on("drain", () => drainLatch.openUnsafe())
       return body.stream.pipe(
         Stream.orDie,

package/src/NodeHttpServerRequest.ts

@@ -1,18 +1,31 @@
 /**
- * @since 1.0.0
+ * Accessors for the Node.js objects behind an Effect HTTP server request.
+ *
+ * `toIncomingMessage` returns the underlying Node `http.IncomingMessage`.
+ * `toServerResponse` returns the underlying Node `http.ServerResponse`,
+ * evaluating the stored response thunk when the response was created lazily.
+ *
+ * @since 4.0.0
  */
 import type { HttpServerRequest } from "effect/unstable/http/HttpServerRequest"
 import type * as Http from "node:http"
 
 /**
- * @since 1.0.0
- * @category Accessors
+ * 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
- * @category Accessors
+ * 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

package/src/NodeMultipart.ts

@@ -1,5 +1,14 @@
 /**
- * @since 1.0.0
+ * Node.js multipart parsing for HTTP `multipart/form-data` request bodies.
+ *
+ * `NodeMultipart` adapts a Node `Readable` plus incoming HTTP headers into
+ * Effect's shared multipart model. It can expose form parts as a stream or
+ * collect a complete persisted form by writing file uploads to scoped temporary
+ * files through the current `FileSystem` and `Path` services. `fileToReadable`
+ * returns the underlying Node readable stream for file parts produced by this
+ * parser.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import type * as FileSystem from "effect/FileSystem"
@@ -16,8 +25,12 @@ import * as NodeStreamP from "node:stream/promises"
 import * as NodeStream from "./NodeStream.ts"
 
 /**
- * @since 1.0.0
+ * Parses multipart data from a Node readable request body and headers into a
+ * stream of `Multipart.Part` values, converting parser failures to
+ * `MultipartError`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const stream = (
   source: Readable,
@@ -39,8 +52,11 @@ export const stream = (
   )
 
 /**
- * @since 1.0.0
+ * Parses multipart data from a Node readable request body and persists file
+ * parts using the current `FileSystem`, `Path`, and `Scope` services.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const persisted = (
   source: Readable,
@@ -57,7 +73,11 @@ export const persisted = (
     }))
 
 /**
- * @since 1.0.0
+ * Returns the underlying Node readable stream for a multipart file produced by
+ * the Node multipart parser.
+ *
+ * @category converting
+ * @since 4.0.0
  */
 export const fileToReadable = (file: Multipart.File): Readable => (file as FileImpl).file
 

package/src/NodePath.ts

@@ -1,24 +1,40 @@
 /**
- * @since 1.0.0
+ * Node.js layers for Effect's `Path` service.
+ *
+ * This module provides the default, POSIX, and Windows variants of the
+ * platform-independent `Path` service by reusing the shared Node path
+ * implementation. The provided path services include Node file URL conversion
+ * behavior.
+ *
+ * @since 4.0.0
  */
 import * as NodePath from "@effect/platform-node-shared/NodePath"
 import type * as Layer from "effect/Layer"
 import type { Path } from "effect/Path"
 
 /**
- * @since 1.0.0
- * @category layer
+ * Provides the default Node `Path` service using the platform's `node:path`
+ * implementation.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Path> = NodePath.layer
 
 /**
- * @since 1.0.0
- * @category layer
+ * Provides the `Path` service using Node's POSIX path implementation,
+ * regardless of the host platform.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerPosix: Layer.Layer<Path> = NodePath.layerPosix
 
 /**
- * @since 1.0.0
- * @category layer
+ * Provides the `Path` service using Node's Windows path implementation,
+ * regardless of the host platform.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerWin32: Layer.Layer<Path> = NodePath.layerWin32

package/src/NodeRedis.ts

@@ -1,20 +1,32 @@
 /**
- * @since 1.0.0
+ * Node.js Redis integration backed by `ioredis`.
+ *
+ * This module creates a scoped `ioredis` client and exposes it in two forms:
+ * the generic `Redis` service and the {@link NodeRedis} service for direct
+ * access to the underlying client. `layer` accepts ioredis options directly,
+ * while `layerConfig` reads them from Effect config. Both layers close the
+ * client when the layer scope ends.
+ *
+ * @since 4.0.0
  */
 import * as Config from "effect/Config"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Fn from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as Scope from "effect/Scope"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Redis from "effect/unstable/persistence/Redis"
 import * as IoRedis from "ioredis"
 
 /**
- * @since 1.0.0
- * @category Service
+ * Service tag for the Node Redis integration, exposing the underlying
+ * `ioredis` client and a `use` helper that maps client failures to
+ * `RedisError`.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class NodeRedis extends ServiceMap.Service<NodeRedis, {
+export class NodeRedis extends Context.Service<NodeRedis, {
   readonly client: IoRedis.Redis
   readonly use: <A>(f: (client: IoRedis.Redis) => Promise<A>) => Effect.Effect<A, Redis.RedisError>
 }>()("@effect/platform-node/NodeRedis") {}
@@ -45,30 +57,36 @@ const make = Effect.fnUntraced(function*(
     use
   })
 
-  return ServiceMap.make(NodeRedis, nodeRedis).pipe(
-    ServiceMap.add(Redis.Redis, redis)
+  return Context.make(NodeRedis, nodeRedis).pipe(
+    Context.add(Redis.Redis, redis)
   )
 })
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides `Redis` and `NodeRedis` services backed by an `ioredis` client
+ * created with the supplied options and closed when the layer scope ends.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layer = (
   options?: IoRedis.RedisOptions | undefined
-): Layer.Layer<Redis.Redis | NodeRedis> => Layer.effectServices(make(options))
+): Layer.Layer<Redis.Redis | NodeRedis> => Layer.effectContext(make(options))
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides `Redis` and `NodeRedis` services from `Config`-backed ioredis
+ * options, closing the client when the layer scope ends.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerConfig: (
   options: Config.Wrap<IoRedis.RedisOptions>
 ) => Layer.Layer<Redis.Redis | NodeRedis, Config.ConfigError> = (
   options: Config.Wrap<IoRedis.RedisOptions>
 ): Layer.Layer<Redis.Redis | NodeRedis, Config.ConfigError> =>
-  Layer.effectServices(
-    Config.unwrap(options).asEffect().pipe(
+  Layer.effectContext(
+    Config.unwrap(options).pipe(
       Effect.flatMap(make)
     )
   )