Log deprecated Router warning once per process

The deprecated `Router`/`RouterError` compatibility shim from
`@fedify/fedify/federation` logged a deprecation warning on every
wrapped call: `convertRouterError()` wraps every compatibility method,
so a deprecated `Router` used on the request path logged on every
`route()` call, and the error path logged a second, duplicate warning
when constructing the compatibility `RouterError`.  For applications
that keep the compatibility class during migration, this could flood
logs.

Consolidate both warnings into a single module-level one-shot
`warnDeprecated()` guard so the migration signal is emitted at most
once per process, and add a regression test asserting the warning is
logged at most once across many wrapped calls and the error path.

#758 (comment)

Assisted-by: Claude Code:claude-opus-4-7

Author: 2chanhaeng

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

@@ -1,5 +1,6 @@
 import { test } from "@fedify/fixture";
 import { RouterError as UriTemplateRouterError } from "@fedify/uri-template";
+import { configure, type LogRecord, reset } from "@logtape/logtape";
 import { assert, assertEquals, assertFalse, assertThrows } from "@std/assert";
 import { Router, RouterError, type RouterOptions } from "./router.ts";
 
@@ -119,6 +120,59 @@ test("Router.route() returns null for non-path inputs", () => {
   assertEquals(router.route("/unknown"), null);
 });
 
+let logtapeLock: Promise<void> = Promise.resolve();
+
+function withLogtapeLock<T>(fn: () => Promise<T>): Promise<T> {
+  const run = logtapeLock.then(fn, fn);
+  logtapeLock = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+test("Router deprecation warning is logged at most once", () =>
+  withLogtapeLock(async () => {
+    const records: LogRecord[] = [];
+    await reset();
+    try {
+      await configure({
+        sinks: {
+          buffer(record: LogRecord): void {
+            records.push(record);
+          },
+        },
+        filters: {},
+        loggers: [
+          {
+            category: ["fedify", "federation", "router", "deprecated"],
+            sinks: ["buffer"],
+          },
+          { category: ["logtape", "meta"], sinks: [] },
+        ],
+      });
+
+      const router = new Router();
+      router.add("/users/{name}", "user");
+      for (let i = 0; i < 50; i++) {
+        router.route("/users/alice");
+        router.route("https://example.com/not-a-path");
+        router.has("user");
+        router.build("user", { name: "alice" });
+      }
+      assertThrows(() => router.add("foo", "bar"), RouterError);
+
+      const deprecationWarnings = records.filter((record) =>
+        typeof record.rawMessage === "string" &&
+        record.rawMessage.includes("deprecated")
+      );
+      assert(
+        deprecationWarnings.length <= 1,
+        "expected at most one deprecation warning, got " +
+          deprecationWarnings.length,
+      );
+    } finally {
+      await reset();
+    }
+  }));
+
 test("Compatibility between RouterErrors", () => {
   const newError = new UriTemplateRouterError("boom");
   assert(newError instanceof UriTemplateRouterError);

packages/fedify/src/federation/router.ts

@@ -12,6 +12,17 @@ import { getLogger } from "@logtape/logtape";
 
 const logger = getLogger(["fedify", "federation", "router", "deprecated"]);
 
+let deprecationWarned = false;
+
+function warnDeprecated(): void {
+  if (deprecationWarned) return;
+  deprecationWarned = true;
+  logger.warn(
+    "The `Router` and `RouterError` classes from `@fedify/fedify` are " +
+      "deprecated.  Please use `Router` from `@fedify/uri-template` instead.",
+  );
+}
+
 /**
  * Options for the {@link Router}.
  * @since 0.12.0
@@ -159,19 +170,13 @@ export class RouterError extends _RouterError {
    */
   constructor(message: string) {
     super(message);
-    logger.warn(
-      "The `RouterError` class from `@fedify/fedify` is deprecated." +
-        " Please use `Router` from `@fedify/uri-template` instead.",
-    );
+    warnDeprecated();
   }
 }
 
 function convertRouterError<T>(func: () => T): T {
   try {
-    logger.warn(
-      "The `Router` class from `@fedify/fedify` is deprecated." +
-        " Please use `Router` from `@fedify/uri-template` instead.",
-    );
+    warnDeprecated();
     return func();
   } catch (error) {
     if (error instanceof _RouterError) {