@flun/mailer 2.1.4

package/lib/smtp-pool/index.js

@@ -0,0 +1,294 @@
+import { EventEmitter } from 'events';
+import { SmtpConnection } from '../smtp-connection/index.js';
+import { PoolResource } from './pool-resource.js';
+import { regexs, resetRegex, initSmtpConstructor, verifySmtp } from '../shared.js';
+
+/**
+ * 为 @flun/mailer 创建 SMTP 连接池传输对象
+ * >查看定义:@see {@link SmtpPool}
+ * @constructor
+ * @param {Object} options SMTP 连接选项
+ */
+class SmtpPool extends EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.name = 'SmtpPool';
+        initSmtpConstructor(this, options, SmtpConnection, 'smtpPool'); // 初始化SMTP连接
+        const { maxConnections, maxMessages, rateLimit, rateDelta } = this.options;
+        this.options.maxConnections = maxConnections || 5; // 最大连接数
+        this.options.maxMessages = maxMessages || 100;     // 每个连接最大消息数
+
+
+        // 速率限制配置(计数器,超时定时器,等待队列,检查点,时间窗口->毫秒,限制数量)
+        this._rateLimit = {
+            counter: 0, timeout: null, waiting: [], checkpoint: false,
+            delta: Number(rateDelta) || 1000, limit: Number(rateLimit) || 0
+        };
+        // 消息队列,连接池,连接计数器,连接池是否已关闭,是否处于空闲状态
+        this._queue = [], this._connections = []; this._connectionCounter = 0; this._closed = false, this.idling = true;
+
+        // 立即触发空闲事件
+        setImmediate(() => {
+            if (this.idling) this.emit('idle');
+        });
+    }
+
+    /**
+     * 将电子邮件加入队列，使用选定设置发送
+     *
+     * @param {Object} mail 邮件对象
+     * @param {Function} callback 回调函数
+     */
+    send(mail, callback) {
+        if (this._closed) return false;                            // 如果连接池已关闭，则返回false
+        this._queue.push({ mail, requeueAttempts: 0, callback });  // 将邮件加入队列(包括重试尝试计数)
+
+        // 如果队列长度达到最大连接数且处于空闲状态，则标记为非空闲
+        if (this.idling && this._queue.length >= this.options.maxConnections) this.idling = false;
+        setImmediate(() => this.#processMessages());              // 立即开始处理消息
+
+        return true;
+    }
+
+    /**
+     * 关闭池中的所有连接。如果有消息正在发送，则稍后关闭连接
+     */
+    close() {
+        this._closed = true, clearTimeout(this._rateLimit.timeout); // 标记为已关闭并清除速率限制定时器（如果存在）
+        const conLen = this._connections.length;
+        let queLen = this._queue.length;
+        if (!conLen && !queLen) return;         // 如果没有连接和队列，则直接返回
+
+        // 移除所有可用连接
+        for (let i = conLen - 1; i >= 0; i--) {
+            const connection = this._connections[i];
+            if (connection) {
+                const cid = connection.id;
+                connection.close(), this._connections.splice(i, 1);  // 从数组中移除连接
+                this.logger.info({ tnx: 'connection', cid, action: 'removed' }, '连接 #%s 已移除', cid);
+            }
+        }
+
+        // 清理整个队列
+        const invokeCallbacks = () => {
+            while ((queLen = this._queue.length) > 0) {
+                const entry = this._queue.shift();
+                if (entry && typeof entry.callback === 'function') {
+                    try {
+                        entry.callback(new Error(`连接池已关闭，队列中还有 ${queLen} 个待处理请求`));
+                    } catch (E) {
+                        this.logger.error({ err: E, tnx: 'callback' }, '回调错误: %s', E.message);
+                    }
+                }
+            }
+            this.logger.debug({ tnx: 'connection' }, '待处理队列条目已清除');
+        };
+
+        setImmediate(invokeCallbacks);
+    }
+
+    /**
+     * 检查队列和可用连接。如果有要发送的消息且有可用连接，则使用此连接发送邮件
+     */
+    #processMessages() {
+        let connection;
+        const queLen = this._queue.length, conLen = this._connections.length,
+            idlingEmit = () => {
+                this.idling = true, this.emit('idle'); // 标记为空闲
+            };
+
+        if (this._closed) return;                  // 如果已关闭，则不执行任何操作
+        // 如果队列为空，则不执行任何操作
+        if (!queLen) {
+            if (!this.idling) idlingEmit();
+            return;
+        }
+
+        // 查找第一个可用连接
+        for (let i = 0; i < conLen; i++)
+            if (this._connections[i].available) {
+                connection = this._connections[i];
+                break;
+            }
+
+        // 如果没有可用连接且未达到最大连接数，则创建新连接
+        const { maxConnections } = this.options;
+        if (!connection && conLen < maxConnections) connection = this.#createConnection();
+        if (!connection) return this.idling = false;               // 如果没有可用连接，则标记为非空闲并返回
+        if (!this.idling && queLen < maxConnections) idlingEmit(); // 检查处理队列中是否有空闲空间
+
+        // 从队列中取出一个条目并分配给连接
+        const entry = connection.queueEntry = this._queue.shift(), rCMI = resetRegex(regexs.CLEAN_MESSAGE_ID),
+            messageId = entry.messageId = (entry.mail.message.getHeader('message-id') || '').replace(rCMI, ''),
+            cid = connection.id, _rateLimit = this._rateLimit;
+        connection.available = false; // 标记连接为忙碌
+        this.logger.debug({ tnx: 'pool', cid, messageId, action: 'assign' },
+            '将消息 <%s> 分配给 #%s (%s)', messageId, cid, connection.messages + 1
+        );
+        // 处理速率限制
+        if (_rateLimit.limit) {
+            _rateLimit.counter++;
+            if (!_rateLimit.checkpoint) _rateLimit.checkpoint = Date.now();
+        }
+
+        // 发送邮件
+        connection.send(entry.mail, (err, info) => {
+            // 仅当前处理程序未更改时处理回调
+            if (entry === connection.queueEntry) {
+                try {
+                    entry.callback(err, info);
+                } catch (E) {
+                    this.logger.error({ err: E, tnx: 'callback', cid }, '回调错误 #%s: %s', cid, E.message);
+                }
+                connection.queueEntry = false;
+            }
+        });
+    }
+
+    /**
+     * 创建新的池资源
+     */
+    #createConnection() {
+        const connection = new PoolResource(this), cid = connection.id = ++this._connectionCounter; // 分配连接ID
+
+        this.logger.info({ tnx: 'pool', cid, action: 'conection' }, '创建新的池资源 #%s', cid);
+        // 监听池资源事件
+        connection.on('available', () => {
+            this.logger.debug({ tnx: 'connection', cid, action: 'available' }, '连接 #%s 变为可用', cid);
+            this._closed ? this.close() : this.#processMessages(); // 如果已关闭,则从连接列表中移除此连接,否则检查是否还有其它发送
+        }).once('error', err => {
+            if (err.code !== 'EMAXLIMIT') this.logger.error({ err, tnx: 'pool', cid }, '池错误 #%s: %s', cid, err.message);
+            else this.logger.debug({ tnx: 'pool', cid, action: 'maxlimit' }, '连接 #%s 已达到最大消息限制', cid);
+
+            // 如果连接有队列条目，则调用回调并传递错误
+            if (connection.queueEntry) {
+                try {
+                    connection.queueEntry.callback(err);
+                } catch (E) {
+                    this.logger.error({ err: E, tnx: 'callback', cid }, '回调错误 #%s: %s', cid, E.message);
+                }
+                connection.queueEntry = false;
+            }
+
+            this.#removeConnection(connection), this.#continueProcessing(); // 从连接列表中移除错误的连接,然后继续处理队列
+        }).once('close', () => {
+            this.logger.info({ tnx: 'connection', cid, action: 'closed' }, '连接 #%s 已关闭', cid);
+            this.#removeConnection(connection);
+            const { queueEntry } = connection;
+            if (queueEntry)
+                // 如果连接在发送时关闭，将消息重新加入队列;如果未达到最大重试次数，则重新排队
+                setTimeout(() => {
+                    this.#shouldRequeueOnClose(queueEntry) ? this.#requeueOnClose(connection) : this.#failOnClose(connection);
+                    this.#continueProcessing();
+                }, 50);  // 必须等待一下，因为"error"处理程序的回调可能在下一个事件循环中调用
+            else {
+                if (!this._closed && this.idling && !this._connections.length) this.emit('clear');
+                this.#continueProcessing();
+            }
+        });
+
+        this._connections.push(connection); // 将新连接添加到连接池
+        return connection;
+    }
+
+    /**
+     * 检查连接关闭时是否应该重新排队
+     */
+    #shouldRequeueOnClose(queueEntry) {
+        const { maxRequeues } = this.options;
+        return maxRequeues === undefined || maxRequeues < 0 || queueEntry.requeueAttempts < maxRequeues;
+    }
+
+    /**
+     * 连接关闭时失败传递
+     */
+    #failOnClose(connection) {
+        const { queueEntry, id } = connection;
+        if (queueEntry?.callback) {
+            try {
+                queueEntry.callback(new Error('连接关闭后达到最大重试次数'));
+            } catch (E) {
+                this.logger.error(
+                    { err: E, tnx: 'callback', messageId: queueEntry.messageId, cid: id }, '回调错误 #%s: %s', id, E.message);
+            }
+            connection.queueEntry = false;
+        }
+    }
+
+    /**
+     * 连接关闭时重新排队条目
+     */
+    #requeueOnClose(connection) {
+        const { queueEntry, id } = connection;
+        queueEntry.requeueAttempts++;
+        const { messageId, requeueAttempts } = queueEntry;
+        this.logger.debug({ tnx: 'pool', cid: id, messageId, action: 'requeue' },
+            '为 #%s 重新排队消息 <%s>。尝试次数: #%s', messageId, id, requeueAttempts);
+        this._queue.unshift(queueEntry), connection.queueEntry = false;
+    }
+
+    /**
+     * 如果池未关闭，则继续处理消息
+     */
+    #continueProcessing() {
+        this._closed ? this.close() : setTimeout(() => this.#processMessages(), 100);
+    }
+
+    /**
+     * 从池中移除资源
+     *
+     * @param {Object} connection 要移除的 PoolResource
+     */
+    #removeConnection(connection) {
+        const index = this._connections.indexOf(connection);
+        if (index >= 0) this._connections.splice(index, 1);
+    }
+
+    /**
+     * 检查连接是否达到当前速率限制，如果是，则将可用性回调加入队列
+     *
+     * @param {Function} callback 速率限制清除后运行的回调函数
+     */
+    checkRateLimit(callback) {
+        const now = Date.now(), { limit, counter, waiting, checkpoint, delta, timeout } = this._rateLimit;
+        if (!limit) return callback();
+        if (counter < limit) return callback();
+
+        waiting.push(callback);
+        if (checkpoint <= now - delta) return this.#clearRateLimit();
+        else if (!timeout) {
+            this._rateLimit.timeout = setTimeout(() => this.#clearRateLimit(), delta - (now - checkpoint));
+            this._rateLimit.checkpoint = now;
+        }
+    }
+
+    /**
+     * 清除当前速率限制并运行暂停的回调
+     */
+    #clearRateLimit() {
+        clearTimeout(this._rateLimit.timeout);
+        this._rateLimit.timeout = null, this._rateLimit.counter = 0, this._rateLimit.checkpoint = false;
+
+        const { waiting } = this._rateLimit;
+        while (waiting.length) setImmediate(waiting.shift()); // 恢复所有暂停的连接
+    }
+
+    /**
+     * 如果队列中有空闲插槽，则返回true
+     */
+    isIdle() {
+        return this.idling;
+    }
+
+    /**
+     * 验证SMTP配置
+     *
+     * @param {Function} callback 回调函数
+     */
+    verify(callback) {
+        const auth = new PoolResource(this).auth; // 使用PoolResource的认证信息
+        return verifySmtp(this, callback, SmtpConnection, auth);
+    }
+}
+
+export { SmtpPool };

package/lib/smtp-pool/pool-resource.js

@@ -0,0 +1,93 @@
+import { EventEmitter } from 'events';
+import { XOAuth2 } from '../xoauth2.js';
+import { SmtpConnection } from '../smtp-connection/index.js';
+import {
+    createSmtpConnection, setupConnectionHandlers, performSmtpAuthentication, prepareMessageForSending,
+    handleSendResult, createAuthConfig
+} from '../shared.js';
+
+/**
+ * 为连接池创建资源元素
+ * >查看定义:@see {@link PoolResource}
+ * @constructor
+ * @param {Object} pool SmtpPool实例
+ */
+class PoolResource extends EventEmitter {
+    constructor(pool) {
+        super();
+        this.pool = pool, this.options = pool.options, this.logger = this.pool.logger; // 所属连接池,连接选项,日志记录器
+        if (this.options.auth) this.auth = this.getAuth({});                           // 如果提供了认证信息，则设置认证
+
+        this._connection = false, this._connected = false;                             // SMTP连接实例,连接状态标志
+        this.messages = 0, this.available = true;                                      // 已发送消息计数,资源可用性标志
+    }
+
+    /**
+     * 获取认证信息
+     * @param {Object} authOpts 认证选项
+     * @returns {Object|boolean} 认证对象或false
+     */
+    getAuth(authOpts) {
+        if (!authOpts) return this.auth;
+        const authData = { ...this.options?.auth, ...authOpts, authMethod: this.options.authMethod || '' };
+        return createAuthConfig(authData, this.logger, this.mailer, XOAuth2);           // 创建认证配置
+    }
+
+    /**
+     * 建立到SMTP服务器的连接
+     *
+     * @param {Function} callback 连接建立或失败后的回调函数
+     */
+    connect(callback) {
+        this.pool.getSocket(this.options, (err, socketOp) => {
+            if (err) return callback(err);
+            // 创建和配置SMTP连接并处理连接错误和结束事件
+            const { options: newOp, connection } = createSmtpConnection(this, socketOp, SmtpConnection),
+                state = { returned: false }, cleanC = setupConnectionHandlers(state, connection, callback, this);
+
+            // 连接建立后的处理(执行 SMTP 认证和清理监听)
+            connection.connect(() => {
+                if (state.returned) return;
+                performSmtpAuthentication(state, connection, this.auth, newOp, callback, this), cleanC();
+            });
+        });
+    }
+
+    /**
+     * 使用当前配置发送邮件
+     *
+     * @param {Object} mail 邮件对象
+     * @param {Function} callback 回调函数
+     */
+    send(mail, callback) {
+        if (!this._connected) return this.connect(err => err ? callback(err) : this.send(mail, callback));
+
+        const { envelope, readStream, from, to, messageId }
+            = prepareMessageForSending(mail, this.logger, this.id); // 邮件预处理
+        // 执行邮件发送
+        this.connection.send(envelope, readStream, (err, info) => {
+            this.messages++; // 增加消息计数
+
+            // 异步处理资源限制检查
+            setImmediate(() => {
+                if (this.messages >= this.options.maxMessages) {
+                    const err = new Error('资源耗尽');        // 达到最大消息限制
+                    err.code = 'EMAXLIMIT', this.connection.close(), this.emit('error', err);
+                }
+                // 检查速率限制并标记为可用
+                else this.pool.checkRateLimit(() => this.available = true, this.emit('available'));
+            });
+            const result = { err, info, from, to, messageId };
+            handleSendResult(result, callback, this.logger); // 处理发送结果
+        });
+    }
+
+    /**
+     * 关闭连接
+     */
+    close() {
+        this._connected = false, this.auth?.oauth2?.removeAllListeners(), this.connection?.close(), this.emit('close');
+    }
+}
+
+export { PoolResource };

package/lib/smtp-transport.js

@@ -0,0 +1,81 @@
+import { EventEmitter } from 'events';
+import { SmtpConnection } from './smtp-connection/index.js';
+import { XOAuth2 } from './xoauth2.js';
+import {
+    initSmtpConstructor, getSocket, createSmtpConnection, setupConnectionHandlers, createAuthConfig,
+    prepareMessageForSending, handleSendResult, performSmtpAuthentication, verifySmtp
+} from './shared.js';
+
+/**
+ * 为@flun/mailer创建SMTP传输对象
+ * >查看定义:@see {@link SmtpTransport}
+ * @constructor
+ * @param {Object} options 连接选项
+ */
+class SmtpTransport extends EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.name = 'SMTP';
+        initSmtpConstructor(this, options, SmtpConnection, 'smtpTransport');  // 初始化SMTP连接
+        if (this.options.auth) this.auth = this.getAuth({});                  // 如果提供了认证信息，则设置认证
+    }
+
+    /**
+     * 获取认证信息
+     * @param {Object} authOpts 认证选项
+     * @returns {Object|boolean} 认证对象或false
+     */
+    getAuth(authOpts) {
+        if (!authOpts) return this.auth;
+        const authData = { ...this.options?.auth, ...authOpts };
+        return createAuthConfig(authData, this.logger, this.mailer, XOAuth2); // 创建认证配置
+    }
+
+    /**
+     * 使用选定的设置发送电子邮件
+     *
+     * @param {Object} mail 邮件对象
+     * @param {Function} callback 回调函数
+     */
+    send(mail, callback) {
+        getSocket(this.options, (err, socketOp) => {
+            if (err) return callback(err);
+            // 创建并配置SMTP连接,处理连接错误和结束事件
+            const { options: newOp, connection } = createSmtpConnection(this, socketOp, SmtpConnection),
+                state = { returned: false }, cleanC = setupConnectionHandlers(state, connection, callback, this),
+                // 发送消息
+                sendMessage = () => {
+                    const { envelope, readStream, from, to, messageId } = prepareMessageForSending(mail, this.logger);//邮件预处理
+                    connection.send(envelope, readStream, (err, info) => {
+                        state.returned = true, connection.close();
+
+                        const result = { err, info, from, to, messageId };
+                        handleSendResult(result, callback, this.logger); // 处理发送结果
+                    });
+                };
+            // 连接SMTP服务器
+            connection.connect(() => {
+                if (state.returned) return;
+                // 处理认证并发送消息
+                const auth = this.getAuth(mail.data?.auth);
+                performSmtpAuthentication(state, connection, auth, newOp, callback, this, sendMessage), cleanC();
+            });
+        });
+    }
+
+    /**
+     * 验证SMTP配置
+     *
+     * @param {Function} callback 回调函数
+     */
+    verify(callback) {
+        return verifySmtp(this, callback, SmtpConnection, this.auth);
+    }
+
+    // 释放资源
+    close() {
+        this.auth?.oauth2?.removeAllListeners(), this.emit('close');
+    }
+}
+
+export { SmtpTransport };

package/lib/stream-transport.js

@@ -0,0 +1,59 @@
+import { PK, getLogger, prepareMessageForSending, resolveStream } from './shared.js';
+
+/**
+ * 创建一个输出内容是 流(Stream) 或 完整 Buffer的邮件内容的传输对象
+ * 适用于需要将邮件内容直接输出到控制台、文件或其他流接口的场景;
+ * 该传输对象不会实际发送邮件,而是将邮件内容以流或缓冲区的形式提供给调用者;
+ * >查看定义:@see {@link StreamTransport}
+ * @param {Object} [options] 配置选项
+ * @param {boolean} [options.buffer=false]
+ *   - `false`（默认）：**异步流式返回**，邮件内容以可读流 (Readable Stream) 的形式给出。
+ *     适合：需要实时推送、管道转发，或邮件体积很大不想一次全装进内存时。
+ *   - `true`：**先收完整再返回**，邮件内容会被拼成一个 Buffer 对象一次性给你。
+ *     适合：需要加密、签名、保存文件等必须先拿到完整内容的场景。
+ * @param {string} [options.newline='']
+ *   生成的邮件正文使用哪种换行符：
+ *   - `'windows'`, `'win'`, `'dos'` 或 `'\r\n'` → 使用 Windows 风格换行 `\r\n`
+ *   - `'unix'`、空字符串或其他值 → 使用 Unix 风格换行 `\n`
+ *   通常保持默认即可；只有当你明确知道邮件客户端在 Windows 上有换行问题时才需设置。
+ *
+ * @constructor
+ */
+class StreamTransport {
+    constructor(options = {}) {
+        this.options = options, this.name = 'StreamTransport', this.version = PK.version;
+
+        const { component = 'streamTransport', newline = '' } = this.options;
+        this.logger = getLogger(this.options, { component });                                         // 初始化日志记录器
+        this.winbreak = ['win', 'windows', 'dos', '\r\n'].includes(newline.toString().toLowerCase()); // 根据配置确定换行符类型
+    }
+
+    /**
+     * 编译 mailcomposer 消息并将其转发给发送处理器
+     *
+     * @param {Object} emailMessage MailComposer 对象
+     * @param {Function} callback 发送完成时运行的回调函数
+     */
+    send(mail, done) {
+        const { envelope, messageId, readStream } // 邮件预处理
+            = prepareMessageForSending(mail, this.logger, '', { transportType: 'stream', winbreak: this.winbreak });
+
+        // 使用 setImmediate 确保异步执行
+        setImmediate(() => {
+            const handleError = (err, context) => {
+                this.logger.error({ err, tnx: 'send', messageId }, context, messageId, err.message), done(err);
+            };
+
+            // 如果不使用缓冲区，直接返回流(流可读时才认为成功)
+            if (!this.options.buffer) {
+                readStream.once('readable', () => done(null, { envelope, messageId, message: readStream }))
+                    .once('error', err => handleError(err, '为 %s 创建消息流失败。%s'))
+            }
+
+            // 将流数据读取到Buffer中
+            resolveStream(readStream, (err, value) => err ? handleError(err) : done(null, { envelope, messageId, message: value }));
+        });
+    }
+}
+
+export { StreamTransport };

package/lib/well-known/index.js

@@ -0,0 +1,54 @@
+import SERVICES from './services.json' with { type: 'json' }; // 导入服务配置
+import { regexs, resetRegex } from '../regexs.js';            // 导入正则表达式及其重置函数
+
+const normalized = {}, // 储存规范的服务对象
+
+    /**
+     * 规范化键名
+     * 移除非字母数字、点号和连字符的字符，并转换为小写
+     * @param {String} key - 需要规范化的键名
+     * @returns {String} 规范化后的键名
+     */
+    normalizeKey = key => {
+        const rNADH = resetRegex(regexs.NON_ALPHANUMERIC_DOT_HYPHEN);
+        return key.replace(rNADH, '').toLowerCase();
+    },
+
+    /**
+     * 规范化服务对象
+     * 过滤掉不需要的字段（domains 和 aliases）
+     * @param {Object} service - 原始服务对象
+     * @returns {Object} 规范化后的服务对象
+     */
+    normalizeService = service => {
+        const filter = ['domains', 'aliases']; // 需要过滤的字段
+        return Object.fromEntries(
+            Object.entries(service).filter(([key]) => !filter.includes(key)) // 只保留不在过滤列表中的属性
+        );
+    };
+
+// 遍历所有服务键名
+Object.keys(SERVICES).forEach(key => {
+    const service = SERVICES[key],
+
+        // 为指定键添加规范化服务条目
+        addServiceEntry = sourceKey => {
+            normalized[normalizeKey(sourceKey)] = normalizeService(service);
+        };
+    // 处理主键,别名,域名
+    addServiceEntry(key), (service.aliases ?? []).forEach(addServiceEntry), (service.domains ?? []).forEach(addServiceEntry);
+});
+
+/**
+ * 根据提供的键名解析 SMTP 配置;
+ * 键名可以是服务名称（如 'Gmail'）、别名（如 'Google Mail'）或邮箱地址（如 'test@googlemail.com'）
+ * >查看定义:@see {@link wellKnown}
+ * @param {String} key - 服务名称、别名或邮箱地址
+ * @returns {Object|Boolean} SMTP 配置对象,如果未找到则返回 false
+ */
+const wellKnown = key => {
+    key = normalizeKey(key.split('@').pop()); // 如果是邮箱地址,提取域名部分并规范化
+    return normalized[key] || false;          // 返回对应的配置对象,未找到则返回 false
+}
+
+export { wellKnown }