@socketsecurity/lib 5.11.4 → 5.12.0

package/dist/http-request.d.ts

@@ -1,4 +1,34 @@
+import type { IncomingHttpHeaders, IncomingMessage } from 'http';
 import type { Logger } from './logger.js';
+/**
+ * Information passed to the onRequest hook before each request attempt.
+ */
+export interface HttpHookRequestInfo {
+    headers: Record<string, string>;
+    method: string;
+    timeout: number;
+    url: string;
+}
+/**
+ * Information passed to the onResponse hook after each request attempt.
+ */
+export interface HttpHookResponseInfo {
+    duration: number;
+    error?: Error | undefined;
+    headers?: IncomingHttpHeaders | undefined;
+    method: string;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    url: string;
+}
+/**
+ * Lifecycle hooks for observing HTTP request/response events.
+ * Hooks fire per-attempt (retries produce multiple hook calls).
+ */
+export interface HttpHooks {
+    onRequest?: ((info: HttpHookRequestInfo) => void) | undefined;
+    onResponse?: ((info: HttpHookResponseInfo) => void) | undefined;
+}
 /**
  * Configuration options for HTTP/HTTPS requests.
  */
@@ -61,6 +91,11 @@ export interface HttpRequestOptions {
      * ```
      */
     followRedirects?: boolean | undefined;
+    /**
+     * Lifecycle hooks for observing request/response events.
+     * Hooks fire per-attempt — retries and redirects each trigger separate hook calls.
+     */
+    hooks?: HttpHooks | undefined;
     /**
      * HTTP headers to send with the request.
      * A `User-Agent` header is automatically added if not provided.
@@ -92,6 +127,14 @@ export interface HttpRequestOptions {
      * ```
      */
     maxRedirects?: number | undefined;
+    /**
+     * Maximum response body size in bytes. Responses exceeding this limit
+     * will be rejected with an error. Prevents memory exhaustion from
+     * unexpectedly large responses.
+     *
+     * @default undefined (no limit)
+     */
+    maxResponseSize?: number | undefined;
     /**
      * HTTP method to use for the request.
      *
@@ -205,7 +248,7 @@ export interface HttpResponse {
      * console.log(response.headers['set-cookie']) // May be string[]
      * ```
      */
-    headers: Record<string, string | string[] | undefined>;
+    headers: IncomingHttpHeaders;
     /**
      * Parse response body as JSON.
      * Type parameter `T` allows specifying the expected JSON structure.
@@ -270,6 +313,12 @@ export interface HttpResponse {
      * ```
      */
     text(): string;
+    /**
+     * The underlying Node.js IncomingMessage 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;
 }
 /**
  * Configuration options for file downloads.
@@ -567,6 +616,11 @@ export interface FetchChecksumsOptions {
  * ```
  */
 export declare function fetchChecksums(url: string, options?: FetchChecksumsOptions | undefined): Promise<Checksums>;
+/**
+ * Build an enriched error message based on the error code.
+ * Generic guidance (no product-specific branding).
+ */
+export declare function enrichErrorMessage(url: string, method: string, error: NodeJS.ErrnoException): string;
 /**
  * Download a file from a URL to a local path with redirect support, retry logic, and progress callbacks.
  * Uses streaming to avoid loading entire file in memory.

package/dist/http-request.js

@@ -19,6 +19,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var http_request_exports = {};
 __export(http_request_exports, {
+  enrichErrorMessage: () => enrichErrorMessage,
   fetchChecksums: () => fetchChecksums,
   httpDownload: () => httpDownload,
   httpJson: () => httpJson,
@@ -238,25 +239,51 @@ async function httpDownloadAttempt(url, destPath, options) {
     request.end();
   });
 }
+function enrichErrorMessage(url, method, error) {
+  const code = error.code;
+  let message = `${method} request failed: ${url}`;
+  if (code === "ECONNREFUSED") {
+    message += "\n\u2192 Connection refused. Server is unreachable.\n\u2192 Check: Network connectivity and firewall settings.";
+  } else if (code === "ENOTFOUND") {
+    message += "\n\u2192 DNS lookup failed. Cannot resolve hostname.\n\u2192 Check: Internet connection and DNS settings.";
+  } else if (code === "ETIMEDOUT") {
+    message += "\n\u2192 Connection timed out. Network or server issue.\n\u2192 Try: Check network connectivity and retry.";
+  } else if (code === "ECONNRESET") {
+    message += "\n\u2192 Connection reset by server. Possible network interruption.\n\u2192 Try: Retry the request.";
+  } else if (code === "EPIPE") {
+    message += "\n\u2192 Broken pipe. Server closed connection unexpectedly.\n\u2192 Check: Authentication credentials and permissions.";
+  } else if (code === "CERT_HAS_EXPIRED" || code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") {
+    message += "\n\u2192 SSL/TLS certificate error.\n\u2192 Check: System time and date are correct.\n\u2192 Try: Update CA certificates on your system.";
+  } else if (code) {
+    message += `
+\u2192 Error code: ${code}`;
+  }
+  return message;
+}
 async function httpRequestAttempt(url, options) {
   const {
     body,
     ca,
     followRedirects = true,
     headers = {},
+    hooks,
     maxRedirects = 5,
+    maxResponseSize,
     method = "GET",
     timeout = 3e4
   } = { __proto__: null, ...options };
+  const startTime = Date.now();
+  const mergedHeaders = {
+    "User-Agent": "socket-registry/1.0",
+    ...headers
+  };
+  hooks?.onRequest?.({ method, url, headers: mergedHeaders, timeout });
   return await new Promise((resolve, reject) => {
     const parsedUrl = new URL(url);
     const isHttps = parsedUrl.protocol === "https:";
     const httpModule = isHttps ? /* @__PURE__ */ getHttps() : /* @__PURE__ */ getHttp();
     const requestOptions = {
-      headers: {
-        "User-Agent": "socket-registry/1.0",
-        ...headers
-      },
+      headers: mergedHeaders,
       hostname: parsedUrl.hostname,
       method,
       path: parsedUrl.pathname + parsedUrl.search,
@@ -266,10 +293,23 @@ async function httpRequestAttempt(url, options) {
     if (ca && isHttps) {
       requestOptions["ca"] = ca;
     }
+    const emitResponse = (info) => {
+      hooks?.onResponse?.({
+        duration: Date.now() - startTime,
+        method,
+        url,
+        ...info
+      });
+    };
     const request = httpModule.request(
       requestOptions,
       (res) => {
         if (followRedirects && res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          emitResponse({
+            headers: res.headers,
+            status: res.statusCode,
+            statusText: res.statusMessage
+          });
           if (maxRedirects <= 0) {
             reject(
               new Error(
@@ -294,7 +334,9 @@ async function httpRequestAttempt(url, options) {
               ca,
               followRedirects,
               headers,
+              hooks,
               maxRedirects: maxRedirects - 1,
+              maxResponseSize,
               method,
               timeout
             })
@@ -302,7 +344,20 @@ async function httpRequestAttempt(url, options) {
           return;
         }
         const chunks = [];
+        let totalBytes = 0;
         res.on("data", (chunk) => {
+          totalBytes += chunk.length;
+          if (maxResponseSize && totalBytes > maxResponseSize) {
+            res.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)`
+            );
+            emitResponse({ error: err });
+            reject(err);
+            return;
+          }
           chunks.push(chunk);
         });
         res.on("end", () => {
@@ -321,39 +376,45 @@ async function httpRequestAttempt(url, options) {
               return JSON.parse(responseBody.toString("utf8"));
             },
             ok,
+            rawResponse: res,
             status: res.statusCode || 0,
             statusText: res.statusMessage || "",
             text() {
               return responseBody.toString("utf8");
             }
           };
+          emitResponse({
+            headers: res.headers,
+            status: res.statusCode,
+            statusText: res.statusMessage
+          });
           resolve(response);
         });
         res.on("error", (error) => {
+          emitResponse({ error });
           reject(error);
         });
       }
     );
     request.on("error", (error) => {
-      const code = error.code;
-      let message = `HTTP request failed for ${url}: ${error.message}
-`;
-      if (code === "ENOTFOUND") {
-        message += "DNS lookup failed. Check the hostname and your network connection.";
-      } else if (code === "ECONNREFUSED") {
-        message += "Connection refused. Verify the server is running and accessible.";
-      } else if (code === "ETIMEDOUT") {
-        message += "Request timed out. Check your network or increase the timeout value.";
-      } else if (code === "ECONNRESET") {
-        message += "Connection reset. The server may have closed the connection unexpectedly.";
-      } else {
-        message += "Check your network connection and verify the URL is correct.";
-      }
-      reject(new Error(message, { cause: error }));
+      const message = enrichErrorMessage(
+        url,
+        method,
+        error
+      );
+      const enhanced = new Error(message, { cause: error });
+      emitResponse({ error: enhanced });
+      reject(enhanced);
     });
     request.on("timeout", () => {
       request.destroy();
-      reject(new Error(`Request timed out after ${timeout}ms`));
+      const err = 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) {
       request.write(body);
@@ -482,7 +543,9 @@ async function httpRequest(url, options) {
     ca,
     followRedirects = true,
     headers = {},
+    hooks,
     maxRedirects = 5,
+    maxResponseSize,
     method = "GET",
     retries = 0,
     retryDelay = 1e3,
@@ -496,7 +559,9 @@ async function httpRequest(url, options) {
         ca,
         followRedirects,
         headers,
+        hooks,
         maxRedirects,
+        maxResponseSize,
         method,
         timeout
       });
@@ -542,6 +607,7 @@ async function httpText(url, options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  enrichErrorMessage,
   fetchChecksums,
   httpDownload,
   httpJson,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.11.4",
+  "version": "5.12.0",
   "packageManager": "pnpm@10.33.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
@@ -717,6 +717,7 @@
     "update": "node scripts/update.mjs"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-code": "2.1.89",
     "@babel/core": "7.28.4",
     "@babel/parser": "7.28.4",
     "@babel/traverse": "7.28.4",
@@ -732,9 +733,9 @@
     "@npmcli/package-json": "7.0.0",
     "@npmcli/promise-spawn": "8.0.3",
     "@socketregistry/is-unicode-supported": "1.0.5",
-    "@socketregistry/packageurl-js": "1.3.5",
+    "@socketregistry/packageurl-js": "1.4.1",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.11.3",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.11.4",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "4.0.3",