befly 3.17.0 → 3.17.2

package/lib/emailHelper.js

@@ -0,0 +1,110 @@
+/**
+ * 邮件发送工具类 - JavaScript 版本
+ */
+
+import { Logger } from "./logger.js";
+
+/**
+ * 邮件发送工具类
+ */
+export class EmailHelper {
+    /**
+     * 创建 EmailHelper 实例
+     * @param config - 邮件配置
+     */
+    constructor(config) {
+        this.config = config;
+    }
+
+    /**
+     * 发送邮件
+     * @param options - 邮件选项
+     * @returns 是否发送成功
+     */
+    async send(options) {
+        const config = this.getConfig();
+
+        if (!config || !config.host || !config.user) {
+            Logger.warn("邮件未配置，已禁用发送");
+            return false;
+        }
+
+        try {
+            const result = await this.doSend(config, options);
+            if (result.success) {
+                return true;
+            }
+
+            Logger.warn("发送邮件失败", { err: result.error });
+            return false;
+        } catch (error) {
+            Logger.error("发送邮件异常", error);
+            return false;
+        }
+    }
+
+    /**
+     * 获取邮件配置
+     * @returns 完整配置
+     */
+    getConfig() {
+        if (!this.config) {
+            return null;
+        }
+
+        const result = Object.assign({}, this.config);
+        result.pass = this.config.pass || process.env.SMTP_PASS;
+        result.ssl = Boolean(this.config.ssl);
+        return result;
+    }
+
+    /**
+     * 实际发送邮件
+     * @param config - 邮件配置
+     * @param options - 邮件选项
+     * @returns 发送结果
+     */
+    async doSend(config, options) {
+        let emailService;
+
+        try {
+            // 动态加载 emailjs
+            const emailjs = await import("emailjs");
+            emailService = emailjs.server.connect({
+                user: config.user,
+                password: config.pass,
+                host: config.host,
+                port: config.port || 25,
+                ssl: config.ssl,
+                timeout: config.timeout || 10000
+            });
+        } catch (error) {
+            return { success: false, error: error };
+        }
+
+        try {
+            await emailService.send({
+                text: options.text || options.html,
+                from: options.from || config.from || config.user,
+                to: options.to,
+                cc: options.cc,
+                bcc: options.bcc,
+                subject: options.subject,
+                attachment: options.attachments
+            });
+
+            return { success: true };
+        } catch (error) {
+            return { success: false, error: error };
+        }
+    }
+}
+
+/**
+ * 创建邮件工具实例
+ * @param config - 邮件配置
+ * @returns EmailHelper 实例
+ */
+export function createEmailHelper(config) {
+    return new EmailHelper(config);
+}

package/lib/logger.js

@@ -0,0 +1,604 @@
+/**
+ * 日志系统 - Bun 环境自定义实现（替换 pino / pino-roll）
+ */
+
+import { createWriteStream, existsSync, mkdirSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { isAbsolute as nodePathIsAbsolute, join as nodePathJoin, resolve as nodePathResolve } from "node:path";
+
+import { formatYmdHms } from "../utils/formatYmdHms.js";
+import { buildSensitiveKeyMatcher, sanitizeLogObject } from "../utils/loggerUtils.js";
+import { isFiniteNumber, isNumber, isPlainObject, isString } from "../utils/is.js";
+import { normalizePositiveInt } from "../utils/util.js";
+
+// 注意：Logger 可能在运行时/测试中被 process.chdir() 影响。
+// 为避免相对路径的 logs 目录随着 cwd 变化，使用模块加载时的初始 cwd 作为锚点。
+const INITIAL_CWD = process.cwd();
+const RUNTIME_LOG_DIR = nodePathResolve(INITIAL_CWD, "logs");
+
+const BUILTIN_SENSITIVE_KEYS = ["*password*", "pass", "pwd", "*token*", "access_token", "refresh_token", "accessToken", "refreshToken", "authorization", "cookie", "set-cookie", "*secret*", "apiKey", "api_key", "privateKey", "private_key"];
+
+let sanitizeOptions = {
+    maxStringLen: 200,
+    maxArrayItems: 500,
+    sanitizeDepth: 5,
+    sanitizeNodes: 5000,
+    sanitizeObjectKeys: 500,
+    sensitiveKeyMatcher: buildSensitiveKeyMatcher({ builtinPatterns: BUILTIN_SENSITIVE_KEYS, userPatterns: [] })
+};
+
+function buildSanitizeOptionsForWriteOptions(writeOptions) {
+    if (!writeOptions || writeOptions.truncate !== false) return sanitizeOptions;
+
+    // 仅关闭“截断”，仍保留敏感字段掩码与结构化清洗（避免泄露敏感信息）。
+    return {
+        maxStringLen: 200000,
+        maxArrayItems: 5000,
+        sanitizeDepth: sanitizeOptions.sanitizeDepth,
+        sanitizeNodes: sanitizeOptions.sanitizeNodes,
+        sanitizeObjectKeys: sanitizeOptions.sanitizeObjectKeys,
+        sensitiveKeyMatcher: sanitizeOptions.sensitiveKeyMatcher
+    };
+}
+
+let mockInstance = null;
+
+let appFileSink = null;
+let errorFileSink = null;
+
+let config = {
+    debug: 0,
+    dir: RUNTIME_LOG_DIR,
+    maxSize: 20,
+    runtimeEnv: "production"
+};
+
+function safeWriteStderr(msg) {
+    try {
+        process.stderr.write(`${msg}\n`);
+    } catch {
+        // ignore
+    }
+}
+
+function shiftBatchFromPending(pending, maxBatchBytes) {
+    const parts = [];
+    let bytes = 0;
+
+    while (pending.length > 0) {
+        const next = pending[0];
+        const nextBytes = Buffer.byteLength(next);
+        if (parts.length > 0 && bytes + nextBytes > maxBatchBytes) {
+            break;
+        }
+        parts.push(next);
+        bytes = bytes + nextBytes;
+        pending.shift();
+    }
+
+    return { chunk: parts.join(""), bytes: bytes };
+}
+
+class LogFileSink {
+    constructor(options) {
+        this.prefix = options.prefix;
+        this.maxFileBytes = options.maxFileBytes;
+
+        this.stream = null;
+        this.streamDate = "";
+        this.streamIndex = 0;
+        this.streamSizeBytes = 0;
+        this.disabled = false;
+
+        this.pending = [];
+        this.pendingBytes = 0;
+        this.scheduledTimer = null;
+        this.flushing = false;
+
+        this.maxBufferBytes = 10 * 1024 * 1024;
+        this.flushDelayMs = 10;
+        this.maxBatchBytes = 64 * 1024;
+    }
+
+    enqueue(line) {
+        if (this.disabled) return;
+
+        const bytes = Buffer.byteLength(line);
+        if (this.pendingBytes + bytes > this.maxBufferBytes) {
+            // buffer 满：统一丢弃新日志（不区分 level）
+            return;
+        }
+
+        this.pending.push(line);
+        this.pendingBytes = this.pendingBytes + bytes;
+
+        this.scheduleFlush();
+    }
+
+    async flushNow() {
+        this.cancelScheduledFlush();
+        await this.flush();
+    }
+
+    async shutdown() {
+        this.cancelScheduledFlush();
+        await this.flush();
+        await this.closeStream();
+    }
+
+    scheduleFlush() {
+        if (this.scheduledTimer) return;
+
+        this.scheduledTimer = setTimeout(() => {
+            // timer 触发时先清空句柄，避免 flush 内再次 schedule 时被认为“已安排”。
+            this.scheduledTimer = null;
+            void this.flush();
+        }, this.flushDelayMs);
+    }
+
+    cancelScheduledFlush() {
+        if (!this.scheduledTimer) return;
+        clearTimeout(this.scheduledTimer);
+        this.scheduledTimer = null;
+    }
+
+    async flush() {
+        if (this.flushing) return;
+        this.flushing = true;
+
+        try {
+            while (this.pending.length > 0) {
+                const batch = shiftBatchFromPending(this.pending, this.maxBatchBytes);
+                const chunk = batch.chunk;
+                const chunkBytes = Buffer.byteLength(chunk);
+                this.pendingBytes = this.pendingBytes - chunkBytes;
+
+                const ok = await this.writeChunk(chunk, chunkBytes);
+                if (!ok) {
+                    // writer 已禁用/失败：清空剩余 pending
+                    this.pending = [];
+                    this.pendingBytes = 0;
+                    break;
+                }
+            }
+        } finally {
+            this.flushing = false;
+            if (this.pending.length > 0) {
+                this.scheduleFlush();
+            }
+        }
+    }
+
+    async writeChunk(chunk, chunkBytes) {
+        if (this.disabled) return false;
+
+        try {
+            await this.ensureStreamReady(chunkBytes);
+            if (!this.stream) {
+                // 文件 sink 已被禁用或打开失败
+                return false;
+            }
+
+            const ok = this.stream.write(chunk);
+            if (!ok) {
+                await new Promise((resolve) => {
+                    const stream = this.stream;
+                    if (!stream) {
+                        resolve();
+                        return;
+                    }
+                    stream.once("drain", () => resolve());
+                });
+            }
+            this.streamSizeBytes = this.streamSizeBytes + chunkBytes;
+            return true;
+        } catch (error) {
+            safeWriteStderr(`[Logger] file sink flush error (${this.prefix}): ${error?.message || error}`);
+            this.disabled = true;
+            await this.closeStream();
+            return false;
+        }
+    }
+
+    async closeStream() {
+        if (!this.stream) return;
+        const st = this.stream;
+        this.stream = null;
+
+        await new Promise((resolve) => {
+            try {
+                st.end(() => resolve());
+            } catch {
+                resolve();
+            }
+        });
+    }
+
+    openStream(filePath) {
+        try {
+            this.stream = createWriteStream(filePath, { flags: "a" });
+            this.stream.on("error", (error) => {
+                safeWriteStderr(`[Logger] file sink error (${this.prefix}): ${error?.message || error}`);
+                this.disabled = true;
+                void this.closeStream();
+            });
+        } catch (error) {
+            safeWriteStderr(`[Logger] createWriteStream failed (${this.prefix}): ${error?.message || error}`);
+            this.disabled = true;
+            this.stream = null;
+        }
+    }
+
+    getFilePath(date, index) {
+        const suffix = index > 0 ? `.${index}` : "";
+        const filename = this.prefix === "app" ? `${date}${suffix}.log` : `${this.prefix}.${date}${suffix}.log`;
+        return nodePathJoin(RUNTIME_LOG_DIR, filename);
+    }
+
+    async ensureStreamReady(nextChunkBytes) {
+        const date = formatYmdHms(Reflect.construct(Date, []), "date");
+
+        // 日期变化：切新文件
+        if (this.stream && this.streamDate && date !== this.streamDate) {
+            await this.closeStream();
+            this.streamDate = "";
+            this.streamIndex = 0;
+            this.streamSizeBytes = 0;
+        }
+
+        // 首次打开
+        if (!this.stream) {
+            const filePath = this.getFilePath(date, 0);
+            let size = 0;
+            try {
+                const st = await stat(filePath);
+                size = isNumber(st.size) ? st.size : 0;
+            } catch {
+                size = 0;
+            }
+
+            this.streamDate = date;
+            this.streamIndex = 0;
+            this.streamSizeBytes = size;
+
+            this.openStream(filePath);
+            if (!this.stream) return;
+        }
+
+        // 大小滚动
+        if (this.stream && this.maxFileBytes > 0 && this.streamSizeBytes + nextChunkBytes > this.maxFileBytes) {
+            await this.closeStream();
+            this.streamIndex = this.streamIndex + 1;
+            const filePath = this.getFilePath(date, this.streamIndex);
+            this.streamDate = date;
+            this.streamSizeBytes = 0;
+
+            this.openStream(filePath);
+            if (!this.stream) return;
+        }
+    }
+}
+
+export async function flush() {
+    // 测试场景：mock logger 不需要 flush
+    if (mockInstance) return;
+
+    const sinks = [];
+    if (appFileSink) sinks.push({ flush: () => (appFileSink ? appFileSink.flushNow() : Promise.resolve()) });
+    if (errorFileSink) sinks.push({ flush: () => (errorFileSink ? errorFileSink.flushNow() : Promise.resolve()) });
+
+    for (const item of sinks) {
+        try {
+            await item.flush();
+        } catch {
+            // ignore
+        }
+    }
+}
+
+export async function shutdown() {
+    // 测试场景：mock logger 不需要 shutdown
+    if (mockInstance) return;
+
+    // 重要：shutdown 可能与后续 Logger 调用并发。
+    // 因此这里捕获“当前的旧 sink/instance 快照”，只关闭这些快照，避免把新创建的 sink 一并清掉。
+    const currentAppFileSink = appFileSink;
+    const currentErrorFileSink = errorFileSink;
+
+    const sinks = [];
+    if (currentAppFileSink) sinks.push({ shutdown: () => currentAppFileSink.shutdown() });
+    if (currentErrorFileSink) sinks.push({ shutdown: () => currentErrorFileSink.shutdown() });
+
+    for (const item of sinks) {
+        try {
+            await item.shutdown();
+        } catch {
+            // ignore
+        }
+    }
+
+    if (appFileSink === currentAppFileSink) {
+        appFileSink = null;
+    }
+    if (errorFileSink === currentErrorFileSink) {
+        errorFileSink = null;
+    }
+
+    // shutdown 后允许下一次重新初始化时再次校验/创建目录（测试会清理目录，避免 ENOENT）
+    // 无需缓存状态：确保目录存在是幂等的。
+}
+
+function ensureLogDirExists() {
+    try {
+        if (!existsSync(RUNTIME_LOG_DIR)) {
+            mkdirSync(RUNTIME_LOG_DIR, { recursive: true });
+        }
+    } catch (error) {
+        // 不能在 Logger 初始化前调用 Logger 本身，直接抛错即可
+        throw new Error(`创建 logs 目录失败: ${RUNTIME_LOG_DIR}. ${error?.message || error}`, {
+            cause: error,
+            code: "runtime"
+        });
+    }
+}
+
+// 方案B：删除“启动时清理旧日志”功能（减少 I/O 与复杂度）。
+
+/**
+ * 配置日志
+ */
+export function configure(cfg) {
+    // 旧实例可能仍持有文件句柄；这里异步关闭（不阻塞主流程）
+    void shutdown();
+
+    // 方案B：每次 configure 都从默认配置重新构建（避免继承上一次配置造成测试/运行时污染）
+    config = Object.assign(
+        {
+            debug: 0,
+            dir: RUNTIME_LOG_DIR,
+            maxSize: 20,
+            runtimeEnv: "production"
+        },
+        cfg
+    );
+
+    // 约束：日志目录始终固定在当前项目根目录 logs，不允许外部覆盖。
+    config.dir = RUNTIME_LOG_DIR;
+
+    if (cfg && !isString(cfg.runtimeEnv) && isString(cfg.runMode)) {
+        config.runtimeEnv = cfg.runMode;
+    }
+
+    // maxSize：仅按 MB 计算，且强制范围 10..100
+    {
+        const raw = config.maxSize;
+        let mb = isFiniteNumber(raw) ? raw : 20;
+        if (mb < 10) mb = 10;
+        if (mb > 100) mb = 100;
+        config.maxSize = mb;
+    }
+
+    appFileSink = null;
+    errorFileSink = null;
+
+    // 运行时清洗/截断上限（可配置）
+    sanitizeOptions = {
+        maxStringLen: normalizePositiveInt(config.maxStringLen, 200, 20, 200000),
+        maxArrayItems: normalizePositiveInt(config.maxArrayItems, 500, 10, 5000),
+        sanitizeDepth: normalizePositiveInt(config.sanitizeDepth, 5, 1, 10),
+        sanitizeNodes: normalizePositiveInt(config.sanitizeNodes, 5000, 50, 20000),
+        sanitizeObjectKeys: normalizePositiveInt(config.sanitizeObjectKeys, 500, 10, 5000),
+        sensitiveKeyMatcher: buildSensitiveKeyMatcher({ builtinPatterns: BUILTIN_SENSITIVE_KEYS, userPatterns: config.excludeFields })
+    };
+}
+
+/**
+ * 设置 Mock Logger（用于测试）
+ * @param mock - Mock Logger 实例（形如 {info/warn/error/debug}），传 null 清除 mock
+ */
+export function setMockLogger(mock) {
+    mockInstance = mock;
+}
+
+function buildJsonLine(level, timeMs, record) {
+    const base = {
+        level: level,
+        time: formatYmdHms(Reflect.construct(Date, [timeMs])),
+        pid: process.pid
+    };
+
+    // 目标：让 level/time/timeFormat/pid/hostname 在 JSON 行首出现（更易读），同时保持 JSONL 可解析。
+    // 约束：record 不允许覆盖基础字段。
+    // 实现：先写入基础字段，再按 record 的 key 顺序追加其它字段。
+    if (record && isPlainObject(record)) {
+        const out = {};
+        out["level"] = base["level"];
+        out["time"] = base["time"];
+        out["pid"] = base["pid"];
+
+        for (const key of Object.keys(record)) {
+            if (key === "level") continue;
+            if (key === "time") continue;
+            if (key === "pid") continue;
+            out[key] = record[key];
+        }
+
+        // msg 允许保留 record.msg（若存在），否则补齐空字符串。
+        if (record.msg !== undefined) {
+            out["msg"] = record.msg;
+        } else if (out["msg"] === undefined) {
+            out["msg"] = "";
+        }
+
+        try {
+            return `${JSON.stringify(out)}\n`;
+        } catch {
+            try {
+                return `${JSON.stringify({ level: out["level"], time: out["time"], pid: out["pid"], msg: "[Unserializable log record]" })}\n`;
+            } catch {
+                return '{"msg":"[Unserializable log record]"}\n';
+            }
+        }
+    }
+
+    if (base["msg"] === undefined) {
+        base["msg"] = "";
+    }
+
+    try {
+        return `${JSON.stringify(base)}\n`;
+    } catch {
+        try {
+            return `${JSON.stringify({ level: base["level"], time: base["time"], pid: base["pid"], msg: "[Unserializable log record]" })}\n`;
+        } catch {
+            return '{"msg":"[Unserializable log record]"}\n';
+        }
+    }
+}
+
+function ensureSinksReady(kind) {
+    ensureLogDirExists();
+
+    const maxSizeMb = isFiniteNumber(config.maxSize) ? config.maxSize : 20;
+    const maxFileBytes = Math.floor(maxSizeMb * 1024 * 1024);
+
+    if (kind === "app") {
+        if (!appFileSink) {
+            appFileSink = new LogFileSink({ prefix: "app", maxFileBytes: maxFileBytes });
+        }
+        return { fileSink: appFileSink };
+    }
+
+    if (!errorFileSink) {
+        errorFileSink = new LogFileSink({ prefix: "error", maxFileBytes: maxFileBytes });
+    }
+
+    return { fileSink: errorFileSink };
+}
+
+function writeJsonl(kind, level, record, options) {
+    const sinks = ensureSinksReady(kind);
+    const time = Date.now();
+    const effectiveSanitizeOptions = buildSanitizeOptionsForWriteOptions(options);
+    const sanitizedRecord = sanitizeLogObject(record, effectiveSanitizeOptions);
+    const fileLine = buildJsonLine(level, time, sanitizedRecord);
+    sinks.fileSink.enqueue(fileLine);
+}
+
+// 对象清洗/脱敏/截断逻辑已下沉到 utils/loggerUtils.ts（减少 logger.ts 复杂度）。
+
+// 日志仅接受 1 个入参（任意类型）。
+// - plain object（{}）直接作为 record
+// - 其他任何类型：包装成对象再写入（避免 sink 层依赖入参类型）
+function toRecord(input) {
+    if (isPlainObject(input)) {
+        return input;
+    }
+
+    if (input instanceof Error) {
+        return { err: input, msg: input.message || input.name || "Error" };
+    }
+
+    if (input === undefined) {
+        return { msg: "" };
+    }
+
+    if (input === null) {
+        return { msg: "null" };
+    }
+
+    // 非 plain object（数组/Date/Map/...）也走 value 包装，由 sanitize 负责做安全预览/截断。
+    if (typeof input === "object") {
+        return { value: input };
+    }
+
+    try {
+        return { msg: String(input) };
+    } catch {
+        return { msg: "[Unserializable]" };
+    }
+}
+
+function logWrite(level, input, options) {
+    // debug!=1/true 则不记录 debug 日志
+    if (level === "debug" && config.debug !== 1 && config.debug !== true) return;
+
+    const record0 = toRecord(input);
+
+    // 测试场景：mock logger 走同步写入，并在入口进行清洗/脱敏/截断控制
+    if (mockInstance) {
+        const effective = buildSanitizeOptionsForWriteOptions(options);
+        const sanitized = sanitizeLogObject(record0, effective);
+        if (level === "info") {
+            mockInstance.info(sanitized);
+        } else if (level === "warn") {
+            mockInstance.warn(sanitized);
+        } else if (level === "error") {
+            mockInstance.error(sanitized);
+        } else {
+            mockInstance.debug(sanitized);
+        }
+        return;
+    }
+
+    if (level === "error") {
+        // error 仅写入 error 文件
+        writeJsonl("error", "error", record0, options);
+    } else {
+        writeJsonl("app", level, record0, options);
+    }
+}
+
+/**
+ * 日志实例（延迟初始化）
+ */
+export const Logger = {
+    info(msg, data, truncate) {
+        const options = truncate === false ? { truncate: false } : undefined;
+        if (isPlainObject(msg)) {
+            logWrite("info", msg, options);
+            return;
+        }
+
+        logWrite("info", { msg: msg, data: data }, options);
+    },
+    warn(msg, data, truncate) {
+        const options = truncate === false ? { truncate: false } : undefined;
+        if (isPlainObject(msg)) {
+            logWrite("warn", msg, options);
+            return;
+        }
+
+        logWrite("warn", { msg: msg, data: data }, options);
+    },
+    error(msg, err, data, truncate) {
+        const options = truncate === false ? { truncate: false } : undefined;
+        if (isPlainObject(msg)) {
+            logWrite("error", msg, options);
+            return;
+        }
+
+        logWrite("error", { msg: msg, err: err, data: data }, options);
+    },
+    debug(msg, data, truncate) {
+        const options = truncate === false ? { truncate: false } : undefined;
+        if (isPlainObject(msg)) {
+            logWrite("debug", msg, options);
+            return;
+        }
+
+        logWrite("debug", { msg: msg, data: data }, options);
+    },
+    async flush() {
+        await flush();
+    },
+    configure(cfg) {
+        configure(cfg);
+    },
+    setMock(mock) {
+        setMockLogger(mock);
+    },
+    async shutdown() {
+        await shutdown();
+    }
+};