mytglib 1.1.5 → 1.1.7

package/README.md

@@ -203,22 +203,29 @@ console.log(account.accountId, account.runtimeStatus);
 ```
 
 `databasePath` 必须是绝对文件路径，目录和文件权限由运行环境的默认配置决定。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` 只能写真实文件名
+账号连接所需的 auth key 和 JSON Metadata 明文持久化到 SQLite。`.session` 可以使用 Telethon
+的 `sessions` schema 或当前 mtcute 的 `key_value`/`auth_keys` schema，并会在只读打开后
+自动识别。两套 schema 同时存在时：两侧都有效且授权状态完全一致才接受；两侧都有效但内容冲突
+则拒绝；只有一侧有效时使用有效侧；两侧都无有效授权时拒绝。会话文件与 JSON 必须属于同一个
+有效账号，导入时会严格核对 auth key、DC、账号身份和手机号。Pool 只接受 Telegram 官方移动端
+凭据：Android 必须使用 `app_id: 4` 及其官方 `app_hash`，iOS 必须使用 `app_id: 8` 及其官方
+`app_hash`；TDesktop、自定义 API ID 或平台与 API 凭据不匹配的 JSON 会在建立 Telegram 连接前
+直接拒绝。当前不支持代理。
+
+为兼容常见会话导出格式，JSON 的 `session_file` 只能写真实文件名
 `account.session` 或同名 stem `account`，不得携带目录组件；导入后会统一规整为真实文件名。
 StringSession 优先读取 `session_str`，也兼容 `session_string`；两者都缺失时会根据只读 SQLite
-中唯一的 `sessions` 行生成规范 `session_str`。任何显式提供的 StringSession 都必须与 SQLite
+中的主 DC 和 auth key 生成规范 `session_str`。任何显式提供的 StringSession 都必须与 SQLite
 中的主 DC、IPv4、端口和 auth key 完全一致，否则拒绝导入。
+SQLite 与 StringSession 中的 endpoint 只用于交叉校验；实际创建 Pool 客户端时会按 JSON 对应的
+官方 iOS 或 Android 平台，使用相同 DC ID 的内置官方 seed，不会连接上传文件指定的地址。
+`device_token` 可以省略、设为 `null` 或留空；空值按未提供处理，不会写入连接参数。
 
-`minWarmSlots` 可省略，默认值为 `10`，允许范围为 `1..50`。它是正常负载下希望维持的最小
-预连接槽位数，不是导入账号数，也不是无条件建立的连接数。例如导入 500 个账号且设置
-`minWarmSlots: 10` 时，Pool 只会先预热目标槽位，剩余账号作为持久化库存待命，不会把 500 个
-账号同时上线。
+`minWarmSlots` 可省略，默认值为 `10`，可设为正的 JavaScript 安全整数，不再固定限制为 50；
+`minWarmSlots * 5` 也必须是 JavaScript 安全整数。
+它是正常负载下希望维持的最小预连接槽位数，不是导入账号数，也不是无条件建立的连接数。
+例如导入 500 个账号且设置 `minWarmSlots: 100` 时，Pool 只会先预热目标槽位，
+剩余账号作为持久化库存待命，不会把 500 个账号同时上线。
 
 Pool 的策略硬上限固定为 `minWarmSlots * 5`，实际连接上限还会受进程 CPU、内存、文件描述符和
 事件循环压力评估限制。忙碌槽位超过当前连接数一半时，Pool 会在资源允许的情况下异步提高目标槽位；
@@ -258,10 +265,14 @@ console.log(response.status, response.waitTime, response.error);
 未映射到上述业务状态的检测异常会被捕获并以 `OTHER_ERROR` 正常返回，`error` 仅保留可用的 `message`、`name`、
 `code`、`text` 和 `seconds`。
 
-单次检测总期限固定为 10 秒。账号触发 `FLOOD_WAIT` 后会按 Telegram 返回的等待秒数退出暖槽并
-进入冷却，Pool 随即从库存异步补入其他账号；当前请求最多再换用一个已经存在的 `READY` 账号，
-第二次仍触发洪水时返回 `FLOOD_WAIT`。`PHONE_NUMBER_FLOOD` 只保护目标手机号 5 分钟，不处罚
-账号。明确检测结果缓存 5 分钟，最多保存 10,000 条；同一手机号的并发请求会合并为一次检测，
+单次检测的所有尝试共享固定的 10 秒总期限。暖槽 RPC 触发 `FLOOD_WAIT`，或者槽位错误最终
+会映射为 `OTHER_ERROR` 时，当前请求最多在重试时已处于 `READY` 的其他暖槽上重试三次，
+即最多尝试四个暖槽；请求不会等待异步补槽。重试耗尽、没有更多 `READY` 暖槽或总期限耗尽时，
+返回最后一次已实际发生的暖槽错误；如果尚未发生任何暖槽错误就无可用槽位，则直接返回 Pool busy。
+触发 `FLOOD_WAIT` 的账号会按 Telegram 返回的等待秒数退出暖槽并进入冷却，
+Pool 随即从库存异步补入其他账号。
+`PHONE_NUMBER_FLOOD` 是目标手机号级错误，不换槽重试，只保护目标手机号 5 分钟且不处罚账号。
+明确检测结果缓存 5 分钟，最多保存 10,000 条；同一手机号的并发请求会合并为一次检测，
 基础设施错误不缓存，也不提供强制刷新。
 
 `abortSignal` 只取消当前调用方等待，并以 `OTHER_ERROR` 返回取消原因；它不会中断已经启动的
@@ -356,6 +367,8 @@ Rust 实现从 `grammers_core` 根模块导出 `create_phone_status_pool()`、`P
 期限耗尽、目标号码触发 `PHONE_NUMBER_FLOOD` 或检测基础设施失败均返回
 `Ok(PhoneStatusCheckResponse::Busy { .. })`。创建和管理操作的无效输入、调用取消、Pool
 生命周期错误或内部协调错误才通过 `PhoneStatusPoolError` 返回，不应转换成业务 `BUSY`。
+Rust Pool 同样在共享的 10 秒总期限内对 `FLOOD_WAIT` 和暖槽 RPC 其他错误最多换槽重试三次，
+无 `READY` 槽位、期限耗尽或 `PHONE_NUMBER_FLOOD` 不会继续换槽。
 Rust 字段名使用 snake_case，通过 serde 序列化时使用 camelCase。资源上限使用 CPU、内存和文件
 描述符评估；Tokio 没有稳定的 event-loop 利用率指标，因此 Rust 状态不会伪造该项数据。
 
@@ -423,7 +436,9 @@ use grammers_core::{
 `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 中的
+`close()` 完成资源释放。导入的 session JSON 最大为 1 MiB。Rust Pool 与 Node.js
+使用相同的 Telethon/mtcute schema 自动识别、`session_file` stem 兼容和混合 schema 选择规则；
+mtcute 缺失 `dc_main` 时按其原语义使用默认生产 DC2。SQLite 与 StringSession 中的
 endpoint 只用于校验两个文件描述同一个会话；实际连接始终使用 grammers 内置的 Telegram DC
 地址，上传文件不能指定 API 进程的 TCP 目标。`ImportAccountInput` 和
 `CheckPhoneStatusInput` 的 `abort_signal` 是仅运行时字段，使用 serde 反序列化输入时需要由 Rust
@@ -432,7 +447,7 @@ endpoint 只用于校验两个文件描述同一个会话；实际连接始终
 ## 一次性手机号状态检查
 
 `checkPhoneStatus()` 是独立于注册流程的根导出方法。Telegram 没有为此提供纯查询接口；
-本方法使用一个已授权账号的 mtcute `.session` 文件和对应 JSON，根据
+本方法使用一个已授权账号的 Telethon 或 mtcute `.session` 文件和对应 JSON，根据
 [`account.sendChangePhoneCode`](https://core.telegram.org/method/account.sendChangePhoneCode)
 的响应或 RPC 错误推断号码状态：
 
@@ -451,25 +466,40 @@ const result = await checkPhoneStatus({
 console.log(result);
 ```
 
-JSON 必须包含 `syncSessionJson()` 生成的 `session_str`、`session_file`、`app_id`、`app_hash`
-和客户端配置；自定义 iOS 版本还会携带 `override_layer` 以便完整还原。
-方法会以只读方式打开 `.session`，校验其主 DC、IPv4、端口和 auth key 与 JSON 的规范
-`session_str` 一致，再把必要连接状态复制到 `MemoryStorage`；不会迁移或修改原 SQLite 的表和主数据库
-内容。不过 SQLite 在 WAL 模式下即使只读打开也可能创建或更新 `-shm` 等 sidecar，因此这不等同于
-“文件系统零写入”。用于请求的临时客户端不会注册 reCAPTCHA middleware，也不会求解或主动重放
-challenge；正常主 DC 路径只调用一次 `client.call()`，不做应用层重试。mtcute 仍可能为 DC 迁移或
-MTProto 连接恢复重发底层请求，这不是 `maxRetryCount` 控制的应用层重试。请求的
-`settings` 固定为
+JSON 必须包含与 `syncSessionJson()` 输出格式兼容的 `session_str`、`session_file`、`app_id`、`app_hash`
+和客户端配置；自定义 iOS 版本还会携带 `override_layer` 以便完整还原。`session_file` 可以写完整文件名
+`account.session` 或同名 stem `account`，但不得包含目录组件。`device_token` 可以省略、设为 `null`
+或留空，空值按未提供处理。
+方法会以只读方式检查 SQLite schema，自动识别 Telethon 的 `sessions` 表或 mtcute 的
+`key_value` 与 `auth_keys` 表，校验其主 DC、IPv4、端口和 auth key 与 JSON 的规范
+`session_str` 一致，再把必要连接状态复制到 `MemoryStorage`；不会初始化对应存储实现、执行迁移或修改
+原 SQLite 的表和主数据库内容。不过 SQLite 在 WAL 模式下即使只读打开也可能创建或更新 `-shm` 等
+sidecar，因此这不等同于“文件系统零写入”。混合 schema 同样遵循“两侧一致、冲突拒绝、仅一侧有效
+则使用有效侧”的规则。SQLite 与 StringSession 中的 endpoint 只用于交叉校验；实际联网会按
+`lang_pack` 对应的官方平台，使用相同 DC ID 的内置官方 seed。用于请求的临时客户端不会注册
+reCAPTCHA middleware，也不会求解或主动重放 challenge；正常主 DC 路径只调用一次 `client.call()`，
+不做应用层重试。mtcute 仍可能为 DC 迁移或 MTProto 连接恢复重发底层请求，这不是 `maxRetryCount`
+控制的应用层重试。请求的 `settings` 固定为
 `{ _: "codeSettings", allowFlashcall: true, allowFirebase: false, logoutTokens: [] }`。
-`timeout_ms` 默认为 `30000`。会话导出、连接和目标 RPC 等受控异步阶段各自使用完整的
+`timeout_ms` 默认为 `30000`。会话数据库读取、连接和目标 RPC 等受控阶段各自使用完整的
 `timeout_ms` 上限，而不是共享整个方法的总 deadline；资源清理也使用独立的同值上限，并且不会因
-调用方取消而跳过。`abort_signal` 会取消清理前的受控异步阶段；请求重试次数和 flood 自动等待均固定
+调用方取消而跳过。SQLite 查询是同步 native 调用：查询开始前已取消会阻止读取，查询开始后 JavaScript
+timer 或 `abort_signal` 不能硬中断；SQLite 锁等待最多使用 `5000ms` busy timeout，查询返回时还会复核
+阶段期限并拒绝过期结果。其他受控异步阶段会响应 `abort_signal`；请求重试次数和 flood 自动等待均固定
 为 `0`。客户端无论成功或失败都会在返回前尝试有界销毁。
 
-Rust 对应入口是 `grammers_core` 根导出的 `check_phone_status()`。它读取项目生成的 `.grammers`
-会话和同目录 JSON，校验 JSON 中的 `session_str` 与只读会话的主 DC、地址和 auth key 一致，随后
-把授权 key 与连接配置复制到 `MemorySession`；原 `.grammers` 以只读方式
-打开，不会迁移或写回。输入字段使用 snake_case，结果序列化时使用与 npm 一致的 camelCase：
+Rust 对应入口是 `grammers_core` 根导出的 `check_phone_status()`。它按 SQLite schema 自动识别内部
+Grammers、Telethon `sessions` 或 mtcute `key_value`/`auth_keys` 会话，并校验 JSON 中显式提供的
+`session_str` 与主 DC、IPv4/端口和 auth key 一致。Grammers 会话继续以内部
+`session_metadata` 为权威；Telethon/mtcute 的 schema、DC 与 auth key 在同一个只读事务快照中读取。
+三种来源都只把授权 key 与连接配置复制到 `MemorySession`，不会导入、迁移或写回源数据库；外部会话
+记录的地址只用于文件间交叉校验，实际连接仍使用 Grammers 内置的可信 Telegram DC 地址。外部会话的
+`session_file` 可写真实文件名或省略 `.session`/`.grammers` 的同名 stem；内部 `.grammers` 会话还兼容
+旧导出 JSON 中同 stem 的 `.session` 名称，所有形式均不得包含目录组件。`app_id` 只需为正整数且
+`app_hash` 非空，因此不破坏已有自定义凭据；`device_token` 缺失、为 `null` 或空白时按未提供处理。
+Grammers 分支若提供非空 `device_token`，trim 后仍必须与内部 `session_metadata` 一致；省略或空值不会
+从内部 Metadata 自动注入连接参数。
+输入字段使用 snake_case，结果序列化时使用与 npm 一致的 camelCase：
 
 ```rust,no_run
 use grammers_core::{AbortSignal, PhoneStatusCheckInput, Proxy, check_phone_status};