@zap-js/client 0.0.2 → 0.0.5

package/dist/runtime/ipc-client.js

@@ -0,0 +1,621 @@
+import { createServer, createConnection } from "net";
+import { unlinkSync, existsSync } from "fs";
+import { EventEmitter } from "events";
+import { encode, decode } from "@msgpack/msgpack";
+import { isAsyncIterable } from "./types.js";
+/**
+ * Serialize an IPC message to bytes
+ */
+function serializeMessage(msg, encoding) {
+    if (encoding === "msgpack") {
+        return Buffer.from(encode(msg));
+    }
+    return Buffer.from(JSON.stringify(msg));
+}
+/**
+ * Deserialize an IPC message from bytes (auto-detects encoding)
+ */
+function deserializeMessage(data) {
+    if (data.length === 0) {
+        throw new Error("Empty message");
+    }
+    // Auto-detect: JSON starts with '{' (0x7B), MessagePack maps start with 0x80-0xBF
+    const firstByte = data[0];
+    if (firstByte === 0x7b) {
+        // '{' character = JSON
+        return JSON.parse(data.toString("utf-8"));
+    }
+    // MessagePack
+    return decode(data);
+}
+/**
+ * Write a length-prefixed message to a socket
+ */
+function writeFramedMessage(socket, msg, encoding) {
+    const payload = serializeMessage(msg, encoding);
+    const length = payload.length;
+    // 4-byte big-endian length prefix
+    const lengthBuf = Buffer.alloc(4);
+    lengthBuf.writeUInt32BE(length, 0);
+    // ATOMIC: Single write with combined buffer to prevent frame corruption
+    const frame = Buffer.concat([lengthBuf, payload]);
+    socket.write(frame);
+}
+/**
+ * FrameReader - reads length-prefixed frames from a socket
+ */
+class FrameReader {
+    constructor(onFrame) {
+        this.buffer = Buffer.alloc(0);
+        this.onFrame = onFrame;
+    }
+    /**
+     * Process incoming data chunks
+     */
+    push(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        // Process complete frames
+        while (this.buffer.length >= 4) {
+            const length = this.buffer.readUInt32BE(0);
+            // Check for unreasonably large messages (100MB limit)
+            if (length > 100 * 1024 * 1024) {
+                throw new Error(`Message too large: ${length} bytes`);
+            }
+            // Wait for complete frame
+            if (this.buffer.length < 4 + length) {
+                break;
+            }
+            // Extract frame
+            const frame = this.buffer.subarray(4, 4 + length);
+            this.buffer = this.buffer.subarray(4 + length);
+            // Emit frame
+            this.onFrame(frame);
+        }
+    }
+    /**
+     * Reset the buffer
+     */
+    reset() {
+        this.buffer = Buffer.alloc(0);
+    }
+}
+/**
+ * WebSocket connection implementation for TypeScript handlers
+ */
+class WsConnectionImpl {
+    constructor(id, path, headers, handlerId, server) {
+        this.id = id;
+        this.path = path;
+        this.headers = headers;
+        this.handlerId = handlerId;
+        this.server = server;
+    }
+    /**
+     * Send a text message to the client
+     */
+    send(data) {
+        this.server.sendWsMessage(this.id, data, false);
+    }
+    /**
+     * Send binary data to the client
+     */
+    sendBinary(data) {
+        // Base64 encode binary data for IPC transport
+        const encoded = Buffer.from(data).toString("base64");
+        this.server.sendWsMessage(this.id, encoded, true);
+    }
+    /**
+     * Close the connection
+     */
+    close(code, reason) {
+        this.server.closeWsConnection(this.id, code, reason);
+    }
+}
+/**
+ * IpcServer
+ *
+ * Listens on a Unix socket for IPC messages from the Rust backend.
+ * The Rust server sends handler invocation requests, which we dispatch
+ * to the registered TypeScript handlers and send responses back.
+ *
+ * Protocol: Length-prefixed MessagePack (default) with JSON fallback
+ * Frame format: [4-byte big-endian length][payload]
+ */
+export class IpcServer {
+    constructor(socketPath, encoding = "msgpack") {
+        this.server = null;
+        this.handlers = new Map();
+        this.wsHandlers = new Map();
+        this.wsConnections = new Map();
+        this.currentSocket = null;
+        this.socketPath = socketPath;
+        this.encoding = encoding;
+    }
+    /**
+     * Register a handler function for a specific handler ID
+     */
+    registerHandler(handlerId, handler) {
+        this.handlers.set(handlerId, handler);
+    }
+    /**
+     * Register a WebSocket handler for a specific handler ID
+     */
+    registerWsHandler(handlerId, handler) {
+        this.wsHandlers.set(handlerId, handler);
+    }
+    /**
+     * Start the IPC server listening on the Unix socket
+     */
+    async start() {
+        return new Promise((resolve, reject) => {
+            try {
+                // Clean up old socket file if it exists
+                if (existsSync(this.socketPath)) {
+                    try {
+                        unlinkSync(this.socketPath);
+                    }
+                    catch {
+                        // Ignore if we can't delete it
+                    }
+                }
+                // Create Unix domain socket server
+                this.server = createServer((socket) => {
+                    this.handleConnection(socket);
+                });
+                this.server.on("error", (err) => {
+                    console.error(`[IPC] Server error:`, err);
+                    reject(err);
+                });
+                this.server.listen(this.socketPath, () => {
+                    console.log(`[IPC] IPC server listening on ${this.socketPath} (${this.encoding})`);
+                    resolve();
+                });
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Handle a new IPC connection from the Rust server
+     */
+    handleConnection(socket) {
+        console.log(`[IPC] Client connected`);
+        this.currentSocket = socket;
+        const frameReader = new FrameReader((frame) => {
+            void this.handleFrame(frame, socket);
+        });
+        socket.on("data", (chunk) => {
+            try {
+                frameReader.push(chunk);
+            }
+            catch (error) {
+                console.error(`[IPC] Frame error:`, error);
+                socket.destroy();
+            }
+        });
+        socket.on("close", () => {
+            console.log(`[IPC] Client disconnected`);
+            if (this.currentSocket === socket) {
+                this.currentSocket = null;
+            }
+            // Clean up any WebSocket connections for this socket
+            this.wsConnections.clear();
+        });
+        socket.on("error", (error) => {
+            console.error(`[IPC] Connection error:`, error);
+        });
+    }
+    /**
+     * Handle a complete frame
+     */
+    async handleFrame(frame, socket) {
+        try {
+            const message = deserializeMessage(frame);
+            await this.processMessage(message, socket);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`[IPC] Error processing message:`, errorMessage);
+            const errorResponse = {
+                type: "error",
+                code: "HANDLER_ERROR",
+                message: errorMessage,
+                status: 500,
+                digest: crypto.randomUUID(),
+            };
+            writeFramedMessage(socket, errorResponse, this.encoding);
+        }
+    }
+    /**
+     * Process an incoming IPC message
+     */
+    async processMessage(message, socket) {
+        console.log(`[IPC] Received message type: ${message.type}`);
+        if (message.type === "invoke_handler") {
+            const invokeMsg = message;
+            const { handler_id, request } = invokeMsg;
+            console.log(`[IPC] Looking for handler: ${handler_id}`);
+            console.log(`[IPC] Available handlers: ${Array.from(this.handlers.keys()).join(', ')}`);
+            const handler = this.handlers.get(handler_id);
+            if (!handler) {
+                console.error(`[IPC] Handler NOT FOUND: ${handler_id}`);
+                writeFramedMessage(socket, {
+                    type: "error",
+                    code: "HANDLER_NOT_FOUND",
+                    message: `Handler ${handler_id} not found`,
+                    status: 404,
+                    digest: crypto.randomUUID(),
+                }, this.encoding);
+                return;
+            }
+            try {
+                console.log(`[IPC] Invoking handler: ${handler_id} for ${request.method} ${request.path}`);
+                const result = handler(request);
+                // Check if this is a streaming response (async iterable)
+                if (isAsyncIterable(result)) {
+                    await this.handleStreamingResponse(result, handler_id, socket);
+                }
+                else {
+                    // Regular response - await the promise
+                    const response = await result;
+                    console.log(`[IPC] Handler result:`, JSON.stringify(response, null, 2));
+                    writeFramedMessage(socket, {
+                        type: "handler_response",
+                        handler_id,
+                        status: response.status || 200,
+                        headers: response.headers || { "content-type": "application/json" },
+                        body: response.body || "{}",
+                    }, this.encoding);
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`[IPC] Error executing handler ${handler_id}:`, errorMessage);
+                writeFramedMessage(socket, {
+                    type: "error",
+                    code: "HANDLER_EXECUTION_ERROR",
+                    message: errorMessage,
+                    status: 500,
+                    digest: crypto.randomUUID(),
+                }, this.encoding);
+            }
+            return;
+        }
+        // Health check message
+        if (message.type === "health_check") {
+            console.log(`[IPC] Health check received`);
+            writeFramedMessage(socket, { type: "health_check_response" }, this.encoding);
+            return;
+        }
+        // WebSocket connect message - new client connected
+        if (message.type === "ws_connect") {
+            const { connection_id, handler_id, path, headers } = message;
+            console.log(`[IPC] WebSocket connect: ${connection_id} for handler ${handler_id}`);
+            const wsHandler = this.wsHandlers.get(handler_id);
+            if (!wsHandler) {
+                console.error(`[IPC] WebSocket handler NOT FOUND: ${handler_id}`);
+                writeFramedMessage(socket, {
+                    type: "error",
+                    code: "WS_HANDLER_NOT_FOUND",
+                    message: `WebSocket handler ${handler_id} not found`,
+                    status: 404,
+                    digest: crypto.randomUUID(),
+                }, this.encoding);
+                return;
+            }
+            // Create connection object and store it
+            const connection = new WsConnectionImpl(connection_id, path, headers, handler_id, this);
+            this.wsConnections.set(connection_id, connection);
+            // Call onConnect if defined
+            try {
+                if (wsHandler.onConnect) {
+                    await wsHandler.onConnect(connection);
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`[IPC] WebSocket onConnect error:`, errorMessage);
+                // Close the connection on error
+                this.closeWsConnection(connection_id, 1011, errorMessage);
+            }
+            return;
+        }
+        // WebSocket message - message from client
+        if (message.type === "ws_message") {
+            const { connection_id, data, binary } = message;
+            console.log(`[IPC] WebSocket message from ${connection_id}: ${data.length} bytes (binary: ${binary})`);
+            const connection = this.wsConnections.get(connection_id);
+            if (!connection) {
+                console.error(`[IPC] WebSocket connection NOT FOUND: ${connection_id}`);
+                return;
+            }
+            // Use handler_id from the connection (set during connect)
+            const wsHandler = this.wsHandlers.get(connection.handlerId);
+            if (!wsHandler || !wsHandler.onMessage) {
+                return;
+            }
+            try {
+                let messageData;
+                if (binary) {
+                    // Decode base64 binary data
+                    messageData = Buffer.from(data, "base64");
+                }
+                else {
+                    messageData = data;
+                }
+                await wsHandler.onMessage(connection, messageData);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`[IPC] WebSocket onMessage error:`, errorMessage);
+                if (wsHandler.onError) {
+                    try {
+                        await wsHandler.onError(connection, error instanceof Error ? error : new Error(errorMessage));
+                    }
+                    catch {
+                        // Ignore errors in error handler
+                    }
+                }
+            }
+            return;
+        }
+        // WebSocket close - client disconnected
+        if (message.type === "ws_close") {
+            const { connection_id, code, reason } = message;
+            console.log(`[IPC] WebSocket close: ${connection_id} (code: ${code}, reason: ${reason})`);
+            const connection = this.wsConnections.get(connection_id);
+            if (!connection) {
+                return;
+            }
+            // Use handler_id from the connection (set during connect)
+            const wsHandler = this.wsHandlers.get(connection.handlerId);
+            if (wsHandler && wsHandler.onClose) {
+                try {
+                    await wsHandler.onClose(connection, code, reason);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    console.error(`[IPC] WebSocket onClose error:`, errorMessage);
+                }
+            }
+            // Remove from connections map
+            this.wsConnections.delete(connection_id);
+            return;
+        }
+        console.error(`[IPC] Unknown message type: ${message.type}`);
+        writeFramedMessage(socket, {
+            type: "error",
+            code: "UNKNOWN_MESSAGE_TYPE",
+            message: `Unknown message type: ${message.type}`,
+            status: 400,
+            digest: crypto.randomUUID(),
+        }, this.encoding);
+    }
+    /**
+     * Handle a streaming response from a handler
+     */
+    async handleStreamingResponse(stream, handlerId, socket) {
+        const streamId = `stream_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+        console.log(`[IPC] Starting streaming response: ${streamId}`);
+        // Send stream start message
+        writeFramedMessage(socket, {
+            type: "stream_start",
+            stream_id: streamId,
+            status: 200,
+            headers: { "content-type": "text/event-stream" },
+        }, this.encoding);
+        try {
+            // Stream chunks
+            for await (const chunk of stream) {
+                let data;
+                if (chunk.bytes) {
+                    // Binary data - base64 encode
+                    data = Buffer.from(chunk.bytes).toString("base64");
+                }
+                else if (chunk.data) {
+                    // String data - base64 encode for consistency
+                    data = Buffer.from(chunk.data, "utf-8").toString("base64");
+                }
+                else {
+                    continue; // Skip empty chunks
+                }
+                writeFramedMessage(socket, {
+                    type: "stream_chunk",
+                    stream_id: streamId,
+                    data,
+                }, this.encoding);
+            }
+            // Send stream end message
+            writeFramedMessage(socket, {
+                type: "stream_end",
+                stream_id: streamId,
+            }, this.encoding);
+            console.log(`[IPC] Streaming response completed: ${streamId}`);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`[IPC] Streaming error for ${handlerId}:`, errorMessage);
+            // Send error message
+            writeFramedMessage(socket, {
+                type: "error",
+                code: "STREAM_ERROR",
+                message: errorMessage,
+                status: 500,
+                digest: crypto.randomUUID(),
+            }, this.encoding);
+        }
+    }
+    /**
+     * Send a message to a WebSocket client via the Rust server
+     */
+    sendWsMessage(connectionId, data, binary) {
+        if (!this.currentSocket) {
+            console.error(`[IPC] Cannot send WebSocket message: no active socket`);
+            return;
+        }
+        writeFramedMessage(this.currentSocket, {
+            type: "ws_send",
+            connection_id: connectionId,
+            data,
+            binary,
+        }, this.encoding);
+    }
+    /**
+     * Close a WebSocket connection via the Rust server
+     */
+    closeWsConnection(connectionId, code, reason) {
+        // Remove from connections map
+        const connection = this.wsConnections.get(connectionId);
+        const handlerId = connection?.handlerId || "";
+        if (connection) {
+            this.wsConnections.delete(connectionId);
+        }
+        if (!this.currentSocket) {
+            console.error(`[IPC] Cannot close WebSocket connection: no active socket`);
+            return;
+        }
+        writeFramedMessage(this.currentSocket, {
+            type: "ws_close",
+            connection_id: connectionId,
+            handler_id: handlerId,
+            code,
+            reason,
+        }, this.encoding);
+    }
+    /**
+     * Stop the IPC server
+     */
+    async stop() {
+        // Close all WebSocket connections
+        for (const [connectionId] of this.wsConnections) {
+            this.closeWsConnection(connectionId, 1001, "Server shutting down");
+        }
+        this.wsConnections.clear();
+        if (this.server) {
+            return new Promise((resolve) => {
+                this.server.close(() => {
+                    // Clean up socket file
+                    if (existsSync(this.socketPath)) {
+                        try {
+                            unlinkSync(this.socketPath);
+                        }
+                        catch {
+                            // Ignore
+                        }
+                    }
+                    resolve();
+                });
+            });
+        }
+    }
+}
+/**
+ * IpcClient
+ *
+ * Connects to a Unix socket to communicate with the Rust server.
+ * Used for RPC calls from TypeScript to Rust.
+ *
+ * Protocol: Length-prefixed MessagePack (default) with JSON fallback
+ */
+export class IpcClient extends EventEmitter {
+    constructor(socketPath, encoding = "msgpack") {
+        super();
+        this.socket = null;
+        this.connected = false;
+        this.frameReader = null;
+        this.socketPath = socketPath;
+        this.encoding = encoding;
+        this.connect();
+    }
+    /**
+     * Connect to the Unix socket
+     */
+    connect() {
+        this.socket = createConnection(this.socketPath);
+        this.socket.on("connect", () => {
+            this.connected = true;
+            this.emit("connect");
+            // Set up frame reader for length-prefixed messages
+            this.frameReader = new FrameReader((frame) => {
+                try {
+                    const message = deserializeMessage(frame);
+                    this.emit("message", message);
+                }
+                catch (error) {
+                    this.emit("error", new Error(`Failed to deserialize message: ${error}`));
+                }
+            });
+        });
+        this.socket.on("data", (chunk) => {
+            if (this.frameReader) {
+                try {
+                    this.frameReader.push(chunk);
+                }
+                catch (error) {
+                    this.emit("error", error);
+                }
+            }
+        });
+        this.socket.on("error", (err) => {
+            this.connected = false;
+            this.emit("error", err);
+        });
+        this.socket.on("close", () => {
+            this.connected = false;
+            this.emit("close");
+        });
+    }
+    /**
+     * Send a message to the server
+     */
+    send(message) {
+        if (!this.socket || !this.connected) {
+            throw new Error("IPC client not connected");
+        }
+        writeFramedMessage(this.socket, message, this.encoding);
+    }
+    /**
+     * Send a message and wait for response
+     */
+    async sendRecv(message) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error("IPC request timeout"));
+            }, 30000);
+            const handler = (response) => {
+                clearTimeout(timeout);
+                this.removeListener("message", handler);
+                resolve(response);
+            };
+            this.on("message", handler);
+            this.send(message);
+        });
+    }
+    /**
+     * Close the connection
+     */
+    async close() {
+        this.frameReader = null;
+        if (this.socket) {
+            return new Promise((resolve) => {
+                this.socket.once("close", resolve);
+                this.socket.end();
+            });
+        }
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Get the encoding being used
+     */
+    getEncoding() {
+        return this.encoding;
+    }
+}
+// Export serialization utilities for testing
+export { serializeMessage, deserializeMessage, FrameReader };

package/dist/runtime/logger.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Structured JSON Logger for ZapJS
+ *
+ * Provides consistent JSON logging with request context.
+ * Used across the TypeScript runtime for observability.
+ */
+export interface LogContext {
+    request_id?: string;
+    handler_id?: string;
+    method?: string;
+    path?: string;
+    duration_ms?: number;
+    status?: number;
+    [key: string]: unknown;
+}
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+declare class Logger {
+    private jsonFormat;
+    private minLevel;
+    constructor();
+    private shouldLog;
+    private formatEntry;
+    private log;
+    trace(message: string, context?: LogContext): void;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext, error?: Error): void;
+    /**
+     * Create a child logger with pre-set context
+     */
+    child(baseContext: LogContext): ChildLogger;
+    /**
+     * Set JSON format mode
+     */
+    setJsonFormat(enabled: boolean): void;
+    /**
+     * Set minimum log level
+     */
+    setMinLevel(level: LogLevel): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): {
+        jsonFormat: boolean;
+        minLevel: LogLevel;
+    };
+}
+/**
+ * Child logger with inherited base context
+ */
+declare class ChildLogger {
+    private parent;
+    private baseContext;
+    constructor(parent: Logger, baseContext: LogContext);
+    private mergeContext;
+    trace(message: string, context?: LogContext): void;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext, error?: Error): void;
+    /**
+     * Create a further nested child logger
+     */
+    child(additionalContext: LogContext): ChildLogger;
+}
+/**
+ * Global logger instance
+ */
+export declare const logger: Logger;
+export { Logger, ChildLogger };