mytglib 1.1.6 → 2.0.0

package/README.md

@@ -143,6 +143,8 @@ const response = await core.sendCode({
 
 reCAPTCHA 由客户端的全局 network middleware 处理，不限于 `auth.sendCode`。任意尚未包装且允许重放的 RPC 返回格式严格匹配 `403 RECAPTCHA_CHECK_<action>__<siteKey>` 时，middleware 会调用 `recaptchaMobileTokenResolver`，使用 `invokeWithReCaptcha` 包装原请求，并通过后续的 `networkMiddlewares.basic()` 链重试一次。`account.updatePasswordSettings` 和 `payments.assignAppStoreTransaction` 不会被该 middleware 自动重放；已有 `invokeWithReCaptcha` 请求或包装请求再次失败时也不会重复求解、再次包装或形成无限重试。middleware 自动生成的 `invokeWithReCaptcha` 日志记录错误文本、完整原请求、真实响应和错误。
 
+Rust `grammers_core` 对初始 `auth.sendCode` 及其自动生成的 `invokeWithReCaptcha(auth.sendCode)` 额外设置完整 frame 写出后的 20 秒响应期限。连接类失败会先关闭当前 DC sender，再用同一序列化请求和同一 reCAPTCHA token 在新代理隧道上重放一次；明确的 Telegram RPC 错误、取消和第二次连接失败不会重放。该规则不改变 Node.js `@mtcute/node` 实现，也不适用于 `signIn`、`signUp` 或其他 RPC。
+
 `auth.sentCodePaymentRequired` 不是 RPC 错误，而是 `auth.sendCode` 的合法返回。它表示由于所在国家或运营商的短信验证成本较高，官方客户端必须先完成 Telegram Premium 购买流程才能继续登录或注册。原始响应中的 `storeProduct`、`premiumDays`、`currency` 和 `amount` 描述商品与价格，`phoneCodeHash` 保留后续授权上下文，`supportEmailAddress` 和 `supportEmailSubject` 用于联系支持。
 
 `sendCode()` 或 `verifyEmailCode()` 收到该响应时，会像保存 `phoneCodeHash` 一样把三个必需字段原子地挂载到 `core.inputStore`：`{ premiumDays, currency, amount }`。普通 `auth.sentCode`、`auth.sentCodeSuccess`、授权成功及成功销毁客户端时会清空该状态。
@@ -221,10 +223,11 @@ SQLite 与 StringSession 中的 endpoint 只用于交叉校验；实际创建 Po
 官方 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 会在资源允许的情况下异步提高目标槽位；
@@ -264,10 +267,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` 返回取消原因；它不会中断已经启动的
@@ -287,6 +294,7 @@ const testResult = await pool.testAccount(account.accountId);
 const status = await pool.getStatus();
 
 console.log(accounts, detail, testResult, status.runtime);
+console.log(accounts.map(({ phone, cooldownUntil }) => ({ phone, cooldownUntil })));
 
 // 删除会先停止派单，等待该账号当前任务结束，再断开连接并删除持久化记录。
 const removed = await pool.removeAccount(account.accountId);
@@ -296,7 +304,8 @@ const removed = await pool.removeAccount(account.accountId);
 `BUSY`；触发 flood 的账号进入 `COOLDOWN`，认证失效等致命错误会进入 `QUARANTINED`。
 `testAccount()` 是账号健康自检：它使用 `users.getUsers(inputUserSelf)` 验证该账号的授权和身份，
 不会拿这个账号去检测某个外部手机号。验证成功会把隔离账号恢复为可调度状态。
-管理接口返回的账号信息不会包含 auth key 或原始 Metadata，手机号也会被掩码。
+管理接口返回完整 `phone` 和 ISO 格式或 `null` 的 `cooldownUntil`，但不会包含 auth key、原始
+Metadata、session 或其他连接凭据。
 
 `getStatus()` 可用于健康检查和后台展示，包含生命周期、账号库存、各运行态槽位数、当前目标、
 策略上限、资源上限、资源压力和建连并发等信息。若业务需要等待初始暖槽，可以在 API 对外接流量前
@@ -362,6 +371,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 状态不会伪造该项数据。
 
@@ -405,7 +416,8 @@ use grammers_core::{
         let tested = pool.test_account(&account.account_id).await?;
         let status = pool.get_status().await?;
         println!(
-            "accounts={} detail={} tested={} ready={}",
+            "phone={} accounts={} detail={} tested={} ready={}",
+            account.phone,
             accounts.len(),
             detail.is_some(),
             tested.is_some(),
@@ -606,7 +618,10 @@ console.log(result);
 
 `vendor/grammers` 是为后续 Tauri/Rust 桌面端准备的内置 fork，其中项目自有的
 `grammers-core` 承载 `src` 对应的 Rust 实现。它目前尚未接入本 npm 包的 JavaScript 运行路径，
-也不会进入 npm 发布包。上游基线、本地覆盖层、可重复的同步流程和验证范围见
+也不会进入 npm 发布包。Rust `CoreClient` 在 backend 连接初始化尚未完成、没有业务 transport frame
+写出时，若初始化明确超时会自动重新创建一次 backend；该限定重试独立于 RPC 的 `max_retry_count`。
+上游基线、本地覆盖层、
+可重复的同步流程和验证范围见
 [grammers fork 维护文档](docs/grammers-fork.md)。
 
 ## 测试