@fedify/debugger 2.0.0-dev.0

package/dist/mod.d.cts

@@ -0,0 +1,188 @@
+import { Federation, KvStore } from "@fedify/fedify/federation";
+import { FedifySpanExporter } from "@fedify/fedify/otel";
+import { Sink } from "@logtape/logtape";
+
+//#region src/auth.d.ts
+
+/**
+ * Authentication configuration for the debug dashboard.
+ *
+ * The debug dashboard can be protected using one of three authentication modes:
+ *
+ * - `"password"` — Shows a password-only login form.
+ * - `"usernamePassword"` — Shows a username + password login form.
+ * - `"request"` — Authenticates based on the incoming request (e.g., IP
+ *   address).  No login form is shown; unauthenticated requests receive a
+ *   403 response.
+ *
+ * Each mode supports either a static credential check or a callback function.
+ */
+type FederationDebuggerAuth = {
+  readonly type: "password";
+  authenticate(password: string): boolean | Promise<boolean>;
+} | {
+  readonly type: "password";
+  readonly password: string;
+} | {
+  readonly type: "usernamePassword";
+  authenticate(username: string, password: string): boolean | Promise<boolean>;
+} | {
+  readonly type: "usernamePassword";
+  readonly username: string;
+  readonly password: string;
+} | {
+  readonly type: "request";
+  authenticate(request: Request): boolean | Promise<boolean>;
+};
+//#endregion
+//#region src/log-store.d.ts
+/**
+ * A serialized log record for the debug dashboard.
+ */
+interface SerializedLogRecord {
+  /**
+   * The logger category.
+   */
+  readonly category: readonly string[];
+  /**
+   * The log level.
+   */
+  readonly level: string;
+  /**
+   * The rendered log message.
+   */
+  readonly message: string;
+  /**
+   * The timestamp in milliseconds since the Unix epoch.
+   */
+  readonly timestamp: number;
+  /**
+   * The extra properties of the log record (excluding traceId and spanId).
+   */
+  readonly properties: Record<string, unknown>;
+}
+/**
+ * Persistent storage for log records grouped by trace ID, backed by a
+ * {@link KvStore}.  When the same `KvStore` is shared across web and worker
+ * processes the dashboard can display logs produced by background tasks.
+ */
+//#endregion
+//#region src/mod.d.ts
+/**
+ * Resets the internal auto-setup state.  This is intended **only for tests**
+ * that need to exercise the auto-setup code path more than once within the
+ * same process.
+ *
+ * @internal
+ */
+declare function resetAutoSetup(): void;
+/**
+ * Options for {@link createFederationDebugger} with an explicit exporter.
+ *
+ * When `exporter` is provided, the caller is responsible for setting up
+ * the OpenTelemetry tracer provider and passing it to `createFederation()`.
+ */
+interface FederationDebuggerOptions {
+  /**
+   * The path prefix for the debug dashboard.  Defaults to `"/__debug__"`.
+   */
+  path?: string;
+  /**
+   * The {@link FedifySpanExporter} to query trace data from.
+   */
+  exporter: FedifySpanExporter;
+  /**
+   * The {@link KvStore} to persist log records to.  This should typically be
+   * the same `KvStore` instance that was passed to the `FedifySpanExporter`
+   * so that logs and traces are co-located and accessible from all processes
+   * (e.g., both web and worker nodes).
+   */
+  kv: KvStore;
+  /**
+   * Authentication configuration for the debug dashboard.  When omitted,
+   * the dashboard is accessible without authentication.
+   */
+  auth?: FederationDebuggerAuth;
+}
+/**
+ * Options for {@link createFederationDebugger} without an explicit exporter.
+ *
+ * When `exporter` is omitted, the debugger automatically creates a
+ * {@link MemoryKvStore}, {@link FedifySpanExporter},
+ * {@link BasicTracerProvider}, and registers it as the global tracer provider
+ * so that `createFederation()` picks it up automatically.
+ */
+interface FederationDebuggerSimpleOptions {
+  /**
+   * The path prefix for the debug dashboard.  Defaults to `"/__debug__"`.
+   */
+  path?: string;
+  /**
+   * Authentication configuration for the debug dashboard.  When omitted,
+   * the dashboard is accessible without authentication.
+   */
+  auth?: FederationDebuggerAuth;
+}
+/**
+ * Wraps a {@link Federation} object with a debug dashboard.
+ *
+ * When called without an `exporter`, the debugger automatically sets up
+ * OpenTelemetry tracing: it creates a {@link MemoryKvStore},
+ * {@link FedifySpanExporter}, and {@link BasicTracerProvider}, then registers
+ * it as the global tracer provider.  It also auto-configures LogTape to
+ * collect logs per trace.
+ *
+ * @example Simple usage (recommended)
+ * ```typescript ignore
+ * const innerFederation = createFederation({ kv: new MemoryKvStore() });
+ * const federation = createFederationDebugger(innerFederation);
+ * ```
+ *
+ * @template TContextData The context data type of the federation.
+ * @param federation The federation object to wrap.
+ * @param options Optional path configuration.
+ * @returns A new {@link Federation} object with the debug dashboard attached
+ *          and a `sink` property for LogTape integration.
+ */
+declare function createFederationDebugger<TContextData>(federation: Federation<TContextData>, options?: FederationDebuggerSimpleOptions): Federation<TContextData> & {
+  sink: Sink;
+};
+/**
+ * Wraps a {@link Federation} object with a debug dashboard.
+ *
+ * When called with an `exporter`, the caller is responsible for setting up
+ * the OpenTelemetry tracer provider and passing it to `createFederation()`.
+ * The returned object includes a `sink` property that should be added to
+ * the LogTape configuration to collect logs per trace.
+ *
+ * @example Advanced usage with explicit exporter
+ * ```typescript ignore
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv);
+ * const tracerProvider = new BasicTracerProvider({
+ *   spanProcessors: [new SimpleSpanProcessor(exporter)],
+ * });
+ * const innerFederation = createFederation({ kv, tracerProvider });
+ * const federation = createFederationDebugger(innerFederation, {
+ *   exporter,
+ *   kv,
+ * });
+ * await configure({
+ *   sinks: { debugger: federation.sink },
+ *   loggers: [
+ *     { category: "fedify", sinks: ["debugger"] },
+ *   ],
+ * });
+ * ```
+ *
+ * @template TContextData The context data type of the federation.
+ * @param federation The federation object to wrap.
+ * @param options Options including the exporter.
+ * @returns A new {@link Federation} object with the debug dashboard attached
+ *          and a `sink` property for LogTape integration.
+ */
+declare function createFederationDebugger<TContextData>(federation: Federation<TContextData>, options: FederationDebuggerOptions): Federation<TContextData> & {
+  sink: Sink;
+};
+//#endregion
+export { FederationDebuggerAuth, FederationDebuggerOptions, FederationDebuggerSimpleOptions, SerializedLogRecord, createFederationDebugger, resetAutoSetup };

package/dist/mod.d.ts

@@ -0,0 +1,189 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { Federation, KvStore } from "@fedify/fedify/federation";
+import { FedifySpanExporter } from "@fedify/fedify/otel";
+import { Sink } from "@logtape/logtape";
+
+//#region src/auth.d.ts
+
+/**
+ * Authentication configuration for the debug dashboard.
+ *
+ * The debug dashboard can be protected using one of three authentication modes:
+ *
+ * - `"password"` — Shows a password-only login form.
+ * - `"usernamePassword"` — Shows a username + password login form.
+ * - `"request"` — Authenticates based on the incoming request (e.g., IP
+ *   address).  No login form is shown; unauthenticated requests receive a
+ *   403 response.
+ *
+ * Each mode supports either a static credential check or a callback function.
+ */
+type FederationDebuggerAuth = {
+  readonly type: "password";
+  authenticate(password: string): boolean | Promise<boolean>;
+} | {
+  readonly type: "password";
+  readonly password: string;
+} | {
+  readonly type: "usernamePassword";
+  authenticate(username: string, password: string): boolean | Promise<boolean>;
+} | {
+  readonly type: "usernamePassword";
+  readonly username: string;
+  readonly password: string;
+} | {
+  readonly type: "request";
+  authenticate(request: Request): boolean | Promise<boolean>;
+};
+//#endregion
+//#region src/log-store.d.ts
+/**
+ * A serialized log record for the debug dashboard.
+ */
+interface SerializedLogRecord {
+  /**
+   * The logger category.
+   */
+  readonly category: readonly string[];
+  /**
+   * The log level.
+   */
+  readonly level: string;
+  /**
+   * The rendered log message.
+   */
+  readonly message: string;
+  /**
+   * The timestamp in milliseconds since the Unix epoch.
+   */
+  readonly timestamp: number;
+  /**
+   * The extra properties of the log record (excluding traceId and spanId).
+   */
+  readonly properties: Record<string, unknown>;
+}
+/**
+ * Persistent storage for log records grouped by trace ID, backed by a
+ * {@link KvStore}.  When the same `KvStore` is shared across web and worker
+ * processes the dashboard can display logs produced by background tasks.
+ */
+//#endregion
+//#region src/mod.d.ts
+/**
+ * Resets the internal auto-setup state.  This is intended **only for tests**
+ * that need to exercise the auto-setup code path more than once within the
+ * same process.
+ *
+ * @internal
+ */
+declare function resetAutoSetup(): void;
+/**
+ * Options for {@link createFederationDebugger} with an explicit exporter.
+ *
+ * When `exporter` is provided, the caller is responsible for setting up
+ * the OpenTelemetry tracer provider and passing it to `createFederation()`.
+ */
+interface FederationDebuggerOptions {
+  /**
+   * The path prefix for the debug dashboard.  Defaults to `"/__debug__"`.
+   */
+  path?: string;
+  /**
+   * The {@link FedifySpanExporter} to query trace data from.
+   */
+  exporter: FedifySpanExporter;
+  /**
+   * The {@link KvStore} to persist log records to.  This should typically be
+   * the same `KvStore` instance that was passed to the `FedifySpanExporter`
+   * so that logs and traces are co-located and accessible from all processes
+   * (e.g., both web and worker nodes).
+   */
+  kv: KvStore;
+  /**
+   * Authentication configuration for the debug dashboard.  When omitted,
+   * the dashboard is accessible without authentication.
+   */
+  auth?: FederationDebuggerAuth;
+}
+/**
+ * Options for {@link createFederationDebugger} without an explicit exporter.
+ *
+ * When `exporter` is omitted, the debugger automatically creates a
+ * {@link MemoryKvStore}, {@link FedifySpanExporter},
+ * {@link BasicTracerProvider}, and registers it as the global tracer provider
+ * so that `createFederation()` picks it up automatically.
+ */
+interface FederationDebuggerSimpleOptions {
+  /**
+   * The path prefix for the debug dashboard.  Defaults to `"/__debug__"`.
+   */
+  path?: string;
+  /**
+   * Authentication configuration for the debug dashboard.  When omitted,
+   * the dashboard is accessible without authentication.
+   */
+  auth?: FederationDebuggerAuth;
+}
+/**
+ * Wraps a {@link Federation} object with a debug dashboard.
+ *
+ * When called without an `exporter`, the debugger automatically sets up
+ * OpenTelemetry tracing: it creates a {@link MemoryKvStore},
+ * {@link FedifySpanExporter}, and {@link BasicTracerProvider}, then registers
+ * it as the global tracer provider.  It also auto-configures LogTape to
+ * collect logs per trace.
+ *
+ * @example Simple usage (recommended)
+ * ```typescript ignore
+ * const innerFederation = createFederation({ kv: new MemoryKvStore() });
+ * const federation = createFederationDebugger(innerFederation);
+ * ```
+ *
+ * @template TContextData The context data type of the federation.
+ * @param federation The federation object to wrap.
+ * @param options Optional path configuration.
+ * @returns A new {@link Federation} object with the debug dashboard attached
+ *          and a `sink` property for LogTape integration.
+ */
+declare function createFederationDebugger<TContextData>(federation: Federation<TContextData>, options?: FederationDebuggerSimpleOptions): Federation<TContextData> & {
+  sink: Sink;
+};
+/**
+ * Wraps a {@link Federation} object with a debug dashboard.
+ *
+ * When called with an `exporter`, the caller is responsible for setting up
+ * the OpenTelemetry tracer provider and passing it to `createFederation()`.
+ * The returned object includes a `sink` property that should be added to
+ * the LogTape configuration to collect logs per trace.
+ *
+ * @example Advanced usage with explicit exporter
+ * ```typescript ignore
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv);
+ * const tracerProvider = new BasicTracerProvider({
+ *   spanProcessors: [new SimpleSpanProcessor(exporter)],
+ * });
+ * const innerFederation = createFederation({ kv, tracerProvider });
+ * const federation = createFederationDebugger(innerFederation, {
+ *   exporter,
+ *   kv,
+ * });
+ * await configure({
+ *   sinks: { debugger: federation.sink },
+ *   loggers: [
+ *     { category: "fedify", sinks: ["debugger"] },
+ *   ],
+ * });
+ * ```
+ *
+ * @template TContextData The context data type of the federation.
+ * @param federation The federation object to wrap.
+ * @param options Options including the exporter.
+ * @returns A new {@link Federation} object with the debug dashboard attached
+ *          and a `sink` property for LogTape integration.
+ */
+declare function createFederationDebugger<TContextData>(federation: Federation<TContextData>, options: FederationDebuggerOptions): Federation<TContextData> & {
+  sink: Sink;
+};
+//#endregion
+export { FederationDebuggerAuth, FederationDebuggerOptions, FederationDebuggerSimpleOptions, SerializedLogRecord, createFederationDebugger, resetAutoSetup };