Struct FileProtocolStateStorage 

pub struct FileProtocolStateStorage { /* private fields */ }

Protocol-state storage in plain files, in the format the Python, Swift and Kotlin providers write.

A record lives at <root>/<namespace>/t_<sha256(type)>/k_<sha256(type, id)> and carries its own key in a header (see the module docs), so every file is attributable and a read verifies it opened the record it asked for. The directory is portable: a store written by the Python binding opens here for the same account, and the reverse.

Values are stored verbatim. The engine seals every category that can carry message plaintext or key material before it reaches this trait, so those arrive as ciphertext under the record key held in the MLS store. Record keys are peer and message ids and are not sealed; the file names are an unsalted digest of them, so anyone who can list the directory can confirm a guessed id. Directories are created owner-only for that reason.

Implementations

impl FileProtocolStateStorage

pub fn open( root: impl AsRef<Path>, namespace: &str, ) -> Result<Self, FileStoreError>

Opens (creating if needed) the store at <root>/<namespace>/.

namespace must be super::account_storage_namespace of the application id and profile; anything else is refused before a directory is created. root should be a directory the host removes when the installation is removed: protocol state is scoped to an installation, and a store that outlives it resends settled work.

A second store over the same directory is refused with FileStoreError::InUse until this one is closed or dropped.

Examples found in repository

examples/replicated_notes.rs (line 53)

fn open_stores(
    root: &std::path::Path,
    key: &dyn StoreKeyProvider,
) -> Result<(Arc<SealedFileMlsStorage>, Arc<FileProtocolStateStorage>), Box<dyn std::error::Error>>
{
    let namespace = account_storage_namespace(APP_ID, PROFILE);
    // Two roots: MLS material may outlive an installation, protocol state
    // must not.
    let secure = SealedFileMlsStorage::open(root.join("keys"), &namespace, key)?;
    let records = FileProtocolStateStorage::open(root.join("state"), &namespace)?;
    Ok((Arc::new(secure), Arc::new(records)))
}

pub fn close(&self)

Releases the directory and refuses every later operation.

The lock goes at once, whoever still holds the store. An operation in flight finishes first. Afterwards every operation is an error naming the directory, and a new store may open over it. Closing twice is closing once.

pub fn sealed_state( &self, secure: &dyn MlsStorage, ) -> Result<SealedState, FileStoreError>

What the record key secure holds makes of the sealed records here.

Read-only on both stores: nothing is deleted, and no record key is generated. A record whose framing does not parse is passed over, since it says nothing about any key. A record that cannot be read at all is an FileStoreError::Io, and a record key the MLS store cannot read (as opposed to one it does not hold, or holds damaged) is an FileStoreError::RecordKeyUnreadable: neither is taken for an answer.

pub fn directory(&self) -> &Path

The directory this store owns.

pub fn holds_records( root: impl AsRef<Path>, namespace: &str, ) -> Result<bool, FileStoreError>

Whether <root>/<namespace>/ holds protocol state, without opening, creating or locking anything.

A record file in a type directory, which is where this store and every binding’s provider put a record. Not the lock file an open leaves, not a type directory every record has since been deleted from, and not what the MLS store leaves in a directory the two were wrongly made to share: none of those is state a new identity could strand. A directory that cannot be read, at either level, is an FileStoreError::Io, never “no state”.

Trait Implementations

impl Debug for FileProtocolStateStorage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ProtocolStateStorage for FileProtocolStateStorage

fn store( &self, key_type: &str, key_id: &str, data: &[u8], ) -> ProtocolStateResult<()>

Atomically stores or replaces one protocol-state entry.

fn load( &self, key_type: &str, key_id: &str, ) -> ProtocolStateResult<Option<Vec<u8>>>

Loads one protocol-state entry, returning None when absent.

fn delete(&self, key_type: &str, key_id: &str) -> ProtocolStateResult<()>

Deletes one protocol-state entry and succeeds when it is already absent.

fn list_keys(&self, key_type: &str) -> ProtocolStateResult<Vec<String>>

Lists entry IDs within one protocol-state category.