ferogram-session

Session persistence types and pluggable storage backends for ferogram.

Session persistence for ferogram. Extracted in v0.3.7 so you can swap, extend, or use session storage without pulling in the full client.

ferogram re-exports everything from here, so existing code needs no changes.

Installation

[dependencies]
ferogram-session = "0.5.0"

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 session string 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. Use for serverless or portable deployments.

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

// import
Client::builder()
    .session_string(&s)
    .connect()
    .await?;

Encode/decode manually if needed:

use ferogram_session::{StringSession, StringSessionError};

let ss = StringSession::decode("AGQy...")?;
println!("dc={} user={}", ss.session().dc_id, ss.session().user_id);
println!("{}", ss.encode());

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

// restore
Client::builder()
    .session_string(&s)
    .connect()
    .await?;

Backends

BinaryFileBackend

Default backend. 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 cannot write to disk.

use ferogram_session::StringSessionBackend;

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

SqliteBackend (feature: sqlite-session)

ferogram-session = { version = "0.5.0", features = ["sqlite-session"] }

use ferogram_session::SqliteBackend;

let backend = SqliteBackend::open("sessions.db")?;

LibSqlBackend (feature: libsql-session)

ferogram-session = { version = "0.5.0", features = ["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