Skip to main content

Crate ferogram_session

Crate ferogram_session 

Source
Expand description

Session persistence types and storage backends for ferogram.

This crate is part of ferogram, an async Rust MTProto client built by Ankit Chaubey.

Most users do not use this crate directly. The ferogram crate wires it up automatically when you call Client::builder().session(...) or .session_string(...).

§What it stores

  • DC address table with per-DC auth keys, salts, and capability flags (DcFlags: IPv6, media-only, TCP-obfuscated-only, CDN, static). Both IPv4 and IPv6 entries can be kept for the same DC; PersistedSession::dc_for picks the right one for a given prefer_ipv6.
  • MTProto update counters: pts, qts, seq, date, and per-channel pts.
  • Peer access-hash cache for users, channels, groups, and Communities. Communities are tracked separately via is_community so they are never mistaken for a supergroup on reload.
  • Min-user message contexts for InputPeerUserFromMessage.

Call PersistedSession::stats for a SessionStats breakdown, peer counts by kind, DCs with a negotiated auth key, approximate serialized size, useful for spotting a bloated min_peers cache before it needs pruning.

§What’s in here

  • PersistedSession: the serializable session struct. Holds the DC table, update sequence counters, and the peer access-hash cache.
  • SessionBackend: the trait all backends implement: save, load, delete, name.
  • BinaryFileBackend: stores the session as a binary file on disk. Default backend. Saves are atomic, written to a .tmp file then renamed.
  • InMemoryBackend: keeps everything in memory. Nothing survives process exit. Used for tests and ephemeral tasks.
  • StringSessionBackend: serializes the session to a base64 string. Useful for serverless environments where you store state in an env var or database column. Load it with Client::builder().session_string(s).
  • SqliteBackend: SQLite-backed storage via rusqlite, behind the sqlite-session feature. open for a file, in_memory for tests.
  • LibSqlBackend: libSQL storage, behind libsql-session. open_local and in_memory work with no remote server. open_remote (a live Turso connection) and open_replica (a local file kept synced with Turso) need libsql-remote-session on top, and can’t be combined with sqlite-session, both link a sqlite3 C source and the build fails at link time.

You can also implement SessionBackend yourself for Redis, PostgreSQL, or anything else.

§String sessions

Two formats, both accepted by Client::builder().session_string("..."), which auto-detects which one it got.

  • Compact (export_session_string()): dc_id, ip, port, user_id, and auth key only. Good for serverless or portable deployments.
  • Native (export_native_session_string()): full DC table, update counters, and peer cache. Use it when you need to resume update processing from exactly where you left off.

§Binary format

The file backends start with a version byte:

  • 0x01: legacy (DC table only, no update state or peer cache).
  • 0x02: current (DC table + update state + peer cache).
  • 0x06: adds per-channel ChannelKind byte to each peer entry.
  • 0x07: adds future_auth_token for fast re-login after sign_out().
  • 0x08: adds a per-peer is_community byte, marking Telegram Community entities so they no longer collapse into a plain channel on reload.

load() handles all versions. save() always writes v8.

§Example: export and re-import a session

ⓘ
// Export
let s = client.export_session_string().await?;

// Later, in another process or after a restart:
let (client, _) = ferogram::Client::builder()
    .api_id(12345)
    .api_hash("api_hash")
    .session_string(s)
    .connect()
    .await?;

Re-exports§

pub use string_session::FullSession;
pub use string_session::Session;
pub use string_session::StringSession;
pub use string_session::StringSessionError;

Modules§

string_session
Portable compact string-session encoding/decoding (V1/V2 binary base64).

Structs§

BinaryFileBackend
Stores the session in a compact binary file (v2 format).
CachedMinPeer
A min-user context entry: the user was seen with min=true (access_hash not usable directly) so we store the peer+message where they appeared so that InputPeerUserFromMessage can be constructed on restart.
CachedPeer
A cached access-hash entry so that the peer can be addressed across restarts without re-resolving it from Telegram.
DcEntry
One entry in the DC address table.
DcFlags
Per-DC option flags.
InMemoryBackend
Ephemeral in-process session: nothing persisted to disk.
PersistedSession
Everything that needs to survive a process restart.
SessionStats
A breakdown of what a PersistedSession currently holds.
SqliteBackendsqlite-session
SQLite-backed session (via rusqlite).
StringSessionBackend
Portable base64 string session backend.
UpdatesStateSnap
Snapshot of the MTProto update-sequence state that we persist so that catch_up: true can call updates.getDifference with the pre-shutdown pts.

Enums§

ChannelKind
The kind of a Telegram channel, persisted in the session so that is_megagroup() / is_broadcast() work correctly after a restart.
UpdateStateChange
A single update-sequence change, applied via SessionBackend::apply_update_state.

Traits§

SessionBackend
Synchronous snapshot backend: saves and loads the full session at once.

Functions§

default_dc_addresses
Bootstrap DC address table (fallback if GetConfig fails).