sailfork / t3code-github / .repos/ effect/ packages/ platform/ node-shared/ src/ NodeSocket.ts

/**
 * Node socket adapters for Effect sockets.
 *
 * This module opens `node:net` or `node:tls` connections, or wraps existing
 * Node `Duplex` streams, and presents them as `Socket.Socket` values, socket
 * channels, or layers. It also exposes the `NetSocket` service tag for the
 * underlying Node socket.
 *
 * @stability unstable
 * @since 4.0.0
 */
import * as Arr from "effect/Array"
import * as Channel from "effect/Channel"
import * as Context from "effect/Context"
import type * as Duration from "effect/Duration"
import * as Effect from "effect/Effect"
import * as Function from "effect/Function"
import { identity } from "effect/Function"
import * as Latch from "effect/Latch"
import * as Layer from "effect/Layer"
import * as Redacted from "effect/Redacted"
import * as Scope from "effect/Scope"
import * as Socket from "effect/socket/Socket"
import { Buffer } from "node:buffer"
import * as Net from "node:net"
import type { Duplex } from "node:stream"
import * as Tls from "node:tls"

const isDeno = "Deno" in globalThis

/**
 * Service tag for the underlying Node `net.Socket` associated with the current
 * socket connection.
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export class NetSocket extends Context.Service<NetSocket, Net.Socket>()(
  "@effect/platform-node/NodeSocket/NetSocket"
) {}

const readAvailable = (
  conn: Duplex,
  chunkSize: number
): Arr.NonEmptyReadonlyArray<Uint8Array | string> | undefined => {
  const first = conn.read() as Uint8Array | string | null
  if (first === null) return undefined
  const out: [Uint8Array | string, ...Array<Uint8Array | string>] = [first]
  let chunk: Uint8Array | string | null
  // read() may synchronously refill the buffer; leave further reads to the next pull.
  while (out.length < chunkSize && (chunk = conn.read() as Uint8Array | string | null) !== null) {
    out.push(chunk)
  }
  return out
}

const toBuffers = (input: string | Uint8Array | ReadonlyArray<string | Uint8Array>): Array<Buffer> =>
  Arr.map(Arr.ensure(input), (value) => Buffer.from(value))

const closeSocket = (conn: Net.Socket, isOpen: boolean) => {
  if (conn.closed !== false) return
  if (!isOpen || !("destroySoon" in conn)) {
    conn.destroy()
  } else {
    conn.destroySoon()
  }
}

/**
 * Opens a Node TCP connection as an Effect socket.
 *
 * **When to use**
 *
 * Use to create a `Socket.Socket` whose reader acquisition dials
 * `net.createConnection`.
 *
 * **Details**
 *
 * Supports `openTimeout` and closes or destroys the underlying socket when the
 * reader scope is finalized.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const makeNet = (
  options: Net.NetConnectOpts & {
    readonly openTimeout?: Duration.Input | undefined
    /**
     * Maximum chunks per pull. Defaults to 4096 unless a positive safe integer or Infinity is supplied.
     * Use Infinity for unbounded batching.
     */
    readonly chunkSize?: number | undefined
  }
): Effect.Effect<Socket.Socket> =>
  fromDuplex(
    Effect.contextWith((context: Context.Context<Scope.Scope>) => {
      let conn: Net.Socket | undefined
      let isOpen = false
      return Effect.flatMap(
        Scope.addFinalizer(
          Context.get(context, Scope.Scope),
          Effect.sync(() => {
            if (!conn) return
            closeSocket(conn, isOpen)
          })
        ),
        () =>
          Effect.callback<Net.Socket, Socket.SocketError, never>((resume) => {
            conn = Net.createConnection(options)
            conn.once("connect", () => {
              isOpen = true
              resume(Effect.succeed(conn!))
            })
            conn.on("error", (cause: Error) => {
              resume(Effect.fail(
                new Socket.SocketError({
                  reason: new Socket.SocketOpenError({ kind: "Unknown", cause })
                })
              ))
            })
          })
      )
    }),
    options
  )

/**
 * Adapts a Node `Duplex` into a `Socket.Socket`.
 *
 * **Details**
 *
 * Reader acquisition opens the duplex and keeps it paused: each pull reads at
 * most `chunkSize` chunks (default 4096) with `stream.read()`. On Node 26+ that
 * yields each buffered chunk as a separate batch element with no copy. Earlier Node
 * concatenates the buffer into one chunk. The stream is never resumed, so once
 * Node's buffer reaches its `highWaterMark` the kernel receive window closes
 * and the peer blocks: backpressure is end-to-end with no buffering above
 * Node's own.
 *
 * Writes use `write()` return-value backpressure, awaiting one `drain` when
 * the internal buffer is full. `writeAll` corks the stream around the batch.
 * Releasing the writer scope half-closes the stream (`end()`).
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const fromDuplex = <RO>(
  open: Effect.Effect<Duplex, Socket.SocketError, RO>,
  options?: {
    readonly openTimeout?: Duration.Input | undefined
    /**
     * Maximum chunks per pull. Defaults to 4096 unless a positive safe integer or Infinity is supplied.
     * Use Infinity for unbounded batching.
     */
    readonly chunkSize?: number | undefined
    readonly tlsServer?: boolean | undefined
  }
): Effect.Effect<Socket.Socket, never, Exclude<RO, Scope.Scope>> =>
  Effect.withFiber<Socket.Socket, never, Exclude<RO, Scope.Scope>>((fiber) => {
    let currentSocket: Duplex | undefined
    const latch = Latch.makeUnsafe(false)
    const openServices = fiber.context as Context.Context<RO>
    const isServer = options?.tlsServer === true
    const requestedChunkSize = options?.chunkSize ?? 4096
    const chunkSize = requestedChunkSize === Infinity ||
        (Number.isSafeInteger(requestedChunkSize) && requestedChunkSize > 0)
      ? requestedChunkSize
      : 4096
    const secureEvent = isServer ? "secure" : "secureConnect"

    const reader: Socket.Socket["reader"] = Effect.gen(function*() {
      const scope = yield* Effect.scope
      let conn = yield* Scope.provide(open, scope).pipe(
        options?.openTimeout !== undefined ?
          Effect.timeoutOrElse({
            duration: options.openTimeout,
            orElse: () =>
              Effect.fail(
                new Socket.SocketError({
                  reason: new Socket.SocketOpenError({ kind: "Timeout", cause: new Error("Connection timed out") })
                })
              )
          }) :
          identity
      )

      type ReadResume = (
        effect: Effect.Effect<Arr.NonEmptyReadonlyArray<Uint8Array | string>, Socket.SocketError>
      ) => void

      let error: Socket.SocketError | undefined
      let waiter: ReadResume | undefined
      // Bytes consumed by read() while the parked pull was interrupted.
      let pending: Arr.NonEmptyReadonlyArray<Uint8Array | string> | undefined
      let reading = false
      let closed = false
      let upgradeAvailable = true

      // The only place a waiter is resumed, so delivery order has one owner:
      // retained bytes first, then freshly read bytes, then the error.
      function drain() {
        if (waiter === undefined || reading) return
        let chunk = pending
        pending = undefined
        if (chunk === undefined && !closed) {
          // A data listener can interrupt and replace the pull synchronously.
          // The replacement must wait for this read to preserve byte order.
          reading = true
          try {
            chunk = readAvailable(conn, chunkSize)
          } finally {
            reading = false
          }
        }
        // A close during read() discards the bytes it consumed.
        if (closed) chunk = undefined
        if (waiter === undefined) {
          pending = chunk
          return
        }
        const result = chunk !== undefined
          ? Effect.succeed(chunk)
          : error !== undefined
          ? Effect.fail(error)
          : undefined
        if (result === undefined) return
        const resume = waiter
        waiter = undefined
        resume(result)
      }
      // Normal EOF: already consumed bytes are still delivered before the error.
      function end(err: Socket.SocketError) {
        error ??= err
        drain()
      }
      // Teardown or failure: consumed bytes are discarded.
      function close(err: Socket.SocketError) {
        error ??= err
        closed = true
        pending = undefined
        drain()
      }
      function onEnd() {
        end(new Socket.SocketError({ reason: new Socket.SocketCloseError({ code: 1000 }) }))
      }
      function onError(cause: Error) {
        close(
          new Socket.SocketError({
            reason: new Socket.SocketReadError({ cause })
          })
        )
      }
      function onClose(hadError: boolean) {
        const err = new Socket.SocketError({
          reason: new Socket.SocketCloseError({ code: hadError ? 1006 : 1000 })
        })
        if (hadError) close(err)
        else end(err)
      }

      function attachReadListeners(conn: Duplex) {
        conn.on("readable", drain)
        conn.on("end", onEnd)
        conn.on("error", onError)
        conn.on("close", onClose)
      }

      function detachReadListeners(conn: Duplex) {
        conn.off("readable", drain)
        conn.off("end", onEnd)
        conn.off("error", onError)
        conn.off("close", onClose)
      }

      // Deno's node:net compatibility layer stops emitting `readable` after
      // an explicit pause. The stream is already non-flowing without one.
      if (!isDeno) conn.pause()
      attachReadListeners(conn)
      yield* Scope.addFinalizer(
        scope,
        Effect.sync(() => {
          // resume a pull blocked in another fiber before detaching
          close(
            new Socket.SocketError({
              reason: new Socket.SocketCloseError({ code: 1006 })
            })
          )
          detachReadListeners(conn)
          latch.closeUnsafe()
          currentSocket = undefined
          upgradeAvailable = false
        })
      )

      currentSocket = conn
      latch.openUnsafe()

      const pull = Effect.callback<Arr.NonEmptyReadonlyArray<Uint8Array | string>, Socket.SocketError>((resume) => {
        waiter = resume
        drain()
        // Resumed synchronously: nothing to cancel.
        if (waiter !== resume) return
        return Effect.sync(() => {
          if (waiter === resume) waiter = undefined
        })
      })

      const upgrade: Socket.Reader["upgrade"] = (upgradeOptions = {}) =>
        Effect.suspend(() => {
          if (!upgradeAvailable) {
            return Effect.fail(
              new Socket.SocketError({
                reason: new Socket.SocketUpgradeError({
                  cause: new Error("socket is already upgraded or closed")
                })
              })
            )
          }
          const hasKey = upgradeOptions.key !== undefined
          const hasCert = upgradeOptions.cert !== undefined
          if ((isServer && (!hasKey || !hasCert)) || hasKey !== hasCert) {
            return Effect.fail(
              new Socket.SocketError({
                reason: new Socket.SocketUpgradeError({
                  cause: new Error(
                    isServer
                      ? "server TLS upgrade requires both key and cert"
                      : "TLS upgrade credentials must include both key and cert"
                  )
                })
              })
            )
          }
          return Effect.callback<void, Socket.SocketError>((resume) => {
            const raw = conn
            detachReadListeners(raw)

            let tls: Tls.TLSSocket
            try {
              const secureContext = Tls.createSecureContext({
                key: upgradeOptions.key === undefined
                  ? undefined
                  : Arr.map(
                    Arr.ensure(upgradeOptions.key),
                    (value) => Buffer.from(Redacted.value(value))
                  ),
                cert: upgradeOptions.cert === undefined ? undefined : toBuffers(upgradeOptions.cert),
                ca: upgradeOptions.ca === undefined ? undefined : toBuffers(upgradeOptions.ca),
                passphrase: upgradeOptions.passphrase === undefined
                  ? undefined
                  : Redacted.value(upgradeOptions.passphrase)
              })
              const tlsOptions = {
                secureContext,
                ALPNProtocols: upgradeOptions.alpnProtocols === undefined
                  ? undefined
                  : [...upgradeOptions.alpnProtocols],
                requestCert: upgradeOptions.requestCert,
                rejectUnauthorized: upgradeOptions.rejectUnauthorized
              }
              tls = isServer
                ? new Tls.TLSSocket(raw as Net.Socket, { ...tlsOptions, isServer: true })
                : Tls.connect({ ...tlsOptions, servername: upgradeOptions.servername, socket: raw as Net.Socket })
            } catch (cause) {
              attachReadListeners(raw)
              resume(Effect.fail(
                new Socket.SocketError({
                  reason: new Socket.SocketUpgradeError({ cause })
                })
              ))
              return
            }

            conn = tls
            currentSocket = tls
            tls.pause()

            function cleanup() {
              tls.off(secureEvent, succeed)
              tls.off("error", failUpgrade)
              tls.off("close", onUpgradeClose)
            }
            function succeed() {
              cleanup()
              upgradeAvailable = false
              attachReadListeners(tls)
              resume(Effect.void)
            }
            function failUpgrade(cause: unknown) {
              cleanup()
              const upgradeError = new Socket.SocketError({
                reason: new Socket.SocketUpgradeError({ cause })
              })
              close(upgradeError)
              resume(Effect.fail(upgradeError))
            }
            function onUpgradeClose() {
              failUpgrade(new Error("socket closed during TLS upgrade"))
            }

            tls.once(secureEvent, succeed)
            tls.once("error", failUpgrade)
            tls.once("close", onUpgradeClose)

            return Effect.sync(() => {
              cleanup()
              close(
                new Socket.SocketError({
                  reason: new Socket.SocketCloseError({ code: 1006 })
                })
              )
              tls.destroy()
            })
          })
        })

      return { pull, upgrade }
    }).pipe(
      Effect.updateContext((input: Context.Context<Scope.Scope>) => Context.merge(openServices, input))
    ) as Socket.Socket["reader"]

    const awaitDrain = (conn: Duplex) =>
      Effect.callback<void, Socket.SocketError>((resume) => {
        function cleanup() {
          conn.off("drain", onDrain)
          conn.off("error", onError)
          conn.off("close", onClose)
        }
        function onDrain() {
          cleanup()
          resume(Effect.void)
        }
        function onError(cause: Error) {
          cleanup()
          resume(Effect.fail(
            new Socket.SocketError({
              reason: new Socket.SocketWriteError({ cause })
            })
          ))
        }
        function onClose() {
          cleanup()
          resume(Effect.fail(
            new Socket.SocketError({
              reason: new Socket.SocketWriteError({ cause: new Error("socket closed") })
            })
          ))
        }
        conn.on("drain", onDrain)
        conn.on("error", onError)
        conn.on("close", onClose)
        return Effect.sync(cleanup)
      })

    const write = (
      chunk: Uint8Array | string | Socket.CloseEvent
    ): Effect.Effect<void, Socket.SocketError> =>
      Effect.suspend(() => {
        const conn = currentSocket
        if (conn === undefined) return latch.whenOpen(write(chunk))
        if (Socket.isCloseEvent(chunk)) {
          conn.destroy(chunk.code > 1000 ? new Error(`closed with code ${chunk.code}`) : undefined)
          return Effect.void
        }
        try {
          return conn.write(chunk) ? Effect.void : awaitDrain(conn)
        } catch (cause) {
          return Effect.fail(
            new Socket.SocketError({
              reason: new Socket.SocketWriteError({ cause })
            })
          )
        }
      })

    const writeAll = (
      chunks: Arr.NonEmptyReadonlyArray<Uint8Array | string>
    ): Effect.Effect<void, Socket.SocketError> =>
      Effect.suspend(() => {
        const conn = currentSocket
        if (conn === undefined) return latch.whenOpen(writeAll(chunks))
        let needsDrain = false
        try {
          if (chunks.length === 1) {
            needsDrain = !conn.write(chunks[0])
          } else {
            conn.cork()
            try {
              for (let i = 0; i < chunks.length; i++) {
                needsDrain = !conn.write(chunks[i]) || needsDrain
              }
            } finally {
              conn.uncork()
            }
          }
        } catch (cause) {
          return Effect.fail(
            new Socket.SocketError({
              reason: new Socket.SocketWriteError({ cause })
            })
          )
        }
        return needsDrain ? awaitDrain(conn) : Effect.void
      })

    const writer: Socket.Socket["writer"] = Effect.acquireRelease(
      Effect.succeed({ write, writeAll }),
      () =>
        Effect.sync(() => {
          if (!currentSocket || currentSocket.writableEnded) return
          currentSocket.end()
        })
    )

    return Effect.succeed(Socket.make({ reader, writer }))
  })

/**
 * Creates a `Channel` over a TCP socket, reading arrays of `Uint8Array`
 * chunks and writing arrays of bytes, strings, or socket close events.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const makeNetChannel = <IE = never>(
  options: Parameters<typeof makeNet>[0]
): Channel.Channel<
  Arr.NonEmptyReadonlyArray<Uint8Array>,
  Socket.SocketError | IE,
  void,
  Arr.NonEmptyReadonlyArray<Uint8Array | string | Socket.CloseEvent>,
  IE
> =>
  Channel.unwrap(
    Effect.map(makeNet(options), Socket.toChannelWith<IE>())
  )

/**
 * Provides a `Socket.Socket` by opening a TCP connection with the supplied
 * Node `net` connection options.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerNet: (options: Parameters<typeof makeNet>[0]) => Layer.Layer<
  Socket.Socket,
  Socket.SocketError
> = Function.flow(makeNet, Layer.effect(Socket.Socket))

/**
 * Opens a Node TLS connection as an Effect socket.
 *
 * **When to use**
 *
 * Use to create a `Socket.Socket` whose reader acquisition dials
 * `tls.connect` and completes once the TLS handshake has finished.
 *
 * **Details**
 *
 * Accepts the same options as `tls.connect`, so trust anchors (`ca`), client
 * certificates (`cert` / `key`), ALPN protocols, and `servername` are set
 * there. A failed handshake, including an untrusted or expired peer
 * certificate, fails with a `SocketOpenError`. Supports `openTimeout` and
 * destroys the underlying socket when the reader scope is finalized.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const makeTls = (
  options: Tls.ConnectionOptions & {
    readonly openTimeout?: Duration.Input | undefined
    /**
     * Maximum chunks per pull. Defaults to 4096 unless a positive safe integer or Infinity is supplied.
     * Use Infinity for unbounded batching.
     */
    readonly chunkSize?: number | undefined
  }
): Effect.Effect<Socket.Socket> =>
  fromDuplex(
    Effect.contextWith((context: Context.Context<Scope.Scope>) => {
      let conn: Tls.TLSSocket | undefined
      let isOpen = false
      return Effect.flatMap(
        Scope.addFinalizer(
          Context.get(context, Scope.Scope),
          Effect.sync(() => {
            if (!conn) return
            closeSocket(conn, isOpen)
          })
        ),
        () =>
          Effect.callback<Tls.TLSSocket, Socket.SocketError, never>((resume) => {
            conn = Tls.connect(options)
            conn.once("secureConnect", () => {
              isOpen = true
              resume(Effect.succeed(conn!))
            })
            conn.on("error", (cause: Error) => {
              resume(Effect.fail(
                new Socket.SocketError({
                  reason: new Socket.SocketOpenError({ kind: "Unknown", cause })
                })
              ))
            })
          })
      )
    }),
    options
  )

/**
 * Creates a `Channel` over a TLS socket, reading arrays of `Uint8Array`
 * chunks and writing arrays of bytes, strings, or socket close events.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const makeTlsChannel = <IE = never>(
  options: Parameters<typeof makeTls>[0]
): Channel.Channel<
  Arr.NonEmptyReadonlyArray<Uint8Array>,
  Socket.SocketError | IE,
  void,
  Arr.NonEmptyReadonlyArray<Uint8Array | string | Socket.CloseEvent>,
  IE
> =>
  Channel.unwrap(
    Effect.map(makeTls(options), Socket.toChannelWith<IE>())
  )

/**
 * Provides a `Socket.Socket` by opening a TLS connection with the supplied
 * Node `tls` connection options.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerTls: (options: Parameters<typeof makeTls>[0]) => Layer.Layer<
  Socket.Socket,
  Socket.SocketError
> = Function.flow(makeTls, Layer.effect(Socket.Socket))