dsh-plugin-remote-connect-beta 0.1.0-beta.1

package/lib/core/tenancy.js

@@ -0,0 +1,267 @@
+/**
+ * 多租户管理层：把「租户注册表」和「每租户一个 Harness 实例」拼在一起。
+ *
+ * 分工：
+ *  - core/tenant.js   —— 租户定义与注册表（纯数据）
+ *  - core/instance.js —— 单个实例的启动/看护（纯进程）
+ *  - 本模块           —— 两者之间的编排：谁该起、谁在跑、路由句柄、增删改查
+ *  - core/proxy.js    —— 按租户凭据把请求送到对应实例
+ *
+ * 路由句柄的形状（proxy 只认这三个字段）：
+ *     { id, upstreamPort(): number, token(): string }
+ * 实例没起来时返回 0 / ''，网关会回 503（"该租户的 Harness 还没起来"），而不是把人挡在门外。
+ *
+ * @module dsh-plugin-remote-connect-beta/core/tenancy
+ */
+import path from 'node:path'
+import { createRegistry, generateAccessKey, normalizeTenant, slugifyId } from './tenant.js'
+import { createInstance, discoverHarnessBin, discoverRuntime } from './instance.js'
+import { translator } from './messages.js'
+
+const tEn = translator('en')
+
+/**
+ * @param {object} options
+ * @param {object} options.config 归一化后的 `config.tenants`
+ * @param {(line: string) => void} [options.log]
+ * @param {(state: object) => void} [options.onState] 任一实例状态变化时回调（面板据此刷新）
+ */
+export function createTenancy(options) {
+  const config = options.config
+  const log = options.log ?? (() => {})
+  const onState = options.onState ?? (() => {})
+
+  const registry = createRegistry({
+    file: config.registry,
+    baseDir: config.baseDir,
+    log,
+  })
+
+  const discovered = {
+    bin: discoverHarnessBin({ configured: config.harness.bin }),
+    runtime: discoverRuntime({ configured: config.harness.node }),
+  }
+
+  /** @type {Map<string, object>} 租户 id → 实例 */
+  const instances = new Map()
+  /** @type {Map<string, object>} 租户 id → 最近一次状态 */
+  const states = new Map()
+
+  function harnessProblem() {
+    if (discovered.bin === null) {
+      return '找不到 DSH Harness 入口：请在 tenants.harness.bin 指定 @deepseek-ai/dsh/lib/bin.js 的路径'
+    }
+    return null
+  }
+
+  function instanceFor(tenant) {
+    const existing = instances.get(tenant.id)
+    if (existing !== undefined) return existing
+    if (harnessProblem() !== null) return null
+    const instance = createInstance({
+      tenant,
+      harness: {
+        bin: discovered.bin.bin,
+        node: discovered.runtime.node,
+        electron: discovered.runtime.electron,
+        extraArgs: config.harness.extraArgs,
+      },
+      log,
+      onState: (state) => {
+        states.set(state.id, state)
+        onState(state)
+      },
+    })
+    instances.set(tenant.id, instance)
+    return instance
+  }
+
+  /** 路由句柄：租户存在就给（哪怕实例没起来，交给网关回 503）。 */
+  function handle(id) {
+    const tenant = registry.get(id)
+    if (tenant === null) return null
+    const instance = instances.get(id)
+    if (instance === undefined) {
+      return { id, tenant, upstreamPort: () => 0, token: () => '' }
+    }
+    return {
+      id,
+      tenant,
+      upstreamPort: () => instance.upstreamPort(),
+      token: () => instance.token(),
+      state: () => instance.state(),
+    }
+  }
+
+  /** 面板/CLI 看的一份汇总：租户定义 + 运行状态 + 就绪信息。 */
+  function describe(id) {
+    const tenant = registry.get(id)
+    if (tenant === null) return null
+    const state = states.get(id) ?? {
+      id,
+      phase: 'idle',
+      code: 'tenant.idle',
+      params: { id },
+      detail: tEn('tenant.idle'),
+      port: tenant.port,
+      hasToken: false,
+      restarts: 0,
+    }
+    return {
+      id: tenant.id,
+      name: tenant.name,
+      accessKey: tenant.accessKey,
+      home: tenant.home,
+      profile: tenant.profile,
+      port: state.port ?? tenant.port,
+      autostart: tenant.autostart,
+      enabled: tenant.enabled,
+      note: tenant.note,
+      createdAt: tenant.createdAt,
+      phase: state.phase,
+      code: state.code,
+      params: state.params,
+      detail: state.detail,
+      hint: state.hintCode === undefined ? undefined : tEn(state.hintCode),
+      hasToken: state.hasToken === true,
+      restarts: state.restarts ?? 0,
+      pid: state.pid ?? null,
+      running: state.phase === 'up',
+    }
+  }
+
+  function list() {
+    return registry.list().map((tenant) => describe(tenant.id))
+  }
+
+  /** 读注册表，并把组合里预置的租户补齐（组合是"种子"，注册表是运行时事实来源）。 */
+  function load() {
+    const result = registry.load()
+    for (const seed of config.list) {
+      const { problems, tenant } = normalizeTenant(seed, { baseDir: config.baseDir })
+      if (problems.length > 0) {
+        log('组合里预置的租户不合法，已跳过：' + problems.join('；'))
+        continue
+      }
+      if (registry.get(tenant.id) !== null) continue
+      try {
+        registry.add({ ...tenant, accessKey: tenant.accessKey === '' ? generateAccessKey() : tenant.accessKey })
+      } catch (error) {
+        log('预置租户 ' + tenant.id + ' 未能写入注册表：' + String(error?.message ?? error))
+      }
+    }
+    return { loaded: result.loaded, dropped: result.dropped, total: registry.size() }
+  }
+
+  function start(id) {
+    const tenant = registry.get(id)
+    if (tenant === null) throw new Error('租户不存在：' + String(id))
+    if (harnessProblem() !== null) throw new Error(harnessProblem())
+    const instance = instanceFor(tenant)
+    instance.start()
+    return describe(id)
+  }
+
+  async function stop(id) {
+    const instance = instances.get(id)
+    if (instance === undefined) return describe(id)
+    await instance.stop()
+    return describe(id)
+  }
+
+  /** 自动拉起所有 autostart 的租户（插件装载/局域网或公网入口启动时调用）。 */
+  function startAutostart() {
+    if (!config.enabled || config.autostart !== true) return []
+    const started = []
+    for (const tenant of registry.list()) {
+      if (tenant.enabled !== true || tenant.autostart !== true) continue
+      try {
+        start(tenant.id)
+        started.push(tenant.id)
+      } catch (error) {
+        log('租户 ' + tenant.id + ' 自动启动失败：' + String(error?.message ?? error))
+      }
+    }
+    return started
+  }
+
+  async function stopAll() {
+    const all = [...instances.values()]
+    instances.clear()
+    await Promise.all(all.map((instance) => instance.stop().catch(() => {})))
+  }
+
+  /**
+   * 面板/CLI 新增租户：id 可由显示名自动收敛，访问密钥自动生成。
+   * @returns {{ tenant: object, accessKey: string }}
+   */
+  function add(input = {}) {
+    const requestedId = typeof input.id === 'string' && input.id.trim() !== '' ? input.id.trim() : ''
+    const id = requestedId !== '' ? requestedId : slugifyId(input.name ?? '', 'u')
+    const tenant = registry.add({
+      id,
+      name: typeof input.name === 'string' && input.name.trim() !== '' ? input.name.trim() : id,
+      note: typeof input.note === 'string' ? input.note : '',
+      accessKey: typeof input.accessKey === 'string' && input.accessKey !== '' ? input.accessKey : generateAccessKey(),
+      home: typeof input.home === 'string' && input.home !== '' ? input.home : path.join(config.baseDir, id),
+      port: input.port ?? 0,
+      autostart: input.autostart !== false,
+    })
+    // 新增即拉起：多租户的意义是"给人一个链接就能用"
+    if (tenant.enabled === true && tenant.autostart === true) {
+      try {
+        start(tenant.id)
+      } catch (error) {
+        log('租户 ' + tenant.id + ' 已写入注册表，但启动失败：' + String(error?.message ?? error))
+      }
+    }
+    return { tenant, accessKey: tenant.accessKey }
+  }
+
+  /** 删除租户：先停实例，再从注册表移除（它的 home 目录保持原样，不替用户删数据）。 */
+  async function remove(id) {
+    const tenant = registry.get(id)
+    if (tenant === null) return null
+    await stop(id)
+    instances.delete(id)
+    states.delete(id)
+    registry.remove(id)
+    return tenant
+  }
+
+  function rotate(id) {
+    const tenant = registry.rotateKey(id)
+    // 旧 Cookie 立刻失效：gate 会按 id 查回租户，但 Cookie 里的签名密钥没变，
+    // 真正让它失效的是"密钥换了 → 新链接用新密钥"，旧的 ?k= 直接 404。
+    return tenant
+  }
+
+  return {
+    enabled: config.enabled === true,
+    registry,
+    harness: {
+      bin: discovered.bin === null ? null : discovered.bin.bin,
+      binSource: discovered.bin === null ? null : discovered.bin.source,
+      node: discovered.runtime.node,
+      nodeSource: discovered.runtime.source,
+      problem: harnessProblem(),
+    },
+    load,
+    list,
+    describe,
+    handle,
+    findByKey: (key) => {
+      const tenant = registry.findByKey(key)
+      return tenant === null ? null : handle(tenant.id)
+    },
+    add,
+    remove,
+    rotate,
+    start,
+    stop,
+    startAutostart,
+    stopAll,
+    /** 仅测试用：某个租户的实例（拿令牌/端口）。 */
+    instance: (id) => instances.get(id) ?? null,
+  }
+}

package/lib/core/tenant.js

@@ -0,0 +1,272 @@
+/**
+ * 租户模型与租户注册表（多租户网关的地基）。
+ *
+ * 为什么需要它：一个 Harness 实例本身就是**单用户**的（会话、凭据、设置、工作区、启动令牌
+ * 都在它自己的 `DSH_HOME` 里）。所以"多租户"不是给单个实例加个开关，而是：
+ *
+ *     一个网关（本插件） ──按租户凭据路由──► 每个租户一个独立 Harness 实例
+ *                                              （独立 DSH_HOME / 端口 / 令牌）
+ *
+ * 本模块只做三件事：校验租户定义、把定义持久化到注册表、按凭据或 id 查租户。
+ * 实例的启动与看护在 core/instance.js，请求路由在 core/proxy.js。
+ *
+ * 注册表是 JSON 文件（默认 `<stateDir>/tenants.json`，0600），写入用「临时文件 + rename」，
+ * 避免面板/CLI 同时改的时候留下半个文件。
+ *
+ * @module dsh-plugin-remote-connect-beta/core/tenant
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+/** 租户 id：小写、数字、连字符；2–32 位；直接用作 DSH profile 名与目录名。 */
+export const TENANT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,31}$/
+
+/** 访问密钥形态：URL 安全字符，16–128 位（与 public.accessKey 同规则）。 */
+export const ACCESS_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/
+
+/** 默认的租户根目录：每个租户的 DSH_HOME 放在它下面。 */
+export function defaultTenantBaseDir(homeDir = os.homedir()) {
+  return path.join(homeDir, 'DSH-tenants')
+}
+
+/** 生成一个租户访问密钥（32 字符 base64url ≈ 192 bit）。 */
+export function generateAccessKey() {
+  return crypto.randomBytes(24).toString('base64url')
+}
+
+/** 把用户输入的显示名收敛成合法 id（中文名等无法直接当目录名）。 */
+export function slugifyId(value, fallback = 't') {
+  const ascii = String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 32)
+  if (TENANT_ID_PATTERN.test(ascii)) return ascii
+  // 全是非 ASCII（例如中文名）：用调用方给的兜底前缀 + 随机尾巴，保证唯一且合法
+  const tail = crypto.randomBytes(3).toString('hex')
+  const head = ascii.replace(/[^a-z0-9]/g, '').slice(0, 8) || fallback
+  return (head + '-' + tail).slice(0, 32)
+}
+
+function asRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {}
+}
+
+function asString(value, fallback = '') {
+  return typeof value === 'string' ? value : fallback
+}
+
+/**
+ * 校验并归一化一个租户定义。
+ *
+ * 语义与插件其它配置一致：**格式非法**报错（id 不合法、端口越界、home 不是绝对路径……），
+ * "还没配好"（例如端口留空让系统分配）不算非法。
+ *
+ * @param {unknown} raw
+ * @param {object} [options]
+ * @param {string} [options.baseDir] 相对 home 的解析基准（默认 `~/DSH-tenants`）
+ * @param {number} [options.port] 已是该租户占用的端口时允许重复（更新场景）
+ * @returns {{ problems: string[], tenant: object }}
+ */
+export function normalizeTenant(raw, options = {}) {
+  const input = asRecord(raw)
+  const problems = []
+  const baseDir = options.baseDir ?? defaultTenantBaseDir()
+
+  const id = asString(input.id).trim()
+  if (!TENANT_ID_PATTERN.test(id)) {
+    problems.push('租户 id 必须是 2–32 位小写字母/数字/连字符：' + JSON.stringify(id))
+  }
+
+  const accessKey = asString(input.accessKey).trim()
+  if (!ACCESS_KEY_PATTERN.test(accessKey)) {
+    problems.push('租户 ' + (id || '?') + ' 的 accessKey 需为 16–128 位 URL 安全字符（[A-Za-z0-9_-]）')
+  }
+
+  const rawHome = asString(input.home).trim()
+  const home = rawHome === '' ? path.join(baseDir, id || 'tenant') : path.resolve(rawHome.replace(/^~(?=\/|$)/, os.homedir()))
+  if (!path.isAbsolute(home)) problems.push('租户 ' + (id || '?') + ' 的 home 必须是绝对路径')
+
+  const profileRaw = asString(input.profile).trim()
+  const profile = profileRaw === '' ? id : profileRaw
+  if (!TENANT_ID_PATTERN.test(profile)) {
+    problems.push('租户 ' + (id || '?') + ' 的 profile 名不合法（同 id 规则）：' + JSON.stringify(profile))
+  }
+
+  const portRaw = input.port === undefined || input.port === null || input.port === '' ? 0 : Number(input.port)
+  if (!Number.isSafeInteger(portRaw) || portRaw < 0 || portRaw > 65535) {
+    problems.push('租户 ' + (id || '?') + ' 的 port 必须是 0–65535（0 = 由系统分配）')
+  }
+
+  const name = asString(input.name).trim() || id
+  const note = asString(input.note)
+
+  return {
+    problems,
+    tenant: {
+      id,
+      name,
+      accessKey,
+      home,
+      profile,
+      port: Number.isSafeInteger(portRaw) ? portRaw : 0,
+      // 默认自动拉起：多租户的意义就是"别人打开就能用"，不该还要房主手动开
+      autostart: input.autostart !== false,
+      enabled: input.enabled !== false,
+      note,
+      createdAt: asString(input.createdAt) || new Date().toISOString(),
+    },
+  }
+}
+
+/**
+ * 租户注册表：一个 JSON 文件 + 内存缓存。
+ *
+ * @param {object} options
+ * @param {string} options.file 注册表文件路径
+ * @param {string} [options.baseDir] home 的默认父目录
+ * @param {(line: string) => void} [options.log]
+ */
+export function createRegistry(options) {
+  const file = options.file
+  const baseDir = options.baseDir ?? defaultTenantBaseDir()
+  const log = options.log ?? (() => {})
+  /** @type {Map<string, object>} */
+  const tenants = new Map()
+
+  function load() {
+    tenants.clear()
+    let text = ''
+    try {
+      text = fs.readFileSync(file, 'utf8')
+    } catch (error) {
+      if (error?.code !== 'ENOENT') log('租户注册表读取失败：' + String(error?.message ?? error))
+      return { loaded: 0, dropped: [] }
+    }
+    let parsed
+    try {
+      parsed = JSON.parse(text)
+    } catch (error) {
+      log('租户注册表不是合法 JSON，已忽略：' + String(error?.message ?? error))
+      return { loaded: 0, dropped: [] }
+    }
+    const list = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.tenants) ? parsed.tenants : []
+    const dropped = []
+    for (const item of list) {
+      const { problems, tenant } = normalizeTenant(item, { baseDir })
+      if (problems.length > 0) {
+        dropped.push({ id: asString(asRecord(item).id, '?'), problems })
+        continue
+      }
+      if (tenants.has(tenant.id)) {
+        dropped.push({ id: tenant.id, problems: ['重复的 id，只保留第一条'] })
+        continue
+      }
+      tenants.set(tenant.id, tenant)
+    }
+    if (dropped.length > 0) {
+      log('租户注册表有 ' + String(dropped.length) + ' 条被忽略：' + dropped.map((d) => d.id + '（' + d.problems.join('；') + '）').join('，'))
+    }
+    return { loaded: tenants.size, dropped }
+  }
+
+  function persist() {
+    const list = [...tenants.values()]
+    const dir = path.dirname(file)
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    const tmp = file + '.tmp-' + String(process.pid)
+    fs.writeFileSync(tmp, JSON.stringify({ version: 1, tenants: list }, null, 2) + '\n', { mode: 0o600 })
+    fs.renameSync(tmp, file)
+    return list
+  }
+
+  function list() {
+    return [...tenants.values()].sort((a, b) => a.id.localeCompare(b.id))
+  }
+
+  function get(id) {
+    return tenants.get(String(id)) ?? null
+  }
+
+  function findByKey(key) {
+    if (typeof key !== 'string' || key === '') return null
+    for (const tenant of tenants.values()) {
+      if (tenant.accessKey.length === key.length && crypto.timingSafeEqual(Buffer.from(tenant.accessKey), Buffer.from(key))) {
+        return tenant
+      }
+    }
+    return null
+  }
+
+  function add(raw) {
+    // 没给密钥就自动生成：调用方（CLI / 面板 / 组合）不该为了拿一个密钥去拼 crypto
+    const input = asRecord(raw)
+    const candidate = asString(input.accessKey).trim() === '' ? { ...input, accessKey: generateAccessKey() } : input
+    const { problems, tenant } = normalizeTenant(candidate, { baseDir })
+    if (problems.length > 0) {
+      const error = new Error(problems.join('；'))
+      error.problems = problems
+      throw error
+    }
+    if (tenants.has(tenant.id)) {
+      const error = new Error('租户 ' + tenant.id + ' 已存在')
+      error.problems = [error.message]
+      throw error
+    }
+    // 密钥必须唯一：否则两个租户会互相串门
+    if (findByKey(tenant.accessKey) !== null) {
+      const error = new Error('该访问密钥已被别的租户占用')
+      error.problems = [error.message]
+      throw error
+    }
+    tenants.set(tenant.id, tenant)
+    persist()
+    return tenant
+  }
+
+  function update(id, patch) {
+    const current = get(id)
+    if (current === null) throw new Error('租户不存在：' + String(id))
+    const { problems, tenant } = normalizeTenant({ ...current, ...asRecord(patch), id: current.id }, { baseDir })
+    if (problems.length > 0) {
+      const error = new Error(problems.join('；'))
+      error.problems = problems
+      throw error
+    }
+    const clash = findByKey(tenant.accessKey)
+    if (clash !== null && clash.id !== current.id) throw new Error('该访问密钥已被别的租户占用')
+    tenants.set(tenant.id, tenant)
+    persist()
+    return tenant
+  }
+
+  function remove(id) {
+    const current = get(id)
+    if (current === null) return null
+    tenants.delete(id)
+    persist()
+    return current
+  }
+
+  /** 换一个访问密钥（旧链接与旧 Cookie 立刻失效）。 */
+  function rotateKey(id) {
+    return update(id, { accessKey: generateAccessKey() })
+  }
+
+  return {
+    file,
+    baseDir,
+    load,
+    list,
+    get,
+    findByKey,
+    add,
+    update,
+    remove,
+    rotateKey,
+    /** 仅测试/排障用：直接看内存里的原始映射。 */
+    size: () => tenants.size,
+  }
+}