@yumerijs/core 2.2.2 → 3.0.0-alpha.2

package/dist/session.js

@@ -6,96 +6,187 @@
 import crypto from 'crypto';
 import * as formidable from 'formidable';
 import fs from 'fs';
-export class Session {
+/**
+ * 会话请求包装类
+ * 负责收集和整理所有来自客户端的请求信息
+ */
+class SessionRequest {
+    /** 客户端的 IP 地址 */
     ip;
-    cookie;
+    /** 请求中携带的原始 Cookie 键值对 */
+    cookies;
+    /** URL 中的查询字符串参数 */
     query;
+    /** 请求的资源路径（不含查询参数） */
+    pathname;
+    /** 所有的请求头信息 */
+    headers;
+    /** 客户端支持的语言列表，已按权重排序 */
+    languages = [];
+    /** 请求使用的协议 */
+    protocol = 'http';
+    /** 原始的 IncomingMessage 对象 */
+    raw;
+    constructor(data) {
+        this.ip = data.ip;
+        this.cookies = data.cookies;
+        this.query = data.query;
+        this.pathname = data.pathname || '/';
+        this.headers = data.headers;
+        this.raw = data.raw;
+    }
+}
+/**
+ * 会话响应包装类
+ * 负责管理和准备发往客户端的数据
+ */
+class SessionResponse {
+    /** 待发送的 HTTP 状态码 */
+    status = 200;
+    /** 待发送的响应头 */
+    headers = { 'Content-Type': 'text/plain' };
+    /** 准备设置到客户端的 Cookie 集合 */
+    cookies = {};
+    /** 响应体的具体类型 */
+    type = "plain";
+    /** 响应的具体内容 */
+    body;
+    /** 标识该响应是否已经处理完毕 */
+    handled = false;
+    /** 原始的 ServerResponse 对象 */
+    raw;
+    constructor(res) {
+        this.raw = res;
+    }
+}
+/**
+ * 会话对象 (Session)
+ * 是插件开发中最核心的对象，封装了请求、响应及各种便捷工具
+ */
+export class Session {
+    /** 封装后的请求对象 */
+    request;
+    /** 封装后的响应对象 */
+    response;
+    /** 当前会话的唯一标识符 (UUID) */
     sessionid;
+    /** 持久化的会话数据存储 */
     data = {};
-    newCookie = {};
-    head = {};
-    status = 200;
-    _restype = "plain";
-    _body;
+    /** 供插件或中间件挂载的临时属性 */
     properties = {};
-    client = null;
+    /** 对核心服务器实例的引用 */
     server;
-    protocol = 'http';
-    pathname;
-    languages;
-    responseHandled = false;
+    /** 当前插件的上下文环境 */
     pluginContext;
     /**
-     * @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, cookie, server, req, res, pathname, query, pluginContext) {
-        this.ip = ip;
-        this.cookie = cookie;
-        this.query = query;
         this.server = server;
-        this.pathname = pathname;
         this.pluginContext = pluginContext;
-        let header = {};
-        for (let key in req.headers) {
-            const value = req.headers[key];
-            if (typeof value === 'string') {
-                header[key] = value;
-            }
-            else if (Array.isArray(value)) {
-                header[key] = value.join(', ');
-            }
-            else if (value !== undefined) {
-                header[key] = String(value);
+        const headers = {};
+        if (req) {
+            for (const key in req.headers) {
+                const value = req.headers[key];
+                headers[key] = Array.isArray(value) ? value.join(', ') : String(value || '');
             }
         }
-        this.client = {
-            req: req,
-            res: res,
-            headers: header
-        };
-        this.head['Content-Type'] = 'text/plain';
+        this.request = new SessionRequest({ ip, cookies: cookie, query, pathname, headers, raw: req });
+        this.response = new SessionResponse(res);
         if (cookie.sessionid) {
             this.sessionid = cookie.sessionid;
         }
         else {
-            this.sessionid = this.generateId(this.ip);
+            this.sessionid = this.generateId();
             this.setCookie('sessionid', this.sessionid);
         }
         if (cookie.lang) {
-            this.languages = cookie.lang.split(',');
+            this.request.languages = cookie.lang.split(',');
         }
-        else if (req.headers['accept-language']) {
-            this.languages = this.parseAcceptLanguages(req.headers['accept-language']);
-            this.setCookie('lang', this.languages.join(','));
+        else if (headers['accept-language']) {
+            this.request.languages = this.parseAcceptLanguages(headers['accept-language']);
+            this.setCookie('lang', this.request.languages.join(','));
         }
     }
-    response(body, type = 'text') {
-        this._restype = type;
-        this._body = body;
+    /** 获取客户端 IP 地址 */
+    get ip() { return this.request.ip; }
+    /** 获取请求中的 Cookie 集合 */
+    get cookie() { return this.request.cookies; }
+    /** 获取 URL 查询参数 */
+    get query() { return this.request.query; }
+    /** 获取请求路径 */
+    get pathname() { return this.request.pathname; }
+    /** 获取语言列表 */
+    get languages() { return this.request.languages; }
+    /** 获取请求协议 */
+    get protocol() { return this.request.protocol; }
+    set protocol(val) { this.request.protocol = val; }
+    /** 获取或设置响应状态码 */
+    get status() { return this.response.status; }
+    set status(val) { this.response.status = val; }
+    /** 获取待发送的新 Cookie */
+    get newCookie() { return this.response.cookies; }
+    /** 获取响应头对象 */
+    get head() { return this.response.headers; }
+    /** 获取当前响应内容类型 */
+    get _restype() { return this.response.type; }
+    /** 获取响应是否已处理的标记 */
+    get responseHandled() { return this.response.handled; }
+    set responseHandled(val) { this.response.handled = val; }
+    /** 组装并获取 Client 兼容对象 */
+    get client() {
+        return {
+            req: this.request.raw,
+            res: this.response.raw,
+            headers: this.request.headers
+        };
+    }
+    /**
+     * 设置响应体内容
+     * @param body 响应内容
+     * @param type 内容类型，默认为 'plain'
+     */
+    respond(body, type = 'plain') {
+        this.response.type = type;
+        this.response.body = body;
     }
+    /** 获取响应类型 */
     get restype() {
-        return this._restype;
+        return this.response.type;
     }
+    /** 获取响应体内容 */
     get body() {
-        return this._body;
+        return this.response.body;
     }
+    /** 设置响应体内容，自动推断类型 */
     set body(value) {
-        this._body = value;
-        this._restype = "plain"; // 自动把 restype 设成 plain
+        this.response.body = value;
+        this.response.type = typeof value === 'string' ? "plain" : "json";
     }
+    /**
+     * 设置响应 Cookie
+     * @param name Cookie 键名
+     * @param value Cookie 值
+     * @param options 配置项
+     */
     setCookie(name, value, options = {}) {
         if (options.path === undefined) {
             options.path = '/';
         }
-        this.newCookie[name] = { value, options };
+        this.response.cookies[name] = { value, options };
     }
     /**
-     * 解析 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) {
         if (!header)
@@ -136,18 +227,14 @@ export class Session {
         return result;
     }
     /**
-     * 生成 sessionid
-     * @param ip 用户IP
-     * @param option 选项
+     * 生成会话 ID (UUID)
      */
-    generateId(ip, option) {
-        const sessionId = this.md5(ip + Date.now().toString() + Math.random().toString()); // 添加随机性
-        return sessionId;
+    generateId() {
+        return crypto.randomUUID();
     }
     /**
-     * 解析请求体
-     * @param client 客户端
-     * @returns Promise<ParsedParams>
+     * 异步解析请求体
+     * @returns 返回解析后的参数
      */
     async parseRequestBody(client = this.client) {
         const req = client.req;
@@ -191,90 +278,58 @@ export class Session {
         });
     }
     /**
-     * 获取请求体
-     * @param req 请求对象
-     * @returns Promise<string>
+     * 获取请求体文本
      */
     async getReqBody(req) {
-        let body = "";
-        req.on('data', chunk => body += chunk.toString());
-        return body;
+        return new Promise((resolve) => {
+            let body = "";
+            req.on('data', chunk => body += chunk.toString());
+            req.on('end', () => resolve(body));
+        });
     }
-    // MD5 加密
+    /**
+     * MD5 加密
+     */
     md5(str) {
         const hash = crypto.createHash('md5');
         hash.update(str);
         return hash.digest('hex');
     }
-    // 设置会话数据
-    setData(key, value) {
-        this.data[key] = value;
-    }
-    // 删除会话数据
-    deleteData(key) {
-        delete this.data[key];
-    }
-    // 清空会话数据
-    clearData() {
-        this.data = {};
-    }
-    // 销毁会话
-    destroy() {
-        this.clearData(); // 清理会话数据
-    }
+    /** 设置会话数据 */
+    setData(key, value) { this.data[key] = value; }
+    /** 删除会话数据 */
+    deleteData(key) { delete this.data[key]; }
+    /** 清空会话数据 */
+    clearData() { this.data = {}; }
+    /** 销毁会话 */
+    destroy() { this.clearData(); }
+    /** 设置 MIME 类型 */
     setMime(mimeType) {
-        switch (mimeType) {
-            case 'png':
-                this.head['Content-Type'] = 'image/png';
-                break;
-            case 'jpg':
-            case 'jpeg':
-                this.head['Content-Type'] = 'image/jpeg';
-                break;
-            case 'pdf':
-                this.head['Content-Type'] = 'application/pdf';
-                break;
-            case 'plain':
-                this.head['Content-Type'] = 'text/plain';
-                break;
-            case 'html':
-                this.head['Content-Type'] = 'text/html';
-                break;
-            case 'json':
-                this.head['Content-Type'] = 'application/json';
-                break;
-            case 'xml':
-                this.head['Content-Type'] = 'application/xml';
-                break;
-            default:
-                this.head['Content-Type'] = mimeType;
-                break;
-        }
-    }
-    send(data) {
-        return this.client.res.write(data);
+        const map = {
+            'png': 'image/png', 'jpg': 'image/jpeg', 'jpeg': 'image/jpeg',
+            'pdf': 'application/pdf', 'plain': 'text/plain', 'html': 'text/html',
+            'json': 'application/json', 'xml': 'application/xml'
+        };
+        this.response.headers['Content-Type'] = map[mimeType] || mimeType;
     }
+    /** 向响应流写入数据 */
+    send(data) { return this.response.raw.write(data); }
+    /** 结束响应 */
     endsession(message) {
-        this.responseHandled = true;
-        return this.client.res.end(message);
+        this.response.handled = true;
+        return this.response.raw.end(message);
     }
-    /**
-     * 获取I18n文本
-     * @param name 文本点名称
-     */
+    /** 获取国际化文本 */
     text(name) {
-        return this.server.core.i18n.get(name, this.languages);
+        return this.server.core.i18n.get(name, this.request.languages);
     }
-    /**
-     * 设置缓存标头
-     * @param option 选项
-     */
+    /** 设置缓存标头 */
     setCache(option) {
         if (option.etag)
-            this.head['ETag'] = `${option.etag}`;
+            this.response.headers['ETag'] = `${option.etag}`;
         if (option.modified)
-            this.head['Last-Modified'] = option.modified.toUTCString();
-        let control = [];
+            this.response.headers['Last-Modified'] = option.modified.toUTCString();
+        const control = [];
         if (option.cacheControl !== undefined)
             control.push(option.cacheControl);
         if (option.maxAge !== undefined)
@@ -284,148 +339,90 @@ export class Session {
         if (option.isImmutable)
             control.push('immutable');
         if (control.length > 0)
-            this.head['Cache-Control'] = control.join(', ');
+            this.response.headers['Cache-Control'] = control.join(', ');
         if (option.expires)
-            this.head['Expires'] = option.expires.toUTCString();
+            this.response.headers['Expires'] = option.expires.toUTCString();
     }
-    /**
-     * 设置静态文件
-     * @param content 文件内容
-     * @param option 选项
-     */
+    /** 发送静态内容并处理缓存 */
     static(content, option) {
-        // 先查看用户是否在询问文件修改情况
-        if (this.client.headers['If-Modified-Since']) {
-            const modified = new Date(this.client.headers['If-Modified-Since']);
-            if (modified.getTime() === option.modified?.getTime()) {
-                this.status = 304;
+        if (this.request.headers['if-modified-since']) {
+            const modified = new Date(this.request.headers['if-modified-since']);
+            if (option.modified && modified.getTime() === option.modified.getTime()) {
+                this.response.status = 304;
                 return;
             }
         }
-        if (this.client.headers['If-None-Match']) {
-            if (this.client.headers['If-None-Match'] === option.etag) {
-                this.status = 304;
-                return;
-            }
+        if (this.request.headers['if-none-match'] === option.etag) {
+            this.response.status = 304;
+            return;
         }
         this.setCache(option);
-        this.response(content);
+        this.respond(content);
     }
-    /**
-     * 发送静态文件
-     * @param path 文件路径
-     * @param option 缓存选项
-     * @returns void
-     */
+    /** 发送文件并处理缓存 */
     file(path, option) {
-        if (this.client.headers['If-Modified-Since']) {
-            const modified = new Date(this.client.headers['If-Modified-Since']);
-            const moditime = fs.statSync(path).mtime;
-            if (modified.getTime() === moditime.getTime()) {
-                this.status = 304;
+        const stats = fs.statSync(path);
+        if (this.request.headers['if-modified-since']) {
+            const modified = new Date(this.request.headers['if-modified-since']);
+            if (modified.getTime() === stats.mtime.getTime()) {
+                this.response.status = 304;
                 return;
             }
         }
         const etag = crypto.createHash(option.etagType || 'md5').update(fs.readFileSync(path)).digest('hex');
-        if (this.client.headers['If-None-Match']) {
-            if (option.etag) {
-                if (this.client.headers['If-None-Match'] === etag) {
-                    this.status = 304;
-                    return;
-                }
-            }
+        if (this.request.headers['if-none-match'] === etag) {
+            this.response.status = 304;
+            return;
         }
         this.setCache({
-            modified: fs.statSync(path).mtime,
-            etag,
-            maxAge: option.maxAge,
-            smaxAge: option.smaxAge,
-            cacheControl: 'public'
+            modified: stats.mtime, etag,
+            maxAge: option.maxAge, smaxAge: option.smaxAge, cacheControl: 'public'
         });
-        this.response(fs.createReadStream(path), 'stream');
+        this.respond(fs.createReadStream(path), 'stream');
     }
-    /**
-     * 发送普通文件
-     * @param path 文件路径
-     * @param isStream 是否流式传输
-     */
+    /** 直接发送文件 */
     sendFile(path, isStream = false) {
         if (isStream) {
             this.setMime('application/octet-stream');
-            this.response(fs.createReadStream(path), 'stream');
+            this.respond(fs.createReadStream(path), 'stream');
         }
         else {
-            this.response(fs.readFileSync(path), 'buffer');
+            this.respond(fs.readFileSync(path), 'buffer');
         }
     }
-    /**
-     * 渲染模板
-     * @template 模板字符串
-     * @data 数据
-     * @missing 缺失值处理方式，keep-template: 保留模板，keep-key: 保留键，remove: 移除
-     * @regex 模板匹配正则，默认为{{ xxx.xxx }}
-     */
-    render(template, data, missing = 'keep-template', regex = /\{\{\s*([\w.]+)\s*\}\}/g) {
-        const getValue = (obj, path) => {
-            return path.split('.').reduce((acc, key) => acc?.[key], obj);
-        };
-        return template.replace(regex, (_, key) => {
-            const value = getValue(data, key);
-            if (value !== undefined)
-                return String(value);
-            switch (missing) {
-                case 'keep-key':
-                    return key;
-                case 'remove':
-                    return '';
-                case 'keep-template':
-                default:
-                    return _;
-            }
-        });
-    }
-    /**
-     * 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.
-     */
+    /** 渲染组件视图 */
     async renderView(component, data = {}) {
-        if (!this.pluginContext) {
-            throw new Error(`Cannot call 'renderView' because the session is not associated with a plugin context.`);
-        }
-        const renderer = this.pluginContext.renderer || null;
-        const pluginName = this.pluginContext.pluginname;
+        if (!this.pluginContext)
+            throw new Error(`Plugin context missing.`);
+        const renderer = this.pluginContext.renderer;
         if (!renderer) {
-            this.server.core.logger.error(`Renderer declared by plugin "${pluginName}" is not registered. Have you installed the renderer package (e.g., '@yumerijs/vue-renderer')?`);
-            // throw new Error(`Renderer "${rendererName}" is not registered.`);
+            this.server.core.logger.error(`Renderer missing for ${this.pluginContext.pluginname}`);
+            return;
         }
-        const renderOptions = {
-            pluginName,
-        };
         try {
-            const html = await renderer.render(component, data, renderOptions);
+            const html = await renderer.render(component, data, { pluginName: this.pluginContext.pluginname });
             this.setMime('text/html');
-            this.response(html, 'plain');
+            this.respond(html, 'plain');
         }
         catch (error) {
-            this.server.core.logger.error(`Error while rendering view for plugin "${pluginName}":`, error);
+            this.server.core.logger.error(`Render error:`, error);
             throw error;
         }
     }
-    async renderFile(filePath, data) {
-        const renderer = this.pluginContext.renderer;
-        const pluginName = this.pluginContext.pluginname;
+    /** 渲染文件 */
+    async render(filePath, data) {
+        const renderer = this.pluginContext?.renderer;
         if (!renderer) {
-            this.server.core.logger.error(`Renderer declared by plugin "${pluginName}" is not registered. Have you installed the renderer package (e.g., '@yumerijs/vue-renderer')?`);
-            // throw new Error(`Renderer "${rendererName}" is not registered.`);
+            this.server.core.logger.error(`Renderer missing.`);
+            return;
         }
         try {
             const html = await renderer.renderFile(filePath, data);
             this.setMime('text/html');
-            this.response(html, 'plain');
+            this.respond(html, 'plain');
         }
         catch (error) {
-            this.server.core.logger.error(`Error while rendering file "${filePath}":`, error);
+            this.server.core.logger.error(`File render error:`, error);
             throw error;
         }
     }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@yumerijs/core",
-  "version": "2.2.2",
+  "version": "3.0.0-alpha.2",
   "description": "Core module for yumeri",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "type": "module",
   "files": [
     "dist"
   ],