dsh-session-guard 4.1.11 → 4.1.16

package/src/client/settings-bridge.ts

@@ -0,0 +1,202 @@
+/**
+ * BridgeDocHandle — 设置卡双轨数据源的桥轨（M4/T20-b）。
+ *
+ * ≤0.1.5（settingsScope fiber 永不解 / 0.1.0-0.1.1 无 client 服务）时，
+ * 配置卡经本句柄走自家 webServer 桥（describe/mutate）读写宿主 settings 服务。
+ * 与原生 SettingsScope（scope-face.ts）同构：getSnapshot/subscribe/set/unset。
+ * 读 = POST /api/<ns>/settings/describe；写 = POST …/mutate（ops 转发宿主服务），
+ * 成功即用回填描述符刷新快照并通知订阅者（无本地第二份状态——权威值始终在宿主）。
+ *
+ * 与 perm-gate src/client/bridge-scope.ts（T13b/T20-b 泛化模板）的差异：
+ * ① 快照形状对齐本仓 SettingsScope（status: loading/ready/unavailable + mode）；
+ * ② describe 未就绪（settings-unavailable/ns-not-registered）时有限重试
+ *    （宿主 settings 服务解析晚于卡挂载的窗口），重试耗尽才落 'unavailable'。
+ */
+
+/** 与 server 侧 settingsBridgeRoutesFor（src/settings-bridge.js）必须逐字符一致。 */
+function settingsBridgeRoutesFor(ns: string): { describe: string; mutate: string } {
+  return { describe: `/api/${ns}/settings/describe`, mutate: `/api/${ns}/settings/mutate` }
+}
+
+interface Snapshot<T> {
+  status: 'loading' | 'ready' | 'unavailable'
+  value: T | undefined
+  revision: number | undefined
+  writable: boolean
+  base: unknown
+  user: unknown
+  mode: 'bridge'
+}
+
+interface Descriptor {
+  value?: unknown
+  revision?: number
+  [k: string]: unknown
+}
+
+interface BridgeBody {
+  ok?: boolean
+  code?: string
+  message?: string
+  value?: { descriptor?: Descriptor; writable?: boolean }
+}
+
+interface MutateOp {
+  op: 'set' | 'unset'
+  path: string[]
+  value?: unknown
+}
+
+/**
+ * ≤0.1.5 宿主 describe 的 descriptor.value 是「每字段 → {}」骨架（0.1.0/0.1.5
+ * 实测：value={enabled:{},…,officialProviders:{}}，真值拆在 base（合并默认层）
+ * 与 user（用户层））——直接吞 value 会让卡拿到 officialProviders={}，
+ * `?? []` 不兜底（{} 非 nullish）→ ListRow values.join 崩，整族 tab 槽殉葬。
+ * 判特征：对象且每个自有值都是空 plain 对象（guard 字段是标量/数组，不会全空）。
+ * 命中即以 {...base, ...user} 重组有效值（guard 配置全是顶层标量/数组，浅合并即语义）。
+ */
+function isFieldSkeleton(v: unknown): v is Record<string, Record<string, never>> {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false
+  const values = Object.values(v as Record<string, unknown>)
+  return values.length > 0
+    && values.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x) && Object.keys(x as object).length === 0)
+}
+
+function plainObject(v: unknown): Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? { ...(v as Record<string, unknown>) } : {}
+}
+
+/** descriptor → 卡面可用 plain 值：正常代际用 value；骨架代际用 base+user 浅合并。 */
+function descriptorPlainValue(d: Descriptor): unknown {
+  if (!isFieldSkeleton(d.value)) return d.value
+  return { ...plainObject(d.base), ...plainObject(d.user) }
+}
+
+/** describe 不可就绪码：宿主 settings 未解析/未注册——值得重试的瞬态。 */
+const RETRYABLE_CODES = new Set(['settings-unavailable', 'ns-not-registered'])
+const RETRY_DELAY_MS = 1500
+const RETRY_MAX = 4
+
+export class BridgeDocHandle<T> {
+  private snapshot: Snapshot<T>
+  private listeners = new Set<() => void>()
+  private revision: number | undefined
+  private retriesLeft = RETRY_MAX
+  private inflight: Promise<void> | undefined
+  private readonly ns: string
+  private readonly routes: { describe: string; mutate: string }
+
+  constructor(ns: string) {
+    this.ns = ns
+    this.routes = settingsBridgeRoutesFor(ns)
+    this.snapshot = {
+      status: 'loading',
+      value: undefined,
+      revision: undefined,
+      writable: true,
+      base: undefined,
+      user: undefined,
+      mode: 'bridge',
+    }
+    void this.refresh()
+  }
+
+  getSnapshot(): Snapshot<T> {
+    return this.snapshot
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  async set(field: string, value: unknown): Promise<boolean> {
+    return this.mutate([{ op: 'set', path: [field], value }])
+  }
+
+  async unset(field: string): Promise<boolean> {
+    return this.mutate([{ op: 'unset', path: [field] }])
+  }
+
+  private notify(): void {
+    for (const l of [...this.listeners]) l()
+  }
+
+  private applyDescriptor(d: Descriptor, writable: boolean): void {
+    this.revision = typeof d.revision === 'number' ? d.revision : undefined
+    this.snapshot = {
+      status: 'ready',
+      value: descriptorPlainValue(d) as T | undefined,
+      revision: this.revision,
+      writable,
+      base: undefined,
+      user: undefined,
+      mode: 'bridge',
+    }
+  }
+
+  private async request(path: string, body?: unknown): Promise<BridgeBody> {
+    const response = await fetch(path, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body ?? {}),
+    })
+    if (!response.ok) throw new Error(`bridge ${path} HTTP ${response.status}`)
+    return (await response.json()) as BridgeBody
+  }
+
+  /** describe 拉取；瞬态未就绪码在重试预算内延迟重拉，耗尽才落 unavailable。 */
+  refresh(): Promise<void> {
+    if (this.inflight !== undefined) return this.inflight
+    this.inflight = (async () => {
+      try {
+        const body = await this.request(this.routes.describe)
+        if (body.ok && body.value?.descriptor !== undefined) {
+          this.retriesLeft = RETRY_MAX
+          this.applyDescriptor(body.value.descriptor, body.value.writable !== false)
+        } else if (body.code !== undefined && RETRYABLE_CODES.has(body.code) && this.retriesLeft > 0) {
+          this.retriesLeft -= 1
+          this.inflight = undefined
+          setTimeout(() => {
+            void this.refresh()
+          }, RETRY_DELAY_MS)
+          return
+        } else {
+          this.snapshot = { ...this.snapshot, status: 'unavailable', writable: false }
+        }
+      } catch {
+        // 网络异常：按瞬态处理，预算内重试
+        if (this.retriesLeft > 0) {
+          this.retriesLeft -= 1
+          this.inflight = undefined
+          setTimeout(() => {
+            void this.refresh()
+          }, RETRY_DELAY_MS)
+          return
+        }
+        this.snapshot = { ...this.snapshot, status: 'unavailable', writable: false }
+      }
+      // 重试路径已在上面清过 inflight（setTimeout 后由 refresh() 重建）；
+      // 终态路径在此清挂起标记并广播。重试等待期 notify 无害（快照未变）。
+      this.inflight = undefined
+      this.notify()
+    })()
+    return this.inflight
+  }
+
+  private async mutate(ops: MutateOp[]): Promise<boolean> {
+    const body = await this.request(this.routes.mutate, { ops, expectedRevision: this.revision })
+    if (body.ok && body.value?.descriptor !== undefined) {
+      this.applyDescriptor(body.value.descriptor, this.snapshot.writable)
+      this.notify()
+      return true
+    }
+    if (body.code === 'settings-conflict') {
+      await this.refresh() // 乐观并发失败：拉权威值，让下次写入带新 revision
+      return false
+    }
+    throw new Error(`bridge mutate failed: ${body.code ?? 'unknown'} ${body.message ?? ''}`)
+  }
+}

package/src/client/settings-card.tsx

@@ -223,6 +223,12 @@ function SelectRow<T extends string>(props: {
   )
 }
 
+/** 卡面字段消毒：宿主 describe 形态异常（≤0.1.5 骨架残留等）时槽崩会殉葬全族
+ * tab——ListRow 的 values 非 nullish 非数组（如 {}）会让 `?? []` 失守，逐卡硬护栏。 */
+function toList(v: unknown): string[] {
+  return Array.isArray(v) ? v.map(String) : []
+}
+
 /** 插件配置卡片主体：可展开的 <li> + header 按钮 + pill switch 字段体。 */
 export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
   const snapshot = useSyncExternalStore(
@@ -303,7 +309,7 @@ export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
               <ListRow
                 label="追加官方 provider id"
                 description="精确匹配，优先级最高（逗号分隔）"
-                values={value.officialProviders ?? []}
+                values={toList(value.officialProviders)}
                 placeholder="deepseek-official"
                 disabled={readonly}
                 onCommit={(next) => { void scope.set('officialProviders', next) }}
@@ -311,7 +317,7 @@ export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
               <ListRow
                 label="官方端点名单"
                 description="baseURL 归一化后的 host（逗号分隔）"
-                values={value.officialBaseURLs ?? []}
+                values={toList(value.officialBaseURLs)}
                 placeholder="api.deepseek.com"
                 disabled={readonly}
                 onCommit={(next) => { void scope.set('officialBaseURLs', next) }}
@@ -319,7 +325,7 @@ export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
               <SelectRow<'hold' | 'error'>
                 label="拦截方式"
                 description="挂起等待不报错；或报错并记入延后队列"
-                value={value.deferredMode ?? 'hold'}
+                value={value.deferredMode === 'error' ? 'error' : 'hold'}
                 options={[
                   { value: 'hold', label: '挂起等待（退峰自动放行）' },
                   { value: 'error', label: '报错并延后（退峰续跑）' },

package/src/index.js

@@ -24,6 +24,7 @@ import { detectTaskControl } from './detect.js'
 import { makeIsRoot } from './request-guard.js'
 import { createWiring } from './wiring.js'
 import { NS, DEFAULT_SETTINGS, SettingsSchema } from './settings.js'
+import { registerSettingsBridgeRoutes } from './settings-bridge.js'
 
 // 0.1.7：声明式设置 —— volatile 字段即自动表单。
 export const Config = SettingsSchema
@@ -66,10 +67,13 @@ export function apply(ctx, config = {}) {
   // 否则 client 配置卡报「设置命名空间不可用」。两条 legacy 路径按服务能力
   // 自动分派:0.1.2/0.1.5 = 服务实例 installSection;0.1.0/0.1.1 = 模块级
   // installSettingsSection + settingsNamespace。fail-open:失败仅告警。
+  /** 宿主 settings 服务活引用（桥的惰性 getter 用；apply 期注入解到即填）。 */
+  let settingsSvcRef
   try {
     ctx.inject(['settings'], (sctx) => {
       const service = sctx.settings
       if (service === undefined || service === null) return
+      settingsSvcRef = service
       const hooks = {
         setSource: (source) => {
           configSource = typeof source === 'function' ? source() : source
@@ -460,4 +464,16 @@ export function apply(ctx, config = {}) {
       }
     }, 'session-guard: routes')
   }
+
+  // ── settings webServer 桥（M4/T20-b 泛化）：describe/mutate 两端点 ──────
+  // 双轨数据源的桥轨：≤0.1.5（settingsScope 死路/无服务）时 client
+  // BridgeDocHandle 经此读写宿主 settings 服务。getSettingsSvc 惰性取
+  // （cordis ctx.get 永不 throw）——宿主 settings 解析早晚不影响注册。
+  // 置于 prefix 路由之后（routes[0] = /session-guard 前缀，契约与测试锚定）。
+  // fail-open：注册失败 error 告警（对齐 L474 风格），不炸插件加载。
+  try {
+    registerSettingsBridgeRoutes(ctx.webServer, () => settingsSvcRef, NS)
+  } catch (error) {
+    ctx.logger?.error?.(`[session-guard] settings bridge registration failed: ${String(error && error.message || error)}`)
+  }
 }

package/src/settings-bridge.js

@@ -0,0 +1,141 @@
+/**
+ * dsh-session-guard — settings webServer 桥（M4/T20-b 泛化）。
+ *
+ * 设置卡双轨数据源的桥轨：≤0.1.5（settingsScope fiber 永不解 / 0.1.0-0.1.1 无
+ * client 服务）时，client BridgeDocHandle 经 describe/mutate 两端点读写宿主
+ * settings 服务。桥只是 HTTP 皮：读 = svc.describe 取自家 ns 描述符；写 =
+ * svc.mutate 转 ops 落宿主服务（不落第二份状态）；mutate 成功即 describe 回填，
+ * 带 expectedRevision 乐观并发。守卫：POST-only + redactSecrets + 256KB。
+ * 语义与 perm-gate src/bridge.ts（5260fe6 泛化）逐字对齐，本仓为 JS 形态。
+ */
+
+/** 一个 settings ns 的桥路由对——client 侧（src/client/settings-bridge.ts）必须同式派生（测试钉死一致）。 */
+function settingsBridgeRoutesFor(ns) {
+  return { describe: `/api/${ns}/settings/describe`, mutate: `/api/${ns}/settings/mutate` }
+}
+
+function readJsonBody(req, limit = 256 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      size += buf.length
+      if (size > limit) {
+        reject(new Error('bridge body too large'))
+        if (typeof req.resume === 'function') req.resume()
+        return
+      }
+      chunks.push(buf)
+    })
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8')
+      if (raw === '') {
+        resolve({})
+        return
+      }
+      try {
+        resolve(JSON.parse(raw))
+      } catch (e) {
+        reject(e instanceof Error ? e : new Error(String(e)))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+function sendJson(res, code, body) {
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+  res.end(JSON.stringify(body))
+}
+
+function isConflict(e) {
+  return e instanceof Error && /conflict|revision/i.test(e.message)
+}
+
+function describeNs(svc, ns) {
+  return svc.describe({ redactSecrets: true }).find((d) => d.ns === ns)
+}
+
+/**
+ * 注册 describe/mutate 两端点（kind:'exact'）。
+ * @param {unknown} server 宿主 webServer 服务（须有 register(kind,path,handler)）
+ * @param {() => unknown} getSettingsSvc 惰性取宿主 settings 服务（cordis ctx.get 永不 throw，可安全常取）
+ * @param {string} ns 自家 settings 命名空间
+ * @returns {Array<() => void>} 注销函数数组
+ */
+export function registerSettingsBridgeRoutes(server, getSettingsSvc, ns) {
+  if (typeof server !== 'object' || server === null) return []
+  const ws = typeof server.register === 'function' ? server : undefined
+  if (ws === undefined) return []
+  const offs = []
+  const routes = settingsBridgeRoutesFor(ns)
+
+  offs.push(ws.register({
+    kind: 'exact',
+    path: routes.describe,
+    handler: (req, res) => {
+      if (req.method !== 'POST') {
+        sendJson(res, 405, { ok: false, code: 'method-not-allowed' })
+        return
+      }
+      const svc = getSettingsSvc()
+      if (svc === undefined || svc === null || typeof svc.describe !== 'function') {
+        sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service not resolved yet' })
+        return
+      }
+      try {
+        const descriptor = describeNs(svc, ns)
+        if (descriptor === undefined) {
+          sendJson(res, 200, { ok: false, code: 'ns-not-registered', message: `settings namespace "${ns}" is not registered` })
+          return
+        }
+        sendJson(res, 200, { ok: true, value: { descriptor, writable: svc.writable !== false } })
+      } catch (e) {
+        sendJson(res, 200, { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) })
+      }
+    },
+  }))
+
+  offs.push(ws.register({
+    kind: 'exact',
+    path: routes.mutate,
+    handler: (req, res) => {
+      if (req.method !== 'POST') {
+        sendJson(res, 405, { ok: false, code: 'method-not-allowed' })
+        return
+      }
+      const svc = getSettingsSvc()
+      if (svc === undefined || svc === null || typeof svc.mutate !== 'function') {
+        sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service mutate not available' })
+        return
+      }
+      readJsonBody(req).then((body) => {
+        const ops = body.ops
+        const valid = Array.isArray(ops) && ops.every((op) => op !== null && typeof op === 'object' && (op.op === 'set' || op.op === 'unset'))
+        if (!valid) {
+          sendJson(res, 200, { ok: false, code: 'settings-rejected', message: 'malformed bridge mutate ops' })
+          return
+        }
+        const expectedRevision = typeof body.expectedRevision === 'number' ? body.expectedRevision : undefined
+        svc.mutate(ns, ops, expectedRevision).then(() => {
+          // mutate 成功即 describe 回填（写路径归口宿主服务，无第二份状态）
+          const descriptor = describeNs(svc, ns)
+          if (descriptor === undefined) {
+            sendJson(res, 200, { ok: false, code: 'internal', message: `namespace "${ns}" disposed after mutate` })
+            return
+          }
+          sendJson(res, 200, { ok: true, value: { descriptor } })
+        }).catch((e) => {
+          sendJson(res, 200, isConflict(e)
+            ? { ok: false, code: 'settings-conflict', message: e instanceof Error ? e.message : String(e) }
+            : { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) })
+        })
+      }).catch((e) => {
+        sendJson(res, 200, { ok: false, code: 'bad-request', message: e instanceof Error ? e.message : String(e) })
+      })
+    },
+  }))
+
+  return offs
+}

package/src/client/shell-overlay.tsx

@@ -1,69 +0,0 @@
-/**
- * dsh-session-guard — 无设置页宿主（0.1.0/0.1.1）的兜底配置入口。
- *
- * 壳级 `shell.overlay` 席位渲染：右下角固定齿轮钮，点开固定定位浮层承载
- * SessionGuardCard（page 形态，默认展开）。配置存储全在 host 侧（settings
- * 服务），浮层与宿主设置页解耦——壳再老也不影响读写。有设置页的宿主上
- * 该齿轮与行配置卡/家族 tab 并存，作为全局快捷入口。
- */
-import { useState } from 'react'
-import { SessionGuardCard } from './settings-card'
-import type { SessionGuardConfig } from './settings-card'
-import type { SettingsScope } from './scope-face'
-
-export function ShellSettingsEntry(props: {
-  scope: SettingsScope<SessionGuardConfig>
-}): JSX.Element {
-  const [open, setOpen] = useState(false)
-  return (
-    <div style={{ position: 'fixed', right: 16, bottom: 64, zIndex: 10000 }}>
-      {open && (
-        <div
-          onClick={() => setOpen(false)}
-          style={{ position: 'fixed', top: 0, left: 0, right: 0, bottom: 0, background: 'rgba(0,0,0,.45)', zIndex: 10000 }}
-        />
-      )}
-      {open && (
-        <div
-          style={{
-            position: 'fixed',
-            top: '6vh',
-            left: '50%',
-            transform: 'translateX(-50%)',
-            width: 'min(760px, 92vw)',
-            maxHeight: '84vh',
-            overflowY: 'auto',
-            zIndex: 10001,
-          }}
-        >
-          <button
-            type="button"
-            onClick={() => setOpen(false)}
-            style={{ position: 'sticky', top: 6, float: 'right', marginRight: 8, zIndex: 2 }}
-          >
-            ✕ 关闭
-          </button>
-          <SessionGuardCard scope={props.scope} />
-        </div>
-      )}
-      <button
-        type="button"
-        title="会话守护设置"
-        onClick={() => setOpen(state => !state)}
-        style={{
-          width: 40,
-          height: 40,
-          borderRadius: '50%',
-          border: '1px solid rgba(127,127,127,.4)',
-          background: 'rgba(30,30,32,.85)',
-          color: 'inherit',
-          cursor: 'pointer',
-          fontSize: 16,
-          boxShadow: '0 4px 16px rgba(0,0,0,.35)',
-        }}
-      >
-        🛡
-      </button>
-    </div>
-  )
-}