ferogram-connect 0.6.5

Raw TCP connection, MTProto framing and transport for ferogram
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

/*
 * Copyright (c) 2026 Ankit Chaubey <ankitchaubey.dev@gmail.com>
 * https://github.com/ankit-chaubey
 *
 * Project: ferogram
 * Website: https://ferogram.dev
 *
 * Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
 * https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
 * <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
 * This file may not be copied, modified, or distributed except according
 * to those terms.
 */

#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc(html_root_url = "https://docs.rs/ferogram-connect/0.6.5")]
//! Raw TCP connection, MTProto framing, and transport for ferogram.
//!
//! This crate is part of [ferogram](https://crates.io/crates/ferogram), an async Rust
//! MTProto client built by [Ankit Chaubey](https://github.com/ankit-chaubey).
//!
//! - Channel: [t.me/Ferogram](https://t.me/Ferogram)
//! - Chat: [t.me/FerogramChat](https://t.me/FerogramChat)
//!
//! Most users do not need this crate directly. The `ferogram` crate wraps
//! everything. Use `ferogram-connect` only if you are building a custom
//! transport layer, an MTProxy relay, or need low-level control over how
//! frames are sent and received.
//!
//! # What's in here
//!
//! - **`connect_to_dc`**: Dials a Telegram DC, performs the MTProto
//!   handshake (auth key generation or reuse), and returns a [`Connection`]
//!   ready for encrypted RPC traffic.
//! - **[`TransportKind`]**: Selects the wire framing: Abridged,
//!   Intermediate, Full (default), Obfuscated2, PaddedIntermediate, or
//!   FakeTLS. Obfuscated variants are required for MTProxy and resist DPI.
//! - **[`FrameKind`]**: Runtime framing state attached to a live connection.
//!   Full transport tracks per-direction sequence numbers and CRC32;
//!   Obfuscated variants share an `Arc<Mutex<ObfuscatedCipher>>` so TX and
//!   RX run concurrently without a separate lock per direction.
//! - **`send_frame` / `recv_frame_plain`**: Frame serialisation and
//!   deserialisation helpers for the various transport shapes.
//! - **SOCKS5 / MTProxy**: [`Socks5Config`] and [`MtProxyConfig`] let you
//!   route connections through a proxy before the MTProto handshake.
//!   `Socks5Config::connect` needs the `socks5` feature; the config struct
//!   itself is always available.
//! - **PFS helpers**: [`decode_bind_response`] / [`decode_bind_single`]
//!   decode the `auth.bindTempAuthKey` response without pulling in the full
//!   TL schema crate.
//! - **Utilities**: [`gz_inflate`], [`maybe_gz_decompress`],
//!   [`build_container_body`], [`maybe_gz_pack`], [`crc32_ieee`], and
//!   friends used by the sender layer.
//!
//! # Example: establish a plain connection
//!
//! ```rust,no_run
//! use ferogram_connect::{TransportKind, connect_to_dc};
//!
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! // DC 2 production address; in practice load this from your session/config.
//! let (stream, frame_kind, session) =
//!     connect_to_dc("149.154.167.51:443", 2, &TransportKind::Full, None, None).await?;
//! println!("connected, salt={}", session.salt);
//! # let _ = (stream, frame_kind);
//! # Ok(())
//! # }
//! ```
//!
//! # Feature flags
//!
//! | Flag | What it enables |
//! |---|---|
//! | `socks5` | `Socks5Config::connect`, actually dialing out through a SOCKS5 proxy (pulls in `tokio-socks`) |

#![deny(unsafe_code)]

pub mod connection;
pub mod error;
pub mod frame;
pub mod pfs;
pub mod proxy;
pub mod race;
pub mod socks5;
pub mod tls_record;
pub mod transport;
pub mod transport_intermediate;
pub mod transport_kind;
pub mod transport_obfuscated;
pub mod util;

pub use connection::{Connection, FrameKind, FutureSalt, connect_to_dc};
pub use error::ConnectError;
pub use frame::{faketls_read_exact, send_frame};
pub use pfs::{decode_bind_response, decode_bind_single};
pub use proxy::MtProxyConfig;
pub use race::{RaceLeg, default_transport_race};
pub use socks5::Socks5Config;
pub use transport_intermediate::{
    FullTransport, IntermediateTransport, PaddedIntermediateTransport,
};
pub use transport_kind::TransportKind;
pub use transport_obfuscated::{ObfuscatedFraming, ObfuscatedStream};
pub use util::{crc32_ieee, gz_inflate, maybe_gz_decompress, random_i64, tl_read_bytes};

// Additional exports needed by ferogram crate
pub use connection::{NO_PING_DISCONNECT, PING_DELAY_SECS, SALT_USE_DELAY};
pub use frame::recv_frame_plain;

pub use util::{
    COMPRESSION_THRESHOLD, build_container_body, build_msgs_ack_body, gz_pack_body, jitter_delay,
    maybe_gz_pack, tl_read_string, tl_write_bytes,
};