mn-ws-server 0.0.0-stage → 0.2.1

package/dist/config.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function configDir() {
+    return process.env.MN_WS_HOME || path.join(os.homedir(), '.mn-ws');
+}
+export function serverConfigFile() {
+    return path.join(configDir(), 'server.json');
+}
+export function readConfigFile() {
+    try {
+        const f = serverConfigFile();
+        if (!fs.existsSync(f))
+            return {};
+        return JSON.parse(fs.readFileSync(f, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** 真值判定：1 / true / yes / on（大小写不敏感）。 */
+export function isEnvTruthy(value) {
+    if (value === undefined || value === null)
+        return false;
+    const s = String(value).trim().toLowerCase();
+    return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+/**
+ * 布尔开关的严格解析。
+ *
+ * 空 → undefined（**没表态**，让上层按「跟随其他配置」处理）；
+ * 1/true/yes/on → true；0/false/no/off → false；其他值 → **直接抛错**。
+ *
+ * 为什么要严格：部署脚本里 `MN_WS_AUTH_ENABLED=1` 被当成「关闭」时，
+ * 服务照常启动、/health 照样绿，而整套按用户隔离的属主判据**静默不存在** ——
+ * CI 全绿、人以为开着。这类「配了等于没配」必须在解析层就炸掉。
+ */
+export function parseBoolFlag(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    if (v === true || v === false)
+        return v;
+    const s = String(v).trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(s))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(s))
+        return false;
+    throw new Error(`布尔开关取值无法识别：${JSON.stringify(v)}（认 1/true/yes/on 与 0/false/no/off）`);
+}
+/** 命令行解析：--key value / --key=value / --flag / 位置参数。 */
+export function parseArgs(argv) {
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--') {
+            positional.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            let key;
+            let value;
+            if (eq >= 0) {
+                key = a.slice(2, eq);
+                value = a.slice(eq + 1);
+            }
+            else {
+                key = a.slice(2);
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    value = next;
+                    i += 1;
+                }
+                else {
+                    value = true;
+                }
+            }
+            flags[camel(key)] = value;
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    return { flags, positional };
+}
+export function camel(s) {
+    return s.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function pick(...vals) {
+    for (const v of vals) {
+        if (v !== undefined && v !== null && v !== '')
+            return v;
+    }
+    return undefined;
+}
+/**
+ * 取字符串值，缺省是**空串**。
+ *
+ * 为什么不能直接 String(pick(...))：pick 全空时返回 undefined，
+ * 而 `String(undefined)` 是字符串 **"undefined"** —— 不是空串！
+ * 这里是**安全项**：token / jwtSecret 若是 "undefined"，
+ * `config.token && gate === config.token` 就等于「任何人都能用
+ * `X-Mn-Ws-Token: undefined` 通过门禁」。所以缺省必须是空串。
+ */
+export function str(v) {
+    return v === undefined || v === null ? '' : String(v);
+}
+/**
+ * 合并出最终配置。
+ *
+ * 环境变量前缀 MN_WS_（REMOTETYPE_ 那种大写下划线风格）。
+ */
+export function loadServerConfig(flags = {}) {
+    const file = readConfigFile();
+    const env = process.env;
+    return {
+        host: str(pick(flags.host, env.MN_WS_HOST, file.host, '0.0.0.0')),
+        port: Number(pick(flags.port, env.MN_WS_PORT, file.port, 7777)),
+        wsPath: str(pick(flags.wsPath, env.MN_WS_WS_PATH, file.wsPath, '/ws')),
+        token: str(pick(flags.token, env.MN_WS_TOKEN, file.token, '')),
+        issuer: str(pick(flags.issuer, env.MN_WS_ISSUER, file.issuer, 'http://47.110.80.47:8082')),
+        // server 半自己的 OIDC 身份（只用于「我是谁」，不发起授权码流程）
+        idpClientId: str(pick(flags.idpClientId, env.MN_WS_IDP_CLIENT_ID, file.idpClientId, 'mn-ws-server')),
+        // client 半的身份：真正发起授权码流程的是它（本机 CLI 在回环上收码 + PKCE）
+        loginClientId: str(pick(flags.loginClientId, env.MN_WS_LOGIN_CLIENT_ID, file.loginClientId, 'mn-ws-client')),
+        redirectUri: str(pick(flags.redirectUri, env.MN_WS_REDIRECT_URI, file.redirectUri, '')),
+        jwtSecret: str(pick(flags.jwtSecret, env.MN_WS_JWT_SECRET, file.jwtSecret, '')),
+        authEnabled: parseBoolFlag(pick(flags.authEnabled, env.MN_WS_AUTH_ENABLED, file.authEnabled, '')),
+        insecure: flags.insecure === true || env.MN_WS_INSECURE === '1',
+        requestTimeoutMs: Number(pick(flags.requestTimeout, env.MN_WS_REQUEST_TIMEOUT, file.requestTimeoutMs, 30_000)),
+        logLevel: String(pick(flags.logLevel, env.MN_WS_LOG_LEVEL, file.logLevel, 'info')),
+        dataDir: path.join(configDir(), 'data'),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * mn-ws-server 的公共面。
+ *
+ * ⚠️ client 半以 workspace 依赖引入这个包（`mn-ws-server`）：
+ * 两端说的是同一套帧协议，协议定义**只写一份**，改一处就是改两处。
+ * 所以这里导出的东西要当**跨端契约**看 —— 改形状之前先想清楚两边的兼容。
+ *
+ * 协议与应用目录分开导出（`./protocol` / `./apps`），是为了让 client 半
+ * 只取它需要的那部分，不必把 server 的运行时一起打进浏览器包。
+ */
+export * from './protocol.js';
+export * from './apps.js';
+export { Logger, LEVELS, type LogLevel } from './logger.js';
+export { Store, type AuditRecord } from './store.js';
+export { AuthHub, DEVICE_TOKEN_TTL_SEC, b64url, b64urlJson, fromB64url, type DeviceTokenPayload, type DeviceRecord, type PublicAuthConfig, } from './auth.js';
+export { createServer, type ServerOptions } from './server.js';
+export { loadServerConfig, parseArgs, parseBoolFlag, isEnvTruthy, configDir, serverConfigFile, type ServerConfig, } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EACL,OAAO,EACP,oBAAoB,EACpB,MAAM,EACN,UAAU,EACV,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * mn-ws-server 的公共面。
+ *
+ * ⚠️ client 半以 workspace 依赖引入这个包（`mn-ws-server`）：
+ * 两端说的是同一套帧协议，协议定义**只写一份**，改一处就是改两处。
+ * 所以这里导出的东西要当**跨端契约**看 —— 改形状之前先想清楚两边的兼容。
+ *
+ * 协议与应用目录分开导出（`./protocol` / `./apps`），是为了让 client 半
+ * 只取它需要的那部分，不必把 server 的运行时一起打进浏览器包。
+ */
+export * from './protocol.js';
+export * from './apps.js';
+export { Logger, LEVELS } from './logger.js';
+export { Store } from './store.js';
+export { AuthHub, DEVICE_TOKEN_TTL_SEC, b64url, b64urlJson, fromB64url, } from './auth.js';
+export { createServer } from './server.js';
+export { loadServerConfig, parseArgs, parseBoolFlag, isEnvTruthy, configDir, serverConfigFile, } from './config.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAoB,MAAM,YAAY,CAAC;AACrD,OAAO,EACL,OAAO,EACP,oBAAoB,EACpB,MAAM,EACN,UAAU,EACV,UAAU,GAIX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,WAAW,EACX,SAAS,EACT,gBAAgB,GAEjB,MAAM,aAAa,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 极简分级日志器。
+ *
+ * 与 mn-rt 的 client/lib/logger.js 同款：写文件 + 控制台，
+ * 不引第三方依赖（这个包要能被 npx 一把跑起来，依赖越少越好）。
+ */
+export declare const LEVELS: Record<string, number>;
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare class Logger {
+    level: number;
+    levelName: string;
+    dir: string | null;
+    name: string;
+    private stream;
+    constructor({ level, dir, name }?: {
+        level?: string;
+        dir?: string | null;
+        name?: string;
+    });
+    private _log;
+    debug(msg: string, extra?: unknown): void;
+    info(msg: string, extra?: unknown): void;
+    warn(msg: string, extra?: unknown): void;
+    error(msg: string, extra?: unknown): void;
+    close(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAgD,CAAC;AAE3F,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,qBAAa,MAAM;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,MAAM,CAAwB;gBAE1B,EAAE,KAAc,EAAE,GAAU,EAAE,IAAc,EAAE,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;IAkBvH,OAAO,CAAC,IAAI;IAYZ,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAEzC,KAAK,IAAI,IAAI;CAMd"}

package/dist/logger.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * 极简分级日志器。
+ *
+ * 与 mn-rt 的 client/lib/logger.js 同款：写文件 + 控制台，
+ * 不引第三方依赖（这个包要能被 npx 一把跑起来，依赖越少越好）。
+ */
+export const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+export class Logger {
+    level;
+    levelName;
+    dir;
+    name;
+    stream;
+    constructor({ level = 'info', dir = null, name = 'mn-ws' } = {}) {
+        this.level = LEVELS[level] ?? LEVELS.info ?? 20;
+        this.levelName = level;
+        this.dir = dir;
+        this.name = name;
+        this.stream = null;
+        if (dir) {
+            try {
+                fs.mkdirSync(dir, { recursive: true });
+                const file = path.join(dir, `${name}.log`);
+                this.stream = fs.createWriteStream(file, { flags: 'a' });
+            }
+            catch {
+                this.stream = null; // 写不了日志不是致命错误，降级成只打控制台
+            }
+        }
+    }
+    _log(level, msg, extra) {
+        if ((LEVELS[level] || 0) < this.level)
+            return;
+        const ts = new Date().toISOString();
+        const line = extra
+            ? `${ts} [${level.toUpperCase()}] ${msg} ${safeJson(extra)}`
+            : `${ts} [${level.toUpperCase()}] ${msg}`;
+        try {
+            process.stdout.write(`${line}\n`);
+        }
+        catch { /* ignore */ }
+        if (this.stream) {
+            try {
+                this.stream.write(`${line}\n`);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    debug(msg, extra) { this._log('debug', msg, extra); }
+    info(msg, extra) { this._log('info', msg, extra); }
+    warn(msg, extra) { this._log('warn', msg, extra); }
+    error(msg, extra) { this._log('error', msg, extra); }
+    close() {
+        if (this.stream) {
+            try {
+                this.stream.end();
+            }
+            catch { /* ignore */ }
+            this.stream = null;
+        }
+    }
+}
+function safeJson(obj) {
+    try {
+        return JSON.stringify(obj);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 通道协议：mn-ws server 半 ⇄ client 半 之间的 WebSocket 帧格式。
+ *
+ * 帧是 JSON 文本。**请求类帧带 id 用于配对** —— 一条 WS 连接上同时跑多个
+ * HTTP 请求，响应按 id 归位（见 §多路复用）。
+ *
+ * 这套协议刻意做成**零语义**的：帧里装的就是「一次 HTTP 请求」与
+ * 「一次 HTTP 响应」，server 半原样转发、client 半原样还原。
+ * 任何业务语义（nx 的 action、鉴权规则）都不进协议层。
+ *
+ * ⚠️ 这个模块被 **client 半以 workspace 依赖引入**（`mn-ws-server` 的公共面）。
+ * 改这里的形状 = 同时改两端，所以改动必须先想清楚两边的兼容。
+ */
+export declare const PROTOCOL_VERSION = 1;
+/** 帧类型 */
+export declare const FRAME: {
+    readonly WELCOME: "welcome";
+    readonly REGISTERED: "registered";
+    readonly REQUEST: "request";
+    readonly ABORT: "abort";
+    readonly PING: "ping";
+    readonly SHUTDOWN: "shutdown";
+    readonly ERROR: "error";
+    readonly REGISTER: "register";
+    readonly RESPONSE: "response";
+    readonly CHUNK: "chunk";
+    readonly PONG: "pong";
+};
+export type FrameType = (typeof FRAME)[keyof typeof FRAME];
+/**
+ * 不能跨代理转发的头（hop-by-hop）。
+ *
+ * 这些头描述的是**某一次连接**的属性，转发到下一跳会出错或无意义：
+ *   · Connection: keep-alive  —— 新连接会自己协商
+ *   · Transfer-Encoding: chunked —— body 已经被完整读成 buffer，重新算长度
+ *   · Upgrade / Proxy-*        —— 代理自己的协商，不该替下游决定
+ */
+export declare const HOP_BY_HOP_HEADERS: ReadonlySet<string>;
+/**
+ * 请求头里必须**剥离**的头：
+ *   · hop-by-hop —— 描述的是某一次连接，不该跨代理
+ *   · Origin     —— nx-kv 的跨站防护只放行本机来源，透传浏览器 Origin 会 403
+ *   · X-Mn-Ws-Token —— **mn-ws 自己的 L1 凭据**，属于桥接层内部事务，
+ *     泄给目标服务等于把门禁令牌交出去
+ */
+export declare const STRIP_REQUEST_HEADERS: ReadonlySet<string>;
+/**
+ * 响应头里不能转发的头。
+ *
+ * `content-length` 会在 client half 重新按实际 body 长度计算；
+ * `content-encoding` 由 client half 的 http 客户端处理，body 到手时已解码。
+ */
+export declare const STRIP_RESPONSE_HEADERS: ReadonlySet<string>;
+/** 请求体上限（字节）。与 nx-kv 的 24MB 对齐；base64 后约 32MB。 */
+export declare const MAX_BODY_BYTES: number;
+/** 单个 HTTP 请求在 server 半的最长等待时间（毫秒）。 */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** 协议层的头：键统一小写，值统一成数组（保住 set-cookie 这类多值头）。 */
+export type ProtocolHeaders = Record<string, string[]>;
+/** 规范化前的头（Node 的 IncomingHttpHeaders 形状：值可能是 string | string[] | undefined）。 */
+export type RawHeaders = Record<string, string | string[] | number | undefined>;
+/** 帧的通用形状。具体帧再各自收窄。 */
+export interface Frame {
+    type: string;
+    id?: string;
+    [k: string]: unknown;
+}
+/** 帧编码：把一个对象序列化成 WS 文本帧。 */
+export declare function encodeFrame(obj: unknown): string;
+/**
+ * 帧解码。返回 null 表示「这不是一帧合法的协议消息」——
+ * 调用方应当忽略并计数，而不是把解析异常抛给连接层。
+ */
+export declare function decodeFrame(raw: unknown): Frame | null;
+export declare function nextRequestId(prefix?: string): string;
+/** 头对象规范化：键统一小写，值统一成数组。 */
+export declare function normalizeHeaders(headers: RawHeaders | undefined | null): ProtocolHeaders;
+/** 取头的第一个值（大小写不敏感）。 */
+export declare function headerValue(headers: ProtocolHeaders | Record<string, unknown> | undefined | null, name: string): string | undefined;
+/** 剔除不该转发的请求头。 */
+export declare function stripRequestHeaders(headers: Record<string, string[] | string> | undefined | null): Record<string, string[] | string>;
+/** 剔除不该转发的响应头。 */
+export declare function stripResponseHeaders(headers: Record<string, string[] | string> | undefined | null): Record<string, string[] | string>;
+/**
+ * 把协议层的头（值统一是数组）压平成 Node http 能吃的形状。
+ *
+ * ## 为什么需要这一步
+ *
+ * 协议层把头的值统一存成数组，是为了**保住 set-cookie 这类多值头**
+ * （一个响应里可以有几十条 Set-Cookie，用 string 就只剩最后一条）。
+ * 但 Node 的 `http.request({headers})` 与 `res.writeHead(status, headers)`
+ * 要求**除 set-cookie 外全是字符串** —— 直接把数组塞进去会抛
+ * `options.headers.host property must be of type string. Received an instance of Array`。
+ *
+ * @param headers  规范化后的头
+ * @param arrayAllowed 允许保留数组的键（响应侧用 set-cookie）
+ */
+export declare function flattenHeaders(headers: Record<string, string[] | string> | undefined | null, arrayAllowed?: readonly string[]): Record<string, string | string[]>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,UAAU;AACV,eAAO,MAAM,KAAK;;;;;;;;;;;;CAcR,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,OAAO,KAAK,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAUjD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAIpD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAGrD,CAAC;AAEH,kDAAkD;AAClD,eAAO,MAAM,cAAc,QAAmB,CAAC;AAE/C,uCAAuC;AACvC,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAEvD,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;AAEhF,uBAAuB;AACvB,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,4BAA4B;AAC5B,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAkBtD;AASD,wBAAgB,aAAa,CAAC,MAAM,SAAM,GAAG,MAAM,CAIlD;AAED,2BAA2B;AAC3B,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,GAAG,eAAe,CASxF;AAED,uBAAuB;AACvB,wBAAgB,WAAW,CACzB,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,EACrE,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAOpB;AAED,kBAAkB;AAClB,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,GAC5D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,CAOnC;AAED,kBAAkB;AAClB,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,GAC5D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,CAOnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,EAC7D,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAgBnC"}

package/dist/protocol.js

@@ -0,0 +1,201 @@
+/**
+ * 通道协议：mn-ws server 半 ⇄ client 半 之间的 WebSocket 帧格式。
+ *
+ * 帧是 JSON 文本。**请求类帧带 id 用于配对** —— 一条 WS 连接上同时跑多个
+ * HTTP 请求，响应按 id 归位（见 §多路复用）。
+ *
+ * 这套协议刻意做成**零语义**的：帧里装的就是「一次 HTTP 请求」与
+ * 「一次 HTTP 响应」，server 半原样转发、client 半原样还原。
+ * 任何业务语义（nx 的 action、鉴权规则）都不进协议层。
+ *
+ * ⚠️ 这个模块被 **client 半以 workspace 依赖引入**（`mn-ws-server` 的公共面）。
+ * 改这里的形状 = 同时改两端，所以改动必须先想清楚两边的兼容。
+ */
+export const PROTOCOL_VERSION = 1;
+/** 帧类型 */
+export const FRAME = {
+    // server → client
+    WELCOME: 'welcome',
+    REGISTERED: 'registered',
+    REQUEST: 'request',
+    ABORT: 'abort',
+    PING: 'ping',
+    SHUTDOWN: 'shutdown',
+    ERROR: 'error',
+    // client → server
+    REGISTER: 'register',
+    RESPONSE: 'response',
+    CHUNK: 'chunk',
+    PONG: 'pong',
+};
+/**
+ * 不能跨代理转发的头（hop-by-hop）。
+ *
+ * 这些头描述的是**某一次连接**的属性，转发到下一跳会出错或无意义：
+ *   · Connection: keep-alive  —— 新连接会自己协商
+ *   · Transfer-Encoding: chunked —— body 已经被完整读成 buffer，重新算长度
+ *   · Upgrade / Proxy-*        —— 代理自己的协商，不该替下游决定
+ */
+export const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'proxy-connection',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+/**
+ * 请求头里必须**剥离**的头：
+ *   · hop-by-hop —— 描述的是某一次连接，不该跨代理
+ *   · Origin     —— nx-kv 的跨站防护只放行本机来源，透传浏览器 Origin 会 403
+ *   · X-Mn-Ws-Token —— **mn-ws 自己的 L1 凭据**，属于桥接层内部事务，
+ *     泄给目标服务等于把门禁令牌交出去
+ */
+export const STRIP_REQUEST_HEADERS = new Set([
+    ...HOP_BY_HOP_HEADERS,
+    'origin',
+    'x-mn-ws-token',
+]);
+/**
+ * 响应头里不能转发的头。
+ *
+ * `content-length` 会在 client half 重新按实际 body 长度计算；
+ * `content-encoding` 由 client half 的 http 客户端处理，body 到手时已解码。
+ */
+export const STRIP_RESPONSE_HEADERS = new Set([
+    ...HOP_BY_HOP_HEADERS,
+    'content-length',
+]);
+/** 请求体上限（字节）。与 nx-kv 的 24MB 对齐；base64 后约 32MB。 */
+export const MAX_BODY_BYTES = 24 * 1024 * 1024;
+/** 单个 HTTP 请求在 server 半的最长等待时间（毫秒）。 */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** 帧编码：把一个对象序列化成 WS 文本帧。 */
+export function encodeFrame(obj) {
+    return JSON.stringify(obj);
+}
+/**
+ * 帧解码。返回 null 表示「这不是一帧合法的协议消息」——
+ * 调用方应当忽略并计数，而不是把解析异常抛给连接层。
+ */
+export function decodeFrame(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    let text;
+    if (typeof raw === 'string')
+        text = raw;
+    else if (Buffer.isBuffer(raw))
+        text = raw.toString('utf8');
+    else if (Array.isArray(raw))
+        text = Buffer.concat(raw).toString('utf8');
+    else
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj))
+        return null;
+    const type = obj.type;
+    if (typeof type !== 'string')
+        return null;
+    return obj;
+}
+/**
+ * 生成一个跨连接唯一的请求 id。
+ *
+ * server 半的 pending 表是**全局**的（不按连接分表），所以 id 必须全局唯一：
+ * 只带连接内计数的话，两条连接上的 "1" 会撞车，响应会被配到错误的请求上。
+ */
+let _seq = 0;
+export function nextRequestId(prefix = 'r') {
+    _seq = (_seq + 1) % 0xffffff;
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `${prefix}-${Date.now().toString(36)}-${_seq.toString(36)}-${rand}`;
+}
+/** 头对象规范化：键统一小写，值统一成数组。 */
+export function normalizeHeaders(headers) {
+    const out = {};
+    if (!headers || typeof headers !== 'object')
+        return out;
+    for (const [k, v] of Object.entries(headers)) {
+        const key = String(k).toLowerCase();
+        if (v === undefined || v === null)
+            continue;
+        out[key] = Array.isArray(v) ? v.map((x) => String(x)) : [String(v)];
+    }
+    return out;
+}
+/** 取头的第一个值（大小写不敏感）。 */
+export function headerValue(headers, name) {
+    if (!headers)
+        return undefined;
+    const key = String(name).toLowerCase();
+    const v = headers[key];
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    if (Array.isArray(v))
+        return v.length ? String(v[0]) : undefined;
+    return String(v);
+}
+/** 剔除不该转发的请求头。 */
+export function stripRequestHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers || {})) {
+        if (STRIP_REQUEST_HEADERS.has(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/** 剔除不该转发的响应头。 */
+export function stripResponseHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers || {})) {
+        if (STRIP_RESPONSE_HEADERS.has(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * 把协议层的头（值统一是数组）压平成 Node http 能吃的形状。
+ *
+ * ## 为什么需要这一步
+ *
+ * 协议层把头的值统一存成数组，是为了**保住 set-cookie 这类多值头**
+ * （一个响应里可以有几十条 Set-Cookie，用 string 就只剩最后一条）。
+ * 但 Node 的 `http.request({headers})` 与 `res.writeHead(status, headers)`
+ * 要求**除 set-cookie 外全是字符串** —— 直接把数组塞进去会抛
+ * `options.headers.host property must be of type string. Received an instance of Array`。
+ *
+ * @param headers  规范化后的头
+ * @param arrayAllowed 允许保留数组的键（响应侧用 set-cookie）
+ */
+export function flattenHeaders(headers, arrayAllowed = []) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers || {})) {
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            if (arrayAllowed.includes(k)) {
+                if (v.length)
+                    out[k] = v.map((x) => String(x));
+                continue;
+            }
+            if (!v.length)
+                continue;
+            out[k] = String(v[0]);
+            continue;
+        }
+        out[k] = String(v);
+    }
+    return out;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}