@fedify/vocab-runtime 2.5.0-dev.2446 → 2.5.0-dev.2448

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.5.0-dev.2446+2014cb03",
+  "version": "2.5.0-dev.2448+756933d0",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts",

package/dist/internal/portable-dereference.cjs

@@ -497,6 +497,35 @@ var PortableObjectRejectedError = class extends Error {
 		this.name = "PortableObjectRejectedError";
 	}
 };
+/**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+async function acceptCandidate(observer, candidate) {
+	if (observer?.accept == null) return true;
+	let accepted;
+	try {
+		accepted = await observer.accept(candidate);
+	} catch (error) {
+		observer.failed?.({
+			operation: "accept",
+			error
+		});
+		return false;
+	}
+	if (!accepted) observer.failed?.({ operation: "accept" });
+	return accepted;
+}
+/** Wraps an error that has already been reported to the observer. */
+var ObservedFailure = class {
+	error;
+	constructor(error) {
+		this.error = error;
+	}
+};
 var PortableObjectRejection = class {
 	message;
 	values;
@@ -592,6 +621,10 @@ async function dereferencePortableIri(url, options) {
 					requestUrl,
 					error
 				});
+				options.observer?.failed?.({
+					operation: "fetch",
+					error
+				});
 				attempts.push({
 					type: "error",
 					error
@@ -622,11 +655,33 @@ async function dereferencePortableIri(url, options) {
 					throw new PortableObjectRejection("the proof verifier failed: {error}", { error });
 				}
 				if (!result.verified) throw new PortableObjectRejection("it does not satisfy the FEP-ef61 proof policy: {result}", { result });
-				const object = await options.parse(document, {
-					contextLoader,
-					baseUrl: url
-				});
+				let object;
+				try {
+					object = await options.parse(document, {
+						contextLoader,
+						baseUrl: url
+					});
+				} catch (error) {
+					options.observer?.failed?.({
+						operation: "parse",
+						error
+					});
+					throw new ObservedFailure(error);
+				}
 				signal?.throwIfAborted();
+				if (!await acceptCandidate(options.observer, {
+					document,
+					documentUrl: remoteDocument.documentUrl,
+					baseUrl: url,
+					contextLoader,
+					object
+				})) {
+					attempts.push({
+						type: "rejected",
+						source: requestUrl
+					});
+					continue;
+				}
 				if (object != null && typeof object === "object") provenances.set(object, {
 					acceptance: result.unsecured === true ? "unsecured" : "verified",
 					...result.collectionContext === void 0 ? {} : { collectionContext: result.collectionContext },
@@ -642,20 +697,29 @@ async function dereferencePortableIri(url, options) {
 						url: lookupUrl,
 						requestUrl
 					});
+					options.observer?.failed?.({
+						operation: "verify",
+						error: error.values.error
+					});
 					attempts.push({
 						type: "rejected",
 						source: requestUrl
 					});
 					continue;
 				}
+				const cause = error instanceof ObservedFailure ? error.error : error;
+				if (!(error instanceof ObservedFailure)) options.observer?.failed?.({
+					operation: "verify",
+					error
+				});
 				logger.debug("Failed to parse {url} from {requestUrl}: {error}", {
 					url: lookupUrl,
 					requestUrl,
-					error
+					error: cause
 				});
 				attempts.push({
 					type: "error",
-					error
+					error: cause
 				});
 			}
 		}
@@ -701,6 +765,7 @@ async function checkPortableObjectId(document, expectedId, contextLoader) {
 }
 //#endregion
 exports.PortableObjectRejectedError = PortableObjectRejectedError;
+exports.acceptCandidate = acceptCandidate;
 exports.copyPortableProvenance = copyPortableProvenance;
 exports.createSnapshotContextLoader = createSnapshotContextLoader;
 exports.dereferencePortableIri = dereferencePortableIri;

package/dist/internal/portable-dereference.d.cts

@@ -311,6 +311,58 @@ interface DereferencePortableIriOptions<T> {
     baseUrl: URL;
   }) => Promise<T>;
   span?: Span;
+  /**
+  * Observes each candidate document, and may refuse a candidate that was
+  * otherwise acceptable, in which case the next gateway is tried.
+  */
+  observer?: DereferenceObserver<T>;
+}
+/**
+* A candidate document that a lookup or a dereference was about to return.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceCandidate<T> {
+  /** The document as it was retrieved. */
+  readonly document: unknown;
+  /** The URL the document was finally retrieved from. */
+  readonly documentUrl: string;
+  /** The `baseUrl` option the document was parsed with. */
+  readonly baseUrl: URL;
+  /**
+  * The context loader the document was parsed with.  It keeps serving the
+  * same context documents until the {@link DereferenceObserver.accept}
+  * call settles.
+  */
+  readonly contextLoader: DocumentLoader;
+  /** The parsed object. */
+  readonly object: T;
+}
+/**
+* Observes the candidates and the swallowed failures of a lookup or
+* a dereference.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceObserver<T> {
+  /**
+  * Called for each candidate whose parse succeeded, right before it would be
+  * returned.  If it resolves to `false`, the candidate is refused, and the
+  * next one is tried.  An error it throws is treated as a refusal, and is
+  * reported to {@link failed}.
+  */
+  accept?(candidate: DereferenceCandidate<T>): Promise<boolean>;
+  /** Called for each failure that does not propagate by itself. */
+  failed?(failure: DereferenceFailure): void;
+}
+/**
+* A failure observed by {@link DereferenceObserver.failed}.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceFailure {
+  readonly operation: "fetch" | "verify" | "parse" | "origin" | "accept";
+  readonly error?: unknown;
 }
 /**
 * The error thrown by {@link dereferencePortableIri} under
@@ -323,6 +375,14 @@ declare class PortableObjectRejectedError extends Error {
   constructor(message: string);
 }
 /**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+declare function acceptCandidate<T>(observer: DereferenceObserver<T> | undefined, candidate: DereferenceCandidate<T>): Promise<boolean>;
+/**
 * Dereferences an FEP-ef61 portable IRI through its gateways.
 *
 * Gateways are tried one by one until one of them returns a single-node
@@ -346,4 +406,4 @@ declare function dereferencePortableIri<T extends {
   id: URL | null;
 }>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
 //#endregion
-export { DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };
+export { DereferenceCandidate, DereferenceFailure, DereferenceObserver, DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, acceptCandidate, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };

package/dist/internal/portable-dereference.d.ts

@@ -311,6 +311,58 @@ interface DereferencePortableIriOptions<T> {
     baseUrl: URL;
   }) => Promise<T>;
   span?: Span;
+  /**
+  * Observes each candidate document, and may refuse a candidate that was
+  * otherwise acceptable, in which case the next gateway is tried.
+  */
+  observer?: DereferenceObserver<T>;
+}
+/**
+* A candidate document that a lookup or a dereference was about to return.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceCandidate<T> {
+  /** The document as it was retrieved. */
+  readonly document: unknown;
+  /** The URL the document was finally retrieved from. */
+  readonly documentUrl: string;
+  /** The `baseUrl` option the document was parsed with. */
+  readonly baseUrl: URL;
+  /**
+  * The context loader the document was parsed with.  It keeps serving the
+  * same context documents until the {@link DereferenceObserver.accept}
+  * call settles.
+  */
+  readonly contextLoader: DocumentLoader;
+  /** The parsed object. */
+  readonly object: T;
+}
+/**
+* Observes the candidates and the swallowed failures of a lookup or
+* a dereference.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceObserver<T> {
+  /**
+  * Called for each candidate whose parse succeeded, right before it would be
+  * returned.  If it resolves to `false`, the candidate is refused, and the
+  * next one is tried.  An error it throws is treated as a refusal, and is
+  * reported to {@link failed}.
+  */
+  accept?(candidate: DereferenceCandidate<T>): Promise<boolean>;
+  /** Called for each failure that does not propagate by itself. */
+  failed?(failure: DereferenceFailure): void;
+}
+/**
+* A failure observed by {@link DereferenceObserver.failed}.
+*
+* @internal Not part of the public API contract.
+*/
+interface DereferenceFailure {
+  readonly operation: "fetch" | "verify" | "parse" | "origin" | "accept";
+  readonly error?: unknown;
 }
 /**
 * The error thrown by {@link dereferencePortableIri} under
@@ -323,6 +375,14 @@ declare class PortableObjectRejectedError extends Error {
   constructor(message: string);
 }
 /**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+declare function acceptCandidate<T>(observer: DereferenceObserver<T> | undefined, candidate: DereferenceCandidate<T>): Promise<boolean>;
+/**
 * Dereferences an FEP-ef61 portable IRI through its gateways.
 *
 * Gateways are tried one by one until one of them returns a single-node
@@ -346,4 +406,4 @@ declare function dereferencePortableIri<T extends {
   id: URL | null;
 }>(url: URL, options: DereferencePortableIriOptions<T>): Promise<T | null>;
 //#endregion
-export { DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };
+export { DereferenceCandidate, DereferenceFailure, DereferenceObserver, DereferencePortableIriOptions, PortableObjectRejectedError, PortableReferrerLink, PortableResponseClaim, acceptCandidate, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };

package/dist/internal/portable-dereference.js

@@ -496,6 +496,35 @@ var PortableObjectRejectedError = class extends Error {
 		this.name = "PortableObjectRejectedError";
 	}
 };
+/**
+* Asks an observer whether to accept a candidate.  A refusal, including an
+* error thrown by the observer, is reported to the observer as an `accept`
+* failure.
+* @returns `true` if there is no observer, or it accepted the candidate.
+* @internal Not part of the public API contract.
+*/
+async function acceptCandidate(observer, candidate) {
+	if (observer?.accept == null) return true;
+	let accepted;
+	try {
+		accepted = await observer.accept(candidate);
+	} catch (error) {
+		observer.failed?.({
+			operation: "accept",
+			error
+		});
+		return false;
+	}
+	if (!accepted) observer.failed?.({ operation: "accept" });
+	return accepted;
+}
+/** Wraps an error that has already been reported to the observer. */
+var ObservedFailure = class {
+	error;
+	constructor(error) {
+		this.error = error;
+	}
+};
 var PortableObjectRejection = class {
 	message;
 	values;
@@ -591,6 +620,10 @@ async function dereferencePortableIri(url, options) {
 					requestUrl,
 					error
 				});
+				options.observer?.failed?.({
+					operation: "fetch",
+					error
+				});
 				attempts.push({
 					type: "error",
 					error
@@ -621,11 +654,33 @@ async function dereferencePortableIri(url, options) {
 					throw new PortableObjectRejection("the proof verifier failed: {error}", { error });
 				}
 				if (!result.verified) throw new PortableObjectRejection("it does not satisfy the FEP-ef61 proof policy: {result}", { result });
-				const object = await options.parse(document, {
-					contextLoader,
-					baseUrl: url
-				});
+				let object;
+				try {
+					object = await options.parse(document, {
+						contextLoader,
+						baseUrl: url
+					});
+				} catch (error) {
+					options.observer?.failed?.({
+						operation: "parse",
+						error
+					});
+					throw new ObservedFailure(error);
+				}
 				signal?.throwIfAborted();
+				if (!await acceptCandidate(options.observer, {
+					document,
+					documentUrl: remoteDocument.documentUrl,
+					baseUrl: url,
+					contextLoader,
+					object
+				})) {
+					attempts.push({
+						type: "rejected",
+						source: requestUrl
+					});
+					continue;
+				}
 				if (object != null && typeof object === "object") provenances.set(object, {
 					acceptance: result.unsecured === true ? "unsecured" : "verified",
 					...result.collectionContext === void 0 ? {} : { collectionContext: result.collectionContext },
@@ -641,20 +696,29 @@ async function dereferencePortableIri(url, options) {
 						url: lookupUrl,
 						requestUrl
 					});
+					options.observer?.failed?.({
+						operation: "verify",
+						error: error.values.error
+					});
 					attempts.push({
 						type: "rejected",
 						source: requestUrl
 					});
 					continue;
 				}
+				const cause = error instanceof ObservedFailure ? error.error : error;
+				if (!(error instanceof ObservedFailure)) options.observer?.failed?.({
+					operation: "verify",
+					error
+				});
 				logger.debug("Failed to parse {url} from {requestUrl}: {error}", {
 					url: lookupUrl,
 					requestUrl,
-					error
+					error: cause
 				});
 				attempts.push({
 					type: "error",
-					error
+					error: cause
 				});
 			}
 		}
@@ -699,4 +763,4 @@ async function checkPortableObjectId(document, expectedId, contextLoader) {
 	if (actualId !== expectedId) throw new PortableObjectRejection("its @id ({objectId}) does not match the requested portable ID", { objectId: id });
 }
 //#endregion
-export { PortableObjectRejectedError, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };
+export { PortableObjectRejectedError, acceptCandidate, copyPortableProvenance, createSnapshotContextLoader, dereferencePortableIri, getPortableGatewayCandidates, getPortableResponseClaim, getReferrerGateways, isCompatibleEf61Iri, isInPortableChain, isPortableIri, isPortableMode, isUnsecuredPortableObject, isUnverifiedPortableClaim, markUnverifiedPortableClaim, mustDereferencePortableObject, parseCompatibleEf61Reference, recordPortableReferrer, rejectMalformedCompatibleReference, warnUnverifiableEmbeddedObject };

package/dist/mod.cjs

@@ -16,7 +16,7 @@ let _multiformats_base_x = require("@multiformats/base-x");
 _multiformats_base_x = require_rolldown_runtime.__toESM(_multiformats_base_x, 1);
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.5.0-dev.2446+2014cb03";
+var version = "2.5.0-dev.2448+756933d0";
 //#endregion
 //#region src/request.ts
 /**

package/dist/mod.js

@@ -12,7 +12,7 @@ import { PublicKeyInfo } from "pkijs";
 import baseX from "@multiformats/base-x";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.5.0-dev.2446+2014cb03";
+var version = "2.5.0-dev.2448+756933d0";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/{body-Ddx6WgR5.cjs → body-DP2u2wUX.cjs}

@@ -1,4 +1,4 @@
-const require_request = require("./request-glvxfx2U.cjs");
+const require_request = require("./request-B77_oZnk.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/{body-CQi2bVi5.mjs → body-oV99TVdA.mjs}

@@ -1,4 +1,4 @@
-import { t as FetchError } from "./request-1pPyYz3e.mjs";
+import { t as FetchError } from "./request-BlLYI4x3.mjs";
 import { getLogger } from "@logtape/logtape";
 //#region src/body.ts
 /** Decoded JSON body limit: 16 MiB.  @internal */

package/dist/tests/body.test.cjs

@@ -1,4 +1,4 @@
-const require_body = require("./body-Ddx6WgR5.cjs");
+const require_body = require("./body-DP2u2wUX.cjs");
 let node_assert_strict = require("node:assert/strict");
 let node_test = require("node:test");
 let node_zlib = require("node:zlib");

package/dist/tests/body.test.mjs

@@ -1,4 +1,4 @@
-import { i as readBoundedText, t as BodyTooLargeError } from "./body-CQi2bVi5.mjs";
+import { i as readBoundedText, t as BodyTooLargeError } from "./body-oV99TVdA.mjs";
 import { deepStrictEqual, ok, rejects } from "node:assert/strict";
 import { test } from "node:test";
 import { gunzipSync, gzipSync } from "node:zlib";

package/dist/tests/decimal.test.cjs

@@ -1,12 +1,12 @@
-require("./request-glvxfx2U.cjs");
+require("./request-B77_oZnk.cjs");
 require("./url-BNakuZ8k.cjs");
-require("./docloader-C3vDXwn1.cjs");
+require("./docloader-CwxZguqN.cjs");
 require("./key-C-AYkdJJ.cjs");
 require("./multibase-B5Mea7Ip.cjs");
 require("./digest-3FeH2Y-Q.cjs");
 require("./langtag-DASCPgl3.cjs");
 require("./langstr-h89Kjekh.cjs");
-require("./portable-media-BJf_gGQz.cjs");
+require("./portable-media-D7ClSjFO.cjs");
 let node_test = require("node:test");
 let node_assert = require("node:assert");
 //#region src/decimal.ts

package/dist/tests/decimal.test.mjs

@@ -1,12 +1,12 @@
-import "./request-1pPyYz3e.mjs";
+import "./request-BlLYI4x3.mjs";
 import "./url-DMxmp7ZG.mjs";
-import "./docloader-CrVannnU.mjs";
+import "./docloader-D3mA7aPJ.mjs";
 import "./key-C2Db_TAJ.mjs";
 import "./multibase-BPnF_L4e.mjs";
 import "./digest-COC7xDiQ.mjs";
 import "./langtag-CD3zHKPN.mjs";
 import "./langstr-Dw8IBDZl.mjs";
-import "./portable-media-Cc58dUeE.mjs";
+import "./portable-media-B-oCeotd.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, throws } from "node:assert";
 //#region src/decimal.ts

package/dist/tests/{docloader-C3vDXwn1.cjs → docloader-CwxZguqN.cjs}

@@ -1,6 +1,6 @@
-const require_request = require("./request-glvxfx2U.cjs");
+const require_request = require("./request-B77_oZnk.cjs");
 const require_url = require("./url-BNakuZ8k.cjs");
-const require_body = require("./body-Ddx6WgR5.cjs");
+const require_body = require("./body-DP2u2wUX.cjs");
 const require_contexts = require("./contexts-C9Lj11SC.cjs");
 const require_link = require("./link-DlKm8bEr.cjs");
 let _logtape_logtape = require("@logtape/logtape");

package/dist/tests/{docloader-CrVannnU.mjs → docloader-D3mA7aPJ.mjs}

@@ -1,6 +1,6 @@
-import { a as logRequest, n as createActivityPubRequest, o as name, s as version, t as FetchError } from "./request-1pPyYz3e.mjs";
+import { a as logRequest, n as createActivityPubRequest, o as name, s as version, t as FetchError } from "./request-BlLYI4x3.mjs";
 import { n as UrlError, x as validatePublicUrl } from "./url-DMxmp7ZG.mjs";
-import { i as readBoundedText, n as MAX_BODY_SIZE, r as readBoundedBytes, t as BodyTooLargeError } from "./body-CQi2bVi5.mjs";
+import { i as readBoundedText, n as MAX_BODY_SIZE, r as readBoundedBytes, t as BodyTooLargeError } from "./body-oV99TVdA.mjs";
 import { t as preloadedContexts } from "./contexts-duRA_dDC.mjs";
 import { t as HttpHeaderLink } from "./link-Cevmc87v.mjs";
 import { getLogger } from "@logtape/logtape";

package/dist/tests/docloader.test.cjs

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-glvxfx2U.cjs");
+const require_request = require("./request-B77_oZnk.cjs");
 const require_url = require("./url-BNakuZ8k.cjs");
 const require_contexts = require("./contexts-C9Lj11SC.cjs");
-const require_docloader = require("./docloader-C3vDXwn1.cjs");
+const require_docloader = require("./docloader-CwxZguqN.cjs");
 const require_jsonld = require("./jsonld-CmDhHNTx.cjs");
 let node_zlib = require("node:zlib");
 let _logtape_logtape = require("@logtape/logtape");

package/dist/tests/docloader.test.mjs

@@ -1,7 +1,7 @@
-import { t as FetchError } from "./request-1pPyYz3e.mjs";
+import { t as FetchError } from "./request-BlLYI4x3.mjs";
 import { n as UrlError } from "./url-DMxmp7ZG.mjs";
 import { n as cid_v1_default, t as preloadedContexts } from "./contexts-duRA_dDC.mjs";
-import { i as withDocumentLoaderTimeout, n as getRemoteDocument, r as resolveDocumentLoaderTimeout, t as getDocumentLoader } from "./docloader-CrVannnU.mjs";
+import { i as withDocumentLoaderTimeout, n as getRemoteDocument, r as resolveDocumentLoaderTimeout, t as getDocumentLoader } from "./docloader-D3mA7aPJ.mjs";
 import { t as jsonld_default } from "./jsonld-DweIJ07b.mjs";
 import { gzipSync } from "node:zlib";
 import { configure, reset } from "@logtape/logtape";

package/dist/tests/{portable-media-Cc58dUeE.mjs → portable-media-B-oCeotd.mjs}

@@ -1,6 +1,6 @@
-import { r as getUserAgent } from "./request-1pPyYz3e.mjs";
+import { r as getUserAgent } from "./request-BlLYI4x3.mjs";
 import { g as parseGatewayUrl, x as validatePublicUrl } from "./url-DMxmp7ZG.mjs";
-import { r as readBoundedBytes } from "./body-CQi2bVi5.mjs";
+import { r as readBoundedBytes } from "./body-oV99TVdA.mjs";
 import { a as verifyDigestMultibase, i as parseHashlink, r as parseDigestMultibase } from "./digest-COC7xDiQ.mjs";
 //#region src/portable-media.ts
 function resolveTimeout(value, fallback) {

package/dist/tests/{portable-media-BJf_gGQz.cjs → portable-media-D7ClSjFO.cjs}

@@ -1,6 +1,6 @@
-const require_request = require("./request-glvxfx2U.cjs");
+const require_request = require("./request-B77_oZnk.cjs");
 const require_url = require("./url-BNakuZ8k.cjs");
-const require_body = require("./body-Ddx6WgR5.cjs");
+const require_body = require("./body-DP2u2wUX.cjs");
 const require_digest = require("./digest-3FeH2Y-Q.cjs");
 //#region src/portable-media.ts
 function resolveTimeout(value, fallback) {

package/dist/tests/portable-media.test.cjs

@@ -1,5 +1,5 @@
 const require_digest = require("./digest-3FeH2Y-Q.cjs");
-const require_portable_media = require("./portable-media-BJf_gGQz.cjs");
+const require_portable_media = require("./portable-media-D7ClSjFO.cjs");
 let node_assert_strict = require("node:assert/strict");
 let node_test = require("node:test");
 let node_http = require("node:http");

package/dist/tests/portable-media.test.mjs

@@ -1,5 +1,5 @@
 import { n as createHashlink, t as computeDigestMultibase } from "./digest-COC7xDiQ.mjs";
-import { t as fetchPortableMedia } from "./portable-media-Cc58dUeE.mjs";
+import { t as fetchPortableMedia } from "./portable-media-B-oCeotd.mjs";
 import { deepStrictEqual, equal, rejects } from "node:assert/strict";
 import { test } from "node:test";
 import { createServer } from "node:http";

package/dist/tests/{request-glvxfx2U.cjs → request-B77_oZnk.cjs}

@@ -4,7 +4,7 @@ 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.2446+2014cb03";
+var version = "2.5.0-dev.2448+756933d0";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/{request-1pPyYz3e.mjs → request-BlLYI4x3.mjs}

@@ -2,7 +2,7 @@ import { n as UrlError } from "./url-DMxmp7ZG.mjs";
 import process from "node:process";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.5.0-dev.2446+2014cb03";
+var version = "2.5.0-dev.2448+756933d0";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/request.test.cjs

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-glvxfx2U.cjs");
+const require_request = require("./request-B77_oZnk.cjs");
 const require_url = require("./url-BNakuZ8k.cjs");
 let node_test = require("node:test");
 let node_process = require("node:process");

package/dist/tests/request.test.mjs

@@ -1,4 +1,4 @@
-import { i as isTransientFetchError, n as createActivityPubRequest, r as getUserAgent, s as version, t as FetchError } from "./request-1pPyYz3e.mjs";
+import { i as isTransientFetchError, n as createActivityPubRequest, r as getUserAgent, s as version, t as FetchError } from "./request-BlLYI4x3.mjs";
 import { n as UrlError } from "./url-DMxmp7ZG.mjs";
 import { test } from "node:test";
 import process from "node:process";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.5.0-dev.2446+2014cb03",
+  "version": "2.5.0-dev.2448+756933d0",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",

package/src/internal/portable-dereference.ts

@@ -705,6 +705,61 @@ export interface DereferencePortableIriOptions<T> {
     options: { contextLoader: DocumentLoader; baseUrl: URL },
   ) => Promise<T>;
   span?: Span;
+  /**
+   * Observes each candidate document, and may refuse a candidate that was
+   * otherwise acceptable, in which case the next gateway is tried.
+   */
+  observer?: DereferenceObserver<T>;
+}
+
+/**
+ * A candidate document that a lookup or a dereference was about to return.
+ *
+ * @internal Not part of the public API contract.
+ */
+export interface DereferenceCandidate<T> {
+  /** The document as it was retrieved. */
+  readonly document: unknown;
+  /** The URL the document was finally retrieved from. */
+  readonly documentUrl: string;
+  /** The `baseUrl` option the document was parsed with. */
+  readonly baseUrl: URL;
+  /**
+   * The context loader the document was parsed with.  It keeps serving the
+   * same context documents until the {@link DereferenceObserver.accept}
+   * call settles.
+   */
+  readonly contextLoader: DocumentLoader;
+  /** The parsed object. */
+  readonly object: T;
+}
+
+/**
+ * Observes the candidates and the swallowed failures of a lookup or
+ * a dereference.
+ *
+ * @internal Not part of the public API contract.
+ */
+export interface DereferenceObserver<T> {
+  /**
+   * Called for each candidate whose parse succeeded, right before it would be
+   * returned.  If it resolves to `false`, the candidate is refused, and the
+   * next one is tried.  An error it throws is treated as a refusal, and is
+   * reported to {@link failed}.
+   */
+  accept?(candidate: DereferenceCandidate<T>): Promise<boolean>;
+  /** Called for each failure that does not propagate by itself. */
+  failed?(failure: DereferenceFailure): void;
+}
+
+/**
+ * A failure observed by {@link DereferenceObserver.failed}.
+ *
+ * @internal Not part of the public API contract.
+ */
+export interface DereferenceFailure {
+  readonly operation: "fetch" | "verify" | "parse" | "origin" | "accept";
+  readonly error?: unknown;
 }
 
 /**
@@ -725,6 +780,34 @@ type Attempt =
   | { readonly type: "rejected"; readonly source: string }
   | { readonly type: "error"; readonly error: unknown };
 
+/**
+ * Asks an observer whether to accept a candidate.  A refusal, including an
+ * error thrown by the observer, is reported to the observer as an `accept`
+ * failure.
+ * @returns `true` if there is no observer, or it accepted the candidate.
+ * @internal Not part of the public API contract.
+ */
+export async function acceptCandidate<T>(
+  observer: DereferenceObserver<T> | undefined,
+  candidate: DereferenceCandidate<T>,
+): Promise<boolean> {
+  if (observer?.accept == null) return true;
+  let accepted: boolean;
+  try {
+    accepted = await observer.accept(candidate);
+  } catch (error) {
+    observer.failed?.({ operation: "accept", error });
+    return false;
+  }
+  if (!accepted) observer.failed?.({ operation: "accept" });
+  return accepted;
+}
+
+/** Wraps an error that has already been reported to the observer. */
+class ObservedFailure {
+  constructor(readonly error: unknown) {}
+}
+
 class PortableObjectRejection {
   constructor(
     readonly message: string,
@@ -852,6 +935,7 @@ export async function dereferencePortableIri<T extends { id: URL | null }>(
           requestUrl,
           error,
         });
+        options.observer?.failed?.({ operation: "fetch", error });
         attempts.push({ type: "error", error });
         continue;
       }
@@ -887,11 +971,29 @@ export async function dereferencePortableIri<T extends { id: URL | null }>(
             { result },
           );
         }
-        const object = await options.parse(document, {
-          contextLoader,
-          baseUrl: url,
-        });
+        let object: T;
+        try {
+          object = await options.parse(document, {
+            contextLoader,
+            baseUrl: url,
+          });
+        } catch (error) {
+          options.observer?.failed?.({ operation: "parse", error });
+          throw new ObservedFailure(error);
+        }
         signal?.throwIfAborted();
+        if (
+          !await acceptCandidate(options.observer, {
+            document,
+            documentUrl: remoteDocument.documentUrl,
+            baseUrl: url,
+            contextLoader,
+            object,
+          })
+        ) {
+          attempts.push({ type: "rejected", source: requestUrl });
+          continue;
+        }
         if (object != null && typeof object === "object") {
           provenances.set(object, {
             acceptance: result.unsecured === true ? "unsecured" : "verified",
@@ -913,15 +1015,23 @@ export async function dereferencePortableIri<T extends { id: URL | null }>(
               "because " + error.message,
             { ...error.values, url: lookupUrl, requestUrl },
           );
+          options.observer?.failed?.({
+            operation: "verify",
+            error: error.values.error,
+          });
           attempts.push({ type: "rejected", source: requestUrl });
           continue;
         }
+        const cause = error instanceof ObservedFailure ? error.error : error;
+        if (!(error instanceof ObservedFailure)) {
+          options.observer?.failed?.({ operation: "verify", error });
+        }
         logger.debug("Failed to parse {url} from {requestUrl}: {error}", {
           url: lookupUrl,
           requestUrl,
-          error,
+          error: cause,
         });
-        attempts.push({ type: "error", error });
+        attempts.push({ type: "error", error: cause });
       }
     }
   } finally {