@graphty/remote-logger 0.0.1 → 1.2.0

package/src/server/dual-server.ts

@@ -0,0 +1,308 @@
+/**
+ * Dual server orchestration for running HTTP and MCP interfaces simultaneously.
+ *
+ * This module provides a unified way to start both HTTP and MCP servers
+ * that share the same log storage instance.
+ * @module server/dual-server
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type * as http from "http";
+import type * as https from "https";
+import * as net from "net";
+import * as os from "os";
+import * as path from "path";
+
+import { createMcpServer } from "../mcp/mcp-server.js";
+import { JsonlWriter } from "./jsonl-writer.js";
+import { createLogServer } from "./log-server.js";
+import { LogStorage, type ServerMode } from "./log-storage.js";
+import { certFilesExist } from "./self-signed-cert.js";
+
+// ANSI color codes for terminal output
+const colors = {
+    reset: "\x1b[0m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    cyan: "\x1b[36m",
+};
+
+/** Maximum number of ports to try when scanning for available port */
+const MAX_PORT_SCAN_ATTEMPTS = 100;
+
+/** Maximum port number allowed (ports 9000-9099 per project guidelines) */
+const MAX_PORT_NUMBER = 9099;
+
+/**
+ * Check if a port is available for binding.
+ * @param port - Port number to check
+ * @param host - Host to bind to
+ * @returns Promise resolving to true if port is available, false otherwise
+ */
+async function isPortAvailable(port: number, host: string): Promise<boolean> {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+
+        // Enable SO_REUSEADDR to allow faster port reuse after server shutdown
+        server.once("error", (err: NodeJS.ErrnoException) => {
+            if (err.code === "EADDRINUSE") {
+                resolve(false);
+            } else {
+                // Other errors (permission, etc.) - port is not usable
+                resolve(false);
+            }
+        });
+
+        server.once("listening", () => {
+            server.close(() => {
+                resolve(true);
+            });
+        });
+
+        // Set SO_REUSEADDR before binding
+        server.listen({ port, host, exclusive: false });
+    });
+}
+
+/**
+ * Find an available port starting from the given base port.
+ * Increments port number until an available port is found.
+ * @param basePort - Starting port number
+ * @param host - Host to bind to
+ * @param quiet - Suppress output messages
+ * @returns Promise resolving to available port number
+ * @throws Error if no available port found within MAX_PORT_SCAN_ATTEMPTS
+ */
+export async function findAvailablePort(basePort: number, host: string, quiet: boolean = false): Promise<number> {
+    let port = basePort;
+    let attempts = 0;
+
+    while (attempts < MAX_PORT_SCAN_ATTEMPTS) {
+        if (port > MAX_PORT_NUMBER) {
+            // Wrap around if we exceed max port (shouldn't happen normally)
+            break;
+        }
+
+        if (await isPortAvailable(port, host)) {
+            if (port !== basePort && !quiet) {
+                // eslint-disable-next-line no-console
+                console.log(
+                    `${colors.yellow}Port ${basePort} in use, using port ${port} instead${colors.reset}`,
+                );
+            }
+            return port;
+        }
+
+        if (!quiet && attempts === 0) {
+            // eslint-disable-next-line no-console
+            console.log(
+                `${colors.yellow}Port ${port} is already in use, scanning for available port...${colors.reset}`,
+            );
+        }
+
+        port++;
+        attempts++;
+    }
+
+    // No available port found
+    const errorMsg = `Could not find available port after ${MAX_PORT_SCAN_ATTEMPTS} attempts starting from ${basePort}. ` +
+        `Ports ${basePort}-${port - 1} are all in use. ` +
+        `Try killing existing processes: pkill -f "remote-log-server"`;
+
+    if (!quiet) {
+         
+        console.error(`${colors.red}${errorMsg}${colors.reset}`);
+    }
+
+    throw new Error(errorMsg);
+}
+
+/**
+ * Options for creating a dual server.
+ */
+export interface DualServerOptions {
+    /** Port for HTTP server (default: 9080) */
+    httpPort?: number;
+    /** Host for HTTP server (default: localhost) */
+    httpHost?: string;
+    /** Enable MCP server (default: true) */
+    mcpEnabled?: boolean;
+    /** Enable HTTP server (default: true) */
+    httpEnabled?: boolean;
+    /** Suppress terminal output (default: false) */
+    quiet?: boolean;
+    /** Path to SSL certificate file (HTTPS only used if both certPath and keyPath provided) */
+    certPath?: string;
+    /** Path to SSL private key file (HTTPS only used if both certPath and keyPath provided) */
+    keyPath?: string;
+    /** Path to file for writing logs (optional) */
+    logFile?: string;
+    /** External LogStorage instance (optional, will create one if not provided) */
+    storage?: LogStorage;
+    /** External JSONL writer instance (optional, will create one if not provided) */
+    jsonlWriter?: JsonlWriter;
+    /** Only serve /log POST and /health GET endpoints (default: false) */
+    logReceiveOnly?: boolean;
+}
+
+/**
+ * Result of creating a dual server.
+ */
+export interface DualServerResult {
+    /** HTTP or HTTPS server instance (if httpEnabled) */
+    httpServer?: http.Server | https.Server;
+    /** MCP server instance (if mcpEnabled) */
+    mcpServer?: McpServer;
+    /** Shared log storage instance */
+    storage: LogStorage;
+    /** JSONL writer instance */
+    jsonlWriter?: JsonlWriter;
+    /** Actual HTTP port used (may differ from requested if port was in use) */
+    httpPort?: number;
+    /** Graceful shutdown function */
+    shutdown: () => Promise<void>;
+}
+
+/**
+ * Create and start a dual server with HTTP and/or MCP interfaces.
+ *
+ * By default, both HTTP and MCP are enabled. Use httpEnabled/mcpEnabled
+ * to control which interfaces to start.
+ * @param options - Server configuration options
+ * @returns Promise resolving to the dual server result
+ */
+export async function createDualServer(options: DualServerOptions = {}): Promise<DualServerResult> {
+    const {
+        httpPort: requestedPort = 9080,
+        httpHost = "localhost",
+        mcpEnabled = true,
+        httpEnabled = true,
+        quiet = false,
+        storage: externalStorage,
+        jsonlWriter: externalJsonlWriter,
+        logReceiveOnly = false,
+        certPath,
+        keyPath,
+    } = options;
+
+    // Create or use provided JSONL writer
+    const jsonlBaseDir = path.join(os.tmpdir(), "remote-logger");
+    const jsonlWriter = externalJsonlWriter ?? new JsonlWriter(jsonlBaseDir);
+
+    // Create or use provided storage
+    const storage = externalStorage ?? new LogStorage({ jsonlWriter });
+
+    let httpServer: http.Server | https.Server | undefined;
+    let mcpServer: McpServer | undefined;
+    let actualHttpPort: number | undefined;
+
+    // Start HTTP server if enabled
+    if (httpEnabled) {
+        // Find an available port starting from the requested port
+        actualHttpPort = await findAvailablePort(requestedPort, httpHost, quiet);
+
+        const result = createLogServer({
+            port: actualHttpPort,
+            host: httpHost,
+            storage,
+            quiet,
+            logReceiveOnly,
+            certPath,
+            keyPath,
+        });
+        httpServer = result.server;
+
+        // Wait for HTTP server to be listening
+        const serverToStart = httpServer;
+        const portToUse = actualHttpPort;
+        await new Promise<void>((resolve, reject) => {
+            serverToStart.on("error", (err: NodeJS.ErrnoException) => {
+                // Provide helpful error message for port conflicts
+                if (err.code === "EADDRINUSE") {
+                    const errorMsg = `Port ${portToUse} is already in use. ` +
+                        `This shouldn't happen after port scanning - there may be a race condition. ` +
+                        `Try again or kill existing processes: pkill -f "remote-log-server"`;
+                    if (!quiet) {
+                         
+                        console.error(`${colors.red}${errorMsg}${colors.reset}`);
+                    }
+                    reject(new Error(errorMsg));
+                } else {
+                    reject(err);
+                }
+            });
+            serverToStart.listen({ port: portToUse, host: httpHost, exclusive: false }, () => {
+                serverToStart.removeListener("error", reject);
+                if (!quiet) {
+                    // eslint-disable-next-line no-console
+                    console.log(
+                        `${colors.green}HTTP server listening on ${httpHost}:${portToUse}${colors.reset}`,
+                    );
+                }
+                resolve();
+            });
+        });
+
+        // Set server config in storage so MCP tools can report it
+        // Determine protocol based on whether valid cert files were provided
+        const useHttps = certPath && keyPath && certFilesExist(certPath, keyPath);
+        const protocol = useHttps ? "https" : "http";
+        // Determine mode based on configuration
+        let mode: ServerMode;
+        if (logReceiveOnly && mcpEnabled) {
+            mode = "mcp-only";
+        } else if (!mcpEnabled) {
+            mode = "http-only";
+        } else {
+            mode = "dual";
+        }
+        storage.setServerConfig({
+            httpPort: actualHttpPort,
+            httpHost,
+            protocol,
+            httpEndpoint: `${protocol}://${httpHost}:${actualHttpPort}/log`,
+            mode,
+        });
+    }
+
+    // Create and connect MCP server if enabled
+    if (mcpEnabled) {
+        mcpServer = createMcpServer(storage);
+        const transport = new StdioServerTransport();
+        await mcpServer.connect(transport);
+    }
+
+    // Track if we created the JSONL writer internally
+    const ownsJsonlWriter = !externalJsonlWriter;
+
+    // Shutdown function
+    const shutdown = async (): Promise<void> => {
+        // Close HTTP server
+        if (httpServer?.listening) {
+            await new Promise<void>((resolve) => {
+                httpServer.close(() => { resolve(); });
+            });
+        }
+
+        // Close JSONL writer only if we created it internally
+        if (ownsJsonlWriter) {
+            await jsonlWriter.close();
+        }
+
+        // Stop cleanup timer if storage was created internally
+        if (!externalStorage) {
+            storage.stopCleanupTimer();
+        }
+    };
+
+    return {
+        httpServer,
+        mcpServer,
+        storage,
+        jsonlWriter,
+        httpPort: actualHttpPort,
+        shutdown,
+    };
+}

package/src/server/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Server-side logging utilities.
+ * These are only meant to be run in Node.js, not in the browser.
+ * @module server
+ */
+
+export {
+    createDualServer,
+    type DualServerOptions,
+    type DualServerResult,
+} from "./dual-server.js";
+export {
+    type FileStats,
+    type JsonlEntry,
+    JsonlWriter,
+} from "./jsonl-writer.js";
+export {
+    clearLogs,
+    createLogServer,
+    type CreateLogServerOptions,
+    type CreateLogServerResult,
+    getJsonlWriter,
+    getLogStorage,
+    HELP_TEXT,
+    type LogEntry,
+    type LogServerOptions,
+    main,
+    parseArgs,
+    type ParseArgsResult,
+    setLogStorage,
+    startLogServer,
+} from "./log-server.js";
+export {
+    type AddLogsOptions,
+    type ClearFilter,
+    type HealthStatus,
+    type LogEntryWithSession,
+    type LogFilter,
+    LogStorage,
+    type LogStorageOptions,
+    type SearchOptions,
+    type ServerConfig,
+    type ServerMode,
+    type ServerStatus,
+    type SessionFilter,
+    type SessionMetadata,
+} from "./log-storage.js";
+export {
+    extractMarkerFromPath,
+    extractMarkerFromSessionId,
+    type MarkerResolutionOptions,
+    resolveProjectMarker,
+} from "./marker-utils.js";
+export { certFilesExist, type GeneratedCert, generateSelfSignedCert, readCertFiles } from "./self-signed-cert.js";

package/src/server/jsonl-writer.ts

@@ -0,0 +1,277 @@
+/**
+ * JSONL file writer for streaming logs to disk.
+ *
+ * Organizes logs by project marker in the temp directory:
+ * {baseDir}/{marker}/logs.jsonl
+ * @module server/jsonl-writer
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * A JSONL log entry.
+ */
+export interface JsonlEntry {
+    /** ISO 8601 timestamp when the log was created */
+    time: string;
+    /** Log level (e.g., "INFO", "DEBUG", "WARN", "ERROR") */
+    level: string;
+    /** The log message */
+    message: string;
+    /** Session ID this log belongs to */
+    sessionId: string;
+    /** Optional additional data */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * File statistics.
+ */
+export interface FileStats {
+    /** Whether the file exists */
+    exists: boolean;
+    /** File size in bytes */
+    size: number;
+}
+
+/**
+ * Internal state for a marker's file handle.
+ */
+interface MarkerState {
+    /** File descriptor */
+    fd: number;
+    /** Pending writes buffer */
+    buffer: string[];
+    /** Write lock to serialize writes */
+    writeLock: Promise<void>;
+}
+
+/**
+ * JSONL file writer that streams log entries to disk.
+ *
+ * Each project marker gets its own log file in the structure:
+ * {baseDir}/{marker}/logs.jsonl
+ */
+export class JsonlWriter {
+    private readonly baseDir: string;
+    private readonly markerStates = new Map<string, MarkerState>();
+    private closed = false;
+
+    /**
+     * Create a new JsonlWriter.
+     * @param baseDir - Base directory for log files (e.g., os.tmpdir()/remote-logger)
+     */
+    constructor(baseDir: string) {
+        this.baseDir = baseDir;
+    }
+
+    /**
+     * Get the file path for a project marker.
+     * @param projectMarker - The project marker
+     * @returns Full path to the JSONL file
+     */
+    getFilePath(projectMarker: string): string {
+        return path.join(this.baseDir, projectMarker, "logs.jsonl");
+    }
+
+    /**
+     * Get file statistics for a project marker's log file.
+     * @param projectMarker - The project marker
+     * @returns File stats or null if file doesn't exist
+     */
+    getFileStats(projectMarker: string): FileStats | null {
+        const filePath = this.getFilePath(projectMarker);
+
+        try {
+            const stats = fs.statSync(filePath);
+            return {
+                exists: true,
+                size: stats.size,
+            };
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Write a log entry to the appropriate file.
+     * @param projectMarker - The project marker
+     * @param entry - The log entry to write
+     * @returns Promise that resolves when the write is queued
+     */
+    write(projectMarker: string, entry: JsonlEntry): Promise<void> {
+        if (this.closed) {
+            return Promise.resolve();
+        }
+
+        const state = this.ensureMarkerState(projectMarker);
+        const line = `${JSON.stringify(entry)}\n`;
+
+        // Add to buffer and trigger write
+        state.buffer.push(line);
+
+        // Chain the write to maintain order
+        state.writeLock = state.writeLock.then(() => {
+            this.flushBuffer(state);
+        });
+
+        return Promise.resolve();
+    }
+
+    /**
+     * Flush all pending writes to disk.
+     */
+    async flush(): Promise<void> {
+        const flushPromises: Promise<void>[] = [];
+
+        for (const state of this.markerStates.values()) {
+            // Wait for pending writes and flush buffer
+            flushPromises.push(state.writeLock.then(() => {
+                this.flushBuffer(state);
+            }));
+        }
+
+        await Promise.all(flushPromises);
+
+        // Sync all file descriptors
+        for (const state of this.markerStates.values()) {
+            try {
+                fs.fsyncSync(state.fd);
+            } catch {
+                // Ignore sync errors
+            }
+        }
+    }
+
+    /**
+     * Close all file handles.
+     */
+    async close(): Promise<void> {
+        if (this.closed) {
+            return;
+        }
+
+        this.closed = true;
+
+        // Flush all pending writes
+        await this.flush();
+
+        // Close all file handles
+        for (const state of this.markerStates.values()) {
+            try {
+                fs.closeSync(state.fd);
+            } catch {
+                // Ignore close errors
+            }
+        }
+
+        this.markerStates.clear();
+    }
+
+    /**
+     * Ensure the marker state exists, creating file if needed.
+     * @param projectMarker - The project marker
+     * @returns The marker state
+     */
+    private ensureMarkerState(projectMarker: string): MarkerState {
+        let state = this.markerStates.get(projectMarker);
+
+        if (!state) {
+            const filePath = this.getFilePath(projectMarker);
+            const dir = path.dirname(filePath);
+
+            // Create directory if it doesn't exist
+            fs.mkdirSync(dir, { recursive: true });
+
+            // Open file for appending
+            const fd = fs.openSync(filePath, "a");
+
+            state = {
+                fd,
+                buffer: [],
+                writeLock: Promise.resolve(),
+            };
+
+            this.markerStates.set(projectMarker, state);
+        }
+
+        return state;
+    }
+
+    /**
+     * Flush the buffer for a marker state.
+     * @param state - The marker state to flush
+     */
+    private flushBuffer(state: MarkerState): void {
+        if (state.buffer.length === 0) {
+            return;
+        }
+
+        // Take all buffered entries
+        const toWrite = state.buffer.join("");
+        state.buffer = [];
+
+        // Write to file
+        fs.writeSync(state.fd, toWrite);
+    }
+
+    /**
+     * Clean up old project log files based on directory modification time.
+     * Removes entire project directories that haven't been modified within the retention period.
+     * @param retentionDays - Number of days to retain logs
+     * @returns Number of project directories removed
+     */
+    cleanupOldFiles(retentionDays: number): number {
+        // Check if base directory exists
+        if (!fs.existsSync(this.baseDir)) {
+            return 0;
+        }
+
+        const cutoffTime = new Date();
+        cutoffTime.setDate(cutoffTime.getDate() - retentionDays);
+        const cutoffMs = cutoffTime.getTime();
+
+        let removed = 0;
+
+        try {
+            const entries = fs.readdirSync(this.baseDir, { withFileTypes: true });
+
+            for (const entry of entries) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+
+                const dirPath = path.join(this.baseDir, entry.name);
+
+                try {
+                    const stats = fs.statSync(dirPath);
+
+                    // Check if directory is older than retention period
+                    if (stats.mtimeMs < cutoffMs) {
+                        // Close file handle if we have one open for this marker
+                        const state = this.markerStates.get(entry.name);
+                        if (state) {
+                            try {
+                                fs.closeSync(state.fd);
+                            } catch {
+                                // Ignore close errors
+                            }
+                            this.markerStates.delete(entry.name);
+                        }
+
+                        // Remove the directory
+                        fs.rmSync(dirPath, { recursive: true, force: true });
+                        removed++;
+                    }
+                } catch {
+                    // Ignore errors for individual directories
+                }
+            }
+        } catch {
+            // Ignore errors reading base directory
+        }
+
+        return removed;
+    }
+}