@fedify/fedify/dist/mod-yvIXFAEi.d.cts

An ActivityPub server framework

/// <reference lib="esnext.temporal" />
import { n as HttpMessageSignaturesSpecDeterminer } from "./http-VyDTd4G3.cjs";
import { n as KvStore, t as KvKey } from "./kv-gJ8LYbxX.cjs";
import { DocumentLoader, DocumentLoaderFactoryOptions } from "@fedify/vocab-runtime";
import { MeterProvider, TracerProvider } from "@opentelemetry/api";

//#region src/utils/docloader.d.ts
/**
* Options for {@link getAuthenticatedDocumentLoader}.
* @see {@link getAuthenticatedDocumentLoader}
* @since 1.3.0
*/
interface GetAuthenticatedDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
  /**
  * An optional 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
  */
  specDeterminer?: HttpMessageSignaturesSpecDeterminer;
  /**
  * The OpenTelemetry tracer provider.  If omitted, the global tracer provider
  * is used.
  * @since 1.6.0
  */
  tracerProvider?: TracerProvider;
}
/**
* Gets an authenticated {@link DocumentLoader} for the given identity.
* Note that an authenticated document loader intentionally does not cache
* the fetched documents.
* @param identity The identity to get the document loader for.
*                 The actor's key pair.
* @param options The options for the document loader.
* @returns The authenticated document loader.
* @throws {TypeError} If the key is invalid or unsupported.
* @since 0.4.0
*/
declare function getAuthenticatedDocumentLoader(identity: {
  keyId: URL;
  privateKey: CryptoKey;
}, {
  allowPrivateAddress,
  maxRedirection,
  userAgent,
  specDeterminer,
  tracerProvider
}?: GetAuthenticatedDocumentLoaderOptions): DocumentLoader;
//#endregion
//#region src/federation/metrics.d.ts
/**
* The kind of remote ActivityPub lookup, recorded as
* `activitypub.lookup.kind` on the public-key lookup and remote document
* fetch metric families.
*
*  -  `public_key`: a public key lookup performed by `fetchKey` /
*     `fetchKeyDetailed` (always recorded on `activitypub.key.lookup*`).
*  -  `actor`: a document fetch whose resolved value is an Actor.  The
*     bucket exists in the taxonomy for future actor-aware call sites;
*     today, actor documents fetched through Fedify's generic document
*     loader are still classified as `object` because the kind is decided
*     at the loader boundary, before the response is parsed.
*  -  `object`: a generic ActivityPub object fetch through Fedify's
*     document loader.  This is the default classification for
*     `documentLoader` invocations that do not match a more specific
*     bucket.
*  -  `context`: a JSON-LD `@context` document fetch through Fedify's
*     context loader.
*  -  `other`: a fetch that does not fit any of the above classifications.
* @since 2.3.0
*/
type LookupKind = "public_key" | "actor" | "object" | "context" | "other";
/**
* The {@link LookupKind} values that can appear on remote document fetch
* metrics.  `public_key` lookups are reported on the
* `activitypub.key.lookup` metric family instead, so it is excluded here.
* @since 2.3.0
*/
type DocumentFetchKind = Exclude<LookupKind, "public_key">;
//#endregion
//#region src/utils/kv-cache.d.ts
/**
* The parameters for {@link kvCache} function.
*/
interface KvCacheParameters {
  /**
  * The document loader to decorate with a cache.
  */
  readonly loader: DocumentLoader;
  /**
  * The key–value store to use for backing the cache.
  */
  readonly kv: KvStore;
  /**
  * The key prefix to use for namespacing the cache.
  * `["_fedify", "remoteDocument"]` by default.
  */
  readonly prefix?: KvKey;
  /**
  * The per-URL cache rules in the array of `[urlPattern, duration]` pairs
  * where `urlPattern` is either a string, a {@link URL}, or
  * a {@link URLPattern} and `duration` is a {@link Temporal.DurationLike}.
  * The `duration` is allowed to be at most 30 days.
  *
  * By default, 5 minutes for all URLs.
  */
  readonly rules?: readonly [string | URL | URLPattern, Temporal.Duration | Temporal.DurationLike][];
  /**
  * The OpenTelemetry meter provider used to record
  * `activitypub.document.cache` measurements.  When omitted, the wrapper
  * does not emit any metric measurements, preserving the previous
  * unobserved-cache behavior.
  * @since 2.3.0
  */
  readonly meterProvider?: MeterProvider;
  /**
  * The lookup kind to record on the `activitypub.lookup.kind` attribute of
  * `activitypub.document.cache` measurements.  Defaults to `"object"` so
  * the generic document loader case does not require an explicit option.
  * Set to `"context"` for context-loader wrappers; the
  * authenticated-loader path does not use `kvCache()` and is therefore
  * out of scope.
  * @since 2.3.0
  */
  readonly kind?: DocumentFetchKind;
}
/**
* Decorates a {@link DocumentLoader} with a cache backed by a {@link KvStore}.
* @param parameters The parameters for the cache.
* @returns The decorated document loader which is cache-enabled.
*/
declare function kvCache({
  loader,
  kv,
  prefix,
  rules,
  meterProvider,
  kind
}: KvCacheParameters): DocumentLoader;
//#endregion
export { getAuthenticatedDocumentLoader as n, kvCache as t };