diff --git a/README.md b/README.md index 020fa422..200fc0b4 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,43 @@ # gramsrv -`gramsrv` is a Telegram-like MTProto server written in Go. It uses -[`github.com/gotd/td`](https://github.com/gotd/td) v0.144.0 / Layer 225 as the TL -and MTProto base, and its first compatibility target is a pinned Telegram -Desktop build. +`gramsrv` is a Go implementation of a Telegram-like MTProto server, focused on +real client compatibility, repeatable protocol research, and self-hosted chat +experiments. -`gramsrv` is an independent, unofficial project. It is not affiliated with, -endorsed by, or sponsored by Telegram or the official Telegram team. +[Website](https://telesrv.net) · [Discussion group](https://t.me/telesrv_chat) · [Channel](https://t.me/telesrv) · [中文 README](README.zh-CN.md) -Keywords: `MTProto`, `Telegram Desktop`, `gotd/td`, `Telegram-like server`, `Go`, -`self-hosted chat server`. +![gramsrv multi-device Desktop and Android preview](docs/assets/readme-hero.png) -[中文 README](README.zh-CN.md) +`gramsrv` is independent and unofficial. It is not affiliated with, endorsed by, +or sponsored by Telegram or the official Telegram team. -![Telegram Desktop Alice/Bob connected to gramsrv](docs/assets/tdesktop-dual-session.png) +## Highlights -## Status +- **Multi-device is implemented.** Telegram Desktop and Android clients can use + the same server state, with scoped sessions, online fan-out, current-session + exclusion, and offline recovery through update difference APIs. +- **Telegram Desktop is the primary compatibility target.** The public build + tracks a pinned TDesktop baseline and keeps compatibility work documented. +- **Android compatibility is active.** The current public screenshots include a + patched Android client connected to the same server path. +- **Core chat paths work today.** Login, users, contacts, dialogs, private + messages, supergroups/channels, media/files, profile/channel photos, + stickers, reactions, language packs, and presence are covered on the main + path. +- **Production boundaries are explicit.** Large-scale public channels, + multi-DC/file-DC/CDN, Bot API, payments, stories, Premium business logic, + abuse controls, and production object storage are outside the current public + scope. -This project is useful for local protocol research and Telegram Desktop -compatibility work. It is not a production Telegram replacement. +For downloads, public information, and the current hosted experience entry, +visit [telesrv.net](https://telesrv.net). For questions, compatibility reports, +and development discussion, join [t.me/telesrv_chat](https://t.me/telesrv_chat). -Implemented main paths include MTProto key exchange, login with a development -code, users/contacts/dialogs, private messages, supergroups/channels, update -difference recovery, local media/files, profile/channel photos, stickers, -reactions, and presence. Large-scale public channels, multi-DC/file-DC/CDN, -Bot API, payments, stories, Premium business logic, production abuse controls, -and production object storage are intentionally out of scope for now. +## Screenshots -## Contributing - -Contributions are very welcome. The most helpful areas right now are Telegram -Desktop compatibility reports, reproducible RPC traces, focused bug fixes, -tests for online/offline update behavior, performance work on already -implemented paths, and documentation that makes local setup easier. - -Please keep changes scoped and compatibility-driven. If a change affects -Telegram Desktop behavior, include the client version/commit, the RPC path you -tested, and whether server logs stayed free of `NOT_IMPLEMENTED`, `Unhandled -RPC`, `bad_msg`, panic, or internal errors. +| Telegram Desktop | Android | +|---|---| +| Telegram Desktop connected to gramsrv | Android client connected to gramsrv | ## Repository Layout @@ -52,7 +52,7 @@ internal/store/ store interfaces and memory/postgres/redis backends docs/ compatibility notes and module design docs ``` -## Run gramsrv +## Quick Start Requirements: @@ -90,86 +90,37 @@ Useful development environment variables: The optional sticker seed directory is skipped when it does not exist. -## Build Telegram Desktop For gramsrv +## Client Compatibility -The stock Telegram Desktop binary will not connect to `gramsrv`: it trusts -Telegram's production DC list and RSA keys. Build your own patched client. +Stock Telegram clients will not connect to `gramsrv` because they trust +Telegram's production DC list and RSA keys. Use a patched experience client from +the [official website](https://telesrv.net), or build your own client with a +minimal protocol patch. -Target baseline: +Current Telegram Desktop baseline: - Telegram Desktop commit: `9caf32dffc90ddd9bb08ad5777b865f729fa167b` - TL layer: 225 - Local DC: `127.0.0.1:2398`, DC id `2` -Clone and pin Telegram Desktop: - -```powershell -git clone --recursive https://github.com/telegramdesktop/tdesktop.git -cd tdesktop -git checkout 9caf32dffc90ddd9bb08ad5777b865f729fa167b -git submodule update --init --recursive -``` - -Build prerequisites and exact platform instructions are maintained upstream: - -- Windows: `docs/building-win.md` -- macOS: `docs/building-mac.md` -- Linux: `docs/building-linux.md` - -For Windows x64, the pinned upstream instructions currently boil down to: - -```powershell -Telegram\build\prepare\win.bat -cd Telegram -configure.bat x64 -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH -``` - -Then open `out\Telegram.slnx` in Visual Studio and build the `Telegram` -project. The debug binary is written to `out\Debug\Telegram.exe`. - -## Patch Telegram Desktop - -After `gramsrv` has generated `data/server_rsa.pem`, export the matching public -key: +After `gramsrv` generates `data/server_rsa.pem`, export the matching public key: ```powershell openssl rsa -in data/server_rsa.pem -RSAPublicKey_out -out data/server_rsa.pub ``` -Patch Telegram Desktop file -`Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp`: +Patch `Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp`: -1. Replace built-in production and test DC lists with local DC 2: - -```cpp -const BuiltInDc kBuiltInDcs[] = { - { 2, "127.0.0.1", 2398 }, -}; - -const BuiltInDc kBuiltInDcsIPv6[] = { - { 2, "::1", 2398 }, -}; - -const BuiltInDc kBuiltInDcsTest[] = { - { 2, "127.0.0.1", 2398 }, -}; - -const BuiltInDc kBuiltInDcsIPv6Test[] = { - { 2, "::1", 2398 }, -}; -``` - -2. Replace both `kPublicRSAKeys` and `kTestPublicRSAKeys` with the contents of +1. Replace the built-in production/test DC lists with your `gramsrv` endpoint. +2. Replace both `kPublicRSAKeys` and `kTestPublicRSAKeys` with `data/server_rsa.pub`. -3. In `DcOptions::constructFromBuiltIn()`, add `Flag::f_tcpo_only` to the IPv4 - and IPv6 built-in DC flags. +3. Add `Flag::f_tcpo_only` to the built-in DC flags. -Keep this client patch minimal: DC endpoints, RSA key, and TCP-only flags only. -Do not mix UI changes into the protocol patch. +Keep the client patch minimal: endpoint, RSA key, and TCP-only flags only. -## Run Two Local Desktop Clients +## Multi-Device Smoke Test -Use separate TDesktop working directories so Alice and Bob do not share `tdata`: +Use separate client working directories so sessions do not share local `tdata`: ```powershell $tdesktop = "C:\path\to\tdesktop\out\Debug\Telegram.exe" @@ -177,16 +128,19 @@ Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-alice") Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob") ``` -Log in with two different phone numbers. In local development, the login code is +Log in with different phone numbers. In local development, the login code is `12345` unless you changed `TELESRV_DEV_AUTH_CODE`. -If the client keeps reconnecting, check these first: +Recommended checks: -- `gramsrv` is listening on port `2398`. -- `data/server_rsa.pub` was copied into both RSA key arrays in TDesktop. -- `TELESRV_ADVERTISE_IP` matches the address reachable from the client. -- TDesktop was built from the pinned Layer 225 baseline or re-audited for a new - layer. +- Send private messages, stickers, media, replies, forwards, edits, deletes, + and read receipts between two users. +- Keep one device online and restart another device to verify offline + `updates.getDifference` recovery. +- Open the same account from multiple sessions and confirm current-session + echoes are not duplicated while other online sessions receive updates. +- Check server logs for no new `NOT_IMPLEMENTED`, `Unhandled RPC`, `bad_msg`, + panic, or internal errors. ## Documentation @@ -196,3 +150,13 @@ If the client keeps reconnecting, check these first: - [Message module](docs/message-module.md) - [Channel module](docs/channel-module.md) - [Performance audit](docs/performance-audit.md) + +## Contributing + +Compatibility-driven contributions are welcome. Useful areas include Telegram +Desktop and Android reports, reproducible RPC traces, focused bug fixes, +multi-device update tests, performance work on already implemented paths, and +documentation that makes local setup easier. + +If a change affects visible client behavior, include the client version/commit, +the RPC path you tested, and the server log result. diff --git a/README.zh-CN.md b/README.zh-CN.md index 99224860..eeab62c4 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,31 +1,28 @@ # gramsrv -`gramsrv` 是一个用 Go 编写的 Telegram-like MTProto server，以 -[`github.com/gotd/td`](https://github.com/gotd/td) v0.144.0 / Layer 225 作为 -TL 与 MTProto 基础，第一兼容目标是固定基线的 Telegram Desktop。 +`gramsrv` 是一个用 Go 编写的 Telegram-like MTProto server，重点放在真实客户端兼容、可复现协议研究和自建聊天服务实验。 + +[官网](https://telesrv.net) · [讨论群组](https://t.me/telesrv_chat) · [频道](https://t.me/telesrv) · [English README](README.md) + +![gramsrv Desktop 与 Android 多设备预览](docs/assets/readme-hero.png) `gramsrv` 是独立的非官方项目，与 Telegram 官方及其团队没有关联，也未获得其背书或赞助。 -关键词：`MTProto`、`Telegram Desktop`、`gotd/td`、`Telegram-like server`、`Go`、 -`self-hosted chat server`。 +## 亮点 -[English README](README.md) +- **多设备已实现。** Telegram Desktop 与 Android 客户端可以使用同一套服务端状态，支持 scoped session、在线 fan-out、当前 session 排除，以及通过 updates difference API 做离线恢复。 +- **Telegram Desktop 是第一兼容目标。** 当前公开版本围绕固定 TDesktop 基线推进，并把兼容性进展写入文档。 +- **Android 兼容正在推进。** 当前公开截图已经包含连接到同一服务端路径的 Android 客户端。 +- **核心聊天主路径可用。** 已覆盖登录、users、contacts、dialogs、私聊消息、超级群/频道、media/files、用户/频道头像、stickers、reactions、语言包与 presence。 +- **生产边界明确。** 大规模公开频道、多 DC / 文件 DC / CDN、Bot API、payments、stories、Premium 商业逻辑、生产风控和生产对象存储不属于当前公开版本范围。 -![Telegram Desktop Alice/Bob connected to gramsrv](docs/assets/tdesktop-dual-session.png) +下载、公开说明和当前体验入口见 [telesrv.net](https://telesrv.net)。问题交流、兼容反馈和开发讨论可以加入 [t.me/telesrv_chat](https://t.me/telesrv_chat)。 -## 当前状态 +## 截图 -本项目适合本地协议研究、Telegram Desktop 兼容性验证和自建 MTProto server 实验。它不是生产级 Telegram 替代品。 - -当前已覆盖的主路径包括 MTProto key exchange、开发验证码登录、users/contacts/dialogs、私聊消息、超级群/频道、updates difference 恢复、本地 media/files、用户/频道头像、stickers、reactions 和 presence。 - -暂不默认覆盖大规模公开频道、多 DC / 文件 DC / CDN、Bot API、payments、stories、Premium 商业逻辑、生产风控、生产对象存储等能力。 - -## 欢迎贡献 - -欢迎大家参与贡献。现在最有价值的方向包括 Telegram Desktop 兼容性报告、可复现 RPC trace、聚焦的小 bug fix、在线/离线 updates 行为测试、已实现路径的性能优化，以及让本地启动更顺滑的文档改进。 - -请尽量保持改动范围清晰，并围绕兼容性目标展开。如果改动会影响 Telegram Desktop 可见行为，请在 PR 或说明里写清客户端版本/commit、验证过的 RPC 路径，以及 server 日志是否没有新增 `NOT_IMPLEMENTED`、`Unhandled RPC`、`bad_msg`、panic 或 internal error。 +| Telegram Desktop | Android | +|---|---| +| Telegram Desktop connected to gramsrv | Android client connected to gramsrv | ## 仓库结构 @@ -40,7 +37,7 @@ internal/store/ store interfaces 与 memory/postgres/redis 后端 docs/ 兼容性记录与模块设计文档 ``` -## 运行 gramsrv +## 快速启动 依赖： @@ -77,88 +74,33 @@ go build -o bin/gramsrv.exe ./cmd/telesrv 如果 sticker seed 目录不存在，启动时会自动跳过。 -## 编译连接 gramsrv 的 Telegram Desktop +## 客户端兼容 -官方 Telegram Desktop 二进制不能直接连接 `gramsrv`，因为它信任的是 Telegram 官方 DC 列表和 RSA keys。你需要编译一个最小 patch 过的客户端。 +官方 Telegram 客户端不能直接连接 `gramsrv`，因为它们信任的是 Telegram 官方 DC 列表和 RSA keys。你可以从 [官网](https://telesrv.net) 获取体验客户端，或者自己编译带最小协议 patch 的客户端。 -目标基线： +当前 Telegram Desktop 基线： - Telegram Desktop commit：`9caf32dffc90ddd9bb08ad5777b865f729fa167b` - TL layer：225 - 本地 DC：`127.0.0.1:2398`，DC id `2` -克隆并固定 Telegram Desktop： - -```powershell -git clone --recursive https://github.com/telegramdesktop/tdesktop.git -cd tdesktop -git checkout 9caf32dffc90ddd9bb08ad5777b865f729fa167b -git submodule update --init --recursive -``` - -编译依赖和各平台完整说明以 Telegram Desktop 上游文档为准： - -- Windows：`docs/building-win.md` -- macOS：`docs/building-mac.md` -- Linux：`docs/building-linux.md` - -Windows x64 下，固定基线的主要步骤是： - -```powershell -Telegram\build\prepare\win.bat -cd Telegram -configure.bat x64 -D TDESKTOP_API_ID=YOUR_API_ID -D TDESKTOP_API_HASH=YOUR_API_HASH -``` - -然后用 Visual Studio 打开 `out\Telegram.slnx`，构建 `Telegram` project。Debug 二进制会生成在 `out\Debug\Telegram.exe`。 - -## Patch Telegram Desktop - 等 `gramsrv` 生成 `data/server_rsa.pem` 后，导出匹配的公钥： ```powershell openssl rsa -in data/server_rsa.pem -RSAPublicKey_out -out data/server_rsa.pub ``` -修改 Telegram Desktop 文件： +修改 `Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp`： -```text -Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp -``` +1. 把内置 production/test DC 列表替换为你的 `gramsrv` endpoint。 +2. 把 `kPublicRSAKeys` 和 `kTestPublicRSAKeys` 都替换为 `data/server_rsa.pub`。 +3. 给 built-in DC flags 加上 `Flag::f_tcpo_only`。 -1. 把内置 production/test DC 列表替换为本地 DC 2： +客户端 patch 应保持最小：只改 endpoint、RSA key 和 TCP-only flags。 -```cpp -const BuiltInDc kBuiltInDcs[] = { - { 2, "127.0.0.1", 2398 }, -}; +## 多设备冒烟验证 -const BuiltInDc kBuiltInDcsIPv6[] = { - { 2, "::1", 2398 }, -}; - -const BuiltInDc kBuiltInDcsTest[] = { - { 2, "127.0.0.1", 2398 }, -}; - -const BuiltInDc kBuiltInDcsIPv6Test[] = { - { 2, "::1", 2398 }, -}; -``` - -2. 把 `kPublicRSAKeys` 和 `kTestPublicRSAKeys` 都替换为 `data/server_rsa.pub` 的内容。 -3. 在 `DcOptions::constructFromBuiltIn()` 中给 IPv4 与 IPv6 built-in DC flags 加上 `Flag::f_tcpo_only`。 - -```cpp -const auto flags = Flag::f_static | Flag::f_tcpo_only; -const auto flags = Flag::f_static | Flag::f_ipv6 | Flag::f_tcpo_only; -``` - -客户端 patch 应保持最小：只改 DC endpoint、RSA public key 和 TCP-only flags，不要把 UI 改动混入协议兼容 patch。 - -## 启动两个本地 Desktop 客户端 - -用不同的 TDesktop working directory，避免 Alice 和 Bob 共用同一个 `tdata`： +使用不同的客户端工作目录，避免多个 session 共用本地 `tdata`： ```powershell $tdesktop = "C:\path\to\tdesktop\out\Debug\Telegram.exe" @@ -166,14 +108,14 @@ Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-alice") Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob") ``` -用两个不同手机号登录。本地开发默认验证码是 `12345`，除非你修改了 `TELESRV_DEV_AUTH_CODE`。 +用不同手机号登录。本地开发默认验证码是 `12345`，除非你修改了 `TELESRV_DEV_AUTH_CODE`。 -如果客户端一直重连，优先检查： +推荐检查： -- `gramsrv` 是否正在监听 `2398`。 -- `data/server_rsa.pub` 是否同时复制到了 TDesktop 的两个 RSA key 数组。 -- `TELESRV_ADVERTISE_IP` 是否是客户端可访问的地址。 -- TDesktop 是否基于固定 Layer 225 基线构建，或者你已经重新审计了新 layer。 +- 在两个用户之间发送私聊消息、贴纸、媒体、回复、转发、编辑、删除和已读回执。 +- 保持一个设备在线，重启另一个设备，验证离线 `updates.getDifference` 恢复。 +- 同一账号打开多个 session，确认当前 session 不重复收到 echo，其它在线 session 能收到更新。 +- 检查 server 日志没有新增 `NOT_IMPLEMENTED`、`Unhandled RPC`、`bad_msg`、panic 或 internal error。 ## 文档 @@ -183,3 +125,9 @@ Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob") - [消息模块](docs/message-module.md) - [频道模块](docs/channel-module.md) - [性能审计](docs/performance-audit.md) + +## 参与贡献 + +欢迎围绕兼容性目标参与贡献。现在最有价值的方向包括 Telegram Desktop / Android 兼容反馈、可复现 RPC trace、聚焦的小 bug fix、多设备 update 测试、已实现路径的性能优化，以及让本地启动更顺滑的文档改进。 + +如果改动会影响客户端可见行为，请写清客户端版本/commit、验证过的 RPC 路径，以及 server 日志结果。 diff --git a/docs/assets/android1.png b/docs/assets/android1.png new file mode 100644 index 00000000..42894208 Binary files /dev/null and b/docs/assets/android1.png differ diff --git a/docs/assets/readme-hero.png b/docs/assets/readme-hero.png new file mode 100644 index 00000000..f176c338 Binary files /dev/null and b/docs/assets/readme-hero.png differ diff --git a/docs/assets/tdesktop-alice.png b/docs/assets/tdesktop-alice.png deleted file mode 100644 index 41b2897e..00000000 Binary files a/docs/assets/tdesktop-alice.png and /dev/null differ diff --git a/docs/assets/tdesktop-bob.png b/docs/assets/tdesktop-bob.png deleted file mode 100644 index b9fde7a6..00000000 Binary files a/docs/assets/tdesktop-bob.png and /dev/null differ diff --git a/docs/assets/tdesktop-dual-session.png b/docs/assets/tdesktop-dual-session.png deleted file mode 100644 index 1942c7af..00000000 Binary files a/docs/assets/tdesktop-dual-session.png and /dev/null differ diff --git a/docs/assets/tdesktop1.png b/docs/assets/tdesktop1.png new file mode 100644 index 00000000..2411e7aa Binary files /dev/null and b/docs/assets/tdesktop1.png differ