@capyclaw/service-broker 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# dsh-service-broker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 服务中间件。服务解耦标准的执行者：**启动清单/后端/用户不直接拉服务，
+一切结构化命令投递到这里，由中间件把每个服务作为独立进程拉起、守护、登记。**
+
+原则对应关系：
+
+| 原则 | 本插件的做法 |
+|------|--------------|
+| 服务彼此独立 | 每个服务 = 独立进程 + 独立端口，互不感知、不互相带动 |
+| 能做什么局限在自己的端口里 | 引擎只按 spec 拉起/回收，不解释服务内容 |
+| 跨端口调动交给中间件 | `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（桌面/外部场景的主形态）
+
+```bash
+node server.mjs [--port 39610] [--manifest services.json] [--stop-on-exit]
+```
+
+- 开机清单：`--manifest` 指向的 JSON（`{"services":[…spec]}` 或裸数组）幂等拉起；
+- 之后外部（如桌面后端）把结构化命令投递到控制端点。
+
+### embedded（dsh 场景）
+
+cordis insert 唯一一行（`cordis.patch.yml`），config：
+
+```yaml
+- insert:
+    - id: service-broker
+      name: "dsh-service-broker"
+      config:
+        manifest: "C:/…/services.json"   # 开机清单（可省略=待命）
+        controlPort: 0                    # >0 时embedded 也开控制端点
+        stopOnUnload: false               # true=插件卸载时全停（默认服务独立存活）
+        skills:
+          url: "http://127.0.0.1:39321"   # 可选：ctx.skills 瘦客户端数据源
+```
+
+## 服务规格 spec（与桌面后端 works_services 契约对齐）
+
+```json
+{
+  "id": "ppt-workbench",
+  "cmd": ["node", "…/server.mjs", "--port", "${PORT}"],
+  "env": { "EXAMPLE": "${SOME_VAR}" },
+  "cwd": "…",
+  "ports": { "main": 39311, "extra": "auto" },
+  "url": "http://127.0.0.1:${PORT}",
+  "healthPath": "/healthz",
+  "keepAlive": true,
+  "requires": ["dep-service"]
+}
+```
+
+- `${PORT}` / `${PORT_<NAME>}`：端口占位符（auto 由中间件现场分配；固定端口原样使用）；
+  cmd/env/url/cwd 里都可引用；其余 `${VAR}` 从环境展开，缺失 → 空串（诚实降级）。
+- `requires`：中间件按闭包拓扑排序拉起（成环报错）；只在本批内解析。
+- `keepAlive`：默认 true，进程死亡由守护按**原端口**自动重启（连续失败限次）。
+
+## 结构化命令投递（控制端点，只绑 127.0.0.1）
+
+```
+GET  /healthz            中间件自身健康
+GET  /control/list       服务全量列表（含 running/pid/ports/url）
+POST /control/apply      { commands: [{op:"up",service:spec} | {op:"stop",id}], waitMs? }
+POST /control/start      { id }（重放清单/上次规格）或 { service: spec }
+POST /control/stop       { id }（pid 身份核验后 taskkill /T /F）
+GET  /control/doctor?id  存活 + 健康端点体检
+```
+
+设置 `DSH_BROKER_TOKEN` 后，`/control/*` 需带 `x-broker-token` 头。
+
+## discovery 注册表
+
+`~/.dsh/services.json`（可 `--discovery`/`config.discoveryPath` 改）：
+
+```json
+{ "version": 1, "updatedAt": "…", "services": {
+    "ppt-workbench": { "id": "…", "state": "running", "url": "http://127.0.0.1:39311",
+                       "healthPath": "/healthz", "pid": 1234, "ports": {"main": 39311},
+                       "keepAlive": true, "reused": false, "startedAt": "…" } } }
+```
+
+UI/侧栏/其他工具只读这张表做发现，**永远不直接拉起别人**。
+
+## 复用优先（幂等）
+
+`up` 前先看目标端口：已有健康实例（`/healthz` 200 且自报 pid）→ 收编复用，
+不重启；被不健康进程占用 → 诚实失败，不抢端口。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-service-broker：唯一中间件插件。
+# 服务解耦标准见 docs/SERVICE_STANDARD.md——业务/端口服务一律不 insert 进
+# dsh 进程，由本插件按清单以独立进程拉起；跨端口组织只经过中间件。
+- insert:
+    - id: service-broker
+      name: "dsh-service-broker"

package/dsh-suite.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../dsh-suite-kit/suite.schema.json",
+  "name": "dsh-service-broker-suite",
+  "version": "0.1.0",
+  "title": "Service Broker",
+  "description": "服务中间件：按清单/结构化命令以独立进程拉起各服务，负责守护、发现与控制端点。",
+  "packages": {
+    "dsh-service-broker": {
+      "role": "middleware",
+      "version": "^0.1.0",
+      "path": ".",
+      "provides": {
+        "services": ["serviceBroker"],
+        "capabilities": { "service.broker": "1.0.0" },
+        "ports": ["auto"]
+      }
+    }
+  },
+  "rows": [{ "id": "service-broker", "name": "dsh-service-broker" }],
+  "checks": []
+}

package/lib/control.mjs

@@ -0,0 +1,117 @@
+/**
+ * dsh-service-broker 控制端点：外部投递结构化命令的入口。
+ *
+ * 端点（只绑 127.0.0.1）：
+ *   GET  /healthz            中间件自身健康
+ *   GET  /control/list       服务全量列表
+ *   POST /control/apply      结构化命令批投递 { commands: [...], waitMs? }
+ *   POST /control/start      { id? | service? }（id = 重放上次规格；service = 新规格）
+ *   POST /control/stop       { id }
+ *   GET  /control/doctor?id=
+ *
+ * 鉴权：设了 DSH_BROKER_TOKEN 时，除 /healthz 外都要带 x-broker-token。
+ * HTTP 形状对齐 dsh-runtime-control 的控制面风格。
+ */
+import http from 'node:http'
+import { existsSync, readFileSync } from 'node:fs'
+
+function jsonBody(req, limit = 8 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limit) { reject(new Error('body too large')); req.destroy(); return }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8')
+      if (!raw) return resolve({})
+      try { resolve(JSON.parse(raw)) } catch { reject(new Error('bad json')) }
+    })
+    req.on('error', reject)
+  })
+}
+
+function send(res, code, value) {
+  const text = JSON.stringify(value)
+  res.writeHead(code, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(text),
+    'access-control-allow-origin': '*',
+  })
+  res.end(text)
+}
+
+/**
+ * @param {import('./engine.mjs').ServiceEngine} engine
+ * @param {{ token?: string, manifestPath?: string }} options
+ */
+export function createControlServer(engine, options = {}) {
+  const manifestPath = options.manifestPath
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1')
+    const route = `${req.method} ${url.pathname}`
+    try {
+      if (options.token && route !== 'GET /healthz'
+        && req.headers['x-broker-token'] !== options.token) {
+        return send(res, 401, { ok: false, error: '需要 x-broker-token' })
+      }
+
+      if (route === 'GET /healthz') {
+        return send(res, 200, {
+          ok: true,
+          service: 'dsh-service-broker',
+          role: 'middleware',
+          pid: process.pid,
+          uptimeSec: Math.round(process.uptime()),
+        })
+      }
+
+      if (route === 'GET /control/list') {
+        return send(res, 200, { ok: true, services: await engine.list() })
+      }
+
+      if (route === 'POST /control/apply') {
+        const body = await jsonBody(req)
+        const result = await engine.apply(body.commands || [], { waitMs: body.waitMs })
+        return send(res, result.ok ? 200 : 207, result)
+      }
+
+      if (route === 'POST /control/start') {
+        const body = await jsonBody(req)
+        let spec = body.service
+        if (!spec && body.id && manifestPath && existsSync(manifestPath)) {
+          const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+          const services = Array.isArray(manifest) ? manifest : manifest.services
+          spec = (services || []).find((s) => s.id === body.id)
+          if (spec) spec = { ...spec, id: body.id }
+        }
+        if (!spec && body.id) {
+          const row = (await engine.list()).find((s) => s.id === body.id)
+          if (row?.url) return send(res, 200, { ok: true, services: [row] })
+        }
+        if (!spec) return send(res, 400, { ok: false, error: '缺 service 规格或可重放的 id' })
+        const result = await engine.apply([{ op: 'up', service: spec }], { waitMs: body.waitMs })
+        return send(res, result.ok ? 200 : 207, result)
+      }
+
+      if (route === 'POST /control/stop') {
+        const body = await jsonBody(req)
+        if (!body.id) return send(res, 400, { ok: false, error: '缺 id' })
+        return send(res, 200, await engine.stop(body.id))
+      }
+
+      if (route === 'GET /control/doctor') {
+        const id = url.searchParams.get('id')
+        if (!id) return send(res, 400, { ok: false, error: '缺 id' })
+        return send(res, 200, await engine.doctor(id))
+      }
+
+      send(res, 404, { ok: false, error: `未知端点 ${route}` })
+    } catch (err) {
+      send(res, 400, { ok: false, error: err.message })
+    }
+  })
+  return server
+}

package/lib/discovery.mjs

@@ -0,0 +1,47 @@
+/**
+ * discovery 注册表：中间件运行事实的唯一落点。
+ *
+ * 形状（~/.dsh/services.json）：
+ *   {
+ *     "version": 1,
+ *     "updatedAt": "2026-11-01T…",
+ *     "services": {
+ *       "<id>": { id, state, url, pid, ports, specHash, keepAlive, startedAt }
+ *     }
+ *   }
+ *
+ * 口径：损坏 = 空表（诚实降级，不阻塞）；原子写（唯一 tmp + rename，
+ * tmp 名带随机段——同进程并发写不会互抢同一个 tmp）。
+ */
+import { readFile, rename, writeFile, mkdir } from 'node:fs/promises'
+import path from 'node:path'
+
+/** 每个注册表文件一条写队列：整文件读改写串行化，杜绝并发互相覆盖。 */
+const _writeQueues = new Map()
+
+function enqueueWrite(filePath, task) {
+  const key = path.resolve(filePath).toLowerCase()
+  const prev = _writeQueues.get(key) || Promise.resolve()
+  const run = prev.then(task, task)
+  _writeQueues.set(key, run.then(() => {}, () => {}))
+  return run
+}
+
+export async function loadDiscovery(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function saveDiscovery(filePath, data) {
+  return enqueueWrite(filePath, async () => {
+    await mkdir(path.dirname(filePath), { recursive: true })
+    const tmp = path.join(
+      path.dirname(filePath),
+      `.${path.basename(filePath)}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`)
+    await writeFile(tmp, JSON.stringify(data, null, 2), 'utf8')
+    await rename(tmp, filePath)
+  })
+}