@myassis/gateway 1.0.85 → 1.0.87

package/dist/services/relay/protocol.js

@@ -0,0 +1,526 @@
+"use strict";
+/**
+ * ⚠️ 此文件由脚本自动生成，请勿手动编辑！
+ *
+ * 源文件： shared/src/relay/protocol.ts
+ * 生成方式：node scripts/sync-shared-source.js
+ *
+ * 如需修改，请编辑上述源文件后重新运行同步脚本。
+ * CI 会校验本文件与源文件的一致性，不一致将导致构建失败。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripHopByHopHeaders = exports.checkGatewayFeatures = exports.checkProtocolVersion = exports.ReceiveWindow = exports.SendWindow = exports.StreamIdAllocator = exports.decodeWsData = exports.encodeWsDataFrames = exports.MAX_WS_DATA_CHUNK = exports.WS_DATA_PREFIX_SIZE = exports.WsDataKind = exports.splitIntoFrames = exports.decodeJsonPayload = exports.decodeFrame = exports.encodeJsonFrame = exports.encodeFrame = exports.RelayProtocolError = exports.AbortReason = exports.isControlFrame = exports.isKnownFrameType = exports.frameTypeName = exports.FrameType = exports.CONTROL_STREAM_ID = exports.PING_TIMEOUT_MS = exports.PING_INTERVAL_MS = exports.MAX_CONCURRENT_STREAMS = exports.INITIAL_WINDOW_SIZE = exports.MAX_FRAME_PAYLOAD = exports.FRAME_HEADER_SIZE = exports.RELAY_REQUIRED_FEATURE = exports.RELAY_MIN_PROTOCOL_VERSION = exports.RELAY_PROTOCOL_VERSION = void 0;
+/**
+ * 中继帧协议（单源实现）
+ * ============================================================
+ * Gateway 与 Server 之间用一条 WSS 长连接承载多路 HTTP/WebSocket 流量，
+ * 因此需要一层帧协议做多路复用、流控与生命周期管理。
+ *
+ * 设计约束（来自 docs/RELAY_MODE.md）：
+ * 1. 帧必须能逐块转发，不得为了拼完整响应而缓冲 —— 否则 SSE 首字延迟被拖长。
+ * 2. 必须支持信用式流控，避免单个大上传/长响应打爆中继内存。
+ * 3. 必须携带协议版本，网关分布在用户机器上无法强制升级。
+ *
+ * 【本文件是单源，不从 shared/src/index.ts 导出】
+ * @myassis/shared 是以已发布包被消费的（gateway 钉 1.0.19、server 钉 1.0.24），
+ * 若同时可从包内导入，就会出现「包版本」与「同步副本」两个来源而重新引入漂移。
+ * 各端一律使用 scripts/sync-shared-source.js 生成的本地副本，CI 校验一致性。
+ *
+ * 帧结构（大端）：
+ *   +--------+------------------+------------------+
+ *   | type   | streamId         | payload          |
+ *   | 1 byte | 4 bytes (uint32) | 变长             |
+ *   +--------+------------------+------------------+
+ *
+ * streamId 为 0 表示连接级控制帧（HELLO/PING 等），与具体流无关。
+ */
+// ============ 常量 ============
+/** 当前帧协议版本 */
+exports.RELAY_PROTOCOL_VERSION = 1;
+/** Server 可接受的最低网关协议版本（低于此值要求用户升级网关） */
+exports.RELAY_MIN_PROTOCOL_VERSION = 1;
+/**
+ * 中继模式要求网关必备的能力位。
+ *
+ * 存在的原因是一次真实故障：一台机器上同时跑着新旧两个网关，端口顺延后
+ * 隧道由新实例建立、回环请求却落到旧实例，结果 /api/v1/* 全部 404 ——
+ * 隧道显示在线、/health 也 200，用户只看到一个无从下手的「404」。
+ * 有了能力位，服务端能在第一个请求就明确回答「这台网关太旧」。
+ */
+exports.RELAY_REQUIRED_FEATURE = 'relay@1';
+/** 帧头长度：1 字节 type + 4 字节 streamId */
+exports.FRAME_HEADER_SIZE = 5;
+/**
+ * 单帧载荷上限 64KB。
+ * 偏小是有意为之：帧越小，SSE/流式响应的转发粒度越细，首字延迟越低。
+ */
+exports.MAX_FRAME_PAYLOAD = 64 * 1024;
+/** 每条流的初始接收窗口（信用式流控） */
+exports.INITIAL_WINDOW_SIZE = 256 * 1024;
+/** 单条隧道允许的最大并发流数 */
+exports.MAX_CONCURRENT_STREAMS = 64;
+/** 心跳间隔与超时（毫秒） */
+exports.PING_INTERVAL_MS = 20000;
+exports.PING_TIMEOUT_MS = 60000;
+/** streamId 为 0 代表连接级控制帧 */
+exports.CONTROL_STREAM_ID = 0;
+/** streamId 取值上限（uint32） */
+const MAX_STREAM_ID = 0xffffffff;
+// ============ 帧类型 ============
+/**
+ * 帧类型。
+ *
+ * 用 const 对象而非 enum：server 端开启了 erasableSyntaxOnly，
+ * TS enum 会生成运行时代码因而被禁止。这样单源可被三端共同编译。
+ */
+exports.FrameType = {
+    // --- 连接级 ---
+    HELLO: 0x01,
+    HELLO_ACK: 0x02,
+    PING: 0x03,
+    PONG: 0x04,
+    // --- HTTP 请求/响应 ---
+    REQ_HEAD: 0x10,
+    REQ_DATA: 0x11,
+    REQ_END: 0x12,
+    RESP_HEAD: 0x13,
+    RESP_DATA: 0x14,
+    RESP_END: 0x15,
+    // --- 流控与生命周期 ---
+    STREAM_ABORT: 0x20,
+    WINDOW_UPDATE: 0x21,
+    // --- WebSocket 通道 ---
+    WS_OPEN: 0x30,
+    WS_DATA: 0x31,
+    WS_CLOSE: 0x32,
+};
+/** 帧类型 → 名称，用于日志与错误信息 */
+const FRAME_TYPE_NAMES = Object.fromEntries(Object.entries(exports.FrameType).map(([name, value]) => [value, name]));
+/** 取帧类型名称，未知类型返回十六进制值 */
+function frameTypeName(type) {
+    return FRAME_TYPE_NAMES[type] ?? `0x${type.toString(16)}`;
+}
+exports.frameTypeName = frameTypeName;
+/** 判断是否为已知帧类型 */
+function isKnownFrameType(value) {
+    return (value === exports.FrameType.HELLO ||
+        value === exports.FrameType.HELLO_ACK ||
+        value === exports.FrameType.PING ||
+        value === exports.FrameType.PONG ||
+        value === exports.FrameType.REQ_HEAD ||
+        value === exports.FrameType.REQ_DATA ||
+        value === exports.FrameType.REQ_END ||
+        value === exports.FrameType.RESP_HEAD ||
+        value === exports.FrameType.RESP_DATA ||
+        value === exports.FrameType.RESP_END ||
+        value === exports.FrameType.STREAM_ABORT ||
+        value === exports.FrameType.WINDOW_UPDATE ||
+        value === exports.FrameType.WS_OPEN ||
+        value === exports.FrameType.WS_CLOSE ||
+        value === exports.FrameType.WS_DATA);
+}
+exports.isKnownFrameType = isKnownFrameType;
+/** 控制帧（streamId 必须为 0） */
+const CONTROL_FRAME_TYPES = new Set([
+    exports.FrameType.HELLO,
+    exports.FrameType.HELLO_ACK,
+    exports.FrameType.PING,
+    exports.FrameType.PONG,
+]);
+/** 该帧类型是否为连接级控制帧 */
+function isControlFrame(type) {
+    return CONTROL_FRAME_TYPES.has(type);
+}
+exports.isControlFrame = isControlFrame;
+// ============ 中止原因 ============
+exports.AbortReason = {
+    /** 客户端主动断开（对应 Desktop 的 AbortController） */
+    CLIENT_CLOSED: 1,
+    /** 上游网关处理超时 */
+    TIMEOUT: 2,
+    /** 网关本地请求失败 */
+    GATEWAY_ERROR: 3,
+    /** 违反协议（如超窗、未知帧） */
+    PROTOCOL_ERROR: 4,
+    /** 超出配额或限流 */
+    QUOTA_EXCEEDED: 5,
+    /** 隧道正在关闭 */
+    TUNNEL_CLOSING: 6,
+};
+// ============ 错误类型 ============
+/** 协议层错误：解析失败、越界、非法字段等 */
+class RelayProtocolError extends Error {
+    reason;
+    constructor(message, reason = exports.AbortReason.PROTOCOL_ERROR) {
+        super(message);
+        this.name = 'RelayProtocolError';
+        this.reason = reason;
+    }
+}
+exports.RelayProtocolError = RelayProtocolError;
+// ============ 编码 ============
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: false });
+function assertValidStreamId(type, streamId) {
+    if (!Number.isInteger(streamId) || streamId < 0 || streamId > MAX_STREAM_ID) {
+        throw new RelayProtocolError(`非法 streamId: ${streamId}`);
+    }
+    if (isControlFrame(type) && streamId !== exports.CONTROL_STREAM_ID) {
+        throw new RelayProtocolError(`控制帧 ${frameTypeName(type)} 的 streamId 必须为 0，实际 ${streamId}`);
+    }
+    if (!isControlFrame(type) && streamId === exports.CONTROL_STREAM_ID) {
+        throw new RelayProtocolError(`流帧 ${frameTypeName(type)} 的 streamId 不得为 0`);
+    }
+}
+/**
+ * 编码一个帧。
+ * @throws RelayProtocolError 载荷超过上限或 streamId 非法
+ */
+function encodeFrame(type, streamId, payload = new Uint8Array(0)) {
+    if (!isKnownFrameType(type)) {
+        throw new RelayProtocolError(`未知帧类型: ${type}`);
+    }
+    assertValidStreamId(type, streamId);
+    if (payload.byteLength > exports.MAX_FRAME_PAYLOAD) {
+        throw new RelayProtocolError(`载荷 ${payload.byteLength} 字节超过单帧上限 ${exports.MAX_FRAME_PAYLOAD}，调用方需自行分片`);
+    }
+    const buf = new Uint8Array(exports.FRAME_HEADER_SIZE + payload.byteLength);
+    const view = new DataView(buf.buffer);
+    buf[0] = type;
+    view.setUint32(1, streamId, false);
+    buf.set(payload, exports.FRAME_HEADER_SIZE);
+    return buf;
+}
+exports.encodeFrame = encodeFrame;
+/** 将对象作为 JSON 载荷编码成帧 */
+function encodeJsonFrame(type, streamId, value) {
+    return encodeFrame(type, streamId, textEncoder.encode(JSON.stringify(value)));
+}
+exports.encodeJsonFrame = encodeJsonFrame;
+// ============ 解码 ============
+/**
+ * 解码一个完整帧。
+ *
+ * 注意：WebSocket 天然保留消息边界，因此这里按「一条消息 = 一个帧」处理，
+ * 不需要像 TCP 那样做粘包拆分。
+ *
+ * @throws RelayProtocolError 长度不足、类型未知或 streamId 非法
+ */
+function decodeFrame(data) {
+    if (data.byteLength < exports.FRAME_HEADER_SIZE) {
+        throw new RelayProtocolError(`帧长度 ${data.byteLength} 小于帧头 ${exports.FRAME_HEADER_SIZE}`);
+    }
+    const type = data[0];
+    if (!isKnownFrameType(type)) {
+        throw new RelayProtocolError(`未知帧类型: 0x${type.toString(16)}`);
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const streamId = view.getUint32(1, false);
+    assertValidStreamId(type, streamId);
+    const payloadLength = data.byteLength - exports.FRAME_HEADER_SIZE;
+    if (payloadLength > exports.MAX_FRAME_PAYLOAD) {
+        throw new RelayProtocolError(`载荷 ${payloadLength} 字节超过单帧上限 ${exports.MAX_FRAME_PAYLOAD}`);
+    }
+    // subarray 而非 slice：避免每帧都复制一次载荷
+    return {
+        type,
+        streamId,
+        payload: data.subarray(exports.FRAME_HEADER_SIZE),
+    };
+}
+exports.decodeFrame = decodeFrame;
+/**
+ * 把帧载荷解析为 JSON。
+ * @throws RelayProtocolError 载荷不是合法 JSON
+ */
+function decodeJsonPayload(payload) {
+    let text;
+    try {
+        text = textDecoder.decode(payload);
+    }
+    catch {
+        throw new RelayProtocolError('载荷不是合法 UTF-8');
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new RelayProtocolError('载荷不是合法 JSON');
+    }
+}
+exports.decodeJsonPayload = decodeJsonPayload;
+// ============ 分片 ============
+/**
+ * 将大块数据按单帧上限切分为多个帧。
+ *
+ * 用于请求体上传与响应体下发：调用方无需关心 MAX_FRAME_PAYLOAD，
+ * 但必须逐帧发送而不是等全部切完再发，否则又回到缓冲老路。
+ */
+function* splitIntoFrames(type, streamId, data) {
+    if (data.byteLength === 0) {
+        yield encodeFrame(type, streamId, data);
+        return;
+    }
+    for (let offset = 0; offset < data.byteLength; offset += exports.MAX_FRAME_PAYLOAD) {
+        const end = Math.min(offset + exports.MAX_FRAME_PAYLOAD, data.byteLength);
+        yield encodeFrame(type, streamId, data.subarray(offset, end));
+    }
+}
+exports.splitIntoFrames = splitIntoFrames;
+// ============ WebSocket 数据帧 ============
+/**
+ * WS_DATA 载荷的首字节标记原始消息类型。
+ *
+ * WebSocket 区分 text 与 binary 两种帧，且这一区分对上层可见
+ * （浏览器收到 binary 会给出 Blob/ArrayBuffer 而非 string）。
+ * 中继必须原样保持，否则网关侧 JSON.parse(data.toString()) 之类的
+ * 既有逻辑会因类型变化而失效。
+ */
+exports.WsDataKind = {
+    TEXT: 0,
+    BINARY: 1,
+};
+/** WS_DATA 载荷的类型标记长度 */
+exports.WS_DATA_PREFIX_SIZE = 1;
+/** WS_DATA 单帧可承载的最大原始数据量（需为标记留 1 字节） */
+exports.MAX_WS_DATA_CHUNK = exports.MAX_FRAME_PAYLOAD - exports.WS_DATA_PREFIX_SIZE;
+/**
+ * 把一条 WebSocket 消息编码为一个或多个 WS_DATA 帧。
+ *
+ * 注意分片语义：这里不额外标记「消息结束」，因为一条 WS 消息被拆成多帧后，
+ * 接收方需要按顺序拼回。为避免引入额外状态，超过单帧上限的消息在
+ * 每一帧都重复携带同一个类型标记，接收方按 streamId 顺序追加即可。
+ * 业务侧 WS 消息都是小体量 JSON，触发分片属极少数情况。
+ */
+function* encodeWsDataFrames(streamId, data, binary) {
+    const kind = binary ? exports.WsDataKind.BINARY : exports.WsDataKind.TEXT;
+    if (data.byteLength <= exports.MAX_WS_DATA_CHUNK) {
+        yield encodeFrame(exports.FrameType.WS_DATA, streamId, withKind(kind, data));
+        return;
+    }
+    for (let offset = 0; offset < data.byteLength; offset += exports.MAX_WS_DATA_CHUNK) {
+        const end = Math.min(offset + exports.MAX_WS_DATA_CHUNK, data.byteLength);
+        yield encodeFrame(exports.FrameType.WS_DATA, streamId, withKind(kind, data.subarray(offset, end)));
+    }
+}
+exports.encodeWsDataFrames = encodeWsDataFrames;
+function withKind(kind, data) {
+    const payload = new Uint8Array(exports.WS_DATA_PREFIX_SIZE + data.byteLength);
+    payload[0] = kind;
+    payload.set(data, exports.WS_DATA_PREFIX_SIZE);
+    return payload;
+}
+/**
+ * 解析 WS_DATA 载荷。
+ * @throws RelayProtocolError 载荷为空或类型标记非法
+ */
+function decodeWsData(payload) {
+    if (payload.byteLength < exports.WS_DATA_PREFIX_SIZE) {
+        throw new RelayProtocolError('WS_DATA 载荷缺少类型标记');
+    }
+    const kind = payload[0];
+    if (kind !== exports.WsDataKind.TEXT && kind !== exports.WsDataKind.BINARY) {
+        throw new RelayProtocolError(`未知 WS_DATA 类型标记: ${kind}`);
+    }
+    return {
+        binary: kind === exports.WsDataKind.BINARY,
+        data: payload.subarray(exports.WS_DATA_PREFIX_SIZE),
+    };
+}
+exports.decodeWsData = decodeWsData;
+// ============ streamId 分配 ============
+/**
+ * streamId 分配器。
+ *
+ * 双方都可主动发起流（Server 转发 Desktop 请求、网关侧暂无但保留），
+ * 为避免 id 撞车，一侧使用奇数、一侧使用偶数。
+ */
+class StreamIdAllocator {
+    next;
+    step = 2;
+    /** @param odd true 分配奇数（Server 侧），false 分配偶数（Gateway 侧） */
+    constructor(odd) {
+        this.next = odd ? 1 : 2;
+    }
+    allocate() {
+        const id = this.next;
+        // 回绕：跳过 0（保留给控制帧）
+        this.next += this.step;
+        if (this.next > MAX_STREAM_ID) {
+            this.next = this.next % 2 === 1 ? 1 : 2;
+        }
+        return id;
+    }
+}
+exports.StreamIdAllocator = StreamIdAllocator;
+// ============ 流控 ============
+/**
+ * 信用式发送窗口。
+ *
+ * 发送方每发出 N 字节就扣减 N 信用，收到 WINDOW_UPDATE 后补回。
+ * 信用耗尽时必须暂停读取上游（req.pause()），这是防止中继 OOM 的关键。
+ */
+class SendWindow {
+    available;
+    constructor(initial = exports.INITIAL_WINDOW_SIZE) {
+        this.available = initial;
+    }
+    /** 当前可用信用 */
+    get credit() {
+        return this.available;
+    }
+    /** 是否还能发送数据 */
+    canSend(bytes) {
+        return bytes <= this.available;
+    }
+    /**
+     * 消费信用。
+     * @throws RelayProtocolError 信用不足（调用方应先 canSend 判断并暂停上游）
+     */
+    consume(bytes) {
+        if (bytes > this.available) {
+            throw new RelayProtocolError(`发送窗口不足：需要 ${bytes}，可用 ${this.available}`);
+        }
+        this.available -= bytes;
+    }
+    /**
+     * 补充信用。
+     * @throws RelayProtocolError delta 非正或导致窗口溢出
+     */
+    increase(delta) {
+        if (!Number.isInteger(delta) || delta <= 0) {
+            throw new RelayProtocolError(`WINDOW_UPDATE 的 delta 必须为正整数，实际 ${delta}`);
+        }
+        if (this.available + delta > MAX_STREAM_ID) {
+            throw new RelayProtocolError('发送窗口溢出');
+        }
+        this.available += delta;
+    }
+}
+exports.SendWindow = SendWindow;
+/**
+ * 接收窗口。
+ *
+ * 消费掉数据后调用 consume() 累积待确认字节，
+ * 达到阈值（半窗）才发一次 WINDOW_UPDATE，避免每帧都回一个确认帧。
+ */
+class ReceiveWindow {
+    size;
+    pending = 0;
+    used = 0;
+    constructor(size = exports.INITIAL_WINDOW_SIZE) {
+        this.size = size;
+    }
+    /**
+     * 记录收到的数据。
+     * @throws RelayProtocolError 对端超发（协议违规）
+     */
+    receive(bytes) {
+        this.used += bytes;
+        if (this.used > this.size) {
+            throw new RelayProtocolError(`对端超发：已收 ${this.used} 超过窗口 ${this.size}`);
+        }
+    }
+    /**
+     * 标记数据已被消费，返回需要通告的 delta；
+     * 未达阈值返回 0 表示暂不发送 WINDOW_UPDATE。
+     */
+    consume(bytes) {
+        this.pending += bytes;
+        this.used -= bytes;
+        if (this.pending * 2 >= this.size) {
+            const delta = this.pending;
+            this.pending = 0;
+            return delta;
+        }
+        return 0;
+    }
+    /** 强制取出待确认字节（如流即将空闲时收尾） */
+    flush() {
+        const delta = this.pending;
+        this.pending = 0;
+        return delta;
+    }
+}
+exports.ReceiveWindow = ReceiveWindow;
+/**
+ * 校验网关上报的协议版本是否被本端接受。
+ *
+ * 网关分布在用户机器上无法强制升级，因此这里只做区间判断，
+ * 并给出明确原因，由 Desktop 决定提示「请升级网关」还是「请升级客户端」。
+ */
+function checkProtocolVersion(peerVersion) {
+    if (!Number.isInteger(peerVersion) || peerVersion <= 0) {
+        return { compatible: false, reason: `非法协议版本: ${peerVersion}` };
+    }
+    if (peerVersion < exports.RELAY_MIN_PROTOCOL_VERSION) {
+        return {
+            compatible: false,
+            reason: `网关协议版本 ${peerVersion} 过低（最低支持 ${exports.RELAY_MIN_PROTOCOL_VERSION}），请升级网关`,
+        };
+    }
+    if (peerVersion > exports.RELAY_PROTOCOL_VERSION) {
+        return {
+            compatible: false,
+            reason: `网关协议版本 ${peerVersion} 高于服务端支持的 ${exports.RELAY_PROTOCOL_VERSION}，请升级服务端`,
+        };
+    }
+    return { compatible: true };
+}
+exports.checkProtocolVersion = checkProtocolVersion;
+/**
+ * 校验网关能力位是否满足中继要求。
+ *
+ * 与协议版本分开判断：版本对得上只说明「帧能解开」，不代表网关真的具备
+ * 中继所需的业务路由（如 /auth/adopt-token）。旧网关完全可能协议版本正确
+ * 却缺少这些接口。
+ *
+ * features 缺失（undefined/空数组）也判为不兼容：能上报 features 本身就是
+ * 新版本的标志，宁可让老网关明确失败，也不要放它进来产生 404。
+ */
+function checkGatewayFeatures(features) {
+    if (!Array.isArray(features) || features.length === 0) {
+        return {
+            compatible: false,
+            reason: '网关未上报能力位，版本过旧，请升级网关后重试',
+        };
+    }
+    if (!features.includes(exports.RELAY_REQUIRED_FEATURE)) {
+        return {
+            compatible: false,
+            reason: `网关不支持中继能力 ${exports.RELAY_REQUIRED_FEATURE}，请升级网关后重试`,
+        };
+    }
+    return { compatible: true };
+}
+exports.checkGatewayFeatures = checkGatewayFeatures;
+// ============ 头部处理 ============
+/**
+ * hop-by-hop 头：仅对单跳连接有意义，不得透传到另一跳，
+ * 否则会出现「上游声明 chunked 但中继已解码」之类的语义错乱。
+ */
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+    'http2-settings',
+]);
+/** 剥离 hop-by-hop 头，并统一小写键名 */
+function stripHopByHopHeaders(headers) {
+    const result = {};
+    for (const [rawKey, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        const key = rawKey.toLowerCase();
+        if (HOP_BY_HOP_HEADERS.has(key))
+            continue;
+        result[key] = Array.isArray(value) ? value.join(', ') : value;
+    }
+    return result;
+}
+exports.stripHopByHopHeaders = stripHopByHopHeaders;

package/dist/services/relay/relayConfig.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * 中继客户端配置
+ *
+ * 网关的中继凭据（gatewayId / relaySecret）在配对时由 Server 下发，
+ * 落在 persistStore 中；入口地址则来自环境变量，默认与 SERVER_BASE_URL 一致
+ * —— 中继入口就是 Server 本身，没有必要让用户再配一遍。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearRelayCredential = exports.setRelayCredential = exports.getRelayCredential = exports.setRelayEnabled = exports.isRelayEnabled = exports.getTunnelUrl = exports.getRelayBaseUrl = exports.RELAY_CREDENTIAL_KEY = exports.RELAY_ENABLED_KEY = void 0;
+const index_js_1 = require("../../config/index.js");
+const persistStore_js_1 = require("../../stores/persistStore.js");
+/** persistStore 键：中继开关 */
+exports.RELAY_ENABLED_KEY = 'relay:enabled';
+/** persistStore 键：配对凭据 */
+exports.RELAY_CREDENTIAL_KEY = 'relay:credential';
+/**
+ * 中继入口地址（Server 地址），末尾不带斜杠。
+ * 允许用 RELAY_URL 单独覆盖，便于把中继指向与业务 API 不同的入口。
+ */
+function getRelayBaseUrl() {
+    const raw = (process.env.RELAY_URL || index_js_1.appConfig.serverBaseUrl || '').trim();
+    return raw.replace(/\/+$/, '');
+}
+exports.getRelayBaseUrl = getRelayBaseUrl;
+/** 隧道 WS 地址：http→ws、https→wss */
+function getTunnelUrl() {
+    const base = getRelayBaseUrl();
+    if (!base)
+        return '';
+    const wsBase = base.replace(/^http/i, (m) => (m === 'HTTP' ? 'WS' : 'ws'));
+    return `${wsBase}/relay/tunnel`;
+}
+exports.getTunnelUrl = getTunnelUrl;
+/** 用户是否已开启中继（安全默认：关闭） */
+function isRelayEnabled() {
+    return persistStore_js_1.persistStore.get(exports.RELAY_ENABLED_KEY, false) === true;
+}
+exports.isRelayEnabled = isRelayEnabled;
+/** 写入中继开关 */
+function setRelayEnabled(enabled) {
+    persistStore_js_1.persistStore.set(exports.RELAY_ENABLED_KEY, enabled === true);
+}
+exports.setRelayEnabled = setRelayEnabled;
+/** 读取配对凭据（未配对返回 null） */
+function getRelayCredential() {
+    const value = persistStore_js_1.persistStore.get(exports.RELAY_CREDENTIAL_KEY, null);
+    // userId 缺失的凭据一律视为无效（等同未配对，用户重新配对即可修复）：
+    // 宁可让功能不可用，也不能让属主校验失去依据。
+    if (!value || !value.gatewayId || !value.secret || !value.userId)
+        return null;
+    return value;
+}
+exports.getRelayCredential = getRelayCredential;
+/** 保存配对凭据 */
+function setRelayCredential(credential) {
+    persistStore_js_1.persistStore.set(exports.RELAY_CREDENTIAL_KEY, credential);
+}
+exports.setRelayCredential = setRelayCredential;
+/** 清除配对凭据（解绑/换账号） */
+function clearRelayCredential() {
+    persistStore_js_1.persistStore.delete(exports.RELAY_CREDENTIAL_KEY);
+}
+exports.clearRelayCredential = clearRelayCredential;

package/dist/services/session/Session.js

@@ -440,6 +440,25 @@ class Session {
     getMessageCount() {
         return this.messages.length;
     }
+    /**
+     * 取断线期间的消息变更（新增 / 修改 / 删除）。
+     *
+     * WebSocket 重连的退避最长 30s，这期间错过的会话流事件无法补发，
+     * 而重连后又没有任何信号告诉终端「你落后了」，各终端就会永久分歧。
+     * 终端报上自己的 seq 游标，这里只回变更部分。
+     *
+     * @param sinceSeq 终端已知的最大 seq，0 表示全量
+     */
+    getMessagesChangedSince(sinceSeq) {
+        const store = this.store;
+        return {
+            messages: store.findMessagesChangedSince(this.id, sinceSeq),
+            // 删除不留痕迹，光靠 seq 发现不了离线期间被删的消息，
+            // 因此一并回完整 id 列表让终端剪除多余项
+            messageIds: store.findMessageIdsBySessionId(this.id),
+            maxSeq: store.getMaxMessageSeq(),
+        };
+    }
     /**
      * Get messages by page (descending order)
      */
@@ -691,8 +710,6 @@ class Session {
         const settings = await dataService_js_1.settingsService.get(token);
         const streamDelay = this.getStreamDelay(settings.streamSpeed);
         this.currentMessageId = assistantMessageId;
-        const memoryManager = new MemoryManager_js_1.MemoryManager(this, this.abortController.signal, childAgent, res);
-        const historyMessages = await memoryManager.getHistoryMessagesAsync();
         // 同一用户可能同时在多个终端登录，而 SSE 只能回给发起请求的那个终端。
         // 这里预先取到 WebSocketService，把每个 SSE 事件同步给该用户的其他连接，
         // 从而让所有终端看到同一份会话流。子 Agent 的内部流不需要同步。
@@ -719,6 +736,25 @@ class Session {
                 logger.error('SSE mirror error:', error);
             }
         };
+        // 其他终端没有参与本次请求，需要补一条用户消息才能对齐会话。
+        // 必须在 message_start 之前同步：否则接收端会先插入助手占位，
+        // 导致助手消息排在用户消息前面。
+        //
+        // 同时带上助手占位标记：接收端据此在用户消息后面立即插入「思考中」
+        // 占位气泡，与发起端表现一致（占位文案由接收端按自身语言生成）。
+        if (!childAgent) {
+            mirrorToOtherClients({
+                type: 'user_message',
+                message: this.getUserMessage(content, userMessageId, attachments),
+                assistantPlaceholder: true,
+            });
+        }
+        // 必须在加载历史（可能触发上下文压缩）之前发出：
+        // context_compressing 是对助手消息的原地更新，接收端必须先有占位气泡。
+        // MemoryManager 会在压缩历史时发出 context_compressing，
+        // 把镜像函数传进去，使该事件也能同步到其他终端。
+        const memoryManager = new MemoryManager_js_1.MemoryManager(this, this.abortController.signal, childAgent, res, mirrorToOtherClients);
+        const historyMessages = await memoryManager.getHistoryMessagesAsync();
         // SSE 辅助方法：res 为 null 时跳过写入（本地执行模式），但仍同步给其他终端
         const sendSSE = (res, data) => {
             mirrorToOtherClients(data);
@@ -741,19 +777,6 @@ class Session {
                 clearInterval(heartbeatInterval);
             }
         }, 15000);
-        // 其他终端没有参与本次请求，需要补一条用户消息才能对齐会话。
-        // 必须在 message_start 之前同步：否则接收端会先插入助手占位，
-        // 导致助手消息排在用户消息前面。
-        //
-        // 同时带上助手占位标记：接收端据此在用户消息后面立即插入「思考中」
-        // 占位气泡，与发起端表现一致（占位文案由接收端按自身语言生成）。
-        if (!childAgent) {
-            mirrorToOtherClients({
-                type: 'user_message',
-                message: this.getUserMessage(content, userMessageId, attachments),
-                assistantPlaceholder: true,
-            });
-        }
         // Send message start event
         sendSSE(res, { type: 'message_start' });
         // Build messages for API call (保留 tool_call_id 等必要字段)