rust-fetch 1.1.0 → 2.1.0

package/node.js

@@ -0,0 +1,265 @@
+// Node.js entry point (selected through the "node" export condition).
+//
+// Browsers load the .wasm file with fetch(), which Node.js can't do for
+// file: URLs. Here the module is compiled synchronously on import instead, so
+// the API is ready to use immediately; calling `init()` is optional and
+// returns the already-initialized module.
+//
+// It also registers a transport built on node:http/node:https. Node's global
+// fetch() implements browser semantics (WHATWG streams) on top of the same
+// sockets and is considerably slower; this transport only moves bytes.
+// Retries, timeouts, validation and decoding stay in the Rust core.
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import zlib from 'node:zlib';
+import { initSync } from './rust_fetch.js';
+
+initSync({ module: readFileSync(new URL('./rust_fetch_bg.wasm', import.meta.url)) });
+
+const MAX_REDIRECTS = 20;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const ACCEPT_ENCODING = typeof zlib.zstdDecompressSync === 'function' ? 'gzip, deflate, br, zstd' : 'gzip, deflate, br';
+
+const textDecoder = new TextDecoder();
+// Response body types, numbered like `BodyType` in src/wasm/mod.rs
+const AUTO = 0;
+const JSON_BODY = 1;
+const TEXT = 2;
+const BINARY = 3;
+
+// Same rules as is_json_content_type / is_text_content_type in src/types.rs
+function mimeEssence(contentType) {
+  return (contentType ?? '').split(';')[0].trim().toLowerCase();
+}
+function isJsonType(essence) {
+  return essence === 'application/json' || essence.endsWith('+json');
+}
+function isTextType(essence) {
+  return (
+    essence.startsWith('text/') ||
+    essence.endsWith('+xml') ||
+    essence === 'application/xml' ||
+    essence === 'application/javascript' ||
+    essence === 'application/x-www-form-urlencoded'
+  );
+}
+
+function coded(error, code) {
+  error.code = code;
+  return error;
+}
+
+/**
+ * Decode a body like `decode_body` in src/wasm/transport.rs, in JS so the
+ * text never crosses into wasm. TextDecoder replaces invalid UTF-8 and strips
+ * a BOM; the length is checked first, since a BOM-only body is not empty.
+ */
+function decodeBody(bytes, contentType, bodyType) {
+  if (bytes.length === 0) return bodyType === TEXT ? '' : bodyType === BINARY ? new Uint8Array(0) : null;
+  const essence = mimeEssence(contentType);
+  const json = bodyType === JSON_BODY || (bodyType === AUTO && isJsonType(essence));
+  const text = json || bodyType === TEXT || (bodyType === AUTO && isTextType(essence));
+  if (!text) return bytes;
+  const decoded = textDecoder.decode(bytes);
+  if (!json) return decoded;
+  try {
+    return JSON.parse(decoded);
+  } catch (error) {
+    if (bodyType === AUTO) return decoded; // mislabelled responses fall back to text
+    throw coded(error, 'RUST_FETCH_PARSE');
+  }
+}
+
+/** Undo one Content-Encoding; unknown encodings are passed through, like fetch() */
+function decode(body, encoding) {
+  switch (encoding) {
+    case 'gzip':
+    case 'x-gzip':
+      return zlib.gunzipSync(body, { finishFlush: zlib.constants.Z_SYNC_FLUSH });
+    case 'deflate':
+      // Servers send both zlib-wrapped and raw deflate under this name
+      return body[0] === 0x78 ? zlib.inflateSync(body) : zlib.inflateRawSync(body);
+    case 'br':
+      return zlib.brotliDecompressSync(body);
+    case 'zstd':
+      return typeof zlib.zstdDecompressSync === 'function' ? zlib.zstdDecompressSync(body) : body;
+    default:
+      return body;
+  }
+}
+
+function decompress(body, contentEncoding) {
+  if (!contentEncoding || body.length === 0) return body;
+  // Encodings are listed in the order they were applied
+  const encodings = contentEncoding.toLowerCase().split(',').map((e) => e.trim()).filter((e) => e && e !== 'identity');
+  for (let i = encodings.length - 1; i >= 0; i--) body = decode(body, encodings[i]);
+  return body;
+}
+
+/** Response headers as one string per name; repeated headers joined with ", " */
+function flattenHeaders(raw) {
+  const headers = {};
+  for (const name in raw) {
+    const value = raw[name];
+    headers[name] = Array.isArray(value) ? value.join(', ') : value;
+  }
+  return headers;
+}
+
+/**
+ * A plain Uint8Array that owns its memory. Small Node Buffers share a pooled
+ * ArrayBuffer, so those are copied; larger ones are wrapped without copying.
+ */
+function ownedBytes(bytes) {
+  return bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+    ? new Uint8Array(bytes.buffer)
+    : new Uint8Array(bytes);
+}
+
+function withoutHeaders(headers, names) {
+  const copy = { ...headers };
+  for (const name of names) delete copy[name];
+  return copy;
+}
+
+function send(state, method, url, headers, body, redirects, resolve, reject) {
+  if (state.cancelled) return;
+  const transport = url.protocol === 'https:' ? https : http;
+  const request = transport.request(url, { method, headers }, (response) => {
+    const status = response.statusCode;
+    const location = response.headers.location;
+
+    if (REDIRECT_STATUSES.has(status) && location) {
+      response.resume();
+      if (redirects >= MAX_REDIRECTS) return reject(new TypeError(`Too many redirects (more than ${MAX_REDIRECTS})`));
+      let next;
+      try {
+        next = new URL(location, url);
+      } catch {
+        return reject(new TypeError(`Invalid redirect location: ${location}`));
+      }
+      if (next.protocol !== 'http:' && next.protocol !== 'https:') {
+        return reject(new TypeError(`Unsupported redirect to ${next.protocol}`));
+      }
+      // Same rules as fetch(): 303, and 301/302 after POST, become a bodiless GET
+      let nextMethod = method;
+      let nextBody = body;
+      let nextHeaders = headers;
+      if ((status === 303 && method !== 'GET' && method !== 'HEAD') || ((status === 301 || status === 302) && method === 'POST')) {
+        nextMethod = 'GET';
+        nextBody = undefined;
+        nextHeaders = withoutHeaders(nextHeaders, ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location']);
+      }
+      // Never forward credentials to another origin
+      if (next.origin !== url.origin) {
+        nextHeaders = withoutHeaders(nextHeaders, ['authorization', 'cookie', 'proxy-authorization']);
+      }
+      return send(state, nextMethod, next, nextHeaders, nextBody, redirects + 1, resolve, reject);
+    }
+
+    // With a Content-Length, fill one preallocated buffer (a single copy);
+    // otherwise collect chunks and join them at the end.
+    const expected = Number(response.headers['content-length']);
+    const preallocated = !response.headers['content-encoding'] && Number.isSafeInteger(expected) && expected > 0 && expected <= 512 * 1024 * 1024;
+    const buffer = preallocated ? new Uint8Array(expected) : undefined;
+    let received = 0;
+    const chunks = [];
+    response.on('data', (chunk) => {
+      if (buffer && received + chunk.length <= expected) buffer.set(chunk, received);
+      else chunks.push(chunk);
+      received += chunk.length;
+    });
+    response.on('error', reject);
+    // A socket closed mid-body may emit 'close' without 'end' (a settled promise ignores this)
+    response.on('close', () => {
+      if (!response.complete) reject(new TypeError('The connection closed before the response body was complete'));
+    });
+    response.on('end', () => {
+      if (!response.complete) return reject(new TypeError('The connection closed before the response body was complete'));
+      try {
+        let body;
+        if (buffer && received === expected && chunks.length === 0) {
+          body = buffer;
+        } else {
+          const raw = buffer ? Buffer.concat([buffer.subarray(0, Math.min(received, expected)), ...chunks]) : Buffer.concat(chunks);
+          body = ownedBytes(method === 'HEAD' ? raw : decompress(raw, response.headers['content-encoding']));
+        }
+        resolve({ status, url: url.href, headers: flattenHeaders(response.headers), body });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+  request.on('error', reject);
+  request.end(body);
+  state.request = request;
+}
+
+/**
+ * One attempt, called by the Rust core with
+ * `{ method, url, headers, body?, timeout?, bodyType }`. Resolves to the
+ * finished `{ status, statusText, ok, url, headers, body }` (the core fills
+ * in statusText). Rejects with code RUST_FETCH_TIMEOUT or RUST_FETCH_PARSE,
+ * or any other error for network failures.
+ *
+ * The promise has a `cancel()` method, which the core calls only when it
+ * abandons an attempt (e.g. AbortSignal); this is much cheaper than wiring an
+ * AbortSignal into every request.
+ */
+function nodeTransport(request) {
+  const state = { cancelled: false, request: undefined, bodyType: request.bodyType ?? AUTO };
+  let timer;
+  const promise = new Promise((resolve, reject) => {
+    if (request.timeout > 0) {
+      // Covers the whole attempt: connecting, redirects and reading the body
+      timer = setTimeout(() => {
+        cancel();
+        reject(coded(new Error(`Request timeout after ${request.timeout}ms`), 'RUST_FETCH_TIMEOUT'));
+      }, request.timeout);
+    }
+    let url;
+    try {
+      url = new URL(request.url);
+    } catch (error) {
+      clearTimeout(timer);
+      return reject(error);
+    }
+    const headers = { ...request.headers };
+    headers['accept'] ??= '*/*';
+    headers['accept-encoding'] ??= ACCEPT_ENCODING;
+    headers['user-agent'] ??= 'rust-fetch';
+    if (request.body) headers['content-length'] ??= String(request.body.length);
+    const settle = (fn) => (value) => {
+      clearTimeout(timer);
+      fn(value);
+    };
+    send(state, request.method, url, headers, request.body, 0, settle(resolve), settle(reject));
+  });
+  const cancel = () => {
+    state.cancelled = true;
+    state.request?.destroy();
+  };
+  // Decode only after the socket's event handlers have returned: decoding
+  // inside them keeps the raw chunks and stream state alive during
+  // JSON.parse, which costs several times more garbage collection.
+  const finished = promise.then((response) => finishResponse(response, state.bodyType));
+  finished.cancel = () => {
+    clearTimeout(timer);
+    cancel();
+  };
+  return finished;
+}
+
+/** The response object handed to the Rust core (which fills in statusText) */
+function finishResponse({ status, url, headers, body }, bodyType) {
+  const ok = status >= 200 && status < 300;
+  // Error statuses carry their body as text (for HttpError.body)
+  const decoded = ok ? decodeBody(body, headers['content-type'], bodyType) : decodeBody(body, '', TEXT);
+  return { status, statusText: '', ok, url, headers, body: decoded };
+}
+
+globalThis[Symbol.for('rust-fetch.transport')] = nodeTransport;
+
+export { default } from './rust_fetch.js';
+export * from './rust_fetch.js';

package/package.json

@@ -4,8 +4,8 @@
   "collaborators": [
     "Asem Qaffaf <asem@qaffaf.com>"
   ],
-  "description": "A world-class WebAssembly HTTP client library with excellent error handling and clean API",
-  "version": "1.1.0",
+  "description": "A reliable HTTP client for JavaScript and TypeScript, written in Rust and compiled to WebAssembly: timeouts, retries, typed errors and interceptors, faster than fetch() in Node.js",
+  "version": "2.1.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
@@ -13,8 +13,12 @@
   },
   "files": [
     "rust_fetch_bg.wasm",
+    "rust_fetch_bg.wasm.d.ts",
     "rust_fetch.js",
-    "rust_fetch.d.ts"
+    "rust_fetch.d.ts",
+    "node.js",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "main": "rust_fetch.js",
   "types": "rust_fetch.d.ts",
@@ -27,5 +31,25 @@
     "client",
     "fetch",
     "webassembly"
-  ]
-}
+  ],
+  "exports": {
+    ".": {
+      "types": "./rust_fetch.d.ts",
+      "node": "./node.js",
+      "default": "./rust_fetch.js"
+    },
+    "./rust_fetch.js": {
+      "types": "./rust_fetch.d.ts",
+      "default": "./rust_fetch.js"
+    },
+    "./rust_fetch_bg.wasm": "./rust_fetch_bg.wasm",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://github.com/asemqaffaf/rust-fetch#readme",
+  "bugs": {
+    "url": "https://github.com/asemqaffaf/rust-fetch/issues"
+  }
+}