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

package/dist/mod.d.ts

@@ -1,7 +1,9 @@
 /// <reference lib="esnext.temporal" />
-import { _ as isTransientFetchError, a as DocumentLoaderOptions, c as getDocumentLoader, d as withDocumentLoaderTimeout, f as CreateRequestOptions, g as getUserAgent, h as createActivityPubRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as GetUserAgentOptions, n as DocumentLoader, o as GetDocumentLoaderOptions, p as FetchError, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as resolveDocumentLoaderTimeout, v as logRequest } from "./docloader-BBnBpbsG.js";
-import { i as PortableObjectVerifierOptions, n as PortableObjectVerification, r as PortableObjectVerifier, t as PortableObjectReferrer } from "./portable-BDydjp5H.js";
+import { _ as parseJsonLdId, a as expandIPv6Address, b as withGatewayHints, c as getFe34Origin, d as haveSameIriOrigin, f as isGatewayUrl, g as parseIri, h as parseGatewayUrl, i as canonicalizePortableUri, l as getGatewayHints, m as isValidPublicIPv6Address, n as UrlError, o as formatIri, p as isValidPublicIPv4Address, r as arePortableUrisEqual, s as fromCompatibleEf61Id, u as haveSameFe34Origin, v as toCompatibleEf61Id, x as withoutGatewayHints, y as validatePublicUrl } from "./url-4EE56sNP.js";
+import { _ as isTransientFetchError, a as DocumentLoaderOptions, c as getDocumentLoader, d as withDocumentLoaderTimeout, f as CreateRequestOptions, g as getUserAgent, h as createActivityPubRequest, i as DocumentLoaderFactoryOptions, l as getRemoteDocument, m as GetUserAgentOptions, n as DocumentLoader, o as GetDocumentLoaderOptions, p as FetchError, r as DocumentLoaderFactory, s as RemoteDocument, t as AuthenticatedDocumentLoaderFactory, u as resolveDocumentLoaderTimeout, v as logRequest } from "./docloader-DD6binpN.js";
+import { i as PortableObjectVerifierOptions, n as PortableObjectVerification, r as PortableObjectVerifier, t as PortableObjectReferrer } from "./portable-1VSnSJFj.js";
 import { TracerProvider } from "@opentelemetry/api";
+
 //#region src/contexts.d.ts
 declare const preloadedContexts: Record<string, unknown>;
 //#endregion
@@ -468,338 +470,4 @@ interface PropertyPreprocessorContext {
 */
 type PropertyPreprocessor<T = unknown> = (value: Json, context: PropertyPreprocessorContext) => T | undefined | Error | Promise<T | undefined | Error>;
 //#endregion
-//#region src/url.d.ts
-declare class UrlError extends Error {
-  /**
-  * The failure category. Defaults to `"disallowed"`.
-  * `"dns"` includes lookup errors and results with no usable IP addresses.
-  * @since 2.0.29
-  */
-  readonly reason: "dns" | "disallowed";
-  constructor(message: string, options?: {
-    cause?: unknown;
-    reason?: "dns" | "disallowed";
-  });
-}
-/**
-* Parses a JSON-LD `@id` value as an IRI, including FEP-ef61 portable
-* ActivityPub IRIs.  See {@link parseIri} for how IRIs are parsed.
-* @param id The `@id` value.
-* @param base The base IRI to resolve a relative `@id` against.
-* @returns The parsed IRI, or `undefined` if `id` is missing or a blank node
-*          identifier.
-* @throws {TypeError} If `id` is not a valid IRI.
-* @since 2.4.0
-*/
-declare function parseJsonLdId(id: string | undefined, base?: string | URL): URL | undefined;
-/**
-* Parses an IRI as a URL, including FEP-ef61 portable ActivityPub IRIs.
-* Portable URI and FEP-ef61 compatible identifier strings whose path contains
-* a `.` or `..` segment, including percent-encoded spellings, throw a
-* `TypeError`: JavaScript `URL` would otherwise identify a different object.
-* This also applies to compatible identifier strings used as relative bases.
-* A `URL` argument may already have lost such segments before this function
-* receives it.
-*
-* Portable IRIs, e.g., `ap://did:key:z6Mk.../actor`, cannot be represented by
-* JavaScript `URL` as they are, so the returned `URL` keeps the DID authority
-* percent-encoded, e.g., `ap+ef61://did%3Akey%3Az6Mk.../actor`.  Use
-* {@link formatIri} to get the canonical string back.
-* @param iri The IRI to parse.
-* @param base The base IRI to resolve a relative IRI against.
-* @returns The parsed IRI.
-* @throws {TypeError} If the IRI is malformed.
-* @since 2.4.0
-*/
-declare function parseIri(iri: string | URL, base?: string | URL): URL;
-/**
-* Formats a URL as an IRI, including FEP-ef61 portable ActivityPub IRIs.
-* Portable URI and FEP-ef61 compatible identifier strings with dot segments
-* throw a `TypeError` because their paths cannot be represented by JavaScript
-* `URL` without normalization.
-*
-* Portable IRIs are formatted with the `ap+ef61:` scheme and a decoded DID
-* authority, even if they were parsed from `ap:` IRIs.  FEP-ef61 currently
-* recommends the `ap:` scheme, so a future major version of Fedify may change
-* the scheme this function produces.  Do not compare its results as strings to
-* tell whether two portable IRIs identify the same object; use
-* `arePortableUrisEqual()` instead.
-* @param iri The IRI to format.
-* @returns The formatted IRI.  A string that cannot be parsed as a URL at all
-*          is returned unchanged.
-* @throws {TypeError} If the IRI is a malformed portable IRI or FEP-ef61
-*                     compatible identifier, e.g., one with dot segments.
-* @since 2.4.0
-*/
-declare function formatIri(iri: string | URL): string;
-/**
-* Canonicalizes a FEP-ef61 portable ActivityPub URI for comparison.
-*
-* This accepts both `ap:` and `ap+ef61:` URI strings with decoded or
-* percent-encoded DID authorities.  The returned value uses the `ap+ef61:`
-* scheme, a decoded DID authority, and no query component.  Pass the raw URI
-* string, not a `URL` object, because JavaScript `URL` normalizes opaque path
-* segments before Fedify can compare them.
-*
-* The `ap+ef61:` scheme of the result is a choice of Fedify's, whereas
-* FEP-ef61 currently canonicalizes portable URIs with the `ap:` scheme.
-* A future major version of Fedify may change the scheme of the result, so
-* do not persist the result as the only copy of an identifier; keep the
-* original URI, and canonicalize it again when comparing.
-*
-* @param input The raw portable ActivityPub URI string to canonicalize.
-* @returns The canonical portable ActivityPub URI string.
-* @throws {TypeError} If the input is not a valid portable ActivityPub IRI.
-* @since 2.4.0
-*/
-declare function canonicalizePortableUri(input: string): string;
-/**
-* Checks whether two FEP-ef61 portable ActivityPub URIs identify the same
-* portable object.
-*
-* Non-string inputs return `false`.  Non-portable URI strings use strict string
-* equality.  Portable URI strings are compared through
-* {@link canonicalizePortableUri}; malformed portable URI strings return
-* `false` unless they are exactly equal.
-*
-* @since 2.4.0
-*/
-declare function arePortableUrisEqual(left: string, right: string): boolean;
-/**
-* Computes an IRI's FEP-fe34 origin.
-*
-* HTTP(S) IRIs use their web origin.  FEP-ef61 portable ActivityPub IRIs and
-* DID URLs use their DID as a cryptographic origin.
-*
-* @throws {TypeError} If the IRI does not have a supported FEP-fe34 origin.
-* @since 2.4.0
-*/
-declare function getFe34Origin(input: string | URL): string;
-/**
-* Checks whether two IRIs have the same FEP-fe34 origin.
-*
-* Malformed or unsupported IRIs are treated as non-matching.
-*
-* @since 2.4.0
-*/
-declare function haveSameFe34Origin(left: string | URL, right: string | URL): boolean;
-/**
-* Checks whether two IRIs have the same origin.  Unlike comparing
-* `URL.origin`, which is `"null"` for URLs with non-special schemes, this
-* compares FEP-ef61 portable ActivityPub IRIs by their schemes and DIDs, so
-* that `ap:` and `ap+ef61:` IRIs of the same DID with decoded or
-* percent-encoded authorities have the same origin.  Other IRIs with
-* a non-special scheme and a host are compared by their schemes and hosts.
-*
-* This is not an FEP-fe34 origin check: an `ap+ef61:` IRI and the `did:key`
-* verification method of the same DID have different origins here.  Use
-* {@link haveSameFe34Origin} for that.
-* @param left The first IRI.
-* @param right The second IRI.
-* @returns `true` if the IRIs have the same origin.
-* @since 2.4.0
-*/
-declare function haveSameIriOrigin(left: URL, right: URL): boolean;
-/**
-* Checks whether the URL is an FEP-ef61 gateway base URI, i.e., an HTTP(S)
-* URI with no credentials, path, query, or fragment, such as
-* `https://example.com/`.  FEP-ef61 requires every item of a portable actor's
-* `gateways` to be such a URI.  A URI with an empty query or fragment
-* delimiter, such as `https://example.com/?`, is not a gateway base URI.
-*
-* Note that the `URL` class normalizes `https://example.com` to
-* `https://example.com/`, so both are gateway base URIs.
-* @param url The URL to check.
-* @returns `true` if the URL is an FEP-ef61 gateway base URI.
-* @since 2.4.0
-*/
-declare function isGatewayUrl(url: URL): boolean;
-/**
-* Parses and validates an FEP-ef61 gateway base URI, i.e., an HTTP(S) URI with
-* no credentials, path, query, or fragment, such as `https://example.com`.
-* See {@link isGatewayUrl} for the rules.
-* @param url The gateway base URI to parse.
-* @returns The parsed gateway base URI, whose path is `/`.
-* @throws {TypeError} If the URI is malformed, or is not an HTTP(S) base URI
-*                     with no credentials, path, query, or fragment.  In the
-*                     latter case, the message starts with
-*                     `Invalid FEP-ef61 gateway:`.
-* @since 2.4.0
-*/
-declare function parseGatewayUrl(url: string): URL;
-/**
-* Converts an [FEP-ef61] compatible identifier into a portable ActivityPub
-* URI.
-*
-* A compatible identifier is an HTTP(S) URL under a gateway's fixed
-* `/.well-known/apgateway/` path, such as
-* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
-* This function removes the gateway part and returns the corresponding
-* portable URI, e.g., `ap+ef61://did:key:z6Mk.../objects/1`, in the same
-* internal `URL` form that {@link parseIri} produces.  The path, query, and
-* fragment are preserved, so the result is a portable URI, not a comparison
-* form; pass its `href` to {@link canonicalizePortableUri} or
-* {@link arePortableUrisEqual} to compare it with other portable URIs.
-*
-* The conversion only reveals the *claimed* portable identifier.  Anyone can
-* publish a compatible identifier for any DID on their own server, so the
-* gateway that served it is neither the object's origin nor authorized to act
-* for the DID.  Callers must still verify the retrieved document's Object
-* Integrity Proof against the DID, as FEP-ef61 requires, and should keep the
-* original URL if they need the gateway as a retrieval hint.
-*
-* Arbitrary gateway paths are not supported.
-*
-* [FEP-ef61]: https://w3id.org/fep/ef61
-*
-* @param input The URL to convert.
-* @returns The portable ActivityPub URI, or `null` if the input is not an
-*          HTTP(S) URL whose path starts with `/.well-known/apgateway/did:`.
-*          Other gateway routes, such as the gateway discovery endpoint and
-*          hashlink media URLs, also yield `null`.
-* @throws {TypeError} If the input looks like a compatible identifier but is
-*                     malformed, e.g., it has an invalid DID, no object path,
-*                     invalid percent-encoding, credentials, or location
-*                     hints (`@gateway` query parameters, or the legacy
-*                     `gateways` parameter), or its raw string path would
-*                     change during URL parsing.  Already-parsed `URL`
-*                     arguments cannot reveal segments lost by their parser.
-* @since 2.4.0
-*/
-declare function fromCompatibleEf61Id(input: string | URL): URL | null;
-/**
-* Converts a portable ActivityPub URI into an [FEP-ef61] compatible
-* identifier, which is an HTTP(S) URL under the gateway's fixed
-* `/.well-known/apgateway/` path.
-*
-* For example, `ap+ef61://did:key:z6Mk.../objects/1` and
-* `https://server.example` yield
-* `https://server.example/.well-known/apgateway/did:key:z6Mk.../objects/1`.
-* Both `ap:` and `ap+ef61:` URIs with decoded or percent-encoded DID
-* authorities are accepted.  Publishers should use the first gateway in the
-* actor's `gateways` list, as FEP-ef61 requires.
-*
-* The path and fragment are preserved, with characters that are not allowed
-* in HTTP(S) URLs percent-encoded the same way as
-* {@link canonicalizePortableUri} does.  FEP-ef61 location hints (`@gateway`
-* query parameters, and the legacy `gateways` parameter) are removed, since
-* compatible identifiers must not have them; other query parameters are kept
-* in order.
-*
-* Arbitrary gateway paths are not supported.
-*
-* [FEP-ef61]: https://w3id.org/fep/ef61
-*
-* @param portableId The `ap:` or `ap+ef61:` URI to convert.
-* @param gateway The gateway's HTTP(S) origin, e.g., `https://server.example`.
-* @returns The compatible identifier.
-* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
-*                     URI, if its path has `.` or `..` segments (which
-*                     HTTP(S) URLs cannot represent without changing the
-*                     identified object), or if the gateway is
-*                     not an HTTP(S) origin with no credentials, path, query,
-*                     or fragment.
-* @since 2.4.0
-*/
-declare function toCompatibleEf61Id(portableId: string | URL, gateway: string | URL): URL;
-/**
-* Returns a copy of an [FEP-ef61] portable ActivityPub URI with `@gateway`
-* location hints for the given gateways, which tell consumers where they can
-* retrieve the object.  Put hints on *references* to portable actors, e.g.,
-* in `actor`, `attributedTo`, `to`, or `cc`, when constructing an object, as
-* FEP-ef61 recommends:
-*
-* ~~~~ typescript
-* withGatewayHints("ap://did:key:z6Mk.../actor", [
-*   "https://server1.example",
-*   "https://server2.example",
-* ]);
-* // ap+ef61://did:key:z6Mk.../actor?@gateway=https%3A%2F%2Fserver1.example&@gateway=https%3A%2F%2Fserver2.example
-* ~~~~
-*
-* Do not put hints on an object's own `id`.  Hints do not change the
-* identity of a portable URI, since FEP-ef61 drops the query when comparing
-* portable URIs, but implementations that do not canonicalize portable URIs
-* would take a hinted ID for another object.  Add hints before signing the
-* object, since its Object Integrity Proof covers its references too.
-*
-* The hints that the URI already has, including the legacy `gateways`
-* parameter, are replaced.  Each gateway becomes a `@gateway` query
-* parameter whose value is its URI-encoded origin, e.g.,
-* `@gateway=https%3A%2F%2Fserver1.example`, in the given order after the
-* other query parameters.  Duplicate gateways are dropped, and an empty list
-* removes the hints as {@link withoutGatewayHints} does.  The other query
-* parameters, their order, and the fragment are kept, but percent-encoding
-* is normalized the same way as {@link canonicalizePortableUri} does it.
-*
-* Fedify follows at most five hints when dereferencing a portable URI
-* (three for the key ID of an HTTP Signature), so list the preferred
-* gateways first; there is no limit on the number of hints added here.
-*
-* [FEP-ef61]: https://w3id.org/fep/ef61
-*
-* @param portableId The `ap:` or `ap+ef61:` URI.  Pass the raw string rather
-*                   than a `URL` if its path may have `.` or `..` segments,
-*                   because the `URL` class resolves them.
-* @param gateways The gateways, e.g., the `gateways` of the actor that the
-*                 URI refers to.  Each has to be an HTTP(S) origin with no
-*                 credentials, path, query, or fragment.
-* @returns The portable URI with the hints, in the same internal `URL` form
-*          as {@link parseIri} returns.  Use {@link formatIri} to get its
-*          canonical string.
-* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
-*                     URI, e.g., it is a compatible identifier, which must
-*                     not have location hints; if its path has `.` or `..`
-*                     segments, which the `URL` class cannot represent; or
-*                     if a gateway is invalid.
-* @since 2.4.0
-*/
-declare function withGatewayHints(portableId: string | URL, gateways: Iterable<string | URL>): URL;
-/**
-* Returns a copy of an [FEP-ef61] portable ActivityPub URI without its
-* location hints, i.e., `@gateway` query parameters and the legacy
-* `gateways` parameter.  The other query parameters, their order, and the
-* fragment are kept, but percent-encoding is normalized the same way as
-* {@link canonicalizePortableUri} does it.
-*
-* [FEP-ef61]: https://w3id.org/fep/ef61
-*
-* @param portableId The `ap:` or `ap+ef61:` URI.  Pass the raw string rather
-*                   than a `URL` if its path may have `.` or `..` segments,
-*                   because the `URL` class resolves them.
-* @returns The portable URI without the hints, in the same internal `URL`
-*          form as {@link parseIri} returns.
-* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
-*                     URI, or if its path has `.` or `..` segments, which
-*                     the `URL` class cannot represent.
-* @since 2.4.0
-*/
-declare function withoutGatewayHints(portableId: string | URL): URL;
-/**
-* Gets the gateways in the `@gateway` location hints of an [FEP-ef61]
-* portable ActivityPub URI, in order.  Hints that are not valid gateways,
-* i.e., HTTP(S) origins with no credentials, path, query, or fragment, are
-* skipped, and so are duplicates.  The legacy `gateways` parameter is not
-* read.
-*
-* Unlike Fedify's dereferencing, which follows at most five hints, this
-* returns all of them.
-*
-* [FEP-ef61]: https://w3id.org/fep/ef61
-*
-* @param portableId The `ap:` or `ap+ef61:` URI.
-* @returns The gateways, e.g., `https://server1.example/`.
-* @throws {TypeError} If the portable ID is not a valid `ap:` or `ap+ef61:`
-*                     URI.
-* @since 2.4.0
-*/
-declare function getGatewayHints(portableId: string | URL): URL[];
-/**
-* Validates a URL to prevent SSRF attacks.
-*/
-declare function validatePublicUrl(url: string): Promise<void>;
-declare function isValidPublicIPv4Address(address: string): boolean;
-declare function isValidPublicIPv6Address(address: string): boolean;
-declare function expandIPv6Address(address: string): string;
-//#endregion
 export { type AuthenticatedDocumentLoaderFactory, type CreateRequestOptions, type Decimal, type DidKeyVerificationMethod, type DocumentLoader, type DocumentLoaderFactory, type DocumentLoaderFactoryOptions, type DocumentLoaderOptions, FetchError, type FetchPortableMediaOptions, type GetDocumentLoaderOptions, type GetUserAgentOptions, type Json, LanguageString, type ParsedDigestMultibase, type ParsedHashlink, type PortableMedia, type PortableObjectReferrer, type PortableObjectVerification, type PortableObjectVerifier, type PortableObjectVerifierOptions, type PropertyPreprocessor, type PropertyPreprocessorContext, type RemoteDocument, UrlError, arePortableUrisEqual, canParseDecimal, canonicalizePortableUri, computeDigestMultibase, createActivityPubRequest, createHashlink, decodeMultibase, encodeMultibase, encodingFromBaseData, expandIPv6Address, exportDidKey, exportMultibaseKey, exportSpki, fetchPortableMedia, formatIri, fromCompatibleEf61Id, getDocumentLoader, getFe34Origin, getGatewayHints, getRemoteDocument, getUserAgent, haveSameFe34Origin, haveSameIriOrigin, importDidKey, importMultibaseKey, importPem, importPkcs1, importSpki, isDecimal, isGatewayUrl, isTransientFetchError, isValidPublicIPv4Address, isValidPublicIPv6Address, logRequest, normalizeLanguageTag, parseDecimal, parseDidKeyVerificationMethod, parseDigestMultibase, parseGatewayUrl, parseHashlink, parseIri, parseJsonLdId, preloadedContexts, resolveDocumentLoaderTimeout, toCompatibleEf61Id, validatePublicUrl, verifyDigestMultibase, verifyHashlink, withDocumentLoaderTimeout, withGatewayHints, withoutGatewayHints };

package/dist/mod.js

@@ -1,6 +1,7 @@
 
 import { t as preloadedContexts } from "./contexts-DWrj4AGR.js";
-import { S as withoutGatewayHints, _ as parseIri, a as expandIPv6Address, b as validatePublicUrl, c as getFe34Origin, d as haveSameIriOrigin, f as isGatewayUrl, g as parseGatewayUrl, i as canonicalizePortableUri, l as getGatewayHints, m as isValidPublicIPv6Address, n as UrlError, o as formatIri, p as isValidPublicIPv4Address, r as arePortableUrisEqual, s as fromCompatibleEf61Id, u as haveSameFe34Origin, v as parseJsonLdId, x as withGatewayHints, y as toCompatibleEf61Id } from "./url-Dzyp-NsC.js";
+import { C as toCompatibleEf61Id, E as withoutGatewayHints, T as withGatewayHints, a as canonicalizePortableUri, b as parseIri, c as fromCompatibleEf61Id, d as haveSameFe34Origin, f as haveSameIriOrigin, h as isValidPublicIPv6Address, l as getFe34Origin, m as isValidPublicIPv4Address, n as UrlError, o as expandIPv6Address, p as isGatewayUrl, r as arePortableUrisEqual, s as formatIri, u as getGatewayHints, w as validatePublicUrl, x as parseJsonLdId, y as parseGatewayUrl } from "./url-mWveR5GA.js";
+import { n as openPublicFetch, t as openDirectFetch } from "./public-fetch-ziZ39L5I.js";
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import process from "node:process";
@@ -12,7 +13,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.2448+756933d0";
+var version = "2.5.0-dev.2492+4648c04e";
 //#endregion
 //#region src/request.ts
 /**
@@ -521,7 +522,7 @@ async function bufferErrorResponse(response, url, signal) {
 		try {
 			await readBoundedBytes(response, MAX_ERROR_BODY_SIZE, url);
 		} catch (error) {
-			await clone.body?.cancel().catch(() => {});
+			clone.body?.cancel().catch(() => {});
 			if (signal?.aborted) throw error;
 			logger.debug("Failed to read the error response body from {url}: {error}", {
 				url,
@@ -553,14 +554,48 @@ async function bufferErrorResponse(response, url, signal) {
 * Gets a {@link RemoteDocument} from the given response.
 * @param url The URL of the document to load.
 * @param response The response to get the document from.
-* @param fetch The function to fetch the document.
+* @param fetch The function to fetch the document.  It is called with the URL
+*              of an alternate document, if any, after the response body has
+*              been either read or its cancellation has been started.
 * @param options The options for loading the document.
 * @returns The loaded remote document.
 * @throws {FetchError} If the response is not OK.
 * @internal
 */
 async function getRemoteDocument(url, response, fetch, options) {
-	const documentUrl = response.url === "" ? url : response.url;
+	const result = await parseRemoteDocument(url, response, options);
+	if ("alternate" in result) return await fetch(result.alternate, options);
+	return result.document;
+}
+/**
+* Starts cancelling the body of a response without waiting for it to settle.
+* The cancellation of a branch of a tee (e.g., a body cloned by a fetch mock)
+* settles only after the other branch is cancelled too, per the Streams
+* standard, so awaiting it could block forever.  Failures are only logged.
+* @param response The response whose body is cancelled.
+* @param url The URL of the response, for logging.
+*/
+function cancelResponseBody(response, url) {
+	response.body?.cancel().catch((error) => {
+		logger.debug("Failed to cancel the response body from {url}: {error}", {
+			url,
+			error
+		});
+	});
+}
+/**
+* Gets a {@link RemoteDocument} from the given response, or the URL of an
+* alternate document to load instead.  When an alternate document is found,
+* the response body has been either read or its cancellation has been started
+* (without waiting for it), so that the alternate document can be loaded after
+* the response's session is closed.
+* @param url The URL of the document to load.
+* @param response The response to get the document from.
+* @returns The loaded remote document, or the alternate document URL.
+* @throws {FetchError} If the response is not OK.
+*/
+async function parseRemoteDocument(url, response, options) {
+	const documentUrl = url;
 	const docUrl = new URL(documentUrl);
 	if (!response.ok) {
 		if (options?.suppressError) logger.warn("Failed to fetch document: {status} {url} {headers}", {
@@ -602,7 +637,8 @@ async function getRemoteDocument(url, response, fetch, options) {
 						alternateUrl: altUri.href,
 						url: documentUrl
 					});
-					return await fetch(altUri.href, options);
+					cancelResponseBody(response, documentUrl);
+					return { alternate: altUri.href };
 				}
 			}
 		}
@@ -638,7 +674,7 @@ async function getRemoteDocument(url, response, fetch, options) {
 					alternateUrl: attribs.href,
 					url: documentUrl
 				});
-				return await fetch(new URL(attribs.href, docUrl).href, options);
+				return { alternate: new URL(attribs.href, docUrl).href };
 			}
 		}
 		try {
@@ -653,11 +689,11 @@ async function getRemoteDocument(url, response, fetch, options) {
 		url: documentUrl,
 		headers: Object.fromEntries(response.headers.entries())
 	});
-	return {
+	return { document: {
 		contextUrl,
 		document,
 		documentUrl
-	};
+	} };
 }
 /**
 * Resolves {@link DocumentLoaderFactoryOptions.timeout} into milliseconds.
@@ -762,10 +798,59 @@ function withDocumentLoaderTimeout(loader, timeout) {
 * @returns The document loader.
 * @since 1.3.0
 */
-function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedContexts, timeout, userAgent } = {}) {
+function getDocumentLoader(options = {}) {
+	return createDocumentLoader(options);
+}
+/**
+* The implementation of {@link getDocumentLoader}, with injectable
+* dependencies.  This is not exported from any entry point.
+* @param options Options for the document loader.
+* @param deps The dependencies.
+* @returns The document loader.
+*/
+function createDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedContexts, timeout, userAgent } = {}, deps = {}) {
 	const resolvedTimeout = resolveDocumentLoaderTimeout(timeout);
 	const tracer = trace.getTracerProvider().getTracer(name, version);
 	const maximumRedirection = maxRedirection ?? DEFAULT_MAX_REDIRECTION;
+	async function openHop(url, options) {
+		try {
+			const session = deps.openHop != null ? await deps.openHop(url) : allowPrivateAddress ? await openDirectFetch(url) : await openPublicFetch(url, { signal: options?.signal });
+			if (options?.signal?.aborted) {
+				await session.close();
+				options.signal.throwIfAborted();
+			}
+			return session;
+		} catch (error) {
+			if (error instanceof UrlError) if (error.reason === "dns") logger.debug("DNS lookup failed for {url}", {
+				url,
+				error
+			});
+			else logger[options?.suppressError ? "warn" : "error"]("Disallowed private URL: {url}", {
+				url,
+				error
+			});
+			throw error;
+		}
+	}
+	async function fetchHop(session, url, span, options) {
+		try {
+			const request = createActivityPubRequest(url, { userAgent });
+			logRequest(logger, request);
+			const response = await session.fetch(request, {
+				redirect: "manual",
+				signal: options?.signal
+			});
+			span.setAttribute("http.response.status_code", response.status);
+			if (response.status >= 300 && response.status < 400 && response.headers.has("Location")) {
+				const location = response.headers.get("Location");
+				cancelResponseBody(response, url);
+				return { location };
+			}
+			return await parseRemoteDocument(url, response, options);
+		} finally {
+			await session.close();
+		}
+	}
 	async function load(url, options, redirected = 0, visited = /* @__PURE__ */ new Set()) {
 		options?.signal?.throwIfAborted();
 		const parsedUrl = new URL(url);
@@ -780,36 +865,15 @@ function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedC
 				documentUrl: currentUrl
 			};
 		}
-		if (!allowPrivateAddress) {
-			try {
-				await validatePublicUrl(currentUrl);
-			} catch (error) {
-				if (error instanceof UrlError) if (error.reason === "dns") logger.debug("DNS lookup failed for {url}", {
-					url: currentUrl,
-					error
-				});
-				else logger[options?.suppressError ? "warn" : "error"]("Disallowed private URL: {url}", {
-					url: currentUrl,
-					error
-				});
-				throw error;
-			}
-			options?.signal?.throwIfAborted();
-		}
+		const session = await openHop(currentUrl, options);
 		visited.add(currentUrl);
 		return await tracer.startActiveSpan("activitypub.fetch_document", {
 			kind: SpanKind.CLIENT,
 			attributes: { "url.full": currentUrl }
 		}, async (span) => {
 			try {
-				const request = createActivityPubRequest(currentUrl, { userAgent });
-				logRequest(logger, request);
-				const response = await fetch(request, {
-					redirect: "manual",
-					signal: options?.signal
-				});
-				span.setAttribute("http.response.status_code", response.status);
-				if (response.status >= 300 && response.status < 400 && response.headers.has("Location")) {
+				const outcome = await fetchHop(session, currentUrl, span, options);
+				if ("location" in outcome) {
 					if (redirected >= maximumRedirection) {
 						logger[options?.suppressError ? "warn" : "error"]("Too many redirections ({redirections}) while fetching document.", {
 							redirections: redirected + 1,
@@ -817,7 +881,7 @@ function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedC
 						});
 						throw new FetchError(currentUrl, `Too many redirections (${redirected + 1})`);
 					}
-					const redirectUrl = new URL(response.headers.get("Location"), response.url === "" ? currentUrl : response.url).href;
+					const redirectUrl = new URL(outcome.location, currentUrl).href;
 					span.setAttribute("http.redirect.url", redirectUrl);
 					if (visited.has(redirectUrl)) {
 						logger[options?.suppressError ? "warn" : "error"]("Detected a redirect loop while fetching document: {url} -> {redirectUrl}", {
@@ -828,12 +892,14 @@ function getDocumentLoader({ allowPrivateAddress, maxRedirection, skipPreloadedC
 					}
 					return await load(redirectUrl, options, redirected + 1, visited);
 				}
-				const result = await getRemoteDocument(currentUrl, response, async (alternateUrl) => {
+				let result;
+				if ("alternate" in outcome) {
+					const alternateUrl = outcome.alternate;
 					options?.signal?.throwIfAborted();
 					if (redirected >= DEFAULT_MAX_REDIRECTION) throw new FetchError(currentUrl, `Too many redirections (${redirected + 1})`);
 					if (visited.has(alternateUrl)) throw new FetchError(currentUrl, `Redirect loop detected: ${alternateUrl}`);
-					return await load(alternateUrl, options, redirected + 1, visited);
-				}, options);
+					result = await load(alternateUrl, options, redirected + 1, visited);
+				} else result = outcome.document;
 				span.setAttribute("docloader.document_url", result.documentUrl);
 				if (result.contextUrl != null) span.setAttribute("docloader.context_url", result.contextUrl);
 				return result;

package/dist/{portable-BDydjp5H.d.ts → portable-1VSnSJFj.d.ts}

@@ -1,5 +1,5 @@
 /// <reference lib="esnext.temporal" />
-import { n as DocumentLoader } from "./docloader-BBnBpbsG.js";
+import { n as DocumentLoader } from "./docloader-DD6binpN.js";
 import { TracerProvider } from "@opentelemetry/api";
 
 //#region src/portable.d.ts

package/dist/{portable-Dfvcg_Wy.d.cts → portable-Cr7NwZwb.d.cts}

@@ -1,5 +1,5 @@
 /// <reference lib="esnext.temporal" />
-import { n as DocumentLoader } from "./docloader-BBnBpbsG.cjs";
+import { n as DocumentLoader } from "./docloader-DD6binpN.cjs";
 import { TracerProvider } from "@opentelemetry/api";
 
 //#region src/portable.d.ts