Struct WebExtStorageStore

pub struct WebExtStorageStore { /* private fields */ }

A store is used to access storage.sync data. It manages an underlying database connection, and exposes methods for reading and writing storage items scoped to an extension ID. Each item is a JSON object, with one or more string keys, and values of any type that can serialize to JSON.

An application should create only one store, and manage the instance as a singleton. While this isn’t enforced, if you make multiple stores pointing to the same database file, you are going to have a bad time: each store will create its own database connection, using up extra memory and CPU cycles, and causing write contention. For this reason, you should only call Store::new() (or webext_store_new(), from the FFI) once.

Note that our Db implementation is behind an Arc<> because we share that connection with our sync engines - ie, these engines also hold an Arc<> around the same object.

Implementations

impl WebExtStorageStore

pub fn new(db_path: impl AsRef<Path>) -> Result<Self>

Creates a store backed by a database at db_path. The path can be a file path or file: URI.

pub fn interrupt_handle(&self) -> Arc<SqlInterruptHandle>

Returns an interrupt handle for this store.

pub fn set(&self, ext_id: &str, val: JsonValue) -> Result<StorageChanges>

Sets one or more JSON key-value pairs for an extension ID. Returns a list of changes, with existing and new values for each key in val.

pub fn usage(&self) -> Result<Vec<UsageInfo>>

Returns information about per-extension usage

pub fn get(&self, ext_id: &str, keys: JsonValue) -> Result<JsonValue>

Returns the values for one or more keys keys can be:

• null, in which case all key-value pairs for the extension are returned, or an empty object if the extension doesn’t have any stored data.
• A single string key, in which case an object with only that key and its value is returned, or an empty object if the key doesn’t
• An array of string keys, in which case an object with only those keys and their values is returned. Any keys that don’t exist will be omitted.
• An object where the property names are keys, and each value is the default value to return if the key doesn’t exist.

This method always returns an object (that is, a serde_json::Value::Object).

pub fn remove(&self, ext_id: &str, keys: JsonValue) -> Result<StorageChanges>

Deletes the values for one or more keys. As with get, keys can be either a single string key, or an array of string keys. Returns a list of changes, where each change contains the old value for each deleted key.

pub fn clear(&self, ext_id: &str) -> Result<StorageChanges>

Deletes all key-value pairs for the extension. As with remove, returns a list of changes, where each change contains the old value for each deleted key.

pub fn get_bytes_in_use(&self, ext_id: &str, keys: JsonValue) -> Result<u64>

Returns the bytes in use for the specified items (which can be null, a string, or an array)

pub fn close(&self) -> Result<()>

Closes the store and its database connection. See the docs for StorageDb::close for more details on when this can fail.

pub fn get_synced_changes(&self) -> Result<Vec<SyncedExtensionChange>>

Gets the changes which the current sync applied. Should be used immediately after the bridged engine is told to apply incoming changes, and can be used to notify observers of the StorageArea of the changes that were applied. The result is a Vec of already JSON stringified changes.

pub fn migrate(&self, filename: impl AsRef<Path>) -> Result<()>

Migrates data from a database in the format of the “old” kinto implementation. Information about how the migration went is stored in the database, and can be read using Self::take_migration_info.

Note that filename isn’t normalized or canonicalized.

pub fn take_migration_info(&self) -> Result<Option<MigrationInfo>>

Read-and-delete (e.g. take in rust parlance, see Option::take) operation for any MigrationInfo stored in this database.

impl WebExtStorageStore

pub fn bridged_engine(self: Arc<Self>) -> Arc<WebExtStorageBridgedEngine>