Merge pull request #680 from dahlia/issue-644-actor-tombstone

Support tombstones in actor dispatchers and request contexts

Author: dahlia

CHANGES.md

@@ -10,11 +10,23 @@ To be released.
 
 ### @fedify/fedify
 
+ -  Allowed actor dispatchers to return `Tombstone` for deleted accounts.
+    Fedify now serves those actor URIs as `410 Gone` with the serialized
+    tombstone body, and the corresponding WebFinger lookups also return
+    `410 Gone` instead of pretending the account was never handled.
+    Added a `RequestContext.getActor()` overload that can return those
+    tombstones to application code when called with
+    `{ tombstone: "passthrough" }`.
+    [[#644], [#680]]
+
  -  Added `DoubleKnockOptions.maxRedirection` to configure the maximum number
     of redirects followed by `doubleKnock()`.
     `getAuthenticatedDocumentLoader()` now also respects
     `GetAuthenticatedDocumentLoaderOptions.maxRedirection`.
 
+[#644]: https://github.com/fedify-dev/fedify/issues/644
+[#680]: https://github.com/fedify-dev/fedify/pull/680
+
 ### @fedify/vocab-runtime
 
  -  Added `DocumentLoaderFactoryOptions.maxRedirection` to configure the

docs/manual/actor.md

@@ -14,8 +14,8 @@ by its identifier.  Since the actor dispatcher is the most significant part of
 Fedify, it is the first thing you need to do to make Fedify work.
 
 An actor dispatcher is a callback function that takes a `Context` object and
-an identifier, and returns an actor object.  The actor object can be one of
-the following:
+an identifier, and returns an actor object, a `Tombstone`, or `null`.
+Live actor objects can be one of the following:
 
  -  `Application`
  -  `Group`
@@ -25,7 +25,7 @@ the following:
 
 The below example shows how to register an actor dispatcher:
 
-~~~~ typescript{7-15} twoslash
+~~~~ typescript{8-16} twoslash
 // @noErrors: 2451 2345
 import type { Federation } from "@fedify/fedify";
 const federation = null as unknown as Federation<void>;
@@ -54,6 +54,32 @@ In the above example, the `~Federatable.setActorDispatcher()` method registers
 an actor dispatcher for the `/users/{identifier}` path.  This pattern syntax
 follows the [URI Template] specification.
 
+If the actor exists but should be represented as deleted, return a `Tombstone`
+instead of `null`:
+
+~~~~ typescript twoslash
+// @noErrors: 2345
+import { type Federation } from "@fedify/fedify";
+import { Tombstone } from "@fedify/vocab";
+const federation = null as unknown as Federation<void>;
+const deletedAt = Temporal.Instant.from("2024-01-15T00:00:00Z");
+// ---cut-before---
+federation.setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
+  if (identifier !== "alice") return null;
+  return new Tombstone({
+    id: ctx.getActorUri(identifier),
+    deleted: deletedAt,
+  });
+});
+~~~~
+
+When an actor dispatcher returns a `Tombstone`, Fedify responds from the actor
+endpoint with `410 Gone` and the serialized tombstone body.  WebFinger for the
+same account also responds with `410 Gone`.
+
+Use `null` only when the identifier is not handled at all and the request
+should fall through to the next middleware or `onNotFound` handler.
+
 > [!TIP]
 > By registering the actor dispatcher, `Federation.fetch()` automatically
 > deals with [WebFinger] requests for the actor.

docs/manual/context.md

@@ -214,6 +214,26 @@ if (actor != null) {
 }
 ~~~~
 
+By default, `RequestContext.getActor()` suppresses tombstoned actors and returns
+`null` for them.  If you need to distinguish a deleted actor from a missing
+identifier, pass `{ tombstone: "passthrough" }`:
+
+~~~~ typescript twoslash
+import { type Federation } from "@fedify/fedify";
+import { Tombstone } from "@fedify/vocab";
+const federation = null as unknown as Federation<void>;
+const request = new Request("");
+const identifier: string = "";
+// ---cut-before---
+const ctx = federation.createContext(request, undefined);
+const actor = await ctx.getActor(identifier, {
+  tombstone: "passthrough",
+});
+if (actor instanceof Tombstone) {
+  console.log(`${identifier} was deleted at ${actor.deleted}`);
+}
+~~~~
+
 > [!NOTE]
 > The `RequestContext.getActor()` method is only available when the actor
 > dispatcher is registered to the `Federation` object.  If the actor dispatcher

docs/manual/webfinger.md

@@ -198,6 +198,10 @@ The WebFinger links dispatcher receives two parameters:
 > route.
 
 > [!NOTE]
+> If your actor dispatcher returns a `Tombstone` for a deleted account,
+> Fedify responds to the corresponding WebFinger lookup with `410 Gone`
+> instead of a JRD document.  This matches the actor endpoint behavior,
+> which also returns `410 Gone` for the tombstoned actor URI.
 > Before the introduction of `~Federatable.setWebFingerLinksDispatcher()` in
 > Fedify 1.9.0, WebFinger responses could only be customized through
 > `~Federatable.setActorDispatcher()` by setting the actor's `url` property.

docs/tutorial/basics.md

@@ -471,8 +471,9 @@ In the above code, we use the `~Federatable.setActorDispatcher()` method to set
 an actor dispatcher for the server.  The first argument is the path pattern
 for the actor, and the second argument is a callback function that takes
 a `Context` object and the actor's identifier.  The callback function should
-return an `Actor` object or `null` if the actor is not found.  In this case,
-we return a `Person` object for the actor *me*.
+return an `Actor` object, a `Tombstone` if the account is gone, or `null` if
+the actor is not found.  In this case, we return a `Person` object for the
+actor *me*.
 
 Alright, we have an actor on the server.  Let's see if it works by querying
 WebFinger for the actor.  Run the server by executing the following command:

packages/fedify/src/federation/builder.ts

@@ -6,7 +6,7 @@ import type {
   Object,
   Recipient,
 } from "@fedify/vocab";
-import { getTypeId } from "@fedify/vocab";
+import { getTypeId, Tombstone } from "@fedify/vocab";
 import { getLogger } from "@logtape/logtape";
 import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import type { Tracer } from "@opentelemetry/api";
@@ -265,6 +265,7 @@ export class FederationBuilderImpl<TContextData>
               "Context.getActorUri(identifier).",
           );
         }
+        if (actor instanceof Tombstone) return actor;
         if (
           this.followingCallbacks != null &&
           this.followingCallbacks.dispatcher != null

packages/fedify/src/federation/callback.ts

@@ -1,4 +1,4 @@
-import type { Activity, Actor, Object } from "@fedify/vocab";
+import type { Activity, Actor, Object, Tombstone } from "@fedify/vocab";
 import type { Link } from "@fedify/webfinger";
 import type { VerifyRequestFailureReason } from "../sig/http.ts";
 import type { NodeInfo } from "../nodeinfo/types.ts";
@@ -28,7 +28,7 @@ export type WebFingerLinksDispatcher<TContextData> = (
 ) => readonly Link[] | Promise<readonly Link[]>;
 
 /**
- * A callback that dispatches an {@link Actor} object.
+ * A callback that dispatches an {@link Actor} object or a {@link Tombstone}.
  *
  * @template TContextData The context data to pass to the {@link Context}.
  * @param context The request context.
@@ -37,7 +37,7 @@ export type WebFingerLinksDispatcher<TContextData> = (
 export type ActorDispatcher<TContextData> = (
   context: RequestContext<TContextData>,
   identifier: string,
-) => Actor | null | Promise<Actor | null>;
+) => Actor | Tombstone | null | Promise<Actor | Tombstone | null>;
 
 /**
  * A callback that dispatches key pairs for an actor.

packages/fedify/src/federation/context.ts

@@ -8,6 +8,7 @@ import type {
   Multikey,
   Object,
   Recipient,
+  Tombstone,
   TraverseCollectionOptions,
 } from "@fedify/vocab";
 import type { DocumentLoader } from "@fedify/vocab-runtime";
@@ -437,6 +438,20 @@ export interface Context<TContextData> {
   ): URL;
 }
 
+/**
+ * Options for {@link RequestContext.getActor}.
+ * @since 2.2.0
+ */
+export interface GetActorOptions {
+  /**
+   * Controls how tombstoned actors are returned.
+   *
+   * By default, tombstones are suppressed and returned as `null`.  Set this to
+   * `"passthrough"` to receive a {@link Tombstone} result instead.
+   */
+  readonly tombstone?: "suppress" | "passthrough";
+}
+
 /**
  * A context for a request.
  */
@@ -470,6 +485,54 @@ export interface RequestContext<TContextData> extends Context<TContextData> {
    */
   getActor(identifier: string): Promise<Actor | null>;
 
+  /**
+   * Gets an {@link Actor} object or {@link Tombstone} for the given
+   * identifier.
+   * @param identifier The actor's identifier.
+   * @param options Options for getting the actor.  Set
+   *                `options.tombstone` to `"passthrough"` to receive
+   *                tombstoned actors instead of `null`.
+   * @returns The actor object, a tombstone, or `null` if the actor is not
+   *          found.
+   * @throws {Error} If no actor dispatcher is available.
+   * @since 2.2.0
+   */
+  getActor(
+    identifier: string,
+    options: GetActorOptions & { readonly tombstone: "passthrough" },
+  ): Promise<Actor | Tombstone | null>;
+
+  /**
+   * Gets an {@link Actor} object for the given identifier.
+   * @param identifier The actor's identifier.
+   * @param options Options for getting the actor.
+   * @returns The actor object, or `null` if the actor is not found.
+   *          Tombstoned actors are suppressed unless `options.tombstone` is
+   *          `"passthrough"`.
+   * @throws {Error} If no actor dispatcher is available.
+   * @since 2.2.0
+   */
+  getActor(
+    identifier: string,
+    options: GetActorOptions & { readonly tombstone?: "suppress" | undefined },
+  ): Promise<Actor | null>;
+
+  /**
+   * Gets an {@link Actor} object or {@link Tombstone} for the given
+   * identifier.
+   * @param identifier The actor's identifier.
+   * @param options Options for getting the actor.
+   * @returns The actor object, a tombstone, or `null` if the actor is not
+   *          found.  This broad overload is used when the caller passes an
+   *          options value whose `tombstone` mode is not known statically.
+   * @throws {Error} If no actor dispatcher is available.
+   * @since 2.2.0
+   */
+  getActor(
+    identifier: string,
+    options: GetActorOptions,
+  ): Promise<Actor | Tombstone | null>;
+
   /**
    * Gets an object of the given class with the given values.
    * @param cls The class to instantiate.

packages/fedify/src/federation/federation.ts

@@ -114,7 +114,9 @@ export interface Federatable<TContextData> {
    *             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.
+   * @param dispatcher An actor dispatcher callback to register.  It may return
+   *                   an actor, a `Tombstone`, or `null` if the actor is not
+   *                   found.
    * @returns An object with methods to set other actor dispatcher callbacks.
    * @throws {RouterError} Thrown if the path pattern is invalid.
    */

packages/fedify/src/federation/handler.test.ts

@@ -9,6 +9,7 @@ import {
   Note,
   type Object,
   Person,
+  Tombstone,
 } from "@fedify/vocab";
 import { FetchError } from "@fedify/vocab-runtime";
 import { assert, assertEquals } from "@std/assert";
@@ -68,6 +69,7 @@ const WRAPPER_QUOTE_CONTEXT_TERMS = {
 
 test("handleActor()", async () => {
   const federation = createFederation<void>({ kv: new MemoryKvStore() });
+  const deletedAt = Temporal.Instant.from("2024-01-15T00:00:00Z");
   let context = createRequestContext<void>({
     federation,
     data: undefined,
@@ -83,6 +85,13 @@ test("handleActor()", async () => {
       name: "Someone",
     });
   };
+  const tombstoneDispatcher: ActorDispatcher<void> = (ctx, identifier) => {
+    if (identifier !== "gone") return null;
+    return new Tombstone({
+      id: ctx.getActorUri(identifier),
+      deleted: deletedAt,
+    });
+  };
   let onNotFoundCalled: Request | null = null;
   const onNotFound = (request: Request) => {
     onNotFoundCalled = request;
@@ -294,6 +303,53 @@ test("handleActor()", async () => {
   });
   assertEquals(onNotFoundCalled, null);
   assertEquals(onUnauthorizedCalled, null);
+
+  onNotFoundCalled = null;
+  response = await handleActor(
+    context.request,
+    {
+      context,
+      identifier: "gone",
+      actorDispatcher: tombstoneDispatcher,
+      authorizePredicate: () => false,
+      onNotFound,
+      onUnauthorized,
+    },
+  );
+  assertEquals(response.status, 401);
+  assertEquals(onNotFoundCalled, null);
+  assertEquals(onUnauthorizedCalled, context.request);
+
+  onUnauthorizedCalled = null;
+  response = await handleActor(
+    context.request,
+    {
+      context,
+      identifier: "gone",
+      actorDispatcher: tombstoneDispatcher,
+      authorizePredicate: () => true,
+      onNotFound,
+      onUnauthorized,
+    },
+  );
+  assertEquals(response.status, 410);
+  assertEquals(
+    response.headers.get("Content-Type"),
+    "application/activity+json",
+  );
+  assertEquals(response.headers.get("Vary"), "Accept");
+  assertEquals(await response.json(), {
+    "@context": [
+      "https://www.w3.org/ns/activitystreams",
+      "https://w3id.org/security/data-integrity/v1",
+      "https://gotosocial.org/ns",
+    ],
+    id: "https://example.com/users/gone",
+    type: "Tombstone",
+    deleted: "2024-01-15T00:00:00Z",
+  });
+  assertEquals(onNotFoundCalled, null);
+  assertEquals(onUnauthorizedCalled, null);
 });
 
 test("handleObject()", async () => {