@fedify/fedify
Version:
An ActivityPub server framework
209 lines • 7.2 kB
TypeScript
import * as dntShim from "../_dnt.shims.js";
import type { KvKey, KvStore } from "../federation/kv.js";
/**
* A remote JSON-LD document and its context fetched by
* a {@link DocumentLoader}.
*/
export interface RemoteDocument {
/**
* The URL of the context document.
*/
contextUrl: string | null;
/**
* The fetched JSON-LD document.
*/
document: unknown;
/**
* The URL of the fetched document.
*/
documentUrl: string;
}
/**
* A JSON-LD document loader that fetches documents from the Web.
* @param url The URL of the document to load.
* @returns The loaded remote document.
*/
export type DocumentLoader = (url: string) => Promise<RemoteDocument>;
/**
* A factory function that creates a {@link DocumentLoader} with options.
* @param options The options for the document loader.
* @returns The document loader.
* @since 1.4.0
*/
export type DocumentLoaderFactory = (options?: DocumentLoaderFactoryOptions) => DocumentLoader;
/**
* Options for {@link DocumentLoaderFactory}.
* @see {@link DocumentLoaderFactory}
* @see {@link AuthenticatedDocumentLoaderFactory}
* @since 1.4.0
*/
export interface DocumentLoaderFactoryOptions {
/**
* Whether to allow fetching private network addresses.
* Turned off by default.
* @default `false``
*/
allowPrivateAddress?: boolean;
/**
* Options for making `User-Agent` string.
* If a string is given, it is used as the `User-Agent` header value.
* If an object is given, it is passed to {@link getUserAgent} function.
*/
userAgent?: GetUserAgentOptions | string;
}
/**
* A factory function that creates an authenticated {@link DocumentLoader} for
* a given identity. This is used for fetching documents that require
* authentication.
* @param identity The identity to create the document loader for.
* The actor's key pair.
* @param options The options for the document loader.
* @returns The authenticated document loader.
* @since 0.4.0
*/
export type AuthenticatedDocumentLoaderFactory = (identity: {
keyId: URL;
privateKey: dntShim.CryptoKey;
}, options?: DocumentLoaderFactoryOptions) => DocumentLoader;
/**
* Error thrown when fetching a JSON-LD document failed.
*/
export declare class FetchError extends Error {
/**
* The URL that failed to fetch.
*/
url: URL;
/**
* Constructs a new `FetchError`.
*
* @param url The URL that failed to fetch.
* @param message Error message.
*/
constructor(url: URL | string, message?: string);
}
/**
* Options for {@link getDocumentLoader}.
* @since 1.3.0
*/
export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
/**
* Whether to preload the frequently used contexts.
*/
skipPreloadedContexts?: boolean;
}
/**
* Creates a JSON-LD document loader that utilizes the browser's `fetch` API.
*
* The created loader preloads the below frequently used contexts by default
* (unless `options.ignorePreloadedContexts` is set to `true`):
*
* - <https://www.w3.org/ns/activitystreams>
* - <https://w3id.org/security/v1>
* - <https://w3id.org/security/data-integrity/v1>
* - <https://www.w3.org/ns/did/v1>
* - <https://w3id.org/security/multikey/v1>
* - <https://purl.archive.org/socialweb/webfinger>
* - <http://schema.org/>
* @param options Options for the document loader.
* @returns The document loader.
* @since 1.3.0
*/
export declare function getDocumentLoader({ allowPrivateAddress, skipPreloadedContexts, userAgent }?: GetDocumentLoaderOptions): DocumentLoader;
/**
* A JSON-LD document loader that utilizes the browser's `fetch` API.
*
* This loader preloads the below frequently used contexts:
*
* - <https://www.w3.org/ns/activitystreams>
* - <https://w3id.org/security/v1>
* - <https://w3id.org/security/data-integrity/v1>
* - <https://www.w3.org/ns/did/v1>
* - <https://w3id.org/security/multikey/v1>
* - <https://purl.archive.org/socialweb/webfinger>
* - <http://schema.org/>
* @param url The URL of the document to load.
* @param allowPrivateAddress Whether to allow fetching private network
* addresses. Turned off by default.
* @returns The remote document.
* @deprecated Use {@link getDocumentLoader} instead.
*/
export declare function fetchDocumentLoader(url: string, allowPrivateAddress?: boolean): Promise<RemoteDocument>;
/**
* Options for {@link getAuthenticatedDocumentLoader}.
* @see {@link getAuthenticatedDocumentLoader}
* @since 1.3.0
*/
export interface GetAuthenticatedDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
}
/**
* 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
*/
export declare function getAuthenticatedDocumentLoader(identity: {
keyId: URL;
privateKey: dntShim.CryptoKey;
}, { allowPrivateAddress, userAgent }?: GetAuthenticatedDocumentLoaderOptions): DocumentLoader;
/**
* The parameters for {@link kvCache} function.
*/
export interface KvCacheParameters {
/**
* The document loader to decorate with a cache.
*/
loader: DocumentLoader;
/**
* The key-value store to use for backing the cache.
*/
kv: KvStore;
/**
* The key prefix to use for namespacing the cache.
* `["_fedify", "remoteDocument"]` by default.
*/
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.Duration}.
* The `duration` is allowed to be at most 30 days.
*
* By default, 5 minutes for all URLs.
*/
rules?: [string | URL | dntShim.URLPattern, dntShim.Temporal.Duration][];
}
/**
* 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.
*/
export declare function kvCache({ loader, kv, prefix, rules }: KvCacheParameters): DocumentLoader;
/**
* Options for making `User-Agent` string.
* @see {@link getUserAgent}
* @since 1.3.0
*/
export interface GetUserAgentOptions {
/**
* An optional software name and version, e.g., `"Hollo/1.0.0"`.
*/
software?: string | null;
/**
* An optional URL to append to the user agent string.
* Usually the URL of the ActivityPub instance.
*/
url?: string | URL | null;
}
/**
* Gets the user agent string for the given application and URL.
* @param options The options for making the user agent string.
* @returns The user agent string.
* @since 1.3.0
*/
export declare function getUserAgent({ software, url }?: GetUserAgentOptions): string;
//# sourceMappingURL=docloader.d.ts.map