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
• MTProto update counters: pts, qts, seq, date, and per-channel pts
• Peer access-hash cache for users, channels, and groups
• 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.

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")?;

LibSqlBackend (feature: libsql-session)

use ferogram_session::LibSqlBackend;
let backend = LibSqlBackend::open_local("sessions.db")?;

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

MIT or Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.

Ankit Chaubey - github.com/ankit-chaubey