ee-core 4.1.5 → 5.0.0-beta.5

package/dist/cjs/socket/httpServer.d.ts

@@ -0,0 +1,74 @@
+import Koa from 'koa';
+import type { HttpServerConfig } from '../types/index.js';
+/**
+ * HttpServer - HTTP server
+ *
+ * Created using factory pattern (static create()), because initialization requires async port acquisition.
+ * When enable=false in config, the service will not start after creation.
+ */
+export declare class HttpServer {
+    /** HTTP server configuration */
+    config: HttpServerConfig;
+    /** Koa application instance */
+    httpApp: Koa | undefined;
+    /** Channel separator */
+    channelSeparator: string;
+    private constructor();
+    /**
+     * Factory method: create and initialize HttpServer
+     *
+     * @returns Fully initialized HttpServer instance
+     */
+    static create(): Promise<HttpServer>;
+    /**
+     * Initialize HTTP server
+     *
+     * Acquires an available port then creates a Koa application and starts listening.
+     * The port number is written to process.env.EE_HTTP_PORT for other modules to access.
+     */
+    init(): Promise<void>;
+    /**
+     * Create Koa application and start HTTP/HTTPS service
+     *
+     * Loads middleware in order, handles HTTPS configuration, and starts listening.
+     */
+    _create(): Promise<void>;
+    /**
+     * Core routing dispatch middleware
+     *
+     * Maps HTTP request paths to controller methods:
+     * 1. Remove leading '/' from path
+     * 2. Check if path is in filter list (e.g., favicon.ico)
+     * 3. Ensure path starts with 'controller'
+     * 4. Find and call controller method via resolveControllerFn
+     * 5. GET requests pass query params, POST requests pass body params
+     *
+     * Error handling: When controller method throws an exception, returns 500 + { error: 'Internal Server Error' }
+     */
+    _dispatch(ctx: Koa.Context, next: Koa.Next): Promise<void>;
+    /**
+     * Get Koa application instance
+     *
+     * @returns Koa instance, or undefined if HTTP service is not enabled
+     */
+    getHttpApp(): Koa | undefined;
+    /**
+     * Set up Koa error handler
+     *
+     * @param app - Koa application instance
+     * @param errorHandler - Error handler function that receives an Error parameter
+     */
+    _setupErrorHandler(app: Koa, errorHandler: ((err: Error) => void) | null): void;
+    /**
+     * Load pre/post middleware
+     *
+     * Middleware can be factory functions (called to return Koa middleware) or direct middleware functions.
+     * Invalid middleware will be skipped with a warning.
+     *
+     * @param app - Koa application instance
+     * @param middlewares - Middleware array
+     * @param type - Type identifier (pre/post), used for warning messages
+     */
+    _loadMiddlewares(app: Koa, middlewares?: unknown[], type?: string): void;
+}
+//# sourceMappingURL=httpServer.d.ts.map

package/dist/cjs/socket/httpServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpServer.d.ts","sourceRoot":"","sources":["../../../src/socket/httpServer.ts"],"names":[],"mappings":"AAsBA,OAAO,GAAG,MAAM,KAAK,CAAC;AAWtB,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,mBAAmB,CAAC;AAKrE;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,gCAAgC;IAChC,MAAM,EAAE,gBAAgB,CAAC;IACzB,+BAA+B;IAC/B,OAAO,EAAE,GAAG,GAAG,SAAS,CAAC;IACzB,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,CAAC;IAEzB,OAAO;IAOP;;;;OAIG;WACU,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC;IAM1C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4D9B;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA+ChE;;;;OAIG;IACH,UAAU,IAAI,GAAG,GAAG,SAAS;IAI7B;;;;;OAKG;IACH,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAM/E;;;;;;;;;OASG;IACH,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,GAAE,OAAO,EAAO,EAAE,IAAI,SAAQ,GAAG,IAAI;CAY5E"}

package/dist/cjs/socket/httpServer.js

@@ -0,0 +1,240 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpServer = void 0;
+/**
+ * @module socket/httpServer
+ * @description HTTP/HTTPS server. Provides RESTful API services based on the Koa framework,
+ * routing HTTP requests to corresponding controller methods.
+ *
+ * Request routing rules:
+ * - URL path maps to controller path, e.g., /controller/user/add → controller.user.add
+ * - GET request parameters from query, POST request parameters from body
+ * - Paths starting with 'controller' are used directly, otherwise 'controller' prefix is added automatically
+ * - URIs in filterRequest return specified data directly without going through controllers
+ *
+ * Middleware loading order:
+ * 1. Error handler (errorHandler)
+ * 2. Pre-middleware (preMiddleware)
+ * 3. CORS cross-origin middleware
+ * 4. koa-body request body parsing middleware
+ * 5. Core routing dispatch middleware (_dispatch)
+ * 6. Post-middleware (postMiddleware)
+ */
+const debug_1 = __importDefault(require("debug"));
+const assert_1 = __importDefault(require("assert"));
+const type_check_js_1 = require("../utils/type_check.js");
+const koa_1 = __importDefault(require("koa"));
+const koa2_cors_1 = __importDefault(require("koa2-cors"));
+const koa_body_1 = __importDefault(require("koa-body"));
+const https_1 = __importDefault(require("https"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const index_js_1 = require("../log/index.js");
+const index_js_2 = require("../ps/index.js");
+const index_js_3 = require("../controller/index.js");
+const index_js_4 = require("../config/index.js");
+const index_js_5 = require("../utils/port/index.js");
+const utils_js_1 = require("./utils.js");
+const debugLog = (0, debug_1.default)('ee-core:socket:httpServer');
+/**
+ * HttpServer - HTTP server
+ *
+ * Created using factory pattern (static create()), because initialization requires async port acquisition.
+ * When enable=false in config, the service will not start after creation.
+ */
+class HttpServer {
+    constructor() {
+        const config = (0, index_js_4.getConfig)();
+        this.config = config.httpServer;
+        this.channelSeparator = config.mainServer.channelSeparator || '/';
+        this.httpApp = undefined;
+    }
+    /**
+     * Factory method: create and initialize HttpServer
+     *
+     * @returns Fully initialized HttpServer instance
+     */
+    static async create() {
+        const instance = new HttpServer();
+        await instance.init();
+        return instance;
+    }
+    /**
+     * Initialize HTTP server
+     *
+     * Acquires an available port then creates a Koa application and starts listening.
+     * The port number is written to process.env.EE_HTTP_PORT for other modules to access.
+     */
+    async init() {
+        if (this.config.enable === false) {
+            return;
+        }
+        const port = await (0, index_js_5.getPort)({ port: this.config.port });
+        if (!port) {
+            throw new Error('[ee-core] [socket/HttpServer] http port required, and must be a number !');
+        }
+        process.env.EE_HTTP_PORT = String(port);
+        this.config.port = port;
+        this._create();
+    }
+    /**
+     * Create Koa application and start HTTP/HTTPS service
+     *
+     * Loads middleware in order, handles HTTPS configuration, and starts listening.
+     */
+    async _create() {
+        const config = this.config;
+        const koaConfig = config.koaConfig || {};
+        const preMiddleware = koaConfig.preMiddleware || [];
+        const postMiddleware = koaConfig.postMiddleware || [];
+        const errorHandler = koaConfig.errorHandler || null;
+        const isHttps = config.https.enable === true;
+        const sslOptions = {};
+        if (isHttps) {
+            config.protocol = 'https://';
+            const httpsConfig = config.https;
+            const keyFile = path_1.default.join((0, index_js_2.getBaseDir)(), httpsConfig.key);
+            const certFile = path_1.default.join((0, index_js_2.getBaseDir)(), httpsConfig.cert);
+            (0, assert_1.default)(fs_1.default.existsSync(keyFile), 'ssl key file is required');
+            (0, assert_1.default)(fs_1.default.existsSync(certFile), 'ssl cert file is required');
+            sslOptions.key = fs_1.default.readFileSync(keyFile);
+            sslOptions.cert = fs_1.default.readFileSync(certFile);
+        }
+        const url = config.protocol + config.host + ':' + config.port;
+        const corsOptions = config.cors;
+        const koaApp = new koa_1.default();
+        // Set up error handler for unified error code handling
+        this._setupErrorHandler(koaApp, errorHandler);
+        // Load pre-middleware
+        this._loadMiddlewares(koaApp, preMiddleware, 'pre');
+        // Core middleware
+        koaApp.use((0, koa2_cors_1.default)(corsOptions));
+        koaApp.use((0, koa_body_1.default)(config.body));
+        koaApp.use(this._dispatch.bind(this));
+        // Load post-middleware
+        this._loadMiddlewares(koaApp, postMiddleware, 'post');
+        let msg = '[socket/http] server is: ' + url;
+        const listenOpt = { host: config.host, port: config.port };
+        if (isHttps) {
+            const server = https_1.default.createServer(sslOptions, koaApp.callback());
+            server.on('error', (err) => {
+                index_js_1.coreLogger.error(`[socket/http] https server error: ${err.message}`);
+            });
+            server.listen(listenOpt, () => {
+                index_js_1.coreLogger.info(msg);
+            });
+        }
+        else {
+            const server = koaApp.listen(listenOpt, () => {
+                index_js_1.coreLogger.info(msg);
+            });
+            server.on('error', (err) => {
+                index_js_1.coreLogger.error(`[socket/http] http server error: ${err.message}`);
+            });
+        }
+        this.httpApp = koaApp;
+    }
+    /**
+     * Core routing dispatch middleware
+     *
+     * Maps HTTP request paths to controller methods:
+     * 1. Remove leading '/' from path
+     * 2. Check if path is in filter list (e.g., favicon.ico)
+     * 3. Ensure path starts with 'controller'
+     * 4. Find and call controller method via resolveControllerFn
+     * 5. GET requests pass query params, POST requests pass body params
+     *
+     * Error handling: When controller method throws an exception, returns 500 + { error: 'Internal Server Error' }
+     */
+    async _dispatch(ctx, next) {
+        const controller = (0, index_js_3.getController)();
+        const { filterRequest } = (0, index_js_4.getConfig)().httpServer;
+        let uriPath = ctx.request.path;
+        const method = ctx.request.method;
+        let params = ctx.request.query;
+        // Deep copy query object to avoid Express/Koa proxy object issues
+        params = (0, type_check_js_1.isObject)(params) ? JSON.parse(JSON.stringify(params)) : {};
+        const body = ctx.request.body;
+        ctx.response.status = 200;
+        try {
+            // Remove leading '/'
+            if (uriPath.indexOf('/') === 0) {
+                uriPath = uriPath.substring(1);
+            }
+            // Filter requests that don't need routing
+            if (filterRequest.uris.includes(uriPath)) {
+                ctx.response.body = filterRequest.returnData;
+                await next();
+                return;
+            }
+            // Automatically add 'controller' prefix
+            if (uriPath.slice(0, 10) !== 'controller') {
+                uriPath = 'controller/' + uriPath;
+            }
+            const cmd = uriPath.split('/').join(this.channelSeparator);
+            debugLog('[request] uri %s', cmd);
+            // GET uses query, POST uses body
+            const args = method === 'POST' ? body : params;
+            const fn = (0, utils_js_1.resolveControllerFn)(controller, cmd, this.channelSeparator);
+            if (!fn)
+                throw new Error('function not exists');
+            const result = await fn.call(controller, args, ctx);
+            ctx.response.body = result;
+        }
+        catch (err) {
+            index_js_1.coreLogger.error('[httpServer] throw error:', err);
+            ctx.response.status = 500;
+            ctx.response.body = { error: 'Internal Server Error' };
+            // Attach original error to ctx for downstream error-reporting middleware
+            ctx.__ee_error = err;
+        }
+        await next();
+    }
+    /**
+     * Get Koa application instance
+     *
+     * @returns Koa instance, or undefined if HTTP service is not enabled
+     */
+    getHttpApp() {
+        return this.httpApp;
+    }
+    /**
+     * Set up Koa error handler
+     *
+     * @param app - Koa application instance
+     * @param errorHandler - Error handler function that receives an Error parameter
+     */
+    _setupErrorHandler(app, errorHandler) {
+        if ((0, type_check_js_1.isFunction)(errorHandler)) {
+            app.on('error', errorHandler);
+        }
+    }
+    /**
+     * Load pre/post middleware
+     *
+     * Middleware can be factory functions (called to return Koa middleware) or direct middleware functions.
+     * Invalid middleware will be skipped with a warning.
+     *
+     * @param app - Koa application instance
+     * @param middlewares - Middleware array
+     * @param type - Type identifier (pre/post), used for warning messages
+     */
+    _loadMiddlewares(app, middlewares = [], type = 'pre') {
+        if ((0, type_check_js_1.isArray)(middlewares)) {
+            middlewares.forEach((middleware) => {
+                if ((0, type_check_js_1.isFunction)(middleware)) {
+                    // middleware is a factory function, called to return (ctx, next) => {} style middleware
+                    app.use(middleware());
+                }
+                else {
+                    index_js_1.coreLogger.warn(`[ee-core/httpServer] Invalid ${type} middleware detected, skipping.`);
+                }
+            });
+        }
+    }
+}
+exports.HttpServer = HttpServer;
+//# sourceMappingURL=httpServer.js.map

package/dist/cjs/socket/httpServer.js.map

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

package/dist/cjs/socket/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module socket
+ * @description Communication service module entry point. Provides creation and management of three communication modes:
+ *
+ * - SocketServer: SocketIO server for third-party software communication via WebSocket
+ * - HttpServer: HTTP/HTTPS server for RESTful API calls
+ * - IpcServer: Electron IPC server for renderer process communication via ipcRenderer
+ *
+ * Usage:
+ * - loadSocket(): Called during framework startup to create and initialize all communication services
+ * - getSocketServer() / getHttpServer() / getIpcServer(): Get service instances
+ */
+export { SocketServer } from './socketServer.js';
+export { HttpServer } from './httpServer.js';
+export { IpcServer } from './ipcServer.js';
+import { Server as IoServer } from 'socket.io';
+import IoClient from 'socket.io-client';
+import Koa from 'koa';
+import { SocketServer } from './socketServer.js';
+import { HttpServer } from './httpServer.js';
+import { IpcServer } from './ipcServer.js';
+export { Koa, IoServer, IoClient };
+/**
+ * Create SocketIO server
+ *
+ * @returns SocketServer instance
+ */
+export declare function createSocketServer(): Promise<SocketServer>;
+/**
+ * Get SocketIO server instance
+ */
+export declare function getSocketServer(): SocketServer | null;
+/**
+ * Create HTTP server
+ *
+ * @returns HttpServer instance
+ */
+export declare function createHttpServer(): Promise<HttpServer>;
+/**
+ * Get HTTP server instance
+ */
+export declare function getHttpServer(): HttpServer | null;
+/**
+ * Create IPC server
+ *
+ * @returns IpcServer instance
+ */
+export declare function createIpcServer(): IpcServer;
+/**
+ * Get IPC server instance
+ */
+export declare function getIpcServer(): IpcServer | null;
+/**
+ * Load and initialize all communication services
+ *
+ * Created in order: SocketIO → HTTP → IPC
+ * Called by Application.run() during the framework startup flow.
+ */
+export declare function loadSocket(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/socket/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,QAAQ,MAAM,kBAAkB,CAAC;AACxC,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAanC;;;;GAIG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAGhE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,UAAU,CAAC,CAG5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAG3C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAE/C;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAIhD"}

package/dist/cjs/socket/index.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IoClient = exports.IoServer = exports.Koa = exports.IpcServer = exports.HttpServer = exports.SocketServer = void 0;
+exports.createSocketServer = createSocketServer;
+exports.getSocketServer = getSocketServer;
+exports.createHttpServer = createHttpServer;
+exports.getHttpServer = getHttpServer;
+exports.createIpcServer = createIpcServer;
+exports.getIpcServer = getIpcServer;
+exports.loadSocket = loadSocket;
+/**
+ * @module socket
+ * @description Communication service module entry point. Provides creation and management of three communication modes:
+ *
+ * - SocketServer: SocketIO server for third-party software communication via WebSocket
+ * - HttpServer: HTTP/HTTPS server for RESTful API calls
+ * - IpcServer: Electron IPC server for renderer process communication via ipcRenderer
+ *
+ * Usage:
+ * - loadSocket(): Called during framework startup to create and initialize all communication services
+ * - getSocketServer() / getHttpServer() / getIpcServer(): Get service instances
+ */
+var socketServer_js_1 = require("./socketServer.js");
+Object.defineProperty(exports, "SocketServer", { enumerable: true, get: function () { return socketServer_js_1.SocketServer; } });
+var httpServer_js_1 = require("./httpServer.js");
+Object.defineProperty(exports, "HttpServer", { enumerable: true, get: function () { return httpServer_js_1.HttpServer; } });
+var ipcServer_js_1 = require("./ipcServer.js");
+Object.defineProperty(exports, "IpcServer", { enumerable: true, get: function () { return ipcServer_js_1.IpcServer; } });
+const socket_io_1 = require("socket.io");
+Object.defineProperty(exports, "IoServer", { enumerable: true, get: function () { return socket_io_1.Server; } });
+const socket_io_client_1 = __importDefault(require("socket.io-client"));
+exports.IoClient = socket_io_client_1.default;
+const koa_1 = __importDefault(require("koa"));
+exports.Koa = koa_1.default;
+const socketServer_js_2 = require("./socketServer.js");
+const httpServer_js_2 = require("./httpServer.js");
+const ipcServer_js_2 = require("./ipcServer.js");
+/** Service instance storage */
+const Instance = {
+    socketServer: null,
+    httpServer: null,
+    ipcServer: null,
+};
+/**
+ * Create SocketIO server
+ *
+ * @returns SocketServer instance
+ */
+async function createSocketServer() {
+    Instance.socketServer = await socketServer_js_2.SocketServer.create();
+    return Instance.socketServer;
+}
+/**
+ * Get SocketIO server instance
+ */
+function getSocketServer() {
+    return Instance.socketServer;
+}
+/**
+ * Create HTTP server
+ *
+ * @returns HttpServer instance
+ */
+async function createHttpServer() {
+    Instance.httpServer = await httpServer_js_2.HttpServer.create();
+    return Instance.httpServer;
+}
+/**
+ * Get HTTP server instance
+ */
+function getHttpServer() {
+    return Instance.httpServer;
+}
+/**
+ * Create IPC server
+ *
+ * @returns IpcServer instance
+ */
+function createIpcServer() {
+    Instance.ipcServer = new ipcServer_js_2.IpcServer();
+    return Instance.ipcServer;
+}
+/**
+ * Get IPC server instance
+ */
+function getIpcServer() {
+    return Instance.ipcServer;
+}
+/**
+ * Load and initialize all communication services
+ *
+ * Created in order: SocketIO → HTTP → IPC
+ * Called by Application.run() during the framework startup flow.
+ */
+async function loadSocket() {
+    await createSocketServer();
+    await createHttpServer();
+    createIpcServer();
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/socket/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":";;;;;;AAyCA,gDAGC;AAKD,0CAEC;AAOD,4CAGC;AAKD,sCAEC;AAOD,0CAGC;AAKD,oCAEC;AAQD,gCAIC;AAjGD;;;;;;;;;;;GAWG;AACH,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AACrB,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAElB,yCAA+C;AAOjC,yFAPK,kBAAQ,OAOL;AANtB,wEAAwC;AAMhB,mBANjB,0BAAQ,CAMiB;AALhC,8CAAsB;AAKb,cALF,aAAG,CAKE;AAJZ,uDAAiD;AACjD,mDAA6C;AAC7C,iDAA2C;AAI3C,+BAA+B;AAC/B,MAAM,QAAQ,GAIV;IACF,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;IAChB,SAAS,EAAE,IAAI;CAChB,CAAC;AAEF;;;;GAIG;AACI,KAAK,UAAU,kBAAkB;IACtC,QAAQ,CAAC,YAAY,GAAG,MAAM,8BAAY,CAAC,MAAM,EAAE,CAAC;IACpD,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe;IAC7B,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,gBAAgB;IACpC,QAAQ,CAAC,UAAU,GAAG,MAAM,0BAAU,CAAC,MAAM,EAAE,CAAC;IAChD,OAAO,QAAQ,CAAC,UAAU,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa;IAC3B,OAAO,QAAQ,CAAC,UAAU,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe;IAC7B,QAAQ,CAAC,SAAS,GAAG,IAAI,wBAAS,EAAE,CAAC;IACrC,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,UAAU;IAC9B,MAAM,kBAAkB,EAAE,CAAC;IAC3B,MAAM,gBAAgB,EAAE,CAAC;IACzB,eAAe,EAAE,CAAC;AACpB,CAAC"}

package/dist/cjs/socket/ipcServer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * IpcServer - IPC server
+ *
+ * Traverses the controller object tree and registers ipcMain channel handlers for each exported method.
+ * Uses recursive loop() to traverse nested controller directory structures.
+ */
+export declare class IpcServer {
+    /** Channel separator, default '/' */
+    channelSeparator: string;
+    /** Controller directory name (used to generate property path prefix) */
+    directory: string;
+    constructor();
+    /**
+     * Initialize: traverse controller tree and register all IPC channels
+     */
+    init(): void;
+    /**
+     * Recursively traverse the controller object tree
+     *
+     * Distinguished by EXPORTS symbol marker:
+     * - Objects with EXPORTS marker → leaf nodes (controller method collections), call register()
+     * - Objects without marker → intermediate nodes (directory/namespace), continue recursion
+     *
+     * @param obj - Current object being traversed
+     * @param pathname - Current property path
+     */
+    loop(obj: Record<string, unknown>, pathname: string): void;
+    /**
+     * Register controller methods as IPC channel handlers
+     *
+     * Registers two handlers for each method:
+     * 1. ipcMain.on (synchronous model): Sets event.returnValue, supports async methods
+     * 2. ipcMain.handle (asynchronous model): Returns Promise, recommended
+     *
+     * @param exportObj - Controller method collection object
+     * @param propertyChain - Property path (e.g., 'controller.user')
+     */
+    register(exportObj: Record<string, unknown>, propertyChain: string): void;
+}
+//# sourceMappingURL=ipcServer.d.ts.map

package/dist/cjs/socket/ipcServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipcServer.d.ts","sourceRoot":"","sources":["../../../src/socket/ipcServer.ts"],"names":[],"mappings":"AA4BA;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;;IAQlB;;OAEG;IACH,IAAI,IAAI,IAAI;IAKZ;;;;;;;;;OASG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAgB1D;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;CAiC1E"}

package/dist/cjs/socket/ipcServer.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IpcServer = void 0;
+/**
+ * @module socket/ipcServer
+ * @description Electron IPC server. Registers controller methods as IPC channel handlers,
+ * enabling renderer processes to call main process controller methods via ipcRenderer.
+ *
+ * Supports two communication models:
+ * - send/on model (synchronous): Renderer uses ipcRenderer.sendSync(),
+ *   main process returns results via event.returnValue.
+ *   Supports both sync and async controller methods (Electron's sendSync enters a nested
+ *   message loop that processes microtasks, so event.returnValue set after await is received).
+ *
+ * - invoke/handle model (asynchronous): Renderer uses ipcRenderer.invoke(),
+ *   main process returns a Promise via ipcMain.handle().
+ *   ✅ Recommended model, supports both synchronous and asynchronous controller methods.
+ *
+ * Channel naming rule: Replace '.' in controller path with channelSeparator (default '/')
+ * Example: controller.user.add → controller/user/add
+ */
+const debug_1 = __importDefault(require("debug"));
+const electron_1 = require("electron");
+const index_js_1 = require("../log/index.js");
+const index_js_2 = require("../controller/index.js");
+const file_loader_js_1 = require("../core/loader/file_loader.js");
+const index_js_3 = require("../config/index.js");
+const utils_js_1 = require("./utils.js");
+const debugLog = (0, debug_1.default)('ee-core:socket:ipcServer');
+/**
+ * IpcServer - IPC server
+ *
+ * Traverses the controller object tree and registers ipcMain channel handlers for each exported method.
+ * Uses recursive loop() to traverse nested controller directory structures.
+ */
+class IpcServer {
+    constructor() {
+        this.channelSeparator = (0, index_js_3.getConfig)().mainServer.channelSeparator || '/';
+        this.directory = 'controller';
+        this.init();
+    }
+    /**
+     * Initialize: traverse controller tree and register all IPC channels
+     */
+    init() {
+        const controller = (0, index_js_2.getController)();
+        this.loop(controller, this.directory);
+    }
+    /**
+     * Recursively traverse the controller object tree
+     *
+     * Distinguished by EXPORTS symbol marker:
+     * - Objects with EXPORTS marker → leaf nodes (controller method collections), call register()
+     * - Objects without marker → intermediate nodes (directory/namespace), continue recursion
+     *
+     * @param obj - Current object being traversed
+     * @param pathname - Current property path
+     */
+    loop(obj, pathname) {
+        const keys = Object.keys(obj);
+        for (const key of keys) {
+            if (key === 'constructor')
+                continue;
+            const subObj = obj[key];
+            const propertyChain = pathname + '.' + key;
+            // EXPORTS symbol marker indicates this is a controller method collection (leaf node)
+            if (subObj && subObj[file_loader_js_1.EXPORTS] === true) {
+                this.register(subObj, propertyChain);
+            }
+            else if (typeof subObj === 'object') {
+                this.loop(subObj, propertyChain);
+            }
+        }
+    }
+    /**
+     * Register controller methods as IPC channel handlers
+     *
+     * Registers two handlers for each method:
+     * 1. ipcMain.on (synchronous model): Sets event.returnValue, supports async methods
+     * 2. ipcMain.handle (asynchronous model): Returns Promise, recommended
+     *
+     * @param exportObj - Controller method collection object
+     * @param propertyChain - Property path (e.g., 'controller.user')
+     */
+    register(exportObj, propertyChain) {
+        const controller = (0, index_js_2.getController)();
+        const keys = Object.keys(exportObj);
+        for (const key of keys) {
+            const tmpChannel = `${propertyChain}.${key}`;
+            const channel = tmpChannel.split('.').join(this.channelSeparator);
+            debugLog('[register] channel %s', channel);
+            // send/on model (synchronous)
+            // Electron's sendSync enters a nested message loop that processes microtasks,
+            // so event.returnValue set after await IS received by sendSync.
+            electron_1.ipcMain.on(channel, async (event, params) => {
+                try {
+                    const fn = (0, utils_js_1.resolveControllerFn)(controller, channel, this.channelSeparator);
+                    if (!fn)
+                        return;
+                    const result = await fn.call(controller, params, event);
+                    event.returnValue = result;
+                }
+                catch (e) {
+                    index_js_1.coreLogger.error('[socket/IpcServer] send/on throw error:', e);
+                    // Send error info back so renderer can distinguish errors from legitimate undefined
+                    event.returnValue = { __EE_ERROR__: true, message: e instanceof Error ? e.message : String(e) };
+                }
+            });
+            // invoke/handle model (asynchronous, recommended)
+            // Throw error so renderer's ipcRenderer.invoke() rejects, allowing try/catch on renderer side
+            electron_1.ipcMain.handle(channel, async (event, params) => {
+                const fn = (0, utils_js_1.resolveControllerFn)(controller, channel, this.channelSeparator);
+                if (!fn)
+                    return undefined;
+                return await fn.call(controller, params, event);
+            });
+        }
+    }
+}
+exports.IpcServer = IpcServer;
+//# sourceMappingURL=ipcServer.js.map