@capyclaw/service-broker 0.1.0 → 0.2.0

package/README.md

@@ -12,6 +12,15 @@ DSH 服务中间件。服务解耦标准的执行者：**启动清单/后端/用
 | 跨端口调动交给中间件 | `requires` 拓扑、端口分配、复用/冲突仲裁、discovery 都在这里 |
 | 不硬耦合 | 引擎零 dsh 依赖；embedded（cordis 插件壳）与 standalone（独立端口）同一份逻辑 |
 
+## 变更记录
+
+- **0.2.0**（2026-11-04）：新增**统一服务 spec**——`service.schema.json`（JSON Schema）
+  与 `lib/spec.mjs`（代码面校验 `validateServiceSpec`/`validateServiceManifest`），
+  `loadManifest` 在装载期拒绝结构非法的清单（同清单重复 id 也在此报错）；
+  新增 exports `./spec`、`./schema`。`stack-services.json`（dsh-stack-kit 编译）与
+  `service-manifest.json`（dsh-suite-kit 物化）自此共用同一份 spec 契约。
+- 0.1.0：初始发布。
+
 ## 两种形态
 
 ### standalone（桌面/外部场景的主形态）

package/lib/manifest.mjs

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { validateServiceManifest } from './spec.mjs'
 
 export const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 
@@ -23,6 +24,8 @@ export function loadManifest(manifestPath) {
   const raw = JSON.parse(readFileSync(file, 'utf8'))
   const services = Array.isArray(raw) ? raw : raw.services
   if (!Array.isArray(services)) throw new Error(`manifest 格式非法（缺 services 数组）: ${file}`)
+  const specErrors = validateServiceManifest(services, file)
+  if (specErrors.length) throw new Error(`manifest 服务 spec 非法:\n- ${specErrors.join('\n- ')}`)
   const base = path.dirname(file)
   return services.map((service) => expandPackageDir(service, base))
 }

package/lib/spec.mjs

@@ -0,0 +1,78 @@
+/**
+ * 服务 spec 校验：service.schema.json 的代码面。
+ *
+ * stack-services.json（dsh-stack-kit 编译）与 service-manifest.json
+ * （dsh-suite-kit 物化）共用这一份 spec；本模块是装载期与跨包测试
+ * 共同调用的唯一校验器（结构级——语义由 engine/discovery 在运行期裁决）。
+ */
+const ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+
+function checkPortValue(value, label, errors) {
+  if (value === undefined) return
+  if (value === 'auto') return
+  if (!Number.isInteger(value) || value <= 0 || value > 65535) {
+    errors.push(`${label} 必须是 1-65535 整数或 "auto"`)
+  }
+}
+
+/** 校验单个服务 spec；返回错误数组（空 = 通过）。 */
+export function validateServiceSpec(service, at = 'service') {
+  const errors = []
+  if (!service || typeof service !== 'object' || Array.isArray(service)) {
+    return [`${at} 必须是对象`]
+  }
+  if (typeof service.id !== 'string' || !ID_RE.test(service.id)) {
+    errors.push(`${at}.id 必须是非空的服务标识（字母数字开头，可含 . _ -）`)
+  }
+  if (!Array.isArray(service.cmd) || service.cmd.length === 0 || service.cmd.some((item) => typeof item !== 'string')) {
+    errors.push(`${at}.cmd 必须是非空 string[]（完整命令行）`)
+  }
+  if (service.ports !== undefined) {
+    if (typeof service.ports !== 'object' || service.ports === null || Array.isArray(service.ports)) {
+      errors.push(`${at}.ports 必须是对象（main 或具名端口）`)
+    } else {
+      for (const [name, value] of Object.entries(service.ports)) {
+        checkPortValue(value, `${at}.ports.${name}`, errors)
+      }
+    }
+  }
+  if (service.env !== undefined && (typeof service.env !== 'object' || service.env === null
+    || Array.isArray(service.env) || Object.values(service.env).some((value) => typeof value !== 'string'))) {
+    errors.push(`${at}.env 必须是 string -> string 对象`)
+  }
+  if (service.keepAlive !== undefined && typeof service.keepAlive !== 'boolean') {
+    errors.push(`${at}.keepAlive 必须是 boolean`)
+  }
+  if (service.healthPath !== undefined && typeof service.healthPath !== 'string') {
+    errors.push(`${at}.healthPath 必须是 string`)
+  }
+  if (service.url !== undefined && typeof service.url !== 'string') errors.push(`${at}.url 必须是 string`)
+  if (service.cwd !== undefined && typeof service.cwd !== 'string') errors.push(`${at}.cwd 必须是 string`)
+  if (service.logFile !== undefined && typeof service.logFile !== 'string') errors.push(`${at}.logFile 必须是 string`)
+  if (service.requires !== undefined && (!Array.isArray(service.requires)
+    || service.requires.some((item) => typeof item !== 'string'))) {
+    errors.push(`${at}.requires 必须是 string[]`)
+  }
+  if (service.portFrom !== undefined && !['content', 'urlPort'].includes(service.portFrom)) {
+    errors.push(`${at}.portFrom 只允许 content | urlPort`)
+  }
+  if (service.dirFrom !== undefined && service.dirFrom !== 'contentState') {
+    errors.push(`${at}.dirFrom 只允许 contentState`)
+  }
+  return errors
+}
+
+/** 校验整份清单（services 数组 + 同清单 id 唯一）；返回错误数组（空 = 通过）。 */
+export function validateServiceManifest(services, label = 'manifest') {
+  if (!Array.isArray(services)) return [`${label}: services 必须是数组`]
+  const errors = []
+  const seen = new Set()
+  services.forEach((service, index) => {
+    errors.push(...validateServiceSpec(service, `${label}[${index}]`))
+    if (service && typeof service === 'object' && typeof service.id === 'string') {
+      if (seen.has(service.id)) errors.push(`${label}: 重复的服务 id ${service.id}`)
+      seen.add(service.id)
+    }
+  })
+  return errors
+}

package/package.json

@@ -1,25 +1,42 @@
 {
   "name": "@capyclaw/service-broker",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DSH 服务中间件（唯一进程内插件）：按清单/结构化命令把各服务作为独立进程拉起，负责守护、发现（discovery）、控制端点；服务与服务之间不互相带动，跨端口组织一律经过这里。",
   "type": "module",
   "main": "./lib/host.mjs",
   "exports": {
     ".": "./lib/host.mjs",
     "./engine": "./lib/engine.mjs",
+    "./manifest": "./lib/manifest.mjs",
+    "./spec": "./lib/spec.mjs",
+    "./schema": "./service.schema.json",
     "./package.json": "./package.json"
   },
+  "engines": {
+    "node": ">=18",
+    "dsh": "^0.2.0-rc.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "suite": "./dsh-suite.json",
-    "apiVersion": "1.0.0"
+    "apiVersion": "1.0.0",
+    "category": "service",
+    "platform": "both"
+  },
+  "meta": {
+    "title": "服务中间件",
+    "description": "按清单把各服务作为独立进程拉起，守护、发现与控制端点；服务之间不互相带动"
   },
   "files": [
     "lib/",
     "server.mjs",
     "services.json",
+    "service.schema.json",
     "cordis.patch.yml",
     "dsh-suite.json",
     "README.md"
@@ -27,5 +44,8 @@
   "license": "MIT",
   "scripts": {
     "test": "node --test test/unit.test.mjs test/e2e.test.mjs test/stability.test.mjs test/adopt-detached.test.mjs"
+  },
+  "dependencies": {
+    "@capyclaw/plugin-kit": "^0.2.0"
   }
 }

package/service.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://dsh.local/schemas/service.schema.json",
+  "title": "DSH Broker 服务清单（唯一服务 spec）",
+  "description": "stack-services.json（dsh-stack-kit 编译）与 service-manifest.json（dsh-suite-kit 物化）是同一 spec 的两个 runtime 工件；本 schema 是二者共同的契约。${PACKAGE_DIR}/${PORT}/${PORT_<NAME>} 占位符由装载/仲裁层展开。",
+  "type": "object",
+  "required": ["services"],
+  "properties": {
+    "services": { "type": "array", "items": { "$ref": "#/$defs/service" } }
+  },
+  "$defs": {
+    "port": {
+      "anyOf": [
+        { "type": "integer", "minimum": 1, "maximum": 65535 },
+        { "type": "string", "enum": ["auto"] }
+      ]
+    },
+    "service": {
+      "type": "object",
+      "required": ["id", "cmd"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$", "description": "服务 id（同清单内唯一）" },
+        "cmd": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "完整命令行（占位符原样保留，broker 展开分配）" },
+        "ports": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/port" },
+          "description": "main 为主端口；具名端口映射 PORT_<NAME>"
+        },
+        "url": { "type": "string", "description": "服务入口 URL 模板" },
+        "healthPath": { "type": "string", "description": "健康探测路径（默认 /healthz）" },
+        "keepAlive": { "type": "boolean", "description": "进程死亡后由 broker 原端口复活" },
+        "env": { "type": "object", "additionalProperties": { "type": "string" } },
+        "cwd": { "type": "string" },
+        "requires": { "type": "array", "items": { "type": "string" }, "description": "同清单内依赖的服务 id" },
+        "logFile": { "type": "string" },
+        "portFrom": { "type": "string", "enum": ["content", "urlPort"], "description": "suite 物化期提示：主端口取 runtime content/urlPort（物化后删除）" },
+        "dirFrom": { "type": "string", "enum": ["contentState"], "description": "suite 物化期提示：--dir 参数指向 runtime contentState（物化后删除）" }
+      }
+    }
+  }
+}