mytglib 1.1.2 → 1.1.4

package/README.md

@@ -4,7 +4,7 @@
 
 ## 环境
 
-- Node.js 20+
+- Node.js 20、22、23、24、25 或 26（与 `better-sqlite3@12.11.1` 支持范围一致）
 - 执行登录或代理检查时，需要一个可连接 Telegram 主 DC 的 HTTP 或 SOCKS5 代理
 
 安装当前仓库依赖：
@@ -173,7 +173,263 @@ const jsonFilePath = await core.syncSessionJson();
 
 `syncSessionJson()` 无参数并返回 JSON 文件路径。JSON 中的 `session_str` 为可与 Telethon StringSession v1 兼容的字符串，`reg_time` 按中国标准时间转为 `YYYY-MM-DD`；当前转换仅支持项目使用的 IPv4 主 DC。底层 `.session` 仍是 mtcute SQLite，不会被转换成 Telethon SQLite。输出文件包含 auth key 和明文两步验证密码，会以 `0600` 权限原子替换，必须与 `.session` 一样按密码保护。
 
-## 手机号状态检查
+## 手机号状态账号池
+
+`createPhoneStatusPool()` 用于在常驻 Node.js API 进程内维护一组已经授权的 Telegram
+账号。账号导入后由 Pool 自主预连接、派单、冷却、隔离、补槽和回收；管理员只负责导入、查看、
+测试或删除账号，不需要手工启用、停用或扩缩容。
+
+Pool 使用消费者模式：外部请求只消费已经连接的 `READY` 槽位，不会在请求路径中临时连接
+Telegram。创建 Pool 和后续补槽均为异步操作，因此进程刚启动、账号刚导入或资源已达上限而没有
+`READY` 账号时，检测会立即返回 `OTHER_ERROR`，不会排队等待建连。
+
+### 初始化与导入
+
+```js
+import { resolve } from "node:path";
+import { createPhoneStatusPool } from "mytglib";
+
+const pool = await createPhoneStatusPool({
+  databasePath: resolve(".data/phone-status-pool/pool.sqlite"),
+  minWarmSlots: 10,
+});
+
+const account = await pool.importAccount({
+  sessionFilePath: "/secure/imports/13099434947.session",
+  sessionJsonFilePath: "/secure/imports/13099434947.json",
+});
+
+console.log(account.accountId, account.runtimeStatus);
+```
+
+`databasePath` 必须是绝对文件路径。数据库目录和文件分别使用 `0700`、`0600` 权限；Pool 会把
+账号连接所需的 auth key 和 JSON Metadata 明文持久化到 SQLite，因此应把数据库目录视为密钥目录
+进行保护。`.session` 与 JSON 必须属于同一个有效的 Telethon 账号，导入时会严格核对 auth key、
+DC、账号身份和手机号。Pool 只接受 Telegram 官方移动端凭据：Android 必须使用 `app_id: 4`
+及其官方 `app_hash`，iOS 必须使用 `app_id: 8` 及其官方 `app_hash`；TDesktop、自定义 API ID
+或平台与 API 凭据不匹配的 JSON 会在建立 Telegram 连接前直接拒绝。当前不支持代理。
+
+为兼容常见 Telethon 导出格式，JSON 的 `session_file` 只能写真实文件名
+`account.session` 或同名 stem `account`，不得携带目录组件；导入后会统一规整为真实文件名。
+StringSession 优先读取 `session_str`，也兼容 `session_string`；两者都缺失时会根据只读 SQLite
+中唯一的 `sessions` 行生成规范 `session_str`。任何显式提供的 StringSession 都必须与 SQLite
+中的主 DC、IPv4、端口和 auth key 完全一致，否则拒绝导入。
+
+`minWarmSlots` 可省略，默认值为 `10`，允许范围为 `1..50`。它是正常负载下希望维持的最小
+预连接槽位数，不是导入账号数，也不是无条件建立的连接数。例如导入 500 个账号且设置
+`minWarmSlots: 10` 时，Pool 只会先预热目标槽位，剩余账号作为持久化库存待命，不会把 500 个
+账号同时上线。
+
+Pool 的策略硬上限固定为 `minWarmSlots * 5`，实际连接上限还会受进程 CPU、内存、文件描述符和
+事件循环压力评估限制。忙碌槽位超过当前连接数一半时，Pool 会在资源允许的情况下异步提高目标槽位；
+高峰过后，弹性槽位连续空闲 10 分钟才进入回收，并且每 30 秒最多回收一个，避免连接数瞬间震荡。
+当总连接上限高于 `minWarmSlots` 时，Pool 会在这个上限内部为导入和待机账号自检保留 1 个临时
+管理连接位；该预留不会突破 `minWarmSlots * 5`。若资源上限已经低到不高于最小暖槽数，管理建连
+会返回 `POOL_BUSY`，优先保护正在提供服务的暖槽。
+
+### 检测与返回值
+
+```js
+const response = await pool.checkPhoneStatus({
+  phone: "+12025550123",
+  abortSignal: new AbortController().signal,
+});
+
+console.log(response.status, response.waitTime, response.error);
+```
+
+返回对象固定使用一套扁平结构：
+
+```js
+{
+  waitTime: 0,
+  phone: "+12025550123",
+  startedAt: "2026-08-13T00:00:00.000Z",
+  endedAt: "2026-08-13T00:00:00.120Z",
+  durationMs: 120,
+  status: "PHONE_NUMBER_OCCUPIED",
+  error: null,
+}
+```
+
+`status` 只会是 `PHONE_NUMBER_OCCUPIED`、`PHONE_NUMBER_NO_OCCUPIED`、
+`PHONE_NUMBER_INVALID`、`PHONE_NUMBER_BANNED`、`FLOOD_WAIT` 或 `OTHER_ERROR`。
+`FLOOD_WAIT` 的等待秒数写入 `waitTime`；其他状态的 `waitTime` 为 `0`。
+未映射到上述业务状态的检测异常会被捕获并以 `OTHER_ERROR` 正常返回，`error` 仅保留可用的 `message`、`name`、
+`code`、`text` 和 `seconds`。
+
+单次检测总期限固定为 10 秒。账号触发 `FLOOD_WAIT` 后会按 Telegram 返回的等待秒数退出暖槽并
+进入冷却，Pool 随即从库存异步补入其他账号；当前请求最多再换用一个已经存在的 `READY` 账号，
+第二次仍触发洪水时返回 `FLOOD_WAIT`。`PHONE_NUMBER_FLOOD` 只保护目标手机号 5 分钟，不处罚
+账号。明确检测结果缓存 5 分钟，最多保存 10,000 条；同一手机号的并发请求会合并为一次检测，
+基础设施错误不缓存，也不提供强制刷新。
+
+`abortSignal` 只取消当前调用方等待，并以 `OTHER_ERROR` 返回取消原因；它不会中断已经启动的
+single-flight RPC。即使当前只有一个等待者，后台检测仍可完成并写入明确结果缓存。调用开始前已经
+取消的 signal 会在读取缓存前返回，不会命中旧结果或启动新 RPC。
+
+按照当前业务规则，`403 RECAPTCHA_CHECK_signup`（含 site key 后缀）直接判定为
+`PHONE_NUMBER_NO_OCCUPIED`。Pool 不求解、不重放 challenge；它会回收触发 challenge 的槽位并从库存
+异步补槽。其他 reCAPTCHA action 仍按 `OTHER_ERROR` 返回。
+
+### 管理与运行状态
+
+```js
+const accounts = await pool.listAccounts();
+const detail = await pool.getAccount(account.accountId);
+const testResult = await pool.testAccount(account.accountId);
+const status = await pool.getStatus();
+
+console.log(accounts, detail, testResult, status.runtime);
+
+// 删除会先停止派单，等待该账号当前任务结束，再断开连接并删除持久化记录。
+const removed = await pool.removeAccount(account.accountId);
+```
+
+账号运行态由 Pool 管理：可用账号处于 `STANDBY`、`RESERVED`、`CONNECTING`、`READY` 或
+`BUSY`；触发 flood 的账号进入 `COOLDOWN`，认证失效等致命错误会进入 `QUARANTINED`。
+`testAccount()` 是账号健康自检：它使用 `users.getUsers(inputUserSelf)` 验证该账号的授权和身份，
+不会拿这个账号去检测某个外部手机号。验证成功会把隔离账号恢复为可调度状态。
+管理接口返回的账号信息不会包含 auth key 或原始 Metadata，手机号也会被掩码。
+
+`getStatus()` 可用于健康检查和后台展示，包含生命周期、账号库存、各运行态槽位数、当前目标、
+策略上限、资源上限、资源压力和建连并发等信息。若业务需要等待初始暖槽，可以在 API 对外接流量前
+轮询 `status.runtime.ready`；检测方法自身始终不会等待预热。
+
+### 部署与关闭
+
+一个 SQLite 号池数据库同时只能由一个 Pool/进程持有，重复打开会抛出
+`POOL_ALREADY_OWNED`。为避免多个进程同时接管同一数据库，Pool 不会自动删除陈旧 owner lock；
+进程异常退出后再次启动会抛出 `POOL_STALE_LOCK`，必须先确认原 Pool 进程已经停止，再人工删除错误
+`details.lockPath` 指向的 `.lock` 文件。因此 Pool 应作为 API 进程级单例创建，而不是在每个路由或
+每次请求中创建。
+使用 PM2 时应采用单实例 `fork` 模式，不要使用 `cluster`：
+
+```js
+export default {
+  apps: [{
+    name: "api",
+    script: "server.js",
+    exec_mode: "fork",
+    instances: 1,
+  }],
+};
+```
+
+Next.js 必须让持有 Pool 的路由运行在 Node.js runtime，不能使用 Edge runtime；常驻连接和本地
+SQLite owner lock 也不适合无状态 serverless 部署。由于 `better-sqlite3` 是原生依赖，建议在
+`next.config.js` 中把库及相关运行时包保持为服务端外部依赖：
+
+```js
+/** @type {import("next").NextConfig} */
+const nextConfig = {
+  serverExternalPackages: ["mytglib", "@mtcute/node", "better-sqlite3"],
+};
+
+export default nextConfig;
+```
+
+对应 Route Handler 显式声明：
+
+```js
+export const runtime = "nodejs";
+```
+
+进程退出时应停止接收新请求并安全关闭 Pool：
+
+```js
+await pool.close({ drainTimeoutMs: 10_000 });
+```
+
+`close()` 会先等待正在执行的管理和检测操作；超过 drain deadline 后取消未完成操作，再销毁所有
+Telegram 客户端、定时器、缓存、SQLite 连接和 owner lock。关闭后的 Pool 不能复用，应重新调用
+`createPhoneStatusPool()`。如果强制关闭宽限期结束时仍有底层客户端销毁任务，`close()` 返回
+`POOL_CLOSE_TIMEOUT` 并保持 SQLite repository 和 owner lock；后台销毁结束后可再次调用 `close()`
+完成资源释放。
+
+### Rust API
+
+Rust 实现从 `grammers_core` 根模块导出 `create_phone_status_pool()`、`PhoneStatusPool` 及相关
+输入、响应和状态类型。调度、持久化格式和暖槽策略与 Node.js 实现一致。Rust Pool 仍使用
+`RESULT`/`BUSY` 调度响应。目标手机号格式无效属于明确检测结果，返回
+`Ok(PhoneStatusCheckResponse::Result { result: PhoneNumberInvalid, .. })`；没有 `READY` 账号、检测
+期限耗尽、目标号码触发 `PHONE_NUMBER_FLOOD` 或检测基础设施失败均返回
+`Ok(PhoneStatusCheckResponse::Busy { .. })`。创建和管理操作的无效输入、调用取消、Pool
+生命周期错误或内部协调错误才通过 `PhoneStatusPoolError` 返回，不应转换成业务 `BUSY`。
+Rust 字段名使用 snake_case，通过 serde 序列化时使用 camelCase。资源上限使用 CPU、内存和文件
+描述符评估；Tokio 没有稳定的 event-loop 利用率指标，因此 Rust 状态不会伪造该项数据。
+
+```rust,no_run
+use grammers_core::{
+    CheckPhoneStatusInput, CloseOptions, ImportAccountInput, PhoneStatusCheckResponse,
+    PhoneStatusPoolError, PhoneStatusPoolOptions, create_phone_status_pool,
+};
+
+# async fn example() -> Result<(), PhoneStatusPoolError> {
+    let mut options = PhoneStatusPoolOptions::new("/secure/phone-status-pool/pool.sqlite");
+    options.min_warm_slots = 10;
+    let pool = create_phone_status_pool(options).await?;
+
+    // 即使任一管理或检测步骤失败，下面仍会执行安全关闭。
+    let operation: Result<(), PhoneStatusPoolError> = async {
+        let account = pool
+            .import_account(ImportAccountInput::new(
+                "/secure/imports/13099434947.session",
+                "/secure/imports/13099434947.json",
+            ))
+            .await?;
+
+        match pool
+            .check_phone_status(CheckPhoneStatusInput::new("+12025550123"))
+            .await?
+        {
+            PhoneStatusCheckResponse::Result {
+                result,
+                checked_at,
+                cached,
+                ..
+            } => println!("{result:?} {checked_at} cached={cached}"),
+            PhoneStatusCheckResponse::Busy {
+                retry_after_seconds,
+            } => println!("BUSY retryAfterSeconds={retry_after_seconds}"),
+        }
+
+        let accounts = pool.list_accounts().await?;
+        let detail = pool.get_account(&account.account_id).await?;
+        let tested = pool.test_account(&account.account_id).await?;
+        let status = pool.get_status().await?;
+        println!(
+            "accounts={} detail={} tested={} ready={}",
+            accounts.len(),
+            detail.is_some(),
+            tested.is_some(),
+            status.runtime.ready,
+        );
+
+        pool.remove_account(&account.account_id).await?;
+        Ok(())
+    }
+    .await;
+
+    let close_result = pool.close(CloseOptions::default()).await;
+    operation?;
+    close_result?;
+#     Ok(())
+# }
+```
+
+`PhoneStatusPoolOptions::new()` 要求绝对数据库路径，`min_warm_slots` 省略时为 `10`。创建方法只
+打开本地状态并启动异步预热，不等待 Telegram 暖槽连接完成；可在接入业务流量前轮询
+`pool.get_status().await?.runtime.ready`。同一个数据库仍只能由一个 Pool 实例持有，进程退出前应
+始终调用 `pool.close(CloseOptions::default()).await`。如果强制关闭宽限期结束时仍有后台清理，
+`close()` 返回 `POOL_CLOSE_TIMEOUT` 并暂时保留 SQLite owner lock；后台任务退出后可再次调用
+`close()` 完成资源释放。导入的 session JSON 最大为 1 MiB。SQLite 与 StringSession 中的
+endpoint 只用于校验两个文件描述同一个会话；实际连接始终使用 grammers 内置的 Telegram DC
+地址，上传文件不能指定 API 进程的 TCP 目标。`ImportAccountInput` 和
+`CheckPhoneStatusInput` 的 `abort_signal` 是仅运行时字段，使用 serde 反序列化输入时需要由 Rust
+调用方另行赋值。
+
+## 一次性手机号状态检查
 
 `checkPhoneStatus()` 是独立于注册流程的根导出方法。Telegram 没有为此提供纯查询接口；
 本方法使用一个已授权账号的 mtcute `.session` 文件和对应 JSON，根据
@@ -250,9 +506,11 @@ Rust 的 `timeout_ms` 覆盖文件读取、只读会话加载、连接及目标
 返回对象固定包含 `waitTime`、原样传入的 `phone`、ISO 时间字符串 `startedAt`/`endedAt`、
 `durationMs`、`status` 和 `error`。`status` 可能为 `PHONE_NUMBER_OCCUPIED`、
 `PHONE_NUMBER_NO_OCCUPIED`、`PHONE_NUMBER_INVALID`、`PHONE_NUMBER_BANNED`、`FLOOD_WAIT`
-或 `OTHER_ERROR`。`RECAPTCHA_CHECK_signup` 不会触发求解或再次请求，也不用于推断号码状态，而是按
-`OTHER_ERROR` 返回；`FLOOD_WAIT` 的秒数写入 `waitTime`；其他异常同样不会向外抛出，而是在 `error`
-中保留可用的 `message`、`name`、`code`、`text` 和 `seconds`。
+或 `OTHER_ERROR`。`RECAPTCHA_CHECK_signup` 不会触发求解或再次请求，而是按当前业务规则返回
+`PHONE_NUMBER_NO_OCCUPIED`；`FLOOD_WAIT` 的秒数写入 `waitTime`；其他异常同样不会向外抛出，而是在 `error`
+中保留可用的 `message`、`name`、`code`、`text` 和 `seconds`。sender cleanup 失败始终返回
+`OTHER_ERROR` 且 `waitTime` 为 `0`；若目标 RPC 同时失败，合并后的 message 会包含 cleanup 原因，并保留
+可用的 RPC 关键字段。
 
 授权成功后可调用 Telegram 官方的 [`account.getAuthorizations`](https://core.telegram.org/method/account.getAuthorizations)
 获取当前账号的全部登录会话，并把响应保存到同目录的 `<session stem>.authorizations.json`：