ferogram_connect/
lib.rs

1// Copyright (c) Ankit Chaubey <ankitchaubey.dev@gmail.com>
2//
3// ferogram: async Telegram MTProto client in Rust
4// https://github.com/ankit-chaubey/ferogram
5//
6// Licensed under either the MIT License or the Apache License 2.0.
7// See the LICENSE-MIT or LICENSE-APACHE file in this repository:
8// https://github.com/ankit-chaubey/ferogram
9//
10// Feel free to use, modify, and share this code.
11// Please keep this notice when redistributing.
12
13#![cfg_attr(docsrs, feature(doc_cfg))]
14#![doc(html_root_url = "https://docs.rs/ferogram-connect/0.6.3")]
15//! Raw TCP connection, MTProto framing, and transport for ferogram.
16//!
17//! This crate is part of [ferogram](https://crates.io/crates/ferogram), an async Rust
18//! MTProto client built by [Ankit Chaubey](https://github.com/ankit-chaubey).
19//!
20//! - Channel: [t.me/Ferogram](https://t.me/Ferogram)
21//! - Chat: [t.me/FerogramChat](https://t.me/FerogramChat)
22//!
23//! Most users do not need this crate directly. The `ferogram` crate wraps
24//! everything. Use `ferogram-connect` only if you are building a custom
25//! transport layer, an MTProxy relay, or need low-level control over how
26//! frames are sent and received.
27//!
28//! # What's in here
29//!
30//! - **`connect_to_dc`**: Dials a Telegram DC, performs the MTProto
31//!   handshake (auth key generation or reuse), and returns a [`Connection`]
32//!   ready for encrypted RPC traffic.
33//! - **[`TransportKind`]**: Selects the wire framing: Abridged,
34//!   Intermediate, Full (default), Obfuscated2, PaddedIntermediate, or
35//!   FakeTLS. Obfuscated variants are required for MTProxy and resist DPI.
36//! - **[`FrameKind`]**: Runtime framing state attached to a live connection.
37//!   Full transport tracks per-direction sequence numbers and CRC32;
38//!   Obfuscated variants share an `Arc<Mutex<ObfuscatedCipher>>` so TX and
39//!   RX run concurrently without a separate lock per direction.
40//! - **`send_frame` / `recv_frame_plain`**: Frame serialisation and
41//!   deserialisation helpers for the various transport shapes.
42//! - **SOCKS5 / MTProxy**: [`Socks5Config`] and [`MtProxyConfig`] let you
43//!   route connections through a proxy before the MTProto handshake.
44//! - **PFS helpers**: [`decode_bind_response`] / [`decode_bind_single`]
45//!   decode the `auth.bindTempAuthKey` response without pulling in the full
46//!   TL schema crate.
47//! - **Utilities**: [`gz_inflate`], [`maybe_gz_decompress`],
48//!   [`build_container_body`], [`maybe_gz_pack`], [`crc32_ieee`], and
49//!   friends used by the sender layer.
50//!
51//! # Example: establish a plain connection
52//!
53//! ```rust,no_run
54//! use ferogram_connect::{TransportKind, connect_to_dc};
55//!
56//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
57//! // DC 2 production address; in practice load this from your session/config.
58//! let (stream, frame_kind, session) =
59//!     connect_to_dc("149.154.167.51:443", 2, &TransportKind::Full, None, None).await?;
60//! println!("connected, salt={}", session.salt);
61//! # let _ = (stream, frame_kind);
62//! # Ok(())
63//! # }
64//! ```
65
66#![deny(unsafe_code)]
67
68pub mod connection;
69pub mod error;
70pub mod frame;
71pub mod pfs;
72pub mod proxy;
73pub mod socks5;
74pub mod transport;
75pub mod transport_intermediate;
76pub mod transport_kind;
77pub mod transport_obfuscated;
78pub mod util;
79
80pub use connection::{Connection, FrameKind, FutureSalt, connect_to_dc};
81pub use error::ConnectError;
82pub use frame::send_frame;
83pub use pfs::{decode_bind_response, decode_bind_single};
84pub use proxy::MtProxyConfig;
85pub use socks5::Socks5Config;
86pub use transport_intermediate::{
87    FullTransport, IntermediateTransport, PaddedIntermediateTransport,
88};
89pub use transport_kind::TransportKind;
90pub use transport_obfuscated::{ObfuscatedFraming, ObfuscatedStream};
91pub use util::{crc32_ieee, gz_inflate, maybe_gz_decompress, random_i64, tl_read_bytes};
92
93// Additional exports needed by ferogram crate
94pub use connection::{NO_PING_DISCONNECT, PING_DELAY_SECS, SALT_USE_DELAY};
95pub use frame::recv_frame_plain;
96
97pub use util::{
98    COMPRESSION_THRESHOLD, build_container_body, build_msgs_ack_body, gz_pack_body, jitter_delay,
99    maybe_gz_pack, tl_read_string, tl_write_bytes,
100};
ferogram_connect/lib.rs

ferogram_connect/
lib.rs
