@fedify/vocab-runtime 2.5.0-dev.2339 → 2.5.0-dev.2358

package/src/request.test.ts

@@ -2,7 +2,13 @@ import { deepStrictEqual } from "node:assert";
 import process from "node:process";
 import { test } from "node:test";
 import metadata from "../deno.json" with { type: "json" };
-import { createActivityPubRequest, getUserAgent } from "./request.ts";
+import {
+  createActivityPubRequest,
+  FetchError,
+  getUserAgent,
+  isTransientFetchError,
+} from "./request.ts";
+import { UrlError } from "./url.ts";
 
 test("getUserAgent()", () => {
   if ("Deno" in globalThis) {
@@ -100,3 +106,139 @@ test("createActivityPubRequest() asks for the ActivityStreams profile", () => {
       'application/ld+json; profile="https://www.w3.org/ns/activitystreams"',
   );
 });
+
+test("isTransientFetchError() classifies document loader errors", () => {
+  const url = "https://example.com/object";
+  const response = (status: number) => new Response(null, { status });
+  deepStrictEqual(
+    isTransientFetchError(new FetchError(url, "HTTP 503", response(503))),
+    true,
+  );
+  deepStrictEqual(
+    isTransientFetchError(new FetchError(url, "HTTP 408", response(408))),
+    true,
+  );
+  deepStrictEqual(
+    isTransientFetchError(new FetchError(url, "HTTP 429", response(429))),
+    true,
+  );
+  deepStrictEqual(
+    isTransientFetchError(new FetchError(url, "HTTP 404", response(404))),
+    false,
+  );
+  deepStrictEqual(
+    isTransientFetchError(new FetchError(url, "HTTP 410", response(410))),
+    false,
+  );
+  deepStrictEqual(
+    isTransientFetchError(new FetchError(url, "Redirect loop detected")),
+    false,
+  );
+  const timeout = new FetchError(url, "Timed out after 1000 ms");
+  timeout.cause = new DOMException("Timed out", "TimeoutError");
+  deepStrictEqual(isTransientFetchError(timeout), true);
+  const tooLarge = new FetchError(url, "Body exceeds the limit");
+  tooLarge.name = "BodyTooLargeError";
+  deepStrictEqual(isTransientFetchError(tooLarge), false);
+  deepStrictEqual(
+    isTransientFetchError(new UrlError("DNS lookup failed", { reason: "dns" })),
+    true,
+  );
+  deepStrictEqual(
+    isTransientFetchError(new UrlError("Disallowed private URL")),
+    false,
+  );
+  deepStrictEqual(
+    isTransientFetchError(
+      new TypeError("fetch failed", { cause: new Error("ECONNRESET") }),
+    ),
+    true,
+  );
+  let invalidUrl: unknown;
+  try {
+    new URL("::");
+  } catch (error) {
+    invalidUrl = error;
+  }
+  deepStrictEqual(isTransientFetchError(invalidUrl), false);
+  deepStrictEqual(
+    isTransientFetchError(
+      new TypeError("Failed to parse URL from ::", {
+        cause: Object.assign(new TypeError("Invalid URL"), {
+          code: "ERR_INVALID_URL",
+        }),
+      }),
+    ),
+    false,
+  );
+  deepStrictEqual(isTransientFetchError(new SyntaxError("Bad JSON")), false);
+  deepStrictEqual(
+    isTransientFetchError(new DOMException("Aborted", "AbortError")),
+    true,
+  );
+  deepStrictEqual(isTransientFetchError(new Error("unknown")), true);
+});
+
+test("isTransientFetchError() recognizes errors from other package copies", () => {
+  const dns = Object.assign(new Error("DNS lookup failed"), {
+    name: "UrlError",
+    reason: "dns",
+  });
+  deepStrictEqual(isTransientFetchError(dns), true);
+  const notFound = Object.assign(new Error("HTTP 404"), {
+    name: "FetchError",
+    url: new URL("https://example.com/"),
+    response: new Response(null, { status: 404 }),
+  });
+  deepStrictEqual(isTransientFetchError(notFound), false);
+});
+
+test("isTransientFetchError() classifies aggregate errors by their members", () => {
+  const notFound = (url: string) =>
+    new FetchError(url, "HTTP 404", new Response(null, { status: 404 }));
+  const unavailable = (url: string) =>
+    new FetchError(url, "HTTP 503", new Response(null, { status: 503 }));
+  deepStrictEqual(
+    isTransientFetchError(
+      new AggregateError([
+        notFound("https://a.example/"),
+        notFound("https://b.example/"),
+      ]),
+    ),
+    false,
+  );
+  deepStrictEqual(
+    isTransientFetchError(
+      new AggregateError([
+        notFound("https://a.example/"),
+        unavailable("https://b.example/"),
+      ]),
+    ),
+    true,
+  );
+  deepStrictEqual(isTransientFetchError(new AggregateError([])), true);
+  const gone = new FetchError(
+    "https://a.example/",
+    "HTTP 410",
+    new Response(null, { status: 410 }),
+  );
+  deepStrictEqual(
+    isTransientFetchError(new AggregateError([gone, gone])),
+    false,
+  );
+  deepStrictEqual(
+    isTransientFetchError(
+      new AggregateError([
+        new FetchError("https://a.example/", "a", undefined),
+        new FetchError("https://b.example/", "b", undefined),
+      ].map((e) => Object.assign(e, { cause: gone }))),
+    ),
+    false,
+  );
+});
+
+test("isTransientFetchError() tolerates cyclic causes", () => {
+  const error = new FetchError("https://example.com/", "cyclic");
+  error.cause = error;
+  deepStrictEqual(isTransientFetchError(error), true);
+});

package/src/request.ts

@@ -1,6 +1,7 @@
 import type { Logger } from "@logtape/logtape";
 import process from "node:process";
 import metadata from "../deno.json" with { type: "json" };
+import { UrlError } from "./url.ts";
 
 /**
  * Error thrown when fetching a JSON-LD document failed.
@@ -31,6 +32,118 @@ export class FetchError extends Error {
   }
 }
 
+const MAX_CAUSE_DEPTH = 8;
+
+/**
+ * Guesses whether an error thrown by a document loader is transient,
+ * i.e., whether fetching the same document again later could succeed.
+ *
+ * This is a heuristic classification, not a guarantee.  Callers that retry
+ * on transient errors should still bound the number of retries.  The rules
+ * are:
+ *
+ *  -  A {@link UrlError} is transient only if its
+ *     {@link UrlError.reason | reason} is `"dns"`; URLs disallowed by SSRF
+ *     protection are permanent.
+ *  -  A {@link FetchError} with a {@link FetchError.response | response} is
+ *     transient if the status is 5xx, 408 (Request Timeout), or 429 (Too Many
+ *     Requests); other statuses such as 404 are permanent.
+ *  -  A {@link FetchError} without a response is classified by its `cause`,
+ *     which is how timeouts are reported.  Without a cause, it is permanent
+ *     (e.g., redirect loops, too many redirections, or bodies that exceed the
+ *     size limit).
+ *  -  A `TimeoutError` or `AbortError` is transient.
+ *  -  A `TypeError` from parsing an invalid URL is permanent; any other
+ *     `TypeError` is transient, since `fetch()` reports network failures
+ *     that way.
+ *  -  A `SyntaxError` (a malformed JSON body) is permanent.
+ *  -  An `AggregateError`, e.g., from trying several gateways, is transient
+ *     if any of its errors is.
+ *  -  Any other error is treated as transient.
+ *
+ * @param error The error thrown by a document loader.
+ * @returns `true` if the error is likely transient, `false` if retrying is
+ *          unlikely to help.
+ * @since 2.5.0
+ */
+export function isTransientFetchError(error: unknown): boolean {
+  return classifyFetchError(error, new Set(), 0);
+}
+
+function classifyFetchError(
+  error: unknown,
+  path: Set<unknown>,
+  depth: number,
+): boolean {
+  // Only an error on the current path is a cycle; the same error can appear
+  // in several branches, e.g., twice in an AggregateError:
+  if (depth > MAX_CAUSE_DEPTH || path.has(error)) return true;
+  path.add(error);
+  try {
+    return classifyErrorShape(error, path, depth);
+  } finally {
+    path.delete(error);
+  }
+}
+
+function classifyErrorShape(
+  error: unknown,
+  path: Set<unknown>,
+  depth: number,
+): boolean {
+  if (!(error instanceof Error) && !isNamedError(error)) return true;
+  const name = (error as { readonly name: string }).name;
+  if (error instanceof UrlError || name === "UrlError") {
+    return (error as { readonly reason?: unknown }).reason === "dns";
+  }
+  if (name === "BodyTooLargeError") return false;
+  if (error instanceof FetchError || name === "FetchError") {
+    const response = (error as { readonly response?: unknown }).response;
+    if (isResponseLike(response)) {
+      const status = response.status;
+      return status >= 500 || status === 408 || status === 429;
+    }
+    const cause = (error as { readonly cause?: unknown }).cause;
+    if (cause == null) return false;
+    return classifyFetchError(cause, path, depth + 1);
+  }
+  if (error instanceof AggregateError || name === "AggregateError") {
+    const errors = (error as { readonly errors?: unknown }).errors;
+    if (!Array.isArray(errors) || errors.length < 1) return true;
+    return errors.some((e) => classifyFetchError(e, path, depth + 1));
+  }
+  if (name === "TimeoutError" || name === "AbortError") return true;
+  if (error instanceof TypeError || name === "TypeError") {
+    // Node.js's fetch() wraps the URL parsing error as its cause:
+    const cause = (error as { readonly cause?: unknown }).cause;
+    return !isInvalidUrlError(error) && !isInvalidUrlError(cause);
+  }
+  if (error instanceof SyntaxError || name === "SyntaxError") return false;
+  return true;
+}
+
+function isNamedError(error: unknown): boolean {
+  return typeof error === "object" && error != null &&
+    typeof (error as { readonly name?: unknown }).name === "string";
+}
+
+function isResponseLike(
+  value: unknown,
+): value is { readonly status: number } {
+  return typeof value === "object" && value != null &&
+    typeof (value as { readonly status?: unknown }).status === "number";
+}
+
+function isInvalidUrlError(error: unknown): boolean {
+  if (typeof error !== "object" || error == null) return false;
+  const { code, message } = error as {
+    readonly code?: unknown;
+    readonly message?: unknown;
+  };
+  return code === "ERR_INVALID_URL" ||
+    typeof message === "string" && message.startsWith("Invalid URL");
+}
+
 /**
  * The `Accept` header value for fetching ActivityPub objects.  ActivityPub
  * and FEP-ef61 gateways require the ActivityStreams profile on the JSON-LD

package/dist/tests/request-BM1AsOPj.mjs

@@ -1,82 +0,0 @@
-import process from "node:process";
-//#region deno.json
-var name = "@fedify/vocab-runtime";
-var version = "2.5.0-dev.2339+5e786861";
-//#endregion
-//#region src/request.ts
-/**
-* Error thrown when fetching a JSON-LD document failed.
-*/
-var FetchError = class extends Error {
-	/**
-	* The URL that failed to fetch.
-	*/
-	url;
-	/**
-	* The HTTP response that failed, if available.
-	*/
-	response;
-	/**
-	* Constructs a new `FetchError`.
-	*
-	* @param url The URL that failed to fetch.
-	* @param message Error message.
-	* @param response The failed HTTP response, if available.
-	*/
-	constructor(url, message, response) {
-		super(message == null ? url.toString() : `${url}: ${message}`);
-		this.name = "FetchError";
-		this.url = typeof url === "string" ? new URL(url) : url;
-		this.response = response;
-	}
-};
-/**
-* The `Accept` header value for fetching ActivityPub objects.  ActivityPub
-* and FEP-ef61 gateways require the ActivityStreams profile on the JSON-LD
-* media type.
-*/
-const ACTIVITYPUB_ACCEPT = "application/activity+json, application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"";
-/**
-* Creates a request for the given URL.
-* @param url The URL to create the request for.
-* @param options The options for the request.
-* @returns The created request.
-* @internal
-*/
-function createActivityPubRequest(url, options = {}) {
-	return new Request(url, {
-		headers: {
-			Accept: ACTIVITYPUB_ACCEPT,
-			"User-Agent": typeof options.userAgent === "string" ? options.userAgent : getUserAgent(options.userAgent)
-		},
-		redirect: "manual"
-	});
-}
-/**
-* Gets the user agent string for the given application and URL.
-* @param options The options for making the user agent string.
-* @returns The user agent string.
-* @since 1.3.0
-*/
-function getUserAgent({ software, url } = {}) {
-	const fedify = `Fedify/${version}`;
-	const runtime = globalThis.Deno?.version?.deno != null ? `Deno/${Deno.version.deno}` : globalThis.process?.versions?.bun != null ? `Bun/${process.versions.bun}` : "navigator" in globalThis && navigator.userAgent === "Cloudflare-Workers" ? navigator.userAgent : globalThis.process?.versions?.node != null ? `Node.js/${process.versions.node}` : null;
-	const userAgent = software == null ? [fedify] : [software, fedify];
-	if (runtime != null) userAgent.push(runtime);
-	if (url != null) userAgent.push(`+${url.toString()}`);
-	return `${userAgent.shift()} (${userAgent.join("; ")})`;
-}
-/**
-* Logs the request.
-* @param request The request to log.
-* @internal
-*/
-function logRequest(logger, request) {
-	logger.debug("Fetching document: {method} {url} {headers}", {
-		method: request.method,
-		url: request.url,
-		headers: Object.fromEntries(request.headers.entries())
-	});
-}
-//#endregion
-export { name as a, logRequest as i, createActivityPubRequest as n, version as o, getUserAgent as r, FetchError as t };

package/dist/tests/request-lSaiCxqI.cjs

@@ -1,119 +0,0 @@
-const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-let node_process = require("node:process");
-node_process = require_rolldown_runtime.__toESM(node_process, 1);
-//#region deno.json
-var name = "@fedify/vocab-runtime";
-var version = "2.5.0-dev.2339+5e786861";
-//#endregion
-//#region src/request.ts
-/**
-* Error thrown when fetching a JSON-LD document failed.
-*/
-var FetchError = class extends Error {
-	/**
-	* The URL that failed to fetch.
-	*/
-	url;
-	/**
-	* The HTTP response that failed, if available.
-	*/
-	response;
-	/**
-	* Constructs a new `FetchError`.
-	*
-	* @param url The URL that failed to fetch.
-	* @param message Error message.
-	* @param response The failed HTTP response, if available.
-	*/
-	constructor(url, message, response) {
-		super(message == null ? url.toString() : `${url}: ${message}`);
-		this.name = "FetchError";
-		this.url = typeof url === "string" ? new URL(url) : url;
-		this.response = response;
-	}
-};
-/**
-* The `Accept` header value for fetching ActivityPub objects.  ActivityPub
-* and FEP-ef61 gateways require the ActivityStreams profile on the JSON-LD
-* media type.
-*/
-const ACTIVITYPUB_ACCEPT = "application/activity+json, application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"";
-/**
-* Creates a request for the given URL.
-* @param url The URL to create the request for.
-* @param options The options for the request.
-* @returns The created request.
-* @internal
-*/
-function createActivityPubRequest(url, options = {}) {
-	return new Request(url, {
-		headers: {
-			Accept: ACTIVITYPUB_ACCEPT,
-			"User-Agent": typeof options.userAgent === "string" ? options.userAgent : getUserAgent(options.userAgent)
-		},
-		redirect: "manual"
-	});
-}
-/**
-* Gets the user agent string for the given application and URL.
-* @param options The options for making the user agent string.
-* @returns The user agent string.
-* @since 1.3.0
-*/
-function getUserAgent({ software, url } = {}) {
-	const fedify = `Fedify/${version}`;
-	const runtime = globalThis.Deno?.version?.deno != null ? `Deno/${Deno.version.deno}` : globalThis.process?.versions?.bun != null ? `Bun/${node_process.default.versions.bun}` : "navigator" in globalThis && navigator.userAgent === "Cloudflare-Workers" ? navigator.userAgent : globalThis.process?.versions?.node != null ? `Node.js/${node_process.default.versions.node}` : null;
-	const userAgent = software == null ? [fedify] : [software, fedify];
-	if (runtime != null) userAgent.push(runtime);
-	if (url != null) userAgent.push(`+${url.toString()}`);
-	return `${userAgent.shift()} (${userAgent.join("; ")})`;
-}
-/**
-* Logs the request.
-* @param request The request to log.
-* @internal
-*/
-function logRequest(logger, request) {
-	logger.debug("Fetching document: {method} {url} {headers}", {
-		method: request.method,
-		url: request.url,
-		headers: Object.fromEntries(request.headers.entries())
-	});
-}
-//#endregion
-Object.defineProperty(exports, "FetchError", {
-	enumerable: true,
-	get: function() {
-		return FetchError;
-	}
-});
-Object.defineProperty(exports, "createActivityPubRequest", {
-	enumerable: true,
-	get: function() {
-		return createActivityPubRequest;
-	}
-});
-Object.defineProperty(exports, "getUserAgent", {
-	enumerable: true,
-	get: function() {
-		return getUserAgent;
-	}
-});
-Object.defineProperty(exports, "logRequest", {
-	enumerable: true,
-	get: function() {
-		return logRequest;
-	}
-});
-Object.defineProperty(exports, "name", {
-	enumerable: true,
-	get: function() {
-		return name;
-	}
-});
-Object.defineProperty(exports, "version", {
-	enumerable: true,
-	get: function() {
-		return version;
-	}
-});

package/dist/tests/{portable-dereference-qTLMqe2_.cjs → portable-dereference-DaTBBvCj.cjs}

@@ -1,5 +1,5 @@
-const require_contexts = require("./contexts-C9Lj11SC.cjs");
 const require_url = require("./url-BNakuZ8k.cjs");
+const require_contexts = require("./contexts-C9Lj11SC.cjs");
 require("./jsonld-CmDhHNTx.cjs");
 const require_jsonld_cache = require("./jsonld-cache-BEXiiM-V.cjs");
 let _logtape_logtape = require("@logtape/logtape");

package/dist/tests/{portable-dereference-DmTYDy2p.mjs → portable-dereference-sGRs_qdT.mjs}

@@ -1,5 +1,5 @@
-import { t as preloadedContexts } from "./contexts-duRA_dDC.mjs";
 import { h as parseGatewayOrigin, o as formatIri, s as fromCompatibleEf61Id, t as GATEWAY_HINT_PARAMETER, u as haveSameFe34Origin } from "./url-DMxmp7ZG.mjs";
+import { t as preloadedContexts } from "./contexts-duRA_dDC.mjs";
 import "./jsonld-DweIJ07b.mjs";
 import { c as unwrapReleasedDocumentLoader, s as registerDocumentLoaderWrapper } from "./jsonld-cache-DFnWsLuZ.mjs";
 import { getLogger } from "@logtape/logtape";