@fedify/fedify 2.0.0-dev.1485 → 2.0.0-dev.150

package/dist/http-M8k5mKc0.d.cts

@@ -0,0 +1,253 @@
+import { CryptographicKey, Multikey } from "./vocab-CeDBzu-f.cjs";
+import { DocumentLoader } from "@fedify/vocab-runtime";
+import { TracerProvider } from "@opentelemetry/api";
+
+//#region src/sig/key.d.ts
+
+/**
+ * Generates a key pair which is appropriate for Fedify.
+ * @param algorithm The algorithm to use.  Currently only RSASSA-PKCS1-v1_5 and
+ *                  Ed25519 are supported.
+ * @returns The generated key pair.
+ * @throws {TypeError} If the algorithm is unsupported.
+ */
+declare function generateCryptoKeyPair(algorithm?: "RSASSA-PKCS1-v1_5" | "Ed25519"): Promise<CryptoKeyPair>;
+/**
+ * Exports a key in JWK format.
+ * @param key The key to export.  Either public or private key.
+ * @returns The exported key in JWK format.  The key is suitable for
+ *          serialization and storage.
+ * @throws {TypeError} If the key is invalid or unsupported.
+ */
+declare function exportJwk(key: CryptoKey): Promise<JsonWebKey>;
+/**
+ * Imports a key from JWK format.
+ * @param jwk The key in JWK format.
+ * @param type Which type of key to import, either `"public"` or `"private"`.
+ * @returns The imported key.
+ * @throws {TypeError} If the key is invalid or unsupported.
+ */
+declare function importJwk(jwk: JsonWebKey, type: "public" | "private"): Promise<CryptoKey>;
+/**
+ * Options for {@link fetchKey}.
+ * @since 1.3.0
+ */
+interface FetchKeyOptions {
+  /**
+   * The document loader for loading remote JSON-LD documents.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The context loader for loading remote JSON-LD contexts.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The key cache to use for caching public keys.
+   * @since 0.12.0
+   */
+  keyCache?: KeyCache;
+  /**
+   * The OpenTelemetry tracer provider to use for tracing.  If omitted,
+   * the global tracer provider is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * The result of {@link fetchKey}.
+ * @since 1.3.0
+ */
+interface FetchKeyResult<T extends CryptographicKey | Multikey> {
+  /**
+   * The fetched (or cached) key.
+   */
+  readonly key: T & {
+    publicKey: CryptoKey;
+  } | null;
+  /**
+   * Whether the key is fetched from the cache.
+   */
+  readonly cached: boolean;
+}
+/**
+ * Fetches a {@link CryptographicKey} or {@link Multikey} from the given URL.
+ * If the given URL contains an {@link Actor} object, it tries to find
+ * the corresponding key in the `publicKey` or `assertionMethod` property.
+ * @template T The type of the key to fetch.  Either {@link CryptographicKey}
+ *              or {@link Multikey}.
+ * @param keyId The URL of the key.
+ * @param cls The class of the key to fetch.  Either {@link CryptographicKey}
+ *            or {@link Multikey}.
+ * @param options Options for fetching the key.  See {@link FetchKeyOptions}.
+ * @returns The fetched key or `null` if the key is not found.
+ * @since 1.3.0
+ */
+declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | string, cls: (new (...args: any[]) => T) & {
+  fromJsonLd(jsonLd: unknown, options: {
+    documentLoader?: DocumentLoader;
+    contextLoader?: DocumentLoader;
+    tracerProvider?: TracerProvider;
+  }): Promise<T>;
+}, options?: FetchKeyOptions): Promise<FetchKeyResult<T>>;
+/**
+ * A cache for storing cryptographic keys.
+ * @since 0.12.0
+ */
+interface KeyCache {
+  /**
+   * Gets a key from the cache.
+   * @param keyId The key ID.
+   * @returns The key if found, `null` if the key is not available (e.g.,
+   *          fetching the key was tried but failed), or `undefined`
+   *          if the cache is not available.
+   */
+  get(keyId: URL): Promise<CryptographicKey | Multikey | null | undefined>;
+  /**
+   * Sets a key to the cache.
+   *
+   * Note that this caches unavailable keys (i.e., `null`) as well,
+   * and it is recommended to make unavailable keys expire after a short period.
+   * @param keyId The key ID.
+   * @param key The key to cache.  `null` means the key is not available
+   *            (e.g., fetching the key was tried but failed).
+   */
+  set(keyId: URL, key: CryptographicKey | Multikey | null): Promise<void>;
+}
+//#endregion
+//#region src/sig/http.d.ts
+/**
+ * The standard to use for signing and verifying HTTP signatures.
+ * @since 1.6.0
+ */
+type HttpMessageSignaturesSpec =
+/**
+ * The Signing HTTP Messages (draft-cavage-http-signatures-12) specification,
+ * which is widely adopted and used in the fediverse (as of May 2025).
+ */
+"draft-cavage-http-signatures-12"
+/**
+ * The HTTP Message Signatures (RFC 9421) specification, which is the
+ * finalized standard but not widely adopted yet (as of May 2025).
+ */ | "rfc9421";
+/**
+ * Options for {@link signRequest}.
+ * @since 1.3.0
+ */
+interface SignRequestOptions {
+  /**
+   * The HTTP message signatures specification to use for signing.
+   * @default `"draft-cavage-http-signatures-12"`
+   * @since 1.6.0
+   */
+  spec?: HttpMessageSignaturesSpec;
+  /**
+   * The current time.  If not specified, the current time is used.  This is
+   * useful for testing.
+   * @since 1.6.0
+   */
+  currentTime?: Temporal.Instant;
+  /**
+   * The request body as ArrayBuffer. If provided, avoids cloning the request body.
+   * @since 1.7.7
+   */
+  body?: ArrayBuffer | null;
+  /**
+   * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+   * is used.
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Signs a request using the given private key.
+ * @param request The request to sign.
+ * @param privateKey The private key to use for signing.
+ * @param keyId The key ID to use for the signature.  It will be used by the
+ *              verifier.
+ * @returns The signed request.
+ * @throws {TypeError} If the private key is invalid or unsupported.
+ */
+declare function signRequest(request: Request, privateKey: CryptoKey, keyId: URL, options?: SignRequestOptions): Promise<Request>;
+/**
+ * Options for {@link verifyRequest}.
+ */
+interface VerifyRequestOptions {
+  /**
+   * The document loader to use for fetching the public key.
+   */
+  documentLoader?: DocumentLoader;
+  /**
+   * The context loader to use for JSON-LD context retrieval.
+   */
+  contextLoader?: DocumentLoader;
+  /**
+   * The time window to allow for the request date.  The actual time window is
+   * twice the value of this option, with the current time as the center.
+   * Or if it is `false`, no time check is performed.
+   *
+   * An hour by default.
+   */
+  timeWindow?: Temporal.Duration | Temporal.DurationLike | false;
+  /**
+   * The current time.  If not specified, the current time is used.  This is
+   * useful for testing.
+   */
+  currentTime?: Temporal.Instant;
+  /**
+   * The key cache to use for caching public keys.
+   * @since 0.12.0
+   */
+  keyCache?: KeyCache;
+  /**
+   * The HTTP message signatures specification to use for verifying.
+   * @default `"draft-cavage-http-signatures-12"`
+   * @since 1.6.0
+   */
+  spec?: HttpMessageSignaturesSpec;
+  /**
+   * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
+   * is used.
+   * @since 1.3.0
+   */
+  tracerProvider?: TracerProvider;
+}
+/**
+ * Verifies the signature of a request.
+ *
+ * Note that this function consumes the request body, so it should not be used
+ * if the request body is already consumed.  Consuming the request body after
+ * calling this function is okay, since this function clones the request
+ * under the hood.
+ *
+ * @param request The request to verify.
+ * @param options Options for verifying the request.
+ * @returns The public key of the verified signature, or `null` if the signature
+ *          could not be verified.
+ */
+declare function verifyRequest(request: Request, options?: VerifyRequestOptions): Promise<CryptographicKey | null>;
+/**
+ * A spec determiner for HTTP Message Signatures.
+ * It determines the spec to use for signing requests.
+ * It is used for double-knocking
+ * (see <https://swicg.github.io/activitypub-http-signature/#how-to-upgrade-supported-versions>).
+ * @since 1.6.0
+ */
+interface HttpMessageSignaturesSpecDeterminer {
+  /**
+   * Determines the spec to use for signing requests.
+   * @param origin The origin of the URL to make the request to.
+   * @returns The spec to use for signing requests.
+   */
+  determineSpec(origin: string): HttpMessageSignaturesSpec | Promise<HttpMessageSignaturesSpec>;
+  /**
+   * Remembers the successfully used spec for the given origin.
+   * @param origin The origin of the URL that was requested.
+   * @param spec The spec to remember.
+   */
+  rememberSpec(origin: string, spec: HttpMessageSignaturesSpec): void | Promise<void>;
+}
+/**
+ * The options for double-knock requests.
+ * @since 1.6.0
+ */
+//#endregion
+export { FetchKeyOptions, FetchKeyResult, HttpMessageSignaturesSpec, HttpMessageSignaturesSpecDeterminer, KeyCache, SignRequestOptions, VerifyRequestOptions, exportJwk, fetchKey, generateCryptoKeyPair, importJwk, signRequest, verifyRequest };

package/dist/{http-C7rxW7Kh.js → http-b10BrywC.js}

@@ -3,8 +3,9 @@
       import { URLPattern } from "urlpattern-polyfill";
       globalThis.addEventListener = () => {};
     
-import { CryptographicKey, deno_default } from "./type-I68qwqmo.js";
-import { fetchKey, validateCryptoKey } from "./key-CYOcZ9G5.js";
+import { deno_default } from "./deno-DHmnBq8X.js";
+import { CryptographicKey } from "./vocab-Durhw0Gx.js";
+import { fetchKey, validateCryptoKey } from "./key-W6YaI4J_.js";
 import { getLogger } from "@logtape/logtape";
 import { SpanStatusCode, trace } from "@opentelemetry/api";
 import { ATTR_HTTP_REQUEST_HEADER, ATTR_HTTP_REQUEST_METHOD, ATTR_URL_FULL } from "@opentelemetry/semantic-conventions";
@@ -658,7 +659,7 @@ async function verifyRequestRfc9421(request, span, { documentLoader, contextLoad
 		const signatureBaseBytes = new TextEncoder().encode(signatureBase);
 		span?.setAttribute("http_signatures.signature", encodeHex(sigBytes));
 		try {
-			const verified = await crypto.subtle.verify(algorithm, key.publicKey, sigBytes, signatureBaseBytes);
+			const verified = await crypto.subtle.verify(algorithm, key.publicKey, sigBytes.slice(), signatureBaseBytes);
 			if (verified) {
 				validKey = key;
 				break;

package/dist/{inbox-eK2W2MF3.js → inbox-gPnuScsy.js}

@@ -3,7 +3,9 @@
       import { URLPattern } from "urlpattern-polyfill";
       globalThis.addEventListener = () => {};
     
-import { Activity, deno_default, getTypeId } from "./type-I68qwqmo.js";
+import { deno_default } from "./deno-DHmnBq8X.js";
+import { Activity } from "./vocab-Durhw0Gx.js";
+import { getTypeId } from "./type-BSNcIxTd.js";
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
 
@@ -41,17 +43,34 @@ var InboxListenerSet = class InboxListenerSet {
 		return this.dispatchWithClass(activity)?.listener ?? null;
 	}
 };
-async function routeActivity({ context: ctx, json, activity, recipient, inboxListeners, inboxContextFactory, inboxErrorHandler, kv, kvPrefixes, queue, span, tracerProvider }) {
+async function routeActivity({ context: ctx, json, activity, recipient, inboxListeners, inboxContextFactory, inboxErrorHandler, kv, kvPrefixes, queue, span, tracerProvider, idempotencyStrategy }) {
 	const logger = getLogger([
 		"fedify",
 		"federation",
 		"inbox"
 	]);
-	const cacheKey = activity.id == null ? null : [
-		...kvPrefixes.activityIdempotence,
-		ctx.origin,
-		activity.id.href
-	];
+	let cacheKey = null;
+	if (activity.id != null) {
+		const inboxContext = inboxContextFactory(recipient, json, activity.id?.href, getTypeId(activity).href);
+		const strategy = idempotencyStrategy ?? "per-inbox";
+		let keyString;
+		if (typeof strategy === "function") {
+			const result = await strategy(inboxContext, activity);
+			keyString = result;
+		} else switch (strategy) {
+			case "global":
+				keyString = activity.id.href;
+				break;
+			case "per-origin":
+				keyString = `${ctx.origin}\n${activity.id.href}`;
+				break;
+			case "per-inbox":
+				keyString = `${ctx.origin}\n${activity.id.href}\n${recipient == null ? "sharedInbox" : `inbox\n${recipient}`}`;
+				break;
+			default: keyString = `${ctx.origin}\n${activity.id.href}`;
+		}
+		if (keyString != null) cacheKey = [...kvPrefixes.activityIdempotence, keyString];
+	}
 	if (cacheKey != null) {
 		const cached = await kv.get(cacheKey);
 		if (cached === true) {

package/dist/{key-CYOcZ9G5.js → key-W6YaI4J_.js}

@@ -3,9 +3,11 @@
       import { URLPattern } from "urlpattern-polyfill";
       globalThis.addEventListener = () => {};
     
-import { CryptographicKey, Object as Object$1, deno_default, getDocumentLoader } from "./type-I68qwqmo.js";
-import { isActor } from "./actor-7ivEf1H3.js";
+import { deno_default } from "./deno-DHmnBq8X.js";
+import { CryptographicKey, Object as Object$1 } from "./vocab-Durhw0Gx.js";
+import { isActor } from "./actor-C6cDxaJJ.js";
 import { getLogger } from "@logtape/logtape";
+import { getDocumentLoader } from "@fedify/vocab-runtime";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 
 //#region src/sig/key.ts

package/dist/{keycache-BLq6GT4_.js → keycache-DkTZcjkH.js}

@@ -3,7 +3,7 @@
       import { URLPattern } from "urlpattern-polyfill";
       globalThis.addEventListener = () => {};
     
-import { CryptographicKey, Multikey } from "./type-I68qwqmo.js";
+import { CryptographicKey, Multikey } from "./vocab-Durhw0Gx.js";
 
 //#region src/federation/keycache.ts
 var KvKeyCache = class {

package/dist/{keys-BIwlbtMN.js → keys-CfcSjjys.js}

@@ -3,7 +3,8 @@
       import { URLPattern } from "urlpattern-polyfill";
       globalThis.addEventListener = () => {};
     
-import { CryptographicKey, Multikey, importSpki } from "./type-I68qwqmo.js";
+import { CryptographicKey, Multikey } from "./vocab-Durhw0Gx.js";
+import { importSpki } from "@fedify/vocab-runtime";
 
 //#region src/testing/keys.ts
 const rsaPublicKey1 = new CryptographicKey({

package/dist/{kv-C7sopW2E.d.ts → kv-BpJND1Hr.d.ts}

@@ -19,6 +19,21 @@ interface KvStoreSetOptions {
    */
   ttl?: Temporal.Duration;
 }
+/**
+ * An entry returned by the {@link KvStore.list} method.
+ *
+ * @since 1.10.0
+ */
+interface KvStoreListEntry {
+  /**
+   * The key of the entry.
+   */
+  key: KvKey;
+  /**
+   * The value of the entry.
+   */
+  value: unknown;
+}
 /**
  * An abstract interface for a key–value store.
  *
@@ -54,6 +69,16 @@ interface KvStore {
    * @since 1.8.0
    */
   cas?: (key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions) => Promise<boolean>;
+  /**
+   * Lists all entries in the store that match the given prefix.
+   * If no prefix is given, all entries are returned.
+   * @param prefix The prefix to filter keys by.  If not specified, all entries
+   *               are returned.
+   * @returns An async iterable of entries matching the prefix.
+   * @since 1.10.0
+   * @since 2.0.0 This method is now required instead of optional.
+   */
+  list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
 }
 /**
  * A key–value store that stores values in memory.
@@ -79,6 +104,10 @@ declare class MemoryKvStore implements KvStore {
    * {@inheritDoc KvStore.cas}
    */
   cas(key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions): Promise<boolean>;
+  /**
+   * {@inheritDoc KvStore.list}
+   */
+  list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
 }
 //#endregion
-export { KvKey, KvStore, KvStoreSetOptions, MemoryKvStore };
+export { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions, MemoryKvStore };

package/dist/{kv-CRZrzyXm.js → kv-DaWUKuhD.js}

@@ -68,6 +68,28 @@ var MemoryKvStore = class {
 		this.#values[encodedKey] = [newValue, expiration];
 		return Promise.resolve(true);
 	}
+	/**
+	* {@inheritDoc KvStore.list}
+	*/
+	async *list(prefix) {
+		const now = Temporal.Now.instant();
+		for (const [encodedKey, entry] of Object.entries(this.#values)) {
+			const key = JSON.parse(encodedKey);
+			if (prefix != null) {
+				if (key.length < prefix.length) continue;
+				if (!prefix.every((p, i) => key[i] === p)) continue;
+			}
+			const [value, expiration] = entry;
+			if (expiration != null && now.until(expiration).sign < 0) {
+				delete this.#values[encodedKey];
+				continue;
+			}
+			yield {
+				key,
+				value
+			};
+		}
+	}
 };
 
 //#endregion

package/dist/kv-cD_d4hg-.d.cts

@@ -0,0 +1,110 @@
+//#region src/federation/kv.d.ts
+/**
+ * A key for a key–value store.  An array of one or more strings.
+ *
+ * @since 0.5.0
+ */
+type KvKey = readonly [string] | readonly [string, ...string[]];
+/**
+ * Additional options for setting a value in a key–value store.
+ *
+ * @since 0.5.0
+ */
+interface KvStoreSetOptions {
+  /**
+   * The time-to-live (TTL) for the value.
+   */
+  ttl?: Temporal.Duration;
+}
+/**
+ * An entry returned by the {@link KvStore.list} method.
+ *
+ * @since 1.10.0
+ */
+interface KvStoreListEntry {
+  /**
+   * The key of the entry.
+   */
+  key: KvKey;
+  /**
+   * The value of the entry.
+   */
+  value: unknown;
+}
+/**
+ * An abstract interface for a key–value store.
+ *
+ * @since 0.5.0
+ */
+interface KvStore {
+  /**
+   * Gets the value for the given key.
+   * @param key The key to get the value for.
+   * @returns The value for the key, or `undefined` if the key does not exist.
+   * @template T The type of the value to get.
+   */
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  /**
+   * Sets the value for the given key.
+   * @param key The key to set the value for.
+   * @param value The value to set.
+   * @param options Additional options for setting the value.
+   */
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions): Promise<void>;
+  /**
+   * Deletes the value for the given key.
+   * @param key The key to delete.
+   */
+  delete(key: KvKey): Promise<void>;
+  /**
+   * Compare-and-swap (CAS) operation for the key–value store.
+   * @param key The key to perform the CAS operation on.
+   * @param expectedValue The expected value for the key.
+   * @param newValue The new value to set if the expected value matches.
+   * @param options Additional options for setting the value.
+   * @return `true` if the CAS operation was successful, `false` otherwise.
+   * @since 1.8.0
+   */
+  cas?: (key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions) => Promise<boolean>;
+  /**
+   * Lists all entries in the store that match the given prefix.
+   * If no prefix is given, all entries are returned.
+   * @param prefix The prefix to filter keys by.  If not specified, all entries
+   *               are returned.
+   * @returns An async iterable of entries matching the prefix.
+   * @since 1.10.0
+   * @since 2.0.0 This method is now required instead of optional.
+   */
+  list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
+}
+/**
+ * A key–value store that stores values in memory.
+ * Do not use this in production as it does not persist values.
+ *
+ * @since 0.5.0
+ */
+declare class MemoryKvStore implements KvStore {
+  #private;
+  /**
+   * {@inheritDoc KvStore.get}
+   */
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  /**
+   * {@inheritDoc KvStore.set}
+   */
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions): Promise<void>;
+  /**
+   * {@inheritDoc KvStore.delete}
+   */
+  delete(key: KvKey): Promise<void>;
+  /**
+   * {@inheritDoc KvStore.cas}
+   */
+  cas(key: KvKey, expectedValue: unknown, newValue: unknown, options?: KvStoreSetOptions): Promise<boolean>;
+  /**
+   * {@inheritDoc KvStore.list}
+   */
+  list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
+}
+//#endregion
+export { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions, MemoryKvStore };

package/dist/kv-cache-C6NrTtII.js

@@ -0,0 +1,107 @@
+
+      import { Temporal } from "@js-temporal/polyfill";
+      import { URLPattern } from "urlpattern-polyfill";
+      globalThis.addEventListener = () => {};
+    
+import { getLogger } from "@logtape/logtape";
+import { preloadedContexts } from "@fedify/vocab-runtime";
+
+//#region src/utils/kv-cache.ts
+const logger = getLogger([
+	"fedify",
+	"utils",
+	"kv-cache"
+]);
+/**
+* A mock implementation of a key–value store for testing purposes.
+*/
+var MockKvStore = class {
+	#values = {};
+	get(key) {
+		return Promise.resolve(this.#values[JSON.stringify(key)]);
+	}
+	set(key, value, _options) {
+		this.#values[JSON.stringify(key)] = value;
+		return Promise.resolve();
+	}
+	async delete(_) {}
+	cas(..._) {
+		return Promise.resolve(false);
+	}
+	async *list(prefix) {
+		for (const [encodedKey, value] of Object.entries(this.#values)) {
+			const key = JSON.parse(encodedKey);
+			if (prefix != null) {
+				if (key.length < prefix.length) continue;
+				if (!prefix.every((p, i) => key[i] === p)) continue;
+			}
+			yield {
+				key,
+				value
+			};
+		}
+	}
+};
+/**
+* Decorates a {@link DocumentLoader} with a cache backed by a {@link Deno.Kv}.
+* @param parameters The parameters for the cache.
+* @returns The decorated document loader which is cache-enabled.
+*/
+function kvCache({ loader, kv, prefix, rules }) {
+	const keyPrefix = prefix ?? ["_fedify", "remoteDocument"];
+	rules ??= [[new URLPattern({}), Temporal.Duration.from({ minutes: 5 })]];
+	for (const [p, duration] of rules) if (Temporal.Duration.compare(duration, { days: 30 }) > 0) throw new TypeError("The maximum cache duration is 30 days: " + (p instanceof URLPattern ? `${p.protocol}://${p.username}:${p.password}@${p.hostname}:${p.port}/${p.pathname}?${p.search}#${p.hash}` : p.toString()));
+	return async (url, options) => {
+		if (url in preloadedContexts) {
+			logger.debug("Using preloaded context: {url}.", { url });
+			return {
+				contextUrl: null,
+				document: preloadedContexts[url],
+				documentUrl: url
+			};
+		}
+		const match = matchRule(url, rules);
+		if (match == null) return await loader(url, options);
+		const key = [...keyPrefix, url];
+		let cache = void 0;
+		try {
+			cache = await kv.get(key);
+		} catch (error) {
+			if (error instanceof Error) logger.warn("Failed to get the document of {url} from the KV cache: {error}", {
+				url,
+				error
+			});
+		}
+		if (cache == null) {
+			const remoteDoc = await loader(url, options);
+			try {
+				await kv.set(key, remoteDoc, { ttl: match });
+			} catch (error) {
+				logger.warn("Failed to save the document of {url} to the KV cache: {error}", {
+					url,
+					error
+				});
+			}
+			return remoteDoc;
+		}
+		return cache;
+	};
+}
+function matchRule(url, rules) {
+	for (const [pattern, d] of rules) {
+		const duration = d instanceof Temporal.Duration ? d : Temporal.Duration.from(d);
+		if (typeof pattern === "string") {
+			if (url === pattern) return duration;
+			continue;
+		}
+		if (pattern instanceof URL) {
+			if (pattern.href == url) return duration;
+			continue;
+		}
+		if (pattern.test(url)) return duration;
+	}
+	return null;
+}
+
+//#endregion
+export { MockKvStore, kvCache };