@socketsecurity/lib 5.14.0 → 5.15.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.15.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.15.0) - 2026-04-06
+
+### Added — http-request
+
+- `stream` option on `HttpRequestOptions` — resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
+- `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
+
+### Changed — http-request
+
+- `httpDownload` now uses `httpRequest` with `stream: true` internally, eliminating ~120 lines of duplicated HTTP plumbing
+
 ## [5.14.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.14.0) - 2026-04-06
 
 ### Added — http-request

package/dist/http-request.d.ts

@@ -277,6 +277,20 @@ export interface HttpRequestOptions {
      * })
      * ```
      */
+    /**
+     * When true, resolve with an HttpResponse whose body is NOT buffered.
+     * The `rawResponse` property contains the unconsumed IncomingResponse
+     * stream for piping to files or other destinations.
+     *
+     * `body`, `text()`, `json()`, and `arrayBuffer()` return empty/zero
+     * values since the stream has not been read.
+     *
+     * Incompatible with `maxResponseSize` (size enforcement requires
+     * reading the body).
+     *
+     * @default false
+     */
+    stream?: boolean | undefined;
     throwOnError?: boolean | undefined;
     /**
      * Request timeout in milliseconds.
@@ -657,26 +671,18 @@ export interface HttpDownloadOptions {
  * Result of a successful file download.
  */
 export interface HttpDownloadResult {
-    /**
-     * Absolute path where the file was saved.
-     *
-     * @example
-     * ```ts
-     * const result = await httpDownload('https://example.com/file.zip', '/tmp/file.zip')
-     * console.log(`Downloaded to: ${result.path}`)
-     * ```
-     */
+    /** HTTP response headers from the final response (after redirects). */
+    headers: IncomingHttpHeaders;
+    /** Whether the download succeeded (status 200-299). Always true on success (non-2xx throws). */
+    ok: true;
+    /** Absolute path where the file was saved. */
     path: string;
-    /**
-     * Total size of downloaded file in bytes.
-     *
-     * @example
-     * ```ts
-     * const result = await httpDownload('https://example.com/file.zip', '/tmp/file.zip')
-     * console.log(`Downloaded ${result.size} bytes`)
-     * ```
-     */
+    /** Total size of downloaded file in bytes. */
     size: number;
+    /** HTTP status code from the final response (after redirects). */
+    status: number;
+    /** HTTP status message from the final response (after redirects). */
+    statusText: string;
 }
 /**
  * Map of filenames to their SHA256 hashes.

package/dist/http-request.js

@@ -193,135 +193,61 @@ async function httpDownloadAttempt(url, destPath, options) {
     onProgress,
     timeout = 12e4
   } = { __proto__: null, ...options };
+  const response = await httpRequestAttempt(url, {
+    ca,
+    followRedirects,
+    headers,
+    maxRedirects,
+    method: "GET",
+    stream: true,
+    timeout
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Download failed: HTTP ${response.status} ${response.statusText}`
+    );
+  }
+  const res = response.rawResponse;
+  if (!res) {
+    throw new Error("Stream response missing rawResponse");
+  }
+  const { createWriteStream } = /* @__PURE__ */ getFs();
+  const totalSize = Number.parseInt(
+    response.headers["content-length"] || "0",
+    10
+  );
   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
-      },
-      hostname: parsedUrl.hostname,
-      method: "GET",
-      path: parsedUrl.pathname + parsedUrl.search,
-      port: parsedUrl.port,
-      timeout
-    };
-    if (ca && isHttps) {
-      requestOptions["ca"] = ca;
-    }
-    const { createWriteStream } = /* @__PURE__ */ getFs();
-    let fileStream;
-    let streamClosed = false;
-    const closeStream = () => {
-      if (!streamClosed && fileStream) {
-        streamClosed = true;
-        fileStream.close();
+    let downloadedSize = 0;
+    const fileStream = createWriteStream(destPath);
+    fileStream.on("error", (error) => {
+      fileStream.close();
+      reject(
+        new Error(`Failed to write file: ${error.message}`, { cause: error })
+      );
+    });
+    res.on("data", (chunk) => {
+      downloadedSize += chunk.length;
+      if (onProgress && totalSize > 0) {
+        onProgress(downloadedSize, totalSize);
       }
-    };
-    const request = httpModule.request(
-      requestOptions,
-      (res) => {
-        if (followRedirects && res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          if (maxRedirects <= 0) {
-            reject(
-              new Error(
-                `Too many redirects (exceeded maximum: ${maxRedirects})`
-              )
-            );
-            return;
-          }
-          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:") {
-            reject(
-              new Error(
-                `Redirect from HTTPS to HTTP is not allowed: ${redirectUrl}`
-              )
-            );
-            return;
-          }
-          resolve(
-            httpDownloadAttempt(redirectUrl, destPath, {
-              ca,
-              followRedirects,
-              headers,
-              maxRedirects: maxRedirects - 1,
-              onProgress,
-              timeout
-            })
-          );
-          return;
-        }
-        if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
-          closeStream();
-          reject(
-            new Error(
-              `Download failed: HTTP ${res.statusCode} ${res.statusMessage}`
-            )
-          );
-          return;
-        }
-        const totalSize = Number.parseInt(
-          res.headers["content-length"] || "0",
-          10
-        );
-        let downloadedSize = 0;
-        fileStream = createWriteStream(destPath);
-        fileStream.on("error", (error) => {
-          closeStream();
-          const err = new Error(`Failed to write file: ${error.message}`, {
-            cause: error
-          });
-          reject(err);
-        });
-        res.on("data", (chunk) => {
-          downloadedSize += chunk.length;
-          if (onProgress && totalSize > 0) {
-            onProgress(downloadedSize, totalSize);
-          }
-        });
-        res.on("end", () => {
-          fileStream?.close(() => {
-            streamClosed = true;
-            resolve({
-              path: destPath,
-              size: downloadedSize
-            });
-          });
-        });
-        res.on("error", (error) => {
-          closeStream();
-          reject(error);
+    });
+    res.on("end", () => {
+      fileStream.close(() => {
+        resolve({
+          headers: response.headers,
+          ok: true,
+          path: destPath,
+          size: downloadedSize,
+          status: response.status,
+          statusText: response.statusText
         });
-        res.pipe(fileStream);
-      }
-    );
-    request.on("error", (error) => {
-      closeStream();
-      const code = error.code;
-      let message = `HTTP download 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 }));
+      });
     });
-    request.on("timeout", () => {
-      request.destroy();
-      closeStream();
-      reject(new Error(`Download timed out after ${timeout}ms`));
+    res.on("error", (error) => {
+      fileStream.close();
+      reject(error);
     });
-    request.end();
+    res.pipe(fileStream);
   });
 }
 function enrichErrorMessage(url, method, error) {
@@ -355,6 +281,7 @@ async function httpRequestAttempt(url, options) {
     maxRedirects = 5,
     maxResponseSize,
     method = "GET",
+    stream = false,
     timeout = 3e4
   } = { __proto__: null, ...options };
   const startTime = Date.now();
@@ -452,11 +379,37 @@ async function httpRequestAttempt(url, options) {
               maxRedirects: maxRedirects - 1,
               maxResponseSize,
               method,
+              stream,
               timeout
             })
           );
           return;
         }
+        if (stream) {
+          const status = res.statusCode || 0;
+          const statusText = res.statusMessage || "";
+          const ok = status >= 200 && status < 300;
+          emitResponse({
+            headers: res.headers,
+            status,
+            statusText
+          });
+          const emptyBody = Buffer.alloc(0);
+          resolveOnce({
+            arrayBuffer: () => emptyBody.buffer,
+            body: emptyBody,
+            headers: res.headers,
+            json: () => {
+              throw new Error("Cannot parse JSON from a streaming response");
+            },
+            ok,
+            rawResponse: res,
+            status,
+            statusText,
+            text: () => ""
+          });
+          return;
+        }
         const chunks = [];
         let totalBytes = 0;
         res.on("data", (chunk) => {
@@ -533,12 +486,12 @@ async function httpRequestAttempt(url, options) {
     });
     if (body) {
       if (typeof body === "object" && typeof body.pipe === "function") {
-        const stream = body;
-        stream.on("error", (err) => {
+        const stream2 = body;
+        stream2.on("error", (err) => {
           request.destroy();
           rejectOnce(err);
         });
-        stream.pipe(request);
+        stream2.pipe(request);
         return;
       }
       request.write(body);
@@ -613,8 +566,8 @@ Computed: ${computedHash}`
       }
       await fs.promises.rename(tempPath, destPath);
       return {
-        path: destPath,
-        size: result.size
+        ...result,
+        path: destPath
       };
     } catch (e) {
       lastError = e;
@@ -676,6 +629,7 @@ async function httpRequest(url, options) {
     onRetry,
     retries = 0,
     retryDelay = 1e3,
+    stream = false,
     throwOnError = false,
     timeout = 3e4
   } = { __proto__: null, ...options };
@@ -696,6 +650,7 @@ async function httpRequest(url, options) {
     maxRedirects,
     maxResponseSize,
     method,
+    stream,
     timeout
   };
   let lastError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "5.14.0",
+  "version": "5.15.0",
   "packageManager": "pnpm@10.33.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
@@ -717,7 +717,7 @@
     "update": "node scripts/update.mjs"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-code": "2.1.89",
+    "@anthropic-ai/claude-code": "2.1.92",
     "@babel/core": "7.28.4",
     "@babel/parser": "7.28.4",
     "@babel/traverse": "7.28.4",
@@ -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.13.0",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.14.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "4.0.3",