@fedify/fedify/types/federation/federation.d.ts

An ActivityPub server framework

import type { Actor, Recipient } from "../vocab/actor.js";
import type { Activity, Hashtag, Object } from "../vocab/vocab.js";
import type { ActorAliasMapper, ActorDispatcher, ActorHandleMapper, ActorKeyPairsDispatcher, AuthorizePredicate, CollectionCounter, CollectionCursor, CollectionDispatcher, InboxErrorHandler, InboxListener, NodeInfoDispatcher, ObjectAuthorizePredicate, ObjectDispatcher, SharedInboxKeyDispatcher } from "./callback.js";
import type { Context, RequestContext } from "./context.js";
/**
 * Options for {@link Federation.startQueue} method.
 * @since 1.0.0
 */
export interface FederationStartQueueOptions {
    /**
     * The signal to abort the task queue.
     */
    signal?: AbortSignal;
    /**
     * Starts the task worker only for the specified queue.  If unspecified,
     * which is the default, the task worker starts for all three queues:
     * inbox, outbox, and fanout.
     * @since 1.3.0
     */
    queue?: "inbox" | "outbox" | "fanout";
}
/**
 * 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.fetch}.
 *
 * @since 0.13.0
 */
export interface Federation<TContextData> {
    /**
     * Manually start the task queue.
     *
     * This method is useful when you set the `manuallyStartQueue` option to
     * `true` in the {@link createFederation} function.
     * @param contextData The context data to pass to the context.
     * @param options Additional options for starting the queue.
     */
    startQueue(contextData: TContextData, options?: FederationStartQueueOptions): Promise<void>;
    /**
     * 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/{identifier}",
     *   async (ctx, identifier) => {
     *     return new Person({
     *       id: ctx.getActorUri(identifier),
     *       // ...
     *     });
     *   }
     * );
     * ```
     *
     * @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: `{identifier}`.
     * @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}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: ActorDispatcher<TContextData>): ActorCallbackSetters<TContextData>;
    /**
     * Registers an object dispatcher.
     *
     * @typeParam TContextData The context data to pass to the {@link Context}.
     * @typeParam TObject The type of object to dispatch.
     * @typeParam TParam The parameter names of the requested URL.
     * @param cls The Activity Vocabulary class of the object to dispatch.
     * @param path The URI path pattern for the object dispatcher.  The syntax is
     *             based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one or more variables.
     * @param dispatcher An object dispatcher callback to register.
     */
    setObjectDispatcher<TObject extends Object, TParam extends string>(cls: (new (...args: any[]) => TObject) & {
        typeId: URL;
    }, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
    /**
     * Registers an object dispatcher.
     *
     * @typeParam TContextData The context data to pass to the {@link Context}.
     * @typeParam TObject The type of object to dispatch.
     * @typeParam TParam The parameter names of the requested URL.
     * @param cls The Activity Vocabulary class of the object to dispatch.
     * @param path The URI path pattern for the object dispatcher.  The syntax is
     *             based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one or more variables.
     * @param dispatcher An object dispatcher callback to register.
     */
    setObjectDispatcher<TObject extends Object, TParam extends string>(cls: (new (...args: any[]) => TObject) & {
        typeId: URL;
    }, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
    /**
     * Registers an object dispatcher.
     *
     * @typeParam TContextData The context data to pass to the {@link Context}.
     * @typeParam TObject The type of object to dispatch.
     * @typeParam TParam The parameter names of the requested URL.
     * @param cls The Activity Vocabulary class of the object to dispatch.
     * @param path The URI path pattern for the object dispatcher.  The syntax is
     *             based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one or more variables.
     * @param dispatcher An object dispatcher callback to register.
     */
    setObjectDispatcher<TObject extends Object, TParam extends string>(cls: (new (...args: any[]) => TObject) & {
        typeId: URL;
    }, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
    /**
     * Registers an object dispatcher.
     *
     * @typeParam TContextData The context data to pass to the {@link Context}.
     * @typeParam TObject The type of object to dispatch.
     * @typeParam TParam The parameter names of the requested URL.
     * @param cls The Activity Vocabulary class of the object to dispatch.
     * @param path The URI path pattern for the object dispatcher.  The syntax is
     *             based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one or more variables.
     * @param dispatcher An object dispatcher callback to register.
     */
    setObjectDispatcher<TObject extends Object, TParam extends string>(cls: (new (...args: any[]) => TObject) & {
        typeId: URL;
    }, path: `${string}{${TParam}}${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
    /**
     * Registers an object dispatcher.
     *
     * @typeParam TContextData The context data to pass to the {@link Context}.
     * @typeParam TObject The type of object to dispatch.
     * @typeParam TParam The parameter names of the requested URL.
     * @param cls The Activity Vocabulary class of the object to dispatch.
     * @param path The URI path pattern for the object dispatcher.  The syntax is
     *             based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one or more variables.
     * @param dispatcher An object dispatcher callback to register.
     */
    setObjectDispatcher<TObject extends Object, TParam extends string>(cls: (new (...args: any[]) => TObject) & {
        typeId: URL;
    }, path: `${string}{${TParam}}${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
    /**
     * Registers an object dispatcher.
     *
     * @typeParam TContextData The context data to pass to the {@link Context}.
     * @typeParam TObject The type of object to dispatch.
     * @typeParam TParam The parameter names of the requested URL.
     * @param cls The Activity Vocabulary class of the object to dispatch.
     * @param path The URI path pattern for the object dispatcher.  The syntax is
     *             based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one or more variables.
     * @param dispatcher An object dispatcher callback to register.
     */
    setObjectDispatcher<TObject extends Object, TParam extends string>(cls: (new (...args: any[]) => TObject) & {
        typeId: URL;
    }, path: `${string}{${TParam}}${string}`, dispatcher: ObjectDispatcher<TContextData, TObject, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
    /**
     * Registers an inbox dispatcher.
     *
     * @param path The URI path pattern for the inbox dispatcher.  The syntax is
     *             based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one variable: `{identifier}`, and must match
     *             the inbox listener path.
     * @param dispatcher An inbox dispatcher callback to register.
     * @throws {@link RouterError} Thrown if the path pattern is invalid.
     */
    setInboxDispatcher(path: `${string}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: CollectionDispatcher<Activity, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
    /**
     * Registers an outbox dispatcher.
     *
     * @example
     * ``` typescript
     * federation.setOutboxDispatcher(
     *   "/users/{identifier}/outbox",
     *   async (ctx, identifier, 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: `{identifier}`.
     * @param dispatcher An outbox dispatcher callback to register.
     * @throws {@link RouterError} Thrown if the path pattern is invalid.
     */
    setOutboxDispatcher(path: `${string}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: CollectionDispatcher<Activity, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
    /**
     * 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: `{identifier}`.
     * @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}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: CollectionDispatcher<Actor | URL, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
    /**
     * 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: `{identifier}`.
     * @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}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: CollectionDispatcher<Recipient, Context<TContextData>, TContextData, URL>): CollectionCallbackSetters<Context<TContextData>, TContextData, URL>;
    /**
     * Registers a liked collection dispatcher.
     * @param path The URI path pattern for the liked collection.  The syntax
     *             is based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one variable: `{identifier}`.
     * @param dispatcher A liked collection callback to register.
     * @returns An object with methods to set other liked collection
     *          callbacks.
     * @throws {@link RouterError} Thrown if the path pattern is invalid.
     */
    setLikedDispatcher(path: `${string}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: CollectionDispatcher<Object | URL, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
    /**
     * Registers a featured collection dispatcher.
     * @param path The URI path pattern for the featured collection.  The syntax
     *             is based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one variable: `{identifier}`.
     * @param dispatcher A featured collection callback to register.
     * @returns An object with methods to set other featured collection
     *          callbacks.
     * @throws {@link RouterError} Thrown if the path pattern is invalid.
     */
    setFeaturedDispatcher(path: `${string}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: CollectionDispatcher<Object, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
    /**
     * Registers a featured tags collection dispatcher.
     * @param path The URI path pattern for the featured tags collection.
     *             The syntax is based on URI Template
     *             ([RFC 6570](https://tools.ietf.org/html/rfc6570)).  The path
     *             must have one variable: `{identifier}`.
     * @param dispatcher A featured tags collection callback to register.
     * @returns An object with methods to set other featured tags collection
     *          callbacks.
     * @throws {@link RouterError} Thrown if the path pattern is invalid.
     */
    setFeaturedTagsDispatcher(path: `${string}{identifier}${string}` | `${string}{handle}${string}`, dispatcher: CollectionDispatcher<Hashtag, RequestContext<TContextData>, TContextData, void>): CollectionCallbackSetters<RequestContext<TContextData>, TContextData, void>;
    /**
     * Assigns the URL path for the inbox and starts setting inbox listeners.
     *
     * @example
     * ``` typescript
     * federation
     *   .setInboxListeners("/users/{identifier}/inbox", "/inbox")
     *   .on(Follow, async (ctx, follow) => {
     *     const from = await follow.getActor(ctx);
     *     if (!isActor(from)) return;
     *     // ...
     *   })
     *   .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: `{identifier}`, and must
     *                  match the inbox dispatcher path.
     * @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}{identifier}${string}` | `${string}{handle}${string}`, sharedInboxPath?: string): InboxListenerSetters<TContextData>;
    /**
     * 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.
     */
    fetch(request: Request, options: FederationFetchOptions<TContextData>): Promise<Response>;
}
/**
 * Additional settings for the actor dispatcher.
 *
 * ``` typescript
 * const federation = createFederation<void>({ ... });
 * federation
 *   .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
 *     // ...
 *   })
 *   .setKeyPairsDispatcher(async (ctxData, identifier) => {
 *     // ...
 *   });
 * ```
 */
export interface ActorCallbackSetters<TContextData> {
    /**
     * Sets the key pairs dispatcher for actors.
     * @param dispatcher A callback that returns the key pairs for an actor.
     * @returns The setters object so that settings can be chained.
     * @since 0.10.0
     */
    setKeyPairsDispatcher(dispatcher: ActorKeyPairsDispatcher<TContextData>): ActorCallbackSetters<TContextData>;
    /**
     * Sets the callback function that maps a WebFinger username to
     * the corresponding actor's identifier.  If it's omitted, the identifier
     * is assumed to be the same as the WebFinger username, which makes your
     * actors have the immutable handles.  If you want to let your actors change
     * their fediverse handles, you should set this dispatcher.
     * @param mapper A callback that maps a WebFinger username to
     *               the corresponding actor's identifier.
     * @returns The setters object so that settings can be chained.
     * @since 0.15.0
     */
    mapHandle(mapper: ActorHandleMapper<TContextData>): ActorCallbackSetters<TContextData>;
    /**
     * Sets the callback function that maps a WebFinger query to the corresponding
     * actor's identifier or username.  If it's omitted, the WebFinger handler
     * only supports the actor URIs and `acct:` URIs.  If you want to support
     * other queries, you should set this dispatcher.
     * @param mapper A callback that maps a WebFinger query to the corresponding
     *               actor's identifier or username.
     * @returns The setters object so that settings can be chained.
     * @since 1.4.0
     */
    mapAlias(mapper: ActorAliasMapper<TContextData>): ActorCallbackSetters<TContextData>;
    /**
     * Specifies the conditions under which requests are authorized.
     * @param predicate A callback that returns whether a request is authorized.
     * @returns The setters object so that settings can be chained.
     * @since 0.7.0
     */
    authorize(predicate: AuthorizePredicate<TContextData>): ActorCallbackSetters<TContextData>;
}
/**
 * Additional settings for an object dispatcher.
 */
export interface ObjectCallbackSetters<TContextData, TObject extends Object, TParam extends string> {
    /**
     * Specifies the conditions under which requests are authorized.
     * @param predicate A callback that returns whether a request is authorized.
     * @returns The setters object so that settings can be chained.
     * @since 0.7.0
     */
    authorize(predicate: ObjectAuthorizePredicate<TContextData, TParam>): ObjectCallbackSetters<TContextData, TObject, TParam>;
}
/**
 * Additional settings for a collection dispatcher.
 *
 * @typeParam TContext The type of the context.  {@link Context} or
 *                     {@link RequestContext}.
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @typeParam TFilter The type of filter for the collection.
 */
export interface CollectionCallbackSetters<TContext extends Context<TContextData>, TContextData, TFilter> {
    /**
     * Sets the counter for the collection.
     * @param counter A callback that returns the number of items in the collection.
     * @returns The setters object so that settings can be chained.
     */
    setCounter(counter: CollectionCounter<TContextData, TFilter>): CollectionCallbackSetters<TContext, TContextData, TFilter>;
    /**
     * Sets the first cursor for the collection.
     * @param cursor The cursor for the first item in the collection.
     * @returns The setters object so that settings can be chained.
     */
    setFirstCursor(cursor: CollectionCursor<TContext, TContextData, TFilter>): CollectionCallbackSetters<TContext, TContextData, TFilter>;
    /**
     * Sets the last cursor for the collection.
     * @param cursor The cursor for the last item in the collection.
     * @returns The setters object so that settings can be chained.
     */
    setLastCursor(cursor: CollectionCursor<TContext, TContextData, TFilter>): CollectionCallbackSetters<TContext, TContextData, TFilter>;
    /**
     * Specifies the conditions under which requests are authorized.
     * @param predicate A callback that returns whether a request is authorized.
     * @returns The setters object so that settings can be chained.
     * @since 0.7.0
     */
    authorize(predicate: AuthorizePredicate<TContextData>): CollectionCallbackSetters<TContext, TContextData, TFilter>;
}
/**
 * Registry for inbox listeners for different activity types.
 */
export interface InboxListenerSetters<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>): InboxListenerSetters<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>): InboxListenerSetters<TContextData>;
    /**
     * Configures a callback to dispatch the key pair for the authenticated
     * document loader of the {@link Context} passed to the shared inbox listener.
     *
     * @param dispatcher A callback to dispatch the key pair for the authenticated
     *                   document loader.
     * @returns The setters object so that settings can be chained.
     * @since 0.11.0
     */
    setSharedKeyDispatcher(dispatcher: SharedInboxKeyDispatcher<TContextData>): InboxListenerSetters<TContextData>;
}
/**
 * Parameters of {@link Federation.fetch} method.
 *
 * @typeParam TContextData The context data to pass to the {@link Context}.
 * @since 0.6.0
 */
export interface FederationFetchOptions<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>;
    /**
     * A callback to handle a request when the request is unauthorized.
     * If not provided, a 401 response is returned.
     * @param request The request object.
     * @returns The response to the request.
     * @since 0.7.0
     */
    onUnauthorized?: (request: Request) => Response | Promise<Response>;
}
//# sourceMappingURL=federation.d.ts.map