@fedify/fedify 0.5.0-dev.88

package/esm/federation/middleware.d.ts

@@ -0,0 +1,309 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import * as dntShim from "../_dnt.shims.js";
+import { Temporal } from "@js-temporal/polyfill";
+import { type AuthenticatedDocumentLoaderFactory, type DocumentLoader } from "../runtime/docloader.js";
+import type { Actor } from "../vocab/actor.js";
+import { Activity } from "../vocab/mod.js";
+import type { ActorDispatcher, ActorKeyPairDispatcher, CollectionCounter, CollectionCursor, CollectionDispatcher, InboxErrorHandler, InboxListener, NodeInfoDispatcher } from "./callback.js";
+import type { Context, RequestContext, SendActivityOptions } from "./context.js";
+import type { KvKey, KvStore } from "./kv.js";
+import type { MessageQueue } from "./mq.js";
+/**
+ * Parameters for initializing a {@link Federation} instance.
+ */
+export interface FederationParameters {
+    /**
+     * The key-value store used for caching, outbox queues, and inbox idempotence.
+     */
+    kv: KvStore;
+    /**
+     * Prefixes for namespacing keys in the Deno KV store.  By default, all keys
+     * are prefixed with `["_fedify"]`.
+     */
+    kvPrefixes?: Partial<FederationKvPrefixes>;
+    /**
+     * The message queue for sending activities to recipients' inboxes.
+     * If not provided, activities will not be queued and will be sent
+     * immediately.
+     */
+    queue?: MessageQueue;
+    /**
+     * A custom JSON-LD document loader.  By default, this uses the built-in
+     * cache-backed loader that fetches remote documents over HTTP(S).
+     */
+    documentLoader?: DocumentLoader;
+    /**
+     * A factory function that creates an authenticated document loader for a
+     * given identity.  This is used for fetching documents that require
+     * authentication.
+     */
+    authenticatedDocumentLoaderFactory?: AuthenticatedDocumentLoaderFactory;
+    /**
+     * Whether to treat HTTP requests as HTTPS.  This is useful for testing and
+     * local development.  However, it must be disabled in production.
+     * Turned off by default.
+     */
+    treatHttps?: boolean;
+    backoffSchedule?: Temporal.Duration[];
+}
+/**
+ * Prefixes for namespacing keys in the Deno KV store.
+ */
+export interface FederationKvPrefixes {
+    /**
+     * The key prefix used for storing whether activities have already been
+     * processed or not.  `["_fedify", "activityIdempotence"]` by default.
+     */
+    activityIdempotence: KvKey;
+    /**
+     * The key prefix used for storing remote JSON-LD documents.
+     * `["_fedify", "remoteDocument"]` by default.
+     */
+    remoteDocument: KvKey;
+}
+/**
+ * An object that registers federation-related business logic and dispatches
+ * requests to the appropriate handlers.
+ *
+ * It also provides a middleware interface for handling requests before your
+ * web framework's router; see {@link Federation.handle}.
+ */
+export declare class Federation<TContextData> {
+    #private;
+    /**
+     * Create a new {@link Federation} instance.
+     * @param parameters Parameters for initializing the instance.
+     */
+    constructor({ kv, kvPrefixes, queue, documentLoader, authenticatedDocumentLoaderFactory, treatHttps, backoffSchedule, }: FederationParameters);
+    /**
+     * Create a new context.
+     * @param baseUrl The base URL of the server.  The `pathname` remains root,
+     *                and the `search` and `hash` are stripped.
+     * @param contextData The context data to pass to the context.
+     * @returns The new context.
+     */
+    createContext(baseUrl: URL, contextData: TContextData): Context<TContextData>;
+    /**
+     * Create a new context for a request.
+     * @param request The request object.
+     * @param contextData The context data to pass to the context.
+     * @returns The new request context.
+     */
+    createContext(request: Request, contextData: TContextData): RequestContext<TContextData>;
+    /**
+     * Registers a NodeInfo dispatcher.
+     * @param path The URI path pattern for the NodeInfo dispatcher.  The syntax
+     *             is based on URI Template
+     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
+     *             must have no variables.
+     * @param dispatcher A NodeInfo dispatcher callback to register.
+     * @throws {RouterError} Thrown if the path pattern is invalid.
+     */
+    setNodeInfoDispatcher(path: string, dispatcher: NodeInfoDispatcher<TContextData>): void;
+    /**
+     * Registers an actor dispatcher.
+     *
+     * @example
+     * ``` typescript
+     * federation.setActorDispatcher(
+     *   "/users/{handle}",
+     *   async (ctx, handle, key) => {
+     *     return new Person({
+     *       id: ctx.getActorUri(handle),
+     *       preferredUsername: handle,
+     *       // ...
+     *     });
+     *   }
+     * );
+     * ```
+     *
+     * @param path The URI path pattern for the actor dispatcher.  The syntax is
+     *             based on URI Template
+     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
+     *             must have one variable: `{handle}`.
+     * @param dispatcher An actor dispatcher callback to register.
+     * @returns An object with methods to set other actor dispatcher callbacks.
+     * @throws {RouterError} Thrown if the path pattern is invalid.
+     */
+    setActorDispatcher(path: string, dispatcher: ActorDispatcher<TContextData>): ActorCallbackSetters<TContextData>;
+    /**
+     * Registers an outbox dispatcher.
+     *
+     * @example
+     * ``` typescript
+     * federation.setOutboxDispatcher(
+     *   "/users/{handle}/outbox",
+     *   async (ctx, handle, options) => {
+     *     let items: Activity[];
+     *     let nextCursor: string;
+     *     // ...
+     *     return { items, nextCursor };
+     *   }
+     * );
+     * ```
+     *
+     * @param path The URI path pattern for the outbox dispatcher.  The syntax is
+     *             based on URI Template
+     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
+     *             must have one variable: `{handle}`.
+     * @param dispatcher An outbox dispatcher callback to register.
+     * @throws {@link RouterError} Thrown if the path pattern is invalid.
+     */
+    setOutboxDispatcher(path: string, dispatcher: CollectionDispatcher<Activity, TContextData>): CollectionCallbackSetters<TContextData>;
+    /**
+     * Registers a following collection dispatcher.
+     * @param path The URI path pattern for the following collection.  The syntax
+     *             is based on URI Template
+     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
+     *             must have one variable: `{handle}`.
+     * @param dispatcher A following collection callback to register.
+     * @returns An object with methods to set other following collection
+     *          callbacks.
+     * @throws {RouterError} Thrown if the path pattern is invalid.
+     */
+    setFollowingDispatcher(path: string, dispatcher: CollectionDispatcher<Actor | URL, TContextData>): CollectionCallbackSetters<TContextData>;
+    /**
+     * Registers a followers collection dispatcher.
+     * @param path The URI path pattern for the followers collection.  The syntax
+     *             is based on URI Template
+     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
+     *             must have one variable: `{handle}`.
+     * @param dispatcher A followers collection callback to register.
+     * @returns An object with methods to set other followers collection
+     *          callbacks.
+     * @throws {@link RouterError} Thrown if the path pattern is invalid.
+     */
+    setFollowersDispatcher(path: string, dispatcher: CollectionDispatcher<Actor | URL, TContextData>): CollectionCallbackSetters<TContextData>;
+    /**
+     * Assigns the URL path for the inbox and starts setting inbox listeners.
+     *
+     * @example
+     * ``` typescript
+     * federation
+     *   .setInboxListeners("/users/{handle/inbox", "/inbox")
+     *   .on(Follow, async (ctx, follow) => {
+     *     const from = await follow.getActor(ctx);
+     *     if (!isActor(from)) return;
+     *     // ...
+     *     await ctx.sendActivity({ })
+     *   })
+     *   .on(Undo, async (ctx, undo) => {
+     *     // ...
+     *   });
+     * ```
+     *
+     * @param inboxPath The URI path pattern for the inbox.  The syntax is based
+     *                  on URI Template
+     *                  ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
+     *                  The path must have one variable: `{handle}`.
+     * @param sharedInboxPath An optional URI path pattern for the shared inbox.
+     *                        The syntax is based on URI Template
+     *                        ([RFC 6570](https://tools.ietf.org/html/rfc6570)).
+     *                        The path must have no variables.
+     * @returns An object to register inbox listeners.
+     * @throws {RouteError} Thrown if the path pattern is invalid.
+     */
+    setInboxListeners(inboxPath: string, sharedInboxPath?: string): InboxListenerSetter<TContextData>;
+    /**
+     * Sends an activity to recipients' inboxes.  You would typically use
+     * {@link Context.sendActivity} instead of this method.
+     *
+     * @param sender The sender's key pair.
+     * @param recipients The recipients of the activity.
+     * @param activity The activity to send.
+     * @param options Options for sending the activity.
+     */
+    sendActivity({ keyId, privateKey }: {
+        keyId: URL;
+        privateKey: dntShim.CryptoKey;
+    }, recipients: Actor | Actor[], activity: Activity, { preferSharedInbox, immediate }?: SendActivityOptions): Promise<void>;
+    /**
+     * Handles a request related to federation.  If a request is not related to
+     * federation, the `onNotFound` or `onNotAcceptable` callback is called.
+     *
+     * Usually, this method is called from a server's request handler or
+     * a web framework's middleware.
+     *
+     * @param request The request object.
+     * @param parameters The parameters for handling the request.
+     * @returns The response to the request.
+     */
+    handle(request: Request, { onNotFound, onNotAcceptable, contextData, }: FederationHandlerParameters<TContextData>): Promise<Response>;
+}
+/**
+ * Parameters of {@link Federation.handle} method.
+ *
+ * @typeParam TContextData The context data to pass to the {@link Context}.
+ */
+export interface FederationHandlerParameters<TContextData> {
+    /**
+     * The context data to pass to the {@link Context}.
+     */
+    contextData: TContextData;
+    /**
+     * A callback to handle a request when the route is not found.
+     * If not provided, a 404 response is returned.
+     * @param request The request object.
+     * @returns The response to the request.
+     */
+    onNotFound?: (request: Request) => Response | Promise<Response>;
+    /**
+     * A callback to handle a request when the request's `Accept` header is not
+     * acceptable.  If not provided, a 406 response is returned.
+     * @param request The request object.
+     * @returns The response to the request.
+     */
+    onNotAcceptable?: (request: Request) => Response | Promise<Response>;
+}
+/**
+ * Additional settings for the actor dispatcher.
+ *
+ * ``` typescript
+ * const federation = new Federation<void>({ ... });
+ * federation.setActorDispatcher("/users/{handle}", async (ctx, handle, key) => {
+ *   ...
+ * })
+ *   .setKeyPairDispatcher(async (ctxData, handle) => {
+ *     ...
+ *   });
+ * ```
+ */
+export interface ActorCallbackSetters<TContextData> {
+    /**
+     * Sets the key pair dispatcher for actors.
+     * @param dispatcher A callback that returns the key pair for an actor.
+     * @returns The setters object so that settings can be chained.
+     */
+    setKeyPairDispatcher(dispatcher: ActorKeyPairDispatcher<TContextData>): ActorCallbackSetters<TContextData>;
+}
+/**
+ * Additional settings for a collection dispatcher.
+ */
+export interface CollectionCallbackSetters<TContextData> {
+    setCounter(counter: CollectionCounter<TContextData>): CollectionCallbackSetters<TContextData>;
+    setFirstCursor(cursor: CollectionCursor<TContextData>): CollectionCallbackSetters<TContextData>;
+    setLastCursor(cursor: CollectionCursor<TContextData>): CollectionCallbackSetters<TContextData>;
+}
+/**
+ * Registry for inbox listeners for different activity types.
+ */
+export interface InboxListenerSetter<TContextData> {
+    /**
+     * Registers a listener for a specific incoming activity type.
+     *
+     * @param type A subclass of {@link Activity} to listen to.
+     * @param listener A callback to handle an incoming activity.
+     * @returns The setters object so that settings can be chained.
+     */
+    on<TActivity extends Activity>(type: new (...args: any[]) => TActivity, listener: InboxListener<TContextData, TActivity>): InboxListenerSetter<TContextData>;
+    /**
+     * Registers an error handler for inbox listeners.  Any exceptions thrown
+     * from the listeners are caught and passed to this handler.
+     *
+     * @param handler A callback to handle an error.
+     * @returns The setters object so that settings can be chained.
+     */
+    onError(handler: InboxErrorHandler<TContextData>): InboxListenerSetter<TContextData>;
+}
+//# sourceMappingURL=middleware.d.ts.map

package/esm/federation/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/federation/middleware.ts"],"names":[],"mappings":"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"}