@fedify/fedify 0.5.0-dev.88

package/esm/federation/middleware.js

@@ -0,0 +1,626 @@
+import * as dntShim from "../_dnt.shims.js";
+import { Temporal } from "@js-temporal/polyfill";
+import { exportJwk, importJwk, validateCryptoKey } from "../httpsig/key.js";
+import { handleNodeInfo, handleNodeInfoJrd } from "../nodeinfo/handler.js";
+import { fetchDocumentLoader, getAuthenticatedDocumentLoader, kvCache, } from "../runtime/docloader.js";
+import { Activity, CryptographicKey } from "../vocab/mod.js";
+import { handleWebFinger } from "../webfinger/handler.js";
+import { handleActor, handleCollection, handleInbox, } from "./handler.js";
+import { Router, RouterError } from "./router.js";
+import { extractInboxes, sendActivity } from "./send.js";
+/**
+ * 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 class Federation {
+    #kv;
+    #kvPrefixes;
+    #queue;
+    #router;
+    #nodeInfoDispatcher;
+    #actorCallbacks;
+    #outboxCallbacks;
+    #followingCallbacks;
+    #followersCallbacks;
+    #inboxListeners;
+    #inboxErrorHandler;
+    #documentLoader;
+    #authenticatedDocumentLoaderFactory;
+    #treatHttps;
+    #backoffSchedule;
+    /**
+     * Create a new {@link Federation} instance.
+     * @param parameters Parameters for initializing the instance.
+     */
+    constructor({ kv, kvPrefixes, queue, documentLoader, authenticatedDocumentLoaderFactory, treatHttps, backoffSchedule, }) {
+        this.#kv = kv;
+        this.#kvPrefixes = {
+            ...({
+                activityIdempotence: ["_fedify", "activityIdempotence"],
+                remoteDocument: ["_fedify", "remoteDocument"],
+            }),
+            ...(kvPrefixes ?? {}),
+        };
+        this.#queue = queue;
+        this.#router = new Router();
+        this.#router.add("/.well-known/webfinger", "webfinger");
+        this.#router.add("/.well-known/nodeinfo", "nodeInfoJrd");
+        this.#inboxListeners = new Map();
+        this.#documentLoader = documentLoader ?? kvCache({
+            loader: fetchDocumentLoader,
+            kv: kv,
+            prefix: this.#kvPrefixes.remoteDocument,
+        });
+        this.#authenticatedDocumentLoaderFactory =
+            authenticatedDocumentLoaderFactory ??
+                getAuthenticatedDocumentLoader;
+        this.#treatHttps = treatHttps ?? false;
+        if (backoffSchedule != null) {
+            // TODO: Deno KV Queue's backoff schedule is too limited for our needs.
+            //       We should manually implement our own backoff retrial mechanism.
+            //       Fortunately, Deno KV Queue's delay option allows up to 30 days.
+            //       We can use that to implement our own backoff schedule.
+            if (backoffSchedule.length > 5) {
+                throw new Error("Backoff schedule must have at most 5 entries.");
+            }
+            const hour = Temporal.Duration.from({ hours: 1 });
+            if (backoffSchedule.some((d) => Temporal.Duration.compare(d, hour) > 0)) {
+                throw new Error("Backoff schedule must not exceed 1 hour.");
+            }
+        }
+        this.#backoffSchedule = backoffSchedule ?? [
+            3000,
+            15000,
+            60000,
+            15 * 60000,
+            60 * 60000,
+        ].map((ms) => Temporal.Duration.from({ milliseconds: ms }));
+        queue?.listen(this.#listenQueue.bind(this));
+    }
+    async #listenQueue(message) {
+        try {
+            await sendActivity({
+                keyId: new URL(message.keyId),
+                privateKey: await importJwk(message.privateKey, "private"),
+                activity: await Activity.fromJsonLd(message.activity, {
+                    documentLoader: this.#documentLoader,
+                }),
+                inbox: new URL(message.inbox),
+                documentLoader: this.#documentLoader,
+            });
+        }
+        catch (_) {
+            if (message.trial < this.#backoffSchedule.length) {
+                this.#queue?.enqueue({
+                    ...message,
+                    trial: message.trial + 1,
+                }, { delay: this.#backoffSchedule[message.trial] });
+            }
+        }
+    }
+    createContext(urlOrRequest, contextData) {
+        const request = urlOrRequest instanceof Request ? urlOrRequest : null;
+        const url = urlOrRequest instanceof URL
+            ? new URL(urlOrRequest)
+            : new URL(urlOrRequest.url);
+        if (request == null) {
+            url.pathname = "/";
+            url.hash = "";
+            url.search = "";
+        }
+        if (this.#treatHttps)
+            url.protocol = "https:";
+        const getKeyPairFromHandle = async (handle) => {
+            if (this.#actorCallbacks?.keyPairDispatcher == null) {
+                throw new Error("No actor key pair dispatcher registered.");
+            }
+            let keyPair = this.#actorCallbacks?.keyPairDispatcher(contextData, handle);
+            if (keyPair instanceof Promise)
+                keyPair = await keyPair;
+            if (keyPair == null) {
+                throw new Error(`No key pair found for actor ${JSON.stringify(handle)}`);
+            }
+            return {
+                keyId: new URL(`${context.getActorUri(handle)}#main-key`),
+                privateKey: keyPair.privateKey,
+            };
+        };
+        const getAuthenticatedDocumentLoader = this.#authenticatedDocumentLoaderFactory;
+        function getDocumentLoader(identity) {
+            if ("handle" in identity) {
+                const keyPair = getKeyPairFromHandle(identity.handle);
+                return keyPair.then((pair) => getAuthenticatedDocumentLoader(pair));
+            }
+            return getAuthenticatedDocumentLoader(identity);
+        }
+        const context = {
+            data: contextData,
+            documentLoader: this.#documentLoader,
+            getNodeInfoUri: () => {
+                const path = this.#router.build("nodeInfo", {});
+                if (path == null) {
+                    throw new RouterError("No NodeInfo dispatcher registered.");
+                }
+                return new URL(path, url);
+            },
+            getActorUri: (handle) => {
+                const path = this.#router.build("actor", { handle });
+                if (path == null) {
+                    throw new RouterError("No actor dispatcher registered.");
+                }
+                return new URL(path, url);
+            },
+            getOutboxUri: (handle) => {
+                const path = this.#router.build("outbox", { handle });
+                if (path == null) {
+                    throw new RouterError("No outbox dispatcher registered.");
+                }
+                return new URL(path, url);
+            },
+            getInboxUri: (handle) => {
+                if (handle == null) {
+                    const path = this.#router.build("sharedInbox", {});
+                    if (path == null) {
+                        throw new RouterError("No shared inbox path registered.");
+                    }
+                    return new URL(path, url);
+                }
+                const path = this.#router.build("inbox", { handle });
+                if (path == null) {
+                    throw new RouterError("No inbox path registered.");
+                }
+                return new URL(path, url);
+            },
+            getFollowingUri: (handle) => {
+                const path = this.#router.build("following", { handle });
+                if (path == null) {
+                    throw new RouterError("No following collection path registered.");
+                }
+                return new URL(path, url);
+            },
+            getFollowersUri: (handle) => {
+                const path = this.#router.build("followers", { handle });
+                if (path == null) {
+                    throw new RouterError("No followers collection path registered.");
+                }
+                return new URL(path, url);
+            },
+            getHandleFromActorUri: (actorUri) => {
+                if (actorUri.origin !== url.origin)
+                    return null;
+                const route = this.#router.route(actorUri.pathname);
+                if (route?.name !== "actor")
+                    return null;
+                return route.values.handle;
+            },
+            getActorKey: async (handle) => {
+                let keyPair = this.#actorCallbacks?.keyPairDispatcher?.(contextData, handle);
+                if (keyPair instanceof Promise)
+                    keyPair = await keyPair;
+                if (keyPair == null)
+                    return null;
+                return new CryptographicKey({
+                    id: new URL(`${context.getActorUri(handle)}#main-key`),
+                    owner: context.getActorUri(handle),
+                    publicKey: keyPair.publicKey,
+                });
+            },
+            getDocumentLoader,
+            sendActivity: async (sender, recipients, activity, options = {}) => {
+                const senderPair = "handle" in sender
+                    ? await getKeyPairFromHandle(sender.handle)
+                    : sender;
+                return await this.sendActivity(senderPair, recipients, activity, options);
+            },
+        };
+        if (request == null)
+            return context;
+        const reqCtx = {
+            ...context,
+            request,
+            url,
+        };
+        return reqCtx;
+    }
+    /**
+     * 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, dispatcher) {
+        if (this.#router.has("nodeInfo")) {
+            throw new RouterError("NodeInfo dispatcher already set.");
+        }
+        const variables = this.#router.add(path, "nodeInfo");
+        if (variables.size !== 0) {
+            throw new RouterError("Path for NodeInfo dispatcher must have no variables.");
+        }
+        this.#nodeInfoDispatcher = dispatcher;
+    }
+    /**
+     * 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, dispatcher) {
+        if (this.#router.has("actor")) {
+            throw new RouterError("Actor dispatcher already set.");
+        }
+        const variables = this.#router.add(path, "actor");
+        if (variables.size !== 1 || !variables.has("handle")) {
+            throw new RouterError("Path for actor dispatcher must have one variable: {handle}");
+        }
+        const callbacks = { dispatcher };
+        this.#actorCallbacks = callbacks;
+        const setters = {
+            setKeyPairDispatcher: (dispatcher) => {
+                callbacks.keyPairDispatcher = dispatcher;
+                return setters;
+            },
+        };
+        return setters;
+    }
+    /**
+     * 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, dispatcher) {
+        if (this.#router.has("outbox")) {
+            throw new RouterError("Outbox dispatcher already set.");
+        }
+        const variables = this.#router.add(path, "outbox");
+        if (variables.size !== 1 || !variables.has("handle")) {
+            throw new RouterError("Path for outbox dispatcher must have one variable: {handle}");
+        }
+        const callbacks = {
+            dispatcher,
+        };
+        this.#outboxCallbacks = callbacks;
+        const setters = {
+            setCounter(counter) {
+                callbacks.counter = counter;
+                return setters;
+            },
+            setFirstCursor(cursor) {
+                callbacks.firstCursor = cursor;
+                return setters;
+            },
+            setLastCursor(cursor) {
+                callbacks.lastCursor = cursor;
+                return setters;
+            },
+        };
+        return setters;
+    }
+    /**
+     * 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, dispatcher) {
+        if (this.#router.has("following")) {
+            throw new RouterError("Following collection dispatcher already set.");
+        }
+        const variables = this.#router.add(path, "following");
+        if (variables.size !== 1 || !variables.has("handle")) {
+            throw new RouterError("Path for following collection dispatcher must have one variable: {handle}");
+        }
+        const callbacks = {
+            dispatcher,
+        };
+        this.#followingCallbacks = callbacks;
+        const setters = {
+            setCounter(counter) {
+                callbacks.counter = counter;
+                return setters;
+            },
+            setFirstCursor(cursor) {
+                callbacks.firstCursor = cursor;
+                return setters;
+            },
+            setLastCursor(cursor) {
+                callbacks.lastCursor = cursor;
+                return setters;
+            },
+        };
+        return setters;
+    }
+    /**
+     * 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, dispatcher) {
+        if (this.#router.has("followers")) {
+            throw new RouterError("Followers collection dispatcher already set.");
+        }
+        const variables = this.#router.add(path, "followers");
+        if (variables.size !== 1 || !variables.has("handle")) {
+            throw new RouterError("Path for followers collection dispatcher must have one variable: {handle}");
+        }
+        const callbacks = {
+            dispatcher,
+        };
+        this.#followersCallbacks = callbacks;
+        const setters = {
+            setCounter(counter) {
+                callbacks.counter = counter;
+                return setters;
+            },
+            setFirstCursor(cursor) {
+                callbacks.firstCursor = cursor;
+                return setters;
+            },
+            setLastCursor(cursor) {
+                callbacks.lastCursor = cursor;
+                return setters;
+            },
+        };
+        return setters;
+    }
+    /**
+     * 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, sharedInboxPath) {
+        if (this.#router.has("inbox")) {
+            throw new RouterError("Inbox already set.");
+        }
+        const variables = this.#router.add(inboxPath, "inbox");
+        if (variables.size !== 1 || !variables.has("handle")) {
+            throw new RouterError("Path for inbox must have one variable: {handle}");
+        }
+        if (sharedInboxPath != null) {
+            const siVars = this.#router.add(sharedInboxPath, "sharedInbox");
+            if (siVars.size !== 0) {
+                throw new RouterError("Path for shared inbox must have no variables.");
+            }
+        }
+        const listeners = this.#inboxListeners;
+        const setter = {
+            on(
+            // deno-lint-ignore no-explicit-any
+            type, listener) {
+                if (listeners.has(type)) {
+                    throw new TypeError("Listener already set for this type.");
+                }
+                listeners.set(type, listener);
+                return setter;
+            },
+            onError: (handler) => {
+                this.#inboxErrorHandler = handler;
+                return setter;
+            },
+        };
+        return setter;
+    }
+    /**
+     * 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.
+     */
+    async sendActivity({ keyId, privateKey }, recipients, activity, { preferSharedInbox, immediate } = {}) {
+        if (activity.id == null) {
+            activity = activity.clone({
+                id: new URL(`urn:uuid:${dntShim.crypto.randomUUID()}`),
+            });
+        }
+        validateCryptoKey(privateKey, "private");
+        const inboxes = extractInboxes({
+            recipients: Array.isArray(recipients) ? recipients : [recipients],
+            preferSharedInbox,
+        });
+        if (immediate || this.#queue == null) {
+            const promises = [];
+            for (const inbox of inboxes) {
+                promises.push(sendActivity({
+                    keyId,
+                    privateKey,
+                    activity,
+                    inbox,
+                    documentLoader: this.#documentLoader,
+                }));
+            }
+            await Promise.all(promises);
+            return;
+        }
+        const privateKeyJwk = await exportJwk(privateKey);
+        const activityJson = await activity.toJsonLd({ expand: true });
+        for (const inbox of inboxes) {
+            const message = {
+                type: "outbox",
+                keyId: keyId.href,
+                privateKey: privateKeyJwk,
+                activity: activityJson,
+                inbox: inbox.href,
+                trial: 0,
+            };
+            this.#queue.enqueue(message);
+        }
+    }
+    /**
+     * 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.
+     */
+    async handle(request, { onNotFound, onNotAcceptable, contextData, }) {
+        onNotFound ??= notFound;
+        onNotAcceptable ??= notAcceptable;
+        const url = new URL(request.url);
+        const route = this.#router.route(url.pathname);
+        if (route == null) {
+            const response = onNotFound(request);
+            return response instanceof Promise ? await response : response;
+        }
+        let context = this.createContext(request, contextData);
+        switch (route.name) {
+            case "webfinger":
+                return await handleWebFinger(request, {
+                    context,
+                    actorDispatcher: this.#actorCallbacks?.dispatcher,
+                    onNotFound,
+                });
+            case "nodeInfoJrd":
+                return await handleNodeInfoJrd(request, context);
+            case "nodeInfo":
+                return await handleNodeInfo(request, {
+                    context,
+                    nodeInfoDispatcher: this.#nodeInfoDispatcher,
+                });
+            case "actor":
+                return await handleActor(request, {
+                    handle: route.values.handle,
+                    context,
+                    actorDispatcher: this.#actorCallbacks?.dispatcher,
+                    onNotFound,
+                    onNotAcceptable,
+                });
+            case "outbox":
+                return await handleCollection(request, {
+                    handle: route.values.handle,
+                    context,
+                    collectionCallbacks: this.#outboxCallbacks,
+                    onNotFound,
+                    onNotAcceptable,
+                });
+            case "inbox":
+                context = {
+                    ...context,
+                    documentLoader: await context.getDocumentLoader({
+                        handle: route.values.handle,
+                    }),
+                };
+            // falls through
+            case "sharedInbox":
+                return await handleInbox(request, {
+                    handle: route.values.handle ?? null,
+                    context,
+                    kv: this.#kv,
+                    kvPrefix: this.#kvPrefixes.activityIdempotence,
+                    actorDispatcher: this.#actorCallbacks?.dispatcher,
+                    inboxListeners: this.#inboxListeners,
+                    inboxErrorHandler: this.#inboxErrorHandler,
+                    onNotFound,
+                });
+            case "following":
+                return await handleCollection(request, {
+                    handle: route.values.handle,
+                    context,
+                    collectionCallbacks: this.#followingCallbacks,
+                    onNotFound,
+                    onNotAcceptable,
+                });
+            case "followers":
+                return await handleCollection(request, {
+                    handle: route.values.handle,
+                    context,
+                    collectionCallbacks: this.#followersCallbacks,
+                    onNotFound,
+                    onNotAcceptable,
+                });
+            default: {
+                const response = onNotFound(request);
+                return response instanceof Promise ? await response : response;
+            }
+        }
+    }
+}
+function notFound(_request) {
+    return new Response("Not Found", { status: 404 });
+}
+function notAcceptable(_request) {
+    return new Response("Not Acceptable", { status: 406 });
+}

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.test.d.ts","sourceRoot":"","sources":["../../src/federation/middleware.test.ts"],"names":[],"mappings":"AAAA,OAAO,2BAA2B,CAAC"}

package/esm/federation/mod.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The federated server framework.
+ *
+ * @module
+ */
+export * from "./callback.js";
+export * from "./collection.js";
+export * from "./context.js";
+export { respondWithObject, respondWithObjectIfAcceptable, type RespondWithObjectOptions, } from "./handler.js";
+export * from "./kv.js";
+export * from "./middleware.js";
+export * from "./mq.js";
+export * from "./router.js";
+//# sourceMappingURL=mod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/federation/mod.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,iBAAiB,EACjB,6BAA6B,EAC7B,KAAK,wBAAwB,GAC9B,MAAM,cAAc,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC"}

package/esm/federation/mod.js

@@ -0,0 +1,13 @@
+/**
+ * The federated server framework.
+ *
+ * @module
+ */
+export * from "./callback.js";
+export * from "./collection.js";
+export * from "./context.js";
+export { respondWithObject, respondWithObjectIfAcceptable, } from "./handler.js";
+export * from "./kv.js";
+export * from "./middleware.js";
+export * from "./mq.js";
+export * from "./router.js";