ferogram_connect/
lib.rs

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

ferogram_connect/
lib.rs
