socketduct 0.1.15

package/src/client/deferred-virtual-socket.js

@@ -0,0 +1,312 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/no-undefined-types, jsdoc/require-returns */
+import {SocketductStreamError, VirtualSocket} from "./virtual-socket.js"
+
+/**
+ * @typedef {object} PendingByteBudget
+ * @property {(bytes: number) => void} reserveMemory - Reserve pending application bytes.
+ * @property {(bytes: number) => void} releaseMemory - Release pending application bytes.
+ * @typedef {object} DeferredVirtualSocketOptions
+ * @property {PendingByteBudget} budget - Set-wide byte budget.
+ * @property {() => void} onCancel - Remove an unassigned socket from the set queue.
+ * @property {() => void} ref - Reference set resources.
+ * @property {() => void} unref - Unreference set resources.
+ * @typedef {object} WriteReservation
+ * @property {number} bytes - Reserved bytes.
+ * @property {boolean} held - Whether the reservation is still charged.
+ */
+
+/** Bridges one not-yet-assigned socket into its eventual member VirtualSocket. */
+class DeferredSocketOwner {
+  /** @type {PendingByteBudget} */
+  #budget
+
+  /** @type {() => void} */
+  #onCancel
+
+  /** @type {() => void} */
+  #ref
+
+  /** @type {() => void} */
+  #unref
+
+  /** @type {DeferredVirtualSocket | undefined} */
+  #outer
+
+  /** @type {VirtualSocket | undefined} */
+  #inner
+
+  /** @type {WriteReservation[]} */
+  #writeReservations = []
+
+  /** @type {{data: Buffer, callback: (error?: Error | null) => void, reservation: WriteReservation} | undefined} */
+  #activeWrite
+
+  /** @type {((error?: Error | null) => void) | undefined} */
+  #activeFinal
+
+  /** @type {boolean} */
+  #cancelled = false
+
+  /** @param {DeferredVirtualSocketOptions} options - Set-owned deferred socket policy. */
+  constructor(options) {
+    this.#budget = options.budget
+    this.#onCancel = options.onCancel
+    this.#ref = options.ref
+    this.#unref = options.unref
+  }
+
+  /** @param {DeferredVirtualSocket} socket - Public socket facade. */
+  attach(socket) {
+    this.#outer = socket
+  }
+
+  /** @param {number} bytes - Application bytes entering the pending socket. @returns {WriteReservation} */
+  reserveWrite(bytes) {
+    this.#budget.reserveMemory(bytes)
+    const reservation = {bytes, held: true}
+    this.#writeReservations.push(reservation)
+    return reservation
+  }
+
+  /** @param {WriteReservation} reservation - Reservation whose write settled or was rejected. */
+  releaseWrite(reservation) {
+    if (!reservation.held) return
+    reservation.held = false
+    this.#budget.releaseMemory(reservation.bytes)
+  }
+
+  /** @param {WriteReservation} reservation - Reservation for a write rejected before entering the stream. */
+  rollbackWrite(reservation) {
+    const index = this.#writeReservations.indexOf(reservation)
+    if (index !== -1) this.#writeReservations.splice(index, 1)
+    this.releaseWrite(reservation)
+  }
+
+  /**
+   * Assigns exactly one authenticated ready-member socket.
+   * @param {VirtualSocket} inner - Selected member socket.
+   * @returns {boolean} Whether the facade accepted the member.
+   */
+  assign(inner) {
+    if (this.#inner !== undefined) throw new Error("Deferred Socketduct socket is already assigned")
+    if (this.#cancelled || this.#outer === undefined || this.#outer.destroyed) {
+      inner.destroy()
+      return false
+    }
+    const outer = this.#outer
+    this.#inner = inner
+    inner.on("data", (chunk) => {
+      if (!outer._receive(Buffer.from(chunk))) inner.pause()
+    })
+    inner.once("end", () => outer._receiveEnd())
+    inner.on("error", (error) => outer._receiveError(error))
+    inner.once("close", () => {
+      if (outer.destroyed) return
+      if (outer.connecting) outer._receiveError(new SocketductStreamError("Selected Socketduct member closed before connecting", "ERR_SOCKET_CLOSED_BEFORE_CONNECTION"))
+      else outer.destroy()
+    })
+    inner.on("ready", () => outer._markConnected())
+    if (!inner.connecting) queueMicrotask(() => outer._markConnected())
+    if (this.#activeWrite !== undefined) {
+      const active = this.#activeWrite
+      this.#activeWrite = undefined
+      this.releaseWrite(active.reservation)
+      inner.write(active.data, active.callback)
+    }
+    if (this.#activeFinal !== undefined) {
+      const callback = this.#activeFinal
+      this.#activeFinal = undefined
+      inner.end(callback)
+    }
+    return true
+  }
+
+  /** @returns {{address?: string, port?: number}} Physical endpoint metadata. */
+  physicalAddress() {
+    if (this.#inner === undefined) return {}
+    const address = this.#inner.address()
+    return "address" in address ? {address: address.address, port: address.port} : {}
+  }
+
+  /** @returns {number} Assigned protocol stream ID, or zero while unassigned. */
+  streamId() {
+    return this.#inner?.streamId ?? 0
+  }
+
+  /**
+   * @param {number} _streamId - Facade stream ID.
+   * @param {Buffer} data - Application bytes.
+   * @param {(error?: Error | null) => void} callback - Completion.
+   */
+  _writeStream(_streamId, data, callback) {
+    const reservation = this.#writeReservations.shift()
+    if (reservation === undefined) throw new Error("Deferred Socketduct write has no byte reservation")
+    if (this.#inner === undefined) {
+      this.#activeWrite = {data, callback, reservation}
+      return
+    }
+    this.releaseWrite(reservation)
+    this.#inner.write(data, callback)
+  }
+
+  /**
+   * @param {number} _streamId - Facade stream ID.
+   * @param {(error?: Error | null) => void} callback - Completion.
+   */
+  _endStream(_streamId, callback) {
+    if (this.#inner === undefined) {
+      this.#activeFinal = callback
+      return
+    }
+    this.#inner.end(callback)
+  }
+
+  /**
+   * @param {number} _streamId - Facade stream ID.
+   * @param {Error | null} error - Destroy cause.
+   */
+  _destroyStream(_streamId, error) {
+    if (this.#cancelled) return
+    this.#cancelled = true
+    this.#onCancel()
+    for (const reservation of this.#writeReservations) this.releaseWrite(reservation)
+    this.#writeReservations = []
+    if (this.#activeWrite !== undefined) {
+      const active = this.#activeWrite
+      this.#activeWrite = undefined
+      this.releaseWrite(active.reservation)
+      active.callback(error ?? new SocketductStreamError("Deferred Socketduct socket was destroyed", "ERR_STREAM_DESTROYED"))
+    }
+    if (this.#activeFinal !== undefined) {
+      const callback = this.#activeFinal
+      this.#activeFinal = undefined
+      callback(error ?? new SocketductStreamError("Deferred Socketduct socket was destroyed", "ERR_STREAM_DESTROYED"))
+    }
+    if (this.#inner !== undefined && !this.#inner.destroyed) this.#inner.destroy(error ?? undefined)
+  }
+
+  /** @param {number} _streamId - Facade stream ID. */
+  _resumeReadable(_streamId) {
+    void _streamId
+    if (this.#inner !== undefined) this.#inner.resume()
+  }
+
+  /** References the assigned member or the whole set while pending. */
+  ref() {
+    if (this.#inner === undefined) this.#ref()
+    else this.#inner.ref()
+  }
+
+  /** Unreferences the assigned member or the whole set while pending. */
+  unref() {
+    if (this.#inner === undefined) this.#unref()
+    else this.#inner.unref()
+  }
+}
+
+/** A normal VirtualSocket that delays member ownership until readiness. */
+export class DeferredVirtualSocket extends VirtualSocket {
+  /** @type {DeferredSocketOwner} */
+  #owner
+
+  /** @type {string | undefined} */
+  #gatewayId
+
+  /**
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} socketOptions - Target/socket options.
+   * @param {DeferredVirtualSocketOptions} deferredOptions - Set-owned wait policy.
+   */
+  constructor(socketOptions, deferredOptions) {
+    const owner = new DeferredSocketOwner(deferredOptions)
+    super(/** @type {import('./virtual-socket.js').VirtualSocketOwner} */ (owner), 0, socketOptions)
+    this.#owner = owner
+    owner.attach(this)
+    Object.defineProperty(this, "gatewayId", {get: () => this.#gatewayId, enumerable: true, configurable: false})
+  }
+
+  /** @returns {string | undefined} Immutable assignment selected only after readiness. */
+  get gatewayId() {
+    return this.#gatewayId
+  }
+
+  /**
+   * @override
+   * @returns {number} Assigned protocol stream ID, or zero while unassigned.
+   */
+  get streamId() {
+    return this.#owner.streamId()
+  }
+
+  /**
+   * @param {VirtualSocket} socket - Selected ready-member socket.
+   * @param {string} gatewayId - Stable selected gateway ID.
+   * @returns {boolean} Whether assignment succeeded before cancellation.
+   */
+  assign(socket, gatewayId) {
+    if (this.#gatewayId !== undefined) throw new Error("Deferred Socketduct socket gateway is already assigned")
+    if (!this.#owner.assign(socket)) return false
+    this.#gatewayId = gatewayId
+    return true
+  }
+
+  /**
+   * Hard-bounds bytes retained before member assignment while retaining Writable backpressure.
+   * @override
+   * @param {string | NodeJS.ArrayBufferView} chunk - Application bytes.
+   * @param {BufferEncoding | ((error?: Error | null) => void)} [encoding] - Encoding or completion.
+   * @param {(error?: Error | null) => void} [callback] - Completion.
+   * @returns {boolean} Writable backpressure state.
+   */
+  write(chunk, encoding, callback) {
+    const selectedEncoding = typeof encoding === "string" ? encoding : undefined
+    const selectedCallback = typeof encoding === "function" ? encoding : callback
+    if (typeof chunk !== "string" && !ArrayBuffer.isView(chunk)) {
+      return selectedEncoding === undefined
+        ? super.write(chunk, selectedCallback)
+        : super.write(chunk, selectedEncoding, selectedCallback)
+    }
+    const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk, selectedEncoding) : chunk.byteLength
+    /** @type {WriteReservation} */
+    let reservation
+    try {
+      reservation = this.#owner.reserveWrite(bytes)
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error))
+      queueMicrotask(() => {
+        if (selectedCallback !== undefined) selectedCallback(failure)
+        this.destroy(failure)
+      })
+      return false
+    }
+    const completed = (/** @type {Error | null | undefined} */ error) => {
+      this.#owner.releaseWrite(reservation)
+      if (selectedCallback !== undefined) selectedCallback(error)
+    }
+    try {
+      return selectedEncoding === undefined
+        ? super.write(chunk, completed)
+        : super.write(chunk, selectedEncoding, completed)
+    } catch (error) {
+      this.#owner.rollbackWrite(reservation)
+      throw error
+    }
+  }
+
+  /**
+   * Routes final application bytes through the same bounded reservation as write().
+   * @override
+   * @param {string | NodeJS.ArrayBufferView | (() => void)} [chunk] - Final application bytes or completion.
+   * @param {BufferEncoding | (() => void)} [encoding] - Encoding or completion.
+   * @param {() => void} [callback] - Completion after finish.
+   * @returns {this} This socket.
+   */
+  end(chunk, encoding, callback) {
+    if (typeof chunk === "function") return super.end(chunk)
+    const selectedCallback = typeof encoding === "function" ? encoding : callback
+    if (chunk !== undefined) {
+      if (typeof encoding === "string") this.write(chunk, encoding)
+      else this.write(chunk)
+    }
+    return selectedCallback === undefined ? super.end() : super.end(selectedCallback)
+  }
+}

package/src/client/http-agent.js

@@ -0,0 +1,101 @@
+import {Agent} from "node:http"
+
+import {connectSocketduct} from "./socketduct-socket.js"
+
+/**
+ * @typedef {import('./socketduct-socket.js').ConnectSocketductOptions} ConnectSocketductOptions
+ * @typedef {import('./socketduct-socket.js').SocketductSocket} SocketductSocket
+ * @typedef {import('./socketduct-socket.js').SocketductTlsOptions} SocketductTlsOptions
+ * @typedef {object} SocketductHttpAgentOptions
+ * @property {{host: string, port: number, token: string}} relay - Relay connection options.
+ * @property {{host: string, port: number}} target - Target requested for every HTTP connection.
+ * @property {string} spoolDirectory - Spool directory.
+ * @property {{initialDelayMs?: number}} [reconnect] - Reconnect options.
+ * @property {string} [sessionNamePrefix] - Session name prefix.
+ * @property {string} [sessionName] - Fixed session name.
+ * @property {boolean} [keepAlive] - Keep sockets alive between HTTP requests.
+ * @property {number} [maxSockets] - Maximum sockets.
+ * @property {number} [maxFreeSockets] - Maximum free sockets.
+ * @property {SocketductTlsOptions} [tls] - TLS client options.
+ * @property {number} [maxBytes] - Maximum total spool bytes per session.
+ * @property {number} [maxAgeMs] - Maximum age of a spool session before operations are rejected.
+ * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured diagnostic logger.
+ */
+
+export class SocketductHttpAgent extends Agent {
+  /** @type {SocketductHttpAgentOptions} */
+  #options
+
+  /** @type {number} */
+  #connectionId = 0
+
+  /** @param {SocketductHttpAgentOptions} options - Agent options. */
+  constructor(options) {
+    super({
+      keepAlive: options.keepAlive,
+      maxSockets: options.maxSockets,
+      maxFreeSockets: options.maxFreeSockets
+    })
+    this.#options = options
+  }
+
+  /**
+   * @override
+   * @param {import('node:http').ClientRequestArgs} _options - HTTP connection options supplied by Node.
+   * @param {(error: Error | null, socket: SocketductSocket) => void} [callback] - Optional socket callback.
+   * @returns {SocketductSocket} - Socketduct-backed HTTP socket.
+   */
+  createConnection(_options, callback) {
+    this.#connectionId += 1
+    const sessionName = this.#options.sessionName
+      ?? `${this.#options.sessionNamePrefix ?? "socketduct-http"}-${this.#connectionId}`
+    /** @type {ConnectSocketductOptions} */
+    const socketOptions = {
+      relay: this.#options.relay,
+      sessionName,
+      target: this.#options.target,
+      spoolDirectory: this.#options.spoolDirectory
+    }
+    if (this.#options.reconnect !== undefined) {
+      socketOptions.reconnect = this.#options.reconnect
+    }
+    if (this.#options.tls !== undefined) {
+      socketOptions.tls = this.#options.tls
+    }
+    if (this.#options.maxBytes !== undefined) {
+      socketOptions.maxBytes = this.#options.maxBytes
+    }
+    if (this.#options.maxAgeMs !== undefined) {
+      socketOptions.maxAgeMs = this.#options.maxAgeMs
+    }
+    if (this.#options.logger !== undefined) {
+      socketOptions.logger = this.#options.logger
+    }
+    /** @type {SocketductSocket} */
+    const socket = connectSocketduct(socketOptions)
+    if (callback !== undefined) {
+      let settled = false
+      /**
+       * @param {Error | null} error - Connection result.
+       * @returns {void}
+       */
+      const settle = (error) => {
+        if (settled) return
+        settled = true
+        socket.off("connect", onConnect)
+        socket.off("error", onError)
+        callback(error, socket)
+      }
+      /** @returns {void} */
+      const onConnect = () => settle(null)
+      /**
+       * @param {Error} error - Pre-connect Socketduct failure.
+       * @returns {void}
+       */
+      const onError = (error) => settle(error)
+      socket.once("connect", onConnect)
+      socket.once("error", onError)
+    }
+    return socket
+  }
+}