socketduct 0.1.15

package/src/reverse/common.js

@@ -0,0 +1,88 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
+import {readFileSync} from "node:fs"
+import {connect as tlsConnect} from "node:tls"
+
+export const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
+export const STABLE_IDENTIFIER = /^[A-Za-z0-9_-]{8,128}$/
+export const DEFAULT_WINDOW = 256 * 1024
+export const DEFAULT_FRAME_BYTES = 16 * 1024
+export const DEFAULT_MAX_STREAMS = 4096
+export const DEFAULT_HANDSHAKE_MS = 10_000
+export const DEFAULT_MAX_INPUT_BYTES = 64 * 1024
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
+export const DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS = 30_000
+export const MAX_CONTROL_BYTES = 64 * 1024
+
+/** @param {unknown} value - Candidate target. @returns {{host: string, port: number} | undefined} Valid target. */
+export function parseTarget(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const target = /** @type {{host?: unknown, port?: unknown}} */ (value)
+  if (typeof target.host !== "string" || target.host.length === 0 || target.host.length > 253 || !validPort(target.port)) return undefined
+  return {host: target.host, port: /** @type {number} */ (target.port)}
+}
+
+/** @param {unknown} value - Port. @returns {value is number} Validity. */
+export function validPort(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65_535
+}
+
+/** @param {unknown} value - Thrown value. @returns {Error} Error. */
+export function asError(value) {
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+/** @param {unknown} value - Candidate. @param {string} name - Name. @param {number} fallback - Default. @returns {number} Validated value. */
+export function positiveInteger(value, name, fallback) {
+  const selected = /** @type {number} */ (value ?? fallback)
+  if (!Number.isSafeInteger(selected) || selected <= 0) throw new RangeError(`${name} must be a positive integer`)
+  return selected
+}
+
+/**
+ * Loads verified client TLS material. Reverse-gateway transports never expose
+ * an option that disables certificate verification.
+ * @param {{caFile?: string, certFile?: string, keyFile?: string, servername?: string}} options - TLS files.
+ */
+export function resolveVerifiedTls(options) {
+  if (typeof options !== "object" || options === null) throw new TypeError("Reverse-gateway TLS configuration is required")
+  for (const key of Object.keys(options)) {
+    if (key !== "caFile" && key !== "certFile" && key !== "keyFile" && key !== "servername") throw new TypeError(`Unsupported reverse-gateway TLS option: ${key}`)
+  }
+  if ((options.certFile === undefined) !== (options.keyFile === undefined)) throw new TypeError("Reverse-gateway TLS certFile and keyFile must be supplied together")
+  if (options.servername !== undefined && (typeof options.servername !== "string" || options.servername.length === 0)) throw new TypeError("Reverse-gateway TLS servername must be non-empty")
+  return {
+    rejectUnauthorized: true,
+    ...(options.caFile === undefined ? {} : {ca: readFileSync(options.caFile)}),
+    ...(options.certFile === undefined ? {} : {cert: readFileSync(options.certFile)}),
+    ...(options.keyFile === undefined ? {} : {key: readFileSync(options.keyFile)}),
+    ...(options.servername === undefined ? {} : {servername: options.servername})
+  }
+}
+
+/** @param {{host: string, port: number, tls: object}} options - Hub endpoint. */
+export function createHubSocket(options) {
+  return tlsConnect({host: options.host, port: options.port, ...options.tls})
+}
+
+/** @param {import('node:stream').Writable & {destroyed?: boolean, writable?: boolean}} socket - Destination. @param {Buffer} bytes - Wire bytes. @param {() => void} [onWrite] - Called after bytes enter the writable queue. */
+export async function writeSocket(socket, bytes, onWrite) {
+  if (socket.destroyed === true || socket.writable === false) return false
+  const accepted = socket.write(bytes)
+  onWrite?.()
+  if (accepted) return true
+  return await new Promise((resolve) => {
+    const cleanup = () => { socket.off("drain", onDrain); socket.off("close", onClose); socket.off("error", onClose) }
+    const onDrain = () => { cleanup(); resolve(true) }
+    const onClose = () => { cleanup(); resolve(false) }
+    socket.once("drain", onDrain)
+    socket.once("close", onClose)
+    socket.once("error", onClose)
+  })
+}
+
+/** @param {string} code - Safe protocol code. */
+export function protocolError(code) {
+  const error = /** @type {Error & {code: string}} */ (new Error("Socketduct reverse-gateway protocol violation"))
+  error.code = code
+  return error
+}