webext_storage/store.rs
1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5use crate::api::{self, StorageChanges};
6use crate::db::{StorageDb, ThreadSafeStorageDb};
7use crate::error::*;
8use crate::migration::{migrate, MigrationInfo};
9use crate::sync;
10use std::path::Path;
11use std::sync::Arc;
12
13use interrupt_support::SqlInterruptHandle;
14use serde_json::Value as JsonValue;
15
16/// A store is used to access `storage.sync` data. It manages an underlying
17/// database connection, and exposes methods for reading and writing storage
18/// items scoped to an extension ID. Each item is a JSON object, with one or
19/// more string keys, and values of any type that can serialize to JSON.
20///
21/// An application should create only one store, and manage the instance as a
22/// singleton. While this isn't enforced, if you make multiple stores pointing
23/// to the same database file, you are going to have a bad time: each store will
24/// create its own database connection, using up extra memory and CPU cycles,
25/// and causing write contention. For this reason, you should only call
26/// `Store::new()` (or `webext_store_new()`, from the FFI) once.
27///
28/// Note that our Db implementation is behind an Arc<> because we share that
29/// connection with our sync engines - ie, these engines also hold an Arc<>
30/// around the same object.
31pub struct WebExtStorageStore {
32 pub(crate) db: Arc<ThreadSafeStorageDb>,
33}
34
35impl WebExtStorageStore {
36 /// Creates a store backed by a database at `db_path`. The path can be a
37 /// file path or `file:` URI.
38 pub fn new(db_path: impl AsRef<Path>) -> Result<Self> {
39 let db = StorageDb::new(db_path)?;
40 Ok(Self {
41 db: Arc::new(ThreadSafeStorageDb::new(db)),
42 })
43 }
44
45 /// Creates a store backed by an in-memory database.
46 #[cfg(test)]
47 pub fn new_memory(db_path: &str) -> Result<Self> {
48 let db = StorageDb::new_memory(db_path)?;
49 Ok(Self {
50 db: Arc::new(ThreadSafeStorageDb::new(db)),
51 })
52 }
53
54 /// Returns an interrupt handle for this store.
55 pub fn interrupt_handle(&self) -> Arc<SqlInterruptHandle> {
56 self.db.interrupt_handle()
57 }
58
59 /// Sets one or more JSON key-value pairs for an extension ID. Returns a
60 /// list of changes, with existing and new values for each key in `val`.
61 pub fn set(&self, ext_id: &str, val: JsonValue) -> Result<StorageChanges> {
62 let db = &self.db.lock();
63 let conn = db.get_connection()?;
64 let tx = conn.unchecked_transaction()?;
65 let result = api::set(&tx, ext_id, val)?;
66 tx.commit()?;
67 Ok(result)
68 }
69
70 /// Returns information about per-extension usage
71 pub fn usage(&self) -> Result<Vec<crate::UsageInfo>> {
72 let db = &self.db.lock();
73 let conn = db.get_connection()?;
74 api::usage(conn)
75 }
76
77 /// Returns the values for one or more keys `keys` can be:
78 ///
79 /// - `null`, in which case all key-value pairs for the extension are
80 /// returned, or an empty object if the extension doesn't have any
81 /// stored data.
82 /// - A single string key, in which case an object with only that key
83 /// and its value is returned, or an empty object if the key doesn't
84 // exist.
85 /// - An array of string keys, in which case an object with only those
86 /// keys and their values is returned. Any keys that don't exist will be
87 /// omitted.
88 /// - An object where the property names are keys, and each value is the
89 /// default value to return if the key doesn't exist.
90 ///
91 /// This method always returns an object (that is, a
92 /// `serde_json::Value::Object`).
93 pub fn get(&self, ext_id: &str, keys: JsonValue) -> Result<JsonValue> {
94 // Don't care about transactions here.
95 let db = &self.db.lock();
96 let conn = db.get_connection()?;
97 api::get(conn, ext_id, keys)
98 }
99
100 /// Deletes the values for one or more keys. As with `get`, `keys` can be
101 /// either a single string key, or an array of string keys. Returns a list
102 /// of changes, where each change contains the old value for each deleted
103 /// key.
104 pub fn remove(&self, ext_id: &str, keys: JsonValue) -> Result<StorageChanges> {
105 let db = &self.db.lock();
106 let conn = db.get_connection()?;
107 let tx = conn.unchecked_transaction()?;
108 let result = api::remove(&tx, ext_id, keys)?;
109 tx.commit()?;
110 Ok(result)
111 }
112
113 /// Deletes all key-value pairs for the extension. As with `remove`, returns
114 /// a list of changes, where each change contains the old value for each
115 /// deleted key.
116 pub fn clear(&self, ext_id: &str) -> Result<StorageChanges> {
117 let db = &self.db.lock();
118 let conn = db.get_connection()?;
119 let tx = conn.unchecked_transaction()?;
120 let result = api::clear(&tx, ext_id)?;
121 tx.commit()?;
122 Ok(result)
123 }
124
125 /// Returns the bytes in use for the specified items (which can be null,
126 /// a string, or an array)
127 pub fn get_bytes_in_use(&self, ext_id: &str, keys: JsonValue) -> Result<u64> {
128 let db = &self.db.lock();
129 let conn = db.get_connection()?;
130 Ok(api::get_bytes_in_use(conn, ext_id, keys)? as u64)
131 }
132
133 /// Closes the store and its database connection. See the docs for
134 /// `StorageDb::close` for more details on when this can fail.
135 pub fn close(&self) -> Result<()> {
136 let mut db = self.db.lock();
137 db.close()
138 }
139
140 /// Gets the changes which the current sync applied. Should be used
141 /// immediately after the bridged engine is told to apply incoming changes,
142 /// and can be used to notify observers of the StorageArea of the changes
143 /// that were applied.
144 /// The result is a Vec of already JSON stringified changes.
145 pub fn get_synced_changes(&self) -> Result<Vec<sync::SyncedExtensionChange>> {
146 let db = self.db.lock();
147 sync::get_synced_changes(&db)
148 }
149
150 /// Migrates data from a database in the format of the "old" kinto
151 /// implementation. Information about how the migration went is stored in
152 /// the database, and can be read using `Self::take_migration_info`.
153 ///
154 /// Note that `filename` isn't normalized or canonicalized.
155 pub fn migrate(&self, filename: impl AsRef<Path>) -> Result<()> {
156 let db = &self.db.lock();
157 let conn = db.get_connection()?;
158 let tx = conn.unchecked_transaction()?;
159 let result = migrate(&tx, filename.as_ref())?;
160 tx.commit()?;
161 // Failing to store this information should not cause migration failure.
162 if let Err(e) = result.store(conn) {
163 debug_assert!(false, "Migration error: {:?}", e);
164 warn!("Failed to record migration telmetry: {}", e);
165 }
166 Ok(())
167 }
168
169 /// Read-and-delete (e.g. `take` in rust parlance, see Option::take)
170 /// operation for any MigrationInfo stored in this database.
171 pub fn take_migration_info(&self) -> Result<Option<MigrationInfo>> {
172 let db = &self.db.lock();
173 let conn = db.get_connection()?;
174 let tx = conn.unchecked_transaction()?;
175 let result = MigrationInfo::take(&tx)?;
176 tx.commit()?;
177 Ok(result)
178 }
179}
180
181#[cfg(test)]
182pub mod test {
183 use super::*;
184 #[test]
185 fn test_send() {
186 fn ensure_send<T: Send>() {}
187 // Compile will fail if not send.
188 ensure_send::<WebExtStorageStore>();
189 }
190
191 pub fn new_mem_store() -> WebExtStorageStore {
192 WebExtStorageStore {
193 db: Arc::new(ThreadSafeStorageDb::new(crate::db::test::new_mem_db())),
194 }
195 }
196}