mytglib 1.1.4 → 1.1.6

package/README.md

@@ -171,7 +171,7 @@ const updates = await core.submitCredentials({
 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` 一样按密码保护。
+`syncSessionJson()` 无参数并返回 JSON 文件路径。JSON 中的 `session_str` 为可与 Telethon StringSession v1 兼容的字符串，`reg_time` 按中国标准时间转为 `YYYY-MM-DD`；当前转换仅支持项目使用的 IPv4 主 DC。底层 `.session` 仍是 mtcute SQLite，不会被转换成 Telethon SQLite。输出文件包含 auth key 和明文两步验证密码，会通过临时文件原子替换；文件权限由运行环境的默认配置决定。
 
 ## 手机号状态账号池
 
@@ -202,18 +202,24 @@ const account = await pool.importAccount({
 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` 只能写真实文件名
+`databasePath` 必须是绝对文件路径，目录和文件权限由运行环境的默认配置决定。Pool 会把
+账号连接所需的 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 个账号且设置
@@ -423,7 +429,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 +440,7 @@ endpoint 只用于校验两个文件描述同一个会话；实际连接始终
 ## 一次性手机号状态检查
 
 `checkPhoneStatus()` 是独立于注册流程的根导出方法。Telegram 没有为此提供纯查询接口；
-本方法使用一个已授权账号的 mtcute `.session` 文件和对应 JSON，根据
+本方法使用一个已授权账号的 Telethon 或 mtcute `.session` 文件和对应 JSON，根据
 [`account.sendChangePhoneCode`](https://core.telegram.org/method/account.sendChangePhoneCode)
 的响应或 RPC 错误推断号码状态：
 
@@ -451,25 +459,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};