🚀 Telemt Control API V1

Telemt now provides a production-grade Control Plane HTTP API for runtime visibility and safe configuration management.

The MTProto data-plane remains fully isolated.

API Features

1. Dedicated Control Plane

• HTTP/1.1 JSON API (/v1)
• Strict success/error envelopes
• Optimistic concurrency (If-Match with config SHA-256 revision)
• Atomic config mutations
• read_only safety mode

2. Zero-Cost Observability

GET /v1/stats/zero/all

• Pure atomic counter export
• No hotpath impact
• No additional locks
• Core, upstream, middle-proxy, pool, and desync counters

Safe to enable in production without performance risk.

3. Minimal Runtime Snapshots (Feature-Gated)

GET /v1/stats/minimal/all

Disabled by default.

When enabled:

• ME writers state
• Per-DC coverage & availability
• Pool generations
• Floor policy runtime
• Reconnect/backoff settings
• Quarantine state
• Active network path selection

Read-lock only. Optional TTL cache.

If disabled:

• Returns 200 OK
• enabled=false
• Stable JSON contract

4. ME & DC Status Endpoints

• GET /v1/stats/me-writers
• GET /v1/stats/dcs

Coverage and availability percentages included:

• coverage_pct = alive_writers / required_writers * 100
• available_pct = available_endpoints / configured_endpoints * 100

Alias behavior respects minimal feature toggle.

5. Full User Management API

• Create user
• Patch user
• Rotate secret
• Delete user (last user protected)
• Runtime user stats included
• Auto-generated tg://proxy links

All mutations:

• Validate before write
• Persist atomically
• Return updated config revision

Security Model

• Explicit API enable switch
• IP whitelist
• Optional exact-match Authorization header
• Request size limit
• Built-in read_only mode
• No built-in TLS (recommended: loopback + reverse proxy)

Design Principles

• Data-plane isolation
• Config is authoritative
• Fail-fast validation
• Stable JSON contracts
• Zero-cost vs minimal-cost separation
• No automatic policy decisions

Telemt remains a deterministic single-node edge system.

Configuration

Under [server.api]:

• enabled
• listen
• whitelist
• auth_header
• request_body_limit_bytes
• minimal_runtime_enabled
• minimal_runtime_cache_ttl_ms
• read_only

Changes require restart.

Versioning

• API prefix: /v1
• Backward compatibility preserved
• server.admin_api supported as alias

This release formalizes Telemt’s control plane while preserving hotpath performance guarantees: explore details about our API at API.md

What's Changed

• API + Runtime Stats by @axkurcom in #306

Full Changelog: 3.1.6...3.2.0