@webda/debug 4.0.0-beta.3

package/lib/requestlog.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The body of a captured request or response.
+ *
+ * - `text`: text payload that fit entirely within the configured size limit.
+ * - `text-truncated`: text payload truncated at the size limit; `content` is the prefix and `size` is the total byte count.
+ * - `binary`: binary payload — only `size` and a short hex `preview` are kept.
+ * - `empty`: no body at all.
+ */
+export type RequestLogBody = {
+    kind: "text";
+    content: string;
+    size: number;
+} | {
+    kind: "text-truncated";
+    content: string;
+    size: number;
+} | {
+    kind: "binary";
+    size: number;
+    preview: string;
+} | {
+    kind: "empty";
+};
+/**
+ * Captured error attached to a request, when one was thrown.
+ */
+export interface RequestLogError {
+    message: string;
+    stack?: string;
+}
+/**
+ * A single entry in the request log
+ */
+export interface RequestLogEntry {
+    id: string;
+    method: string;
+    url: string;
+    timestamp: number;
+    statusCode?: number;
+    duration?: number;
+    /** Captured request headers (lowercased keys, single string values). */
+    requestHeaders?: Record<string, string>;
+    /** Captured request body. */
+    requestBody?: RequestLogBody;
+    /** Captured response headers (single string values). */
+    responseHeaders?: Record<string, string>;
+    /** Captured response body. */
+    responseBody?: RequestLogBody;
+    /** Captured error, if the request failed. */
+    error?: RequestLogError;
+}
+/**
+ * Summary fields returned by the list endpoint — keep this cheap (no bodies, no headers).
+ */
+export type RequestLogSummary = Pick<RequestLogEntry, "id" | "method" | "url" | "timestamp" | "statusCode" | "duration">;
+/**
+ * Optional details that can be attached to an existing entry after capture.
+ */
+export interface RequestLogDetails {
+    requestHeaders?: Record<string, string>;
+    requestBody?: RequestLogBody;
+    responseHeaders?: Record<string, string>;
+    responseBody?: RequestLogBody;
+    error?: RequestLogError;
+}
+/**
+ * Events emitted by the RequestLog for request lifecycle changes
+ */
+export type RequestLogEvent = {
+    type: "request";
+    id: string;
+    method: string;
+    url: string;
+    timestamp: number;
+} | {
+    type: "result";
+    id: string;
+    statusCode: number;
+    duration: number;
+} | {
+    type: "404";
+    id: string;
+    method: string;
+    url: string;
+};
+type EventCallback = (event: RequestLogEvent) => void;
+/**
+ * A fixed-size ring buffer that tracks HTTP requests and pushes lifecycle events to subscribers.
+ *
+ * When the buffer is full, the oldest entry is evicted to make room for the new one.
+ */
+export declare class RequestLog {
+    private maxSize;
+    private entries;
+    private index;
+    private subscribers;
+    /**
+     * Creates a new RequestLog.
+     *
+     * @param maxSize - Maximum number of entries to retain before evicting the oldest. Defaults to 1000.
+     */
+    constructor(maxSize?: number);
+    /**
+     * Records the start of an incoming HTTP request.
+     *
+     * If the buffer is at capacity the oldest entry is removed first.
+     * A `"request"` event is pushed to all subscribers.
+     *
+     * @param id - Unique identifier for the request.
+     * @param method - HTTP method (e.g. "GET", "POST").
+     * @param url - Request URL.
+     */
+    startRequest(id: string, method: string, url: string): void;
+    /**
+     * Records the completion of a previously started request.
+     *
+     * Updates the entry with the final status code and duration, then pushes a
+     * `"result"` event to all subscribers. Does nothing if the id is unknown.
+     *
+     * @param id - Unique identifier of the request.
+     * @param statusCode - HTTP response status code.
+     * @param duration - Request duration in milliseconds.
+     */
+    completeRequest(id: string, statusCode: number, duration: number): void;
+    /**
+     * Marks a previously started request as a 404 Not Found response.
+     *
+     * Updates the entry's status code to 404 and pushes a `"404"` event to all
+     * subscribers. Does nothing if the id is unknown.
+     *
+     * @param id - Unique identifier of the request.
+     */
+    markNotFound(id: string): void;
+    /**
+     * Attach captured headers, bodies, and/or error details to an existing entry.
+     *
+     * Merges the provided fields onto the entry. Does nothing (silently) if the
+     * id is unknown — the caller should call this only after `startRequest`.
+     *
+     * @param id - Unique identifier of the request.
+     * @param details - Captured details to attach.
+     */
+    attachDetails(id: string, details: RequestLogDetails): void;
+    /**
+     * Returns a shallow copy of all currently stored entries in insertion order.
+     *
+     * Includes any captured headers, bodies, and error details.
+     *
+     * @returns Array of {@link RequestLogEntry} objects.
+     */
+    getEntries(): RequestLogEntry[];
+    /**
+     * Returns lightweight summaries of all stored entries — no headers or bodies.
+     *
+     * Use this for the list view; use {@link getEntry} when the user drills in.
+     *
+     * @returns Array of {@link RequestLogSummary} objects in insertion order.
+     */
+    getSummaries(): RequestLogSummary[];
+    /**
+     * Look up a single entry by id.
+     *
+     * @param id - Unique identifier of the request.
+     * @returns The entry, or `undefined` if not found.
+     */
+    getEntry(id: string): RequestLogEntry | undefined;
+    /**
+     * Registers a callback that will be invoked for every future log event.
+     *
+     * @param callback - Function called with each {@link RequestLogEvent}.
+     * @returns An unsubscribe function. Call it to stop receiving events.
+     */
+    onEvent(callback: EventCallback): () => void;
+    /**
+     * Dispatches an event to all current subscribers.
+     *
+     * @param event - The event to dispatch.
+     */
+    private notify;
+}
+export {};

package/lib/requestlog.js

@@ -0,0 +1,153 @@
+/**
+ * A fixed-size ring buffer that tracks HTTP requests and pushes lifecycle events to subscribers.
+ *
+ * When the buffer is full, the oldest entry is evicted to make room for the new one.
+ */
+export class RequestLog {
+    /**
+     * Creates a new RequestLog.
+     *
+     * @param maxSize - Maximum number of entries to retain before evicting the oldest. Defaults to 1000.
+     */
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+        this.entries = [];
+        this.index = new Map();
+        this.subscribers = new Set();
+    }
+    /**
+     * Records the start of an incoming HTTP request.
+     *
+     * If the buffer is at capacity the oldest entry is removed first.
+     * A `"request"` event is pushed to all subscribers.
+     *
+     * @param id - Unique identifier for the request.
+     * @param method - HTTP method (e.g. "GET", "POST").
+     * @param url - Request URL.
+     */
+    startRequest(id, method, url) {
+        const entry = { id, method, url, timestamp: Date.now() };
+        if (this.entries.length >= this.maxSize) {
+            const removed = this.entries.shift();
+            if (removed)
+                this.index.delete(removed.id);
+        }
+        this.entries.push(entry);
+        this.index.set(id, entry);
+        this.notify({ type: "request", id, method, url, timestamp: entry.timestamp });
+    }
+    /**
+     * Records the completion of a previously started request.
+     *
+     * Updates the entry with the final status code and duration, then pushes a
+     * `"result"` event to all subscribers. Does nothing if the id is unknown.
+     *
+     * @param id - Unique identifier of the request.
+     * @param statusCode - HTTP response status code.
+     * @param duration - Request duration in milliseconds.
+     */
+    completeRequest(id, statusCode, duration) {
+        const entry = this.index.get(id);
+        if (!entry)
+            return;
+        entry.statusCode = statusCode;
+        entry.duration = duration;
+        this.notify({ type: "result", id, statusCode, duration });
+    }
+    /**
+     * Marks a previously started request as a 404 Not Found response.
+     *
+     * Updates the entry's status code to 404 and pushes a `"404"` event to all
+     * subscribers. Does nothing if the id is unknown.
+     *
+     * @param id - Unique identifier of the request.
+     */
+    markNotFound(id) {
+        const entry = this.index.get(id);
+        if (!entry)
+            return;
+        entry.statusCode = 404;
+        this.notify({ type: "404", id, method: entry.method, url: entry.url });
+    }
+    /**
+     * Attach captured headers, bodies, and/or error details to an existing entry.
+     *
+     * Merges the provided fields onto the entry. Does nothing (silently) if the
+     * id is unknown — the caller should call this only after `startRequest`.
+     *
+     * @param id - Unique identifier of the request.
+     * @param details - Captured details to attach.
+     */
+    attachDetails(id, details) {
+        const entry = this.index.get(id);
+        if (!entry)
+            return;
+        if (details.requestHeaders !== undefined)
+            entry.requestHeaders = details.requestHeaders;
+        if (details.requestBody !== undefined)
+            entry.requestBody = details.requestBody;
+        if (details.responseHeaders !== undefined)
+            entry.responseHeaders = details.responseHeaders;
+        if (details.responseBody !== undefined)
+            entry.responseBody = details.responseBody;
+        if (details.error !== undefined)
+            entry.error = details.error;
+    }
+    /**
+     * Returns a shallow copy of all currently stored entries in insertion order.
+     *
+     * Includes any captured headers, bodies, and error details.
+     *
+     * @returns Array of {@link RequestLogEntry} objects.
+     */
+    getEntries() {
+        return [...this.entries];
+    }
+    /**
+     * Returns lightweight summaries of all stored entries — no headers or bodies.
+     *
+     * Use this for the list view; use {@link getEntry} when the user drills in.
+     *
+     * @returns Array of {@link RequestLogSummary} objects in insertion order.
+     */
+    getSummaries() {
+        return this.entries.map(e => ({
+            id: e.id,
+            method: e.method,
+            url: e.url,
+            timestamp: e.timestamp,
+            statusCode: e.statusCode,
+            duration: e.duration
+        }));
+    }
+    /**
+     * Look up a single entry by id.
+     *
+     * @param id - Unique identifier of the request.
+     * @returns The entry, or `undefined` if not found.
+     */
+    getEntry(id) {
+        return this.index.get(id);
+    }
+    /**
+     * Registers a callback that will be invoked for every future log event.
+     *
+     * @param callback - Function called with each {@link RequestLogEvent}.
+     * @returns An unsubscribe function. Call it to stop receiving events.
+     */
+    onEvent(callback) {
+        this.subscribers.add(callback);
+        return () => this.subscribers.delete(callback);
+    }
+    /**
+     * Dispatches an event to all current subscribers.
+     *
+     * @param event - The event to dispatch.
+     */
+    notify(event) {
+        for (const cb of this.subscribers) {
+            cb(event);
+        }
+    }
+}
+//# sourceMappingURL=requestlog.js.map

package/lib/requestlog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestlog.js","sourceRoot":"","sources":["../src/requestlog.ts"],"names":[],"mappings":"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"}

package/lib/tui/client.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Event types received over the WebSocket connection.
+ */
+export type WsEvent = {
+    type: "request";
+    id: string;
+    method: string;
+    url: string;
+    timestamp: number;
+} | {
+    type: "result";
+    id: string;
+    statusCode: number;
+    duration: number;
+} | {
+    type: "404";
+    id: string;
+    method: string;
+    url: string;
+} | {
+    type: "restart";
+} | {
+    type: "log";
+    level: string;
+    message: string;
+    timestamp: number;
+};
+/**
+ * Callback for WebSocket events.
+ */
+export type WsEventCallback = (event: WsEvent) => void;
+/**
+ * HTTP + WebSocket client for the debug server API.
+ *
+ * Connects to the debug server started by `webda debug` and provides
+ * typed methods for each introspection endpoint, plus a reconnecting
+ * WebSocket subscription for live request events.
+ */
+export declare class DebugClient {
+    /** Base URL for HTTP requests (no trailing slash) */
+    private baseUrl;
+    /** Active WebSocket connection */
+    private ws?;
+    /** Whether the client should try to reconnect */
+    private shouldReconnect;
+    /** Current reconnect delay in ms */
+    private reconnectDelay;
+    /** Maximum reconnect delay in ms */
+    private maxReconnectDelay;
+    /** Event subscribers */
+    private subscribers;
+    /** Reconnect timer handle */
+    private reconnectTimer?;
+    /** Connection status */
+    private _connected;
+    /**
+     * Creates a new DebugClient.
+     *
+     * @param baseUrl - Base URL of the debug server, e.g. "http://localhost:18181"
+     */
+    constructor(baseUrl?: string);
+    /**
+     * Whether the WebSocket is currently connected.
+     * @returns true if the WebSocket connection is open
+     */
+    get connected(): boolean;
+    /**
+     * Fetch parsed JSON from a debug API endpoint.
+     *
+     * @param path - API path starting with /
+     * @returns Parsed JSON response
+     */
+    private fetchJson;
+    /**
+     * Fetch all registered models.
+     * @returns array of model metadata objects
+     */
+    getModels(): Promise<any[]>;
+    /**
+     * Fetch a single model by identifier.
+     *
+     * @param id - Fully-qualified model identifier
+     * @returns model metadata object
+     */
+    getModel(id: string): Promise<any>;
+    /**
+     * Fetch all registered services.
+     * @returns array of service info objects
+     */
+    getServices(): Promise<any[]>;
+    /**
+     * Fetch all registered operations.
+     * @returns array of operation info objects
+     */
+    getOperations(): Promise<any[]>;
+    /**
+     * Fetch all registered routes.
+     * @returns array of route info objects
+     */
+    getRoutes(): Promise<any[]>;
+    /**
+     * Fetch the resolved application configuration.
+     * @returns resolved configuration record
+     */
+    getConfig(): Promise<Record<string, any>>;
+    /**
+     * Fetch the OpenAPI specification.
+     * @returns OpenAPI 3.0.3 document
+     */
+    getOpenAPI(): Promise<Record<string, any>>;
+    /**
+     * Fetch recent request log entries (summary fields only — no headers/bodies).
+     * @returns array of request log entry summaries
+     */
+    getRequests(): Promise<any[]>;
+    /**
+     * Fetch the full detail of a single request by id, including captured
+     * headers, bodies, and any error.
+     *
+     * @param id - The request id (as returned in the summary list).
+     * @returns The detailed request entry.
+     */
+    getRequestDetail(id: string): Promise<any>;
+    /**
+     * Fetch recent application log entries.
+     * @returns array of log entries
+     */
+    getLogs(): Promise<any[]>;
+    /**
+     * Fetch application info (package name, version, working directory).
+     * @returns project information record
+     */
+    getAppInfo(): Promise<any>;
+    /**
+     * Search application log entries by query string.
+     *
+     * @param query - search text to filter logs
+     * @returns array of matching log entries
+     */
+    searchLogs(query: string): Promise<any[]>;
+    /**
+     * Subscribe to WebSocket events.
+     *
+     * @param callback - Called for each event received
+     * @returns Unsubscribe function
+     */
+    onEvent(callback: WsEventCallback): () => void;
+    /**
+     * Connect to the debug server WebSocket and begin receiving events.
+     * Automatically reconnects with exponential backoff on disconnect.
+     */
+    connectWebSocket(): void;
+    /**
+     * Internal: establish the WebSocket connection.
+     */
+    private doConnect;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+    /**
+     * Disconnect the WebSocket and stop reconnecting.
+     */
+    disconnect(): void;
+}