ferogram-session

Session persistence types and pluggable storage backends for ferogram.

Session persistence for ferogram. ferogram re-exports everything from here, so existing code needs no changes. You only need to depend on this directly if you're building something that uses session storage without the full client.

For installation instructions see the ferogram README.

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, and dc_for(dc_id, prefer_ipv6) picks the right one.
• MTProto update counters: pts, qts, seq, date, and per-channel pts
• Peer access-hash cache for users, channels, groups, and Communities, tracked separately from channels via is_community so a Community is never mistaken for a supergroup on the wire
• Min-user message contexts for InputPeerUserFromMessage

The binary format is versioned. load() handles all previous versions. save() always writes the current version. Saves are atomic: written to a .tmp file first, then renamed into place.

Call PersistedSession::stats() for a breakdown (peer counts by kind, DCs with negotiated keys, approximate serialized size). Useful for spotting a bloated min_peers cache before it needs pruning.

String Sessions

Two formats are supported. Both are accepted by Client::builder().session_string("...") which auto-detects the format.

Compact (V1/V2)

Exported by client.export_session_string(). Encodes dc_id, ip, port, user_id, and auth key only. Good for serverless or portable deployments.

let s = client.export_session_string().await?;
Client::builder().session_string(&s).connect().await?;

Native (full state)

Exported by client.export_native_session_string(). Includes the full DC table, update counters (PTS, QTS, seq), and peer cache. Use when you need to resume update processing from exactly where you left off.

let s = client.export_native_session_string().await?;
Client::builder().session_string(&s).connect().await?;

Backends

BinaryFileBackend

Default. Saves the session as a binary file on disk.

use ferogram_session::BinaryFileBackend;
let backend = BinaryFileBackend::new("ferogram.session");

InMemoryBackend

No persistence, lives only for the process lifetime. Good for tests or quick scripts.

use ferogram_session::InMemoryBackend;
let backend = InMemoryBackend::new();

StringSessionBackend

Stores the session as a base64 string. Useful when you can't write to disk.

use ferogram_session::StringSessionBackend;
let backend = StringSessionBackend::new(std::env::var("SESSION").unwrap_or_default());

SqliteBackend (feature: sqlite-session)

use ferogram_session::SqliteBackend;
let backend = SqliteBackend::open("sessions.db")?;
let backend = SqliteBackend::in_memory()?; // tests, no disk

LibSqlBackend (feature: libsql-session)

Local file or in-process in-memory, no remote server needed:

use ferogram_session::LibSqlBackend;
let backend = LibSqlBackend::open_local("sessions.db")?;
let backend = LibSqlBackend::in_memory()?; // tests, no disk

Remote Turso and embedded replicas need the libsql-remote-session feature on top of libsql-session:

use ferogram_session::LibSqlBackend;

// Talk to a remote Turso database directly.
let backend = LibSqlBackend::open_remote(url, auth_token)?;

// Local file that stays synced with a remote Turso database.
// Reads hit the local replica; writes sync to the remote.
let backend = LibSqlBackend::open_replica("sessions.db", url, auth_token)?;

sqlite-session and libsql-remote-session can't be enabled together, both pull in a sqlite3 C source and the build fails at link time. Pick one.

Custom Backends

Implement SessionBackend to add your own storage:

use ferogram_session::{SessionBackend, PersistedSession};
use std::io;

struct RedisBackend { /* ... */ }

impl SessionBackend for RedisBackend {
    fn save(&self, session: &PersistedSession) -> io::Result<()> { todo!() }
    fn load(&self) -> io::Result<Option<PersistedSession>> { todo!() }
    fn delete(&self) -> io::Result<()> { todo!() }
    fn name(&self) -> &str { "redis" }
}

Feature flags

Stack position

ferogram
└ ferogram-session  <-- here

License

This project is licensed under either the MIT License or Apache License 2.0, at your option. See LICENSE-MIT and LICENSE-APACHE for details.

Author: Ankit Chaubey (@ankit-chaubey)