Merge pull request #564 from dahlia/debugger

`@fedify/debugger`: Embedded ActivityPub debug dashboard

Author: dahlia

CHANGES.md

@@ -139,6 +139,12 @@ To be released.
     code, the inbox URL, and the response body, making it easier to
     programmatically handle delivery errors.  [[#548], [#559]]
 
+ -  Added `traceId` and `spanId` to LogTape context in federation middleware
+    so that log records emitted during request handling and queue processing
+    include the OpenTelemetry trace and span IDs in their properties.  This
+    enables the `@fedify/debugger` dashboard to display per-trace logs.
+    [[#561], [#564]]
+
 [#280]: https://github.com/fedify-dev/fedify/issues/280
 [#366]: https://github.com/fedify-dev/fedify/issues/366
 [#376]: https://github.com/fedify-dev/fedify/issues/376
@@ -163,6 +169,8 @@ To be released.
 [#548]: https://github.com/fedify-dev/fedify/issues/548
 [#559]: https://github.com/fedify-dev/fedify/pull/559
 [#560]: https://github.com/fedify-dev/fedify/issues/560
+[#561]: https://github.com/fedify-dev/fedify/issues/561
+[#564]: https://github.com/fedify-dev/fedify/pull/564
 
 ### @fedify/cli
 
@@ -231,6 +239,38 @@ To be released.
 [#529]: https://github.com/fedify-dev/fedify/pull/529
 [#531]: https://github.com/fedify-dev/fedify/pull/531
 
+### @fedify/debugger
+
+ -  Created the *@fedify/debugger* package, an embedded real-time ActivityPub
+    debug dashboard for Fedify.  It wraps an existing `Federation` object as
+    a proxy, intercepting requests to a configurable path prefix (default
+    `/__debug__`) and serving an SSR-based web UI.  [[#561], [#564]]
+
+     -  Added `createFederationDebugger()` function that returns a
+        `Federation` proxy with a built-in debug dashboard.  When called
+        without an `exporter` option, it automatically sets up OpenTelemetry
+        tracing (creating `MemoryKvStore`, `FedifySpanExporter`,
+        `BasicTracerProvider`) and registers it as the global tracer
+        provider—no manual OTel configuration needed.
+     -  Traces list page showing trace IDs, activity types, activity counts,
+        and timestamps, with auto-polling for real-time updates.
+     -  Trace detail page showing activity direction, type, actor, signature
+        verification details, inbox URL, and expandable activity JSON.
+     -  JSON API endpoint at `/__debug__/api/traces` for programmatic access.
+     -  Added per-trace log collection using LogTape.  The returned federation
+        object now includes a `sink` property (a LogTape `Sink` function)
+        that captures log records grouped by trace ID.  In the simplified
+        overload (without `exporter`), LogTape is auto-configured.
+     -  Trace detail page now shows a “Logs” section with log level, timestamp,
+        logger category, and message for each log record in the trace.
+     -  JSON API endpoint at `/__debug__/api/logs/:traceId` for retrieving
+        log records for a specific trace.
+     -  Added optional `auth` configuration for protecting the debug dashboard
+        with authentication.  Supports three modes: password-only,
+        username + password, and request-based (e.g., IP filtering).
+        Each mode supports both static credentials and callback functions.
+        Uses cookie-based sessions with HMAC-signed tokens.
+
 ### @fedify/relay
 
  -  Created ActivityPub relay integration as the *@fedify/relay* package.

CONTRIBUTING.md

@@ -335,6 +335,8 @@ The repository is organized as a monorepo with the following packages:
  -  *packages/amqp/*: AMQP/RabbitMQ driver (@fedify/amqp) for Fedify.
  -  *packages/cfworkers/*: Cloudflare Workers integration (@fedify/cfworkers) for
     Fedify.
+ -  *packages/debugger/*: Embedded ActivityPub debug dashboard (@fedify/debugger)
+    for Fedify.
  -  *packages/denokv/*: Deno KV integration (@fedify/denokv) for Fedify.
  -  *packages/elysia/*: Elysia integration (@fedify/elysia) for Fedify.
  -  *packages/express/*: Express integration (@fedify/express) for Fedify.

deno.json

@@ -3,6 +3,7 @@
     "./packages/amqp",
     "./packages/cfworkers",
     "./packages/cli",
+    "./packages/debugger",
     "./packages/denokv",
     "./packages/express",
     "./packages/fastify",
@@ -35,8 +36,10 @@
     "@logtape/logtape": "jsr:@logtape/logtape@^2.0.0",
     "@nestjs/common": "npm:@nestjs/common@^11.0.1",
     "@opentelemetry/api": "npm:@opentelemetry/api@^1.9.0",
-    "@opentelemetry/core": "npm:@opentelemetry/core@^2.0.0",
-    "@opentelemetry/sdk-trace-base": "npm:@opentelemetry/sdk-trace-base@^2.0.0",
+    "@opentelemetry/context-async-hooks": "npm:@opentelemetry/context-async-hooks@^2.5.0",
+    "@opentelemetry/core": "npm:@opentelemetry/core@^2.5.0",
+    "@opentelemetry/sdk-trace-base": "npm:@opentelemetry/sdk-trace-base@^2.5.0",
+    "@opentelemetry/semantic-conventions": "npm:@opentelemetry/semantic-conventions@^1.39.0",
     "@std/assert": "jsr:@std/assert@^1.0.13",
     "@std/async": "jsr:@std/async@^1.0.13",
     "@std/encoding": "jsr:@std/encoding@^1.0.10",
@@ -49,6 +52,7 @@
     "byte-encodings": "npm:byte-encodings@^1.0.11",
     "es-toolkit": "npm:es-toolkit@^1.43.0",
     "h3": "npm:h3@^1.15.0",
+    "hono": "jsr:@hono/hono@^4.8.3",
     "ioredis": "npm:ioredis@^5.8.2",
     "json-preserve-indent": "npm:json-preserve-indent@^1.1.3",
     "postgres": "npm:postgres@^3.4.7",

deno.lock

@@ -77,6 +77,7 @@ const MANUAL = {
     { text: "Integration", link: "/manual/integration.md" },
     { text: "Relay", link: "/manual/relay.md" },
     { text: "Testing", link: "/manual/test.md" },
+    { text: "Debugging", link: "/manual/debug.md" },
     { text: "Linting", link: "/manual/lint.md" },
     { text: "Logging", link: "/manual/log.md" },
     { text: "OpenTelemetry", link: "/manual/opentelemetry.md" },
@@ -92,6 +93,7 @@ const REFERENCES = {
     { text: "@fedify/fedify", link: "https://jsr.io/@fedify/fedify/doc" },
     { text: "@fedify/amqp", link: "https://jsr.io/@fedify/amqp/doc" },
     { text: "@fedify/cfworkers", link: "https://jsr.io/@fedify/cfworkers/doc" },
+    { text: "@fedify/debugger", link: "https://jsr.io/@fedify/debugger/doc" },
     { text: "@fedify/denokv", link: "https://jsr.io/@fedify/denokv/doc" },
     { text: "@fedify/express", link: "https://jsr.io/@fedify/express/doc" },
     { text: "@fedify/fastify", link: "https://jsr.io/@fedify/fastify/doc" },