socketduct 0.1.15

package/src/client/https-agent.js

@@ -0,0 +1,366 @@
+import {Agent} from "node:https"
+import {isIP} from "node:net"
+import {checkServerIdentity, connect as tlsConnect} from "node:tls"
+
+import {connectSocketduct, kCloseSocketductSession} from "./socketduct-socket.js"
+
+const requestContext = Symbol("socketductHttpsRequestContext")
+
+/**
+ * @typedef {import('./socketduct-socket.js').SocketductSocket} SocketductSocket
+ * @typedef {import('./socketduct-socket.js').SocketductTlsOptions} SocketductTlsOptions
+ * @typedef {object} SocketductTargetTlsOptions
+ * @property {string | Buffer | Array<string | Buffer>} [ca] - Target server CA material.
+ * @property {string | Buffer | Array<string | Buffer>} [cert] - Target client certificate material.
+ * @property {string | Buffer} [key] - Target client private key material.
+ * @property {boolean} [rejectUnauthorized] - Reject an unauthorized target certificate. Defaults to true.
+ * @property {string} [servername] - Non-empty target certificate identity and SNI hostname. Defaults to the request or fixed target host; SNI is omitted for IP literals.
+ * @typedef {object} SocketductHttpsAgentOptions
+ * @property {{host: string, port: number, token: string}} relay - Relay connection options.
+ * @property {SocketductTlsOptions} [relayTls] - TLS options for the edge-to-relay connection.
+ * @property {{host: string, port: number}} target - Target requested for every HTTPS connection.
+ * @property {SocketductTargetTlsOptions} [targetTls] - TLS options for the target HTTPS connection.
+ * @property {string} spoolDirectory - Spool directory.
+ * @property {{initialDelayMs?: number}} [reconnect] - Relay reconnect options.
+ * @property {string} [sessionNamePrefix] - Session name prefix.
+ * @property {string} [sessionName] - Fixed session name.
+ * @property {boolean} [keepAlive] - Keep sockets alive between HTTPS requests.
+ * @property {number} [maxSockets] - Maximum sockets.
+ * @property {number} [maxFreeSockets] - Maximum free sockets.
+ * @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.
+ * @typedef {{aborted: boolean, cancel: ((error: Error) => void) | undefined, ownSocket: (socket: import('node:stream').Duplex) => boolean}} RequestContext
+ * @typedef {{cancel: (error: Error, cleanup?: () => void) => void}} PendingConnection
+ */
+
+/** HTTPS agent whose target TCP transport is a resumable Socketduct session. */
+export class SocketductHttpsAgent extends Agent {
+  /** @type {SocketductHttpsAgentOptions} */
+  #options
+
+  /** @type {number} */
+  #connectionId = 0
+
+  /** @type {Set<PendingConnection>} */
+  #pending = new Set()
+
+  /** @type {boolean} */
+  #destroyed = false
+
+  /** @param {SocketductHttpsAgentOptions} options - Agent and tunnel options. */
+  constructor(options) {
+    if (options.targetTls?.servername !== undefined &&
+        (typeof options.targetTls.servername !== "string" || options.targetTls.servername.length === 0)) {
+      throw new TypeError("Target TLS servername must be a non-empty string")
+    }
+    super({
+      keepAlive: options.keepAlive,
+      maxSockets: options.maxSockets,
+      maxFreeSockets: options.maxFreeSockets
+    })
+    if ((options.targetTls?.cert === undefined) !== (options.targetTls?.key === undefined)) {
+      throw new Error("Target TLS cert and key must both be set (atomic pair)")
+    }
+    this.#options = options
+  }
+
+  /**
+   * Associates an asynchronous TLS connection attempt with its originating
+   * request so aborts before socket assignment still tear down the tunnel.
+   * @param {import('node:http').ClientRequest} req - Originating request.
+   * @param {import('node:http').ClientRequestArgs} options - Agent options.
+   * @param {(error: Error | null, socket?: import('node:tls').TLSSocket) => void} callback - Agent callback.
+   * @returns {void}
+   */
+  createSocket(req, options, callback) {
+    const requestSocketOwner = /** @type {{socket: import('node:stream').Duplex | null}} */ (/** @type {unknown} */ (req))
+    /** @type {import('node:stream').Duplex | undefined} */
+    let provisionalSocket
+    /** @type {RequestContext} */
+    const context = {
+      aborted: req.destroyed,
+      cancel: undefined,
+      ownSocket: (socket) => {
+        provisionalSocket = socket
+        // Node removes options.signal before calling Agent.addRequest(). Its
+        // AbortSignal handler still destroys req.socket, so expose only the
+        // in-progress ownership socket here. Do not call req.onSocket(): Node
+        // keeps HTTP output buffered until the Agent callback after secureConnect.
+        requestSocketOwner.socket = socket
+        if (!req.destroyed) return true
+        context.aborted = true
+        context.cancel?.(abortError())
+        return false
+      }
+    }
+    const abort = () => {
+      context.aborted = true
+      context.cancel?.(abortError())
+    }
+    const onClose = () => {
+      if (req.destroyed) abort()
+    }
+    const cleanup = () => {
+      req.off("abort", abort)
+      req.off("close", onClose)
+      if (requestSocketOwner.socket === provisionalSocket) requestSocketOwner.socket = null
+      provisionalSocket = undefined
+      context.cancel = undefined
+    }
+    req.once("abort", abort)
+    req.once("close", onClose)
+    const baseCreateSocket = /** @type {{createSocket: (req: import('node:http').ClientRequest, options: import('node:http').ClientRequestArgs, callback: (error: Error | null, socket?: import('node:stream').Duplex) => void) => void}} */ (/** @type {unknown} */ (Agent.prototype)).createSocket
+    baseCreateSocket.call(this, req, {...options, [requestContext]: context}, (error, socket) => {
+      cleanup()
+      callback(error, /** @type {import('node:tls').TLSSocket | undefined} */ (socket))
+    })
+  }
+
+  /**
+   * Creates the raw Socketduct session first, then performs target TLS over it.
+   * This asynchronous method requires the callback path used by Node's Agent.
+   * Returning undefined is intentional: Node must wait for secureConnect.
+   * @override
+   * @param {import('node:https').RequestOptions} options - Request connection options.
+   * @param {(error: Error | null, socket: import('node:stream').Duplex) => void} callback - Agent completion callback.
+   * @returns {undefined}
+   */
+  createConnection(options, callback) {
+    if (typeof callback !== "function") {
+      const error = /** @type {TypeError & {code: string}} */ (new TypeError("The callback argument must be a function for SocketductHttpsAgent.createConnection"))
+      error.code = "ERR_INVALID_ARG_TYPE"
+      throw error
+    }
+    /**
+     * @param {Error | null} error - Completion error.
+     * @param {import('node:stream').Duplex} [socket] - Connected TLS socket.
+     * @returns {void}
+     */
+    const done = (error, socket) => {
+      callback(error, /** @type {import('node:stream').Duplex} */ (socket))
+    }
+    this.#connectionId += 1
+    const sessionName = this.#options.sessionName
+      ?? `${this.#options.sessionNamePrefix ?? "socketduct-https"}-${this.#connectionId}`
+    /** @type {Parameters<typeof connectSocketduct>[0]} */
+    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.relayTls !== undefined) socketOptions.tls = this.#options.relayTls
+    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 | undefined} */
+    let rawSocket
+    /** @type {import('node:tls').TLSSocket | undefined} */
+    let tlsSocket
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timeoutTimer
+    let settled = false
+
+    /** @type {PendingConnection} */
+    const pending = {cancel: (error, cleanup) => settle(error, undefined, cleanup)}
+    const context = /** @type {import('node:https').RequestOptions & {[requestContext]?: RequestContext}} */ (options)[requestContext]
+
+    const clearTimeoutTimer = () => {
+      if (timeoutTimer !== undefined) {
+        clearTimeout(timeoutTimer)
+        timeoutTimer = undefined
+      }
+    }
+    const removePreConnectListeners = () => {
+      rawSocket?.off("connect", onRawConnect)
+      rawSocket?.off("error", onRawError)
+      tlsSocket?.off("secureConnect", onSecureConnect)
+      tlsSocket?.off("error", onTlsError)
+    }
+    /**
+     * @param {Error | null} error - Connection error or null on success.
+     * @param {import('node:tls').TLSSocket} [connectedSocket] - Established target TLS socket.
+     * @param {() => void} [cleanup] - Optional pending-agent cleanup callback.
+     * @returns {void}
+     */
+    function settle(error, connectedSocket, cleanup) {
+      if (settled) {
+        cleanup?.()
+        return
+      }
+      settled = true
+      clearTimeoutTimer()
+      removePreConnectListeners()
+      context && (context.cancel = undefined)
+      pendingAgent.#pending.delete(pending)
+      if (error !== null) {
+        const ignoreLateTlsError = () => {}
+        tlsSocket?.on("error", ignoreLateTlsError)
+        tlsSocket?.once("close", () => tlsSocket?.off("error", ignoreLateTlsError))
+        const finishError = () => {
+          tlsSocket?.destroy()
+          rawSocket?.destroy()
+          done(error)
+          cleanup?.()
+        }
+        if (rawSocket !== undefined && !rawSocket.destroyed) {
+          rawSocket.once("error", () => {})
+          if (rawSocket.sessionIdentifier !== undefined) {
+            void rawSocket[kCloseSocketductSession]().finally(finishError)
+          } else {
+            finishError()
+          }
+        } else {
+          finishError()
+        }
+        return
+      }
+      done(null, connectedSocket)
+      cleanup?.()
+    }
+    const pendingAgent = this
+
+    const onRawConnect = () => {
+      if (settled || rawSocket === undefined) return
+      const targetTls = this.#options.targetTls ?? {}
+      const requestIdentity = nonEmptyString(options.hostname) ?? nonEmptyString(options.host)
+      const certificateIdentity = targetTls.servername ?? requestIdentity ?? this.#options.target.host
+      const ipIdentity = isIP(certificateIdentity) !== 0
+      /** @type {import('node:tls').ConnectionOptions} */
+      const tlsOptions = {
+        socket: rawSocket,
+        rejectUnauthorized: targetTls.rejectUnauthorized !== false,
+        ...(targetTls.ca === undefined ? {} : {ca: targetTls.ca}),
+        ...(targetTls.cert === undefined ? {} : {cert: targetTls.cert}),
+        ...(targetTls.key === undefined ? {} : {key: targetTls.key})
+      }
+      if (ipIdentity) {
+        tlsOptions.servername = ""
+        tlsOptions.checkServerIdentity = (_hostname, certificate) => checkServerIdentity(certificateIdentity, certificate)
+      } else {
+        tlsOptions.servername = certificateIdentity
+      }
+      try {
+        tlsSocket = tlsConnect(tlsOptions)
+      } catch (error) {
+        settle(error instanceof Error ? error : new Error(String(error)))
+        return
+      }
+      tlsSocket.once("secureConnect", onSecureConnect)
+      tlsSocket.once("error", onTlsError)
+    }
+    /**
+     * @param {Error} error - Raw Socketduct error.
+     * @returns {void}
+     */
+    const onRawError = (error) => settle(error)
+    /** @returns {void} - Completes the target TLS handshake. */
+    const onSecureConnect = () => {
+      if (tlsSocket === undefined || rawSocket === undefined) return
+      const connectedTlsSocket = tlsSocket
+      const ownedRawSocket = rawSocket
+      const closeRawSocket = () => {
+        if (!ownedRawSocket.destroyed) ownedRawSocket.destroy()
+      }
+      const closeTlsSocket = () => {
+        if (!connectedTlsSocket.destroyed) connectedTlsSocket.destroy()
+      }
+      connectedTlsSocket.once("close", closeRawSocket)
+      ownedRawSocket.once("close", closeTlsSocket)
+      ownedRawSocket.on("error", (error) => {
+        if (!connectedTlsSocket.destroyed) connectedTlsSocket.destroy(error)
+      })
+      settle(null, connectedTlsSocket)
+    }
+    /**
+     * @param {Error} error - Target TLS error.
+     * @returns {void}
+     */
+    const onTlsError = (error) => settle(error)
+
+    this.#pending.add(pending)
+    if (context !== undefined) context.cancel = pending.cancel
+    if (this.#destroyed) {
+      settle(agentDestroyedError())
+      return undefined
+    }
+    if (context?.aborted) {
+      settle(abortError())
+      return undefined
+    }
+    try {
+      rawSocket = connectSocketduct(socketOptions)
+    } catch (error) {
+      settle(error instanceof Error ? error : new Error(String(error)))
+      return undefined
+    }
+    rawSocket.once("connect", onRawConnect)
+    rawSocket.once("error", onRawError)
+    if (context !== undefined && !context.ownSocket(rawSocket)) return undefined
+
+    if (typeof options.timeout === "number" && options.timeout > 0) {
+      const timeoutMs = options.timeout
+      timeoutTimer = setTimeout(() => settle(timeoutError(timeoutMs)), timeoutMs)
+      timeoutTimer.unref?.()
+    }
+    return undefined
+  }
+
+  /**
+   * Cancels pending handshakes and destroys established/free TLS sockets.
+   * @override
+   * @returns {void}
+   */
+  destroy() {
+    if (this.#destroyed) return
+    this.#destroyed = true
+    const error = agentDestroyedError()
+    const pendingConnections = [...this.#pending]
+    if (pendingConnections.length === 0) {
+      super.destroy()
+      return
+    }
+    let remaining = pendingConnections.length
+    const finish = () => {
+      remaining -= 1
+      if (remaining === 0) super.destroy()
+    }
+    for (const pending of pendingConnections) pending.cancel(error, finish)
+  }
+}
+
+/**
+ * @param {unknown} value - Candidate certificate identity.
+ * @returns {string | undefined} A non-empty identity.
+ */
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined
+}
+
+/** @returns {Error & {code: string}} Abort error. */
+function abortError() {
+  const error = /** @type {Error & {code: string}} */ (new Error("The operation was aborted"))
+  error.name = "AbortError"
+  error.code = "ABORT_ERR"
+  return error
+}
+
+/**
+ * @param {number} timeoutMs - Expired target TLS timeout.
+ * @returns {Error & {code: string}} Timeout error.
+ */
+function timeoutError(timeoutMs) {
+  const error = /** @type {Error & {code: string}} */ (new Error(`Target TLS connection timed out after ${timeoutMs}ms`))
+  error.code = "ETIMEDOUT"
+  return error
+}
+
+/** @returns {Error & {code: string}} Agent-destroyed error. */
+function agentDestroyedError() {
+  const error = /** @type {Error & {code: string}} */ (new Error("Socketduct HTTPS agent was destroyed"))
+  error.code = "ERR_SOCKETDUCT_AGENT_DESTROYED"
+  return error
+}