snapreq 0.0.1

package/src/transports/node-transport.js

@@ -0,0 +1,323 @@
+// @ts-check
+
+import {buildCapabilities} from "../capabilities.js"
+import {SnapReqAbortError, SnapReqUnsupportedFeatureError} from "../errors.js"
+import SnapReqHeaders from "../headers.js"
+import SnapReqResponse from "../response.js"
+
+/**
+ * Full-featured transport backed by Node's `http`/`https` modules. Supports
+ * Unix sockets, client TLS, keep-alive, request-body compression, response
+ * decompression and streaming. The `node:*` modules are loaded with a dynamic
+ * `import()` so this file never has to be bundled by web/Expo bundlers — the
+ * transport selector only imports it when running on Node.
+ */
+export default class NodeTransport {
+  /** @returns {string} - Transport name. */
+  static get transportName() {
+    return "node"
+  }
+
+  /** @returns {boolean} - Whether this transport can run in the current environment. */
+  static isAvailable() {
+    return typeof process !== "undefined" && Boolean(process.versions?.node)
+  }
+
+  /**
+   * @param {object} [config] - Transport configuration.
+   * @param {string} [config.socketPath] - Unix domain socket path.
+   * @param {{ca?: string | Buffer, cert?: string | Buffer, key?: string | Buffer, rejectUnauthorized?: boolean}} [config.tls] - TLS material for HTTPS connections.
+   * @param {boolean} [config.keepAlive] - Reuse connections across requests. Defaults to true.
+   */
+  constructor({socketPath, tls, keepAlive = true} = {}) {
+    this.socketPath = socketPath
+    this.tls = tls
+    this.keepAlive = keepAlive
+    /** @type {{http: any, https: any, zlib: any, stream: any} | null} */
+    this._modules = null
+    /** @type {any} */
+    this._httpAgent = null
+    /** @type {any} */
+    this._httpsAgent = null
+  }
+
+  /** @returns {import("../capabilities.js").TransportCapabilities} - Supported capabilities. */
+  get capabilities() {
+    return buildCapabilities({
+      unixSocket: true,
+      tlsClientCert: true,
+      requestCompression: true,
+      responseStreaming: true,
+      requestStreaming: true,
+      keepAlive: true,
+      abort: true
+    })
+  }
+
+  /** @returns {Promise<{http: any, https: any, zlib: any, stream: any}>} - Lazily-loaded Node modules. */
+  async _load() {
+    if (!this._modules) {
+      const [http, https, zlib, stream] = await Promise.all([
+        import("node:http"),
+        import("node:https"),
+        import("node:zlib"),
+        import("node:stream")
+      ])
+
+      this._modules = {http, https, zlib, stream}
+    }
+
+    return this._modules
+  }
+
+  /**
+   * @param {boolean} useTls - Whether the request uses TLS.
+   * @returns {any} - The keep-alive agent for the protocol.
+   */
+  _agent(useTls) {
+    const {http, https} = /** @type {{http: any, https: any}} */ (this._modules)
+
+    if (useTls) {
+      this._httpsAgent ||= new https.Agent({
+        keepAlive: this.keepAlive,
+        ...(this.tls?.ca !== undefined ? {ca: this.tls.ca} : {}),
+        ...(this.tls?.cert !== undefined ? {cert: this.tls.cert} : {}),
+        ...(this.tls?.key !== undefined ? {key: this.tls.key} : {}),
+        ...(this.tls?.rejectUnauthorized !== undefined ? {rejectUnauthorized: this.tls.rejectUnauthorized} : {})
+      })
+
+      return this._httpsAgent
+    }
+
+    this._httpAgent ||= new http.Agent({keepAlive: this.keepAlive})
+
+    return this._httpAgent
+  }
+
+  /**
+   * Performs a single request and resolves once the response headers arrive,
+   * exposing the (decoded) body as a stream so callers can buffer or stream it.
+   * @param {import("../snap-req.js").NormalizedRequest} request - Normalized request.
+   * @returns {Promise<SnapReqResponse>} - The response.
+   */
+  async performRequest(request) {
+    const modules = await this._load()
+    const {zlib, stream} = modules
+    const parsedUrl = new URL(request.url)
+    const useTls = Boolean(this.tls) || parsedUrl.protocol === "https:"
+    const httpModule = useTls ? modules.https : modules.http
+    const headers = new SnapReqHeaders(request.headers)
+    const requestBody = this._prepareRequestBody(request, headers, {zlib, stream})
+
+    /** @type {Record<string, any>} */
+    const requestOptions = {
+      method: request.method,
+      path: `${parsedUrl.pathname}${parsedUrl.search}`,
+      headers: headers.toObject(),
+      agent: this._agent(useTls)
+    }
+
+    if (this.socketPath) {
+      requestOptions.socketPath = this.socketPath
+    } else {
+      requestOptions.hostname = parsedUrl.hostname
+      requestOptions.port = parsedUrl.port || (useTls ? 443 : 80)
+    }
+
+    return await new Promise((resolve, reject) => {
+      if (request.signal?.aborted) {
+        reject(new SnapReqAbortError())
+        return
+      }
+
+      let settled = false
+      const abort = () => req.destroy(new SnapReqAbortError())
+      const removeAbortListener = () => request.signal?.removeEventListener("abort", abort)
+
+      const req = httpModule.request(requestOptions, (res) => {
+        /** @type {import("node:stream").Readable} */
+        let responseStream
+
+        try {
+          responseStream = this._decodeResponseStream(res, zlib)
+        } catch (error) {
+          if (!settled) {
+            settled = true
+            removeAbortListener()
+            reject(error)
+          }
+
+          return
+        }
+
+        // Re-point the abort listener at the response stream so aborting after
+        // headers arrive tears down the body stream rather than the request.
+        removeAbortListener()
+        const abortStream = () => responseStream.destroy(new SnapReqAbortError())
+
+        request.signal?.addEventListener("abort", abortStream, {once: true})
+        responseStream.on("close", () => request.signal?.removeEventListener("abort", abortStream))
+
+        settled = true
+        resolve(new SnapReqResponse({
+          url: request.url,
+          method: request.method,
+          status: res.statusCode,
+          statusText: res.statusMessage || "",
+          headers: this._responseHeaders(res),
+          stream: responseStream,
+          nodeStream: responseStream
+        }))
+      })
+
+      request.signal?.addEventListener("abort", abort, {once: true})
+
+      req.on("error", (/** @type {unknown} */ error) => {
+        removeAbortListener()
+
+        if (!settled) {
+          settled = true
+          reject(error)
+        }
+      })
+
+      if (requestBody.stream) {
+        requestBody.stream.pipe(req)
+      } else {
+        if (requestBody.buffer) req.write(requestBody.buffer)
+
+        req.end()
+      }
+    })
+  }
+
+  /**
+   * @param {import("../snap-req.js").NormalizedRequest} request - Normalized request.
+   * @param {SnapReqHeaders} headers - Headers, mutated with Content-Length / Content-Encoding.
+   * @param {{zlib: any, stream: any}} modules - Node modules.
+   * @returns {{buffer: Buffer | null, stream: import("node:stream").Readable | null}} - Prepared body.
+   */
+  _prepareRequestBody(request, headers, {zlib, stream}) {
+    const compression = request.bodyCompression || "identity"
+    const body = request.body
+
+    if (body.kind === "none") return {buffer: null, stream: null}
+
+    /** @type {Buffer | null} */
+    let buffer = null
+    /** @type {import("node:stream").Readable | null} */
+    let bodyStream = null
+
+    if (body.kind === "stream") {
+      const value = /** @type {any} */ (body.value)
+
+      bodyStream = typeof value.pipe === "function" ? value : stream.Readable.from(value)
+    } else if (body.kind === "bytes") {
+      buffer = Buffer.from(/** @type {Uint8Array} */ (body.value))
+    } else {
+      buffer = Buffer.from(/** @type {string} */ (body.value))
+    }
+
+    if (compression === "identity") {
+      if (buffer) headers.set("Content-Length", String(buffer.length))
+
+      return {buffer, stream: bodyStream}
+    }
+
+    if (headers.has("content-encoding")) {
+      throw new SnapReqUnsupportedFeatureError({
+        feature: "bodyCompression",
+        transport: "node",
+        detail: "cannot combine bodyCompression with an explicit Content-Encoding header"
+      })
+    }
+
+    headers.set("Content-Encoding", compression)
+
+    const compressor = this._requestCompressor(compression, zlib)
+    const source = bodyStream || stream.Readable.from(/** @type {Buffer} */ (buffer))
+
+    source.on("error", (/** @type {Error} */ error) => compressor.destroy(error))
+    source.pipe(compressor)
+
+    return {buffer: null, stream: compressor}
+  }
+
+  /**
+   * @param {string} encoding - Compression encoding.
+   * @param {any} zlib - The zlib module.
+   * @returns {import("node:stream").Transform} - A compressor transform.
+   */
+  _requestCompressor(encoding, zlib) {
+    if (encoding === "gzip") return zlib.createGzip()
+    if (encoding === "deflate") return zlib.createDeflate()
+    if (encoding === "br") return zlib.createBrotliCompress()
+    if (encoding === "zstd" && typeof zlib.createZstdCompress === "function") return zlib.createZstdCompress()
+
+    throw new SnapReqUnsupportedFeatureError({feature: `bodyCompression "${encoding}"`, transport: "node"})
+  }
+
+  /**
+   * @param {import("node:http").IncomingMessage} response - The raw response.
+   * @param {any} zlib - The zlib module.
+   * @returns {import("node:stream").Readable} - The decoded response body stream.
+   */
+  _decodeResponseStream(response, zlib) {
+    const header = response.headers["content-encoding"]
+    const headerValue = Array.isArray(header) ? header.join(",") : header
+    const encodings = (headerValue || "")
+      .split(",")
+      .map((encoding) => encoding.trim().toLowerCase())
+      .filter((encoding) => encoding && encoding !== "identity")
+
+    /** @type {import("node:stream").Readable} */
+    let decoded = response
+
+    for (let index = encodings.length - 1; index >= 0; index -= 1) {
+      decoded = decoded.pipe(this._responseDecoder(encodings[index], zlib))
+    }
+
+    return decoded
+  }
+
+  /**
+   * @param {string} encoding - Content encoding.
+   * @param {any} zlib - The zlib module.
+   * @returns {import("node:stream").Transform} - A decompressor transform.
+   */
+  _responseDecoder(encoding, zlib) {
+    if (encoding === "gzip" || encoding === "x-gzip") return zlib.createGunzip()
+    if (encoding === "deflate") return zlib.createInflate()
+    if (encoding === "br") return zlib.createBrotliDecompress()
+    if (encoding === "zstd" && typeof zlib.createZstdDecompress === "function") return zlib.createZstdDecompress()
+
+    throw new SnapReqUnsupportedFeatureError({feature: `response content-encoding "${encoding}"`, transport: "node"})
+  }
+
+  /**
+   * @param {import("node:http").IncomingMessage} response - The raw response.
+   * @returns {SnapReqHeaders} - The response headers.
+   */
+  _responseHeaders(response) {
+    const headers = new SnapReqHeaders()
+
+    for (const [name, value] of Object.entries(response.headers)) {
+      if (value === undefined) continue
+
+      headers.set(name, Array.isArray(value) ? value.join(", ") : value)
+    }
+
+    return headers
+  }
+
+  /**
+   * Destroys the keep-alive agents, closing all persistent connections.
+   * @returns {void}
+   */
+  close() {
+    this._httpAgent?.destroy()
+    this._httpsAgent?.destroy()
+    this._httpAgent = null
+    this._httpsAgent = null
+  }
+}

package/src/transports/select.js

@@ -0,0 +1,73 @@
+// @ts-check
+
+import {SnapReqError} from "../errors.js"
+import FetchTransport from "./fetch-transport.js"
+import XhrTransport from "./xhr-transport.js"
+
+/**
+ * @typedef {"auto" | "node" | "fetch" | "xhr"} TransportName
+ */
+
+/**
+ * @typedef {object} Transport
+ * @property {import("../capabilities.js").TransportCapabilities} capabilities - Supported capabilities.
+ * @property {(request: import("../snap-req.js").NormalizedRequest) => Promise<import("../response.js").default>} performRequest - Perform a request.
+ * @property {() => void} [close] - Optional resource cleanup.
+ */
+
+/**
+ * Detects the JavaScript runtime so `auto` can pick the right transport.
+ * @returns {"node" | "react-native" | "browser" | "unknown"} - Detected runtime.
+ */
+export function detectRuntime() {
+  const navigatorRef = /** @type {any} */ (globalThis).navigator
+
+  if (navigatorRef && navigatorRef.product === "ReactNative") return "react-native"
+  if (typeof process !== "undefined" && Boolean(process.versions?.node)) return "node"
+  if (typeof window !== "undefined" && typeof document !== "undefined") return "browser"
+
+  return "unknown"
+}
+
+/**
+ * @param {object} config - Node transport configuration.
+ * @returns {Promise<Transport>} - A Node transport instance.
+ */
+async function createNodeTransport(config) {
+  const {default: NodeTransport} = await import("./node-transport.js")
+
+  return new NodeTransport(config)
+}
+
+/**
+ * Resolves a transport for the requested preference. Returns the preference
+ * untouched when it is already a transport instance. The Node transport is
+ * imported dynamically so web/Expo bundlers never pull in `node:*` modules.
+ * @param {TransportName | Transport | undefined} preference - Requested transport.
+ * @param {object} nodeConfig - Configuration forwarded to the Node transport.
+ * @returns {Promise<Transport>} - The resolved transport.
+ */
+export async function selectTransport(preference, nodeConfig) {
+  if (preference && typeof preference === "object" && typeof (/** @type {any} */ (preference).performRequest) === "function") {
+    return /** @type {Transport} */ (preference)
+  }
+
+  const choice = /** @type {TransportName} */ (preference || "auto")
+
+  if (choice === "node") return await createNodeTransport(nodeConfig)
+  if (choice === "fetch") return new FetchTransport()
+  if (choice === "xhr") return new XhrTransport()
+
+  if (choice !== "auto") {
+    throw new SnapReqError(`Unknown transport "${choice}". Use "auto", "node", "fetch", "xhr" or a transport instance.`)
+  }
+
+  const runtime = detectRuntime()
+
+  if (runtime === "node") return await createNodeTransport(nodeConfig)
+  if (FetchTransport.isAvailable()) return new FetchTransport()
+  if (XhrTransport.isAvailable()) return new XhrTransport()
+  if (typeof process !== "undefined" && Boolean(process.versions?.node)) return await createNodeTransport(nodeConfig)
+
+  throw new SnapReqError("No suitable transport found: this platform has no fetch, XMLHttpRequest or Node http support.")
+}

package/src/transports/xhr-transport.js

@@ -0,0 +1,112 @@
+// @ts-check
+
+import {buildCapabilities} from "../capabilities.js"
+import {SnapReqAbortError, SnapReqUnsupportedFeatureError} from "../errors.js"
+import SnapReqHeaders from "../headers.js"
+import SnapReqResponse from "../response.js"
+
+/**
+ * Transport backed by `XMLHttpRequest`. A fallback for web environments that
+ * lack `fetch`. Buffers the whole response (no incremental streaming) and, like
+ * `fetch`, cannot do Unix sockets, client TLS or request-body compression.
+ */
+export default class XhrTransport {
+  /** @returns {string} - Transport name. */
+  static get transportName() {
+    return "xhr"
+  }
+
+  /** @returns {boolean} - Whether this transport can run in the current environment. */
+  static isAvailable() {
+    return typeof XMLHttpRequest === "function"
+  }
+
+  /** @returns {import("../capabilities.js").TransportCapabilities} - Supported capabilities. */
+  get capabilities() {
+    return buildCapabilities({abort: true})
+  }
+
+  /**
+   * @param {import("../snap-req.js").NormalizedRequest} request - Normalized request.
+   * @returns {Promise<SnapReqResponse>} - The response.
+   */
+  performRequest(request) {
+    if (request.bodyCompression && request.bodyCompression !== "identity") {
+      throw new SnapReqUnsupportedFeatureError({feature: "request body compression", transport: "xhr"})
+    }
+
+    if (request.body.kind === "stream") {
+      throw new SnapReqUnsupportedFeatureError({feature: "streamed request bodies", transport: "xhr"})
+    }
+
+    return new Promise((resolve, reject) => {
+      if (request.signal?.aborted) {
+        reject(new SnapReqAbortError())
+        return
+      }
+
+      const xhr = new XMLHttpRequest()
+
+      xhr.open(request.method, request.url, true)
+      xhr.responseType = "arraybuffer"
+
+      if (request.credentials === "include") xhr.withCredentials = true
+
+      for (const [name, value] of request.headers.entries()) xhr.setRequestHeader(name, value)
+
+      const abort = () => xhr.abort()
+
+      request.signal?.addEventListener("abort", abort, {once: true})
+
+      const cleanup = () => request.signal?.removeEventListener("abort", abort)
+
+      xhr.onload = () => {
+        cleanup()
+        resolve(new SnapReqResponse({
+          url: request.url,
+          method: request.method,
+          status: xhr.status,
+          statusText: xhr.statusText,
+          headers: this._parseHeaders(xhr.getAllResponseHeaders()),
+          bytes: new Uint8Array(/** @type {ArrayBuffer} */ (xhr.response) || new ArrayBuffer(0))
+        }))
+      }
+
+      xhr.onerror = () => {
+        cleanup()
+        reject(new Error(`XMLHttpRequest failed for ${request.method} ${request.url}`))
+      }
+
+      xhr.onabort = () => {
+        cleanup()
+        reject(new SnapReqAbortError())
+      }
+
+      const body = request.body
+
+      if (body.kind === "none") {
+        xhr.send()
+      } else {
+        xhr.send(/** @type {any} */ (body.value))
+      }
+    })
+  }
+
+  /**
+   * @param {string} rawHeaders - Raw header block from `getAllResponseHeaders`.
+   * @returns {SnapReqHeaders} - The parsed response headers.
+   */
+  _parseHeaders(rawHeaders) {
+    const headers = new SnapReqHeaders()
+
+    for (const line of rawHeaders.trim().split(/[\r\n]+/)) {
+      const separatorIndex = line.indexOf(":")
+
+      if (separatorIndex === -1) continue
+
+      headers.set(line.slice(0, separatorIndex).trim(), line.slice(separatorIndex + 1).trim())
+    }
+
+    return headers
+  }
+}

package/src/websocket/websocket-channel.js

@@ -0,0 +1,176 @@
+// @ts-check
+
+/**
+ * Client-side handle for a channel subscription opened via
+ * `SnapReqWebSocketClient.subscribeChannel()`. Mirrors the server's
+ * subscription lifecycle — `subscribed` (resolves `ready`) / `onMessage` /
+ * `onClose`.
+ */
+export default class SnapReqWebSocketChannel {
+  /**
+   * @param {object} args - Channel arguments.
+   * @param {import("./websocket-client.js").default} args.client - Owning client.
+   * @param {string} args.subscriptionId - Generated id unique within the session.
+   * @param {string} args.channelType - Name the server registered the channel under.
+   * @param {Record<string, any>} [args.params] - Opaque params forwarded to the server.
+   * @param {string} [args.lastEventId] - Resume replay from this event id.
+   * @param {(body: any) => void} [args.onMessage] - Fired on each `channel-message` from the server.
+   * @param {() => void} [args.onDisconnect] - Fired when the socket drops.
+   * @param {() => void} [args.onResume] - Fired when the session resumes after a drop.
+   * @param {(reason: string) => void} [args.onClose] - Fired exactly once when the subscription closes permanently.
+   */
+  constructor({client, subscriptionId, channelType, params, lastEventId, onMessage, onDisconnect, onResume, onClose}) {
+    this.client = client
+    this.subscriptionId = subscriptionId
+    this.channelType = channelType
+    this.params = params || {}
+    this.lastEventId = lastEventId
+    this._onMessage = onMessage
+    this._onDisconnect = onDisconnect
+    this._onResume = onResume
+    this._onClose = onClose
+    this._ready = false
+    this._resumeReadyOnResume = false
+    this._subscribed = false
+    this._subscribeSent = false
+    this._closed = false
+  }
+
+  /** @returns {Promise<void>} - Resolves once the subscription is acknowledged. */
+  _ensureReadyPromise() {
+    if (!this._readyPromise || !this._resolveReady || !this._rejectReady) {
+      /** @type {Promise<void>} */
+      this._readyPromise = new Promise((resolve, reject) => {
+        this._resolveReady = resolve
+        this._rejectReady = reject
+      })
+    }
+
+    return this._readyPromise
+  }
+
+  /** @returns {Promise<void>} - Resolves once the subscription is acknowledged. */
+  get ready() {
+    return this._ensureReadyPromise()
+  }
+
+  /** @returns {void} */
+  _resolveReadyState() {
+    this._ready = true
+    this._resolveReady?.()
+    this._resolveReady = null
+    this._rejectReady = null
+  }
+
+  /** @returns {void} */
+  _markNotReady() {
+    this._ready = false
+  }
+
+  /** @returns {void} */
+  _handleSubscribed() {
+    if (this._closed || this._subscribed) return
+    this._subscribed = true
+    this._resolveReadyState()
+  }
+
+  /** @returns {void} */
+  _markSubscribeSent() {
+    this._subscribeSent = true
+  }
+
+  /** @returns {boolean} - Whether the subscription still needs to be sent. */
+  _needsSubscribe() {
+    return !this._closed && !this._subscribeSent
+  }
+
+  /**
+   * @param {any} body - Message payload.
+   * @returns {void}
+   */
+  _handleMessage(body) {
+    if (this._closed) return
+    this._onMessage?.(body)
+  }
+
+  /** @returns {void} */
+  _handleDisconnected() {
+    if (this._closed) return
+    this._resumeReadyOnResume ||= this._subscribed
+    this._subscribed = false
+    this._markNotReady()
+    this._onDisconnect?.()
+  }
+
+  /** @returns {void} */
+  _handleResumed() {
+    if (this._closed) return
+    if (this._resumeReadyOnResume) {
+      this._subscribed = true
+      this._resolveReadyState()
+    }
+    this._resumeReadyOnResume = false
+    this._onResume?.()
+  }
+
+  /**
+   * @param {string} reason - Why the subscription closed.
+   * @returns {void}
+   */
+  _handleClosed(reason) {
+    if (this._closed) return
+    this._closed = true
+
+    try {
+      this._onClose?.(reason)
+    } finally {
+      this._resumeReadyOnResume = false
+      if (!this._ready) {
+        this._rejectReady?.(new Error(`Subscription closed before acknowledgement: ${reason}`))
+      }
+
+      this._resolveReady = null
+      this._rejectReady = null
+    }
+  }
+
+  /**
+   * @param {{timeoutMs?: number}} [params] - Options.
+   * @returns {Promise<void>} - Resolves once ready or rejects on timeout.
+   */
+  async waitForReady({timeoutMs = 5000} = {}) {
+    if (this._ready) return
+
+    const readyPromise = this._ensureReadyPromise()
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error(`Subscription not ready after ${timeoutMs}ms`)), timeoutMs)
+    })
+
+    await Promise.race([readyPromise, timeoutPromise])
+  }
+
+  /** @returns {void} */
+  close() {
+    if (this._closed) return
+
+    try {
+      if (this.client.isOpen()) {
+        this.client._sendMessage({type: "channel-unsubscribe", subscriptionId: this.subscriptionId})
+      }
+    } catch {
+      // Socket already gone; server will clean up on session teardown.
+    }
+
+    this.client._removeChannelSubscription(this.subscriptionId)
+    this._handleClosed("client_unsubscribe")
+  }
+
+  /** @returns {boolean} - Whether the subscription is closed. */
+  isClosed() { return this._closed }
+
+  /** @returns {boolean} - Whether the subscription is acknowledged and ready. */
+  isReady() { return this._ready }
+
+  /** @returns {boolean} - Whether the subscription is active. */
+  isSubscribed() { return this._subscribed && !this._closed }
+}