@beignet/devtools 0.0.1

package/src/routes.ts

@@ -0,0 +1,317 @@
+/**
+ * HTTP handlers for devtools API
+ *
+ * These handlers can be used to expose devtools data via HTTP endpoints
+ * in Next.js or any other framework that uses the Fetch API Request/Response.
+ */
+
+import {
+  authorizeDevtoolsRequest,
+  type DevtoolsRouteAccessOptions,
+} from "./access";
+import { isDevtoolsEventType } from "./events";
+import type { DevtoolsFilter, DevtoolsPort } from "./index";
+import { handleDevtoolsUIRequest } from "./ui";
+
+export interface DevtoolsRequestOptions extends DevtoolsRouteAccessOptions {
+  /**
+   * URL path prefix where devtools routes are mounted.
+   *
+   * @example "/api/devtools"
+   */
+  basePath: string;
+}
+
+export interface DevtoolsRouteHandlers {
+  GET(req: Request): Promise<Response>;
+  POST(req: Request): Promise<Response>;
+}
+
+/**
+ * Handle GET requests to list devtools events with optional filtering.
+ *
+ * Query parameters:
+ * - type: Filter by event type (request, error, usecase, eventBus, job, schedule, provider)
+ * - requestId: Filter by request correlation ID
+ * - traceId: Filter by W3C trace ID
+ * - limit: Maximum number of events to return (default: 200)
+ *
+ * @param req - The incoming HTTP request
+ * @param devtools - The DevtoolsPort instance to query
+ * @returns JSON response with events array
+ *
+ * @example
+ * ```ts
+ * // In a Next.js route handler:
+ * // app/api/devtools/core/events/route.ts
+ * import { handleDevtoolsEventsRequest } from "@beignet/devtools";
+ *
+ * export async function GET(req: Request) {
+ *   const devtools = getAppDevtoolsPort(); // app-specific helper
+ *   return handleDevtoolsEventsRequest(req, devtools);
+ * }
+ * ```
+ */
+export async function handleDevtoolsEventsRequest(
+  req: Request,
+  devtools: DevtoolsPort,
+  options: DevtoolsRouteAccessOptions = {},
+): Promise<Response> {
+  const denied = await authorizeDevtoolsRequest(req, options);
+  if (denied) return denied;
+
+  const url = new URL(req.url);
+  const type = url.searchParams.get("type");
+  const requestId = url.searchParams.get("requestId");
+  const traceId = url.searchParams.get("traceId");
+  const limitParam = url.searchParams.get("limit");
+
+  if (type !== null && !isDevtoolsEventType(type)) {
+    return new Response(JSON.stringify({ error: "Invalid event type" }), {
+      status: 400,
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+      },
+    });
+  }
+
+  let limit: number | undefined;
+  if (limitParam !== null) {
+    const parsed = Number.parseInt(limitParam, 10);
+    if (!Number.isNaN(parsed)) {
+      limit = parsed;
+    }
+  }
+
+  const filter: DevtoolsFilter = {
+    type: type ?? undefined,
+    requestId: requestId ?? undefined,
+    traceId: traceId ?? undefined,
+    limit,
+  };
+
+  const events = devtools.getEvents(filter);
+
+  return new Response(
+    JSON.stringify({
+      events,
+      watchers: devtools.getWatchers(),
+    }),
+    {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+      },
+    },
+  );
+}
+
+/**
+ * Handle POST requests to clear all devtools events.
+ *
+ * This endpoint requires a POST request and will clear the in-memory event buffer.
+ *
+ * @param req - The incoming HTTP request
+ * @param devtools - The DevtoolsPort instance to clear
+ * @returns JSON response with success status
+ *
+ * @example
+ * ```ts
+ * // In a Next.js route handler:
+ * // app/api/devtools/clear/route.ts
+ * import { handleDevtoolsClearRequest } from "@beignet/devtools";
+ *
+ * export async function POST(req: Request) {
+ *   const devtools = getAppDevtoolsPort(); // app-specific helper
+ *   return handleDevtoolsClearRequest(req, devtools);
+ * }
+ * ```
+ */
+export async function handleDevtoolsClearRequest(
+  req: Request,
+  devtools: DevtoolsPort,
+  options: DevtoolsRouteAccessOptions = {},
+): Promise<Response> {
+  const denied = await authorizeDevtoolsRequest(req, options);
+  if (denied) return denied;
+
+  if (req.method !== "POST") {
+    return new Response("Method Not Allowed", { status: 405 });
+  }
+
+  await devtools.clear();
+
+  return new Response(JSON.stringify({ ok: true }), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+function encodeSse(event: string, data: unknown): Uint8Array {
+  return new TextEncoder().encode(
+    `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`,
+  );
+}
+
+/**
+ * Handle GET requests for a live Server-Sent Events stream.
+ *
+ * The stream emits:
+ * - `snapshot` with the current event buffer
+ * - `event` when a new event is recorded
+ * - `clear` when the buffer is cleared
+ */
+export async function handleDevtoolsStreamRequest(
+  req: Request,
+  devtools: DevtoolsPort,
+  options: DevtoolsRouteAccessOptions = {},
+): Promise<Response> {
+  const denied = await authorizeDevtoolsRequest(req, options);
+  if (denied) return denied;
+
+  if (req.method !== "GET") {
+    return new Response("Method Not Allowed", { status: 405 });
+  }
+
+  let unsubscribe: (() => void) | undefined;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      let closed = false;
+
+      const enqueue = (event: string, data: unknown) => {
+        if (closed) return;
+        try {
+          controller.enqueue(encodeSse(event, data));
+        } catch {
+          closed = true;
+        }
+      };
+
+      enqueue("snapshot", {
+        events: devtools.getEvents({ limit: 500 }),
+        watchers: devtools.getWatchers(),
+      });
+
+      unsubscribe = devtools.subscribe((event) => {
+        if (event.type === "record") {
+          enqueue("event", { event: event.event });
+          return;
+        }
+        enqueue("clear", { ok: true });
+      });
+
+      req.signal.addEventListener(
+        "abort",
+        () => {
+          closed = true;
+          unsubscribe?.();
+          try {
+            controller.close();
+          } catch {
+            // The stream may already be closed by the client.
+          }
+        },
+        { once: true },
+      );
+    },
+    cancel() {
+      unsubscribe?.();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-store, no-transform",
+      Connection: "keep-alive",
+    },
+  });
+}
+
+/**
+ * Unified devtools request handler.
+ *
+ * Routes requests to the appropriate handler based on the URL path:
+ * - `{basePath}/core/events` → event list (GET)
+ * - `{basePath}/stream` → live event stream (GET)
+ * - `{basePath}/clear` → clear buffer (POST)
+ * - `{basePath}` → dashboard UI (GET)
+ *
+ * This lets you wire up a single catch-all route instead of three separate ones.
+ *
+ * @param req - The incoming HTTP request
+ * @param devtools - The DevtoolsPort instance
+ * @param options - Devtools route options including base path and access policy
+ * @returns Response for the matched sub-route
+ *
+ * @example
+ * ```ts
+ * // Next.js catch-all route: app/api/devtools/[[...path]]/route.ts
+ * import { createDevtoolsRoute } from "@beignet/devtools";
+ * import { getDevtools } from "@/server";
+ *
+ * export const { GET, POST } = createDevtoolsRoute(getDevtools(), {
+ *   basePath: "/api/devtools",
+ * });
+ * ```
+ */
+export async function handleDevtoolsRequest(
+  req: Request,
+  devtools: DevtoolsPort,
+  options: DevtoolsRequestOptions,
+): Promise<Response> {
+  const denied = await authorizeDevtoolsRequest(req, options);
+  if (denied) return denied;
+
+  const url = new URL(req.url);
+  const path = url.pathname.replace(/\/+$/, "");
+  const normalizedBase = options.basePath.replace(/\/+$/, "");
+  const accessChecked: DevtoolsRouteAccessOptions = { enabled: true };
+
+  if (path === `${normalizedBase}/core/events`) {
+    return handleDevtoolsEventsRequest(req, devtools, accessChecked);
+  }
+
+  if (path === `${normalizedBase}/clear`) {
+    return handleDevtoolsClearRequest(req, devtools, accessChecked);
+  }
+
+  if (path === `${normalizedBase}/stream`) {
+    return handleDevtoolsStreamRequest(req, devtools, accessChecked);
+  }
+
+  if (path === normalizedBase) {
+    if (req.method !== "GET") {
+      return new Response("Method Not Allowed", { status: 405 });
+    }
+    return handleDevtoolsUIRequest(options.basePath, accessChecked);
+  }
+
+  return new Response("Not Found", { status: 404 });
+}
+
+/**
+ * Create GET and POST handlers for a devtools catch-all route.
+ *
+ * This is the recommended integration for frameworks such as Next.js that
+ * export HTTP method functions from route modules.
+ */
+export function createDevtoolsRoute(
+  devtools: DevtoolsPort,
+  options: DevtoolsRequestOptions,
+): DevtoolsRouteHandlers {
+  const handle = (req: Request) =>
+    handleDevtoolsRequest(req, devtools, options);
+
+  return {
+    GET: handle,
+    POST: handle,
+  };
+}

package/src/trace-context.ts

@@ -0,0 +1,115 @@
+const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+export interface DevtoolsTraceContext {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  traceparent: string;
+}
+
+export interface ParsedTraceparent {
+  traceId: string;
+  spanId: string;
+  traceFlags: string;
+  traceparent: string;
+}
+
+export interface DevtoolsTraceContextInput {
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+}
+
+function createHexId(length: number): string {
+  const bytes = new Uint8Array(length / 2);
+  if (typeof crypto !== "undefined" && "getRandomValues" in crypto) {
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
+      "",
+    );
+  }
+
+  let value = "";
+  while (value.length < length) {
+    value += Math.floor(Math.random() * 16).toString(16);
+  }
+  return value.slice(0, length);
+}
+
+function isNonZeroHex(value: string): boolean {
+  return !/^0+$/.test(value);
+}
+
+export function createTraceId(): string {
+  let traceId = createHexId(32);
+  while (!isNonZeroHex(traceId)) {
+    traceId = createHexId(32);
+  }
+  return traceId;
+}
+
+export function createSpanId(): string {
+  let spanId = createHexId(16);
+  while (!isNonZeroHex(spanId)) {
+    spanId = createHexId(16);
+  }
+  return spanId;
+}
+
+export function createTraceparent(args: {
+  traceId: string;
+  spanId: string;
+  traceFlags?: string;
+}): string {
+  return `00-${args.traceId}-${args.spanId}-${args.traceFlags ?? "01"}`;
+}
+
+export function parseTraceparent(
+  value: string | null | undefined,
+): ParsedTraceparent | undefined {
+  if (!value) return undefined;
+  const normalized = value.trim().toLowerCase();
+  const match = TRACEPARENT_PATTERN.exec(normalized);
+  if (!match) return undefined;
+
+  const [, traceId, spanId, traceFlags] = match;
+  if (!isNonZeroHex(traceId) || !isNonZeroHex(spanId)) return undefined;
+
+  return {
+    traceId,
+    spanId,
+    traceFlags,
+    traceparent: normalized,
+  };
+}
+
+export function createDevtoolsTraceContext(
+  input: DevtoolsTraceContextInput = {},
+): DevtoolsTraceContext {
+  const parsed = parseTraceparent(input.traceparent);
+  const traceId = input.traceId ?? parsed?.traceId ?? createTraceId();
+  const parentSpanId = input.parentSpanId ?? parsed?.spanId;
+  const spanId = input.spanId ?? createSpanId();
+
+  return {
+    traceId,
+    spanId,
+    ...(parentSpanId ? { parentSpanId } : {}),
+    traceparent: createTraceparent({
+      traceId,
+      spanId,
+      traceFlags: parsed?.traceFlags,
+    }),
+  };
+}
+
+export function createChildDevtoolsTraceContext(
+  parent: DevtoolsTraceContextInput,
+): DevtoolsTraceContext {
+  return createDevtoolsTraceContext({
+    traceId: parent.traceId,
+    parentSpanId: parent.spanId,
+    traceparent: parent.traceparent,
+  });
+}