@socketsecurity/lib 6.0.2 → 6.0.4

package/dist/http-request/download.js

@@ -1,201 +1,200 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var download_exports = {};
-__export(download_exports, {
-  httpDownload: () => httpDownload,
-  httpDownloadAttempt: () => httpDownloadAttempt
-});
-module.exports = __toCommonJS(download_exports);
-var import_promises = require("node:timers/promises");
-var import_safe = require("../fs/safe");
-var import_buffer = require("../primordials/buffer");
-var import_error = require("../primordials/error");
-var import_math = require("../primordials/math");
-var import_number = require("../primordials/number");
-var import_promise = require("../primordials/promise");
-var import_internal = require("./_internal");
-var import_request = require("./request");
-var import_response_types = require("./response-types");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_node_crypto = require('../node/crypto.js');
+const require_primordials_buffer = require('../primordials/buffer.js');
+const require_primordials_error = require('../primordials/error.js');
+const require_primordials_math = require('../primordials/math.js');
+const require_primordials_number = require('../primordials/number.js');
+const require_node_fs = require('../node/fs.js');
+const require_fs_safe = require('../fs/safe.js');
+const require_primordials_promise = require('../primordials/promise.js');
+const require_http_request_request_attempt = require('./request-attempt.js');
+const require_http_request_response_types = require('./response-types.js');
+let node_timers_promises = require("node:timers/promises");
+
+//#region src/http-request/download.ts
+/**
+* @file Streaming file downloads with retries, progress callbacks, and SHA-256
+*   verification. `httpDownload` is the public entry — it writes to a
+*   randomly-named sibling temp file first, then atomic-renames into place on
+*   success so a failed run never leaves a half-written file at `destPath`.
+*   `httpDownloadAttempt` is one streaming pass; the retry / hash-check loop
+*   sits in `httpDownload`. `httpDownloadAttempt` is exported (not private) per
+*   `export-top-level-functions` — it lives here next to the only caller, and
+*   it uses `httpRequestAttempt(... { stream: true })` from `request.ts` to
+*   obtain the unconsumed `rawResponse` it pipes to disk.
+*/
+/**
+* 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.
+*
+* The download is streamed directly to disk, making it memory-efficient even
+* for large files. Progress callbacks allow for real-time download status
+* updates.
+*
+* Automatically follows HTTP redirects (3xx status codes) by default, making it
+* suitable for downloading from services like GitHub releases that redirect to
+* CDN URLs.
+*
+* @example
+*   ```ts
+*   // Simple download
+*   const result = await httpDownload(
+*   'https://example.com/file.zip',
+*   '/tmp/file.zip',
+*   )
+*   console.log(`Downloaded ${result.size} bytes to ${result.path}`)
+*
+*   // Download from GitHub releases (handles 302 redirect automatically)
+*   await httpDownload(
+*   'https://github.com/org/repo/releases/download/v1.0.0/binary.tar.gz',
+*   '/tmp/binary.tar.gz',
+*   )
+*
+*   // With progress tracking
+*   await httpDownload('https://example.com/large-file.zip', '/tmp/file.zip', {
+*   onProgress: (downloaded, total) => {
+*   const percent = ((downloaded / total) * 100).toFixed(1)
+*   console.log(`Progress: ${percent}% (${downloaded}/${total} bytes)`)
+*   },
+*   })
+*
+*   // With retries and custom timeout
+*   await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+*   retries: 3,
+*   retryDelay: 2000,
+*   timeout: 300000, // 5 minutes
+*   headers: { Authorization: 'Bearer token123' },
+*   })
+*   ```
+*
+* @param url - The URL to download from (must start with http:// or https://)
+* @param destPath - Absolute path where the file should be saved.
+* @param options - Download configuration options.
+*
+* @returns Promise resolving to download result with path and size
+*
+* @throws {Error} When all retries are exhausted, download fails, or file
+*   cannot be written.
+*/
 async function httpDownload(url, destPath, options) {
-  const {
-    ca,
-    followRedirects = true,
-    headers = {},
-    logger,
-    maxRedirects = 5,
-    onProgress,
-    progressInterval = 10,
-    retries = 0,
-    retryDelay = 1e3,
-    sha256,
-    timeout = 12e4
-  } = { __proto__: null, ...options };
-  let progressCallback;
-  if (onProgress) {
-    progressCallback = onProgress;
-  } else if (logger) {
-    let lastPercent = 0;
-    progressCallback = (downloaded, total) => {
-      const percent = total === 0 ? 0 : (0, import_math.MathFloor)(downloaded / total * 100);
-      if (percent >= lastPercent + progressInterval) {
-        logger.log(
-          `  Progress: ${percent}% (${(downloaded / 1024 / 1024).toFixed(1)} MB / ${(total / 1024 / 1024).toFixed(1)} MB)`
-        );
-        lastPercent = percent;
-      }
-    };
-  }
-  const crypto = (0, import_internal.getCrypto)();
-  const fs = (0, import_internal.getFs)();
-  const tempSuffix = crypto.randomBytes(6).toString("hex");
-  const tempPath = `${destPath}.${tempSuffix}.download`;
-  if (fs.existsSync(tempPath)) {
-    await (0, import_safe.safeDelete)(tempPath);
-  }
-  let lastError;
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      const result = await httpDownloadAttempt(url, tempPath, {
-        ca,
-        followRedirects,
-        headers,
-        maxRedirects,
-        onProgress: progressCallback,
-        timeout
-      });
-      if (sha256) {
-        const fileContent = await fs.promises.readFile(tempPath);
-        const computedHash = crypto.createHash("sha256").update(fileContent).digest("hex");
-        const expectedHash = sha256.toLowerCase();
-        if (computedHash.length !== expectedHash.length || !crypto.timingSafeEqual(
-          (0, import_buffer.BufferFrom)(computedHash),
-          Buffer.from(expectedHash)
-        )) {
-          await (0, import_safe.safeDelete)(tempPath);
-          throw new import_error.ErrorCtor(
-            `Checksum verification failed for ${url}
-Expected: ${expectedHash}
-Computed: ${computedHash}`
-          );
-        }
-      }
-      await fs.promises.rename(tempPath, destPath);
-      return {
-        ...result,
-        path: destPath
-      };
-    } catch (e) {
-      lastError = e;
-      if (fs.existsSync(tempPath)) {
-        await (0, import_safe.safeDelete)(tempPath);
-      }
-      if (attempt === retries) {
-        break;
-      }
-      const delayMs = retryDelay * 2 ** attempt;
-      await (0, import_promises.setTimeout)(delayMs);
-    }
-  }
-  throw lastError || new import_error.ErrorCtor("Download failed after retries");
+	const { ca, followRedirects = true, headers = {}, logger, maxRedirects = 5, onProgress, progressInterval = 10, retries = 0, retryDelay = 1e3, sha256, timeout = 12e4 } = {
+		__proto__: null,
+		...options
+	};
+	/* c8 ignore start */
+	let progressCallback;
+	if (onProgress) progressCallback = onProgress;
+	else if (logger) {
+		let lastPercent = 0;
+		progressCallback = (downloaded, total) => {
+			const percent = total === 0 ? 0 : require_primordials_math.MathFloor(downloaded / total * 100);
+			if (percent >= lastPercent + progressInterval) {
+				logger.log(`  Progress: ${percent}% (${(downloaded / 1024 / 1024).toFixed(1)} MB / ${(total / 1024 / 1024).toFixed(1)} MB)`);
+				lastPercent = percent;
+			}
+		};
+	}
+	/* c8 ignore stop */
+	const crypto = /* @__PURE__ */ require_node_crypto.getNodeCrypto();
+	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	const tempPath = `${destPath}.${crypto.randomBytes(6).toString("hex")}.download`;
+	if (fs.existsSync(tempPath)) await require_fs_safe.safeDelete(tempPath);
+	let lastError;
+	for (let attempt = 0; attempt <= retries; attempt++) try {
+		const result = await httpDownloadAttempt(url, tempPath, {
+			ca,
+			followRedirects,
+			headers,
+			maxRedirects,
+			onProgress: progressCallback,
+			timeout
+		});
+		if (sha256) {
+			const fileContent = await fs.promises.readFile(tempPath);
+			const computedHash = crypto.createHash("sha256").update(fileContent).digest("hex");
+			const expectedHash = sha256.toLowerCase();
+			if (computedHash.length !== expectedHash.length || !crypto.timingSafeEqual(require_primordials_buffer.BufferFrom(computedHash), Buffer.from(expectedHash))) {
+				await require_fs_safe.safeDelete(tempPath);
+				throw new require_primordials_error.ErrorCtor(`Checksum verification failed for ${url}\nExpected: ${expectedHash}\nComputed: ${computedHash}`);
+			}
+		}
+		await fs.promises.rename(tempPath, destPath);
+		return {
+			...result,
+			path: destPath
+		};
+	} catch (e) {
+		lastError = e;
+		if (fs.existsSync(tempPath)) await require_fs_safe.safeDelete(tempPath);
+		if (attempt === retries) break;
+		await (0, node_timers_promises.setTimeout)(retryDelay * 2 ** attempt);
+	}
+	throw lastError || new require_primordials_error.ErrorCtor("Download failed after retries");
 }
+/**
+* Single download attempt using httpRequestAttempt with stream: true.
+*/
 async function httpDownloadAttempt(url, destPath, options) {
-  const {
-    ca,
-    followRedirects = true,
-    headers = {},
-    maxRedirects = 5,
-    onProgress,
-    timeout = 12e4
-  } = { __proto__: null, ...options };
-  const response = await (0, import_request.httpRequestAttempt)(url, {
-    ca,
-    followRedirects,
-    headers,
-    maxRedirects,
-    method: "GET",
-    stream: true,
-    timeout
-  });
-  if (!response.ok) {
-    throw new import_response_types.HttpResponseError(
-      response,
-      `Download failed: HTTP ${response.status} ${response.statusText}`
-    );
-  }
-  const res = response.rawResponse;
-  if (!res) {
-    throw new import_error.ErrorCtor("Stream response missing rawResponse");
-  }
-  const { createWriteStream } = (0, import_internal.getFs)();
-  const totalSize = (0, import_number.NumberParseInt)(
-    response.headers["content-length"] || "0",
-    10
-  );
-  return await new import_promise.PromiseCtor((resolve, reject) => {
-    let downloadedSize = 0;
-    const fileStream = createWriteStream(destPath);
-    const cleanupPartial = () => {
-      ;
-      (async () => {
-        try {
-          await (0, import_safe.safeDelete)(destPath);
-        } catch {
-        }
-      })();
-    };
-    fileStream.on("error", (error) => {
-      fileStream.destroy();
-      cleanupPartial();
-      reject(
-        new import_error.ErrorCtor(`Failed to write file: ${error.message}`, {
-          cause: error
-        })
-      );
-    });
-    res.on("data", (chunk) => {
-      downloadedSize += chunk.length;
-      if (onProgress && totalSize > 0) {
-        onProgress(downloadedSize, totalSize);
-      }
-    });
-    fileStream.on("finish", () => {
-      resolve({
-        headers: response.headers,
-        ok: true,
-        path: destPath,
-        size: downloadedSize,
-        status: response.status,
-        statusText: response.statusText
-      });
-    });
-    res.on("error", (error) => {
-      fileStream.destroy();
-      cleanupPartial();
-      reject(error);
-    });
-    res.pipe(fileStream);
-  });
+	const { ca, followRedirects = true, headers = {}, maxRedirects = 5, onProgress, timeout = 12e4 } = {
+		__proto__: null,
+		...options
+	};
+	const response = await require_http_request_request_attempt.httpRequestAttempt(url, {
+		ca,
+		followRedirects,
+		headers,
+		maxRedirects,
+		method: "GET",
+		stream: true,
+		timeout
+	});
+	if (!response.ok) throw new require_http_request_response_types.HttpResponseError(response, `Download failed: HTTP ${response.status} ${response.statusText}`);
+	const res = response.rawResponse;
+	/* c8 ignore next 3 */
+	if (!res) throw new require_primordials_error.ErrorCtor("Stream response missing rawResponse");
+	const { createWriteStream } = /* @__PURE__ */ require_node_fs.getNodeFs();
+	const totalSize = require_primordials_number.NumberParseInt(response.headers["content-length"] || "0", 10);
+	return await new require_primordials_promise.PromiseCtor((resolve, reject) => {
+		let downloadedSize = 0;
+		const fileStream = createWriteStream(destPath);
+		const cleanupPartial = () => {
+			(async () => {
+				try {
+					await require_fs_safe.safeDelete(destPath);
+				} catch {}
+			})();
+		};
+		fileStream.on("error", (error) => {
+			fileStream.destroy();
+			cleanupPartial();
+			reject(new require_primordials_error.ErrorCtor(`Failed to write file: ${error.message}`, { cause: error }));
+		});
+		res.on("data", (chunk) => {
+			downloadedSize += chunk.length;
+			if (onProgress && totalSize > 0) onProgress(downloadedSize, totalSize);
+		});
+		fileStream.on("finish", () => {
+			resolve({
+				headers: response.headers,
+				ok: true,
+				path: destPath,
+				size: downloadedSize,
+				status: response.status,
+				statusText: response.statusText
+			});
+		});
+		res.on("error", (error) => {
+			fileStream.destroy();
+			cleanupPartial();
+			reject(error);
+		});
+		res.pipe(fileStream);
+	});
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  httpDownload,
-  httpDownloadAttempt
-});
+
+//#endregion
+exports.httpDownload = httpDownload;
+exports.httpDownloadAttempt = httpDownloadAttempt;

package/dist/http-request/errors.js

@@ -1,50 +1,42 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var errors_exports = {};
-__export(errors_exports, {
-  enrichErrorMessage: () => enrichErrorMessage
-});
-module.exports = __toCommonJS(errors_exports);
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/http-request/errors.ts
+/**
+* @file Error-message enrichment for HTTP/HTTPS requests. `enrichErrorMessage`
+*   translates Node.js network error codes (`ECONNREFUSED`, `ENOTFOUND`,
+*   `ETIMEDOUT`, etc.) into user-facing guidance prefixed with the failing
+*   method + URL. The wording is generic — no product-specific branding — so
+*   the request leaves can use it for any caller. `request.ts` invokes this on
+*   the `request` `'error'` event before rejecting, which is what surfaces the
+*   actionable messages to consumers.
+*/
+/**
+* Build an enriched error message based on the error code. Generic guidance (no
+* product-specific branding).
+*
+* @example
+*   ;```typescript
+*   try {
+*     await fetch('https://api.example.com')
+*   } catch (e) {
+*     console.error(enrichErrorMessage('https://api.example.com', 'GET', e))
+*   }
+*   ```
+*/
 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;
+	const code = error.code;
+	let message = `${method} request failed: ${url}`;
+	if (code === "ECONNREFUSED") message += "\n→ Connection refused. Server is unreachable.\n→ Check: Network connectivity and firewall settings.";
+	else if (code === "ENOTFOUND") message += "\n→ DNS lookup failed. Cannot resolve hostname.\n→ Check: Internet connection and DNS settings.";
+	else if (code === "ETIMEDOUT") message += "\n→ Connection timed out. Network or server issue.\n→ Try: Check network connectivity and retry.";
+	else if (code === "ECONNRESET") message += "\n→ Connection reset by server. Possible network interruption.\n→ Try: Retry the request.";
+	else if (code === "EPIPE") message += "\n→ Broken pipe. Server closed connection unexpectedly.\n→ Check: Authentication credentials and permissions.";
+	else if (code === "CERT_HAS_EXPIRED" || code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") message += "\n→ SSL/TLS certificate error.\n→ Check: System time and date are correct.\n→ Try: Update CA certificates on your system.";
+	else if (code) message += `\n→ Error code: ${code}`;
+	return message;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  enrichErrorMessage
-});
+
+//#endregion
+exports.enrichErrorMessage = enrichErrorMessage;