@onebots/core 1.0.0 → 1.0.4

package/lib/metrics.js

@@ -0,0 +1,201 @@
+/**
+ * 性能指标收集系统
+ * 收集请求数、响应时间、错误率等指标
+ */
+import { createLogger } from './logger.js';
+const logger = createLogger('Metrics');
+/**
+ * 指标收集器
+ */
+export class MetricsCollector {
+    metrics = new Map();
+    maxSamples = 1000; // 每个指标最多保留的样本数
+    /**
+     * 增加计数器
+     */
+    increment(name, value = 1, labels) {
+        const metric = this.getOrCreateMetric(name, 'counter', labels);
+        const lastValue = metric.values[metric.values.length - 1];
+        const newValue = (lastValue?.value || 0) + value;
+        metric.values.push({
+            value: newValue,
+            timestamp: Date.now(),
+            labels,
+        });
+        this.trimSamples(metric);
+    }
+    /**
+     * 设置仪表值
+     */
+    set(name, value, labels) {
+        const metric = this.getOrCreateMetric(name, 'gauge', labels);
+        metric.values.push({
+            value,
+            timestamp: Date.now(),
+            labels,
+        });
+        this.trimSamples(metric);
+    }
+    /**
+     * 记录直方图值
+     */
+    observe(name, value, labels) {
+        const metric = this.getOrCreateMetric(name, 'histogram', labels);
+        metric.values.push({
+            value,
+            timestamp: Date.now(),
+            labels,
+        });
+        this.trimSamples(metric);
+    }
+    /**
+     * 获取或创建指标
+     */
+    getOrCreateMetric(name, type, labels) {
+        const key = this.getMetricKey(name, labels);
+        if (!this.metrics.has(key)) {
+            this.metrics.set(key, {
+                name,
+                type,
+                help: `${name} metric`,
+                values: [],
+                labels,
+            });
+        }
+        return this.metrics.get(key);
+    }
+    /**
+     * 获取指标键
+     */
+    getMetricKey(name, labels) {
+        if (!labels || Object.keys(labels).length === 0) {
+            return name;
+        }
+        const labelStr = Object.entries(labels)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${k}="${v}"`)
+            .join(',');
+        return `${name}{${labelStr}}`;
+    }
+    /**
+     * 修剪样本数量
+     */
+    trimSamples(metric) {
+        if (metric.values.length > this.maxSamples) {
+            metric.values = metric.values.slice(-this.maxSamples);
+        }
+    }
+    /**
+     * 获取指标
+     */
+    getMetric(name, labels) {
+        const key = this.getMetricKey(name, labels);
+        return this.metrics.get(key);
+    }
+    /**
+     * 获取所有指标
+     */
+    getAllMetrics() {
+        return Array.from(this.metrics.values());
+    }
+    /**
+     * 获取最新值
+     */
+    getLatestValue(name, labels) {
+        const metric = this.getMetric(name, labels);
+        if (!metric || metric.values.length === 0) {
+            return undefined;
+        }
+        return metric.values[metric.values.length - 1].value;
+    }
+    /**
+     * 计算平均值
+     */
+    getAverage(name, labels, windowMs) {
+        const metric = this.getMetric(name, labels);
+        if (!metric || metric.values.length === 0) {
+            return undefined;
+        }
+        const now = Date.now();
+        const cutoff = windowMs ? now - windowMs : 0;
+        const relevantValues = metric.values.filter(v => v.timestamp >= cutoff);
+        if (relevantValues.length === 0) {
+            return undefined;
+        }
+        const sum = relevantValues.reduce((acc, v) => acc + v.value, 0);
+        return sum / relevantValues.length;
+    }
+    /**
+     * 计算总和
+     */
+    getSum(name, labels, windowMs) {
+        const metric = this.getMetric(name, labels);
+        if (!metric || metric.values.length === 0) {
+            return undefined;
+        }
+        const now = Date.now();
+        const cutoff = windowMs ? now - windowMs : 0;
+        const relevantValues = metric.values.filter(v => v.timestamp >= cutoff);
+        if (relevantValues.length === 0) {
+            return undefined;
+        }
+        return relevantValues.reduce((acc, v) => acc + v.value, 0);
+    }
+    /**
+     * 导出为 Prometheus 格式
+     */
+    exportPrometheus() {
+        const lines = [];
+        const processed = new Set();
+        for (const metric of this.metrics.values()) {
+            const baseKey = metric.name;
+            if (processed.has(baseKey)) {
+                continue;
+            }
+            processed.add(baseKey);
+            // 添加 HELP 和 TYPE
+            lines.push(`# HELP ${baseKey} ${metric.help}`);
+            lines.push(`# TYPE ${baseKey} ${metric.type}`);
+            // 添加所有相同名称的指标值
+            for (const m of this.metrics.values()) {
+                if (m.name === baseKey) {
+                    const labelStr = m.labels && Object.keys(m.labels).length > 0
+                        ? `{${Object.entries(m.labels).map(([k, v]) => `${k}="${v}"`).join(',')}}`
+                        : '';
+                    const latestValue = m.values[m.values.length - 1];
+                    if (latestValue) {
+                        lines.push(`${baseKey}${labelStr} ${latestValue.value}`);
+                    }
+                }
+            }
+        }
+        return lines.join('\n') + '\n';
+    }
+    /**
+     * 清理过期数据
+     */
+    cleanup(maxAge = 3600000) {
+        const now = Date.now();
+        const cutoff = now - maxAge;
+        for (const metric of this.metrics.values()) {
+            metric.values = metric.values.filter(v => v.timestamp >= cutoff);
+            // 如果指标没有值了，删除它
+            if (metric.values.length === 0) {
+                this.metrics.delete(this.getMetricKey(metric.name, metric.labels));
+            }
+        }
+    }
+    /**
+     * 重置所有指标
+     */
+    reset() {
+        this.metrics.clear();
+        logger.info('All metrics reset');
+    }
+}
+// 全局指标收集器实例
+export const metrics = new MetricsCollector();
+// 定期清理过期数据（每 10 分钟）
+setInterval(() => {
+    metrics.cleanup();
+}, 10 * 60 * 1000);

package/lib/middleware/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 中间件统一导出
+ */
+export { createRateLimit, defaultRateLimit } from './rate-limit.js';
+export { initSecurityAudit, securityAudit, logAuthFailure, logInvalidToken, logSuspiciousRequest, logRateLimit, closeSecurityAudit, } from './security-audit.js';
+export { createTokenValidator, createConfigTokenValidator, createHMACValidator, createManagedTokenValidator, combineValidators, } from './token-validator.js';
+export { metricsCollector } from './metrics-collector.js';
+export { TokenManager, initTokenManager, getTokenManager, type TokenInfo, type TokenManagerOptions, } from './token-manager.js';

package/lib/middleware/index.js

@@ -0,0 +1,8 @@
+/**
+ * 中间件统一导出
+ */
+export { createRateLimit, defaultRateLimit } from './rate-limit.js';
+export { initSecurityAudit, securityAudit, logAuthFailure, logInvalidToken, logSuspiciousRequest, logRateLimit, closeSecurityAudit, } from './security-audit.js';
+export { createTokenValidator, createConfigTokenValidator, createHMACValidator, createManagedTokenValidator, combineValidators, } from './token-validator.js';
+export { metricsCollector } from './metrics-collector.js';
+export { TokenManager, initTokenManager, getTokenManager, } from './token-manager.js';

package/lib/middleware/metrics-collector.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 性能指标收集中间件
+ * 自动收集请求数、响应时间、错误率等指标
+ */
+import type { Context, Next } from 'koa';
+/**
+ * 性能指标收集中间件
+ */
+export declare function metricsCollector(): (ctx: Context, next: Next) => Promise<void>;

package/lib/middleware/metrics-collector.js

@@ -0,0 +1,64 @@
+/**
+ * 性能指标收集中间件
+ * 自动收集请求数、响应时间、错误率等指标
+ */
+import { metrics } from '../metrics.js';
+/**
+ * 性能指标收集中间件
+ */
+export function metricsCollector() {
+    return async (ctx, next) => {
+        const startTime = Date.now();
+        const method = ctx.method;
+        const path = ctx.path;
+        // 增加请求计数
+        metrics.increment('http_requests_total', 1, {
+            method,
+            path: path.split('?')[0], // 移除查询参数
+        });
+        try {
+            await next();
+            const duration = Date.now() - startTime;
+            const status = ctx.status;
+            // 记录响应时间
+            metrics.observe('http_request_duration_ms', duration, {
+                method,
+                path: path.split('?')[0],
+                status: String(status),
+            });
+            // 记录状态码
+            metrics.increment('http_responses_total', 1, {
+                method,
+                path: path.split('?')[0],
+                status: String(status),
+            });
+            // 记录错误
+            if (status >= 400) {
+                metrics.increment('http_errors_total', 1, {
+                    method,
+                    path: path.split('?')[0],
+                    status: String(status),
+                });
+            }
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const status = ctx.status || 500;
+            // 记录错误响应时间
+            metrics.observe('http_request_duration_ms', duration, {
+                method,
+                path: path.split('?')[0],
+                status: String(status),
+                error: 'true',
+            });
+            // 记录错误
+            metrics.increment('http_errors_total', 1, {
+                method,
+                path: path.split('?')[0],
+                status: String(status),
+                error_type: error.name || 'Unknown',
+            });
+            throw error;
+        }
+    };
+}

package/lib/middleware/rate-limit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 速率限制中间件
+ * 防止 API 滥用，保护服务器资源
+ */
+import type { Context, Next } from 'koa';
+interface RateLimitConfig {
+    /** 时间窗口（毫秒） */
+    windowMs: number;
+    /** 每个 IP 在时间窗口内的最大请求数 */
+    max: number;
+    /** 是否跳过成功请求（只限制失败请求） */
+    skipSuccessfulRequests?: boolean;
+    /** 是否跳过失败请求（只限制成功请求） */
+    skipFailedRequests?: boolean;
+    /** 自定义键生成函数 */
+    keyGenerator?: (ctx: Context) => string;
+    /** 跳过函数 */
+    skip?: (ctx: Context) => boolean;
+    /** 自定义错误消息 */
+    message?: string;
+    /** 自定义状态码 */
+    statusCode?: number;
+}
+/**
+ * 创建速率限制中间件
+ */
+export declare function createRateLimit(config: RateLimitConfig): (ctx: Context, next: Next) => Promise<any>;
+/**
+ * 默认速率限制配置
+ */
+export declare const defaultRateLimit: (ctx: Context, next: Next) => Promise<any>;
+export {};

package/lib/middleware/rate-limit.js

@@ -0,0 +1,149 @@
+/**
+ * 速率限制中间件
+ * 防止 API 滥用，保护服务器资源
+ */
+import { createLogger } from '../logger.js';
+import { logRateLimit } from './security-audit.js';
+/**
+ * 速率限制存储（内存实现）
+ * 生产环境建议使用 Redis
+ */
+class MemoryStore {
+    store = {};
+    cleanupInterval;
+    constructor() {
+        // 每 5 分钟清理一次过期记录
+        this.cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            for (const key in this.store) {
+                if (this.store[key].resetTime < now) {
+                    delete this.store[key];
+                }
+            }
+        }, 5 * 60 * 1000);
+    }
+    /**
+     * 获取当前计数
+     */
+    get(key) {
+        const record = this.store[key];
+        if (!record) {
+            return null;
+        }
+        // 如果已过期，删除记录
+        if (record.resetTime < Date.now()) {
+            delete this.store[key];
+            return null;
+        }
+        return record;
+    }
+    /**
+     * 增加计数
+     */
+    increment(key, windowMs) {
+        const now = Date.now();
+        const record = this.store[key];
+        if (!record || record.resetTime < now) {
+            // 创建新记录
+            this.store[key] = {
+                count: 1,
+                resetTime: now + windowMs,
+            };
+            return this.store[key];
+        }
+        // 增加计数
+        record.count++;
+        return record;
+    }
+    /**
+     * 重置计数
+     */
+    reset(key) {
+        delete this.store[key];
+    }
+    /**
+     * 清理所有记录
+     */
+    cleanup() {
+        this.store = {};
+    }
+    /**
+     * 销毁存储
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+        }
+        this.cleanup();
+    }
+}
+/**
+ * 创建速率限制中间件
+ */
+export function createRateLimit(config) {
+    const logger = createLogger('RateLimit');
+    const store = new MemoryStore();
+    const { windowMs = 60 * 1000, // 默认 1 分钟
+    max = 100, // 默认 100 次请求
+    skipSuccessfulRequests = false, skipFailedRequests = false, keyGenerator = (ctx) => {
+        // 默认使用 IP 地址作为键
+        return ctx.ip || ctx.request.ip || 'unknown';
+    }, skip = () => false, message = 'Too many requests, please try again later.', statusCode = 429, } = config;
+    return async (ctx, next) => {
+        // 检查是否跳过
+        if (skip(ctx)) {
+            return next();
+        }
+        // 生成键
+        const key = keyGenerator(ctx);
+        // 获取当前记录
+        const record = store.get(key);
+        if (record) {
+            // 检查是否超过限制
+            if (record.count >= max) {
+                logger.warn('Rate limit exceeded', {
+                    key,
+                    count: record.count,
+                    max,
+                    path: ctx.path,
+                    method: ctx.method,
+                });
+                // 记录安全审计日志
+                logRateLimit(ctx, key, record.count, max);
+                ctx.status = statusCode;
+                ctx.body = {
+                    error: 'RateLimitExceeded',
+                    message,
+                    retryAfter: Math.ceil((record.resetTime - Date.now()) / 1000),
+                };
+                // 设置响应头
+                ctx.set('X-RateLimit-Limit', String(max));
+                ctx.set('X-RateLimit-Remaining', '0');
+                ctx.set('X-RateLimit-Reset', String(Math.ceil(record.resetTime / 1000)));
+                ctx.set('Retry-After', String(Math.ceil((record.resetTime - Date.now()) / 1000)));
+                return;
+            }
+        }
+        // 执行下一个中间件
+        await next();
+        // 根据配置决定是否记录
+        const shouldSkip = (skipSuccessfulRequests && ctx.status < 400) ||
+            (skipFailedRequests && ctx.status >= 400);
+        if (!shouldSkip) {
+            // 增加计数
+            const newRecord = store.increment(key, windowMs);
+            // 设置响应头
+            ctx.set('X-RateLimit-Limit', String(max));
+            ctx.set('X-RateLimit-Remaining', String(Math.max(0, max - newRecord.count)));
+            ctx.set('X-RateLimit-Reset', String(Math.ceil(newRecord.resetTime / 1000)));
+        }
+    };
+}
+/**
+ * 默认速率限制配置
+ */
+export const defaultRateLimit = createRateLimit({
+    windowMs: 60 * 1000, // 1 分钟
+    max: 100, // 100 次请求
+    message: 'Too many requests, please try again later.',
+});

package/lib/middleware/security-audit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 安全审计日志中间件
+ * 记录所有安全相关事件
+ */
+import type { Context, Next } from 'koa';
+/**
+ * 初始化安全审计日志
+ */
+export declare function initSecurityAudit(auditLogDir: string): void;
+/**
+ * 安全审计中间件
+ */
+export declare function securityAudit(): (ctx: Context, next: Next) => Promise<any>;
+/**
+ * 记录认证失败
+ */
+export declare function logAuthFailure(ctx: Context, reason: string): void;
+/**
+ * 记录无效令牌
+ */
+export declare function logInvalidToken(ctx: Context, token?: string): void;
+/**
+ * 记录可疑请求
+ */
+export declare function logSuspiciousRequest(ctx: Context, reason: string, details?: Record<string, any>): void;
+/**
+ * 记录速率限制触发
+ */
+export declare function logRateLimit(ctx: Context, key: string, count: number, max: number): void;
+/**
+ * 关闭审计日志
+ */
+export declare function closeSecurityAudit(): void;