@tool-bridge/server 0.5.0 → 0.10.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import * as http from 'node:http';
+import { Sql } from 'postgres';
 import { Hono } from 'hono';
 
 /**
@@ -84,6 +85,29 @@ interface StateStore {
         }>;
     }>;
     put(key: string, value: unknown): Promise<void>;
+    /**
+     * 可选原子原语:key 不存在则写入并返回 true;已存在则不覆盖并返回 false。
+     * 用途是多副本/多 isolate 并发引导的 winner-takes-all 去重(如 Admin SK 铸造)。
+     * SQL 后端原子实现;Workers KV 最终一致且无 CAS,**不实现**此方法——调用方必须
+     * 容忍回退到非原子的 get-miss→put,并保证重复写幂等或后果可接受。
+     * 可选而非必选:必选会破坏 SDK 消费者已实现的自定义 StateStore。
+     */
+    putIfAbsent?(key: string, value: unknown): Promise<boolean>;
+}
+
+/**
+ * TBError:平台统一错误类型与 TBError↔HTTP 映射。
+ *
+ * core 是纯逻辑内核,不依赖任何运行时(Workers / Node)——错误的 HTTP 呈现
+ * 由网关层读取此处的 `httpStatus` 与 `toJSON()` 完成,core 只定义契约。
+ */
+/** 7 个规范错误码。 */
+type TBErrorCode = 'not_found' | 'permission_denied' | 'invalid_argument' | 'conflict' | 'unavailable' | 'rate_limited' | 'internal';
+/** 线上 body 形状:~help、返回值、错误响应统一用它。 */
+interface TBErrorBody {
+    code: TBErrorCode;
+    message: string;
+    retryable: boolean;
 }
 
 /**
@@ -461,6 +485,54 @@ interface ObjectStore {
     put(key: string, body: ObjectBody, opts?: ObjectPutOptions): Promise<ObjectMeta>;
 }
 
+/**
+ * DeviceFrame:设备 WS 帧协议的类型与编解码。
+ *
+ * JSON 文本帧、`type` 区分;decode 拒绝非 JSON / 未知 type / 缺字段(invalid_argument),
+ * encode 产出紧凑 JSON。ping/pong 序列化为稳定字面量(PING_FRAME_JSON/PONG_FRAME_JSON)——
+ * DO 的 setWebSocketAutoResponse 按字符串精确匹配,设备侧心跳帧不得有其他序列化形态。
+ */
+
+/**
+ * 网关鉴权后为本次 call 生成的调用方来源与权威期限。
+ * 全部由网关签发,不接受来自调用 arguments;设备只消费不自造,且不做授权裁决
+ * (scope 判定在网关侧已完成)。故意不含 scopes / SK / 敏感参数。
+ */
+interface DeviceCallContext {
+    caller: {
+        displayName?: string;
+        /** 本次调用使用的 SK id(非明文,审计用)。 */
+        keyId: string;
+        owner: OwnerRef;
+    };
+    /** 网关签发时刻(网关时钟,非设备本地时钟)。 */
+    createdAt: Timestamp;
+    /** 本次调用的权威失效时刻;设备复检一律以此比对,不信任设备本地时钟。 */
+    expiresAt: Timestamp;
+    /** 全链路观测,与 call id 同源。 */
+    traceId: string;
+}
+
+/**
+ * 网关侧设备会话状态机(纯逻辑,I/O 与时间注入,DO 只做胶水)。
+ *
+ * - awaiting-hello → ready:hello 经 io.onHello 交胶水层做 Check(register),
+ *   通过则 accept(mountPath)(回 ready 帧),否则 reject(error)(拒绝帧 + close(1008))。
+ * - 未 hello 先发非 hello 帧 / hello 重复 / 设备发出网关方向帧 → 拒绝帧 + 关闭。
+ * - call:requestId 幂等表——已有结果的重复 id 立即以首次结果应答;结果未到的重复 id
+ *   挂到同一待决项,不重复下发 call 帧。
+ * - 超时(DEVICE_CALL_TIMEOUT_MS):给调用方 unavailable(retryable:true),给设备 cancel 帧;
+ *   迟到的 result 仅入幂等表(后续重复 id 以它应答)。
+ */
+
+type DeviceCallResult = {
+    ok: true;
+    value: unknown;
+} | {
+    error: TBErrorBody;
+    ok: false;
+};
+
 /**
  * Tool Layer 的中立类型。
  *
@@ -579,6 +651,52 @@ interface SqlSearchStatement {
     readonly params: readonly unknown[];
     readonly sql: string;
 }
+/**
+ * 固定形态语句:参数个数与语义在 core 编排里写死,方言只提供 SQL 文本。
+ * 占位符语法(`?` / `$n`)与字符串函数由各方言自行决定。
+ */
+interface SqlSearchStatements {
+    readonly bumpRevision: string;
+    readonly completeRebuild: string;
+    readonly deleteAllSnapshots: string;
+    readonly deleteAllTools: string;
+    readonly deleteSnapshot: string;
+    readonly deleteSnapshotPrefix: string;
+    readonly deleteTools: string;
+    readonly deleteToolsPrefix: string;
+    /** 单 path 的 path→digest 快照插入(replace 内联使用)。 */
+    readonly insertSnapshot: string;
+    /** 读 meta 单例(revision/seeded/cursor_secret)。 */
+    readonly meta: string;
+    /** replace 前置探测:本 path 的 digest、是否残留 source 行、已用节点数。 */
+    readonly pathState: string;
+    /** 单 path 是否存在 source 行。 */
+    readonly present: string;
+    /** path 或其子树是否存在 source 行。 */
+    readonly presentPrefix: string;
+    /** 全量快照 digest,按 path 升序。 */
+    readonly snapshotDigests: string;
+}
+/**
+ * SQL 方言:把与具体引擎绑定的 SQL 文本从数据库无关的编排里分出来。
+ *
+ * `SqlSearchIndex` 只认识本接口——候选查询 + 一组固定语句 + 建表 DDL。
+ * D1 与 better-sqlite3 同为 SQLite,共用 {@link sqliteSearchDialect};其它引擎
+ * (如 Postgres)实现自己的方言,替换全文检索与占位符语法。方言只管 SQL 文本,
+ * 具体驱动的同步/异步、批量预算、结果整形仍由 {@link SqlSearchDriver} 吸收。
+ */
+interface SqlSearchDialect {
+    /**
+     * 把已 normalize 的 query 变成候选查询语句(含排序与分页)。
+     * prepare(分词、短/长词切分、方言专属语法)由各方言自理——SQLite 走 trigram
+     * FTS + 短词 LIKE,PG 走 ILIKE 子串;编排层只给 normalized query,不预设方言。
+     */
+    candidateStatement(query: string, limit: number, offset: number): SqlSearchStatement;
+    /** 建表(幂等),元素不带尾分号。 */
+    readonly schemaStatements: readonly string[];
+    /** 编排直接下发的固定语句。 */
+    readonly statements: SqlSearchStatements;
+}
 /**
  * 宿主驱动:把 `SqlSearchStatement` 落到具体数据库上。
  *
@@ -607,7 +725,8 @@ interface SqlSearchDriver {
 declare class SqlSearchIndex implements MutableSearchIndex {
     protected readonly driver: SqlSearchDriver;
     readonly capabilities: readonly SearchCapability[];
-    constructor(driver: SqlSearchDriver);
+    protected readonly dialect: SqlSearchDialect;
+    constructor(driver: SqlSearchDriver, dialect?: SqlSearchDialect);
     /** 容量 trigger 的 ABORT 在各驱动里错误形状不同,统一按标记串归一。 */
     private writeOrCapacity;
     private meta;
@@ -694,6 +813,8 @@ interface RemoteSettings {
 /** 帧协议 call 转发的入参(id 由调用点生成,幂等键)。 */
 interface DeviceInvokeRequest {
     arguments: Record<string, unknown>;
+    /** 网关鉴权后的调用方来源与权威期限;缺省则不写入 call 帧。 */
+    context?: DeviceCallContext;
     id: string;
     path: string;
     tool: string;
@@ -712,6 +833,18 @@ interface LocalProviderHooks {
     /** kind:'tool' 节点按路径取进程内工具源;undefined → 走 plugin 解析。 */
     tool?(nodePath: TreePath): UpstreamProvider | undefined;
 }
+/**
+ * 就绪探测报告(GET /readyz 的响应体)。checks 逐后端给出连通结果;
+ * ready=false → 503,编排器(k8s readiness / LB)据此摘除流量。
+ * detail 只放短语级原因(如 "timeout after 1000ms"),不放凭证或拓扑细节。
+ */
+interface ReadinessReport {
+    checks: Record<string, {
+        detail?: string;
+        ok: boolean;
+    }>;
+    ready: boolean;
+}
 /**
  * tb app 的宿主注入面(五注入点 + 解析后的部署配置)。
  * 核心业务逻辑零分叉:Workers 适配层(app.ts)与 SDK(packages/sdk)都注入此形状。
@@ -753,6 +886,12 @@ interface TbAppDeps {
      * 那个插件解析不出 export;反之则解析得出但调不动(unavailable)。宿主该两者同源装配。
      */
     pluginCatalog?: BuiltinCatalog;
+    /**
+     * 后端连通性探测(GET /readyz;k8s readiness)。宿主注入闭包,自行探测其长连接
+     * 后端(PG 池 / Redis)并叠加 draining 状态。缺省 → /readyz 恒 200:请求期绑定
+     * 宿主(Workers 的 KV/D1/R2)无"断连"态,嵌入宿主自理。
+     */
+    readiness?: () => Promise<ReadinessReport>;
     /** context Get 的 $ref 内联阈值(字节,缺省 1 MiB)。 */
     refThresholdBytes?: number;
     /** $ref URL(presign 与 /~ref 中转)有效期秒(缺省 900)。 */
@@ -785,7 +924,8 @@ declare function createTbApp(deps: TbAppDeps): Hono<{
 
 /**
  * Node 宿主的 env 配置面。变量名与语义对齐 CF 宿主(gateway/src/app.ts 的 Env),
- * 仅新增宿主形态相关的 TB_PORT / TB_HOST / TB_DATA_DIR / TB_UI_DIR。
+ * 仅新增宿主形态相关的 TB_PORT / TB_HOST / TB_DATA_DIR / TB_UI_DIR / TB_DATABASE_URL。
+ * 端口额外兜底平台注入的 PORT(PaaS 通行约定)。
  * 解析函数镜像 app.ts 的 allowInsecure / remoteSettingsFromEnv / positiveIntEnv。
  */
 
@@ -804,6 +944,11 @@ interface ServerConfig {
      * configFromEnv 抛错,进程拒绝启动(fail closed,不静默回退到请求期 origin)。
      */
     canonicalOrigin?: string;
+    /**
+     * Postgres 连接串(TB_DATABASE_URL)。给出则 StateStore 与 SearchIndex 都走 PG
+     * (ILIKE 子串检索,无扩展依赖);缺省回退到 dataDir 下的 SQLite。
+     */
+    databaseUrl?: string;
     /** SQLite 库与 fs 对象根所在目录(state.sqlite3 + objects/)。 */
     dataDir: string;
     /** 设备断线后未重连的回收秒数(缺省 24h)。 */
@@ -811,6 +956,18 @@ interface ServerConfig {
     /** SecretStore 主密钥 + $ref 中转 token 签名密钥(base64url 32B)。 */
     encryptionKey?: string;
     host: string;
+    /**
+     * 平台对象存储(context `$ref` 大对象落点)。给出则用 S3/R2 兼容端点,
+     * 缺省回退 dataDir 下的本地 FS。配 S3 后容器可无状态横向扩容 —— FS 落点
+     * 在多副本间互不可见、容器重建即丢。
+     */
+    objectStore?: {
+        accessKeyId: string;
+        bucket: string;
+        endpoint: string;
+        region?: string;
+        secretAccessKey: string;
+    };
     /**
      * 进程内插件装配表(binding 名 → fetch handler)。缺省时 bin 入口装配**全量内置目录**
      * (见 `main.ts`);程序化嵌入方可给自己的表来覆盖或裁剪。
@@ -822,6 +979,14 @@ interface ServerConfig {
      */
     pluginCatalog?: BuiltinCatalog;
     port: number;
+    /**
+     * 多副本设备通道路由的 Redis 连接串(TB_REDIS_URL)。
+     *
+     * 设备的 WebSocket 是活 socket、只存在于接受它的进程里,故多副本时打给"连在别的
+     * 副本上的设备"的调用必须跨副本转发。配上即启用路由表 + pub/sub 转发;
+     * 单副本部署不需要配(本地直连恒命中)。
+     */
+    redisUrl?: string;
     refThresholdBytes?: number;
     refTtlSec?: number;
     remote: {
@@ -830,12 +995,110 @@ interface ServerConfig {
         instanceId?: string;
         maxHops: number;
     };
+    /**
+     * 本副本标识(TB_REPLICA_ID),路由表的 value。缺省用 hostname —— 容器平台上
+     * 每个副本的 hostname 天然唯一;同机多进程需显式区分。
+     */
+    replicaId?: string;
+    /**
+     * SIGTERM 后先置 draining(/readyz 转 503)再关停的等待秒数(TB_SHUTDOWN_DRAIN_SEC,
+     * 缺省 0)。k8s 滚动更新时 endpoint 摘除有传播延迟,不等一拍就关会把仍被路由过来的
+     * 请求吃闭门羹;单机/本地开发保持 0,关停立即进行。
+     */
+    shutdownDrainSec?: number;
     toolCacheTtlSec?: number;
     /** Dashboard 静态资源目录覆盖(缺省经 @tool-bridge/dashboard 包解析)。 */
     uiDir?: string;
 }
 declare function configFromEnv(env?: NodeJS.ProcessEnv): ServerConfig;
 
+/**
+ * DeviceRouter:多副本部署下的设备调用路由。
+ *
+ * 为什么不能只换个存储 —— 设备的 WebSocket 是**活 socket**,只存在于接受它的那个
+ * 进程里,不可序列化。副本 B 收到打给"连在副本 A 上的设备"的 HTTP 调用时,B 手里
+ * 没有那个 socket,必须把调用**转发**给 A、再把结果收回来。所以这里是两件事:
+ *
+ *   1. 路由表(Redis string,带 TTL):deviceId → 持有者副本 ID。TTL + 周期续期让
+ *      副本崩溃后条目自动过期,不需要墓碑清理。
+ *   2. 请求/响应转发(Redis pub/sub):B 往 A 的频道发 call、A 执行完往 B 的回执
+ *      频道发 result。跨副本的请求-响应用 correlationId 关联,并有独立超时兜底 ——
+ *      A 在执行途中崩溃时 B 不能永久挂起。
+ *
+ * 本副本自己持有连接时**完全不经这里**(DeviceHub 先查本地 Map),故单副本部署零额外
+ * 开销、也不需要配 Redis。
+ *
+ * 与 CF 宿主的对照:那边用 Durable Object,天然"每设备一个单点",不存在这个问题。
+ * 本模块是 Node 多副本的等价物。
+ */
+
+/** 路由条目 TTL;续期周期取其 1/3,保证正常情况下不会因抖动过期。 */
+declare const DEVICE_ROUTE_TTL_SEC = 30;
+/** 跨副本转发的等待上限(毫秒)。持有者副本崩溃时靠它兜底,不能永久挂起。 */
+declare const DEVICE_FORWARD_TIMEOUT_MS = 65000;
+/**
+ * DeviceHub 需要的 Redis 能力子集。
+ *
+ * 抽成接口而非直接用 ioredis:让 DeviceHub 不依赖具体客户端,单测可注入内存实现,
+ * 也便于将来换 Valkey / 其它 pub/sub 后端。
+ */
+interface DeviceRouterBackend {
+    /** 删除本副本持有的路由条目(仅当当前值仍是自己,避免删掉已顶替者的条目)。 */
+    clearRoute(deviceId: string, replicaId: string): Promise<void>;
+    close(): Promise<void>;
+    /** 查 deviceId 的持有者副本;无则 null。 */
+    lookupRoute(deviceId: string): Promise<string | null>;
+    /** 向某副本的频道发布消息。 */
+    publish(channel: string, payload: string): Promise<void>;
+    /** 声明/续期:deviceId 由本副本持有,TTL 秒后过期。 */
+    setRoute(deviceId: string, replicaId: string, ttlSec: number): Promise<void>;
+    /** 订阅频道;handler 收到原始 payload。 */
+    subscribe(channel: string, handler: (payload: string) => void): Promise<void>;
+}
+/**
+ * 跨副本调用的发起侧与接收侧编排。
+ *
+ * DeviceHub 只跟本类打交道:`invoke` 时若本地无连接就问 `forward`,
+ * 并把"本副本能否执行某设备调用"的能力通过 `onLocalCall` 交回来。
+ */
+declare class DeviceRouter {
+    readonly replicaId: string;
+    private readonly backend;
+    private readonly opts;
+    private readonly pending;
+    private renewTimer;
+    /** 本副本当前持有的设备(需周期续期路由条目)。 */
+    private readonly owned;
+    constructor(replicaId: string, backend: DeviceRouterBackend, opts: {
+        forwardTimeoutMs?: number;
+        /** 收到转发来的调用时,在本副本执行(本地无该连接则返回 offline)。 */
+        onLocalCall: (deviceId: string, req: DeviceInvokeRequest) => Promise<DeviceCallResult>;
+        ttlSec?: number;
+    });
+    private get ttlSec();
+    /** 订阅本副本的两个频道并启动路由续期。 */
+    start(): Promise<void>;
+    /** 本副本接受了某设备的连接:声明所有权。 */
+    claim(deviceId: string): Promise<void>;
+    /** 本副本失去某设备的连接:释放所有权。 */
+    release(deviceId: string): Promise<void>;
+    /** 某设备当前是否在**任一**副本上在线(reclaim 判定用,不能只看本副本)。 */
+    isOnlineAnywhere(deviceId: string): Promise<boolean>;
+    /**
+     * 把调用转发给持有该设备的副本并等结果。
+     * 无人持有 → null(调用方按 deviceOffline 处理)。
+     */
+    forward(deviceId: string, req: DeviceInvokeRequest): Promise<DeviceCallResult | null>;
+    close(): Promise<void>;
+    /** correlationId 的进程内序号(与 replicaId 组合后全局唯一)。 */
+    private static seq;
+    private renewOwned;
+    /** 作为持有者:执行本地调用并回执。 */
+    private handleForwardedCall;
+    /** 作为发起方:收到回执,唤醒等待者。 */
+    private handleReply;
+}
+
 /**
  * DeviceHub:Node 宿主的设备通道(DeviceChannel 实现,对位 CF 的 DeviceSession DO)。
  *
@@ -852,6 +1115,8 @@ declare function configFromEnv(env?: NodeJS.ProcessEnv): ServerConfig;
  *   探活(isAlive + 周期 ping + terminate)踢半开死连接,避免调用一律吃 60s 超时。
  */
 
+/** router 回调本副本执行设备调用的签名。 */
+type DeviceLocalCall = (deviceId: string, req: DeviceInvokeRequest) => Promise<DeviceCallResult>;
 declare const DEVICE_WS_PATH = "/system/device/ws";
 declare class DeviceHub {
     private readonly store;
@@ -862,16 +1127,38 @@ declare class DeviceHub {
     private readonly connections;
     private readonly reclaimTimers;
     private heartbeat;
+    /** 多副本路由;缺省(单副本)时所有跨副本逻辑短路,行为与之前完全一致。 */
+    private router;
     constructor(opts: {
         heartbeatMs?: number;
         reclaimSec: number;
+        /** 多副本部署的调用路由工厂;拿到 onLocalCall 回调后构造(避免循环依赖)。 */
+        router?: (onLocalCall: DeviceLocalCall) => DeviceRouter;
         search?: MutableSearchIndex;
         store: StateStore;
     });
+    /**
+     * 启动多副本路由(订阅本副本频道 + 路由续期)。单副本时是 no-op。
+     * 必须在开始服务前完成:订阅没建好时转发进来的调用会丢。
+     */
+    startRouter(): Promise<void>;
     /** 挂到 http.Server 的 'upgrade' 事件(仅处理 DEVICE_WS_PATH,其余 404)。 */
     attach(server: http.Server): void;
-    /** DeviceChannel.invoke:HTTP→WS 调用转发(无活连接 → deviceOffline)。 */
+    /**
+     * DeviceChannel.invoke:HTTP→WS 调用转发。
+     *
+     * 本副本持有该设备 → 直接走本地 socket(单副本部署恒走这条,零额外开销)。
+     * 本地没有但配了 router → 问路由表并转发给持有者副本(socket 不可序列化,
+     * 只能把调用送到 socket 所在进程)。都没有 → deviceOffline。
+     */
     invoke(deviceId: string, req: DeviceInvokeRequest): Promise<unknown>;
+    /**
+     * 只走本副本 socket 的调用执行。
+     *
+     * router 收到转发来的调用时回调这里 —— **不能**回调 `invoke`:本地连接刚断时
+     * 那会再次查路由并转发,在两个副本间弹来弹去。这里没有连接就直接 offline。
+     */
+    private invokeLocal;
     /** DeviceChannel.ws:Node 宿主的升级在 http 层处理,永不应命中此路由。 */
     ws(): Promise<Response>;
     /**
@@ -905,6 +1192,114 @@ declare class DeviceHub {
 
 declare function createDataObjectStore(dataDir: string): ObjectStore;
 
+/**
+ * PgSearchIndex:postgres.js 驱动的 SearchIndex(ILIKE 子串检索)。
+ *
+ * 方言(SQL 文本、$n 占位符、ILIKE 检索)在 core 的 pgSearchDialect;
+ * 本文件只吸收 postgres.js 的驱动差异:全异步、写入走 sql.begin() 事务、多行 VALUES
+ * 批量插入(PG 无 D1 的 50 查询预算,故不实现 assertInsertBudget)。
+ *
+ * 不需要任何 PG 扩展:检索是纯 ILIKE,cursor_secret 用内置 gen_random_uuid()。
+ * 因此连接角色无需建扩展权限(受限托管环境常不给),只要能建表。
+ */
+
+/** Node 自托管宿主的 postgres.js SearchIndex。 */
+declare class PgSearchIndex extends SqlSearchIndex {
+    constructor(sql: Sql);
+}
+
+/**
+ * PgStateStore:postgres.js 实现的 StateStore(自托管 Node 宿主的 PG 后端)。
+ *
+ * 与 SqliteStateStore 同形:单表 kv(key text primary key, value jsonb),值以
+ * JSON 存取,强一致。list 用 key 范围扫描(>= prefix AND < successor(prefix)),
+ * 不用 LIKE——key 里的路径段可含 '_'/'%',通配符转义是坑。
+ *
+ * 关键差异——排序 collation:PG 默认按 libc locale 排序,`<` 与 `ORDER BY` 的
+ * 顺序会和 JS(UTF-16 code unit)/SQLite(UTF-8 字节)不一致,直接让前缀范围扫描和
+ * cursor 分页错行漏行。故 key 列显式 `COLLATE "C"`(纯字节序),与 core
+ * MemoryStateStore / SqliteStateStore 的 cursor 语义对齐。防御性地对返回行再做
+ * startsWith 过滤。
+ */
+
+declare class PgStateStore implements StateStore {
+    private readonly sql;
+    constructor(sql: Sql);
+    /** 建表(幂等)。key COLLATE "C" 是字节序正确性的前提,不能省。 */
+    ensureSchema(): Promise<void>;
+    get(key: string): Promise<unknown | null>;
+    getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
+    put(key: string, value: unknown): Promise<void>;
+    putIfAbsent(key: string, value: unknown): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        cursor?: string;
+        items: Array<{
+            key: string;
+            value: unknown;
+        }>;
+    }>;
+}
+
+/**
+ * DeviceRouterBackend 的 Redis(ioredis)实现。
+ *
+ * 两条连接是**必须**的:Redis 连接一旦进入 subscribe 模式就不能再发普通命令,
+ * 而本副本既要订阅自己的频道、又要 GET/SET 路由并向别人 publish。
+ *
+ * clearRoute 用 Lua 做「值匹配才删」:设备刚从副本 A 迁到 B 时,A 的收尾不能删掉
+ * B 刚写入的条目 —— 否则设备明明在线却被判离线。GET+DEL 两步做不到原子,故用脚本。
+ */
+
+declare class RedisDeviceRouterBackend implements DeviceRouterBackend {
+    /** 命令连接(GET/SET/DEL/PUBLISH)。 */
+    private readonly commands;
+    /** 订阅连接(进入 subscribe 模式后不能发普通命令)。 */
+    private readonly subscriber;
+    private readonly handlers;
+    constructor(url: string);
+    setRoute(deviceId: string, replicaId: string, ttlSec: number): Promise<void>;
+    lookupRoute(deviceId: string): Promise<string | null>;
+    clearRoute(deviceId: string, replicaId: string): Promise<void>;
+    publish(channel: string, payload: string): Promise<void>;
+    /** 就绪探测(/readyz):命令连接 PING 一次。断连时 ioredis 会抛/挂起,由调用方限时。 */
+    ping(): Promise<void>;
+    subscribe(channel: string, handler: (payload: string) => void): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * createTbServer:Node 宿主装配(对位 gateway/src/app.ts 的 depsFromEnv)。
+ *
+ * StateStore/SearchIndex 后端二选一:给 TB_DATABASE_URL 走 Postgres,
+ * 否则走 dataDir 下的 SQLite。ObjectStore 始终是 fs。HTTP 用 @hono/node-server;
+ * 引导在 start() 时直调宿主中立 runBootstrap(Node 有真实启动点,不需要 Workers 的
+ * per-request once,故不注入 deps.ensureReady)。设备通道(DeviceHub)与 /ui 静态托管
+ * 由后续装配点注入(deps.device / deps.assets)。
+ */
+
+interface TbServer {
+    app: ReturnType<typeof createTbApp>;
+    close(): Promise<void>;
+    deviceHub: DeviceHub;
+    search: MutableSearchIndex;
+    /** 引导(幂等)+ 孤儿设备回收排程 + 监听;返回实际端口(config.port=0 时由系统分配)。 */
+    start(): Promise<{
+        port: number;
+    }>;
+    /**
+     * 进入 draining:/readyz 立即转 503(编排器摘流量),但继续服务既有与新到请求。
+     * SIGTERM 处理器先调它、等一拍(TB_SHUTDOWN_DRAIN_SEC)再 close(),避免 k8s
+     * endpoint 摘除传播期间仍被路由过来的请求吃闭门羹。幂等。
+     */
+    startDraining(): void;
+    state: StateStore;
+}
+declare function createTbServer(config: ServerConfig): TbServer;
+
 /** Node 宿主的 better-sqlite3 FTS5/trigram SearchIndex。 */
 declare class SqliteSearchIndex extends SqlSearchIndex {
     private readonly db;
@@ -937,6 +1332,7 @@ declare class SqliteStateStore implements StateStore {
     get(key: string): Promise<unknown | null>;
     getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
     put(key: string, value: unknown): Promise<void>;
+    putIfAbsent(key: string, value: unknown): Promise<boolean>;
     delete(key: string): Promise<void>;
     list(prefix: string, opts?: {
         cursor?: string;
@@ -951,26 +1347,4 @@ declare class SqliteStateStore implements StateStore {
     close(): void;
 }
 
-/**
- * createTbServer:Node 宿主装配(对位 gateway/src/app.ts 的 depsFromEnv)。
- *
- * SQLite StateStore + fs ObjectStore + @hono/node-server;引导在 start() 时
- * 直调宿主中立 runBootstrap(Node 有真实启动点,不需要 Workers 的 per-request once,
- * 故不注入 deps.ensureReady)。设备通道(DeviceHub)与 /ui 静态托管由后续
- * 装配点注入(deps.device / deps.assets)。
- */
-
-interface TbServer {
-    app: ReturnType<typeof createTbApp>;
-    close(): Promise<void>;
-    deviceHub: DeviceHub;
-    search: SqliteSearchIndex;
-    /** 引导(幂等)+ 孤儿设备回收排程 + 监听;返回实际端口(config.port=0 时由系统分配)。 */
-    start(): Promise<{
-        port: number;
-    }>;
-    state: SqliteStateStore;
-}
-declare function createTbServer(config: ServerConfig): TbServer;
-
-export { DEVICE_WS_PATH, DeviceHub, type ServerConfig, SqliteSearchIndex, SqliteStateStore, type TbServer, configFromEnv, createDataObjectStore, createTbServer };
+export { DEVICE_FORWARD_TIMEOUT_MS, DEVICE_ROUTE_TTL_SEC, DEVICE_WS_PATH, DeviceHub, type DeviceLocalCall, DeviceRouter, type DeviceRouterBackend, PgSearchIndex, PgStateStore, RedisDeviceRouterBackend, type ServerConfig, SqliteSearchIndex, SqliteStateStore, type TbServer, configFromEnv, createDataObjectStore, createTbServer };

package/dist/index.js

@@ -1,17 +1,29 @@
 import {
+  DEVICE_FORWARD_TIMEOUT_MS,
+  DEVICE_ROUTE_TTL_SEC,
   DEVICE_WS_PATH,
   DeviceHub,
+  DeviceRouter,
+  PgSearchIndex,
+  PgStateStore,
+  RedisDeviceRouterBackend,
   SqliteSearchIndex,
   SqliteStateStore,
   configFromEnv,
   createDataObjectStore,
   createTbServer
-} from "./chunk-3C3J36GT.js";
-import "./chunk-7PM4FD5K.js";
+} from "./chunk-Q7YHZ2SD.js";
+import "./chunk-TPGTA43F.js";
 import "./chunk-MLKGABMK.js";
 export {
+  DEVICE_FORWARD_TIMEOUT_MS,
+  DEVICE_ROUTE_TTL_SEC,
   DEVICE_WS_PATH,
   DeviceHub,
+  DeviceRouter,
+  PgSearchIndex,
+  PgStateStore,
+  RedisDeviceRouterBackend,
   SqliteSearchIndex,
   SqliteStateStore,
   configFromEnv,

package/dist/{ip2proxy-IKV5IWUI.js → ip2proxy-KOA2JUNV.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-FHYFPPBZ.js";
+} from "./chunk-2DA2UI37.js";
 import {
   guardedFetch
-} from "./chunk-7GP7DRES.js";
-import "./chunk-B4ZA7EGO.js";
+} from "./chunk-SBJMMSPA.js";
+import "./chunk-Q44CYUSI.js";
 import {
   TBError,
   external_exports
-} from "./chunk-7PM4FD5K.js";
+} from "./chunk-TPGTA43F.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/ip2proxy/schema.ts

package/dist/{ipgeolocation_io-NSUWUF5X.js → ipgeolocation_io-KNOQD7R7.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-FHYFPPBZ.js";
+} from "./chunk-2DA2UI37.js";
 import {
   guardedFetch
-} from "./chunk-7GP7DRES.js";
-import "./chunk-B4ZA7EGO.js";
+} from "./chunk-SBJMMSPA.js";
+import "./chunk-Q44CYUSI.js";
 import {
   TBError,
   external_exports
-} from "./chunk-7PM4FD5K.js";
+} from "./chunk-TPGTA43F.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/ipgeolocation_io/api.ts

package/dist/{ipqualityscore-ZQKL3WLC.js → ipqualityscore-GF2MQKXI.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-FHYFPPBZ.js";
+} from "./chunk-2DA2UI37.js";
 import {
   guardedFetch
-} from "./chunk-7GP7DRES.js";
-import "./chunk-B4ZA7EGO.js";
+} from "./chunk-SBJMMSPA.js";
+import "./chunk-Q44CYUSI.js";
 import {
   TBError,
   external_exports
-} from "./chunk-7PM4FD5K.js";
+} from "./chunk-TPGTA43F.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/ipqualityscore/api.ts

package/dist/{jina_ai-F4Y7V5AS.js → jina_ai-GB3CQPJ4.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-FHYFPPBZ.js";
+} from "./chunk-2DA2UI37.js";
 import {
   guardedFetch
-} from "./chunk-7GP7DRES.js";
-import "./chunk-B4ZA7EGO.js";
+} from "./chunk-SBJMMSPA.js";
+import "./chunk-Q44CYUSI.js";
 import {
   TBError,
   external_exports
-} from "./chunk-7PM4FD5K.js";
+} from "./chunk-TPGTA43F.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/jina_ai/api.ts