oox 0.3.4 → 0.3.6

package/README.md

@@ -27,3 +27,16 @@ npm install oox
 ```bash
 npx oox --help
 ```
+
+### Examples
+- [basic-example](./examples/basic-example)
+- [routing-example](./examples/routing-example)
+- [rpc-example](./examples/rpc-example)
+- [distributed-example](./examples/distributed-example)
+- [load-balancing-example](./examples/load-balancing-example)
+- [tracing-example](./examples/tracing-example)
+- [service-discovery-example](./examples/service-discovery-example)
+
+
+### Docs
+[config](./docs/config.md)

package/app.js

@@ -1,12 +1,6 @@
 import { EventEmitter } from 'node:events';
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { genKVMethods } from './utils.js';
-export * as logger from './logger.js';
-export class Context {
-    // 请求溯源ID
-    traceId = '';
-}
-export const asyncStore = new AsyncLocalStorage();
+import { asyncStore } from './context.js';
 export const eventHub = new EventEmitter();
 /**
  * sourceMethods => methods

package/bin/cli.js

@@ -16,7 +16,7 @@ if (execFilename.endsWith('oox') || fileURLToPath(import.meta.url) === execFilen
     if (!command || ['help', '-h', '-help', '--help', 'version', '-v', '-version', '--version'].includes(command)) {
         isStartup = false;
         console.log();
-        console.log('OOX Service Engine');
+        console.log(pkg.description);
         console.log(chalk.bold('version'), chalk.bold.green(`${pkg.version}`));
         console.log(chalk.underline(`${pkg.homepage}`));
         console.log();
@@ -28,24 +28,54 @@ if (execFilename.endsWith('oox') || fileURLToPath(import.meta.url) === execFilen
         console.log('  oox entry.js port=8080');
         console.log();
         console.log('  oox entry.js group=app/ registry=:6000');
-        console.log('  oox app/entry/index.js group=app/ env=envs/prod.js ignore=core');
+        console.log('  oox app/entry/index.js group=app/ env=.env/prod.js ignore=core');
         console.log();
         console.log(chalk.bold('Params:'));
-        const params = [
+        const params_base = [
             ['default-env', 'file', '.js or .json file, merge to oox.config'],
-            ['env', 'file', `${chalk.bold.red('default-env')}.js or .json file, merge to oox.config, ${chalk.bold('(after default-env)')}`],
+            ['env', 'file', `.js or .json file, merge to oox.config, ${chalk.bold('(after default-env)')}`],
             ['port', 'int', `default is ${chalk.bold('0')}, for random port, or any integer > 0`],
             ['group', 'dir', 'service group directory, all LocalCall transform to RPC'],
             ['ignore', 'name', 'set a name for LocalCall do not transform to RPC, support string | array<string>'],
-            ['http', 'json', 'HTTP server options, support flat name, ex: http.path=/api'],
-            ['socketio', 'json', 'SocketIO server options, support flat name'],
-            ['isRegistry', 'bool', `default is ${chalk.bold.red('true')}, set no to disable service registry`],
+            ['errorStack', 'bool', 'set no to hidden error stack return'],
+        ];
+        const params_registry = [
+            ['isRegistry', 'bool', `set yes to enable service registry`],
             ['registryAdapter', 'name', 'set service registry adapter name'],
+            ['registryToken', 'token', 'set token for service registry'],
             ['registry', 'urls', 'registry service url, support string | array<string>'],
+            ['registry.url', 'url', 'set service registry url'],
+            ['registry.token', 'token', 'set service registry token'],
+        ];
+        const params_auth = [
+            ['token', 'token', 'set token for connection auth'],
+            ['allow.untrusted', 'bool', `set yes to allow untrusted caller`],
+            ['allow.ip', 'ip', 'set allow IP, support string | array<string>'],
+            ['allow.caller', 'name', 'set allow caller, support string | array<string>'],
             ['origin', 'urls', `set ${chalk.bold('*')}, allow any connections <Access-Control-Allow-Origin>`],
-            ['errorStack', 'bool', 'set no to hidden error stack return'],
         ];
-        console.log(mergeCommandParams(params));
+        const params_modules = [
+            ['http', 'json/bool', 'HTTP server options, support flat name, ex: http.path=/api, or set no to disable HTTP server'],
+            ['http.port', 'int server port'],
+            ['http.path', 'string', 'set HTTP server path'],
+            ['http.origin', 'urls', 'set HTTP server origin, support string | array<string>'],
+            ['http.ssl', 'json', 'set yes to enable HTTPS'],
+            ['http.ssl.cert', 'file', 'set HTTPS certificate path'],
+            ['http.ssl.key', 'file', 'set HTTPS private key path'],
+            ['http.ssl.ca', 'file', 'set HTTPS CA path'],
+            ['socketio', 'json/bool', 'SocketIO server options, support flat name, or set no to disable SocketIO server'],
+            ['socketio.port', 'int server port'],
+            ['socketio.path', 'string', 'set SocketIO server path'],
+            ['socketio.origin', 'urls', 'set SocketIO server origin, support string | array<string>'],
+            ['socketio.ssl', 'json', 'like http.ssl'],
+        ];
+        console.log(mergeCommandParams(params_base));
+        console.log(chalk.bold('Registry:'));
+        console.log(mergeCommandParams(params_registry));
+        console.log(chalk.bold('Auth:'));
+        console.log(mergeCommandParams(params_auth));
+        console.log(chalk.bold('Modules:'));
+        console.log(mergeCommandParams(params_modules));
         console.log('  ...', 'set params as', chalk.bold('foo=bar') + ',', 'usage as', chalk.bold('oox.config.foo'));
         console.log();
     }
@@ -73,10 +103,13 @@ function mergeCommandParams(params) {
             result += ' '.repeat(nameMaxLength);
         }
         else {
-            result += ' '.repeat(nameMaxLength - name.length);
+            result += ' '.repeat(Math.max(0, nameMaxLength - name.length));
         }
-        result += '[' + type + ']';
-        result += ' '.repeat(typeMaxLength - type.length);
+        const typeLeftSpaceLength = Math.max(0, Math.floor((typeMaxLength - type.length) / 2));
+        const typeLeftSpaces = ' '.repeat(typeLeftSpaceLength);
+        const typeRightSpaces = ' '.repeat(Math.max(0, typeMaxLength - type.length - typeLeftSpaceLength));
+        result += '[' + typeLeftSpaces + type + typeRightSpaces + ']';
+        result += ' ';
         result += desc;
         result += '\n';
     }

package/bin/configurer.js

@@ -12,7 +12,11 @@ function mergeFlatEnv(env) {
             const valueKey = subKeys.pop() || '';
             let tmpEnv = env;
             for (const subKey of subKeys) {
-                if (subKey in tmpEnv) { }
+                if (subKey in tmpEnv) {
+                    if ('object' !== typeof tmpEnv[subKey] || null === tmpEnv[subKey]) {
+                        tmpEnv[subKey] = {};
+                    }
+                }
                 else {
                     tmpEnv[subKey] = {};
                 }
@@ -42,20 +46,13 @@ async function readEnvFile(filePath) {
     return env;
 }
 export async function buildConfig(mergeEnv) {
-    const env = Object.create(null);
+    const env = {};
     const defaultEnvPath = argv.getEnvArg('default-env');
     const targetEnvPath = argv.getEnvArg('env');
     const defaultEnv = defaultEnvPath ? await readEnvFile(defaultEnvPath) : {};
     const targetEnv = targetEnvPath ? await readEnvFile(targetEnvPath) : {};
     Object.assign(env, defaultEnv, targetEnv, argv.getAllEnvArgs());
     mergeFlatEnv(env);
-    if ('string' === typeof env.ignore)
-        env.ignore = env.ignore.split(',');
-    if ('string' === typeof env.registry)
-        env.registry = env.registry.split(',');
-    if ('string' === typeof env.origin && env.origin.includes(',')) {
-        env.origin = env.origin.split(',');
-    }
     if (mergeEnv)
         Object.assign(env, mergeEnv);
     return env;

package/bin/proxy-require.js

@@ -4,10 +4,6 @@ import * as path from 'node:path';
 import * as oox from '../index.js';
 import { Module } from 'node:module';
 const require = createRequire(import.meta.url);
-/**
- * 为了不重复创建Proxy，这个对象用于保存各个RPC服务的各个属性Proxy
- */
-const rpcServiceAttrMap = Object.create(null);
 /**
  * 重写 require 缓存
  */
@@ -24,24 +20,6 @@ function rewriteModuleCache(id, exports) {
     m.paths = paths;
     require.cache[id] = m;
 }
-function dotCall(name, action) {
-    return new Proxy(function () { }, {
-        get(target, key) {
-            const attrKey = name + '.' + (action ? action + '.' + key : key);
-            if (rpcServiceAttrMap) {
-                // 不重复创建Proxy
-                return rpcServiceAttrMap[attrKey];
-            }
-            const attrProxy = dotCall(name, attrKey);
-            rpcServiceAttrMap[attrKey] = attrProxy;
-            return attrProxy;
-        },
-        has(target, key) { return true; },
-        apply(target, thisArg, args) {
-            return oox.rpc(name, action, args);
-        }
-    });
-}
 export function proxyGroup(groupDirectory, excludes = []) {
     if (!groupDirectory)
         return;
@@ -70,7 +48,7 @@ export function proxyGroup(groupDirectory, excludes = []) {
             name = scriptMatch[1];
         }
         if (!excludes.includes(name))
-            rewriteModuleCache(id, dotCall(name, ''));
+            rewriteModuleCache(id, oox.proxy(name));
     }
 }
 /**

package/bin/register.js

@@ -1,32 +1,65 @@
 import chalk from 'chalk';
 import * as oox from '../index.js';
+import { randomUUID } from 'node:crypto';
 const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-async function connect(url, prevError = null) {
-    const adapter = oox.keepAliveConnectionAdapters.get(oox.config.registryAdapter);
+async function connect(identify, prevError = null) {
+    let url = '';
+    let connectionData;
+    if (typeof identify === 'string') {
+        url = identify;
+        connectionData = {
+            adapter: oox.config.registryAdapter,
+            url,
+            ip: '',
+            name: 'anonymous',
+            id: randomUUID(),
+            token: oox.config.registryToken,
+        };
+    }
+    else {
+        url = String(identify.url || '');
+        connectionData = identify;
+    }
+    if (!connectionData.name)
+        connectionData.name = 'anonymous';
+    if (!connectionData.id)
+        connectionData.id = randomUUID();
+    if (!connectionData.token)
+        connectionData.token = oox.config.registryToken;
+    if (!connectionData.adapter)
+        connectionData.adapter = oox.config.registryAdapter;
+    const adapter = oox.keepAliveConnectionAdapters.get(connectionData.adapter);
+    if (!adapter) {
+        console.error(chalk.red('[Registry]'), `Registry Adapter ${chalk.bold(connectionData.adapter)} is not found`);
+        return;
+    }
+    if (!url) {
+        console.error(chalk.red('[Registry]'), `Registry URL ${chalk.bold(url)} is empty`);
+        return;
+    }
     try {
-        const connection = await adapter.open(url);
-        onConnection(connection, url);
+        const connection = await adapter.open(connectionData);
+        connection.isRegistry = true;
+        onConnection(connection);
     }
     catch (error) {
         if (!prevError)
-            console.log(chalk.red('[Registry]'), chalk.underline.red(`${url}`), 'error.');
+            console.error(chalk.red('[Registry]'), chalk.underline.red(`${url}`), 'error.');
         await delay(2000);
-        connect(url, error);
+        connect(identify, error);
     }
 }
-async function onConnection(connection, url) {
+async function onConnection(connection) {
     const { name } = connection.data;
     connection.once('disconnect', async () => {
-        console.log(chalk.red('[Registry]'), `Service<${name}>`, chalk.underline.red(`${connection.data.url || url}`), 'disconnected.');
+        console.error(chalk.red('[Registry]'), `Service<${name}>`, chalk.underline.red(`${connection.data.url || name}`), 'disconnected.');
         await delay(1000);
-        connect(url);
+        connect(connection.data);
     });
-    console.log(chalk.green('[Registry]'), `Service<${name}>`, chalk.underline.green(`${connection.data.url || url}`), 'connected.');
+    console.info(chalk.green('[Registry]'), `Service<${name}>`, chalk.underline.green(`${connection.data.url || name}`), 'connected.');
 }
-export async function registry(urls) {
-    if ('string' === typeof urls)
-        urls = [urls];
-    for (const url of urls) {
-        connect(url);
+export async function registry(identifies) {
+    for (const identify of identifies) {
+        connect(identify);
     }
 }

package/bin/starter.js

@@ -1,5 +1,6 @@
 import * as path from 'node:path';
 import chalk from 'chalk';
+import { configFormatters } from '../config.js';
 import * as oox from '../index.js';
 import { buildConfig } from './configurer.js';
 import { registry } from './register.js';
@@ -17,6 +18,8 @@ function getEntryInfo(env, entryFilename) {
     const directory = fullDirectory.split(path.sep).pop();
     const groupFullDirectory = env.group ? path.resolve(env.group) : '';
     const entryMatch = filename.match(entryMatchRegExp);
+    if (!entryMatch)
+        throw new Error('Invalid entry file name: ' + entryFilename);
     const entryFilenameWithoutExtension = entryMatch[1];
     const name = entryFilenameWithoutExtension === 'index' && groupFullDirectory !== fullDirectory ? directory : entryFilenameWithoutExtension;
     return { name, path: fullPath, group: groupFullDirectory };
@@ -37,6 +40,11 @@ export async function configure(env, entryFilename) {
         path: entryInfo.path.replace(/\\/g, '/'),
         group: entryInfo.group.replace(/\\/g, '/'),
     };
+    for (const key in oox.config) {
+        if (key in configFormatters) {
+            oox.config[key] = configFormatters[key](oox.config[key]);
+        }
+    }
     // 模块配置
     oox.modules.setConfig(oox.config);
     oox.emit('app:configured');

package/config.js

@@ -0,0 +1,145 @@
+import { randomUUID } from "node:crypto";
+import { getIPAddress } from "./utils.js";
+export class Config {
+    // 服务ID
+    id = randomUUID();
+    // 服务名称
+    name = 'local';
+    // 服务列表路径
+    group = '';
+    // 非服务模块
+    ignore = [];
+    // 启动文件
+    entryInfo = {
+        // 启动文件路径
+        path: '',
+        // 服务列表路径
+        group: '',
+    };
+    // 主机地址
+    host = getIPAddress(4)[0];
+    // 默认监听端口
+    port = 0;
+    // 默认跨域设置
+    origin = '';
+    // 默认返回错误调用栈信息信息
+    errorStack = true;
+    // 是否开启服务注册功能
+    isRegistry = false;
+    // 服务注册列表
+    registry = [];
+    // 注册服务令牌
+    registryToken = '';
+    // 服务注册适配器
+    registryAdapter = 'socketio';
+    // 当前服务的令牌，验证成功则忽略allow配置
+    token = randomUUID();
+    allow = {
+        // 是否允许未验证令牌连接
+        untrusted: false,
+        // 是否允许指定IP连接
+        ip: [],
+        // 是否允许指定名称连接
+        caller: [],
+    };
+}
+export const configFormatters = {
+    id: function (value) {
+        return String(value || randomUUID());
+    },
+    name: function (value) {
+        return String(value || 'local');
+    },
+    group: function (value) {
+        return String(value || '');
+    },
+    ignore: function (value) {
+        if (Array.isArray(value))
+            return value;
+        if (typeof value === 'string')
+            return value.split(',');
+        return [];
+    },
+    entryInfo: function (value) {
+        return value;
+    },
+    host: function (value) {
+        return String(value || getIPAddress(4)[0]);
+    },
+    port: function (value) {
+        return Number(value) || 0;
+    },
+    origin: function (value) {
+        if (value === '*')
+            return value;
+        if (Array.isArray(value))
+            return value;
+        if (typeof value === 'string')
+            return value.split(',');
+        return '';
+    },
+    errorStack: function (value) {
+        return Boolean(value);
+    },
+    isRegistry: function (value) {
+        return Boolean(value);
+    },
+    registry: function (value) {
+        if ('string' === typeof value)
+            value = value.split(',');
+        if (value && !Array.isArray(value))
+            value = [value];
+        return value;
+    },
+    registryToken: function (value) {
+        return String(value || '');
+    },
+    registryAdapter: function (value) {
+        return String(value || '');
+    },
+    token: function (value) {
+        return String(value || '');
+    },
+    allow: function (value) {
+        value = value || {
+            untrusted: false,
+            ip: [],
+            caller: [],
+        };
+        const { ip, caller } = value;
+        if ('string' === typeof ip)
+            value.ip = ip.split(',');
+        if ('string' === typeof caller)
+            value.caller = caller.split(',');
+        return value;
+    }
+};
+/**
+ * 检查连接是否被允许
+ * @param ip 连接主机 IP
+ * @param caller 连接服务名称
+ * @param token 令牌
+ * @returns 是否被允许
+ */
+export function checkAllow(ip, caller, token) {
+    // check trusted token
+    const trusted = !config.token || token === config.token;
+    if (!trusted) {
+        const { allow } = config;
+        if (!allow.untrusted) {
+            return { allow: false, reason: 'untrusted' };
+        }
+        if (Array.isArray(allow.ip) && allow.ip.length) {
+            let allowed = allow.ip.some(item => item === '*' || new RegExp(item).test(ip));
+            if (!allowed)
+                return { allow: false, reason: 'not allow ip=' + ip };
+        }
+        if (Array.isArray(allow.caller) && allow.caller.length) {
+            let allowed = allow.caller.some(item => item === '*' || new RegExp(item).test(caller));
+            if (!allowed)
+                return { allow: false, reason: 'not allow caller=' + caller };
+        }
+    }
+    return { allow: true };
+}
+export const config = new Config();

package/context.js

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const asyncStore = new AsyncLocalStorage();
+export class AppContext {
+    // 请求溯源ID
+    traceId = '';
+}
+export class Context extends AppContext {
+    // 请求溯源IP
+    sourceIP = '';
+    // 请求者IP
+    ip = '';
+    // 请求者名称
+    caller = 'anonymous';
+    // 请求者ID (长连接专用)
+    callerId = '';
+    // 请求者连接把柄
+    connection;
+    constructor(context) {
+        super();
+        if (context) {
+            if ('toJSON' in context && typeof context.toJSON !== 'function') {
+                throw new Error('Context.toJSON must be a function');
+            }
+            Object.assign(this, context);
+        }
+    }
+    toJSON() {
+        const context = Object.assign({}, this);
+        delete context.connection;
+        return context;
+    }
+}
+let genTraceIdFunction = () => randomUUID();
+export function setGenTraceIdFunction(fn) {
+    genTraceIdFunction = fn;
+}
+/**
+ * 生成随机不重复id
+ */
+export function genTraceId() {
+    return genTraceIdFunction();
+}
+/**
+ * 获取链路跟踪上下文
+ */
+export function genContext(context) {
+    const newContext = new Context(context);
+    if (!newContext.traceId)
+        newContext.traceId = genTraceId();
+    if (!newContext.sourceIP)
+        newContext.sourceIP = newContext.ip;
+    return newContext;
+}
+export function getContext() {
+    const context = asyncStore.getStore();
+    return context || genContext();
+}

package/index.js

@@ -1,139 +1,20 @@
-import { randomUUID } from 'node:crypto';
-import * as app from './app.js';
-import { getIPAddress } from './utils.js';
-import * as registry from './registry.js';
-import Module, { ModuleConfig } from './modules/module.js';
-import { KeepAliveConnection, keepAliveConnectionAdapters, keepAliveConnections, enabledKeepAliveConnections } from './keepalive-connection.js';
-export class Context extends app.Context {
-    // 请求溯源IP
-    sourceIP = '';
-    // 请求者IP
-    ip = '';
-    // 请求者名称
-    caller = 'anonymous';
-    // 请求者ID (长连接专用)
-    callerId = '';
-    // 请求者连接把柄
-    connection;
-    toJSON() {
-        const context = Object.assign({}, this);
-        delete context.connection;
-        return context;
-    }
-}
-export class Config {
-    // 服务ID
-    id = randomUUID();
-    // 服务名称
-    name = 'local';
-    // 服务列表路径
-    group = '';
-    // 非服务模块
-    ignore = [];
-    // 启动文件
-    entryInfo = {
-        // 启动文件路径
-        path: '',
-        // 服务列表路径
-        group: '',
-    };
-    // 主机地址
-    host = getIPAddress(4)[0];
-    // 默认监听端口
-    port = 0;
-    // 默认跨域设置
-    origin = '';
-    // 默认返回错误调用栈信息信息
-    errorStack = true;
-    // 是否开启服务注册功能
-    isRegistry = true;
-    // 服务注册列表
-    registry = [];
-    // 服务注册适配器
-    registryAdapter = 'socketio';
-}
-export const config = new Config();
-let genTraceIdFunction = () => randomUUID();
-export function setGenTraceIdFunction(fn) {
-    genTraceIdFunction = fn;
-}
-/**
- * 生成随机不重复id
- */
-export function genTraceId() {
-    return genTraceIdFunction();
-}
-/**
- * 获取链路跟踪上下文
- */
-export function genContext(context) {
-    const newContext = Object.assign(new Context(), context);
-    if (!newContext.traceId)
-        newContext.traceId = genTraceId();
-    if (!newContext.sourceIP)
-        newContext.sourceIP = newContext.ip;
-    return newContext;
-}
-export function getContext() {
-    const context = asyncStore.getStore();
-    return context || genContext();
-}
 export async function serve() {
     await modules.serve();
+    registry.startBroadcastTimer();
 }
 export async function stop() {
     await modules.stop();
-}
-export function addKeepAliveConnection(connection) {
-    keepAliveConnections.add(connection);
-}
-export function removeKeepAliveConnection(arg1, arg2) {
-    if (typeof arg1 === 'string') {
-        keepAliveConnections.remove(arg1, arg2);
-        enabledKeepAliveConnections.remove(arg1, arg2);
-    }
-    else {
-        keepAliveConnections.remove(arg1);
-        enabledKeepAliveConnections.remove(arg1);
-    }
-}
-/**
-* random connection select for default load balance policy
-* @param name service name
-* @returns selected connection
-*/
-let loadBalancePolicy = (name) => {
-    const connections = enabledKeepAliveConnections.getConnectionsOfService(name);
-    if (!connections || !connections.size)
-        return null;
-    const arrayConnections = Array.from(connections.values());
-    const index = Math.floor(Math.random() * arrayConnections.length);
-    return arrayConnections[index];
-};
-export function setLoadBalancePolicy(policy) {
-    loadBalancePolicy = policy;
-}
-export async function rpc(arg1, action, params, context) {
-    if (!context || !context.traceId) {
-        context = getContext();
-    }
-    let connection;
-    if (arg1 instanceof KeepAliveConnection) {
-        connection = arg1;
-    }
-    else if ('string' === typeof arg1) {
-        connection = loadBalancePolicy(arg1);
-        if (!connection)
-            throw new Error(`Connection<${arg1}> not found`);
-    }
-    else
-        throw new Error(`Unknown rpc arg1<${arg1}>`);
-    return connection.adapter.rpc(connection, action, params, context);
-}
-export { KeepAliveConnection, keepAliveConnectionAdapters, keepAliveConnections, enabledKeepAliveConnections };
-export { Module, ModuleConfig };
+    registry.stopBroadcastTimer();
+}
+export * from './app.js';
+export * from './config.js';
+export * from './context.js';
+export * from './keepalive-connection.js';
+export * from './modules/module.js';
+export * as logger from './logger.js';
+export * from './proxy.js';
+import * as registry from './registry.js';
 export { registry };
-export const { asyncStore, setMethods, getMethods, kvMethods, sourceKVMethods, call, execute, logger, on, once, off, emit, } = app;
-// 放在最后导入，解决循环依赖问题
-import Modules from './modules/index.js';
-export const modules = new Modules;
+// 放在最后导入，避免循环依赖问题
+import * as modules from './modules/index.js';
+export { modules };