# gramsrv

`gramsrv` is a Go implementation of a Telegram-like MTProto server, focused on
real client compatibility, repeatable protocol research, self-hosted chat
experiments, and ongoing tracking of newer Telegram client behavior.

[Website](https://telesrv.net) · [Discussion group](https://t.me/telesrv_chat) · [Channel](https://t.me/telesrv) · [中文 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.

## Demo Video

<p align="center">
  <video src="docs/assets/telesrv-demo-split-60s.mp4" controls muted playsinline width="100%"></video>
</p>

If the GitHub Markdown preview does not show the inline player in your browser,
open the [60-second Desktop and Android demo](docs/assets/telesrv-demo-split-60s.mp4).

## Highlights

- **One server program to run.** After PostgreSQL and Redis are ready, the Go
  server process wires together RSA key preparation, database migrations,
  language pack seeding, MTProto edge handling, RPC routing, updates,
  media/files, and reliable dispatch workers.
- **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.
- **Maintained with Telegram version tracking.** The public baseline stays
  reproducible, while newer Telegram Desktop and Android behavior is tracked
  through real client traces, compatibility notes, and targeted follow-up work.
- **Optimized hot paths are part of the design.** Batched reliable outbox
  delivery, warmed PostgreSQL pools, scoped session lookups, bounded RPC inputs,
  and seek-style pagination reduce repeated work on chat, sync, and media paths.
- **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.

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).

## Maintenance and Version Tracking

`gramsrv` does not treat one pinned client build as the end of the work. The
pinned Telegram Desktop baseline keeps regressions reproducible, while newer
Telegram Desktop and Android releases are followed separately through real
client startup/sync traces, compatibility matrix updates, and focused adaptation
tasks.

When a new Telegram client path appears, the expected workflow is to record it,
bound the inputs, decide whether it should be implemented, stubbed, or marked as
out of scope, and then keep the repository documentation in sync with the actual
behavior.

## Repository Layout

```text
cmd/telesrv/              server entrypoint
deploy/                   docker-compose and PostgreSQL migrations
internal/mtprotoedge/     MTProto transport, auth key, session, ack/resend
internal/rpc/             TL router and Telegram Desktop compatibility handlers
internal/app/             domain services
internal/domain/          protocol-independent domain models
internal/store/           store interfaces and memory/postgres/redis backends
docs/                     compatibility notes and module design docs
```

## Quick Start

Requirements:

- Go 1.25 or newer
- Docker Desktop or Docker Engine with Compose
- OpenSSL, if you want to build a matching Telegram Desktop client

Start PostgreSQL and Redis:

```powershell
docker compose -f deploy/docker-compose.yml up -d
```

Build and run the server:

```powershell
go build -o bin/gramsrv.exe ./cmd/telesrv
.\bin\gramsrv.exe
```

On first start, `gramsrv` creates `data/server_rsa.pem`, applies all database
migrations, seeds bundled language packs, and listens on `0.0.0.0:2398`.

Useful development environment variables:

| Variable | Default | Meaning |
|---|---:|---|
| `TELESRV_LISTEN` | `0.0.0.0:2398` | MTProto listen address |
| `TELESRV_ADVERTISE_IP` | `127.0.0.1` | IP written into `help.getConfig` |
| `TELESRV_DC` | `2` | self-hosted DC id |
| `TELESRV_DEV_AUTH_CODE` | `12345` | fixed login code for local development |
| `TELESRV_POSTGRES_DSN` | local Compose DSN | PostgreSQL connection string |
| `TELESRV_REDIS_ADDR` | `localhost:6399` | Redis address |
| `TELESRV_STICKER_SEED_DIR` | `data/sticker-seed` | optional exported sticker/reaction seed directory |

The optional sticker seed directory is skipped when it does not exist.

## Client Compatibility

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.

Current Telegram Desktop baseline:

- Telegram Desktop commit: `9caf32dffc90ddd9bb08ad5777b865f729fa167b`
- TL layer: 225
- Local DC: `127.0.0.1:2398`, DC id `2`

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/SourceFiles/mtproto/mtproto_dc_options.cpp`:

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. Add `Flag::f_tcpo_only` to the built-in DC flags.

Keep the client patch minimal: endpoint, RSA key, and TCP-only flags only.

## Multi-Device Smoke Test

Use separate client working directories so sessions do not share local `tdata`:

```powershell
$tdesktop = "C:\path\to\tdesktop\out\Debug\Telegram.exe"
Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-alice")
Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob")
```

Log in with different phone numbers. In local development, the login code is
`12345` unless you changed `TELESRV_DEV_AUTH_CODE`.

Recommended checks:

- 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

- [Compatibility matrix](docs/compatibility-matrix.md)
- [Telegram Desktop patch notes](docs/tdesktop-patch-notes.md)
- [Persistence layer](docs/persistence-layer.md)
- [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,
new Telegram client version reports, 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.