nuclight/teleperl

Purpose and Entry Points

Teleperl is a pure-Perl client library for Telegram’s MTProto protocol and Telegram API, with example interactive, bot, transfer, CLI, and minimal GUI applications. Main runnable entry points include cli.pl, auth.pl, bot.pl, download.pl, upload.pl, and tkx.pl. Authentication creates a session used by applications.

Protocol Transport and MTProto Core

MTProto.pm is the low-level protocol layer: it owns Telegram transport/session behavior and depends on generated MTProto TL objects. Network integration is asynchronous through AnyEvent and SOCKS support, represented by AnyEvTkx.pm and AnyEventSocks.pm. This is the boundary between application code and Telegram data centers/proxies.

Telegram API Client Layer

Telegram.pm builds Telegram API operations above MTProto and generated schema constructors. Application-facing scripts and higher-level state managers should invoke Telegram API objects rather than construct transport messages directly. The selected generated schema layer materially determines compatibility with Telegram servers.

TL Schema, Parsing, and Code Generation

Telegram’s type language is parsed and compiled into Perl packages. tl.yp defines the Yapp parser; tl-gen.pl generates MTProto.pm-adjacent protocol types and Telegram.pm API types from schemas. Input schemas live in res/mtproto.tl and versioned API files such as res/layer82-tdesktop.tl. TL/Object.pm provides the common TL object representation/runtime. Generated files are a deliberate compatibility boundary: changing layers may require client logic changes.

Authentication and Cryptography

Authorization and secret-handling infrastructure is concentrated in TeleCrypt/Keys.pm and TeleCrypt/SRP.pm, supporting Telegram key exchange and SRP-related flows. auth.pl is the operational login entry point, obtaining an SMS/session code and persisting a reusable session. Cryptographic primitives come from OpenSSL Perl bindings and random/bignum dependencies.

Client State, Persistence, and Updates

The Teleperl namespace contains stateful client support around the raw API: Teleperl/Storage.pm persists local state/session-related data, Teleperl/PeerCache.pm resolves and caches Telegram peers, and Teleperl/UpdateManager.pm receives/processes update streams. These components isolate long-lived local client state and asynchronous server updates from one-shot API calls.

CLI Application Framework

cli.pl hosts an interactive command application built on CLI/Framework.pm. Command dispatch and command implementations are separated under CLI/Framework/Command.pm and CLI/Framework/Command/, including authentication-facing, inspection, configuration, and console commands. This framework is an application shell over the Teleperl/Telegram layers, not the protocol implementation itself.

Optional Interfaces and Utilities

tkx.pl/ClifTg.pm provide the minimal Tcl/Tk proof-of-work GUI path, while scripts such as cborlog.pl, cborpack.pl, and cborsee.pl support optional CBOR-based logging/inspection workflows. Runtime configuration is expected externally, based on teleperl.example.conf, including API credentials, phone number, and optional proxy settings.