@revenexx/integrations-node-sdk 1.14.0 → 1.15.0

package/dist/fetch.d.ts

@@ -65,6 +65,28 @@ export interface SafeFetchOptions extends RequestInit {
     /** Bind the request to the origin of the credential it carries. */
     credential?: SafeFetchCredential;
 }
+/**
+ * Whether the request behind a failed {@link safeFetch} call may have reached
+ * the host — `false` only when the call is known to have put nothing on the wire
+ * on any hop of any attempt, and `true` for every other error, an unknown one
+ * included. A node that writes reads it to decide whether a create may be
+ * repeated: when this is `false` nothing was sent, so nothing can have been
+ * created.
+ *
+ * It reads `meta.sent === false`, which `safeFetch` puts on what it throws in
+ * that case: a refused address — before the lookup or at connect time — a lookup
+ * that ran out of time, a header or URL that cannot be sent, a credential bound
+ * to another origin, and a connection that was refused, could not be resolved or
+ * reached, or timed out while connecting. The last group arrives as the runtime's
+ * own `TypeError('fetch failed')`, unwrapped as before, with the marker added. A
+ * cancellation is the caller's own reason and is never marked.
+ */
+export declare function mayHaveBeenSent(err: unknown): boolean;
+/**
+ * Make a request through the SSRF guard, under a time budget and an optional
+ * retry budget. A failure that left nothing on the wire says so with
+ * `meta.sent = false` — read it through {@link mayHaveBeenSent}.
+ */
 export declare function safeFetch(url: string | URL, options?: SafeFetchOptions): Promise<Response>;
 /**
  * Read a response body into an ArrayBuffer while enforcing a hard byte cap.

package/dist/index.cjs

@@ -83,6 +83,7 @@ __export(index_exports, {
   isOperator: () => isOperator,
   isVpnErrorCode: () => isVpnErrorCode,
   maxBytesConfigField: () => maxBytesConfigField,
+  mayHaveBeenSent: () => mayHaveBeenSent,
   nodeManifestProblems: () => nodeManifestProblems,
   normalizeCredentialType: () => normalizeCredentialType,
   normalizeLocalized: () => normalizeLocalized,
@@ -377,6 +378,9 @@ function assertBranchNamed(node, result, config) {
   }
 }
 
+// src/fetch.ts
+var import_undici2 = require("undici");
+
 // src/ssrf.ts
 var import_node_diagnostics_channel = require("diagnostics_channel");
 var import_node_dns = __toESM(require("dns"), 1);
@@ -868,7 +872,7 @@ function attemptFailure(err, ctxSignal, deadline) {
   return err;
 }
 function answerUnderDeadline(res, ctxSignal, deadline) {
-  if (!res.body) return res;
+  if (!res.body) return rebuilt(res, null) ?? asRuntimeResponse(res);
   let reader;
   const body = new ReadableStream(
     {
@@ -894,13 +898,27 @@ function answerUnderDeadline(res, ctxSignal, deadline) {
     // a buffer filling while nobody reads.
     { highWaterMark: 0 }
   );
-  let answer;
+  return rebuilt(res, body) ?? asRuntimeResponse(res);
+}
+function rebuilt(res, body) {
   try {
-    answer = new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+    return withUrl(new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers }), res.url);
   } catch {
-    return res;
+    return void 0;
   }
-  return withUrl(answer, res.url);
+}
+function asRuntimeResponse(res) {
+  return withUrl(withStatusLine(new Response(res.body, { headers: res.headers }), res), res.url);
+}
+function withStatusLine(answer, from) {
+  const clone = answer.clone.bind(answer);
+  Object.defineProperties(answer, {
+    status: { value: from.status },
+    statusText: { value: from.statusText },
+    ok: { value: from.ok },
+    clone: { value: () => withStatusLine(clone(), from), configurable: true }
+  });
+  return answer;
 }
 function withUrl(answer, url) {
   const clone = answer.clone.bind(answer);
@@ -908,12 +926,46 @@ function withUrl(answer, url) {
   Object.defineProperty(answer, "clone", { value: () => withUrl(clone(), url) });
   return answer;
 }
-async function timedFetch(url, fetchOptions, ctxSignal, deadline) {
+var runtimeFetch = globalThis.fetch;
+function transport() {
+  const current = globalThis.fetch;
+  return current === runtimeFetch ? import_undici2.fetch : current;
+}
+var NEVER_CONNECTED = /* @__PURE__ */ new Set(["ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
+var REFUSED_WHILE_CONNECTING = /* @__PURE__ */ new Set(["ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH"]);
+function connectFailed(e) {
+  if (typeof e?.code !== "string") return false;
+  return NEVER_CONNECTED.has(e.code) || REFUSED_WHILE_CONNECTING.has(e.code) && e.syscall === "connect";
+}
+function neverConnected(err) {
+  const cause = err?.cause;
+  if (!cause) return false;
+  if (Array.isArray(cause.errors) && cause.errors.length > 0) return cause.errors.every(connectFailed);
+  return connectFailed(cause);
+}
+function markUnsent(err) {
+  if (typeof err !== "object" || err === null) return;
+  const meta = err.meta;
+  const sent = { ...typeof meta === "object" && meta !== null ? meta : {}, sent: false };
+  try {
+    Object.defineProperty(err, "meta", { value: sent, writable: true, configurable: true, enumerable: true });
+  } catch {
+  }
+}
+function mayHaveBeenSent(err) {
+  const meta = err?.meta;
+  return meta?.sent !== false;
+}
+async function timedFetch(url, fetchOptions, ctxSignal, deadline, wire) {
   try {
-    return await fetch(url, { ...fetchOptions, signal: deadline.signal, dispatcher: guardedDispatcher() });
+    const send = transport();
+    const res = await send(url, { ...fetchOptions, signal: deadline.signal, dispatcher: guardedDispatcher() });
+    wire.maybeSent = true;
+    return res;
   } catch (err) {
     const blocked = connectionRefusal(err);
     if (blocked) throw blocked;
+    if (!neverConnected(err)) wire.maybeSent = true;
     throw attemptFailure(err, ctxSignal, deadline);
   }
 }
@@ -944,10 +996,10 @@ function refuseUserinfo(url, status = 0) {
     );
   }
 }
-async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding) {
+async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, wire, binding) {
   const deadline = attemptDeadline(ctxSignal, effectiveMs);
   try {
-    const res = await followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, binding);
+    const res = await followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, wire, binding);
     deadline.clear();
     return answerUnderDeadline(res, ctxSignal, deadline);
   } catch (err) {
@@ -955,7 +1007,7 @@ async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding)
     throw err;
   }
 }
-async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, binding) {
+async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, wire, binding) {
   let currentUrl = url;
   let currentInit = { ...fetchOptions, redirect: "manual" };
   await guardUrl(currentUrl, ctxSignal, deadline, effectiveMs);
@@ -965,7 +1017,7 @@ async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, b
     );
     let res;
     try {
-      res = await timedFetch(currentUrl, currentInit, ctxSignal, deadline);
+      res = await timedFetch(currentUrl, currentInit, ctxSignal, deadline, wire);
     } finally {
       release();
     }
@@ -1020,6 +1072,15 @@ async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, b
   }
 }
 async function safeFetch(url, options = {}) {
+  const wire = { maybeSent: false };
+  try {
+    return await sendWithin(url, options, wire);
+  } catch (err) {
+    if (!wire.maybeSent && err !== options.signal?.reason) markUnsent(err);
+    throw err;
+  }
+}
+async function sendWithin(url, options, wire) {
   const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: ctxSignal, retry, credential, ...fetchOptions } = options;
   const effectiveMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
   const rawAttempts = retry?.attempts ?? DEFAULT_RETRY_ATTEMPTS;
@@ -1044,7 +1105,7 @@ async function safeFetch(url, options = {}) {
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     if (ctxSignal?.aborted) throw ctxSignal.reason;
     try {
-      return await guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding);
+      return await guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, wire, binding);
     } catch (err) {
       if (ctxSignal?.aborted) throw ctxSignal.reason;
       if (err instanceof NodeError && (err.code === "BLOCKED_ADDRESS" || err.code === "TOO_MANY_REDIRECTS" || err.code === "CREDENTIAL_ORIGIN" || err.code === "INVALID_URL")) {
@@ -1660,6 +1721,7 @@ function base64Url(buf) {
   isOperator,
   isVpnErrorCode,
   maxBytesConfigField,
+  mayHaveBeenSent,
   nodeManifestProblems,
   normalizeCredentialType,
   normalizeLocalized,

package/dist/index.js

@@ -217,6 +217,9 @@ function errorPort(opts = {}) {
   };
 }
 
+// src/fetch.ts
+import { fetch as undiciFetch } from "undici";
+
 // src/ssrf.ts
 import { subscribe } from "diagnostics_channel";
 import dns from "dns";
@@ -708,7 +711,7 @@ function attemptFailure(err, ctxSignal, deadline) {
   return err;
 }
 function answerUnderDeadline(res, ctxSignal, deadline) {
-  if (!res.body) return res;
+  if (!res.body) return rebuilt(res, null) ?? asRuntimeResponse(res);
   let reader;
   const body = new ReadableStream(
     {
@@ -734,13 +737,27 @@ function answerUnderDeadline(res, ctxSignal, deadline) {
     // a buffer filling while nobody reads.
     { highWaterMark: 0 }
   );
-  let answer;
+  return rebuilt(res, body) ?? asRuntimeResponse(res);
+}
+function rebuilt(res, body) {
   try {
-    answer = new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+    return withUrl(new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers }), res.url);
   } catch {
-    return res;
+    return void 0;
   }
-  return withUrl(answer, res.url);
+}
+function asRuntimeResponse(res) {
+  return withUrl(withStatusLine(new Response(res.body, { headers: res.headers }), res), res.url);
+}
+function withStatusLine(answer, from) {
+  const clone = answer.clone.bind(answer);
+  Object.defineProperties(answer, {
+    status: { value: from.status },
+    statusText: { value: from.statusText },
+    ok: { value: from.ok },
+    clone: { value: () => withStatusLine(clone(), from), configurable: true }
+  });
+  return answer;
 }
 function withUrl(answer, url) {
   const clone = answer.clone.bind(answer);
@@ -748,12 +765,46 @@ function withUrl(answer, url) {
   Object.defineProperty(answer, "clone", { value: () => withUrl(clone(), url) });
   return answer;
 }
-async function timedFetch(url, fetchOptions, ctxSignal, deadline) {
+var runtimeFetch = globalThis.fetch;
+function transport() {
+  const current = globalThis.fetch;
+  return current === runtimeFetch ? undiciFetch : current;
+}
+var NEVER_CONNECTED = /* @__PURE__ */ new Set(["ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
+var REFUSED_WHILE_CONNECTING = /* @__PURE__ */ new Set(["ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH"]);
+function connectFailed(e) {
+  if (typeof e?.code !== "string") return false;
+  return NEVER_CONNECTED.has(e.code) || REFUSED_WHILE_CONNECTING.has(e.code) && e.syscall === "connect";
+}
+function neverConnected(err) {
+  const cause = err?.cause;
+  if (!cause) return false;
+  if (Array.isArray(cause.errors) && cause.errors.length > 0) return cause.errors.every(connectFailed);
+  return connectFailed(cause);
+}
+function markUnsent(err) {
+  if (typeof err !== "object" || err === null) return;
+  const meta = err.meta;
+  const sent = { ...typeof meta === "object" && meta !== null ? meta : {}, sent: false };
+  try {
+    Object.defineProperty(err, "meta", { value: sent, writable: true, configurable: true, enumerable: true });
+  } catch {
+  }
+}
+function mayHaveBeenSent(err) {
+  const meta = err?.meta;
+  return meta?.sent !== false;
+}
+async function timedFetch(url, fetchOptions, ctxSignal, deadline, wire) {
   try {
-    return await fetch(url, { ...fetchOptions, signal: deadline.signal, dispatcher: guardedDispatcher() });
+    const send = transport();
+    const res = await send(url, { ...fetchOptions, signal: deadline.signal, dispatcher: guardedDispatcher() });
+    wire.maybeSent = true;
+    return res;
   } catch (err) {
     const blocked = connectionRefusal(err);
     if (blocked) throw blocked;
+    if (!neverConnected(err)) wire.maybeSent = true;
     throw attemptFailure(err, ctxSignal, deadline);
   }
 }
@@ -784,10 +835,10 @@ function refuseUserinfo(url, status = 0) {
     );
   }
 }
-async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding) {
+async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, wire, binding) {
   const deadline = attemptDeadline(ctxSignal, effectiveMs);
   try {
-    const res = await followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, binding);
+    const res = await followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, wire, binding);
     deadline.clear();
     return answerUnderDeadline(res, ctxSignal, deadline);
   } catch (err) {
@@ -795,7 +846,7 @@ async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding)
     throw err;
   }
 }
-async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, binding) {
+async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, wire, binding) {
   let currentUrl = url;
   let currentInit = { ...fetchOptions, redirect: "manual" };
   await guardUrl(currentUrl, ctxSignal, deadline, effectiveMs);
@@ -805,7 +856,7 @@ async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, b
     );
     let res;
     try {
-      res = await timedFetch(currentUrl, currentInit, ctxSignal, deadline);
+      res = await timedFetch(currentUrl, currentInit, ctxSignal, deadline, wire);
     } finally {
       release();
     }
@@ -860,6 +911,15 @@ async function followHops(url, fetchOptions, ctxSignal, deadline, effectiveMs, b
   }
 }
 async function safeFetch(url, options = {}) {
+  const wire = { maybeSent: false };
+  try {
+    return await sendWithin(url, options, wire);
+  } catch (err) {
+    if (!wire.maybeSent && err !== options.signal?.reason) markUnsent(err);
+    throw err;
+  }
+}
+async function sendWithin(url, options, wire) {
   const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: ctxSignal, retry, credential, ...fetchOptions } = options;
   const effectiveMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
   const rawAttempts = retry?.attempts ?? DEFAULT_RETRY_ATTEMPTS;
@@ -884,7 +944,7 @@ async function safeFetch(url, options = {}) {
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     if (ctxSignal?.aborted) throw ctxSignal.reason;
     try {
-      return await guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, binding);
+      return await guardedFetch(url, fetchOptions, ctxSignal, effectiveMs, wire, binding);
     } catch (err) {
       if (ctxSignal?.aborted) throw ctxSignal.reason;
       if (err instanceof NodeError && (err.code === "BLOCKED_ADDRESS" || err.code === "TOO_MANY_REDIRECTS" || err.code === "CREDENTIAL_ORIGIN" || err.code === "INVALID_URL")) {
@@ -1417,6 +1477,7 @@ export {
   isOperator,
   isVpnErrorCode,
   maxBytesConfigField,
+  mayHaveBeenSent,
   nodeManifestProblems,
   normalizeCredentialType,
   normalizeLocalized,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/integrations-node-sdk",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "TypeScript interfaces and utilities for Revenexx integration nodes",
   "license": "MIT",
   "author": "revenexx GmbH",