speed 1.2.3 → 1.3.1

package/README.md

@@ -1,2 +1,49 @@
 # speed
-Framework for TypeScript
+
+一个 TypeScript **微服务编排框架**（对标 Spring Cloud），构建于 [typespeed](https://github.com/speedphp/typespeed) 之上。
+
+> 关系：`typespeed`（单体框架 = SpringBoot）造应用，`speed`（微服务编排 = SpringCloud）管应用群。
+
+## 快速开始（1.3.0）
+
+```bash
+npm install speed -g
+speed new demo
+cd demo
+npm install
+npm run start        # 访问 http://127.0.0.1:8080/health
+```
+
+`speed new` 生成的项目使用 **标准装饰器**（TC39，`experimentalDecorators: false`），入口骨架见 `src/main.ts`。
+
+## 注册中心（1.3.1）
+
+注册表是注册中心的「单点真相」，提供 `register` / `unregister` / `getInstances` 三个基础 API（纯内存，同 `host:port` 重复注册只更新不新增）：
+
+```ts
+import { LocalRegistry } from "speed/registry";
+
+const registry = new LocalRegistry();
+registry.register("user-service", { host: "127.0.0.1", port: 8080 });
+registry.register("user-service", { host: "127.0.0.1", port: 8081, metadata: { version: "v2" } });
+
+registry.getInstances("user-service");           // 两个实例
+registry.unregister("user-service", "127.0.0.1", 8080); // true
+```
+
+> 详见 `docs/1.3.1-本地注册表.md`（为什么 → 怎么用 → 原理 → 怎么扩展）。
+
+## 模块（单包 `speed` + 子路径导出）
+
+| 子路径 | 模块 | 版本 |
+|---|---|---|
+| `speed/registry` | ① 注册中心 | 1.3.x |
+| `speed/gateway` | ③ API 网关 | 1.4.x |
+| `speed/config` | ② 配置中心 | 1.5.x |
+| `speed/loadbalancer` | ⑤ 负载均衡 | 1.6.x |
+| `speed/circuit-breaker` | ④ 熔断限流 | 1.7.x |
+| `speed/rpc` | ⑥ RPC 客户端 | 1.8.x |
+| `speed/messaging` | ⑧ 消息驱动 | 1.9.x |
+| `speed/observability` | ⑦+⑨ 追踪可观测 | 1.10.x |
+
+> 骨架阶段，开发中。开发计划见 speedphp 项目内的 `speed-微服务化开发计划.md` 及各模块计划文件。

package/dist/circuit-breaker/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/circuit-breaker/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/config/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/gateway/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/gateway/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./registry";
+export {};

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// speed —— TypeScript 微服务编排框架（对标 Spring Cloud），构建于 typespeed 之上。
+//
+// 骨架阶段（1.3.x）：speed 自身的微服务能力（@Service / @RpcClient / @GatewayRoute / @Config 等）
+// 随模块开发逐步加入；项目入口引导暂由 typespeed 的 @app / ServerFactory 承担
+// （脚手架模板 src/main.ts 直接从 "typespeed" 引入，保证 MAIN_PATH 正确解析到应用目录）。
+__exportStar(require("./registry"), exports);

package/dist/loadbalancer/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/loadbalancer/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/messaging/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/messaging/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/observability/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/observability/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/registry/index.d.ts

@@ -0,0 +1,2 @@
+export { LocalRegistry } from "./registry";
+export type { ServiceInstance } from "./registry";

package/dist/registry/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRegistry = void 0;
+// ① 注册中心（服务注册 + 发现）—— 1.3.x 实现
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "LocalRegistry", { enumerable: true, get: function () { return registry_1.LocalRegistry; } });

package/dist/registry/registry.d.ts

@@ -0,0 +1,14 @@
+export interface ServiceInstance {
+    host: string;
+    port: number;
+    registeredAt?: number;
+    metadata?: Record<string, unknown>;
+}
+export declare class LocalRegistry {
+    private instances;
+    register(serviceName: string, instance: ServiceInstance): ServiceInstance;
+    unregister(serviceName: string, host: string, port: number): boolean;
+    getInstances(serviceName: string): ServiceInstance[];
+    getServiceNames(): string[];
+    getInstanceCount(serviceName: string): number;
+}

package/dist/registry/registry.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRegistry = void 0;
+// 本地注册表：服务注册 + 发现的单点真相（纯内存，不涉及网络）。
+// 数据结构为两级：服务名 -> 实例列表（实例列表用数组，实例带 metadata 扩展位）。
+class LocalRegistry {
+    // 两级结构：服务名 -> 实例列表（实例列表用数组）
+    instances = new Map();
+    // 注册一个实例。同 host:port 重复注册只更新不新增。
+    register(serviceName, instance) {
+        // 去重键：host:port（同一服务内的实例唯一标识）
+        const key = `${instance.host}:${instance.port}`;
+        const list = this.instances.get(serviceName);
+        // 服务已存在时，在其列表里做线性查找（实例数量少，线性足够）
+        if (list) {
+            const existing = list.find((item) => `${item.host}:${item.port}` === key);
+            if (existing) {
+                // 原地刷新注册时间（心跳语义），并替换 metadata（若本次提供）
+                existing.registeredAt = Date.now();
+                if (instance.metadata !== undefined) {
+                    existing.metadata = instance.metadata;
+                }
+                return existing;
+            }
+            // 新实例补全 registeredAt 后 push 进列表
+            const newInstance = {
+                ...instance,
+                registeredAt: instance.registeredAt ?? Date.now(),
+            };
+            list.push(newInstance);
+            return newInstance;
+        }
+        // 服务不存在：新建列表并存入 map
+        const newInstance = {
+            ...instance,
+            registeredAt: instance.registeredAt ?? Date.now(),
+        };
+        this.instances.set(serviceName, [newInstance]);
+        return newInstance;
+    }
+    // 注销。找到并移除同 host:port 的实例返回 true；否则返回 false。
+    unregister(serviceName, host, port) {
+        const list = this.instances.get(serviceName);
+        if (!list) {
+            return false;
+        }
+        const key = `${host}:${port}`;
+        const index = list.findIndex((item) => `${item.host}:${item.port}` === key);
+        if (index === -1) {
+            return false;
+        }
+        list.splice(index, 1);
+        // 移除后若该服务实例列表为空，把 serviceName 这个 key 从 map 删除
+        if (list.length === 0) {
+            this.instances.delete(serviceName);
+        }
+        return true;
+    }
+    // 返回该服务的实例列表（浅拷贝，防止外部改动内部状态）；服务不存在返回 []
+    getInstances(serviceName) {
+        const list = this.instances.get(serviceName);
+        return list ? [...list] : [];
+    }
+    // 返回所有已注册的服务名
+    getServiceNames() {
+        return Array.from(this.instances.keys());
+    }
+    // 返回该服务下实例数量；服务不存在返回 0
+    getInstanceCount(serviceName) {
+        return this.instances.get(serviceName)?.length ?? 0;
+    }
+}
+exports.LocalRegistry = LocalRegistry;

package/dist/rpc/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rpc/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/scaffold/command.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scaffold/command.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const program = new commander_1.Command();
+program
+    .name("speed")
+    .description("A microservices orchestration framework for TypeScript (the Spring Cloud equivalent, built on typespeed).")
+    .version("1.3.1");
+program.command('new <projectName>')
+    .description('Create a new speed project.')
+    .action((projectName) => {
+    const currentDir = process.cwd();
+    const appPath = path.join(currentDir, projectName);
+    if (fs.existsSync(appPath)) {
+        console.error('');
+        console.error(`  Error: directory "${projectName}" already exists.`);
+        console.error('');
+        process.exit(1);
+    }
+    fs.mkdirSync(appPath);
+    mkFile("package.json", appPath, projectName);
+    mkFile("tsconfig.json", appPath, projectName);
+    mkFile(".gitignore", appPath, projectName);
+    fs.mkdirSync(path.join(appPath, "src"));
+    mkFile("main.ts", path.join(appPath, "src"), projectName);
+    mkFile("config.json", path.join(appPath, "src"), projectName);
+    console.log('');
+    console.log('  Create speed project success!');
+    console.log('');
+    console.log('  Next steps:');
+    console.log(`    cd ${projectName}`);
+    console.log('    npm install');
+    console.log('    npm run start');
+    console.log('');
+});
+program.on('--help', () => {
+    console.log('');
+    console.log('  Examples:');
+    console.log('');
+    console.log('    $ speed new demo');
+});
+program.parse(process.argv);
+function mkFile(fileName, targetPath, projectName) {
+    const tplPath = path.join(__dirname, "templates");
+    const fileContents = fs.readFileSync(path.join(tplPath, fileName + ".tpl"), "utf-8");
+    fs.writeFileSync(path.join(targetPath, fileName), fileContents.replace(/###appName###/g, projectName));
+}

package/dist/scaffold/templates/.gitignore.tpl

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

package/dist/scaffold/templates/config.json.tpl

@@ -0,0 +1,3 @@
+{
+    "name": "###appName###"
+}

package/dist/scaffold/templates/main.ts.tpl

@@ -0,0 +1,26 @@
+// Symbol.metadata polyfill：Node 22/24/26 均无 Symbol.metadata，
+// 标准装饰器的 context.metadata 依赖它，缺失会 TypeError，必须最先执行。
+(Symbol as { metadata?: symbol }).metadata ??= Symbol("Symbol.metadata");
+
+// 骨架阶段直接使用 typespeed 的 @app 引导（speed 的微服务装饰器 @Service 等自 1.3.2 起提供）。
+import { app, autoware, ServerFactory } from "typespeed";
+
+/**
+ * speed 项目入口骨架（标准装饰器模式）。
+ *
+ * 目录约定：
+ *   - 服务类放 src/（本文件即入口）；
+ *   - 配置文件 src/config.json（可选，typespeed 启动时自动读取，可用 config()/@value 访问）；
+ *   - tsconfig.json 已固定标准装饰器（experimentalDecorators:false + esnext.decorators lib）。
+ */
+@app
+class Main {
+
+    @autoware(ServerFactory)
+    public server!: ServerFactory;
+
+    public main() {
+        this.server.start(8080);
+        console.log("speed service started at http://127.0.0.1:8080");
+    }
+}

package/dist/scaffold/templates/package.json.tpl

@@ -0,0 +1,19 @@
+{
+    "name": "###appName###",
+    "version": "1.0.0",
+    "description": "A speed microservice project (built on typespeed).",
+    "scripts": {
+        "start": "ts-node --transpile-only src/main.ts",
+        "build": "tsc -p .",
+        "test": "ts-node --transpile-only src/main.ts"
+    },
+    "dependencies": {
+        "speed": "^1.3.0",
+        "typespeed": "^2.6.7"
+    },
+    "devDependencies": {
+        "typescript": "^5.9.3",
+        "ts-node": "^10.9.2",
+        "@types/node": "^22.0.0"
+    }
+}

package/dist/scaffold/templates/tsconfig.json.tpl

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "target": "es2022",
+        "module": "commonjs",
+        "moduleResolution": "node",
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": false,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "useDefineForClassFields": true,
+        "experimentalDecorators": false,
+        "emitDecoratorMetadata": false,
+        "lib": ["es2022", "esnext.decorators"]
+    },
+    "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,15 +1,73 @@
 {
   "name": "speed",
-  "version": "1.2.3",
-  "description": "A new Framework for TypeScript.",
+  "version": "1.3.1",
+  "description": "A microservices orchestration framework for TypeScript (the Spring Cloud equivalent, built on typespeed).",
   "author": "speedphp",
-  "license": "MIT License",
-  "scripts": {
-    "build": "tsc --project ."
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "default": "./dist/registry/index.js"
+    },
+    "./gateway": {
+      "types": "./dist/gateway/index.d.ts",
+      "default": "./dist/gateway/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "default": "./dist/config/index.js"
+    },
+    "./loadbalancer": {
+      "types": "./dist/loadbalancer/index.d.ts",
+      "default": "./dist/loadbalancer/index.js"
+    },
+    "./circuit-breaker": {
+      "types": "./dist/circuit-breaker/index.d.ts",
+      "default": "./dist/circuit-breaker/index.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc/index.d.ts",
+      "default": "./dist/rpc/index.js"
+    },
+    "./messaging": {
+      "types": "./dist/messaging/index.d.ts",
+      "default": "./dist/messaging/index.js"
+    },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "default": "./dist/observability/index.js"
+    }
+  },
+  "bin": {
+    "speed": "dist/scaffold/command.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "typespeed": "^2.6.7",
+    "commander": "^9.5.0"
   },
-  "homepage": "https://github.com/speedphp/speedts#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/speedphp/speedts.git"
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0",
+    "mocha": "10.2.0",
+    "chai": "4.3.7",
+    "@types/mocha": "^10.0.1",
+    "@types/chai": "^4.3.11",
+    "ts-node": "^10.9.1"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "prebuild": "rm -rf dist",
+    "postbuild": "cp -r src/scaffold/templates dist/scaffold/templates",
+    "clean": "rm -rf dist",
+    "test": "NODE_OPTIONS=--no-experimental-strip-types mocha --require ts-node/register test/**/*.ts --exit"
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 speed
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/tsconfig.json

@@ -1,22 +0,0 @@
-{
-    "compilerOptions": {
-      "module": "commonjs",
-      "declaration": true,
-      "removeComments": true,
-      "emitDecoratorMetadata": true,
-      "experimentalDecorators": true,
-      "allowSyntheticDefaultImports": true,
-      "target": "es2017",
-      "sourceMap": true,
-      "outDir": "./",
-      "baseUrl": "./",
-      "skipLibCheck": true,
-      "strictNullChecks": false,
-      "noImplicitAny": false,
-      "forceConsistentCasingInFileNames": false,
-      "noFallthroughCasesInSwitch": false,
-      "types": []
-    },
-    "files": [
-    ]
-  }