Refactor actor alias logic and harden type safety

Refactored `getActorUri()` to use a more idiomatic `??` pattern and
avoid `let`.  Hardened the `mapActorAlias()` signature by using a
template literal type for the `path` parameter.

Consolidated the `ACTOR_ALIAS_PREFIX` constant by exporting it from the
builder and reusing it in the middleware.

#753 (comment)
#753 (comment)
#753 (comment)

Assisted-by: Gemini CLI:gemini-3-flash-preview
Assisted-by: Codex:gpt-5.5

Author: dahlia

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

@@ -44,6 +44,15 @@ test("FederationBuilder", async (t) => {
         RouterError,
         'Actor alias for "instance" already set.',
       );
+      assertThrows(
+        () =>
+          createFederationBuilder<string>()
+            .setActorDispatcher("/users/{identifier}", actorDispatcher)
+            .mapActorAlias("/actor", "instance")
+            .mapActorAlias("/actor", "bot"),
+        RouterError,
+        'Actor alias path "/actor" conflicts with existing route "actorAlias:instance".',
+      );
       builder.setActorDispatcher("/users/{identifier}", actorDispatcher)
         .mapActorAlias("/actor", "instance");
 

packages/fedify/src/federation/builder.ts

@@ -63,7 +63,7 @@ import type {
 } from "./handler.ts";
 import { Router, RouterError } from "./router.ts";
 
-const ACTOR_ALIAS_PREFIX = "actorAlias:";
+export const ACTOR_ALIAS_PREFIX = "actorAlias:";
 
 function validateSingleIdentifierVariablePath(
   path: string,
@@ -524,7 +524,7 @@ export class FederationBuilderImpl<TContextData>
         callbacks.aliasMapper = mapper;
         return setters;
       },
-      mapActorAlias: (path: string, identifier: string) => {
+      mapActorAlias: (path: `/${string}`, identifier: string) => {
         if (this.router.has(`${ACTOR_ALIAS_PREFIX}${identifier}`)) {
           throw new RouterError(
             `Actor alias for "${identifier}" already set.`,
@@ -536,6 +536,12 @@ export class FederationBuilderImpl<TContextData>
             "Path for actor alias must have no variables.",
           );
         }
+        const existingRoute = this.router.route(path);
+        if (existingRoute != null) {
+          throw new RouterError(
+            `Actor alias path "${path}" conflicts with existing route "${existingRoute.name}".`,
+          );
+        }
         this.router.add(path, `${ACTOR_ALIAS_PREFIX}${identifier}`);
         return setters;
       },

packages/fedify/src/federation/federation.ts

@@ -1120,7 +1120,7 @@ export interface ActorCallbackSetters<TContextData> {
    * @since 2.3.0
    */
   mapActorAlias(
-    path: string,
+    path: `/${string}`,
     identifier: string,
   ): ActorCallbackSetters<TContextData>;
 

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

@@ -1224,6 +1224,8 @@ test("Federation.fetch()", async (t) => {
     assertEquals(response.status, 200);
     const body = await response.json() as Record<string, unknown>;
     assertEquals(body.subject, "acct:bot@example.com");
+    assertExists(body.links);
+    assert(Array.isArray(body.links));
     const selfLink = (body.links as Record<string, unknown>[]).find((l) =>
       l.rel === "self"
     );

packages/fedify/src/federation/middleware.ts

@@ -112,8 +112,8 @@ import type {
 } from "./queue.ts";
 import { createExponentialBackoffPolicy, type RetryPolicy } from "./retry.ts";
 import { RouterError } from "./router.ts";
+import { ACTOR_ALIAS_PREFIX } from "./builder.ts";
 
-const ACTOR_ALIAS_PREFIX = "actorAlias:";
 import {
   extractInboxes,
   sendActivity,
@@ -1794,16 +1794,13 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
   }
 
   getActorUri(identifier: string): URL {
-    let path = this.federation.router.build(
+    const path = this.federation.router.build(
       `${ACTOR_ALIAS_PREFIX}${identifier}`,
       {},
+    ) ?? this.federation.router.build(
+      "actor",
+      { identifier },
     );
-    if (path == null) {
-      path = this.federation.router.build(
-        "actor",
-        { identifier },
-      );
-    }
     if (path == null) {
       throw new RouterError("No actor dispatcher registered.");
     }