Support fixed-path actor dispatchers

Added `mapActorAlias()` method to `ActorCallbackSetters` interface to
support mapping fixed paths to sentinel identifiers for the actor
dispatcher. This enables exposing a single, instance-level actor at a
fixed path (like `/actor` for a relay or `/bot` for a bot) without
leaking the sentinel identifier into the actor's URI.

When an alias is mapped, the router will use it for resolving inbound
requests and `Context.getActorUri()` will use it for constructing
outbound actor URIs.

Fixes #752

Assisted-by: Gemini CLI:gemini-3.1-pro-preview
Assisted-by: Codex:gpt-5.5

Author: dahlia

CHANGES.md

@@ -10,6 +10,12 @@ To be released.
 
 ### @fedify/fedify
 
+ -  Added `mapActorAlias()` method to `ActorCallbackSetters` interface to
+    support fixed-path actor dispatchers.  This is useful for exposing a
+    single, instance-level actor at a fixed path, such as `/actor` for a relay
+    or `/bot` for a bot, without leaking a sentinel identifier into the actor's
+    URI. [[#752], [#753]]
+
  -  Added optional `MessageQueue.getDepth()` support, using the new
     `MessageQueueDepth` return type, for reporting queue backlog depth.
     `InProcessMessageQueue` can now report queued messages, including ready
@@ -18,6 +24,8 @@ To be released.
 
 [#735]: https://github.com/fedify-dev/fedify/issues/735
 [#748]: https://github.com/fedify-dev/fedify/pull/748
+[#752]: https://github.com/fedify-dev/fedify/issues/752
+[#753]: https://github.com/fedify-dev/fedify/pull/753
 
 ### @fedify/amqp
 

docs/manual/actor.md

@@ -456,6 +456,48 @@ ctx.getActorUri("2bd304f9-36b3-44f0-bf0b-29124aafcbb4")
 > the argument is a valid identifier before calling the method.
 
 
+Fixed-path actor URIs
+---------------------
+
+*This API is available since Fedify 2.3.0.*
+
+In some cases, you may want to expose a single, instance-level actor at a fixed
+path, such as `/actor` for a relay or `/bot` for a bot, without leaking a
+sentinel identifier like `__instance__` into the actor's URI.
+
+You can alias a fixed path to a sentinel identifier by calling
+the `~ActorCallbackSetters.mapActorAlias()` method:
+
+~~~~ typescript
+// @noErrors: 2345 2391
+import { type Federation } from "@fedify/fedify";
+import { Person } from "@fedify/vocab";
+const federation = null as unknown as Federation<void>;
+// ---cut-before---
+federation
+  .setActorDispatcher("/users/{identifier}", async (ctx, identifier) => {
+    if (identifier === "bot") {
+      return new Person({
+        id: ctx.getActorUri(identifier),
+        preferredUsername: "bot",
+        // ...
+      });
+    }
+    // ...
+  })
+  .mapActorAlias("/bot", "bot");
+~~~~
+
+Once the alias is registered, `Context.getActorUri("bot")` will return
+`https://example.com/bot` rather than `https://example.com/users/bot`.
+Incoming requests to `/bot` will also correctly resolve the identifier to
+`"bot"` and trigger the actor dispatcher.
+
+> [!TIP]
+> You can map multiple fixed paths to different sentinel identifiers by calling
+> the `~ActorCallbackSetters.mapActorAlias()` method multiple times.
+
+
 Decoupling actor URIs from WebFinger usernames
 ----------------------------------------------
 

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

@@ -25,7 +25,18 @@ test("FederationBuilder", async (t) => {
       const actorDispatcher: ActorDispatcher<string> = (_ctx, _identifier) => {
         return null;
       };
-      builder.setActorDispatcher("/users/{identifier}", actorDispatcher);
+      assertThrows(
+        () =>
+          createFederationBuilder<string>().setActorDispatcher(
+            "/users/{identifier}",
+            actorDispatcher,
+          )
+            .mapActorAlias("/actor/{id}", "instance"),
+        RouterError,
+        "Path for actor alias must have no variables.",
+      );
+      builder.setActorDispatcher("/users/{identifier}", actorDispatcher)
+        .mapActorAlias("/actor", "instance");
 
       const inboxListener: InboxListener<string, Activity> = (
         _ctx,
@@ -83,6 +94,7 @@ test("FederationBuilder", async (t) => {
         "webfinger",
       );
       assertEquals(impl.router.route("/users/test123")?.name, "actor");
+      assertEquals(impl.router.route("/actor")?.name, "actorAlias:instance");
       assertEquals(impl.router.route("/users/test123/inbox")?.name, "inbox");
       assertEquals(impl.router.route("/users/test123/outbox")?.name, "outbox");
       assertEquals(

packages/fedify/src/federation/builder.ts

@@ -522,6 +522,16 @@ export class FederationBuilderImpl<TContextData>
         callbacks.aliasMapper = mapper;
         return setters;
       },
+      mapActorAlias: (path: string, identifier: string) => {
+        const variables = new Router().add(path, "temp");
+        if (variables.size > 0) {
+          throw new RouterError(
+            "Path for actor alias must have no variables.",
+          );
+        }
+        this.router.add(path, `actorAlias:${identifier}`);
+        return setters;
+      },
       authorize(predicate: AuthorizePredicate<TContextData>) {
         callbacks.authorizePredicate = predicate;
         return setters;

packages/fedify/src/federation/federation.ts

@@ -1108,6 +1108,20 @@ export interface ActorCallbackSetters<TContextData> {
     mapper: ActorAliasMapper<TContextData>,
   ): ActorCallbackSetters<TContextData>;
 
+  /**
+   * Maps a fixed path to a sentinel identifier.  It is useful for exposing
+   * a single, instance-level actor at a fixed path, such as `/actor` for
+   * a relay or `/bot` for a bot.
+   * @param path The fixed path to map to the identifier.
+   * @param identifier The sentinel identifier to map the path to.
+   * @returns The setters object so that settings can be chained.
+   * @since 2.3.0
+   */
+  mapActorAlias(
+    path: string,
+    identifier: string,
+  ): ActorCallbackSetters<TContextData>;
+
   /**
    * Specifies the conditions under which requests are authorized.
    * @param predicate A callback that returns whether a request is authorized.

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

@@ -301,6 +301,7 @@ test({
 
       federation
         .setActorDispatcher("/users/{identifier}", () => new vocab.Person({}))
+        .mapActorAlias("/bot", "bot")
         .setKeyPairsDispatcher(() => [
           {
             privateKey: rsaPrivateKey2,
@@ -317,11 +318,19 @@ test({
         ctx.getActorUri("handle"),
         new URL("https://example.com/users/handle"),
       );
+      assertEquals(
+        ctx.getActorUri("bot"),
+        new URL("https://example.com/bot"),
+      );
       assertEquals(ctx.parseUri(new URL("https://example.com/")), null);
       assertEquals(
         ctx.parseUri(new URL("https://example.com/users/handle")),
         { type: "actor", identifier: "handle" },
       );
+      assertEquals(
+        ctx.parseUri(new URL("https://example.com/bot")),
+        { type: "actor", identifier: "bot" },
+      );
       assertEquals(ctx.parseUri(null), null);
       assertEquals(
         await ctx.getActorKeyPairs("handle"),
@@ -1132,6 +1141,7 @@ test("Federation.fetch()", async (t) => {
         });
       },
     )
+      .mapActorAlias("/bot", "bot")
       .setKeyPairsDispatcher(() => {
         return [
           { privateKey: rsaPrivateKey2, publicKey: rsaPublicKey2.publicKey! },
@@ -1170,6 +1180,26 @@ test("Federation.fetch()", async (t) => {
     assertEquals(response.status, 406);
   });
 
+  await t.step("GET actor alias", async () => {
+    const { federation, dispatches } = createTestContext();
+
+    const response = await federation.fetch(
+      new Request("https://example.com/bot", {
+        method: "GET",
+        headers: {
+          "Accept": "application/activity+json",
+        },
+      }),
+      { contextData: undefined },
+    );
+
+    assertEquals(dispatches, ["bot"]);
+    assertEquals(response.status, 200);
+    const body = await response.json() as Record<string, unknown>;
+    assertEquals(body.id, "https://example.com/bot");
+    assertEquals(body.preferredUsername, "bot");
+  });
+
   await t.step("POST with application/json", async () => {
     const { federation, inbox } = createTestContext();
 

packages/fedify/src/federation/middleware.ts

@@ -1436,19 +1436,22 @@ export class FederationImpl<TContextData>
     }
     switch (routeName) {
       case "actor":
+      case "actorAlias": {
+        const identifier = route.name.startsWith("actorAlias:")
+          ? route.name.substring("actorAlias:".length)
+          : route.values.identifier;
         context = this.#createContext(request, contextData, {
-          invokedFromActorDispatcher: {
-            identifier: route.values.identifier,
-          },
+          invokedFromActorDispatcher: { identifier },
         });
         return await handleActor(request, {
-          identifier: route.values.identifier,
+          identifier,
           context,
           actorDispatcher: this.actorCallbacks?.dispatcher,
           authorizePredicate: this.actorCallbacks?.authorizePredicate,
           onUnauthorized,
           onNotFound,
         });
+      }
       case "object": {
         const typeId = route.name.replace(/^object:/, "");
         const callbacks = this.objectCallbacks[typeId];
@@ -1789,10 +1792,16 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
   }
 
   getActorUri(identifier: string): URL {
-    const path = this.federation.router.build(
-      "actor",
-      { identifier },
+    let path = this.federation.router.build(
+      `actorAlias:${identifier}`,
+      {},
     );
+    if (path == null) {
+      path = this.federation.router.build(
+        "actor",
+        { identifier },
+      );
+    }
     if (path == null) {
       throw new RouterError("No actor dispatcher registered.");
     }
@@ -1938,8 +1947,10 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
         identifier: undefined,
       };
     }
-    const identifier = route.values.identifier;
-    if (route.name === "actor") {
+    const identifier = route.name.startsWith("actorAlias:")
+      ? route.name.substring("actorAlias:".length)
+      : route.values.identifier;
+    if (route.name === "actor" || route.name.startsWith("actorAlias:")) {
       return {
         type: "actor",
         identifier,

pr-description.md

@@ -0,0 +1,23 @@
+This PR adds `mapActorAlias()` to `ActorCallbackSetters`. An actor dispatcher
+can now map a fixed path, such as `/actor` or `/bot`, to an internal sentinel
+identifier.
+
+Some applications expose a single instance-level actor at a fixed path. Before
+this change, they had to use a sentinel identifier such as `__instance__`, and
+that identifier became part of the actor URI.
+
+`mapActorAlias()` keeps the sentinel internal. Incoming actor requests resolve
+through the alias map. `Context.getActorUri()` uses the same map when building
+outbound actor URIs.
+
+Implementation details:
+
+ -  Aliases register a router route named `actorAlias:{identifier}`.
+ -  Alias paths must be fixed. Paths containing route variables are rejected.
+ -  `Context.getActorUri()` tries the `actorAlias:{identifier}` route first,
+    then falls back to the standard `actor` route.
+ -  `Context.parseUri()` and `fetch()` routing now recognize `actorAlias:`
+    route names and read the identifier from the route name instead of route
+    values.
+
+Resolves #752.