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

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @since 4.0.0
+ */
+/**
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./NodeChildProcessSpawner.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./NodeClusterSocket.ts";
+/**
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./NodeCrypto.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./NodeFileSystem.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodePath from "./NodePath.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./NodeRuntime.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSink from "./NodeSink.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./NodeSocket.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./NodeSocketServer.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./NodeStdio.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStream from "./NodeStream.ts";
+/**
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./NodeTerminal.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,OAAO,KAAK,uBAAuB,MAAM,8BAA8B,CAAA;AAEvE;;GAEG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;GAEG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;GAEG;AACH,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AAErD;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;GAEG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;GAEG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;GAEG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;GAEG;AACH,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AAEzD;;GAEG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;GAEG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;GAEG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * @since 4.0.0
+ */
+// @barrel: Auto-generated exports. Do not edit manually.
+/**
+ * @since 4.0.0
+ */
+export * as NodeChildProcessSpawner from "./NodeChildProcessSpawner.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeClusterSocket from "./NodeClusterSocket.js";
+/**
+ * @since 1.0.0
+ */
+export * as NodeCrypto from "./NodeCrypto.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeFileSystem from "./NodeFileSystem.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodePath from "./NodePath.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeRuntime from "./NodeRuntime.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSink from "./NodeSink.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocket from "./NodeSocket.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeSocketServer from "./NodeSocketServer.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStdio from "./NodeStdio.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeStream from "./NodeStream.js";
+/**
+ * @since 4.0.0
+ */
+export * as NodeTerminal from "./NodeTerminal.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["NodeChildProcessSpawner","NodeClusterSocket","NodeCrypto","NodeFileSystem","NodePath","NodeRuntime","NodeSink","NodeSocket","NodeSocketServer","NodeStdio","NodeStream","NodeTerminal"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,uBAAuB,MAAM,8BAA8B;AAEvE;;;AAGA,OAAO,KAAKC,iBAAiB,MAAM,wBAAwB;AAE3D;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,cAAc,MAAM,qBAAqB;AAErD;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,gBAAgB,MAAM,uBAAuB;AAEzD;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAKC,YAAY,MAAM,mBAAmB","ignoreList":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@effect/platform-node-shared",
   "type": "module",
-  "version": "4.0.0-beta.7",
+  "version": "4.0.0-beta.71",
   "license": "MIT",
   "description": "Unified interfaces for common platform-specific services",
   "homepage": "https://effect.website",
@@ -46,18 +46,19 @@
     "provenance": true
   },
   "peerDependencies": {
-    "effect": "^4.0.0-beta.7"
+    "effect": "^4.0.0-beta.71"
   },
   "devDependencies": {
-    "@types/node": "^25.2.0",
-    "tar": "^7.5.7",
-    "effect": "^4.0.0-beta.7"
+    "@types/node": "^25.7.0",
+    "tar": "^7.5.15",
+    "effect": "^4.0.0-beta.71"
   },
   "dependencies": {
     "@types/ws": "^8.18.1",
-    "ws": "^8.19.0"
+    "ws": "^8.20.0"
   },
   "scripts": {
+    "codegen": "effect-utils codegen",
     "build": "tsc -b tsconfig.json && pnpm babel",
     "build:tsgo": "tsgo -b tsconfig.json && pnpm babel",
     "babel": "babel dist --plugins annotate-pure-calls --out-dir dist --source-maps",

package/src/NodeChildProcessSpawner.ts

@@ -1,5 +1,19 @@
 /**
- * Node.js implementation of `ChildProcessSpawner`.
+ * Shared Node.js implementation of the child process spawner service.
+ *
+ * This module adapts `node:child_process.spawn` to the Effect
+ * `ChildProcessSpawner` service. Provide {@link layer} to run `ChildProcess`
+ * commands in Node-compatible runtimes: commands get scoped process handles
+ * with stdin sinks, stdout and stderr streams, exit-code waiting,
+ * interruption-time cleanup, process killing, and custom file-descriptor pipes.
+ *
+ * The implementation sits below the command-building API. It validates and
+ * resolves `cwd` through the Effect `FileSystem` and `Path` services,
+ * translates Node errno failures to `PlatformError`, and uses scopes to
+ * terminate referenced children when the owning effect is interrupted or
+ * finalized. Pipelines are flattened by {@link flattenCommand} and spawned one
+ * process at a time, wiring the selected source stream (`stdout`, `stderr`,
+ * `all`, or `fdN`) to the destination `stdin` or `fdN`.
  *
  * @since 4.0.0
  */
@@ -17,7 +31,13 @@ import * as Sink from "effect/Sink"
 import * as Stream from "effect/Stream"
 import * as ChildProcess from "effect/unstable/process/ChildProcess"
 import type { ChildProcessHandle } from "effect/unstable/process/ChildProcessSpawner"
-import { ChildProcessSpawner, ExitCode, makeHandle, ProcessId } from "effect/unstable/process/ChildProcessSpawner"
+import {
+  ChildProcessSpawner,
+  ExitCode,
+  make as makeSpawner,
+  makeHandle,
+  ProcessId
+} from "effect/unstable/process/ChildProcessSpawner"
 import * as NodeChildProcess from "node:child_process"
 import { handleErrnoException } from "./internal/utils.ts"
 import * as NodeSink from "./NodeSink.ts"
@@ -337,6 +357,23 @@ const make = Effect.gen(function*() {
     })
   }
 
+  const killProcessGroupOnExit = (
+    childProcess: NodeChildProcess.ChildProcess,
+    signal: NodeJS.Signals
+  ): void => {
+    if (globalThis.process.platform === "win32") {
+      NodeChildProcess.exec(`taskkill /pid ${childProcess.pid} /T /F`, () => {
+        // ignore errors during best-effort cleanup
+      })
+      return
+    }
+    try {
+      globalThis.process.kill(-childProcess.pid!, signal)
+    } catch {
+      // ignore errors during best-effort cleanup
+    }
+  }
+
   const killProcess = (
     command: ChildProcess.StandardCommand,
     childProcess: NodeChildProcess.ChildProcess,
@@ -368,7 +405,7 @@ const make = Effect.gen(function*() {
       ? kill(command, childProcess, killSignal)
       : Effect.timeoutOrElse(kill(command, childProcess, killSignal), {
         duration: options.forceKillAfter,
-        onTimeout: () => kill(command, childProcess, "SIGKILL")
+        orElse: () => kill(command, childProcess, "SIGKILL")
       })
   }
 
@@ -413,6 +450,8 @@ const make = Effect.gen(function*() {
         const stdoutConfig = resolveOutputOption(cmd.options, "stdout")
         const stderrConfig = resolveOutputOption(cmd.options, "stderr")
         const resolvedAdditionalFds = resolveAdditionalFds(cmd.options)
+        let isReferenced = true
+        let cleanupOnNonZeroExit = false
 
         const cwd = yield* resolveWorkingDirectory(cmd.options)
         const env = resolveEnvironment(cmd.options)
@@ -438,6 +477,9 @@ const make = Effect.gen(function*() {
               }
               return yield* Effect.void
             }
+            if (!isReferenced) {
+              return yield* Effect.void
+            }
             // Process is still running, kill it
             return yield* killWithTimeout((command, childProcess, signal) =>
               Effect.catch(
@@ -452,6 +494,26 @@ const make = Effect.gen(function*() {
         )
 
         const pid = ProcessId(childProcess.pid!)
+        childProcess.on("exit", (code) => {
+          if (cleanupOnNonZeroExit && code !== 0 && Predicate.isNotNull(code)) {
+            killProcessGroupOnExit(childProcess, cmd.options.killSignal ?? "SIGTERM")
+          }
+        })
+        const reref = Effect.sync(() => {
+          if (!isReferenced) {
+            childProcess.ref()
+            isReferenced = true
+            cleanupOnNonZeroExit = false
+          }
+        })
+        const unref = Effect.sync(() => {
+          if (isReferenced) {
+            childProcess.unref()
+            isReferenced = false
+            cleanupOnNonZeroExit = true
+          }
+          return reref
+        })
         const stdin = yield* setupChildStdin(cmd, childProcess, stdinConfig)
         const { all, stderr, stdout } = setupChildOutputStreams(cmd, childProcess, stdoutConfig, stderrConfig)
         const { getInputFd, getOutputFd } = yield* setupAdditionalFds(cmd, childProcess, resolvedAdditionalFds)
@@ -489,14 +551,15 @@ const make = Effect.gen(function*() {
           stderr,
           all,
           getInputFd,
-          getOutputFd
+          getOutputFd,
+          unref
         })
       }
       case "PipedCommand": {
         const { commands, pipeOptions } = flattenCommand(cmd)
         const [root, ...pipeline] = commands
 
-        let handle = spawnCommand(root)
+        const handles = [yield* spawnCommand(root)]
 
         for (let i = 0; i < pipeline.length; i++) {
           const command = pipeline[i]
@@ -505,7 +568,7 @@ const make = Effect.gen(function*() {
 
           // Get the appropriate stream from the source based on `from` option
           const sourceStream = Stream.unwrap(
-            Effect.map(handle, (h) => getSourceStream(h, options.from))
+            Effect.succeed(getSourceStream(handles[handles.length - 1], options.from))
           )
 
           // Determine where to pipe: stdin or custom fd
@@ -513,48 +576,73 @@ const make = Effect.gen(function*() {
 
           if (toOption === "stdin") {
             // Pipe to stdin (default behavior)
-            handle = spawnCommand(ChildProcess.make(command.command, command.args, {
-              ...command.options,
-              stdin: { ...stdinConfig, stream: sourceStream }
-            }))
+            handles.push(
+              yield* spawnCommand(ChildProcess.make(command.command, command.args, {
+                ...command.options,
+                stdin: { ...stdinConfig, stream: sourceStream }
+              }))
+            )
           } else {
             // Pipe to custom fd (fd3, fd4, etc.)
             const fd = ChildProcess.parseFdName(toOption)
             if (Predicate.isNotUndefined(fd)) {
               const fdName = ChildProcess.fdName(fd) as `fd${number}`
               const existingFds = command.options.additionalFds ?? {}
-              handle = spawnCommand(ChildProcess.make(command.command, command.args, {
-                ...command.options,
-                additionalFds: {
-                  ...existingFds,
-                  [fdName]: { type: "input" as const, stream: sourceStream }
-                }
-              }))
+              handles.push(
+                yield* spawnCommand(ChildProcess.make(command.command, command.args, {
+                  ...command.options,
+                  additionalFds: {
+                    ...existingFds,
+                    [fdName]: { type: "input" as const, stream: sourceStream }
+                  }
+                }))
+              )
             } else {
               // Invalid fd name, fall back to stdin
-              handle = spawnCommand(ChildProcess.make(command.command, command.args, {
-                ...command.options,
-                stdin: { ...stdinConfig, stream: sourceStream }
-              }))
+              handles.push(
+                yield* spawnCommand(ChildProcess.make(command.command, command.args, {
+                  ...command.options,
+                  stdin: { ...stdinConfig, stream: sourceStream }
+                }))
+              )
             }
           }
         }
 
-        return yield* handle
+        const handle = handles[handles.length - 1]
+        const unref = Effect.gen(function*() {
+          const rerefs: Array<Effect.Effect<void, PlatformError.PlatformError>> = []
+          for (const handle of handles) {
+            rerefs.push(yield* handle.unref)
+          }
+          return Effect.forEach([...rerefs].reverse(), (reref) => reref, { discard: true })
+        })
+
+        return makeHandle({
+          pid: handle.pid,
+          exitCode: handle.exitCode,
+          isRunning: handle.isRunning,
+          kill: handle.kill,
+          stdin: handle.stdin,
+          stdout: handle.stdout,
+          stderr: handle.stderr,
+          all: handle.all,
+          getInputFd: handle.getInputFd,
+          getOutputFd: handle.getOutputFd,
+          unref
+        })
       }
     }
   })
 
-  return ChildProcessSpawner.of({
-    spawn: spawnCommand
-  })
+  return makeSpawner(spawnCommand)
 })
 
 /**
  * Layer providing the `NodeChildProcessSpawner` implementation.
  *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layer: Layer.Layer<
   ChildProcessSpawner,
@@ -569,8 +657,8 @@ export const layer: Layer.Layer<
 /**
  * Result of flattening a pipeline of commands.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface FlattenedPipeline {
   readonly commands: Arr.NonEmptyReadonlyArray<ChildProcess.StandardCommand>
@@ -581,8 +669,8 @@ export interface FlattenedPipeline {
  * Flattens a `Command` into an array of `StandardCommand`s along with pipe
  * options for each connection.
  *
+ * @category utils
  * @since 4.0.0
- * @category Utilities
  */
 export const flattenCommand = (
   command: ChildProcess.Command

package/src/NodeClusterSocket.ts

@@ -1,8 +1,40 @@
 /**
- * @since 1.0.0
+ * Node TCP socket transport for Effect Cluster runner-to-runner RPC.
+ *
+ * This module provides the shared Node layers used by socket-based cluster
+ * transports. `layerClientProtocol` opens TCP sockets to peer runner addresses
+ * and wraps them in the current RPC serialization protocol. `layerSocketServer`
+ * exposes the socket server that receives incoming runner RPC traffic.
+ *
+ * **Mental model**
+ *
+ * The cluster runtime decides which runners exist, which shards they own, and
+ * which messages must be delivered. This module only provides the TCP transport
+ * those services use after a runner address has been selected. The client side
+ * dials an advertised runner address; the server side listens on the address
+ * configured for the local runner.
+ *
+ * **Common tasks**
+ *
+ * Add these layers when a Node or Node-compatible cluster deployment should use
+ * direct socket RPC instead of an HTTP transport. Configure `runnerAddress` as
+ * the address other runners can reach, and configure `runnerListenAddress` when
+ * the local process must bind a different host or port.
+ *
+ * **Gotchas**
+ *
+ * Containers, port mappings, and Kubernetes services often require different
+ * advertised and listening addresses. Serialization is provided by the
+ * surrounding layer, not by this module. A reachable socket confirms only that
+ * TCP transport is available; gossip, shard ownership, health checks, and
+ * persisted message notification are coordinated by the cluster services that
+ * use this transport.
+ *
+ * @since 4.0.0
  */
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
 import * as Runners from "effect/unstable/cluster/Runners"
 import * as ShardingConfig from "effect/unstable/cluster/ShardingConfig"
 import * as RpcClient from "effect/unstable/rpc/RpcClient"
@@ -13,8 +45,11 @@ import * as NodeSocket from "./NodeSocket.ts"
 import * as NodeSocketServer from "./NodeSocketServer.ts"
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the cluster `RpcClientProtocol` by opening TCP sockets to runner
+ * addresses and using the current RPC serialization service.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerClientProtocol: Layer.Layer<
   Runners.RpcClientProtocol,
@@ -39,8 +74,11 @@ export const layerClientProtocol: Layer.Layer<
 )
 
 /**
- * @since 1.0.0
- * @category Layers
+ * Provides the socket server used by cluster runners, listening on
+ * `ShardingConfig.runnerListenAddress` or `runnerAddress`.
+ *
+ * @category layers
+ * @since 4.0.0
  */
 export const layerSocketServer: Layer.Layer<
   SocketServer.SocketServer,
@@ -48,9 +86,9 @@ export const layerSocketServer: Layer.Layer<
   ShardingConfig.ShardingConfig
 > = Effect.gen(function*() {
   const config = yield* ShardingConfig.ShardingConfig
-  const listenAddress = config.runnerListenAddress ?? config.runnerAddress
-  if (listenAddress === undefined) {
+  const listenAddress = Option.orElse(config.runnerListenAddress, () => config.runnerAddress)
+  if (Option.isNone(listenAddress)) {
     return yield* Effect.die("layerSocketServer: ShardingConfig.runnerListenAddress is None")
   }
-  return NodeSocketServer.layer(listenAddress)
+  return NodeSocketServer.layer(listenAddress.value)
 }).pipe(Layer.unwrap)

package/src/NodeCrypto.ts

@@ -0,0 +1,75 @@
+/**
+ * The `NodeCrypto` module implements Effect's `Crypto` service with
+ * Node-compatible `node:crypto` APIs. It exports {@link make} as the concrete
+ * service value and {@link layer} for providing that service to programs that
+ * need cryptographic random bytes, UUID generation, random values, or SHA
+ * digests over `Uint8Array` input.
+ *
+ * **Common tasks**
+ *
+ * - Provide {@link layer} in Node-compatible platform packages and tests
+ * - Reuse {@link make} when a surrounding layer already manages service
+ *   construction
+ * - Compute SHA-1, SHA-256, SHA-384, or SHA-512 digests through
+ *   `effect/Crypto` after the layer is provided
+ *
+ * **Gotchas**
+ *
+ * - Random bytes come from `node:crypto.randomBytes`
+ * - Digests use `node:crypto.createHash`; hash failures become platform
+ *   errors
+ * - SHA-1 is included for interoperability with existing protocols, not for
+ *   new security-sensitive designs
+ *
+ * @since 1.0.0
+ */
+import * as EffectCrypto from "effect/Crypto"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as PlatformError from "effect/PlatformError"
+import * as NodeCrypto from "node:crypto"
+
+const toHashAlgorithm = (algorithm: EffectCrypto.DigestAlgorithm): string => {
+  switch (algorithm) {
+    case "SHA-1":
+      return "sha1"
+    case "SHA-256":
+      return "sha256"
+    case "SHA-384":
+      return "sha384"
+    case "SHA-512":
+      return "sha512"
+  }
+}
+
+const digest: EffectCrypto.Crypto["digest"] = (algorithm, data) =>
+  Effect.try({
+    try: () => Uint8Array.from(NodeCrypto.createHash(toHashAlgorithm(algorithm)).update(data).digest()),
+    catch: (cause) =>
+      PlatformError.systemError({
+        module: "Crypto",
+        method: "digest",
+        _tag: "Unknown",
+        description: "Could not compute digest",
+        cause
+      })
+  })
+
+/**
+ * The default Node.js Crypto service implementation.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make: EffectCrypto.Crypto = EffectCrypto.make({
+  randomBytes: NodeCrypto.randomBytes,
+  digest
+})
+
+/**
+ * A layer that provides the Node.js Crypto service implementation.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer: Layer.Layer<EffectCrypto.Crypto> = Layer.succeed(EffectCrypto.Crypto, make)