[T3ST3ST3R0N]

What this adds

A new MTPROTO backend type that runs the telemt MTProto proxy (an external Rust binary) as a node managed subprocess. It is mutually exclusive with xray and wireguard, following the existing one backend at a time model.

Changes

• proto: BackendType.MTPROTO, a Mtproto proxy message (secret, user_ad_tag, max_tcp_conns, expiration_rfc3339, data_quota_bytes, max_unique_ips), and Proxy.mtproto
• backend/mtproto: parses the panel JSON config and renders telemt TOML, manages the telemt subprocess (run, reload, version), uses telemt's REST control API for user create/patch/delete, scrapes the Prometheus endpoint for per user traffic, tracks per user up/down deltas with reset and counter restart handling, and injects a sentinel user because telemt refuses to start with an empty [access.users]
• controller: MTPROTO start case
• config: TELEMT_EXECUTABLE_PATH
• build: pinned make install_telemt target (telemt 3.4.19) and Dockerfile.mtproto
• tests: unit tests plus an env gated integration test (MTPROTO_TELEMT_BIN)

Verification

Builds and vets clean, unit tests pass. The integration test was run against a real telemt 3.4.19 and confirms process start, version, user create/patch/delete/get, online IP list, system stats, and the empty users sentinel path.

Per user traffic and online count stats come from telemt's Prometheus endpoint, which only binds once telemt's data plane is up (it needs Telegram connectivity). Those paths were verified at the unit level and kept best effort in the integration test, so they should be confirmed once more on a host with Telegram egress.

Panel side (separate change, not in this PR)

The panel needs to send a JSON telemt config, set the backend type to MTPROTO, tag MTProto users with the configured inbound_tag, populate proxies.mtproto.secret (and optional limits), and build the proxy links.

Notes

telemt ships releases roughly weekly. The version is pinned in the Makefile and Dockerfile so it can be bumped deliberately.

Summary by CodeRabbit

• New Features
  • Added MTProto backend support with TeleMT process lifecycle management, user synchronization (including optional sentinel behavior), and metrics/online statistics.
  • Extended the service API to support the MTProto backend type and MTProto proxy settings.
  • Added Docker and build tooling to run TeleMT via a pinned static binary.
• Chores
  • Documented and wired TELEMT_EXECUTABLE_PATH (default: /usr/local/bin/telemt) for selecting the TeleMT binary.
• Tests
  • Added MTProto unit tests and environment-gated integration tests for lifecycle, user sync, and metrics parsing.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 97b39b09-7dec-4f37-b3a8-e981fa4a8a45

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Adds an MTProto backend around the external telemt binary. The change set covers schema and config wiring, telemt process lifecycle management, API and metrics clients, traffic tracking, TOML rendering, controller integration, and supporting build and test updates.

Changes

MTProto Backend

Layer / File(s)	Summary
Schema, config, and telemt install setup common/service.proto, config/config.go, .env.example, Makefile, Dockerfile.mtproto	BackendType gains MTPROTO = 2; Mtproto and Proxy.mtproto are added; TelemtExecutablePath is loaded from TELEMT_EXECUTABLE_PATH with a default path, .env.example documents the setting, and telemt-specific build/install variables plus a multi-stage Docker build are added.
MTProto config parsing and TOML rendering backend/mtproto/config.go, backend/mtproto/toml.go	Parses and validates MTProto JSON config input, extracts inbound_tag, renders managed API/access sections, filters common users into runtime MTProto users, and serializes the resulting map to TOML.
telemt process, API, metrics, and traffic accounting backend/mtproto/process.go, backend/mtproto/process_unix.go, backend/mtproto/process_windows.go, backend/mtproto/client.go, backend/mtproto/metrics.go, backend/mtproto/tracker.go	Implements telemt process lifecycle management, the HTTP JSON API client, Prometheus scraping, and in-memory traffic accounting with reset and restart handling.
MTProto backend controller and runtime sync backend/mtproto/mtproto.go, controller/controller.go	Constructs the MTProto backend, manages the telemt process and desired-user state, applies user sync and restart flows, and serves backend stats and online-state queries.
Unit and integration tests backend/mtproto/mtproto_test.go, backend/mtproto/integration_test.go	Covers config parsing, user selection, rendering, traffic tracking, metrics parsing, latency output, backend lifecycle, and empty-user startup behavior.

Sequence Diagram(s)

sequenceDiagram
    participant Controller
    participant MTProto
    participant processManager
    participant apiClient
    participant metricsScraper

    Controller->>MTProto: New(ctx, cfg, mtConfig, users)
    MTProto->>processManager: newProcessManager(executable, config, pid)
    MTProto->>processManager: Start()
    MTProto->>apiClient: Health() via waitForHealth()
    MTProto-->>Controller: *MTProto

    Controller->>MTProto: SyncUser(ctx, user)
    MTProto->>apiClient: upsertUser / deleteUser

    Controller->>MTProto: SyncUsers(ctx, users)
    MTProto->>processManager: Reload() or Restart()
    MTProto->>apiClient: waitForRuntimeUsers()

    Controller->>MTProto: GetStats(ctx, request)
    MTProto->>metricsScraper: Scrape(ctx)
    metricsScraper-->>MTProto: per-user metrics
    MTProto->>MTProto: trafficTracker.Sync() and stat aggregation

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Poem

🐇 I hop through tunnels, bright and neat,
Telemt sings with busy feet.
TOML twirls, the stats run round,
New MTProto burrows in the ground.
When users come or users part,
This bunny grins with a coder’s heart.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 3.39% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a new MTProto proxy backend powered by telemt.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 10

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/mtproto/config.go`:
- Around line 62-67: The trailing JSON check in NewConfig is too permissive
because decoder.Decode(&extra) leaves extra nil for a trailing null, so multiple
JSON documents can slip through. Update the logic around the decoder.Decode
handling in config.go to explicitly detect any successful second decode,
including null, and reject it as a second JSON value rather than relying on
extra != nil. Keep the existing error path and use the NewConfig trailing-decode
flow to ensure only exactly one JSON object is accepted.

In `@backend/mtproto/integration_test.go`:
- Around line 91-93: The GetUser assertion in the integration test only checks
for any error, so it can pass on the wrong failure mode. Update the test around
mt.apiClient.GetUser to assert the returned error is apiStatusError.NotFound()
specifically, using the existing NotFound helper/matcher already used in this
package. Keep the check focused on the removed-user case rather than treating
any non-nil error as success.

In `@backend/mtproto/mtproto_test.go`:
- Around line 35-38: The mtproto_test.go failure check for NewConfig can panic
because it dereferences cfg inside the t.Fatalf path when cfg is nil. Update the
test around NewConfig and the custom inbound tag assertion so it first handles
err (and nil cfg) before referencing cfg.InboundTag, keeping the failure message
in the mtproto_test.go test case informative without risking a nil-pointer
panic.

In `@backend/mtproto/mtproto.go`:
- Around line 103-105: The startup failure path in MTProto construction
currently calls process shutdown directly and bypasses the cleanup logic in
MTProto.Shutdown(), which leaves log resources uncleared when New returns nil.
Update the failure handling in New to invoke mt.Shutdown() instead of
mt.process.Shutdown(), so the full teardown path runs, including CloseLogs() and
any other cleanup owned by MTProto.
- Around line 511-516: The removal convergence check in the mtproto transition
logic is only comparing `previousDesired` against `desired`, so the sentinel
account can be missed when moving from zero desired users to real users. Update
the `expectedAbsent`/convergence logic in `mtproto.go` to explicitly account for
the sentinel runtime user in addition to `previousDesired`, and make sure the
check in this flow rejects success until the sentinel is actually removed.
- Around line 625-634: The rendered telemt config is being written with
world-readable permissions, which exposes the API bearer token and MTProto
secrets. Update writeFileAtomic so the temporary file written by os.WriteFile
uses private permissions instead of 0644, and ensure the surrounding write path
in mtproto.go preserves those restricted permissions when the file is renamed.
Focus on the writeFileAtomic helper and its temp file creation.
- Around line 585-602: The sentinel user creation in newSentinelUser currently
falls back to predictable Username and Secret values when rand.Read fails, so
change it to fail closed by returning an error instead of constructing a
runtimeUser with deterministic bytes. Update New to handle the new error return
from newSentinelUser and propagate it to the caller rather than continuing
startup with known credentials. Make sure any call sites or tests that reference
newSentinelUser or New are adjusted to expect the error path.

In `@backend/mtproto/process.go`:
- Around line 135-136: The log channel is being closed while the stdout/stderr
scanner goroutines may still be sending, which can panic during normal shutdown.
Update the shutdown flow in process.go around process.Start/captureLogs and the
CloseLogs path so p.captureLogs(stdout) and p.captureLogs(stderr) finish before
p.logs is closed, or keep p.logs open for the full manager lifetime. Use the
existing captureLogs and CloseLogs symbols to locate the fix and ensure
process.Shutdown/MTProto.Shutdown cannot race with pending log sends.
- Around line 66-82: `detectVersion()` and `Reload()` currently wait on
`CombinedOutput()` without any deadline, so a stuck `telemt` process can block
startup or reload indefinitely. Update the command creation path in
`processManager` to use a context-aware command (for example via
`exec.CommandContext`) for both the version check and reload execution, and
apply a short timeout appropriate for these operations. Make sure the timeout is
enforced in both `detectVersion` and `Reload`, and return a distinct
timeout-related error so callers can distinguish it from generic command
failures.

In `@Dockerfile.mtproto`:
- Around line 21-31: The runtime stage in the Dockerfile currently leaves the
container running as root, so update the final stage to create and switch to a
dedicated non-root user before ENTRYPOINT. Keep the existing COPY steps for main
and telemt, then add ownership/permission setup as needed and switch user in the
runtime image so the container no longer executes as root; reference the final
stage around FROM alpine:latest, COPY, and ENTRYPOINT.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 48cc9f9f-74c5-4b6a-8547-e4a25311cfbe

📥 Commits

Reviewing files that changed from the base of the PR and between e0031a2 and caf7481.

⛔ Files ignored due to path filters (2)

• common/service.pb.go is excluded by !**/*.pb.go
• common/service_grpc.pb.go is excluded by !**/*.pb.go

📒 Files selected for processing (17)

• .env.example
• Dockerfile.mtproto
• Makefile
• backend/mtproto/client.go
• backend/mtproto/config.go
• backend/mtproto/integration_test.go
• backend/mtproto/metrics.go
• backend/mtproto/mtproto.go
• backend/mtproto/mtproto_test.go
• backend/mtproto/process.go
• backend/mtproto/process_unix.go
• backend/mtproto/process_windows.go
• backend/mtproto/toml.go
• backend/mtproto/tracker.go
• common/service.proto
• config/config.go
• controller/controller.go

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Drop root in the runtime stage.

The final image never switches away from root, so a compromise in either main or telemt gets full root privileges inside the container. Add a dedicated runtime user here; if you need privileged ports, grant only CAP_NET_BIND_SERVICE at deploy time instead of keeping the whole container root.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Dockerfile.mtproto` around lines 21 - 31, The runtime stage in the Dockerfile
currently leaves the container running as root, so update the final stage to
create and switch to a dedicated non-root user before ENTRYPOINT. Keep the
existing COPY steps for main and telemt, then add ownership/permission setup as
needed and switch user in the runtime image so the container no longer executes
as root; reference the final stage around FROM alpine:latest, COPY, and
ENTRYPOINT.

Source: Linters/SAST tools

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/mtproto/client.go`:
- Around line 72-79: `telemtPatchUserRequest` is omitting zero/empty fields, so
`UpdateUsers()` cannot clear existing telemt settings during a PATCH. Update the
request model and patch flow in `UpdateUsers()` to preserve explicit clears for
`UserAdTag`, `ExpirationRFC3339`, and the limit/quota fields, either by
switching those fields to pointers/nullable values or by adding a separate
clear-path so omitted values are not re-sent as old state.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0b8b481a-cd91-45bf-96ea-cc5e38d17b49

📥 Commits

Reviewing files that changed from the base of the PR and between caf7481 and fc734c2.

⛔ Files ignored due to path filters (2)

• common/service.pb.go is excluded by !**/*.pb.go
• common/service_grpc.pb.go is excluded by !**/*.pb.go

📒 Files selected for processing (17)

• .env.example
• Dockerfile.mtproto
• Makefile
• backend/mtproto/client.go
• backend/mtproto/config.go
• backend/mtproto/integration_test.go
• backend/mtproto/metrics.go
• backend/mtproto/mtproto.go
• backend/mtproto/mtproto_test.go
• backend/mtproto/process.go
• backend/mtproto/process_unix.go
• backend/mtproto/process_windows.go
• backend/mtproto/toml.go
• backend/mtproto/tracker.go
• common/service.proto
• config/config.go
• controller/controller.go

✅ Files skipped from review due to trivial changes (1)

• .env.example

🚧 Files skipped from review as they are similar to previous changes (8)

• config/config.go
• backend/mtproto/process_windows.go
• backend/mtproto/integration_test.go
• common/service.proto
• backend/mtproto/process_unix.go
• controller/controller.go
• backend/mtproto/tracker.go
• Makefile

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== client.go around telemtPatchUserRequest ==\n'
sed -n '60,110p' backend/mtproto/client.go

printf '\n== buildPatchUserRequest ==\n'
sed -n '160,210p' backend/mtproto/client.go

printf '\n== mtproto.go around upsertUser ==\n'
sed -n '1,220p' backend/mtproto/mtproto.go

printf '\n== search for PatchUser / telemtPatchUserRequest usage ==\n'
rg -n "PatchUser|telemtPatchUserRequest|buildPatchUserRequest|UpdateUsers|upsertUser" backend/mtproto

Repository: PasarGuard/node

Length of output: 9240

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== runtimeUser definition and transforms ==\n'
rg -n "type runtimeUser|func .*runtimeUser|optionalPositive|ExpirationRFC3339|UserAdTag|MaxTCPConns|MaxUniqueIPs|DataQuotaBytes" backend/mtproto/client.go backend/mtproto/mtproto.go backend/mtproto/*.go

printf '\n== buildNextDesiredLocked / applyFullDesiredLocked / upsertUser ==\n'
sed -n '300,430p' backend/mtproto/mtproto.go

printf '\n== any clear/reset/delete calls in apiClient ==\n'
rg -n "CreateUser|PatchUser|DeleteUser|Reset|Clear|UpdateUser" backend/mtproto/*.go

Repository: PasarGuard/node

Length of output: 16123

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '209,285p' backend/mtproto/config.go

Repository: PasarGuard/node

Length of output: 2549

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== search for telemt API docs / handlers ==\n'
rg -n "PatchUser|patch user|user_ad_tag|max_tcp_conns|expiration_rfc3339|data_quota_bytes|max_unique_ips|omitempty" -g '!**/*_test.go' .

printf '\n== list likely doc files ==\n'
git ls-files | rg '(^|/)(README|docs|openapi|swagger|api|telemt|mtproto).*'

Repository: PasarGuard/node

Length of output: 17128

---

PATCH drops explicit clears for runtime limits
telemtPatchUserRequest omits zero/empty values, so a partial update can’t clear an existing user_ad_tag, expiration_rfc3339, or limit/quota field on an already-created user. UpdateUsers() will PATCH the old telemt values back into place instead of removing them. Fix by sending explicit zero/empty values on patch, or by using pointer fields / a separate clear path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend/mtproto/client.go` around lines 72 - 79, `telemtPatchUserRequest` is
omitting zero/empty fields, so `UpdateUsers()` cannot clear existing telemt
settings during a PATCH. Update the request model and patch flow in
`UpdateUsers()` to preserve explicit clears for `UserAdTag`,
`ExpirationRFC3339`, and the limit/quota fields, either by switching those
fields to pointers/nullable values or by adding a separate clear-path so omitted
values are not re-sent as old state.

[T3ST3ST3R0N]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/mtproto/mtproto.go`:
- Line 645: The deferred temp-file cleanup in mtproto.go should explicitly
ignore the removal error to satisfy errcheck. Update the deferred
os.Remove(tempPath) cleanup in the affected mtproto logic to use a best-effort
wrapper that discards the returned error intentionally, keeping the cleanup
behavior while making the ignore explicit.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f48cad09-0c52-4681-96c2-a3a30c5cd85b

📥 Commits

Reviewing files that changed from the base of the PR and between fc734c2 and 746cd2f.

📒 Files selected for processing (5)

• backend/mtproto/config.go
• backend/mtproto/integration_test.go
• backend/mtproto/mtproto.go
• backend/mtproto/mtproto_test.go
• backend/mtproto/process.go

🚧 Files skipped from review as they are similar to previous changes (4)

• backend/mtproto/integration_test.go
• backend/mtproto/mtproto_test.go
• backend/mtproto/config.go
• backend/mtproto/process.go

[T3ST3ST3R0N]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[T3ST3ST3R0N]

Superseded by #120, which ports this onto dev and includes the review fixes.