@yunzai-ng/core 0.1.0

package/dist/server/index.d.ts

@@ -0,0 +1,189 @@
+import { type FastifyInstance } from "fastify";
+import type { Disposer, HttpMethod, Logger, RouteHandler, RouteOptions, ServerInfo, WebSocketHandler, WebSocketOptions } from "@yunzai-ng/types";
+import type { CoreConfigHandle } from "../config/core-config.js";
+import type { ServerSink } from "../plugin/hooks.js";
+/** 面板"路由一览"里的一条 HTTP 路由 */
+export interface RouteSummary {
+    /** 请求方法 */
+    readonly method: HttpMethod;
+    /** URL 模式 */
+    readonly pattern: string;
+    /** 注册方前缀 */
+    readonly scope: string;
+    /** 是否需要鉴权 */
+    readonly auth: boolean;
+}
+/** 面板"路由一览"里的一个 WebSocket 端点 */
+export interface WebSocketSummary {
+    /** URL 模式 */
+    readonly pattern: string;
+    /** 注册方前缀 */
+    readonly scope: string;
+}
+/** 面板"路由一览"里的一个静态挂载 */
+export interface StaticSummary {
+    /** URL 模式 */
+    readonly pattern: string;
+    /** 本地目录 */
+    readonly dir: string;
+    /** 是否单页回退 */
+    readonly spa: boolean;
+}
+/** 创建共享服务器的参数 */
+export interface ManagedServerOptions {
+    /** 内核配置句柄，监听地址、端口与访问令牌都从这里读 */
+    readonly config: CoreConfigHandle;
+    /** 日志器 */
+    readonly logger: Logger;
+}
+/**
+ * 共享 HTTP / WebSocket 服务器
+ *
+ * 实现 `ServerSink`，因此 `ctx.route()` / `ctx.websocket()` / `ctx.static()` 最终都落到
+ * 这里。面板自己的 API 也只是"一个 scope 为 `/api` 的普通注册方"，没有任何特权 ——
+ * 这是"一切皆可为插件"在服务器层的体现。
+ */
+export declare class ManagedServer implements ServerSink {
+    #private;
+    /**
+     * 建好实例但不监听
+     *
+     * **不要直接 `new`**，用 `createManagedServer()`：路由必须等到两个 Fastify 插件启动
+     * 完成之后才能注册（原因见 `#boot()`），而那是一个异步过程，构造函数里做不到。
+     * @param opts 构造参数
+     */
+    constructor(opts: ManagedServerOptions);
+    /**
+     * 建一个已就绪的服务器
+     * @param opts 构造参数
+     * @returns 已 `ready()` 的服务器
+     */
+    static create(opts: ManagedServerOptions): Promise<ManagedServer>;
+    /**
+     * 当前服务器状态
+     *
+     * 刻意做成 getter 而不是构造时算好的常量：`port: 0` 时内核会拿到一个随机端口，
+     * 只有 `listen()` 之后才知道是多少，而测试与面板都要显示真实端口。
+     * @returns 服务器信息
+     */
+    get info(): ServerInfo;
+    /** 当前保持连接的 WebSocket 数量 */
+    get connections(): number;
+    /**
+     * 原生 Fastify 实例
+     *
+     * 保留给两种场合：测试中的 `inject()` / `injectWS()`，以及插件确实需要 Fastify 原生
+     * 能力（multipart、SSE、自定义序列化）之时。**直接在其上注册的路由无法摘除**，
+     * 插件热重载后会残留为失效路由，因此除已确认可接受该后果外，应使用 `route()`。
+     * @returns Fastify 实例
+     */
+    get raw(): FastifyInstance;
+    /**
+     * 非本机监听时确保有访问令牌
+     *
+     * 只监听本机就不生成 —— 单机用户不该为了打开面板先去配置文件里抄一串随机字符。
+     * 一旦监听地址对外，没有令牌等于把配置写权限公开，所以这里**自动生成并落盘**，
+     * 而不是只打一句警告了事。
+     * @returns 完成时 resolve
+     */
+    ensureToken(): Promise<void>;
+    /**
+     * 开始监听
+     *
+     * 由 `App.start()` 在插件全部装完之后调用：那时路由才齐，也不会出现"面板半截可用"
+     * 的窗口期。
+     * @returns 完成时 resolve
+     * @throws 服务器已关闭、或端口被占用时
+     */
+    listen(): Promise<void>;
+    /**
+     * 关闭服务器
+     *
+     * 幂等。清表置于 `finally` 中：`fastify.close()` 抛错（例如某个 `preClose` 钩子出现问题）
+     * 亦不应残留大量指向已卸载插件闭包的注册项。
+     * @returns 完成时 resolve
+     */
+    close(): Promise<void>;
+    /**
+     * 注册一条 HTTP 路由
+     * @param scope URL 前缀，通常是 `/plugin/<插件名>`
+     * @param method 请求方法，大小写不敏感
+     * @param path 相对 scope 的路径，可含 `:id` 与末尾的 `*rest`
+     * @param handler 处理函数
+     * @param opts 路由选项；`auth` 缺省为 true
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、方法不受支持、或同一模式重复注册时
+     */
+    route(scope: string, method: HttpMethod, path: string, handler: RouteHandler, opts?: RouteOptions): Disposer;
+    /**
+     * 注册一个 WebSocket 端点
+     *
+     * 不给 `verify` 时沿用面板令牌校验（与 `route()` 的 `auth` 默认为 true 对齐）。
+     * 适配器的反向连接端点要让平台连进来，就自己给一个 `verify` 做签名校验 ——
+     * 给了就完全接管，不再叠加令牌校验。
+     * @param scope URL 前缀
+     * @param path 相对 scope 的路径
+     * @param handler 连接建立后的处理函数
+     * @param opts 端点选项
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、或同一模式重复注册时
+     */
+    websocket(scope: string, path: string, handler: WebSocketHandler, opts?: WebSocketOptions): Disposer;
+    /**
+     * 挂一个静态目录
+     * @param scope URL 前缀
+     * @param urlPath 相对 scope 的 URL 路径，`""` 或 `"/"` 表示挂在 scope 根上
+     * @param dir 本地目录绝对路径
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、`dir` 不是绝对路径、或同一模式重复注册时
+     */
+    static(scope: string, urlPath: string, dir: string): Disposer;
+    /**
+     * 挂载面板：把一个单页应用目录挂到站点根路径
+     *
+     * 内置面板与接管它的插件都走这里，因此"谁在提供面板"只有一个判定依据
+     * （`claimant("/")`）。第二个调用方会在路径表里撞上重复模式而抛错，
+     * 这正是期望行为：静默覆盖会让面板显示的内容无法判定。
+     * @param owner 归属标识，如 `core` 或 `plugin:webui-next`
+     * @param dir 单页应用产物目录（绝对路径）
+     * @returns 注销句柄；幂等
+     * @throws 服务器已关闭、`dir` 不是绝对路径、或根路径已被占用时
+     */
+    panel(owner: string, dir: string): Disposer;
+    /**
+     * 导出全部 HTTP 路由，面板"路由一览"用
+     * @returns 路由摘要数组
+     */
+    listRoutes(): RouteSummary[];
+    /**
+     * 导出全部 WebSocket 端点
+     * @returns 端点摘要数组
+     */
+    listWebsockets(): WebSocketSummary[];
+    /**
+     * 导出全部静态挂载
+     * @returns 挂载摘要数组
+     */
+    listStatic(): StaticSummary[];
+    /**
+     * 查询某路径当前由谁提供
+     *
+     * 先查静态挂载再查 GET 路由：内核用它判断根路径是否已被插件接管，而接管
+     * 面板既可以挂一个单页目录，也可以注册一条返回 HTML 的路由，两种都要认。
+     * @param path URL 路径
+     * @returns 提供方的注册前缀；无人提供时 undefined
+     */
+    claimant(path: string): string | undefined;
+}
+/**
+ * 创建一个共享服务器，但**不**开始监听
+ *
+ * `await ready()` 在此处即完成，而非留至 `listen()`：`ready()` 之后 Fastify 不再
+ * 接受新路由，而本服务器共计只有那 4 条 catch-all，插件后续注册的路由均进入 `PathTable`，
+ * 不经由 Fastify —— 因此提前 ready 是安全的，同时可使 `raw.inject()` / `raw.injectWS()`
+ * 在不占用端口的前提下直接用于测试。
+ * @param opts 构造参数
+ * @returns 已就绪的服务器
+ */
+export declare function createManagedServer(opts: ManagedServerOptions): Promise<ManagedServer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAuBA,OAAgB,EAAE,KAAK,eAAe,EAA0C,MAAM,SAAS,CAAA;AAG/F,OAAO,KAAK,EAEV,QAAQ,EACR,UAAU,EACV,MAAM,EACN,YAAY,EACZ,YAAY,EAGZ,UAAU,EAEV,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAmJpD,2BAA2B;AAC3B,MAAM,WAAW,YAAY;IAC3B,WAAW;IACX,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,aAAa;IACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,YAAY;IACZ,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,aAAa;IACb,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,aAAa;IACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,YAAY;IACZ,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,uBAAuB;AACvB,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,WAAW;IACX,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,aAAa;IACb,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAED,iBAAiB;AACjB,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,UAAU;IACV,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAqUD;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,UAAU;;IA8B9C;;;;;;OAMG;gBACS,IAAI,EAAE,oBAAoB;IAgBtC;;;;OAIG;WACU,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAqGvE;;;;;;OAMG;IACH,IAAI,IAAI,IAAI,UAAU,CASrB;IAED,2BAA2B;IAC3B,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;;;OAOG;IACH,IAAI,GAAG,IAAI,eAAe,CAEzB;IAED;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAYlC;;;;;;;OAOG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAY7B;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;;;;;;;OASG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,IAAI,GAAE,YAAiB,GACtB,QAAQ;IAgBX;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,GAAE,gBAAqB,GAAG,QAAQ;IAKxG;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ;IAI7D;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ;IAI3C;;;OAGG;IACH,UAAU,IAAI,YAAY,EAAE;IAU5B;;;OAGG;IACH,cAAc,IAAI,gBAAgB,EAAE;IAIpC;;;OAGG;IACH,UAAU,IAAI,aAAa,EAAE;IAQ7B;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAwb3C;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAE5F"}