@e-xi/xion 0.0.6

package/dist/main/remote-service/index.js

@@ -0,0 +1,17 @@
+import {
+  RemoteServiceManager,
+  RemoteServiceManagerAbstract
+} from "../../chunk-files/chunk-DD6WZ4NY.js";
+import {
+  RemoteServiceAllowedRequestMethods
+} from "../../chunk-files/chunk-J34MOWJP.js";
+import "../../chunk-files/chunk-RN7AI33H.js";
+import "../../chunk-files/chunk-ID3YDA2K.js";
+import "../../chunk-files/chunk-GN2FNR3Z.js";
+import "../../chunk-files/chunk-3RVKOFMP.js";
+import "../../chunk-files/chunk-FMQTZ3QV.js";
+export {
+  RemoteServiceAllowedRequestMethods,
+  RemoteServiceManager,
+  RemoteServiceManagerAbstract
+};

package/dist/main/remote-service/remote-service-manager-abstract.d.ts

@@ -0,0 +1,303 @@
+import type { XoAppAbstract } from '../app/xo-app-abstract';
+import type { RemoteServiceRequestOptions } from './types/remote-service';
+import { type Session } from 'electron';
+/**
+ * 远程服务管理器抽象类
+ * <p>基于 HTTP(S) 请求实现连接探测与心跳检测</p>
+ * @class RemoteServiceManagerAbstract
+ */
+export declare abstract class RemoteServiceManagerAbstract {
+    /** Xion 应用 */
+    protected readonly xoApp: XoAppAbstract;
+    /** 是否已初始化 */
+    private initialized;
+    /** 远程服务状态 */
+    private state;
+    /** 心跳定时器 */
+    private heartbeatTimer?;
+    /** 重试定时器 */
+    private retryTimer?;
+    /** 快速重试耗尽后的低频探测定时器 */
+    private lowFrequencyProbeTimer?;
+    /** 当前探测请求的取消控制器 */
+    private abortController?;
+    /** 会话序号，用于忽略旧会话的异步结果 */
+    private sessionId;
+    /** 当前进行中探测所属的会话序号 */
+    private probeSessionId;
+    /** 本次运行期间连续失败次数 */
+    private retryCount;
+    /** 是否已手动停止连接 */
+    private manualStopped;
+    /** 是否正在探测 */
+    private probing;
+    /** 当前探测任务，用于合并并发探测请求 */
+    private probePromise?;
+    /** 主进程远程服务状态监听器 */
+    private readonly stateListeners;
+    /**
+     * 构造函数
+     * @param {XoAppAbstract} xoApp Xion 应用
+     */
+    constructor(xoApp: XoAppAbstract);
+    /**
+     * 获取 Electron 默认会话
+     * @returns {Electron.Session}
+     * @private
+     */
+    private electronSession;
+    /**
+     * 获取远程服务配置
+     * @returns {XoRemoteService.Config}
+     * @protected
+     */
+    protected config(): XoRemoteService.Config;
+    /**
+     * 获取远程服务用户设置
+     * @returns {XoRemoteService.UserSettings}
+     * @private
+     */
+    private getUserSettings;
+    /**
+     * 获取实际生效的远程服务设置
+     * <p>用户设置优先于配置</p>
+     * @returns {XoRemoteService.EffectiveSettings}
+     */
+    getEffectiveSettings(): XoRemoteService.EffectiveSettings;
+    /**
+     * 设置远程服务用户设置
+     * @param {XoRemoteService.UserSettings} settings 远程服务用户设置
+     */
+    setSettings(settings: XoRemoteService.UserSettings): void;
+    /**
+     * 重置远程服务用户设置
+     */
+    resetSettings(): void;
+    /**
+     * 请求远程服务 API
+     * <p>当前接口面向 JSON 或文本请求；文件和流式数据使用渲染进程协议</p>
+     * <p>仅在远程服务连接成功后发起请求</p>
+     * @template T 响应数据类型
+     * @param {XoRemoteService.Request}     request       请求参数
+     * @param {Session}                     targetSession 发起请求的渲染进程 Session，主进程调用时默认使用 defaultSession
+     * @param {RemoteServiceRequestOptions} options       主进程请求选项
+     * @returns {Promise<XoRemoteService.Response<T>>}
+     */
+    request<T = unknown>(request: XoRemoteService.Request, targetSession?: Session, options?: RemoteServiceRequestOptions): Promise<XoRemoteService.Response<T>>;
+    /**
+     * 校验请求所属认证会话未发生变化
+     * @param {number} expectedRevision 请求开始时的认证操作版本，未认证请求不传入
+     * @returns {void}
+     * @private
+     */
+    private requireAuthenticationRevision;
+    /**
+     * 执行一次远程服务请求
+     * @template T 响应数据类型
+     * @param {XoRemoteService.Request}           request               请求参数
+     * @param {Session}                           targetSession         发起请求的 Session
+     * @param {XoRemoteService.EffectiveSettings} settings              生效设置
+     * @param {XoRemoteService.Method}            method                请求方法
+     * @param {URL}                               targetUrl             请求地址
+     * @param {JwtAuthorizationContext}           authorization         访问令牌请求头上下文
+     * @param {Readonly<Record<string, string>>}  authenticationHeaders 主进程内部认证请求头
+     * @returns {Promise<XoRemoteService.Response<T>>}
+     * @private
+     */
+    private executeRequest;
+    /**
+     * 构建远程服务请求地址
+     * @param {string}                  serviceUrl 服务基础地址
+     * @param {XoRemoteService.Request} request    请求参数
+     * @returns {URL}
+     * @private
+     */
+    private resolveRequestUrl;
+    /**
+     * 构建请求头
+     * @param {XoRemoteService.Request}          request               渲染进程请求
+     * @param {JwtAuthorizationContext}          authorization         主进程管理的访问令牌请求头上下文
+     * @param {Readonly<Record<string, string>>} authenticationHeaders 主进程内部认证请求头
+     * @returns {Headers}
+     * @private
+     */
+    private buildRequestHeaders;
+    /**
+     * 强制设置 User-Agent 为当前 Session 的 User-Agent
+     * @param {Headers}          headers       请求头
+     * @param {Electron.Session} targetSession 目标 Session
+     * @private
+     */
+    private forceUserAgent;
+    /**
+     * 构建请求体
+     * @param {unknown} body 请求体
+     * @returns {string | undefined}
+     * @private
+     */
+    private buildRequestBody;
+    /**
+     * 构建可返回到渲染进程的响应头
+     * @param {Headers} headers 远程响应头
+     * @returns {Record<string, string>}
+     * @private
+     */
+    private buildResponseHeaders;
+    /**
+     * 验证远程服务用户设置
+     * @param {XoRemoteService.UserSettings} settings 远程服务用户设置
+     * @private
+     */
+    private validateUserSettings;
+    /**
+     * 验证服务地址
+     * <p>仅支持 http/https，生产环境仅允许 https，且必须是合法地址</p>
+     * @param {string} url 服务地址
+     * @private
+     */
+    private validateServiceUrl;
+    /**
+     * 重新发起探测连接
+     * @private
+     */
+    private reconnect;
+    /**
+     * 是否启用远程服务
+     * @returns {boolean}
+     */
+    enabled(): boolean;
+    /**
+     * 初始化远程服务模块
+     * <p>未启用时不发起连接和心跳；启用但未配置服务地址时报错</p>
+     * @returns {boolean}
+     */
+    initialize(): boolean;
+    /**
+     * 确保远程服务已连接
+     * <p>未连接时立即执行一次探测；并发调用复用当前探测任务</p>
+     * @returns {Promise<void>}
+     * @private
+     */
+    private ensureConnected;
+    /**
+     * 发起连接（执行一次连接探测）
+     * @returns {Promise<void>}
+     */
+    connect(): Promise<void>;
+    /**
+     * 执行一次连接探测
+     * <p>HTTP 请求服务地址，仅 200 视为服务可达，其他状态码或网络错误视为失败</p>
+     * @param {boolean} initial 是否为首次连接探测（true 时状态显示为连接中）
+     * @returns {Promise<boolean>} 是否探测成功
+     * @private
+     */
+    private probe;
+    /**
+     * 执行远程服务探测请求
+     * @param {boolean} initial 是否为首次连接探测
+     * @param {number}  session 当前会话序号
+     * @returns {Promise<boolean>} 是否探测成功
+     * @private
+     */
+    private executeProbe;
+    /**
+     * 探测成功
+     * @private
+     */
+    private onProbeSuccess;
+    /**
+     * 探测失败
+     * @param {string} message 失败原因
+     * @private
+     */
+    private onProbeFailure;
+    /**
+     * 安排下一次低频探测
+     * @param {number} interval 探测间隔（毫秒）
+     * @private
+     */
+    private scheduleLowFrequencyProbe;
+    /**
+     * 转换探测错误信息
+     * @param {unknown} error 错误对象
+     * @returns {string}
+     * @private
+     */
+    private toErrorMessage;
+    /**
+     * 转换远程服务请求错误
+     * @param {unknown} error 原始错误
+     * @returns {Error}
+     * @private
+     */
+    private toRequestError;
+    /**
+     * 构建心跳请求地址
+     * <p>未配置心跳路径时直接请求服务地址</p>
+     * @param {XoRemoteService.EffectiveSettings} settings 生效设置
+     * @returns {string}
+     * @private
+     */
+    private buildHeartbeatUrl;
+    /**
+     * 停止当前连接探测
+     * @private
+     */
+    private stopConnection;
+    /**
+     * 启动心跳
+     * <p>按间隔周期探测服务地址，失败时进入断开与重试流程</p>
+     * @private
+     */
+    private startHeartbeat;
+    /**
+     * 停止心跳
+     * @private
+     */
+    private stopHeartbeat;
+    /**
+     * 获取远程服务状态
+     * @returns {XoRemoteService.State}
+     */
+    getState(): XoRemoteService.State;
+    /**
+     * 监听主进程远程服务状态
+     * @param {XoRemoteService.StateListener} listener 状态监听器
+     * @returns {() => void} 移除监听器
+     */
+    addStateListener(listener: XoRemoteService.StateListener): () => void;
+    /**
+     * 更新远程服务状态
+     * @param {Partial<XoRemoteService.State>} state 状态
+     * @protected
+     */
+    protected updateState(state: Partial<XoRemoteService.State>): void;
+    /**
+     * 通知远程服务状态到全部渲染进程
+     */
+    syncToAllWindows(): void;
+    /**
+     * 通知远程服务状态到渲染进程
+     * @param {Electron.BrowserWindow} window 窗口
+     */
+    syncToWindow(window: Electron.BrowserWindow): void;
+    /**
+     * 通知远程服务设置到全部渲染进程
+     */
+    syncSettingsToAllWindows(): void;
+    /**
+     * 通知远程服务设置到渲染进程
+     * @param {Electron.BrowserWindow} window 窗口
+     */
+    syncSettingsToWindow(window: Electron.BrowserWindow): void;
+    /**
+     * 清理全部定时器
+     * @private
+     */
+    private clearTimers;
+    /**
+     * 清理快速重试和低频探测定时器
+     * @private
+     */
+    private clearReconnectTimers;
+}

package/dist/main/remote-service/remote-service-manager.d.ts

@@ -0,0 +1,7 @@
+import { RemoteServiceManagerAbstract } from './remote-service-manager-abstract';
+/**
+ * 远程服务管理器
+ * @class RemoteServiceManager
+ */
+export declare class RemoteServiceManager extends RemoteServiceManagerAbstract {
+}

package/dist/main/remote-service/types/remote-service.d.ts

@@ -0,0 +1,9 @@
+/** 主进程远程服务请求选项 */
+export interface RemoteServiceRequestOptions {
+    /** 鉴权策略，auto 表示存在登录会话时自动附加访问令牌 */
+    authentication?: 'auto' | 'none'
+    /** 主进程内部管理的认证请求头，不接受渲染进程传入 */
+    authenticationHeaders?: Readonly<Record<string, string>>
+    /** 收到 401 后是否自动刷新令牌并重试一次 */
+    retryUnauthorized?: boolean
+}

package/dist/main/renderer-protocol/handlers/renderer-remote-service-protocol-handlers.d.ts

@@ -0,0 +1,130 @@
+import { RendererProtocolHandlersAbstract } from '../renderer-protocol-handlers-abstract';
+/**
+ * 渲染进程远程服务代理协议处理器（内置）
+ * @class RendererRemoteServiceProtocolHandlers
+ */
+export declare class RendererRemoteServiceProtocolHandlers extends RendererProtocolHandlersAbstract {
+    /**
+     * 处理器映射
+     * @returns {XoRendererProtocol.HandlerMap}
+     */
+    handlerMap(): XoRendererProtocol.HandlerMap;
+    /**
+     * 代理远程服务请求
+     * @param {XoRendererProtocol.Context} context 协议处理上下文
+     * @returns {Promise<Response>}
+     * @private
+     */
+    private handleRemoteService;
+    /**
+     * 创建 CORS 预检响应
+     * @param {Request} request       原始请求
+     * @param {string}  allowedOrigin 已允许的请求来源
+     * @returns {Response}
+     * @private
+     */
+    private preflightResponse;
+    /**
+     * 将协议请求地址映射到远程服务地址
+     * @param {string} serviceUrl 远程服务基础地址
+     * @param {URL}    requestUrl 协议请求地址
+     * @returns {URL | undefined}
+     * @private
+     */
+    private resolveTargetUrl;
+    /**
+     * 创建远程服务请求头
+     * @param {Headers} source 原始请求头
+     * @returns {Headers}
+     * @private
+     */
+    private requestHeaders;
+    /**
+     * 创建返回渲染进程的响应头
+     * @param {Headers} source        远程服务响应头
+     * @param {string}  allowedOrigin 已允许的请求来源
+     * @returns {Headers}
+     * @private
+     */
+    private responseHeaders;
+    /**
+     * 获取不允许渲染进程传入的请求头名称
+     * @returns {Set<string>}
+     * @private
+     */
+    private refusedRequestHeaderNames;
+    /**
+     * 判断是否拒绝渲染进程传入指定请求头
+     * @param {string}      name               请求头名称
+     * @param {Set<string>} refusedHeaderNames 拒绝的请求头名称
+     * @returns {boolean}
+     * @private
+     */
+    private isRefusedRequestHeader;
+    /**
+     * 强制设置 User-Agent 为当前 Session 的 User-Agent
+     * @param {Headers}          headers       请求头
+     * @param {Electron.Session} targetSession 目标 Session
+     * @private
+     */
+    private forceUserAgent;
+    /**
+     * 获取 Connection 请求头声明的逐跳头名称
+     * @param {Headers} source 请求头或响应头
+     * @returns {Set<string>}
+     * @private
+     */
+    private connectionHeaderNames;
+    /**
+     * 创建 CORS 响应头
+     * @param {string} allowedOrigin 已允许的请求来源
+     * @returns {Headers}
+     * @private
+     */
+    private corsHeaders;
+    /**
+     * 应用 CORS 响应头
+     * @param {Headers} headers       响应头
+     * @param {string}  allowedOrigin 已允许的请求来源
+     * @returns {void}
+     * @private
+     */
+    private applyCorsHeaders;
+    /**
+     * 获取允许返回的请求来源
+     * @param {string} origin 请求来源
+     * @returns {string | undefined}
+     * @private
+     */
+    private resolveAllowedOrigin;
+    /**
+     * 获取允许访问远程服务代理的渲染进程来源
+     * @returns {Set<string>}
+     * @private
+     */
+    private allowedOrigins;
+    /**
+     * 判断请求方法是否可以携带请求体
+     * @param {string} method 请求方法
+     * @returns {boolean}
+     * @private
+     */
+    private hasRequestBody;
+    /**
+     * 追加 Vary 响应头值
+     * @param {string} value 当前 Vary 响应头
+     * @param {string} name  响应头名称
+     * @returns {string}
+     * @private
+     */
+    private appendVary;
+    /**
+     * 创建文本响应
+     * @param {number}      status  状态码
+     * @param {string}      message 响应消息
+     * @param {HeadersInit} headers 响应头
+     * @returns {Response}
+     * @private
+     */
+    private response;
+}

package/dist/main/renderer-protocol/handlers/renderer-root-protocol-handlers.d.ts

@@ -0,0 +1,65 @@
+import { RendererProtocolHandlersAbstract } from '../renderer-protocol-handlers-abstract';
+/**
+ * 渲染进程根目录协议处理器（内置）
+ * @class RendererRootProtocolHandlers
+ */
+export declare class RendererRootProtocolHandlers extends RendererProtocolHandlersAbstract {
+    /**
+     * 处理器映射
+     * @returns {XoRendererProtocol.HandlerMap}
+     */
+    handlerMap(): XoRendererProtocol.HandlerMap;
+    /**
+     * 加载应用渲染根目录资源
+     * @param {XoRendererProtocol.Context} context 协议处理上下文
+     * @returns {Promise<Response>}
+     * @private
+     */
+    private handleRoot;
+    /**
+     * 从 Vite 开发服务器获取渲染资源
+     * @param {XoRendererProtocol.Context} context 协议处理上下文
+     * @returns {Promise<Response>}
+     * @private
+     */
+    private handleDevResource;
+    /**
+     * 将自定义协议地址解析为 Vite 地址（开发环境）
+     * @param {string} rendererUrl Vite 开发服务基础地址
+     * @param {URL}    requestUrl  自定义协议地址
+     * @returns {URL | undefined}
+     * @private
+     */
+    private resolveDevTargetUrl;
+    /**
+     * 解析渲染进程发布目录（生产环境）
+     * @returns {string | undefined}
+     * @private
+     */
+    private resolveRendererRoot;
+    /**
+     * 将协议地址解析为发布目录内的文件路径
+     * @param {string} rootDir 渲染进程发布目录
+     * @param {URL}    url     协议地址
+     * @returns {string | undefined}
+     * @private
+     */
+    private resolveFilePath;
+    /**
+     * 判断文件是否位于指定目录内
+     * @param {string} parent 父目录
+     * @param {string} child  文件路径
+     * @returns {boolean}
+     * @private
+     */
+    private isInside;
+    /**
+     * 创建文本响应
+     * @param {number}                 status  状态码
+     * @param {string}                 message 响应消息
+     * @param {Record<string, string>} headers 响应头
+     * @returns {Response}
+     * @private
+     */
+    private response;
+}

package/dist/main/renderer-protocol/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Automatically generated by scripts/gen-exports.ts
+ */
+export * from './handlers/renderer-remote-service-protocol-handlers';
+export * from './handlers/renderer-root-protocol-handlers';
+export * from './renderer-protocol-handlers-abstract';
+export * from './renderer-protocol-manager-abstract';
+export * from './renderer-protocol-manager';
+export type * from './types/renderer-protocol';

package/dist/main/renderer-protocol/index.js

@@ -0,0 +1,18 @@
+import {
+  RendererProtocolHandlersAbstract,
+  RendererProtocolManager,
+  RendererProtocolManagerAbstract,
+  RendererRemoteServiceProtocolHandlers,
+  RendererRootProtocolHandlers
+} from "../../chunk-files/chunk-UCMR6V67.js";
+import "../../chunk-files/chunk-WOJ2UKI7.js";
+import "../../chunk-files/chunk-GN2FNR3Z.js";
+import "../../chunk-files/chunk-3RVKOFMP.js";
+import "../../chunk-files/chunk-FMQTZ3QV.js";
+export {
+  RendererProtocolHandlersAbstract,
+  RendererProtocolManager,
+  RendererProtocolManagerAbstract,
+  RendererRemoteServiceProtocolHandlers,
+  RendererRootProtocolHandlers
+};

package/dist/main/renderer-protocol/renderer-protocol-handlers-abstract.d.ts

@@ -0,0 +1,23 @@
+import type { XoAppAbstract } from '../app/xo-app-abstract';
+/**
+ * 渲染进程协议处理器抽象类
+ * @class RendererProtocolHandlersAbstract
+ */
+export declare abstract class RendererProtocolHandlersAbstract {
+    /**
+     * Xion 应用
+     * @type {XoAppAbstract}
+     * @protected
+     */
+    protected readonly xoApp: XoAppAbstract;
+    /**
+     * 构造函数
+     * @param {XoAppAbstract} xoApp Xion 应用
+     */
+    constructor(xoApp: XoAppAbstract);
+    /**
+     * 处理器映射
+     * @returns {XoRendererProtocol.HandlerMap}
+     */
+    abstract handlerMap(): XoRendererProtocol.HandlerMap;
+}

package/dist/main/renderer-protocol/renderer-protocol-manager-abstract.d.ts

@@ -0,0 +1,78 @@
+import type { XoAppAbstract } from '../app/xo-app-abstract';
+import { type Session } from 'electron';
+/**
+ * 渲染进程协议管理器抽象类
+ * @class RendererProtocolManagerAbstract
+ */
+export declare abstract class RendererProtocolManagerAbstract {
+    /** 是否已注册特权协议 */
+    private schemeRegistered;
+    /** 是否已初始化处理器 */
+    private handlersInitialized;
+    /** 已接管协议请求的 Session */
+    private readonly initializedSessions;
+    /** 已注册处理器类 */
+    private readonly registeredHandlerClasses;
+    /** 已注册处理器键 */
+    private readonly registeredHandlerKeys;
+    /** 协议处理器映射 */
+    private readonly handlerMap;
+    /**
+     * Xion 应用
+     * @type {XoAppAbstract}
+     * @protected
+     */
+    protected readonly xoApp: XoAppAbstract;
+    /**
+     * 构造函数
+     * @param {XoAppAbstract} xoApp Xion 应用
+     * <p>构造阶段会直接注册特权协议，因此必须在 Electron ready 事件前创建管理器。</p>
+     */
+    constructor(xoApp: XoAppAbstract);
+    /**
+     * 在 Electron 就绪前注册特权协议
+     * @returns {boolean} 是否完成注册
+     */
+    registerScheme(): boolean;
+    /**
+     * 初始化处理器并接管默认 Session 的渲染进程协议请求
+     * @returns {boolean} 是否完成初始化
+     */
+    initialize(): boolean;
+    /**
+     * 接管指定 Session 的渲染进程协议请求
+     * @param {Electron.Session} targetSession Electron Session
+     * @returns {boolean} 是否完成初始化
+     */
+    initializeSession(targetSession: Session): boolean;
+    /**
+     * 获取渲染进程入口地址，即 window.loadURL() 的地址
+     * @param {string} pathname 页面路径
+     * @returns {string | undefined}
+     */
+    entryUrl(pathname: string): string | undefined;
+    /**
+     * 处理渲染进程协议请求
+     * @param {Request}          request       协议请求
+     * @param {Electron.Session} targetSession 当前协议请求所属 Session
+     * @returns {Promise<Response>}
+     */
+    handle(request: Request, targetSession: Session): Promise<Response>;
+    /**
+     * 注册全部处理器
+     * @private
+     */
+    private registerHandlers;
+    /**
+     * 获取渲染进程协议名
+     * @returns {string | undefined}
+     * @private
+     */
+    private getScheme;
+    /**
+     * 创建自定义处理器列表
+     * @returns {XoRendererProtocol.HandlersConstructor[]}
+     * @protected
+     */
+    protected abstract handlers(): XoRendererProtocol.HandlersConstructor[];
+}

package/dist/main/renderer-protocol/renderer-protocol-manager.d.ts

@@ -0,0 +1,13 @@
+import { RendererProtocolManagerAbstract } from './renderer-protocol-manager-abstract';
+/**
+ * 渲染进程协议管理器
+ * @class RendererProtocolManager
+ */
+export declare class RendererProtocolManager extends RendererProtocolManagerAbstract {
+    /**
+     * 自定义处理器列表
+     * @returns {XoRendererProtocol.HandlersConstructor[]}
+     * @protected
+     */
+    protected handlers(): XoRendererProtocol.HandlersConstructor[];
+}