@grest-ts/ipc 0.0.5

package/src/common/IPCSocket.ts

@@ -0,0 +1,251 @@
+import WebSocket from 'ws';
+import {GGLog} from "@grest-ts/logger";
+import {GGLocator} from "@grest-ts/locator";
+
+export enum IPCMessageType {
+    MSG = 'm',
+    REQ = 'r',
+    RES = 's'
+}
+
+export interface IPCMessage {
+    type: IPCMessageType;
+    id: string;
+    path: string;
+    data?: unknown;
+}
+
+export type IPCMessageHandler = (data: unknown) => void | Promise<void>;
+export type IPCRequestHandler = (data: unknown) => Promise<unknown>;
+
+interface PendingRequest {
+    resolve: (data: unknown) => void;
+    reject: (error: Error) => void;
+    timeout: NodeJS.Timeout;
+}
+
+export class IPCSocket {
+
+    private readonly ws: WebSocket;
+    private readonly messageHandlers: Map<string, IPCMessageHandler> = new Map();
+    private readonly requestHandlers: Map<string, IPCRequestHandler> = new Map();
+    private readonly pendingRequests: Map<string, PendingRequest> = new Map();
+
+    private requestIdCounter = 0;
+    private active = true;
+
+    private readonly closeCallbacks: Array<() => void> = [];
+    private readonly errorCallbacks: Array<(error: Error) => void> = [];
+
+    constructor(ws: WebSocket) {
+        this.ws = ws;
+        const scope = GGLocator.getScope();
+
+        ws.on('message', async (data: Buffer) => {
+            scope.ensureEntered();
+            await this.handleRawMessage(data.toString('utf8'));
+        });
+
+        ws.on('close', () => {
+            scope.ensureEntered();
+            this.active = false;
+            for (const pending of this.pendingRequests.values()) {
+                clearTimeout(pending.timeout);
+                pending.reject(new Error('Connection closed'));
+            }
+            this.pendingRequests.clear();
+            this.closeCallbacks.forEach(cb => {
+                try {
+                    cb();
+                } catch (e) { /* ignore */
+                }
+            });
+        });
+
+        ws.on('error', (error: Error) => {
+            scope.ensureEntered();
+            this.errorCallbacks.forEach(cb => {
+                try {
+                    cb(error);
+                } catch (e) { /* ignore */
+                }
+            });
+        });
+    }
+
+    private static DELIMITER = ':';
+
+    private static serialize(msg: IPCMessage): string {
+        const dataStr = msg.data !== undefined ? JSON.stringify(msg.data) : '';
+        return `${msg.type}${this.DELIMITER}${msg.id}${this.DELIMITER}${msg.path}${this.DELIMITER}${dataStr}`;
+    }
+
+    private static parse(raw: string): IPCMessage | undefined {
+        const parts = raw.split(this.DELIMITER);
+        if (parts.length < 3) return undefined;
+
+        const type = parts[0] as IPCMessageType;
+        const id = parts[1];
+        const path = parts[2];
+        const dataStr = parts.length > 3 ? parts.slice(3).join(this.DELIMITER) : '';
+
+        let data: unknown;
+        if (dataStr) {
+            try {
+                data = JSON.parse(dataStr);
+            } catch {
+                // Invalid JSON
+            }
+        }
+
+        return {type, id, path, data};
+    }
+
+    private async handleRawMessage(raw: string): Promise<void> {
+        const msg = IPCSocket.parse(raw);
+        if (!msg) {
+            GGLog.warn(this, `Invalid IPC message: ${raw.substring(0, 100)}`);
+            return;
+        }
+
+        switch (msg.type) {
+            case IPCMessageType.MSG:
+                await this.handleIncomingMessage(msg);
+                break;
+            case IPCMessageType.REQ:
+                await this.handleIncomingRequest(msg);
+                break;
+            case IPCMessageType.RES:
+                this.handleIncomingResponse(msg);
+                break;
+        }
+    }
+
+    private async handleIncomingMessage(msg: IPCMessage): Promise<void> {
+        const handler = this.messageHandlers.get(msg.path);
+        if (!handler) {
+            GGLog.debug(this, `No handler for message: ${msg.path}`);
+            return;
+        }
+        try {
+            await handler(msg.data);
+        } catch (error) {
+            GGLog.error(this, `Message handler error for ${msg.path}`, error);
+        }
+    }
+
+    private async handleIncomingRequest(msg: IPCMessage): Promise<void> {
+        const handler = this.requestHandlers.get(msg.path);
+
+        const sendResponse = (success: boolean, data?: unknown, error?: string) => {
+            if (this.ws.readyState === WebSocket.OPEN) {
+                const response: IPCMessage = {
+                    type: IPCMessageType.RES,
+                    id: msg.id,
+                    path: msg.path,
+                    data: {success, data, error}
+                };
+                this.ws.send(IPCSocket.serialize(response));
+            }
+        };
+
+        if (!handler) {
+            sendResponse(false, undefined, `No handler for: ${msg.path}`);
+            return;
+        }
+
+        try {
+            const result = await handler(msg.data);
+            sendResponse(true, result);
+        } catch (error: any) {
+            GGLog.error(this, `Request handler error for ${msg.path}`, error);
+            sendResponse(false, undefined, error.message || String(error));
+        }
+    }
+
+    private handleIncomingResponse(msg: IPCMessage): void {
+        const pending = this.pendingRequests.get(msg.id);
+        if (!pending) {
+            GGLog.debug(this, `No pending request for response id: ${msg.id}`);
+            return;
+        }
+
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(msg.id);
+
+        const response = msg.data as { success: boolean; data?: unknown; error?: string };
+        if (response.success) {
+            pending.resolve(response.data);
+        } else {
+            pending.reject(new Error(response.error || 'Request failed'));
+        }
+    }
+
+    public onMessage(path: string, handler: IPCMessageHandler): void {
+        this.messageHandlers.set(path, handler);
+    }
+
+    public onRequest(path: string, handler: IPCRequestHandler): void {
+        this.requestHandlers.set(path, handler);
+    }
+
+    public onClose(callback: () => void): void {
+        this.closeCallbacks.push(callback);
+    }
+
+    public onError(callback: (error: Error) => void): void {
+        this.errorCallbacks.push(callback);
+    }
+
+    public send(path: string, data?: unknown): void {
+        if (!this.active || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('Socket not connected');
+        }
+        const msg: IPCMessage = {type: IPCMessageType.MSG, id: '', path, data};
+        this.ws.send(IPCSocket.serialize(msg));
+    }
+
+    public async request<T = unknown>(path: string, data?: unknown, timeoutMs: number = 10000): Promise<T> {
+        if (!this.active || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('Socket not connected');
+        }
+
+        const id = `${++this.requestIdCounter}`;
+        const msg: IPCMessage = {type: IPCMessageType.REQ, id, path, data};
+
+        return new Promise<T>((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request '${path}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+
+            this.pendingRequests.set(id, {
+                resolve: resolve as (data: unknown) => void,
+                reject,
+                timeout
+            });
+
+            this.ws.send(IPCSocket.serialize(msg));
+        });
+    }
+
+    public isConnected(): boolean {
+        return this.active && this.ws.readyState === WebSocket.OPEN;
+    }
+
+    public close(): void {
+        if (this.active) {
+            this.active = false;
+            this.ws.terminate();
+        }
+    }
+
+    public teardown(): void {
+        for (const pending of this.pendingRequests.values()) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error('Socket teardown'));
+        }
+        this.pendingRequests.clear();
+        this.close();
+    }
+}

package/src/common/IPCTypes.ts

@@ -0,0 +1,17 @@
+/**
+ * Type for messages that the IPC server handles (sent by client, handled by server)
+ */
+export type IPCServerRequest<Request, Response> = string & {
+    __IPCServerRequest: never;
+    __request: Request;
+    __response: Response;
+}
+
+/**
+ * Type for messages that the IPC client handles (sent by server, handled by client)
+ */
+export type IPCClientRequest<Request, Response> = string & {
+    __IPCClientRequest: never;
+    __request: Request;
+    __response: Response;
+}

package/src/index-node.ts

@@ -0,0 +1,6 @@
+export * from './server/IPCServer'
+export * from './client/IPCClient'
+export * from './common/IPCSocket'
+export * from './common/IPCTypes'
+export {INTERNAL_SOCKET_PATH} from './server/SocketHandler'
+export type {SocketMessage} from './server/SocketHandler'

package/src/server/HttpHandler.ts

@@ -0,0 +1,107 @@
+import * as http from 'http';
+import {GGLog} from "@grest-ts/logger";
+import {HttpMethod} from "@grest-ts/common";
+import httpProxy from "http-proxy";
+import findMyWay, {HTTPMethod} from "find-my-way";
+
+/** HTTP route handler - receives body, path params, and headers. Returns response data (or void for empty 200) */
+export type HttpRouteHandler = (body: any, pathParams?: Record<string, string>, headers?: Record<string, string>) => Promise<any>;
+
+/** Default HTTP handler for unmatched routes (proxying) - gets raw req/res */
+export type DefaultHttpHandler = (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
+
+interface RouteStore {
+    handler: HttpRouteHandler;
+}
+
+export class HttpHandler {
+
+    private router = findMyWay<findMyWay.HTTPVersion.V1>();
+    private routeResolver: (path: string) => string
+    private readonly proxy: httpProxy;
+
+    constructor() {
+        this.proxy = httpProxy.createProxyServer({});
+    }
+
+    public setRouteResolver(routeResolver: (path: string) => string) {
+        this.routeResolver = routeResolver
+    }
+
+    public addRoute(method: HttpMethod, path: string, handler: HttpRouteHandler): void {
+        const store: RouteStore = {handler};
+        this.router.on(method as HTTPMethod, path, () => {
+        }, store);
+    }
+
+    public removeRoute(method: HttpMethod, path: string): void {
+        this.router.off(method as HTTPMethod, path);
+    }
+
+    public async handleRequest(
+        req: http.IncomingMessage,
+        res: http.ServerResponse
+    ): Promise<void> {
+        const method = (req.method || 'GET') as HttpMethod;
+        const url = req.url || '/';
+        // Strip query string for route matching
+        const path = url.split('?')[0];
+
+        // Try to match a route
+        const result = this.router.find(method as HTTPMethod, path);
+        if (result?.store) {
+            const store = result.store as RouteStore;
+            const body = await this.readJsonBody(req);
+            // Normalize headers to Record<string, string>
+            const headers: Record<string, string> = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                if (value !== undefined) {
+                    headers[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+                }
+            }
+            const pathParams = result.params as Record<string, string> || {};
+            try {
+                const responseData = await store.handler(body, pathParams, headers);
+                this.sendResponse(res, 200, responseData);
+            } catch (err: any) {
+                GGLog.error(this, `HTTP route error [${method} ${path}]: ${err.message}`, err);
+                this.sendResponse(res, 500, {error: err.message});
+            }
+            return;
+        }
+
+        const routeToUrl = this.routeResolver(path)
+        if (routeToUrl) {
+            GGLog.debug(this, `Proxying ${req.method} ${req.url} -> ${routeToUrl}`);
+            this.proxy.web(req, res, {target: routeToUrl}, (err: Error) => {
+                GGLog.error(this, "Proxy error", err);
+                this.sendResponse(res, 502, {issue: "Proxy error: " + err.message + " (Did the service crash?)"});
+            });
+            return;
+        }
+
+        this.sendResponse(res, 404, {error: `No route for ${method} ${path}! Did you forget to start a service that defines this path?`});
+    }
+
+    private async readJsonBody(req: http.IncomingMessage): Promise<any> {
+        return new Promise((resolve) => {
+            let bodyStr = '';
+            req.on('data', (chunk: Buffer) => {
+                bodyStr += chunk.toString();
+            });
+            req.on('end', () => {
+                try {
+                    resolve(bodyStr ? JSON.parse(bodyStr) : undefined);
+                } catch {
+                    resolve(undefined);
+                }
+            });
+            req.on('error', () => resolve(undefined));
+        });
+    }
+
+    private sendResponse(res: http.ServerResponse, status: number, data?: any): void {
+        res.writeHead(status, {'Content-Type': 'application/json'});
+        res.end(data !== undefined ? JSON.stringify(data) : '');
+    }
+}

package/src/server/IPCServer.ts

@@ -0,0 +1,159 @@
+import * as http from 'http';
+import * as net from 'net';
+import {GGLog} from "@grest-ts/logger";
+import {Duplex} from "stream";
+import {HttpMethod} from "@grest-ts/common";
+import {HttpHandler} from "./HttpHandler";
+import {SocketHandler, SocketMessage} from "./SocketHandler";
+import {IPCClientRequest, IPCServerRequest} from "../common/IPCTypes";
+import {GGLocator, GGLocatorScope} from "@grest-ts/locator";
+import {GGContext} from "@grest-ts/context";
+import {GG_TRACE} from "@grest-ts/trace";
+
+export class IPCServer {
+
+    private readonly httpServer: http.Server;
+    private readonly httpHandler: HttpHandler;
+    private readonly socketHandler: SocketHandler;
+
+    private readonly expectedPort: number;
+    private port: number = 0;
+    private url: string = '';
+
+    private readonly connections: Set<net.Socket> = new Set();
+
+    private readonly scope: GGLocatorScope;
+
+    constructor(port: number = 0) {
+        this.expectedPort = port;
+        this.scope = GGLocator.getScope();
+
+        // Create handlers
+        this.httpHandler = new HttpHandler();
+        this.socketHandler = new SocketHandler();
+
+        // Create HTTP server
+        this.httpServer = http.createServer(async (req, res) => {
+            await new GGContext("LocalRouter").run(async () => {
+                GG_TRACE.init();
+                await this.httpHandler.handleRequest(req, res);
+            });
+        });
+
+        // Handle WebSocket upgrades
+        // Note: Incoming TCP connections start with no async context (they originate from libuv/OS layer).
+        this.httpServer.on('upgrade', async (req, socket, head) => {
+            this.scope.ensureEntered();
+            await new GGContext("LocalRouter").run(async () => {
+                GG_TRACE.init();
+                await this.socketHandler.handleUpgrade(req, socket as Duplex, head);
+            });
+        });
+
+        // Track connections for cleanup
+        this.httpServer.on('connection', (conn) => {
+            this.connections.add(conn);
+            conn.on('close', () => this.connections.delete(conn));
+        });
+    }
+
+    public static defineRequest<Req, Res>(name: string): IPCServerRequest<Req, Res> {
+        return name as IPCServerRequest<Req, Res>;
+    }
+
+    // -----------------------------------------------
+    // Lifecycle
+    // -----------------------------------------------
+
+    public async start(): Promise<boolean> {
+        return new Promise<boolean>((resolve, reject) => {
+            const errorHandler = (err: any) => {
+                if (err.code === 'EADDRINUSE') {
+                    resolve(false);
+                } else {
+                    reject(err);
+                }
+            };
+
+            this.httpServer.once('error', errorHandler);
+
+            this.httpServer.listen(this.expectedPort, '0.0.0.0', () => {
+                this.scope.ensureEntered();
+                this.port = (this.httpServer.address() as any).port;
+                this.url = `http://localhost:${this.port}`;
+                this.httpServer.removeListener('error', errorHandler);
+                GGLog.info(this, `Internal server started on port ${this.port}`);
+                resolve(true);
+            });
+        });
+    }
+
+    public async teardown(): Promise<void> {
+        // Teardown socket handler (closes clients and WSS)
+        await this.socketHandler.teardown();
+
+        // Close all HTTP connections
+        this.connections.forEach(conn => conn.destroy());
+        this.connections.clear();
+
+        // Close the server
+        await new Promise<void>((resolve, reject) => {
+            this.httpServer.close((err) => {
+                this.scope.ensureEntered();
+                if (err) reject(err);
+                else resolve();
+            });
+        });
+
+        GGLog.info(this, 'Internal server stopped');
+    }
+
+    // -----------------------------------------------
+    // Handling http/socket requests that services send between each other. Can intercept http here.
+    // -----------------------------------------------
+
+    public interceptHttp(method: HttpMethod, path: string, handler: (body: any, pathParams?: Record<string, string>, headers?: Record<string, string>) => Promise<any>): void {
+        this.httpHandler.addRoute(method, path, handler);
+    }
+
+    public removeInterceptHttp(method: HttpMethod, path: string): void {
+        this.httpHandler.removeRoute(method, path);
+    }
+
+    public setRouteProxyResolver(resolver: (path: string) => string) {
+        this.httpHandler.setRouteResolver(resolver);
+        this.socketHandler.setRouteResolver(resolver);
+    }
+
+    // -----------------------------------------------
+    // Grest Framework internal messaging between either local discovery server or local test server.
+    // -----------------------------------------------
+
+    public onFrameworkMessage<Req, Res>(
+        type: IPCServerRequest<Req, Res>,
+        handler: (payload: Req, msg: SocketMessage) => Promise<Res>
+    ): void {
+        this.socketHandler.onMessage(type, async (msg) => handler(msg.data as Req, msg));
+    }
+
+    public async sendFrameworkMessage<Req, Res>(
+        runtimeId: string,
+        type: IPCClientRequest<Req, Res>,
+        payload: Req,
+        timeoutMs?: number
+    ): Promise<Res> {
+        return this.socketHandler.request<Res>(runtimeId, type, payload, timeoutMs);
+    }
+
+    // -----------------------------------------------
+    // Accessors
+    // -----------------------------------------------
+
+    public getPort(): number {
+        return this.port;
+    }
+
+    public getUrl(): string {
+        return this.url;
+    }
+}

package/src/server/SocketHandler.ts

@@ -0,0 +1,146 @@
+import * as http from 'http';
+import {WebSocket, WebSocketServer} from 'ws';
+import {GGLog} from "@grest-ts/logger";
+import {Duplex} from "stream";
+import {IPCSocket} from "../common/IPCSocket";
+import httpProxy from "http-proxy";
+
+export const INTERNAL_SOCKET_PATH = '/__ggFrameworkConnection';
+
+export type WsUpgradeHandler = (req: http.IncomingMessage, socket: Duplex, head: Buffer) => Promise<boolean>;
+export type SocketMessageHandler = (msg: SocketMessage) => Promise<unknown>;
+
+export interface SocketMessage {
+    clientId: string;
+    runtimeId?: string;
+    data: unknown;
+}
+
+interface SocketClient {
+    id: string;
+    runtimeId?: string;
+    socket: IPCSocket;
+}
+
+export class SocketHandler {
+
+    private readonly wss: WebSocketServer;
+    private readonly clients: Map<string, SocketClient> = new Map();
+    private readonly clientsByRuntimeId: Map<string, SocketClient> = new Map();
+    private readonly handlers: Map<string, SocketMessageHandler> = new Map();
+    private clientIdCounter = 0;
+
+    private routeResolver: (path: string) => string
+    private readonly proxy: httpProxy;
+
+    constructor() {
+        this.wss = new WebSocketServer({noServer: true});
+        this.proxy = httpProxy.createProxyServer({});
+    }
+
+    public setRouteResolver(routeResolver: (path: string) => string) {
+        this.routeResolver = routeResolver
+    }
+
+    public onMessage(path: string, handler: SocketMessageHandler): void {
+        this.handlers.set(path, handler);
+    }
+
+    public async handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): Promise<void> {
+        if (req.url.startsWith(INTERNAL_SOCKET_PATH)) {
+            this.wss.handleUpgrade(req, socket, head, (ws) => {
+                this.handleNewConnection(ws, req.url);
+            });
+            return;
+        }
+
+        const routeToUrl = this.routeResolver(req.url)
+        if (routeToUrl) {
+            GGLog.debug(this, `Proxying WS ${req.url} -> ${routeToUrl}`);
+            this.proxy.ws(req, socket, head, {target: routeToUrl}, (err: Error) => {
+                GGLog.error(this, `WebSocket proxy error: ${err.message}`);
+                socket.destroy();
+            });
+            return;
+        }
+
+        socket.destroy();
+    }
+
+    private handleNewConnection(ws: WebSocket, url: string): void {
+        const clientId = `client-${++this.clientIdCounter}`;
+
+        let runtimeId: string | undefined;
+        const queryStart = url.indexOf('?');
+        if (queryStart !== -1) {
+            const params = new URLSearchParams(url.substring(queryStart + 1));
+            runtimeId = params.get('runtimeId') ?? undefined;
+        }
+
+        const ipcSocket = new IPCSocket(ws);
+
+        const client: SocketClient = {id: clientId, runtimeId, socket: ipcSocket};
+        this.clients.set(clientId, client);
+        if (runtimeId) {
+            this.clientsByRuntimeId.set(runtimeId, client);
+        }
+
+        GGLog.debug(this, `Socket client connected: ${clientId}` + (runtimeId ? ` (runtimeId: ${runtimeId})` : ''));
+
+        for (const [path, handler] of this.handlers) {
+            ipcSocket.onRequest(path, async (data) => {
+                return handler({
+                    clientId: client.id,
+                    runtimeId: client.runtimeId,
+                    data
+                });
+            });
+        }
+
+        ipcSocket.onClose(() => {
+            this.clients.delete(clientId);
+            if (runtimeId) {
+                this.clientsByRuntimeId.delete(runtimeId);
+            }
+            GGLog.debug(this, `Socket client disconnected: ${clientId}`);
+        });
+
+        ipcSocket.onError((err: Error) => {
+            GGLog.debug(this, `Socket client error: ${clientId} - ${err.message}`);
+        });
+    }
+
+    public async request<T = unknown>(
+        runtimeId: string,
+        path: string,
+        data?: unknown,
+        timeoutMs: number = 10000
+    ): Promise<T> {
+        const client = this.clientsByRuntimeId.get(runtimeId);
+        if (!client) {
+            throw new Error(`No client connected with runtimeId: ${runtimeId}`);
+        }
+        return client.socket.request<T>(path, data, timeoutMs);
+    }
+
+    public send(runtimeId: string, path: string, data?: unknown): void {
+        const client = this.clientsByRuntimeId.get(runtimeId);
+        if (!client) {
+            throw new Error(`No client connected with runtimeId: ${runtimeId}`);
+        }
+        client.socket.send(path, data);
+    }
+
+    public async teardown(): Promise<void> {
+        for (const client of this.clients.values()) {
+            client.socket.teardown();
+        }
+        this.clients.clear();
+        this.clientsByRuntimeId.clear();
+        this.proxy.close();
+
+        await new Promise<void>((resolve) => {
+            this.wss.close(() => resolve());
+        });
+    }
+}