mm_session 1.5.0 → 1.5.2

package/README.md

@@ -0,0 +1,263 @@
+# mm_session
+
+[English Documentation](./README_EN.md) | [中文文档](./README.md)
+
+## 概述
+
+`mm_session` 是一个专为 Koa.js 框架设计的轻量级 session 管理中间件。它提供了简单易用的 session 管理功能，支持自定义存储后端，适用于各种规模的 Web 应用。
+
+## 特性
+
+- ✅ **Koa 中间件标准** - 符合 `app.use(session.middleware())` 使用方式
+- ✅ **存储抽象层** - 支持自定义存储后端
+- ✅ **自动 session 管理** - 自动创建、保存、销毁 session
+- ✅ **Cookie 自动处理** - 自动设置和读取 session cookie
+- ✅ **安全 session ID** - 基于 IP + 时间戳 + AES 加密生成
+- ✅ **异步支持** - 完整的 async/await 支持
+- ✅ **轻量级** - 无冗余依赖，代码简洁
+
+## 安装
+
+```bash
+npm install mm_session
+```
+
+## 快速开始
+
+### 基本用法
+
+```javascript
+const Koa = require('koa');
+const { Session } = require('mm_session');
+
+const app = new Koa();
+
+// 创建 session 实例
+const session = new Session({
+  key: 'my_session',      // cookie 名称
+  max_age: 3600          // session 过期时间（秒）
+});
+
+// 注册中间件
+app.use(session.middleware());
+
+// 业务路由
+app.use(async (ctx) => {
+  // 设置 session 数据
+  if (!ctx.session.user_id) {
+    ctx.session.user_id = 123;
+    ctx.session.username = 'test_user';
+  }
+  
+  // 读取 session 数据
+  ctx.body = {
+    user_id: ctx.session.user_id,
+    username: ctx.session.username
+  };
+});
+
+app.listen(3000);
+```
+
+### 高级配置
+
+```javascript
+const { Session, Store } = require('mm_session');
+
+// 自定义配置
+const session = new Session({
+  key: 'app_session',           // cookie 键名
+  max_age: 7200,               // 过期时间：2小时
+  http_only: true,             // 仅 HTTP 访问
+  secure: process.env.NODE_ENV === 'production', // 生产环境 HTTPS
+  same_site: 'strict'          // 同站策略
+});
+
+// 自定义存储（可选）
+const customStore = new Store('custom_prefix');
+session.init(customStore);
+```
+
+## API 文档
+
+### Session 类
+
+#### 构造函数
+
+```javascript
+new Session(config)
+```
+
+**参数:**
+- `config` (Object) - 配置对象
+  - `key` (String) - session cookie 名称，默认: 'mm:uuid'
+  - `max_age` (Number) - session 过期时间（秒）
+  - 其他 cookie 配置选项
+
+#### 方法
+
+##### middleware()
+返回 Koa 中间件函数。
+
+```javascript
+app.use(session.middleware());
+```
+
+##### init(store)
+初始化自定义存储后端。
+
+```javascript
+session.init(new CustomStore());
+```
+
+### Store 类
+
+存储抽象类，支持自定义存储实现。
+
+```javascript
+const { Store } = require('mm_session');
+const store = new Store('prefix_');
+```
+
+## 配置选项
+
+### Session 配置
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| key | String | 'mm:uuid' | session cookie 名称 |
+| max_age | Number | - | session 过期时间（秒） |
+| http_only | Boolean | true | 仅 HTTP 访问 |
+| secure | Boolean | false | 仅 HTTPS 传输 |
+| same_site | String | 'lax' | 同站策略 |
+
+### Cookie 配置
+
+支持所有 [cookie](https://github.com/jshttp/cookie) 库的配置选项。
+
+## 存储后端
+
+### 默认存储
+默认使用 `mm_cachebase` 作为存储后端，支持内存和文件持久化。
+
+### 自定义存储
+可以实现自定义存储类，只需实现以下接口：
+
+```javascript
+class CustomStore {
+  async get(sessionId) {}
+  async set(sessionData, options, ctx) {}
+  async destroy(sessionId, ctx) {}
+  async getID(ctx) {}
+}
+```
+
+## 示例应用
+
+### 用户登录系统
+
+```javascript
+const session = new Session({
+  key: 'user_session',
+  max_age: 86400 // 24小时
+});
+
+app.use(session.middleware());
+
+// 登录路由
+app.use(async (ctx, next) => {
+  if (ctx.path === '/login' && ctx.method === 'POST') {
+    const { username, password } = ctx.request.body;
+    
+    // 验证用户（示例）
+    if (username === 'admin' && password === 'password') {
+      ctx.session.user = {
+        id: 1,
+        username: 'admin',
+        role: 'administrator'
+      };
+      ctx.body = { success: true };
+    } else {
+      ctx.body = { success: false, error: '认证失败' };
+    }
+  } else {
+    await next();
+  }
+});
+
+// 需要认证的路由
+app.use(async (ctx, next) => {
+  if (!ctx.session.user) {
+    ctx.status = 401;
+    ctx.body = { error: '请先登录' };
+    return;
+  }
+  await next();
+});
+```
+
+## 测试
+
+```bash
+# 运行测试
+npm test
+
+# 或直接运行
+node test.js
+```
+
+## 开发
+
+### 代码规范
+
+项目使用 ESLint 进行代码规范检查：
+
+```bash
+# 检查代码规范
+npx eslint lib/session.js
+
+# 自动修复
+npx eslint lib/session.js --fix
+```
+
+### 项目结构
+
+```
+mm_session/
+├── lib/
+│   ├── session.js     # Session 类实现
+│   └── store.js       # Store 类实现
+├── index.js           # 模块入口
+├── test.js            # 测试文件
+├── eslint.config.js   # ESLint 配置
+└── package.json       # 项目配置
+```
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+ISC License
+
+## 作者
+
+邱文武
+
+## 更新日志
+
+### v1.5.1
+- 修复 session 保存逻辑
+- 优化 cookie 设置机制
+- 改进测试用例
+
+### v1.5.0
+- 重构为类+原型函数模式
+- 符合 Koa 中间件标准使用方式
+- 增强代码可维护性
+
+## 相关项目
+
+- [mm_cachebase](https://www.npmjs.com/package/mm_cachebase) - 缓存基础库
+- [mm_eslint](https://www.npmjs.com/package/mm_eslint) - ESLint 配置

package/README_EN.md

@@ -0,0 +1,263 @@
+# mm_session
+
+[English Documentation](README_EN.md) | [中文文档](README.md)
+
+## Overview
+
+`mm_session` is a lightweight session management middleware designed specifically for the Koa.js framework. It provides simple and easy-to-use session management functionality with support for custom storage backends, suitable for web applications of all sizes.
+
+## Features
+
+- ✅ **Koa Middleware Standard** - Compatible with `app.use(session.middleware())` usage
+- ✅ **Storage Abstraction Layer** - Supports custom storage backends
+- ✅ **Automatic Session Management** - Automatic session creation, saving, and destruction
+- ✅ **Cookie Auto-handling** - Automatic session cookie setting and reading
+- ✅ **Secure Session ID** - Generated based on IP + timestamp + AES encryption
+- ✅ **Async Support** - Full async/await support
+- ✅ **Lightweight** - No redundant dependencies, clean codebase
+
+## Installation
+
+```bash
+npm install mm_session
+```
+
+## Quick Start
+
+### Basic Usage
+
+```javascript
+const Koa = require('koa');
+const { Session } = require('mm_session');
+
+const app = new Koa();
+
+// Create session instance
+const session = new Session({
+  key: 'my_session',      // cookie name
+  max_age: 3600          // session expiration time (seconds)
+});
+
+// Register middleware
+app.use(session.middleware());
+
+// Business routes
+app.use(async (ctx) => {
+  // Set session data
+  if (!ctx.session.user_id) {
+    ctx.session.user_id = 123;
+    ctx.session.username = 'test_user';
+  }
+  
+  // Read session data
+  ctx.body = {
+    user_id: ctx.session.user_id,
+    username: ctx.session.username
+  };
+});
+
+app.listen(3000);
+```
+
+### Advanced Configuration
+
+```javascript
+const { Session, Store } = require('mm_session');
+
+// Custom configuration
+const session = new Session({
+  key: 'app_session',           // cookie key name
+  max_age: 7200,               // expiration time: 2 hours
+  http_only: true,             // HTTP-only access
+  secure: process.env.NODE_ENV === 'production', // HTTPS in production
+  same_site: 'strict'          // same-site policy
+});
+
+// Custom storage (optional)
+const customStore = new Store('custom_prefix');
+session.init(customStore);
+```
+
+## API Documentation
+
+### Session Class
+
+#### Constructor
+
+```javascript
+new Session(config)
+```
+
+**Parameters:**
+- `config` (Object) - Configuration object
+  - `key` (String) - Session cookie name, default: 'mm:uuid'
+  - `max_age` (Number) - Session expiration time (seconds)
+  - Other cookie configuration options
+
+#### Methods
+
+##### middleware()
+Returns Koa middleware function.
+
+```javascript
+app.use(session.middleware());
+```
+
+##### init(store)
+Initialize custom storage backend.
+
+```javascript
+session.init(new CustomStore());
+```
+
+### Store Class
+
+Storage abstraction class supporting custom storage implementations.
+
+```javascript
+const { Store } = require('mm_session');
+const store = new Store('prefix_');
+```
+
+## Configuration Options
+
+### Session Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| key | String | 'mm:uuid' | Session cookie name |
+| max_age | Number | - | Session expiration time (seconds) |
+| http_only | Boolean | true | HTTP-only access |
+| secure | Boolean | false | HTTPS-only transmission |
+| same_site | String | 'lax' | Same-site policy |
+
+### Cookie Configuration
+
+Supports all [cookie](https://github.com/jshttp/cookie) library configuration options.
+
+## Storage Backends
+
+### Default Storage
+Uses `mm_cachebase` as the default storage backend, supporting both memory and file persistence.
+
+### Custom Storage
+You can implement custom storage classes by implementing the following interface:
+
+```javascript
+class CustomStore {
+  async get(sessionId) {}
+  async set(sessionData, options, ctx) {}
+  async destroy(sessionId, ctx) {}
+  async getID(ctx) {}
+}
+```
+
+## Example Applications
+
+### User Login System
+
+```javascript
+const session = new Session({
+  key: 'user_session',
+  max_age: 86400 // 24 hours
+});
+
+app.use(session.middleware());
+
+// Login route
+app.use(async (ctx, next) => {
+  if (ctx.path === '/login' && ctx.method === 'POST') {
+    const { username, password } = ctx.request.body;
+    
+    // User authentication (example)
+    if (username === 'admin' && password === 'password') {
+      ctx.session.user = {
+        id: 1,
+        username: 'admin',
+        role: 'administrator'
+      };
+      ctx.body = { success: true };
+    } else {
+      ctx.body = { success: false, error: 'Authentication failed' };
+    }
+  } else {
+    await next();
+  }
+});
+
+// Routes requiring authentication
+app.use(async (ctx, next) => {
+  if (!ctx.session.user) {
+    ctx.status = 401;
+    ctx.body = { error: 'Please login first' };
+    return;
+  }
+  await next();
+});
+```
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Or run directly
+node test.js
+```
+
+## Development
+
+### Code Style
+
+The project uses ESLint for code style checking:
+
+```bash
+# Check code style
+npx eslint lib/session.js
+
+# Auto-fix issues
+npx eslint lib/session.js --fix
+```
+
+### Project Structure
+
+```
+mm_session/
+├── lib/
+│   ├── session.js     # Session class implementation
+│   └── store.js       # Store class implementation
+├── index.js           # Module entry point
+├── test.js            # Test file
+├── eslint.config.js   # ESLint configuration
+└── package.json       # Project configuration
+```
+
+## Contributing
+
+Issues and Pull Requests are welcome!
+
+## License
+
+ISC License
+
+## Author
+
+Qiu Wenwu
+
+## Changelog
+
+### v1.5.1
+- Fixed session saving logic
+- Optimized cookie setting mechanism
+- Improved test cases
+
+### v1.5.0
+- Refactored to class + prototype function pattern
+- Compatible with Koa middleware standard usage
+- Enhanced code maintainability
+
+## Related Projects
+
+- [mm_cachebase](https://www.npmjs.com/package/mm_cachebase) - Cache base library
+- [mm_eslint](https://www.npmjs.com/package/mm_eslint) - ESLint configuration