npm - @yumerijs/core - Versions diffs - 2.2.2 → 3.0.0-alpha.1 - Mend

@yumerijs/core 2.2.2 → 3.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/dist/server.js CHANGED Viewed

@@ -1,38 +1,41 @@
 import { Logger } from './logger.js';
 import { Session } from './session.js';
 import http from 'http';
-import * as fs from 'fs';
-import * as path from 'path';
 import { URL } from 'url';
-import * as mime from 'mime-types';
 import { resolveVirtualAsset } from '@yumerijs/types';
 const logger = new Logger('server');
+/** 判断是否为流对象 */
 function isStream(value) {
     return value && typeof value.pipe === "function";
 }
+/**
+ * 核心服务器类
+ * 负责底层 HTTP 请求的监听、分发和响应
+ */
 export class Server {
     core;
     port;
     host;
     enableCors;
-    staticDir;
     httpServer = null;
     constructor(core, config = {}) {
         this.core = core;
         this.port = config.port ?? 14510;
         this.host = config.host ?? '0.0.0.0';
         this.enableCors = config.enableCors ?? true;
-        this.staticDir = config.staticDir ?? 'static';
-    }
-    getStaticDir() {
-        return this.staticDir;
     }
+    /**
+     * 创建一个新的会话对象
+     */
     createSession(ip, cookies, res, req, pathname, pluginContext, extra = {}) {
         const session = new Session(ip, cookies, this, req, res, pathname, undefined, pluginContext);
         Object.assign(session.properties, extra);
         session.protocol = extra.protocol ?? 'http';
         return session;
     }
+    /**
+     * 解析请求中的 Cookie
+     */
     parseCookies(req) {
         const cookieHeader = req.headers.cookie;
         if (!cookieHeader)
@@ -44,25 +47,19 @@ export class Server {
         });
         return cookies;
     }
+    /**
+     * 获取客户端真实 IP
+     */
     getClientIP(req) {
         const xff = req.headers['x-forwarded-for'];
         return xff ? xff.split(',')[0].trim() : req.socket.remoteAddress || '127.0.0.1';
     }
-    serveStaticFile(pathname, res) {
-        const fullPath = path.join(process.cwd(), this.staticDir, pathname);
-        fs.readFile(fullPath, (err, data) => {
-            if (err) {
-                res.writeHead(404, { 'Content-Type': 'text/html' });
-                res.end(`<html><body><h1>404 Not Found</h1></body></html>`);
-            }
-            else {
-                res.writeHead(200, { 'Content-Type': mime.lookup(fullPath) || 'text/plain' });
-                res.end(data);
-            }
-        });
-    }
+    /**
+     * 启动服务器
+     */
     async start() {
         this.httpServer = http.createServer(async (req, res) => {
+            // 处理跨域预检请求
             if (req.method === 'OPTIONS' && this.enableCors) {
                 res.writeHead(204, {
                     'Access-Control-Allow-Origin': '*',
@@ -77,6 +74,7 @@ export class Server {
             const queryParams = url.searchParams;
             const ip = this.getClientIP(req);
             const cookies = this.parseCookies(req);
+            // 处理虚拟资产加载
             if (req.method === 'GET' || req.method === 'HEAD') {
                 const virtualAsset = await resolveVirtualAsset(pathname);
                 if (virtualAsset) {
@@ -92,14 +90,18 @@ export class Server {
             const pluginContext = route ? route.context : (rootroute ? rootroute.context : undefined);
             const session = this.createSession(ip, cookies, res, req, pathname, pluginContext, { protocol: 'http', header: req.headers });
             session._startAt = Date.now();
+            /** 路由处理逻辑 */
             const handleRoute = async (routePath) => {
                 const matched = await this.core.executeRoute(routePath, session, queryParams);
                 if (!matched) {
-                    this.serveStaticFile(pathname, res);
+                    // 核心层不再提供静态文件服务，直接返回 404
+                    res.writeHead(404, { 'Content-Type': 'text/plain' });
+                    res.end('Not Found');
                     return;
                 }
                 if (session.responseHandled)
                     return;
+                // 组装响应头
                 const head = { ...session.head };
                 head['Set-Cookie'] = Object.entries(session.newCookie).map(([name, cookie]) => {
                     let cookieString = `${name}=${cookie.value}`;
@@ -121,6 +123,7 @@ export class Server {
                     head['Access-Control-Allow-Origin'] = '*';
                 }
                 res.writeHead(session.status ?? 200, head);
+                // 根据响应类型输出内容
                 switch (session.restype) {
                     case 'plain':
                         res.end(session.body);
@@ -138,9 +141,10 @@ export class Server {
                         }
                         break;
                     default:
-                        res.end(session.body); // fallback
+                        res.end(session.body);
                 }
             };
+            // 分发请求
             if (route && route.allowedMethods.includes(req.method ?? 'GET')) {
                 await handleRoute(pathname);
             }
@@ -148,9 +152,11 @@ export class Server {
                 await handleRoute('root');
             }
             else {
-                this.serveStaticFile(pathname, res);
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not Found');
             }
         });
+        // 处理 WebSocket 升级
         this.httpServer.on('upgrade', async (req, socket, head) => {
             const url = new URL(req.url || '/', `http://${req.headers.host}`);
             const pathname = url.pathname;
@@ -163,9 +169,7 @@ export class Server {
             if (route && route.ws != null) {
                 const matched = await this.core.executeRoute(pathname, session, queryParams);
                 if (!matched) {
-                    socket.write('HTTP/1.1 400 Bad Request\r\n' +
-                        'Content-Type: text/plain\r\n' +
-                        'Connection: close\r\n');
+                    socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
                     socket.destroy();
                 }
                 else {
@@ -175,9 +179,7 @@ export class Server {
                 }
             }
             else {
-                socket.write('HTTP/1.1 400 Bad Request\r\n' +
-                    'Content-Type: text/plain\r\n' +
-                    'Connection: close\r\n');
+                socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
                 socket.destroy();
             }
         });
@@ -185,6 +187,7 @@ export class Server {
             logger.info(`Server listening on ${this.host}:${this.port}`);
         });
     }
+    /** 停止服务器 */
     stop() {
         if (this.httpServer)
             this.httpServer.close(() => logger.info('Server stopped'));

package/dist/session.d.ts CHANGED Viewed

@@ -7,152 +7,253 @@ import { Server } from './server.js';
 import { IncomingMessage, ServerResponse } from 'http';
 import { Stream } from "stream";
 import { Context } from './context.js';
+/** 解析后的请求参数类型，支持字符串或字符串数组 */
 type ParsedParams = Record<string, string | string[] | undefined>;
-type MissingMode = 'keep-template' | 'keep-key' | 'remove';
+/** 客户端对象，包含原始的 HTTP 请求和响应对象 */
 export interface Client {
+    /** 原始的 Node.js HTTP 请求对象 */
     req: IncomingMessage;
+    /** 原始的 Node.js HTTP 响应对象 */
     res: ServerResponse;
+    /** 经过处理后的规范化请求头 */
     headers?: Record<string, string>;
 }
+/** 设置 Cookie 时的配置项 */
 export interface CookieOptions {
+    /** Cookie 的过期时间 */
     expires?: Date;
+    /** Cookie 的有效路径，默认为 '/' */
     path?: string;
+    /** Cookie 的有效域名 */
     domain?: string;
+    /** 是否仅在 HTTPS 连接中传输 */
     secure?: boolean;
+    /** 是否禁止客户端脚本访问该 Cookie */
     httpOnly?: boolean;
+    /** 控制 Cookie 是否随跨站请求发送 */
     sameSite?: 'Strict' | 'Lax' | 'None';
 }
+/** 响应缓存的配置项 */
 export interface CacheOptions {
+    /** 强缓存标识 ETag */
     etag?: string;
+    /** 资源最后修改时间 */
     modified?: Date;
+    /** 浏览器缓存最大时长（秒） */
     maxAge?: number;
+    /** 代理服务器缓存最大时长（秒） */
     smaxAge?: number;
+    /** 标识资源是否永不改变 */
     isImmutable?: boolean;
+    /** 显式的过期时间 */
     expires?: Date;
+    /** 缓存控制的具体策略 */
     cacheControl?: 'public' | 'private' | 'no-cache' | 'no-store' | 'must-revalidate' | 'proxy-revalidate';
 }
+/** 静态文件专用的缓存配置 */
 export interface StaticCacheOptions {
+    /** 是否启用 ETag 生成 */
     etag?: boolean;
+    /** 最大缓存时长 */
     maxAge?: number;
+    /** 代理缓存时长 */
     smaxAge?: number;
+    /** 计算 ETag 使用的哈希算法 */
     etagType?: 'md5' | 'sha1' | 'sha256' | 'sha512';
 }
+/** 响应体的数据类型分类 */
 type ResType = "plain" | "json" | "stream" | "buffer";
+/** 响应类型与具体数据结构的映射表 */
 interface BodyMap {
     plain: string;
     json: Record<string, any>;
     stream: Stream;
     buffer: Buffer;
 }
-export declare class Session {
+/**
+ * 会话请求包装类
+ * 负责收集和整理所有来自客户端的请求信息
+ */
+declare class SessionRequest {
+    /** 客户端的 IP 地址 */
     ip: string;
-    cookie: Record<string, string>;
+    /** 请求中携带的原始 Cookie 键值对 */
+    cookies: Record<string, string>;
+    /** URL 中的查询字符串参数 */
     query: Record<string, string> | undefined;
-    sessionid: string;
-    data: Record<string, any>;
-    newCookie: Record<string, {
+    /** 请求的资源路径（不含查询参数） */
+    pathname: string;
+    /** 所有的请求头信息 */
+    headers: Record<string, string>;
+    /** 客户端支持的语言列表，已按权重排序 */
+    languages: string[];
+    /** 请求使用的协议 */
+    protocol: string;
+    /** 原始的 IncomingMessage 对象 */
+    raw: IncomingMessage;
+    constructor(data: {
+        ip: string;
+        cookies: Record<string, string>;
+        query?: Record<string, string>;
+        pathname?: string;
+        headers: Record<string, string>;
+        raw: IncomingMessage;
+    });
+}
+/**
+ * 会话响应包装类
+ * 负责管理和准备发往客户端的数据
+ */
+declare class SessionResponse {
+    /** 待发送的 HTTP 状态码 */
+    status: number;
+    /** 待发送的响应头 */
+    headers: Record<string, any>;
+    /** 准备设置到客户端的 Cookie 集合 */
+    cookies: Record<string, {
         value: string;
         options: CookieOptions;
     }>;
-    head: Record<string, any>;
-    status: number;
-    private _restype;
-    private _body;
-    properties?: Record<string, any>;
-    client: Client;
+    /** 响应体的具体类型 */
+    type: ResType;
+    /** 响应的具体内容 */
+    body: any;
+    /** 标识该响应是否已经处理完毕 */
+    handled: boolean;
+    /** 原始的 ServerResponse 对象 */
+    raw: ServerResponse;
+    constructor(res: ServerResponse);
+}
+/**
+ * 会话对象 (Session)
+ * 是插件开发中最核心的对象，封装了请求、响应及各种便捷工具
+ */
+export declare class Session {
+    /** 封装后的请求对象 */
+    request: SessionRequest;
+    /** 封装后的响应对象 */
+    response: SessionResponse;
+    /** 当前会话的唯一标识符 (UUID) */
+    sessionid: string;
+    /** 持久化的会话数据存储 */
+    data: Record<string, any>;
+    /** 供插件或中间件挂载的临时属性 */
+    properties: Record<string, any>;
+    /** 对核心服务器实例的引用 */
     server: Server;
-    protocol: string;
-    pathname: string;
-    languages: string[];
-    responseHandled: boolean;
+    /** 当前插件的上下文环境 */
     pluginContext: Context | undefined;
     /**
-     * @constructor
-     * @param ip 用户IP
-     * @param cookie 会话cookie
-     * @param query 请求字符串
+     * 初始化一个新的会话
+     * @param ip 客户端IP
+     * @param cookie 请求Cookie
+     * @param server 服务器实例
+     * @param req 原始请求对象
+     * @param res 原始响应对象
+     * @param pathname 请求路径
+     * @param query 查询参数
+     * @param pluginContext 插件上下文
      */
     constructor(ip: string, cookie: Record<string, string>, server: Server, req?: IncomingMessage, res?: ServerResponse, pathname?: string, query?: Record<string, string>, pluginContext?: Context);
-    response<T extends ResType>(body: BodyMap[T], type?: T): void;
+    /** 获取客户端 IP 地址 */
+    get ip(): string;
+    /** 获取请求中的 Cookie 集合 */
+    get cookie(): Record<string, string>;
+    /** 获取 URL 查询参数 */
+    get query(): Record<string, string>;
+    /** 获取请求路径 */
+    get pathname(): string;
+    /** 获取语言列表 */
+    get languages(): string[];
+    /** 获取请求协议 */
+    get protocol(): string;
+    set protocol(val: string);
+    /** 获取或设置响应状态码 */
+    get status(): number;
+    set status(val: number);
+    /** 获取待发送的新 Cookie */
+    get newCookie(): Record<string, {
+        value: string;
+        options: CookieOptions;
+    }>;
+    /** 获取响应头对象 */
+    get head(): Record<string, any>;
+    /** 获取当前响应内容类型 */
+    get _restype(): ResType;
+    /** 获取响应是否已处理的标记 */
+    get responseHandled(): boolean;
+    set responseHandled(val: boolean);
+    /** 组装并获取 Client 兼容对象 */
+    get client(): Client;
+    /**
+     * 设置响应体内容
+     * @param body 响应内容
+     * @param type 内容类型，默认为 'plain'
+     */
+    respond<T extends ResType>(body: BodyMap[T], type?: T): void;
+    /** 获取响应类型 */
     get restype(): ResType;
-    get body(): string;
-    set body(value: string);
+    /** 获取响应体内容 */
+    get body(): any;
+    /** 设置响应体内容，自动推断类型 */
+    set body(value: any);
+    /**
+     * 设置响应 Cookie
+     * @param name Cookie 键名
+     * @param value Cookie 值
+     * @param options 配置项
+     */
     setCookie(name: string, value: string, options?: CookieOptions): void;
     /**
-     * 解析 Accept-Language 字符串为排序后的语言数组
-     * @param header Accept-Language 头，比如 "zh-CN,zh-TW;q=0.8,en-US;q=0.6"
-     * @returns 按优先级排序的语言数组，自动补上父语言
+     * 解析 Accept-Language 请求头
+     * @param header 原始头字符串
+     * @returns 排序后的语言数组
      */
-    parseAcceptLanguages(header: string): any[];
+    parseAcceptLanguages(header: string): string[];
     /**
-     * 生成 sessionid
-     * @param ip 用户IP
-     * @param option 选项
+     * 生成会话 ID (UUID)
      */
     private generateId;
     /**
-     * 解析请求体
-     * @param client 客户端
-     * @returns Promise<ParsedParams>
+     * 异步解析请求体
+     * @returns 返回解析后的参数
      */
     parseRequestBody(client?: Client): Promise<ParsedParams>;
     /**
-     * 获取请求体
-     * @param req 请求对象
-     * @returns Promise<string>
+     * 获取请求体文本
      */
     getReqBody(req: IncomingMessage): Promise<string>;
+    /**
+     * MD5 加密
+     */
     private md5;
+    /** 设置会话数据 */
     setData(key: string, value: any): void;
+    /** 删除会话数据 */
     deleteData(key: string): void;
+    /** 清空会话数据 */
     clearData(): void;
+    /** 销毁会话 */
     destroy(): void;
-    setMime(mimeType: 'png' | 'jpg' | 'jpeg' | 'pdf' | 'plain' | 'html' | 'json' | 'xml' | string): void;
+    /** 设置 MIME 类型 */
+    setMime(mimeType: string): void;
+    /** 向响应流写入数据 */
     send(data: any): any;
+    /** 结束响应 */
     endsession(message: any): any;
-    /**
-     * 获取I18n文本
-     * @param name 文本点名称
-     */
+    /** 获取国际化文本 */
     text(name: string): any;
-    /**
-     * 设置缓存标头
-     * @param option 选项
-     */
+    /** 设置缓存标头 */
     setCache(option: CacheOptions): void;
-    /**
-     * 设置静态文件
-     * @param content 文件内容
-     * @param option 选项
-     */
+    /** 发送静态内容并处理缓存 */
     static(content: string, option: CacheOptions): void;
-    /**
-     * 发送静态文件
-     * @param path 文件路径
-     * @param option 缓存选项
-     * @returns void
-     */
+    /** 发送文件并处理缓存 */
     file(path: string, option: StaticCacheOptions): void;
-    /**
-     * 发送普通文件
-     * @param path 文件路径
-     * @param isStream 是否流式传输
-     */
+    /** 直接发送文件 */
     sendFile(path: string, isStream?: boolean): void;
-    /**
-     * 渲染模板
-     * @template 模板字符串
-     * @data 数据
-     * @missing 缺失值处理方式，keep-template: 保留模板，keep-key: 保留键，remove: 移除
-     * @regex 模板匹配正则，默认为{{ xxx.xxx }}
-     */
-    render(template: string, data: Record<string, any>, missing?: MissingMode, regex?: RegExp): string;
-    /**
-     * Renders a UI component using the plugin's declared renderer.
-     * @param component The component object to render.
-     * @param data The data/props to pass to the component.
-     */
+    /** 渲染组件视图 */
     renderView(component: any, data?: Record<string, any>): Promise<void>;
-    renderFile(filePath: string, data?: any): Promise<void>;
+    /** 渲染文件 */
+    render(filePath: string, data?: any): Promise<void>;
 }
 export {};