@socketsecurity/lib 5.12.0 → 5.14.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.14.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.14.0) - 2026-04-06
+
+### Added — http-request
+
+- `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled, carries the full `HttpResponse`
+- `throwOnError` option on `HttpRequestOptions` — non-2xx responses throw instead of resolving with `ok: false`, enabling retry of HTTP errors
+- `onRetry` callback on `HttpRequestOptions` — customize retry behavior per-attempt (return `false` to stop, a `number` to override delay, `undefined` for default backoff)
+- Streaming body support — `body` accepts `Readable` streams (incl. `form-data` npm package), auto-merges `getHeaders()` when present
+- `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 `Retry-After` header parser (strict integer seconds + HTTP-date formats)
+- `sanitizeHeaders()` — redact sensitive headers (`authorization`, `cookie`, `set-cookie`, `proxy-authorization`, `proxy-authenticate`, `www-authenticate`) for safe logging
+
+### Changed — http-request
+
+- `HttpRequestOptions.body` type widened from `Buffer | string` to `Buffer | Readable | string`
+- Redirect responses now drained via `res.resume()` to free sockets
+- `maxResponseSize` exceeded now cleans up both response and request
+- `onResponse` hooks wrapped in try/catch — user hook errors can no longer leave promises pending
+
+## [5.13.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.13.0) - 2026-04-05
+
+### Added — http-request
+
+- `readIncomingResponse()` — reads and buffers a Node.js `IncomingResponse` into an `HttpResponse` (#143)
+  - Useful for converting raw responses from code that bypasses `httpRequest()` (e.g. multipart form-data uploads) into the standard `HttpResponse` interface
+- `IncomingResponse` type alias — disambiguates `IncomingMessage` as a client-side response
+- `IncomingRequest` type alias — disambiguates `IncomingMessage` as a server-side request
+
+### Changed — http-request
+
+- Internal `httpRequestAttempt` callbacks now use `IncomingResponse` type
+- `HttpResponse.rawResponse` type narrowed from `IncomingMessage` to `IncomingResponse`
+
 ## [5.12.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.12.0) - 2026-04-04
 
 ### Added — http-request

package/dist/http-request.d.ts

@@ -1,4 +1,24 @@
+/**
+ * @fileoverview HTTP/HTTPS request utilities using Node.js built-in modules with retry logic, redirects, and download support.
+ *
+ * This module provides a fetch-like API built on top of Node.js native `http` and `https` modules.
+ * It supports automatic retries with exponential backoff, redirect following, streaming downloads,
+ * and provides a familiar fetch-style response interface.
+ *
+ * Key Features:
+ * - Automatic retries with exponential backoff for failed requests.
+ * - Redirect following with configurable max redirects.
+ * - Streaming downloads with progress callbacks.
+ * - Fetch-like response interface (`.json()`, `.text()`, `.arrayBuffer()`).
+ * - Timeout support for all operations.
+ * - Zero dependencies on external HTTP libraries.
+ */
+import type { Readable } from 'node:stream';
 import type { IncomingHttpHeaders, IncomingMessage } from 'http';
+/** IncomingMessage received as a response to a client request (http.request callback). */
+export type IncomingResponse = IncomingMessage;
+/** IncomingMessage received as a request in a server handler (http.createServer callback). */
+export type IncomingRequest = IncomingMessage;
 import type { Logger } from './logger.js';
 /**
  * Information passed to the onRequest hook before each request attempt.
@@ -35,7 +55,17 @@ export interface HttpHooks {
 export interface HttpRequestOptions {
     /**
      * Request body to send.
-     * Can be a string (e.g., JSON) or Buffer (e.g., binary data).
+     * Can be a string, Buffer, or Readable stream.
+     *
+     * When a Readable stream is provided, it is piped directly to the request.
+     * If the stream has a `getHeaders()` method (duck-typed, e.g., the `form-data`
+     * npm package), its headers (Content-Type with boundary) are automatically
+     * merged into the request headers.
+     *
+     * **Note:** Streaming bodies are one-shot — they cannot be replayed. Using a
+     * Readable body with `retries > 0` throws an error. Buffer the body as a
+     * string/Buffer if retries are needed. Redirects are also disabled for
+     * streaming bodies since the stream is consumed on the first request.
      *
      * @example
      * ```ts
@@ -52,9 +82,18 @@ export interface HttpRequestOptions {
      *   method: 'POST',
      *   body: buffer
      * })
+     *
+     * // Stream form-data (npm package, not native FormData)
+     * import FormData from 'form-data'
+     * const form = new FormData()
+     * form.append('file', createReadStream('data.json'))
+     * await httpRequest('https://api.example.com/upload', {
+     *   method: 'POST',
+     *   body: form  // auto-merges form.getHeaders()
+     * })
      * ```
      */
-    body?: Buffer | string | undefined;
+    body?: Buffer | Readable | string | undefined;
     /**
      * Custom CA certificates for TLS connections.
      * When provided, these certificates are combined with the default trust
@@ -158,6 +197,38 @@ export interface HttpRequestOptions {
      * ```
      */
     method?: string | undefined;
+    /**
+     * Callback invoked before each retry attempt.
+     * Allows customizing retry behavior per-attempt (e.g., skip 4xx, honor Retry-After).
+     *
+     * @param attempt - Current retry attempt number (1-based)
+     * @param error - The error that triggered the retry (HttpResponseError for HTTP errors)
+     * @param delay - The calculated delay in ms before next retry
+     * @returns `false` to stop retrying and rethrow,
+     *          a `number` to override the delay (ms),
+     *          or `undefined` to use the calculated delay
+     *
+     * @example
+     * ```ts
+     * await httpRequest('https://api.example.com/data', {
+     *   retries: 3,
+     *   throwOnError: true,
+     *   onRetry: (attempt, error, delay) => {
+     *     // Don't retry client errors (except 429)
+     *     if (error instanceof HttpResponseError) {
+     *       if (error.response.status === 429) {
+     *         const retryAfter = parseRetryAfterHeader(error.response.headers['retry-after'])
+     *         return retryAfter ?? undefined
+     *       }
+     *       if (error.response.status >= 400 && error.response.status < 500) {
+     *         return false
+     *       }
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    onRetry?: ((attempt: number, error: unknown, delay: number) => boolean | number | undefined) | undefined;
     /**
      * Number of retry attempts for failed requests.
      * Uses exponential backoff: delay = `retryDelay` * 2^attempt.
@@ -190,6 +261,23 @@ export interface HttpRequestOptions {
      * ```
      */
     retryDelay?: number | undefined;
+    /**
+     * When true, non-2xx HTTP responses throw an `HttpResponseError` instead
+     * of resolving with `response.ok === false`. This makes HTTP error
+     * responses eligible for retry via the `retries` option.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // Throw on 4xx/5xx responses (enabling retry for 5xx)
+     * await httpRequest('https://api.example.com/data', {
+     *   throwOnError: true,
+     *   retries: 3
+     * })
+     * ```
+     */
+    throwOnError?: boolean | undefined;
     /**
      * Request timeout in milliseconds.
      * If the request takes longer than this, it will be aborted.
@@ -314,12 +402,71 @@ export interface HttpResponse {
      */
     text(): string;
     /**
-     * The underlying Node.js IncomingMessage for advanced use cases
+     * The underlying Node.js IncomingResponse for advanced use cases
      * (e.g., streaming, custom header inspection). Only available when
      * the response was not consumed by the convenience methods.
      */
-    rawResponse?: IncomingMessage | undefined;
+    rawResponse?: IncomingResponse | undefined;
+}
+/**
+ * Read and buffer a client-side IncomingResponse into an HttpResponse.
+ *
+ * Useful when you have a raw response from code that bypasses
+ * `httpRequest()` (e.g., multipart form-data uploads via `http.request()`,
+ * or responses from third-party HTTP libraries) and need to convert it
+ * into the standard HttpResponse interface.
+ */
+export declare function readIncomingResponse(msg: IncomingResponse): Promise<HttpResponse>;
+/**
+ * Error thrown when an HTTP response has a non-2xx status code
+ * and `throwOnError` is enabled. Carries the full `HttpResponse`
+ * so callers can inspect status, headers, and body.
+ */
+export declare class HttpResponseError extends Error {
+    response: HttpResponse;
+    constructor(response: HttpResponse, message?: string | undefined);
 }
+/**
+ * Parse a `Retry-After` HTTP header value into milliseconds.
+ *
+ * Supports both formats defined in RFC 7231 §7.1.3:
+ * - **delay-seconds**: integer number of seconds (e.g., `"120"`)
+ * - **HTTP-date**: an absolute date/time (e.g., `"Fri, 31 Dec 2027 23:59:59 GMT"`)
+ *
+ * When the header is an array (multiple values), the first element is used.
+ *
+ * @param value - The raw Retry-After header value(s)
+ * @returns Delay in milliseconds, or `undefined` if the value cannot be parsed
+ *
+ * @example
+ * ```ts
+ * const delay = parseRetryAfterHeader(response.headers['retry-after'])
+ * if (delay !== undefined) {
+ *   await new Promise(resolve => setTimeout(resolve, delay))
+ * }
+ * ```
+ */
+export declare function parseRetryAfterHeader(value: string | string[] | undefined): number | undefined;
+/**
+ * Redact sensitive HTTP headers for safe logging and telemetry.
+ *
+ * Replaces values of sensitive headers (Authorization, Cookie, etc.)
+ * with `[REDACTED]`. Non-sensitive headers are passed through unchanged.
+ * Array values are joined with `', '`.
+ *
+ * @param headers - HTTP headers to sanitize
+ * @returns A new object with sensitive values redacted
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeHeaders({
+ *   'authorization': 'Bearer secret',
+ *   'content-type': 'application/json'
+ * })
+ * // { authorization: '[REDACTED]', 'content-type': 'application/json' }
+ * ```
+ */
+export declare function sanitizeHeaders(headers: Record<string, unknown> | undefined): Record<string, string>;
 /**
  * Configuration options for file downloads.
  */

package/dist/http-request.js

@@ -19,13 +19,17 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var http_request_exports = {};
 __export(http_request_exports, {
+  HttpResponseError: () => HttpResponseError,
   enrichErrorMessage: () => enrichErrorMessage,
   fetchChecksums: () => fetchChecksums,
   httpDownload: () => httpDownload,
   httpJson: () => httpJson,
   httpRequest: () => httpRequest,
   httpText: () => httpText,
-  parseChecksums: () => parseChecksums
+  parseChecksums: () => parseChecksums,
+  parseRetryAfterHeader: () => parseRetryAfterHeader,
+  readIncomingResponse: () => readIncomingResponse,
+  sanitizeHeaders: () => sanitizeHeaders
 });
 module.exports = __toCommonJS(http_request_exports);
 var import_fs = require("./fs.js");
@@ -61,6 +65,87 @@ function getHttps() {
   }
   return _https;
 }
+async function readIncomingResponse(msg) {
+  const chunks = [];
+  for await (const chunk of msg) {
+    chunks.push(chunk);
+  }
+  const body = Buffer.concat(chunks);
+  const status = msg.statusCode ?? 0;
+  const statusText = msg.statusMessage ?? "";
+  return {
+    arrayBuffer: () => body.buffer.slice(
+      body.byteOffset,
+      body.byteOffset + body.byteLength
+    ),
+    body,
+    headers: msg.headers,
+    json: () => JSON.parse(body.toString("utf8")),
+    ok: status >= 200 && status < 300,
+    rawResponse: msg,
+    status,
+    statusText,
+    text: () => body.toString("utf8")
+  };
+}
+class HttpResponseError extends Error {
+  response;
+  constructor(response, message) {
+    const statusCode = response.status ?? "unknown";
+    const statusMessage = response.statusText || "No status message";
+    super(message ?? `HTTP ${statusCode}: ${statusMessage}`);
+    this.name = "HttpResponseError";
+    this.response = response;
+    Error.captureStackTrace(this, HttpResponseError);
+  }
+}
+function parseRetryAfterHeader(value) {
+  if (!value) {
+    return void 0;
+  }
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (!raw) {
+    return void 0;
+  }
+  const trimmed = raw.trim();
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    return seconds * 1e3;
+  }
+  const date = new Date(raw);
+  if (!Number.isNaN(date.getTime())) {
+    const delayMs = date.getTime() - Date.now();
+    if (delayMs > 0) {
+      return delayMs;
+    }
+  }
+  return void 0;
+}
+function sanitizeHeaders(headers) {
+  if (!headers) {
+    return {};
+  }
+  const sensitiveHeaders = /* @__PURE__ */ new Set([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "proxy-authenticate",
+    "set-cookie",
+    "www-authenticate"
+  ]);
+  const result = { __proto__: null };
+  for (const key of Object.keys(headers)) {
+    const value = headers[key];
+    if (sensitiveHeaders.has(key.toLowerCase())) {
+      result[key] = "[REDACTED]";
+    } else if (Array.isArray(value)) {
+      result[key] = value.join(", ");
+    } else if (value !== void 0 && value !== null) {
+      result[key] = String(value);
+    }
+  }
+  return result;
+}
 function parseChecksums(text) {
   const checksums = { __proto__: null };
   for (const line of text.split("\n")) {
@@ -273,12 +358,34 @@ async function httpRequestAttempt(url, options) {
     timeout = 3e4
   } = { __proto__: null, ...options };
   const startTime = Date.now();
+  const streamHeaders = body && typeof body === "object" && "getHeaders" in body && typeof body.getHeaders === "function" ? body.getHeaders() : void 0;
   const mergedHeaders = {
     "User-Agent": "socket-registry/1.0",
+    ...streamHeaders,
     ...headers
   };
   hooks?.onRequest?.({ method, url, headers: mergedHeaders, timeout });
   return await new Promise((resolve, reject) => {
+    let settled = false;
+    const resolveOnce = (response) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(response);
+    };
+    const rejectOnce = (err) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (body && typeof body === "object" && typeof body.destroy === "function") {
+        ;
+        body.destroy();
+      }
+      emitResponse({ error: err });
+      reject(err);
+    };
     const parsedUrl = new URL(url);
     const isHttps = parsedUrl.protocol === "https:";
     const httpModule = isHttps ? /* @__PURE__ */ getHttps() : /* @__PURE__ */ getHttp();
@@ -294,23 +401,28 @@ async function httpRequestAttempt(url, options) {
       requestOptions["ca"] = ca;
     }
     const emitResponse = (info) => {
-      hooks?.onResponse?.({
-        duration: Date.now() - startTime,
-        method,
-        url,
-        ...info
-      });
+      try {
+        hooks?.onResponse?.({
+          duration: Date.now() - startTime,
+          method,
+          url,
+          ...info
+        });
+      } catch {
+      }
     };
     const request = httpModule.request(
       requestOptions,
       (res) => {
         if (followRedirects && res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
           emitResponse({
             headers: res.headers,
             status: res.statusCode,
             statusText: res.statusMessage
           });
           if (maxRedirects <= 0) {
+            settled = true;
             reject(
               new Error(
                 `Too many redirects (exceeded maximum: ${maxRedirects})`
@@ -321,6 +433,7 @@ async function httpRequestAttempt(url, options) {
           const redirectUrl = res.headers.location.startsWith("http") ? res.headers.location : new URL(res.headers.location, url).toString();
           const redirectParsed = new URL(redirectUrl);
           if (isHttps && redirectParsed.protocol !== "https:") {
+            settled = true;
             reject(
               new Error(
                 `Redirect from HTTPS to HTTP is not allowed: ${redirectUrl}`
@@ -328,6 +441,7 @@ async function httpRequestAttempt(url, options) {
             );
             return;
           }
+          settled = true;
           resolve(
             httpRequestAttempt(redirectUrl, {
               body,
@@ -349,18 +463,22 @@ async function httpRequestAttempt(url, options) {
           totalBytes += chunk.length;
           if (maxResponseSize && totalBytes > maxResponseSize) {
             res.destroy();
+            request.destroy();
             const sizeMB = (totalBytes / (1024 * 1024)).toFixed(2);
             const maxMB = (maxResponseSize / (1024 * 1024)).toFixed(2);
-            const err = new Error(
-              `Response exceeds maximum size limit (${sizeMB}MB > ${maxMB}MB)`
+            rejectOnce(
+              new Error(
+                `Response exceeds maximum size limit (${sizeMB}MB > ${maxMB}MB)`
+              )
             );
-            emitResponse({ error: err });
-            reject(err);
             return;
           }
           chunks.push(chunk);
         });
         res.on("end", () => {
+          if (settled) {
+            return;
+          }
           const responseBody = Buffer.concat(chunks);
           const ok = res.statusCode !== void 0 && res.statusCode >= 200 && res.statusCode < 300;
           const response = {
@@ -388,11 +506,10 @@ async function httpRequestAttempt(url, options) {
             status: res.statusCode,
             statusText: res.statusMessage
           });
-          resolve(response);
+          resolveOnce(response);
         });
         res.on("error", (error) => {
-          emitResponse({ error });
-          reject(error);
+          rejectOnce(error);
         });
       }
     );
@@ -402,24 +519,33 @@ async function httpRequestAttempt(url, options) {
         method,
         error
       );
-      const enhanced = new Error(message, { cause: error });
-      emitResponse({ error: enhanced });
-      reject(enhanced);
+      rejectOnce(new Error(message, { cause: error }));
     });
     request.on("timeout", () => {
       request.destroy();
-      const err = new Error(
-        `${method} request timed out after ${timeout}ms: ${url}
+      rejectOnce(
+        new Error(
+          `${method} request timed out after ${timeout}ms: ${url}
 \u2192 Server did not respond in time.
 \u2192 Try: Increase timeout or check network connectivity.`
+        )
       );
-      emitResponse({ error: err });
-      reject(err);
     });
     if (body) {
+      if (typeof body === "object" && typeof body.pipe === "function") {
+        const stream = body;
+        stream.on("error", (err) => {
+          request.destroy();
+          rejectOnce(err);
+        });
+        stream.pipe(request);
+        return;
+      }
       request.write(body);
+      request.end();
+    } else {
+      request.end();
     }
-    request.end();
   });
 }
 async function httpDownload(url, destPath, options) {
@@ -547,31 +673,55 @@ async function httpRequest(url, options) {
     maxRedirects = 5,
     maxResponseSize,
     method = "GET",
+    onRetry,
     retries = 0,
     retryDelay = 1e3,
+    throwOnError = false,
     timeout = 3e4
   } = { __proto__: null, ...options };
+  const isStreamBody = body !== void 0 && typeof body === "object" && typeof body.pipe === "function";
+  if (isStreamBody && retries > 0) {
+    throw new Error(
+      "Streaming body (Readable/FormData) cannot be used with retries. Streams are consumed on first attempt and cannot be replayed. Set retries: 0 or buffer the body as a string/Buffer."
+    );
+  }
+  const attemptOpts = {
+    body,
+    ca,
+    // Disable redirect following for stream bodies — the stream is consumed
+    // on the first request and cannot be re-piped to the redirect target.
+    followRedirects: isStreamBody ? false : followRedirects,
+    headers,
+    hooks,
+    maxRedirects,
+    maxResponseSize,
+    method,
+    timeout
+  };
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
-      return await httpRequestAttempt(url, {
-        body,
-        ca,
-        followRedirects,
-        headers,
-        hooks,
-        maxRedirects,
-        maxResponseSize,
-        method,
-        timeout
-      });
+      const response = await httpRequestAttempt(url, attemptOpts);
+      if (throwOnError && !response.ok) {
+        throw new HttpResponseError(response);
+      }
+      return response;
     } catch (e) {
       lastError = e;
       if (attempt === retries) {
         break;
       }
       const delayMs = retryDelay * 2 ** attempt;
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      if (onRetry) {
+        const retryResult = onRetry(attempt + 1, e, delayMs);
+        if (retryResult === false) {
+          break;
+        }
+        const actualDelay = typeof retryResult === "number" && !Number.isNaN(retryResult) ? Math.max(0, retryResult) : delayMs;
+        await new Promise((resolve) => setTimeout(resolve, actualDelay));
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
     }
   }
   throw lastError || new Error("Request failed after retries");
@@ -607,11 +757,15 @@ async function httpText(url, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  HttpResponseError,
   enrichErrorMessage,
   fetchChecksums,
   httpDownload,
   httpJson,
   httpRequest,
   httpText,
-  parseChecksums
+  parseChecksums,
+  parseRetryAfterHeader,
+  readIncomingResponse,
+  sanitizeHeaders
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.12.0",
+  "version": "5.14.0",
   "packageManager": "pnpm@10.33.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
@@ -735,7 +735,7 @@
     "@socketregistry/is-unicode-supported": "1.0.5",
     "@socketregistry/packageurl-js": "1.4.1",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.11.4",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.13.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "4.0.3",