http.ts

/**
 * @file Lazy-loader for socket-btm's `node:smol-http`. `node:smol-http` is the
 *   C++-accelerated HTTP server + client binding shipped by socket-btm's smol
 *   Node binary. It backs a pipelined HTTP/1.1 + HTTP/2 client (`request`), a
 *   uWS-backed server (`serve`), and a family of fast-path response writers
 *   (`fastJsonResponse`, `fastErrorResponse`, etc.) that bypass the
 *   `http.ServerResponse` allocation hot path. Returns `undefined` on stock
 *   Node + non-Node runtimes. Result is cached across calls.
 *
 * @internal — `src/http-request/` is the natural consumer. Most
 *   callers should use the standard `httpRequest` / `httpJson` /
 *   `httpText` exports, which already route through this when smol
 *   is present.
 */

import { isNodeBuiltin } from '../node/module'

/**
 * Options accepted by `smol-http`'s `request()`. The full surface is larger;
 * socket-lib types only the fields it actually reads. Callers needing more can
 * widen the type at the callsite.
 */
export interface SmolHttpRequestOptions {
  readonly method?: string | undefined
  readonly headers?: Readonly<Record<string, string>> | undefined
  readonly body?: string | Buffer | undefined
  readonly timeout?: number | undefined
}

/**
 * Surface of `node:smol-http`. See socket-btm's
 * additions/source-patched/lib/smol-http.js (and the
 * `internal/socketsecurity/http/core.js` barrel it re-exports) for the
 * canonical shape.
 *
 * Only the entries socket-lib's `http-request/` module needs are typed here.
 * The full surface (server-side `serve`, uWS-backed `fast*Response` writers,
 * `withCork`, `setPipelining`, etc.) is available as `Record<string, unknown>`
 * for callers that need it without expanding the contract here.
 */
export interface SmolHttpBinding {
  /**
   * Lean pipelining-aware HTTP client. Signature mirrors `node:http`'s
   * `request` but returns a thinner-allocation response.
   */
  request(url: string, options?: SmolHttpRequestOptions): Promise<unknown>
  /**
   * Toggle pipelining on the shared client pool. On by default.
   */
  setPipelining(enabled: boolean): void
  /**
   * `true` if the binary was built with io_uring support (Linux only).
   */
  readonly isIoUringAvailable: boolean
  /**
   * `true` if the binary was built with mimalloc.
   */
  readonly isMimallocAvailable: boolean
}

let _smolHttp: SmolHttpBinding | undefined
let _smolHttpProbed = false

/**
 * Returns `node:smol-http` when running on the smol Node binary, otherwise
 * `undefined`. Result is cached across calls.
 */
/*@__NO_SIDE_EFFECTS__*/
export function getSmolHttp(): SmolHttpBinding | undefined {
  if (!_smolHttpProbed) {
    _smolHttpProbed = true
    /* c8 ignore start - smol Node binary only. */
    if (isNodeBuiltin('node:smol-http')) {
      _smolHttp = require('node:smol-http') as SmolHttpBinding
    }
    /* c8 ignore stop */
  }
  return _smolHttp
}