State Management & Persistence

Overview

whatsapp-rust uses a strict state management architecture to ensure consistency and prevent race conditions. All device state modifications must go through the PersistenceManager using the DeviceCommand pattern.

Critical: Never modify Device state directly. Always use DeviceCommand + PersistenceManager::process_command() for writes, or get_device_snapshot() for reads.

Architecture

The state management system has three main components:

src/store/
├── persistence_manager.rs  # Central state coordinator
├── commands.rs             # DeviceCommand pattern
├── device.rs              # Device state structure
└── backend/               # Storage backend (SQLite)

Device State

The Device struct holds all client state (defined in wacore::store::device):

#[derive(Clone, Serialize, Deserialize)]
pub struct Device {
    pub pn: Option<Jid>,              // Phone number JID
    pub lid: Option<Jid>,             // Linked Identity JID
    pub registration_id: u32,
    #[serde(with = "key_pair_serde")]
    pub noise_key: KeyPair,           // Noise protocol keypair
    #[serde(with = "key_pair_serde")]
    pub identity_key: KeyPair,        // Signal protocol identity
    #[serde(with = "key_pair_serde")]
    pub signed_pre_key: KeyPair,
    pub signed_pre_key_id: u32,
    #[serde(with = "BigArray")]
    pub signed_pre_key_signature: [u8; 64],
    pub adv_secret_key: [u8; 32],
    #[serde(with = "account_serde", default)]
    pub account: Option<Arc<wa::ADVSignedDeviceIdentity>>,
    pub push_name: String,
    pub app_version_primary: u32,
    pub app_version_secondary: u32,
    pub app_version_tertiary: u32,
    pub app_version_last_fetched_ms: i64,
    #[serde(skip)]
    pub device_props: wa::DeviceProps,  // Not persisted
    #[serde(skip)]
    pub client_profile: ClientProfile,  // Not persisted; noise-handshake identity
    #[serde(default)]
    pub edge_routing_info: Option<Vec<u8>>,
    #[serde(default)]
    pub props_hash: Option<String>,
    #[serde(default)]
    pub next_pre_key_id: u32,
    #[serde(default)]
    pub server_cert_chain: Option<CachedServerCertChain>,
}

Location: wacore/src/store/device.rs server_cert_chain caches the verified server cert chain returned by a successful XX (or XXfallback) handshake. Device exposes the leaf key on the next connect so do_handshake can attempt Noise IK and skip a server round trip. See WebSocket & Noise Protocol — Noise Protocol Handshake.

Serialization details

The Device struct uses several custom serde strategies:

Field	Strategy	Notes
`noise_key`, `identity_key`, `signed_pre_key`	`key_pair_serde`	Custom serde for Signal `KeyPair` types
`signed_pre_key_signature`	`BigArray`	Handles fixed-size arrays larger than 32 bytes
`account`	`account_serde`	Bridges buffa protobuf types to serde (see below)
`device_props`	`#[serde(skip)]`	Transient, not persisted
`client_profile`	`#[serde(skip)]`	Transient noise-handshake identity, not persisted
`edge_routing_info`, `props_hash`, `next_pre_key_id`, `server_cert_chain`	`#[serde(default)]`	Backward-compatible optional fields

The account field holds an ADVSignedDeviceIdentity (a buffa-generated protobuf type that lacks serde::Deserialize). The account_serde module bridges this gap by encoding the protobuf struct to bytes on serialization and decoding on deserialization:

pub mod account_serde {
    pub fn serialize<S: Serializer>(
        val: &Option<Arc<wa::ADVSignedDeviceIdentity>>, s: S,
    ) -> Result<S::Ok, S::Error> {
        // Encodes to protobuf bytes, then wraps as Option<Vec<u8>>
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(
        d: D,
    ) -> Result<Option<Arc<wa::ADVSignedDeviceIdentity>>, D::Error> {
        // Deserializes Option<Vec<u8>>, then decodes protobuf bytes
    }
}

The #[serde(default)] attribute on account ensures backward compatibility — data serialized before this field existed will deserialize with account: None.

PersistenceManager

The PersistenceManager is the gatekeeper for all state changes.

Architecture

pub struct PersistenceManager {
    device: Arc<tokio::sync::RwLock<Device>>,
    device_snapshot: std::sync::RwLock<Arc<Device>>,
    backend: Arc<dyn Backend>,
    dirty: Arc<AtomicBool>,
    save_notify: Arc<Notify>,
}

device_snapshot is rebuilt under the device write guard inside modify_device — the single mutation funnel — so it is always coherent with committed state. Location: src/store/persistence_manager.rs

Key Methods

Read-Only Access

// Returns the cached Arc<Device> snapshot — sync, no clone, no contention against writers
pub fn get_device_snapshot(&self) -> Arc<Device> {
    self.device_snapshot.read().unwrap().clone()
}

Location: src/store/persistence_manager.rs

State Modification

// Modify device state with a closure; rebuilds device_snapshot under the write guard
pub async fn modify_device<F, R>(&self, modifier: F) -> R
where
    F: FnOnce(&mut Device) -> R,
{
    let mut device_guard = self.device.write().await;
    let result = modifier(&mut device_guard);

    // Rebuild the cached snapshot before releasing the write lock
    *self.device_snapshot.write().unwrap() = Arc::new(device_guard.clone());

    // Mark dirty and notify background saver
    self.dirty.store(true, Ordering::Relaxed);
    self.save_notify.notify_one();

    result
}

Location: src/store/persistence_manager.rs

Command Processing

// Process a device command (preferred for state changes)
pub async fn process_command(&self, command: DeviceCommand) {
    self.modify_device(|device| {
        apply_command_to_device(device, command);
    }).await;
}

Location: src/store/persistence_manager.rs:145-150

Background Saver

The persistence manager runs a background task that periodically saves dirty state:

pub fn run_background_saver(self: Arc<Self>, interval: Duration) {
    tokio::spawn(async move {
        loop {
            tokio::select! {
                _ = self.save_notify.notified() => {
                    debug!("Save notification received.");
                }
                _ = sleep(interval) => {}
            }
            
            if let Err(e) = self.save_to_disk().await {
                error!("Error saving device state: {e}");
            }
        }
    });
}

How it works:

Wakes up when notified OR every interval (typically 30s)
Checks if state is dirty (dirty flag)
If dirty, serializes device state and saves to database
Clears dirty flag

Location: src/store/persistence_manager.rs:123-140

Initialization

pub async fn new(backend: Arc<dyn Backend>) -> Result<Self> {
    // Ensure device row exists in database
    let exists = backend.exists().await?;
    if !exists {
        let id = backend.create().await?;
        debug!("Created device row with id={id}");
    }
    
    // Load existing state or create new
    let device = if let Some(serializable_device) = backend.load().await? {
        let mut dev = Device::new(backend.clone());
        dev.load_from_serializable(serializable_device);
        dev
    } else {
        Device::new(backend.clone())
    };
    
    let snapshot = Arc::new(device.clone());
    Ok(Self {
        device: Arc::new(tokio::sync::RwLock::new(device)),
        device_snapshot: std::sync::RwLock::new(snapshot),
        backend,
        dirty: Arc::new(AtomicBool::new(false)),
        save_notify: Arc::new(Notify::new()),
    })
}

Location: src/store/persistence_manager.rs:23-55

DeviceCommand Pattern

The DeviceCommand enum defines all possible state mutations:

pub enum DeviceCommand {
    SetId(Option<Jid>),
    SetLid(Option<Jid>),
    SetPushName(String),
    SetAccount(Option<wa::ADVSignedDeviceIdentity>),
    SetAppVersion((u32, u32, u32)),
    SetDeviceProps(
        Option<String>,
        Option<wa::device_props::AppVersion>,
        Option<wa::device_props::PlatformType>,
    ),
    SetClientProfile(ClientProfile),
    SetPropsHash(Option<String>),
    SetNextPreKeyId(u32),
    SetLidMigrated(bool),
    /// Install a freshly rotated signed pre-key (WA Web `RotateKeyJob`). Sets
    /// the key trio and stamps the rotation cadence clock in one command so
    /// they can never be observed split.
    SetSignedPreKey {
        key_pair: KeyPair,
        id: u32,
        signature: [u8; 64],
        rotation_ms: i64,
    },
    /// Seed the rotation cadence baseline without touching the key. Used once
    /// for devices upgraded in with `last_signed_pre_key_rotation_ms == 0`, so
    /// the first rotation lands a full interval out instead of firing
    /// immediately on the next connect.
    SetSignedPreKeyRotationBaseline(i64),
}

Location: wacore/src/store/commands.rs

DeviceCommand cannot derive Debug once a variant holds a KeyPair — KeyPair deliberately omits Debug so private key material never formats into logs. The enum has a hand-written Debug impl instead; SetSignedPreKey’s logs only id and rotation_ms, redacting the key pair and signature via finish_non_exhaustive().

Why Commands?

The command pattern provides:

Type safety: All state changes are explicitly defined
Auditability: Easy to log/trace state mutations
Testability: Commands can be tested in isolation
Consistency: Single code path for all modifications
Future compatibility: Easy to add undo/redo or migration logic

Applying Commands

Commands are applied via pattern matching:

pub fn apply_command_to_device(device: &mut Device, command: DeviceCommand) {
    match command {
        DeviceCommand::SetId(id) => {
            device.pn = id;
        }
        DeviceCommand::SetLid(lid) => {
            device.lid = lid;
        }
        DeviceCommand::SetPushName(name) => {
            device.push_name = name;
        }
        DeviceCommand::SetAccount(account) => {
            device.account = account.map(std::sync::Arc::new);
        }
        DeviceCommand::SetAppVersion((p, s, t)) => {
            device.app_version_primary = p;
            device.app_version_secondary = s;
            device.app_version_tertiary = t;
        }
        DeviceCommand::SetLidMigrated(migrated) => {
            device.lid_migrated = migrated;
        }
        DeviceCommand::SetSignedPreKey { key_pair, id, signature, rotation_ms } => {
            device.signed_pre_key = key_pair;
            device.signed_pre_key_id = id;
            device.signed_pre_key_signature = signature;
            device.last_signed_pre_key_rotation_ms = rotation_ms;
        }
        DeviceCommand::SetSignedPreKeyRotationBaseline(rotation_ms) => {
            device.last_signed_pre_key_rotation_ms = rotation_ms;
        }
        // ... handle all variants
    }
}

SetLidMigrated gates outbound DM wire addressing (LID vs. PN) on whether the account is 1:1-LID-migrated. Runtime paths only ever set true — false is reserved for pair-success, where a fresh pairing of a different account must not inherit the previous account’s migration state. See Authentication — one-to-one LID migration state.

Location: wacore/src/store/commands.rs

Usage Patterns

Reading device state

// sync — no .await needed
let snapshot = persistence_manager.get_device_snapshot();
println!("Device JID: {:?}", snapshot.pn);
println!("Push name: {}", snapshot.push_name);

get_device_snapshot() is a plain fn (not async) and returns Arc<Device> — a refcount bump, no Device clone. Borrow fields directly from the held Arc; clone individual fields only when ownership escapes the scope. Don’t hold the snapshot across an await point — doing so pins an old allocation while the live state may have advanced.

Modifying device state (simple)

For simple state changes, use commands:

use wacore::store::commands::DeviceCommand;

// Update push name
persistence_manager.process_command(
    DeviceCommand::SetPushName("My New Name".to_string())
).await;

// Update props hash
persistence_manager.process_command(
    DeviceCommand::SetPropsHash(Some("new_hash".to_string()))
).await;

Modifying device state (complex)

For complex logic involving multiple fields or conditionals:

persistence_manager.modify_device(|device| {
    // Complex mutation logic
    device.push_name = "Updated Name".to_string();
    device.edge_routing_info = Some(new_routing_data);
}).await;

Keep the closure passed to modify_device as short as possible. It holds a write lock on the device state, blocking all other modifications.

Concurrency Patterns

RwLock Semantics

Device state uses two separate locks with different roles:

device_snapshot (std::sync::RwLock<Arc<Device>>): read by get_device_snapshot(). Readers never contend with writers — they take a brief std::sync read lock to clone the Arc, then release immediately. The snapshot is updated inside the tokio::sync::RwLock write guard in modify_device, so readers always see fully committed state.
device (tokio::sync::RwLock<Device>): write-locked inside modify_device(). Only store-adapter code that needs &mut Device trait access (get_device_arc()) takes a read lock here directly.

In practice: get_device_snapshot() is contention-free for readers, and the tokio write lock is only held during actual mutations (rare).

Session locks and message queues

The Client uses two cache-based lock mechanisms for per-chat and per-device serialization:

pub struct Client {
    /// Per-device session locks for Signal protocol operations.
    /// Prevents race conditions when multiple messages from the same sender
    /// are processed concurrently across different chats.
    /// Keys are Signal protocol address strings (e.g., "user@s.whatsapp.net:0")
    pub(crate) session_locks: Cache<String, Arc<async_lock::Mutex<()>>>,

    /// Per-chat lane combining enqueue lock + message queue into a single cached entry.
    /// One cache lookup instead of two per incoming message.
    pub(crate) chat_lanes: Cache<Jid, ChatLane>,
    // ...
}

Both use PortableCache with capacity-based eviction (configurable via CacheConfig), so stale entries are automatically cleaned up. On disconnect, chat_lanes is cleared via the async clear() to drop per-chat queue senders. This causes worker tasks from the old connection to exit via channel close, preventing them from surviving reconnects with outdated Signal session state that would cause decryption failures. See disconnect cleanup for the full list of resources reset on disconnect. Location: src/client.rs

Blocking Operations

CPU-heavy or blocking operations must use spawn_blocking to avoid stalling the async runtime:

use tokio::task::spawn_blocking;

// Bad: Blocks async runtime
let encrypted = expensive_crypto_operation(&data);

// Good: Offloads to thread pool
let encrypted = spawn_blocking(move || {
    expensive_crypto_operation(&data)
}).await?;

For more details on async patterns, see the Architecture guide.

Storage Backend

Backend Trait

The Backend trait is a combination of four domain-specific traits:

pub trait Backend: SignalStore + AppSyncStore + ProtocolStore + DeviceStore + Send + Sync {}

impl<T> Backend for T 
where 
    T: SignalStore + AppSyncStore + ProtocolStore + DeviceStore + Send + Sync
{}

See Storage Traits for the full trait definitions. Location: wacore/src/store/traits.rs

SQLite Implementation

The default storage backend uses SQLite with the Diesel ORM. See Storage Traits for details on SqliteStore, including connection pooling, WAL mode, and multi-device support. Location: storages/sqlite-storage/

Serialization

The Device struct derives Serialize and Deserialize (from serde) for persistence. The PersistenceManager handles serializing device state to the backend via the DeviceStore trait’s save() and load() methods.

Debugging State

Database Snapshots

The debug-snapshots feature enables database snapshots for debugging:

// In error handler
if let Err(e) = decrypt_message(...) {
    persistence_manager.create_snapshot(
        "decrypt_error",
        Some(error_details.as_bytes())
    ).await?;
    
    return Err(e);
}

This creates a timestamped copy of the database:

chats.db
chats_snapshot_decrypt_error_20260228_143022.db
chats_snapshot_decrypt_error_20260228_143022.txt  (metadata)

Location: src/store/persistence_manager.rs:99-121

Logging

State changes are logged at debug level:

RUST_LOG=whatsapp_rust::store=debug cargo run

Output:

[DEBUG] PersistenceManager: Ensuring device row exists.
[DEBUG] PersistenceManager: Loaded existing device data (PushName: 'Alice')
[DEBUG] Device state is dirty, saving to disk.
[DEBUG] Device state saved successfully.

Best Practices

1. Always use commands for state changes

// Bad: Direct modification
persistence_manager.modify_device(|device| {
    device.push_name = "New Name".to_string();
}).await;

// Good: Use command
persistence_manager.process_command(
    DeviceCommand::SetPushName("New Name".to_string())
).await;

2. Minimize lock duration

// Bad: Long lock duration
persistence_manager.modify_device(|device| {
    let data = expensive_calculation(&device.pn);  // Blocks all access!
    device.push_name = data;
}).await;

// Good: Release lock during expensive operation
let snapshot = persistence_manager.get_device_snapshot();
let data = expensive_calculation(&snapshot.pn);
persistence_manager.process_command(
    DeviceCommand::SetPushName(data)
).await;

3. Use chat locks for chat-specific operations

// Per-chat locks serialize operations on the same chat
// The Client uses session_locks and chat_lanes internally
// to prevent race conditions during message processing.

4. Offload heavy operations

use tokio::task::spawn_blocking;

// Crypto operations should use spawn_blocking
let ciphertext = spawn_blocking(move || {
    encrypt_message(&plaintext, &key)
}).await??;

Cache patching strategy

Beyond device state, whatsapp-rust maintains several in-memory caches (device registry, group metadata, LID-PN mappings) that require real-time updates when server notifications arrive.

Granular patching vs. invalidation

The client uses granular cache patching rather than the simpler invalidate-and-refetch approach. When a notification indicates a change (for example, a new device added or a group participant removed), the client reads the cached value, applies the diff in memory, and writes the updated value back — all without making any network requests. This avoids an extra IQ round-trip per update. If no cache entry exists when the notification arrives, the patch is silently skipped, and the next read fetches authoritative state from the server.

// Internal patching pattern (not a public API)
if let Some(mut cached) = cache.get(&key).await {
    cached.apply_change(notification_data);
    cache.insert(key, cached).await;
}

Concurrency model

The get → mutate → insert sequence is not atomic. A concurrent notification for the same key could race and cause one update to be lost. This is acceptable because:

The cache is best-effort — a full server fetch on the next read corrects any drift
Races are rare in practice (device and group notifications for the same user rarely overlap)
Device registry patches persist to the backend store immediately, so even if the cache entry is evicted, the persistent state is correct

Where patching is used

Cache	Patched on	Persisted	Fallback / conflict behavior
Device registry	Device add/remove/update notifications	Yes (backend store)	Hash-only notifications trigger full invalidation
Group metadata	Participant add/remove notifications and API calls	No (cache-only)	`leave()` and cache eviction trigger server re-fetch
LID-PN mappings	Directed sources overwrite; observational bulk sources only seed new LIDs (see `LearningSource`)	Yes (backend store)	Conflict: source-aware write policy gates overwrites; observational mismatches queue a live re-resolve

For full details including the write-policy gate, the live-query reconcile path, and data flow, see Granular cache patching.

Signal Protocol - Cryptographic state stored in Device
Binary Protocol - Protocol messages modify device state
WebSocket Handling - Connection state in Device
Storage - Cache patching and pluggable cache stores

References

Implementation: src/store/persistence_manager.rs
Commands: wacore/src/store/commands.rs
Device structure: wacore/src/store/device.rs
Backend trait: wacore/src/store/traits.rs
SQLite backend: storages/sqlite-storage/src/sqlite_store.rs

​Overview

​Architecture

​Device State

​Serialization details

​PersistenceManager

​Architecture

​Key Methods

​Read-Only Access

​State Modification

​Command Processing

​Background Saver

​Initialization

​DeviceCommand Pattern

​Why Commands?

​Applying Commands

​Usage Patterns

​Reading device state

​Modifying device state (simple)

​Modifying device state (complex)

​Concurrency Patterns

​RwLock Semantics

​Session locks and message queues

​Blocking Operations

​Storage Backend

​Backend Trait

​SQLite Implementation

​Serialization

​Debugging State

​Database Snapshots

​Logging

​Best Practices

​1. Always use commands for state changes

​2. Minimize lock duration

​3. Use chat locks for chat-specific operations

​4. Offload heavy operations

​Cache patching strategy

​Granular patching vs. invalidation

​Concurrency model

​Where patching is used

​Related Components

​References

Overview

Architecture

Device State

Serialization details

PersistenceManager

Architecture

Key Methods

Read-Only Access

State Modification

Command Processing

Background Saver

Initialization

DeviceCommand Pattern

Why Commands?

Applying Commands

Usage Patterns

Reading device state

Modifying device state (simple)

Modifying device state (complex)

Concurrency Patterns

RwLock Semantics

Session locks and message queues

Blocking Operations

Storage Backend

Backend Trait

SQLite Implementation

Serialization

Debugging State

Database Snapshots

Logging

Best Practices

1. Always use commands for state changes

2. Minimize lock duration

3. Use chat locks for chat-specific operations

4. Offload heavy operations

Cache patching strategy

Granular patching vs. invalidation

Concurrency model

Where patching is used

Related Components

References