@yunzai-ng/core 0.1.0

package/dist/server/index.js

@@ -0,0 +1,1123 @@
+/**
+ * 模块职责：共享 HTTP / WebSocket 服务器 —— 面板、插件路由、适配器 webhook 共用一个端口
+ * 依赖方向：依赖 fastify 与本目录的 auth/files/table；不认识任何插件，也不认识面板前端
+ * 生命周期：`createManagedServer()` 建好但不监听；`listen()` 由 `App.start()` 在插件
+ *          全部装完之后调用；`close()` 幂等，由 `App.own()` 登记
+ * 注意事项：四个不显而易见的决定 ——
+ *
+ *          **Fastify 上只注册 4 条 catch-all 路由**（`/` 与 `/*` 各两条），真正的分发走 table.ts 的
+ *          `PathTable` —— find-my-way 没有删除单条路由的 API，而「插件能装能卸能热重载」是核心不变量。
+ *
+ *          **鉴权放在 `onRequest` 钩子里**，不放在处理函数里。fastify 在 `handle-request` 开头就判
+ *          `reply.sent`，故在 `onRequest` 里回了响应，body 解析与路由处理都不会发生 —— 未鉴权的请求
+ *          不该有机会往本进程内存写 64MB。
+ *
+ *          **WebSocket 的拒绝也必须在 `onRequest` 里做。** `@fastify/websocket` 的 `onUpgrade` 会先建
+ *          响应对象再调 `fastify.routing()`，此时回响应得到的是一个真正的 401/404，对方看得到原因；
+ *          等进了 `wsHandler` 再关连接，对方只看到一次没有理由的断线。
+ *
+ *          **静态资源刻意不鉴权。** 浏览器请求文档时设不了请求头，要鉴权就只剩 Cookie 一条路，
+ *          那会把 auth.ts 刻意避开的 CSRF 面重新引进来。HTML/JS 本身不是机密，要保护的是 API。
+ */
+import { isAbsolute } from "node:path";
+import Fastify, {} from "fastify";
+import fastifyStatic from "@fastify/static";
+import fastifyWebsocket from "@fastify/websocket";
+import { createSeqFactory } from "../util/id.js";
+import { formatBytes } from "../util/duration.js";
+import { WS_PROTOCOL, checkAuth, checkForgeableBody, generateToken, isLocalHost } from "./auth.js";
+import { resolveStaticFile } from "./files.js";
+import { HTTP_METHODS, PathTable, isHttpMethod, joinPattern, splitSegments } from "./table.js";
+/** 单条路由未声明 `bodyLimit` 时的请求体上限 */
+const DEFAULT_BODY_LIMIT = 1024 * 1024;
+/**
+ * 任何路由都不得超过的请求体上限
+ *
+ * 同时作为 Fastify 实例级的 `bodyLimit`：实际的限流在本模块自有的解析器中按路由施加，
+ * 此处仅为最后一道兜底，防止某个路由将 `bodyLimit` 设为 `Infinity`。
+ */
+const MAX_BODY_LIMIT = 64 * 1024 * 1024;
+/** 静态挂载的通配参数名，`/webui/*rest` 里的 `rest` */
+const STATIC_REST = "rest";
+/** `ws` 的 `readyState` 里代表"已连通"的值 */
+const WS_OPEN = 1;
+/** `RouteResponse` 允许出现的键；出现其他键即表明该对象实为业务数据 */
+const RESPONSE_KEYS = new Set(["status", "headers", "body"]);
+/**
+ * 取错误的可读文本
+ *
+ * 内核没有统一的错误文案工具（pipeline/router.ts 也是就地内联的），这里同样自备一个，
+ * 免得为一行三元表达式在 util 里加一个模块。
+ * @param err 任意抛出物
+ * @returns 可读文本
+ */
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 去掉查询串与锚点，只留路径
+ * @param url `request.url`，形如 `/api/config?x=1`
+ * @returns 路径部分
+ */
+function pathOf(url) {
+    const cut = url.search(/[?#]/);
+    return cut < 0 ? url : url.slice(0, cut);
+}
+/**
+ * 取 TCP 对端地址
+ *
+ * 刻意使用 `request.socket.remoteAddress` 而非 `request.ip`：后者在 `trustProxy` 开启
+ * 时会变为 `X-Forwarded-For` 的值。鉴权的"是否本机"判断绝不能被一个请求头左右，
+ * 因此此处绕开 Fastify 的加工，直接向内核获取对端地址。
+ *
+ * 使用 `?.` 是必要的：WebSocket 升级经由 `fastify.routing()` 而非正常的请求流程，
+ * 注入式测试（`injectWS`）伪造的 raw request 上并不存在 `socket`。无法取得时返回空串，
+ * 于是 `isLoopbackAddress("")` 为 false —— 无法确定时按"非本机"处理，是安全的一侧。
+ * @param request Fastify 请求
+ * @returns 对端地址；取不到时空串
+ */
+function ipOf(request) {
+    return request.socket?.remoteAddress ?? "";
+}
+/**
+ * 取请求头的第一个值
+ * @param value 头值
+ * @returns 首个值；不存在时 undefined
+ */
+function firstHeader(value) {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * 从 `Content-Type` 里取出媒体类型本身
+ * @param header 头值
+ * @returns 已小写化的媒体类型；没有时空串
+ */
+function mediaTypeOf(header) {
+    return (header ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+}
+/**
+ * 判断是否是一个 WebSocket 升级请求
+ *
+ * 不能只看 `request.ws`：`fastify.addHook()` 立即生效，而 `fastify.register()` 要等到
+ * `ready()` 才启动插件，因此本服务器的 `onRequest` 钩子**排在 `@fastify/websocket`
+ * 自己那个钩子之前**，那时 `request.ws` 还没被赋值。所以以请求头为准，
+ * `request.ws` 只当快捷路径。
+ * @param request Fastify 请求
+ * @returns 是否为升级请求
+ */
+function isUpgradeRequest(request) {
+    if (request.ws === true)
+        return true;
+    const upgrade = firstHeader(request.headers.upgrade);
+    if (upgrade === undefined || upgrade.toLowerCase() !== "websocket")
+        return false;
+    return (firstHeader(request.headers.connection) ?? "").toLowerCase().includes("upgrade");
+}
+/**
+ * 把监听地址转成"能点开"的形式
+ *
+ * `0.0.0.0` 与 `::` 是通配监听地址，不是可访问地址。日志里印一条
+ * `http://0.0.0.0:2536` 等于给用户一个点不开的链接。
+ * @param host 配置里的监听地址
+ * @returns 可放进 URL 的主机名
+ */
+function displayHost(host) {
+    if (host === "" || host === "0.0.0.0")
+        return "127.0.0.1";
+    if (host === "::" || host === "::0")
+        return "[::1]";
+    return host.includes(":") ? `[${host}]` : host;
+}
+/**
+ * 造一个带状态码的错误
+ * @param status HTTP 状态码
+ * @param message 错误文案，会直接回给对方
+ * @returns 错误对象
+ */
+function httpError(status, message) {
+    const err = new Error(message);
+    err.statusCode = status;
+    return err;
+}
+/**
+ * 从错误里取状态码
+ *
+ * 只认 400–599：插件把 `statusCode` 写成 `0` 或 `200` 时，回一个"成功"的错误响应
+ * 远比回 500 更难排查。
+ * @param err 任意抛出物
+ * @returns 状态码；不合法时 500
+ */
+function statusOf(err) {
+    if (typeof err !== "object" || err === null)
+        return 500;
+    const code = err.statusCode;
+    if (typeof code !== "number" || !Number.isInteger(code))
+        return 500;
+    return code >= 400 && code < 600 ? code : 500;
+}
+/**
+ * 判断处理函数的返回值是否为一个 `RouteResponse` 信封
+ *
+ * `RouteHandler` 允许直接以 `return { ok: true }` 作为响应体，亦允许
+ * `return { status: 201, body: x }` 指定状态码，二者必须可以区分。判据是**键集合完全
+ * 落在 `status`/`headers`/`body` 之内**：业务对象只要多出一个字段便不会被误判。
+ * 确需返回一个恰好只含这三个键的业务对象时，外层包裹一层 `{ body: 该对象 }` 即可。
+ * @param value 处理函数的返回值
+ * @returns 是否为信封
+ */
+function isRouteResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (Array.isArray(value) || value instanceof Uint8Array)
+        return false;
+    const keys = Object.keys(value);
+    if (keys.length === 0)
+        return false;
+    if (!keys.every(key => RESPONSE_KEYS.has(key)))
+        return false;
+    const rec = value;
+    if (rec.status !== undefined && typeof rec.status !== "number")
+        return false;
+    if (rec.headers !== undefined && (typeof rec.headers !== "object" || rec.headers === null))
+        return false;
+    return true;
+}
+/**
+ * 把响应体转成 Fastify 认得的形态
+ *
+ * Fastify 只对 `Buffer.isBuffer()` 为真的值走二进制直发。一个普通 `Uint8Array`
+ * 会被当成对象 JSON 序列化成 `{"0":137,"1":80,…}`，而且状态码还是 200 ——
+ * 这种故障从现象追回类型问题极其费时，所以在这里就地转掉。
+ * @param body 处理函数给的响应体
+ * @returns 可交给 `reply.send()` 的值
+ */
+function toPayload(body) {
+    if (body instanceof Uint8Array && !Buffer.isBuffer(body)) {
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    }
+    return body;
+}
+/**
+ * 按处理函数的返回值回响应
+ * @param reply Fastify 响应
+ * @param result 处理函数的返回值
+ * @returns 同一个 `reply`，供处理函数 `return`
+ */
+function sendResult(reply, result) {
+    if (result === undefined)
+        return reply.code(204).send();
+    if (isRouteResponse(result)) {
+        const { status, headers, body } = result;
+        reply.code(status ?? (body === undefined ? 204 : 200));
+        if (headers !== undefined)
+            reply.headers(headers);
+        return body === undefined ? reply.send() : reply.send(toPayload(body));
+    }
+    return reply.send(toPayload(result));
+}
+/**
+ * 解析表单编码的请求体
+ *
+ * 用 `Object.create(null)` 而不是 `{}`：对字面量对象写 `out["__proto__"] = x` 会真的
+ * 改掉它的原型，一个表单字段就能污染下游所有属性查找。
+ * @param text 表单文本
+ * @returns 无原型的键值对
+ */
+function formToObject(text) {
+    const out = Object.create(null);
+    for (const [key, value] of new URLSearchParams(text))
+        out[key] = value;
+    return out;
+}
+/**
+ * 把 `ws` 给的各种数据形态统一成 Buffer
+ * @param data `ws` 的 message 回调第一个参数
+ * @returns 字节
+ */
+function toBytes(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (Array.isArray(data))
+        return Buffer.concat(data.filter((part) => Buffer.isBuffer(part)));
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    if (data instanceof Uint8Array)
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    return Buffer.from(String(data), "utf8");
+}
+/**
+ * 把关闭原因统一成字符串
+ * @param reason `ws` 的 close 回调第二个参数
+ * @returns 原因文本；没有时空串
+ */
+function reasonOf(reason) {
+    if (typeof reason === "string")
+        return reason;
+    if (Buffer.isBuffer(reason))
+        return reason.toString("utf8");
+    return "";
+}
+/**
+ * 将一条 `ws` 原生连接封装为 `WebSocketConnection`
+ * @param socket `ws` 原生连接
+ * @param id 连接编号
+ * @param ip 对端地址
+ * @param headers 握手请求头
+ * @param log 日志器
+ * @returns 交给插件的连接对象
+ */
+function wrapConnection(socket, id, ip, headers, log) {
+    /** 是否仍认为连接可用 */
+    let open = true;
+    const messageCbs = new Set();
+    const closeCbs = new Set();
+    const errorCbs = new Set();
+    /*
+     * 回调收进 Set 由单一监听分发，而不是每个插件各注册一次
+     *
+     * 于是 `onMessage()` 的 Disposer 只是从 Set 里删一项 —— 不需要 `off`（`RawSocket` 因而
+     * 不必声明它），也不会因一条连接上注册了十几个插件而触发 Node 的 MaxListeners 警告。
+     */
+    /**
+     * 把一个事件分发给一组回调
+     * @param set 回调集合
+     * @param args 回调实参
+     */
+    const fire = (set, ...args) => {
+        // 遍历副本：在回调里调用自身的 Disposer 是常见写法，直接遍历原 Set 会让迭代器行为取决于
+        // 删除时机。抛错只记日志不外传 —— 单个插件的缺陷不该中断连接，更不该沿 ws 的事件循环
+        // 变成 uncaught exception
+        for (const cb of [...set]) {
+            try {
+                cb(...args);
+            }
+            catch (err) {
+                log.error(`WebSocket ${id} 的回调抛错：${messageOf(err)}`);
+            }
+        }
+    };
+    socket.on("message", (data, isBinary) => {
+        const bytes = toBytes(data);
+        fire(messageCbs, isBinary ? bytes : bytes.toString("utf8"), isBinary);
+    });
+    socket.on("close", (code, reason) => {
+        open = false;
+        fire(closeCbs, typeof code === "number" ? code : 1006, reasonOf(reason));
+        // 连接已经结束，留着回调只会把插件闭包连带的对象一直吊在内存里
+        messageCbs.clear();
+        closeCbs.clear();
+        errorCbs.clear();
+    });
+    socket.on("error", (err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        // 没人关心时也要留一条痕迹：服务器是 `logger: false` 建的，fastify 自己不会记
+        if (errorCbs.size === 0)
+            log.debug(`WebSocket ${id} 出错：${error.message}`);
+        fire(errorCbs, error);
+    });
+    return {
+        id,
+        ip,
+        headers,
+        get open() {
+            return open && socket.readyState === WS_OPEN;
+        },
+        send(data) {
+            if (!open || socket.readyState !== WS_OPEN) {
+                // 静默丢弃会让"消息发不出去"变成一个查不到的现象，至少留条 debug
+                log.debug(`WebSocket ${id} 已不可用，丢弃一条待发消息`);
+                return;
+            }
+            socket.send(data);
+        },
+        close(code, reason) {
+            open = false;
+            socket.close(code, reason);
+        },
+        onMessage(cb) {
+            messageCbs.add(cb);
+            return () => {
+                messageCbs.delete(cb);
+            };
+        },
+        onClose(cb) {
+            closeCbs.add(cb);
+            return () => {
+                closeCbs.delete(cb);
+            };
+        },
+        onError(cb) {
+            errorCbs.add(cb);
+            return () => {
+                errorCbs.delete(cb);
+            };
+        }
+    };
+}
+/**
+ * 共享 HTTP / WebSocket 服务器
+ *
+ * 实现 `ServerSink`，因此 `ctx.route()` / `ctx.websocket()` / `ctx.static()` 最终都落到
+ * 这里。面板自己的 API 也只是"一个 scope 为 `/api` 的普通注册方"，没有任何特权 ——
+ * 这是"一切皆可为插件"在服务器层的体现。
+ */
+export class ManagedServer {
+    /** Fastify 实例 */
+    #fastify;
+    /** 内核配置句柄 */
+    #config;
+    /** 日志器 */
+    #logger;
+    /** 方法 → 该方法下的路径表 */
+    #routes = new Map();
+    /** WebSocket 端点表 */
+    #ws = new PathTable();
+    /** 静态挂载表 */
+    #static = new PathTable();
+    /** 请求 → 查表结果；使用 WeakMap 以免请求对象被本表长期持有 */
+    #contexts = new WeakMap();
+    /** 请求 → 原始请求体，只在路由声明了 `rawBody` 时写入 */
+    #rawBodies = new WeakMap();
+    /** 当前保持的连接，面板需展示数量，`close()` 需清空 */
+    #connections = new Set();
+    /** 连接编号发号器 */
+    #nextConnId = createSeqFactory("ws-");
+    /** Fastify 内置的 JSON 解析器，带原型污染防护 */
+    #jsonParser;
+    /** 是否已在监听 */
+    #listening = false;
+    /** 是否已关闭 */
+    #closed = false;
+    /** 实际监听到的端口，`listen()` 之后才有值 */
+    #port = 0;
+    /**
+     * 建好实例但不监听
+     *
+     * **不要直接 `new`**，用 `createManagedServer()`：路由必须等到两个 Fastify 插件启动
+     * 完成之后才能注册（原因见 `#boot()`），而那是一个异步过程，构造函数里做不到。
+     * @param opts 构造参数
+     */
+    constructor(opts) {
+        this.#config = opts.config;
+        this.#logger = opts.logger;
+        this.#fastify = Fastify({
+            // 日志走内核自己的 logger；开着 Fastify 的会出现两套格式两份文件
+            logger: false,
+            // 必须为 false：auth.ts 第 4 条的"是否本机"判断依赖真实 TCP 对端地址
+            trustProxy: false,
+            // 本服务器已显式注册 HEAD，若再由 Fastify 自动生成一条将冲突为 duplicate route
+            exposeHeadRoutes: false,
+            bodyLimit: MAX_BODY_LIMIT
+        });
+        this.#jsonParser = this.#fastify.getDefaultJsonParser("remove", "remove");
+        this.#registerPlugins();
+    }
+    /**
+     * 建一个已就绪的服务器
+     * @param opts 构造参数
+     * @returns 已 `ready()` 的服务器
+     */
+    static async create(opts) {
+        const server = new ManagedServer(opts);
+        await server.#boot();
+        return server;
+    }
+    /**
+     * 启动两个 Fastify 插件，然后装上钩子与那 4 条 catch-all 路由
+     *
+     * **`await fastify.after()` 这一步不能省。** `fastify.route()` 会**同步**触发
+     * `onRoute` 钩子（见 fastify 的 `lib/route.js` 里 `addNewRoute` 直接
+     * `for (const hook of this[kHooks].onRoute)`），而 `@fastify/websocket` 的 `onRoute`
+     * 钩子是在其自身启动时方才装上的。若先注册路由，该钩子将完全观察不到本服务器的路由，
+     * 于是路由的 handler 不会被包上"升级分支" —— 表现为所有 WebSocket 握手均得到一个
+     * 普通 HTTP 响应，且完全不报错。
+     * @returns 完成时 resolve
+     */
+    async #boot() {
+        await this.#fastify.after();
+        this.#installRoutes();
+        await this.#fastify.ready();
+    }
+    /**
+     * 注册 `@fastify/static` 与 `@fastify/websocket`
+     *
+     * 两个 `register()` 都是延迟的，真正启动要等 `after()` / `ready()`。
+     */
+    #registerPlugins() {
+        const fastify = this.#fastify;
+        // `serve: false` 让它一条路由都不注册，只装饰出 `reply.sendFile()`。
+        // 它默认会占用 `/*`，而 `/*` 正是本服务器自己的总入口，见 files.ts 文件头
+        fastify.register(fastifyStatic, { serve: false, decorateReply: true });
+        fastify.register(fastifyWebsocket, {
+            options: {
+                // 浏览器将令牌置于子协议中（见 auth.ts 第 2 条）。返回 `WS_PROTOCOL` 即向
+                // 浏览器表明"该子协议被接受"，否则 `new WebSocket(url, [...])` 会立即失败
+                handleProtocols: (protocols) => protocols.has(WS_PROTOCOL) ? WS_PROTOCOL : false
+            },
+            // 服务器以 `logger: false` 创建，插件内部的 `fastify.log.error` 会被丢弃，
+            // 此处将其接回内核日志
+            errorHandler: (error, socket) => {
+                this.#logger.error(`WebSocket 连接出错：${error.message}`);
+                socket.terminate();
+            }
+        });
+    }
+    /**
+     * 装上请求体解析器、钩子、错误处理与那 4 条 catch-all 路由
+     *
+     * 必须在两个插件启动之后调用，见 `#boot()`。
+     */
+    #installRoutes() {
+        const fastify = this.#fastify;
+        fastify.removeAllContentTypeParsers();
+        fastify.addContentTypeParser("*", (request, payload, done) => {
+            this.#parseBody(request, payload, done);
+        });
+        fastify.addHook("onRequest", async (request, reply) => this.#onRequest(request, reply));
+        // `reply.sendFile()` 遇到 ENOENT 会走 `callNotFound()`，加上这个处理器是为了让
+        // 404 也是 `{ error: string }` —— 面板前端只需要认一种错误形状
+        fastify.setNotFoundHandler((request, reply) => this.#reject(reply, 404, `路由 ${pathOf(request.url)} 不存在`));
+        fastify.setErrorHandler((err, request, reply) => {
+            const status = statusOf(err);
+            // 4xx 源于请求方，记录日志只会被扫描器填满；5xx 源于本服务器，必须记录
+            if (status >= 500) {
+                this.#logger.error(`处理 ${request.method} ${pathOf(request.url)} 出错：${messageOf(err)}`);
+            }
+            return this.#reject(reply, status, messageOf(err));
+        });
+        const handler = async (request, reply) => this.#dispatch(request, reply);
+        const wsHandler = (socket, request) => {
+            this.#openConnection(socket, request);
+        };
+        // GET 之外的方法不能带 wsHandler：`@fastify/websocket` 的 onRoute 钩子会抛
+        // `websocket handler can only be declared in GET method`
+        const others = ["POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+        for (const url of ["/", "/*"]) {
+            fastify.route({ method: "GET", url, handler, wsHandler });
+            fastify.route({ method: others, url, handler });
+        }
+    }
+    /**
+     * 当前服务器状态
+     *
+     * 刻意做成 getter 而不是构造时算好的常量：`port: 0` 时内核会拿到一个随机端口，
+     * 只有 `listen()` 之后才知道是多少，而测试与面板都要显示真实端口。
+     * @returns 服务器信息
+     */
+    get info() {
+        const cfg = this.#config.get().server;
+        const port = this.#port === 0 ? cfg.port : this.#port;
+        return {
+            enabled: this.#listening,
+            host: cfg.host,
+            port,
+            publicUrl: cfg.publicUrl ?? `http://${displayHost(cfg.host)}:${port}`
+        };
+    }
+    /** 当前保持连接的 WebSocket 数量 */
+    get connections() {
+        return this.#connections.size;
+    }
+    /**
+     * 原生 Fastify 实例
+     *
+     * 保留给两种场合：测试中的 `inject()` / `injectWS()`，以及插件确实需要 Fastify 原生
+     * 能力（multipart、SSE、自定义序列化）之时。**直接在其上注册的路由无法摘除**，
+     * 插件热重载后会残留为失效路由，因此除已确认可接受该后果外，应使用 `route()`。
+     * @returns Fastify 实例
+     */
+    get raw() {
+        return this.#fastify;
+    }
+    /**
+     * 非本机监听时确保有访问令牌
+     *
+     * 只监听本机就不生成 —— 单机用户不该为了打开面板先去配置文件里抄一串随机字符。
+     * 一旦监听地址对外，没有令牌等于把配置写权限公开，所以这里**自动生成并落盘**，
+     * 而不是只打一句警告了事。
+     * @returns 完成时 resolve
+     */
+    async ensureToken() {
+        const cfg = this.#config.get().server;
+        if (cfg.token !== undefined && cfg.token !== "")
+            return;
+        if (isLocalHost(cfg.host))
+            return;
+        const token = generateToken();
+        await this.#config.patch({ server: { token } }, "api");
+        // 明文输出一次是必要的：使用者此时即需以其登录面板，且它本已写入配置文件
+        this.#logger.warn(`面板监听于 ${cfg.host}，已自动生成访问令牌：${token}`);
+        this.#logger.warn("该令牌已写入配置项 server.token，可随时自行修改");
+    }
+    /**
+     * 开始监听
+     *
+     * 由 `App.start()` 在插件全部装完之后调用：那时路由才齐，也不会出现"面板半截可用"
+     * 的窗口期。
+     * @returns 完成时 resolve
+     * @throws 服务器已关闭、或端口被占用时
+     */
+    async listen() {
+        if (this.#closed)
+            throw new Error("服务器已关闭，不能再监听");
+        if (this.#listening)
+            return;
+        const cfg = this.#config.get().server;
+        await this.#fastify.listen({ host: cfg.host, port: cfg.port });
+        const addr = this.#fastify.server.address();
+        this.#port = typeof addr === "object" && addr !== null ? addr.port : cfg.port;
+        this.#listening = true;
+        this.#logger.info(`面板与插件路由已就绪：${this.info.publicUrl}`);
+    }
+    /**
+     * 关闭服务器
+     *
+     * 幂等。清表置于 `finally` 中：`fastify.close()` 抛错（例如某个 `preClose` 钩子出现问题）
+     * 亦不应残留大量指向已卸载插件闭包的注册项。
+     * @returns 完成时 resolve
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        try {
+            await this.#fastify.close();
+        }
+        finally {
+            for (const table of this.#routes.values())
+                table.clear();
+            this.#ws.clear();
+            this.#static.clear();
+            this.#connections.clear();
+            this.#listening = false;
+        }
+    }
+    /**
+     * 注册一条 HTTP 路由
+     * @param scope URL 前缀，通常是 `/plugin/<插件名>`
+     * @param method 请求方法，大小写不敏感
+     * @param path 相对 scope 的路径，可含 `:id` 与末尾的 `*rest`
+     * @param handler 处理函数
+     * @param opts 路由选项；`auth` 缺省为 true
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、方法不受支持、或同一模式重复注册时
+     */
+    route(scope, method, path, handler, opts = {}) {
+        this.#assertOpen();
+        const key = method.toUpperCase();
+        if (!isHttpMethod(key))
+            throw new Error(`不支持的请求方法 ${method}`);
+        const entry = {
+            scope,
+            handler,
+            // 默认要鉴权：插件作者忘了写选项时，安全的那一侧才该是默认值
+            auth: opts.auth !== false,
+            limit: this.#clampLimit(opts.bodyLimit),
+            rawBody: opts.rawBody === true
+        };
+        return this.#tableOf(key).add(joinPattern(scope, path), entry);
+    }
+    /**
+     * 注册一个 WebSocket 端点
+     *
+     * 不给 `verify` 时沿用面板令牌校验（与 `route()` 的 `auth` 默认为 true 对齐）。
+     * 适配器的反向连接端点要让平台连进来，就自己给一个 `verify` 做签名校验 ——
+     * 给了就完全接管，不再叠加令牌校验。
+     * @param scope URL 前缀
+     * @param path 相对 scope 的路径
+     * @param handler 连接建立后的处理函数
+     * @param opts 端点选项
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、或同一模式重复注册时
+     */
+    websocket(scope, path, handler, opts = {}) {
+        this.#assertOpen();
+        return this.#ws.add(joinPattern(scope, path), { scope, handler, verify: opts.verify });
+    }
+    /**
+     * 挂一个静态目录
+     * @param scope URL 前缀
+     * @param urlPath 相对 scope 的 URL 路径，`""` 或 `"/"` 表示挂在 scope 根上
+     * @param dir 本地目录绝对路径
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、`dir` 不是绝对路径、或同一模式重复注册时
+     */
+    static(scope, urlPath, dir) {
+        return this.#mount(scope, urlPath, dir, false);
+    }
+    /**
+     * 挂载面板：把一个单页应用目录挂到站点根路径
+     *
+     * 内置面板与接管它的插件都走这里，因此"谁在提供面板"只有一个判定依据
+     * （`claimant("/")`）。第二个调用方会在路径表里撞上重复模式而抛错，
+     * 这正是期望行为：静默覆盖会让面板显示的内容无法判定。
+     * @param owner 归属标识，如 `core` 或 `plugin:webui-next`
+     * @param dir 单页应用产物目录（绝对路径）
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、`dir` 不是绝对路径、或根路径已被占用时
+     */
+    panel(owner, dir) {
+        return this.#mount("/", "", dir, true, owner);
+    }
+    /**
+     * 导出全部 HTTP 路由，面板"路由一览"用
+     * @returns 路由摘要数组
+     */
+    listRoutes() {
+        const out = [];
+        for (const [method, table] of this.#routes) {
+            for (const item of table.entries()) {
+                out.push({ method, pattern: item.pattern, scope: item.value.scope, auth: item.value.auth });
+            }
+        }
+        return out;
+    }
+    /**
+     * 导出全部 WebSocket 端点
+     * @returns 端点摘要数组
+     */
+    listWebsockets() {
+        return this.#ws.entries().map(item => ({ pattern: item.pattern, scope: item.value.scope }));
+    }
+    /**
+     * 导出全部静态挂载
+     * @returns 挂载摘要数组
+     */
+    listStatic() {
+        return this.#static.entries().map(item => ({
+            pattern: item.pattern,
+            dir: item.value.dir,
+            spa: item.value.spa
+        }));
+    }
+    /**
+     * 查询某路径当前由谁提供
+     *
+     * 先查静态挂载再查 GET 路由：内核用它判断根路径是否已被插件接管，而接管
+     * 面板既可以挂一个单页目录，也可以注册一条返回 HTML 的路由，两种都要认。
+     * @param path URL 路径
+     * @returns 提供方的注册前缀；无人提供时 undefined
+     */
+    claimant(path) {
+        const parts = splitSegments(path);
+        const mount = this.#static.find(parts);
+        if (mount !== undefined)
+            return mount.value.scope;
+        return this.#routes.get("GET")?.find(parts)?.value.scope;
+    }
+    /**
+     * 静态挂载的公共实现
+     *
+     * 模式写成 `<urlPath>/*rest`：通配段"连什么都不剩也匹配"（见 table.ts 的
+     * `matchSegments`），所以 `/webui/*rest` 同时命中 `/webui` 与 `/webui/a/b.js`，
+     * 不必再额外注册一条裸路径。
+     * @param scope URL 前缀
+     * @param urlPath 相对 scope 的 URL 路径
+     * @param dir 本地目录绝对路径
+     * @param spa 是否单页回退
+     * @param owner 归属标识，缺省与 scope 相同；仅面板挂载需要与 scope 不同的值
+     * @returns 注销句柄
+     * @throws 服务器已关闭或 `dir` 不是绝对路径时
+     */
+    #mount(scope, urlPath, dir, spa, owner = scope) {
+        this.#assertOpen();
+        if (!isAbsolute(dir)) {
+            // 相对路径会随进程工作目录变化，而工作目录取决于用户是怎么启动的
+            throw new Error(`静态目录必须是绝对路径，收到 ${dir}`);
+        }
+        return this.#static.add(joinPattern(scope, `${urlPath}/*${STATIC_REST}`), { dir, spa, scope: owner });
+    }
+    /**
+     * 取某方法的路径表，没有就建
+     * @param method 请求方法
+     * @returns 路径表
+     */
+    #tableOf(method) {
+        let table = this.#routes.get(method);
+        if (table === undefined) {
+            table = new PathTable();
+            this.#routes.set(method, table);
+        }
+        return table;
+    }
+    /**
+     * 把路由声明的请求体上限收进合法范围
+     * @param limit 路由声明的上限
+     * @returns 实际生效的上限
+     */
+    #clampLimit(limit) {
+        if (limit === undefined || !Number.isFinite(limit) || limit <= 0)
+            return DEFAULT_BODY_LIMIT;
+        if (limit > MAX_BODY_LIMIT) {
+            this.#logger.warn(`路由声明的 bodyLimit ${formatBytes(limit)} 超过服务器上限，按 ${formatBytes(MAX_BODY_LIMIT)} 处理`);
+            return MAX_BODY_LIMIT;
+        }
+        return limit;
+    }
+    /**
+     * 拒绝在已关闭的服务器上注册
+     * @throws 已关闭时
+     */
+    #assertOpen() {
+        if (this.#closed)
+            throw new Error("服务器已关闭，不能再注册路由");
+    }
+    /**
+     * 取当前配置里的访问令牌
+     * @returns 令牌；未设置时 undefined
+     */
+    #token() {
+        const token = this.#config.get().server.token;
+        return token === "" ? undefined : token;
+    }
+    /**
+     * 回一个统一形状的错误响应
+     * @param reply Fastify 响应
+     * @param status 状态码
+     * @param message 错误文案
+     * @param extra 额外响应头
+     * @returns 同一个 `reply`
+     */
+    #reject(reply, status, message, extra) {
+        if (extra !== undefined)
+            reply.headers(extra);
+        return reply.code(status).send({ error: message });
+    }
+    /**
+     * 拒绝一次升级请求
+     *
+     * 额外附带 `Connection: close`：升级被拒之后该条 TCP 连接已无其他用途，而
+     * `@fastify/websocket` 的 `onResponse` 钩子仅在 `request.ws` 为真时才去 destroy
+     * socket —— 本服务器的钩子执行于其之前，该标记此时尚未被设置。
+     * @param reply Fastify 响应
+     * @param status 状态码
+     * @param message 错误文案
+     * @returns 同一个 `reply`
+     */
+    #rejectUpgrade(reply, status, message) {
+        return this.#reject(reply, status, message, { connection: "close" });
+    }
+    /**
+     * 唯一的请求入口钩子：查表 → 鉴权 → 缓存上下文
+     *
+     * 返回 `undefined` 表示放行，返回 `reply` 表示"已经回过响应了，别再往下走"。后者
+     * 之所以真的能拦住后续阶段，是因为 fastify 的 `lib/handle-request.js` 第一行就是
+     * `if (reply.sent === true) return`，body 解析与路由处理都在它之后。
+     * @param request Fastify 请求
+     * @param reply Fastify 响应
+     * @returns 已回响应时是 `reply`，放行时是 `undefined`
+     */
+    async #onRequest(request, reply) {
+        const raw = request.method.toUpperCase();
+        const path = pathOf(request.url);
+        const parts = splitSegments(path);
+        if (isUpgradeRequest(request))
+            return this.#handleUpgrade(request, reply, path, parts);
+        if (!isHttpMethod(raw))
+            return this.#reject(reply, 405, `不支持的请求方法 ${raw}`);
+        const method = raw;
+        // HEAD 未单独注册时回落到 GET：Node 的 ServerResponse 对 HEAD 会自动丢弃响应体，
+        // 因此直接执行 GET 的处理函数是安全的，同时免去每个插件重复注册两次
+        const route = method === "HEAD"
+            ? (this.#routes.get("HEAD")?.find(parts) ?? this.#routes.get("GET")?.find(parts))
+            : this.#routes.get(method)?.find(parts);
+        if (route !== undefined) {
+            const entry = route.value;
+            if (entry.auth) {
+                const authReq = { ip: ipOf(request), method, headers: request.headers };
+                const failure = checkAuth(this.#token(), authReq) ?? checkForgeableBody(authReq);
+                if (failure !== undefined)
+                    return this.#reject(reply, failure.status, failure.message);
+            }
+            // 声明了长度就先按声明拒掉，别等把 64MB 收完再说 413
+            const declared = Number(firstHeader(request.headers["content-length"]) ?? "0");
+            if (Number.isFinite(declared) && declared > entry.limit) {
+                return this.#reject(reply, 413, `请求体 ${formatBytes(declared)} 超过该路由的上限 ${formatBytes(entry.limit)}`);
+            }
+            this.#contexts.set(request, {
+                method,
+                path,
+                parts,
+                route,
+                mount: undefined,
+                ws: undefined,
+                limit: entry.limit,
+                rawBody: entry.rawBody
+            });
+            return undefined;
+        }
+        if (method === "GET" || method === "HEAD") {
+            const mount = this.#static.find(parts);
+            if (mount !== undefined) {
+                // 静态资源刻意不鉴权，理由见文件头第 4 条
+                this.#contexts.set(request, {
+                    method,
+                    path,
+                    parts,
+                    route: undefined,
+                    mount,
+                    ws: undefined,
+                    limit: DEFAULT_BODY_LIMIT,
+                    rawBody: false
+                });
+                return undefined;
+            }
+        }
+        const allow = this.#allowFor(parts);
+        // 不存在任何方法 → 该路径本身不存在，应为 404 而非 405
+        if (allow.length === 0)
+            return this.#reject(reply, 404, `路由 ${path} 不存在`);
+        const header = allow.join(", ");
+        if (method === "OPTIONS") {
+            reply.header("allow", header);
+            return reply.code(204).send();
+        }
+        return this.#reject(reply, 405, `${path} 不支持 ${method}`, { allow: header });
+    }
+    /**
+     * 算出某路径支持哪些方法，用于 `Allow` 响应头
+     * @param parts 已解码的路径段
+     * @returns 方法数组；路径不存在时为空数组
+     */
+    #allowFor(parts) {
+        const out = [];
+        for (const method of HTTP_METHODS) {
+            if (this.#routes.get(method)?.find(parts) !== undefined)
+                out.push(method);
+        }
+        // 这两条是服务器代劳的，注册表里查不到但确实支持
+        if (out.includes("GET") && !out.includes("HEAD"))
+            out.push("HEAD");
+        if (out.length > 0 && !out.includes("OPTIONS"))
+            out.push("OPTIONS");
+        return out;
+    }
+    /**
+     * 处理一次 WebSocket 升级请求
+     *
+     * 全部拒绝都在这里做完，理由见文件头第 3 条：此刻回的是真正的 HTTP 响应，对方能
+     * 从状态码和响应体里看到原因；进了 `wsHandler` 之后就只剩"关连接"这一种表达方式。
+     * @param request Fastify 请求
+     * @param reply Fastify 响应
+     * @param path 请求路径
+     * @param parts 已解码的路径段
+     * @returns 已拒绝时是 `reply`，放行时是 `undefined`
+     */
+    async #handleUpgrade(request, reply, path, parts) {
+        const hit = this.#ws.find(parts);
+        if (hit === undefined)
+            return this.#rejectUpgrade(reply, 404, `WebSocket 端点 ${path} 不存在`);
+        const ctx = {
+            method: "GET",
+            path,
+            parts,
+            route: undefined,
+            mount: undefined,
+            ws: hit,
+            limit: 0,
+            rawBody: false
+        };
+        const verify = hit.value.verify;
+        if (verify === undefined) {
+            const failure = checkAuth(this.#token(), { ip: ipOf(request), method: "GET", headers: request.headers });
+            if (failure !== undefined)
+                return this.#rejectUpgrade(reply, failure.status, failure.message);
+        }
+        else {
+            let ok = false;
+            try {
+                ok = await verify(this.#toRequest(request, ctx, hit.params));
+            }
+            catch (err) {
+                // verify 抛出异常等同于校验未通过，但须记录日志：否则 verify 中的一处拼写错误将
+                // 表现为"对端无法连接，而服务端未给出任何信息"
+                this.#logger.error(`WebSocket ${hit.pattern} 的 verify 抛错：${messageOf(err)}`);
+            }
+            if (!ok)
+                return this.#rejectUpgrade(reply, 401, `WebSocket ${path} 校验未通过`);
+        }
+        this.#contexts.set(request, ctx);
+        return undefined;
+    }
+    /**
+     * 把 Fastify 请求转成插件看到的 `RouteRequest`
+     *
+     * 插件拿到的是一个平的、只读的普通对象，不是 Fastify 请求：一方面插件不该依赖
+     * Fastify 的 API（将来换 HTTP 实现时才不必改插件），另一方面这样也堵住了插件从
+     * `request` 上摸到 `raw.socket` 去做越权操作的路。
+     * @param request Fastify 请求
+     * @param ctx 本次请求的查表结果
+     * @param params 路径参数
+     * @returns 只读请求对象
+     */
+    #toRequest(request, ctx, params) {
+        return {
+            method: ctx.method,
+            path: ctx.path,
+            params,
+            query: request.query,
+            headers: request.headers,
+            body: request.body,
+            rawBody: this.#rawBodies.get(request),
+            ip: ipOf(request)
+        };
+    }
+    /**
+     * 唯一的请求体解析器
+     *
+     * 只注册一个 `"*"` catch-all 而不是按类型注册若干个，原因和路由一样：限流上限是
+     * **按路由**来的，只有拿到本次请求的上下文才知道该按多少截断，而 Fastify 的按类型
+     * 解析器拿不到"这条请求命中了哪个路由"。
+     * @param request Fastify 请求
+     * @param payload 原始请求流
+     * @param done 解析完成回调
+     */
+    #parseBody(request, payload, done) {
+        const ctx = this.#contexts.get(request);
+        const limit = ctx?.limit ?? DEFAULT_BODY_LIMIT;
+        const chunks = [];
+        let size = 0;
+        let settled = false;
+        /**
+         * 只允许回调一次
+         * @param err 错误
+         * @param body 解析结果
+         */
+        const finish = (err, body) => {
+            if (settled)
+                return;
+            settled = true;
+            done(err, body);
+        };
+        payload.on("data", (chunk) => {
+            if (settled)
+                return;
+            size += chunk.length;
+            if (size > limit) {
+                finish(httpError(413, `请求体超过该路由的上限 ${formatBytes(limit)}`));
+                // 若不 resume，该连接会持续等待本端读取，直至对端超时
+                payload.resume();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        payload.on("aborted", () => {
+            finish(httpError(400, "请求体尚未传完连接就断了"));
+        });
+        payload.on("error", (err) => {
+            finish(err);
+        });
+        payload.on("end", () => {
+            if (settled)
+                return;
+            const raw = Buffer.concat(chunks);
+            // 仅声明了 rawBody 的路由才保留原始字节：缺省保留会使每个请求额外驻留一份副本
+            if (ctx?.rawBody === true)
+                this.#rawBodies.set(request, raw);
+            if (raw.length === 0) {
+                finish(null, undefined);
+                return;
+            }
+            const type = mediaTypeOf(firstHeader(request.headers["content-type"]));
+            if (type === "application/json" || type.endsWith("+json")) {
+                this.#jsonParser(request, raw.toString("utf8"), finish);
+                return;
+            }
+            if (type === "") {
+                // 部分设备端 SDK 完全不发送 content-type。先按 JSON 尝试解析，失败则将原始字节
+                // 交由路由自行处理 —— 若仅返回一个不含说明的 400，对端无从判断问题所在
+                this.#jsonParser(request, raw.toString("utf8"), (err, body) => {
+                    finish(null, err === null ? body : raw);
+                });
+                return;
+            }
+            if (type === "application/x-www-form-urlencoded") {
+                finish(null, formToObject(raw.toString("utf8")));
+                return;
+            }
+            if (type.startsWith("text/") || type === "application/xml" || type.endsWith("+xml")) {
+                finish(null, raw.toString("utf8"));
+                return;
+            }
+            // 其余（含 multipart）原样给出去，需要的插件自己解
+            finish(null, raw);
+        });
+    }
+    /**
+     * 真正分发一次请求
+     *
+     * 走到这里说明 `onRequest` 已经放行，所以上下文一定在；查不到只可能是有人绕开了钩子
+     * （比如直接往 `raw` 上加了路由），那是 500 而不是 404。
+     * @param request Fastify 请求
+     * @param reply Fastify 响应
+     * @returns 同一个 `reply`
+     */
+    async #dispatch(request, reply) {
+        const ctx = this.#contexts.get(request);
+        if (ctx === undefined)
+            return this.#reject(reply, 500, "请求上下文丢失：这条路由不是通过 route() 注册的");
+        if (ctx.route !== undefined) {
+            const result = await ctx.route.value.handler(this.#toRequest(request, ctx, ctx.route.params));
+            return sendResult(reply, result);
+        }
+        if (ctx.mount !== undefined) {
+            const rest = ctx.mount.params[STATIC_REST] ?? "";
+            const rel = await resolveStaticFile(ctx.mount.value, rest);
+            if (rel === undefined) {
+                reply.callNotFound();
+                return reply;
+            }
+            // 此处给出的是**未编码**的相对路径：`@fastify/static` 内部会自行 `encodeURI()`
+            // 再交给 `@fastify/send`，若在此提前编码将造成双重编码
+            return reply.sendFile(rel, ctx.mount.value.dir);
+        }
+        // 携带升级头进入但最终未被 `@fastify/websocket` 接管 —— 最常见的原因是对端实际
+        // 发送的是一个普通 GET 请求，因此明确说明该端点仅接受 WebSocket，避免对端只见 404 而无从判断
+        if (ctx.ws !== undefined) {
+            return this.#reject(reply, 400, `${ctx.path} 是一个 WebSocket 端点，请使用 WebSocket 连接`);
+        }
+        return this.#reject(reply, 404, `路由 ${ctx.path} 不存在`);
+    }
+    /**
+     * 一条 WebSocket 握手成功后接管连接
+     * @param socket `ws` 原生连接
+     * @param request 握手时的 Fastify 请求
+     */
+    #openConnection(socket, request) {
+        const ctx = this.#contexts.get(request);
+        const hit = ctx?.ws;
+        if (ctx === undefined || hit === undefined) {
+            socket.close(1011, "服务器内部状态丢失");
+            return;
+        }
+        const conn = wrapConnection(socket, this.#nextConnId(), ipOf(request), request.headers, this.#logger);
+        this.#connections.add(conn);
+        conn.onClose(() => {
+            this.#connections.delete(conn);
+        });
+        try {
+            hit.value.handler(conn, this.#toRequest(request, ctx, hit.params));
+        }
+        catch (err) {
+            // 处理函数是同步抛的，此时插件很可能还没挂上任何回调，直接关掉比留个哑连接好
+            this.#logger.error(`WebSocket ${hit.pattern} 的处理函数抛错：${messageOf(err)}`);
+            conn.close(1011, "处理函数抛错");
+        }
+    }
+}
+/**
+ * 创建一个共享服务器，但**不**开始监听
+ *
+ * `await ready()` 在此处即完成，而非留至 `listen()`：`ready()` 之后 Fastify 不再
+ * 接受新路由，而本服务器共计只有那 4 条 catch-all，插件后续注册的路由均进入 `PathTable`，
+ * 不经由 Fastify —— 因此提前 ready 是安全的，同时可使 `raw.inject()` / `raw.injectWS()`
+ * 在不占用端口的前提下直接用于测试。
+ * @param opts 构造参数
+ * @returns 已就绪的服务器
+ */
+export async function createManagedServer(opts) {
+    return ManagedServer.create(opts);
+}
+//# sourceMappingURL=index.js.map