remote_settings/
lib.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 std::{collections::HashMap, fs::File, io::prelude::Write, sync::Arc};
6
7use error_support::{convert_log_report_error, handle_error};
8
9pub mod cache;
10pub mod client;
11pub mod config;
12pub mod context;
13pub mod error;
14pub mod schema;
15pub mod service;
16#[cfg(feature = "signatures")]
17pub(crate) mod signatures;
18pub mod storage;
19
20pub(crate) mod jexl_filter;
21mod macros;
22
23pub use client::{Attachment, RemoteSettingsRecord, RemoteSettingsResponse, RsJsonObject};
24pub use config::{BaseUrl, RemoteSettingsConfig, RemoteSettingsConfig2, RemoteSettingsServer};
25pub use context::RemoteSettingsContext;
26pub use error::{trace, ApiResult, RemoteSettingsError, Result};
27
28use client::Client;
29use error::Error;
30use storage::Storage;
31
32uniffi::setup_scaffolding!("remote_settings");
33
34/// Application-level Remote Settings manager.
35///
36/// This handles application-level operations, like syncing all the collections, and acts as a
37/// factory for creating clients.
38#[derive(uniffi::Object)]
39pub struct RemoteSettingsService {
40    // This struct adapts server::RemoteSettingsService into the public API
41    internal: service::RemoteSettingsService,
42}
43
44#[uniffi::export]
45impl RemoteSettingsService {
46    /// Construct a [RemoteSettingsService]
47    ///
48    /// This is typically done early in the application-startup process.
49    ///
50    /// This method performs no IO or network requests and is safe to run in a main thread that
51    /// can't be blocked.
52    ///
53    /// `storage_dir` is a directory to store SQLite files in -- one per collection. If the
54    /// directory does not exist, it will be created when the storage is first used. Only the
55    /// directory and the SQLite files will be created, any parent directories must already exist.
56    #[uniffi::constructor]
57    pub fn new(storage_dir: String, config: RemoteSettingsConfig2) -> Self {
58        Self {
59            internal: service::RemoteSettingsService::new(storage_dir, config),
60        }
61    }
62
63    /// Create a new Remote Settings client
64    ///
65    /// This method performs no IO or network requests and is safe to run in a main thread that can't be blocked.
66    pub fn make_client(&self, collection_name: String) -> Arc<RemoteSettingsClient> {
67        self.internal.make_client(collection_name)
68    }
69
70    /// Sync collections for all active clients
71    #[handle_error(Error)]
72    pub fn sync(&self) -> ApiResult<Vec<String>> {
73        self.internal.sync()
74    }
75
76    /// Update the remote settings config
77    ///
78    /// This will cause all current and future clients to use new config and will delete any stored
79    /// records causing the clients to return new results from the new config.
80    ///
81    /// Only intended for QA/debugging.  Swapping the remote settings server in the middle of
82    /// execution can cause weird effects.
83    #[handle_error(Error)]
84    pub fn update_config(&self, config: RemoteSettingsConfig2) -> ApiResult<()> {
85        self.internal.update_config(config)
86    }
87}
88
89/// Client for a single Remote Settings collection
90///
91/// Use [RemoteSettingsService::make_client] to create these.
92#[derive(uniffi::Object)]
93pub struct RemoteSettingsClient {
94    // This struct adapts client::RemoteSettingsClient into the public API
95    internal: client::RemoteSettingsClient,
96}
97
98#[uniffi::export]
99impl RemoteSettingsClient {
100    /// Collection this client is for
101    pub fn collection_name(&self) -> String {
102        self.internal.collection_name().to_owned()
103    }
104
105    /// Get the current set of records.
106    ///
107    /// This method normally fetches records from the last sync.  This means that it returns fast
108    /// and does not make any network requests.
109    ///
110    /// If records have not yet been synced it will return None.  Use `sync_if_empty = true` to
111    /// change this behavior and perform a network request in this case.  That this is probably a
112    /// bad idea if you want to fetch the setting in application startup or when building the UI.
113    ///
114    /// None will also be returned on disk IO errors or other unexpected errors.  The reason for
115    /// this is that there is not much an application can do in this situation other than fall back
116    /// to the same default handling as if records have not been synced.
117    ///
118    /// Application-services schedules regular dumps of the server data for specific collections.
119    /// For these collections, `get_records` will never return None.  If you would like to add your
120    /// collection to this list, please reach out to the DISCO team.
121    #[uniffi::method(default(sync_if_empty = false))]
122    pub fn get_records(&self, sync_if_empty: bool) -> Option<Vec<RemoteSettingsRecord>> {
123        match self.internal.get_records(sync_if_empty) {
124            Ok(records) => records,
125            Err(e) => {
126                // Log/report the error
127                trace!("get_records error: {e}");
128                convert_log_report_error(e);
129                // Throw away the converted result and return None, there's nothing a client can
130                // really do with an error except treat it as the None case
131                None
132            }
133        }
134    }
135
136    /// Get the current set of records as a map of record_id -> record.
137    ///
138    /// See [Self::get_records] for an explanation of when this makes network requests, error
139    /// handling, and how the `sync_if_empty` param works.
140    #[uniffi::method(default(sync_if_empty = false))]
141    pub fn get_records_map(
142        &self,
143        sync_if_empty: bool,
144    ) -> Option<HashMap<String, RemoteSettingsRecord>> {
145        self.get_records(sync_if_empty)
146            .map(|records| records.into_iter().map(|r| (r.id.clone(), r)).collect())
147    }
148
149    /// Get attachment data for a remote settings record
150    ///
151    /// Attachments are large binary blobs used for data that doesn't fit in a normal record.  They
152    /// are handled differently than other record data:
153    ///
154    ///   - Attachments are not downloaded in [RemoteSettingsService::sync]
155    ///   - This method will make network requests if the attachment is not cached
156    ///   - This method will throw if there is a network or other error when fetching the
157    ///     attachment data.
158    #[handle_error(Error)]
159    pub fn get_attachment(&self, record: &RemoteSettingsRecord) -> ApiResult<Vec<u8>> {
160        self.internal.get_attachment(record)
161    }
162
163    #[handle_error(Error)]
164    pub fn sync(&self) -> ApiResult<()> {
165        self.internal.sync()
166    }
167
168    /// Shutdown the client, releasing the SQLite connection used to cache records.
169    pub fn shutdown(&self) {
170        self.internal.shutdown()
171    }
172}
173
174impl RemoteSettingsClient {
175    /// Create a new client.  This is not exposed to foreign code, consumers need to call
176    /// [RemoteSettingsService::make_client]
177    fn new(
178        base_url: BaseUrl,
179        bucket_name: String,
180        collection_name: String,
181        #[allow(unused)] context: Option<RemoteSettingsContext>,
182        storage: Storage,
183    ) -> Self {
184        Self {
185            internal: client::RemoteSettingsClient::new(
186                base_url,
187                bucket_name,
188                collection_name,
189                context,
190                storage,
191            ),
192        }
193    }
194}
195
196#[derive(uniffi::Object)]
197pub struct RemoteSettings {
198    pub config: RemoteSettingsConfig,
199    client: Client,
200}
201
202#[uniffi::export]
203impl RemoteSettings {
204    /// Construct a new Remote Settings client with the given configuration.
205    #[uniffi::constructor]
206    #[handle_error(Error)]
207    pub fn new(remote_settings_config: RemoteSettingsConfig) -> ApiResult<Self> {
208        Ok(RemoteSettings {
209            config: remote_settings_config.clone(),
210            client: Client::new(remote_settings_config)?,
211        })
212    }
213
214    /// Fetch all records for the configuration this client was initialized with.
215    #[handle_error(Error)]
216    pub fn get_records(&self) -> ApiResult<RemoteSettingsResponse> {
217        let resp = self.client.get_records()?;
218        Ok(resp)
219    }
220
221    /// Fetch all records added to the server since the provided timestamp,
222    /// using the configuration this client was initialized with.
223    #[handle_error(Error)]
224    pub fn get_records_since(&self, timestamp: u64) -> ApiResult<RemoteSettingsResponse> {
225        let resp = self.client.get_records_since(timestamp)?;
226        Ok(resp)
227    }
228
229    /// Download an attachment with the provided id to the provided path.
230    #[handle_error(Error)]
231    pub fn download_attachment_to_path(
232        &self,
233        attachment_id: String,
234        path: String,
235    ) -> ApiResult<()> {
236        let resp = self.client.get_attachment(&attachment_id)?;
237        let mut file = File::create(path).map_err(Error::AttachmentFileError)?;
238        file.write_all(&resp).map_err(Error::AttachmentFileError)?;
239        Ok(())
240    }
241}
242
243// Public functions that we don't expose via UniFFI.
244//
245// The long-term plan is to create a new remote settings client, transition nimbus + suggest to the
246// new API, then delete this code.
247impl RemoteSettings {
248    /// Fetches all records for a collection that can be found in the server,
249    /// bucket, and collection defined by the [ClientConfig] used to generate
250    /// this [Client]. This function will return the raw viaduct [Response].
251    #[handle_error(Error)]
252    pub fn get_records_raw(&self) -> ApiResult<viaduct::Response> {
253        self.client.get_records_raw()
254    }
255
256    /// Downloads an attachment from [attachment_location]. NOTE: there are no
257    /// guarantees about a maximum size, so use care when fetching potentially
258    /// large attachments.
259    #[handle_error(Error)]
260    pub fn get_attachment(&self, attachment_location: &str) -> ApiResult<Vec<u8>> {
261        self.client.get_attachment(attachment_location)
262    }
263}
264
265#[cfg(test)]
266mod test {
267    use super::*;
268    use crate::RemoteSettingsRecord;
269    use mockito::{mock, Matcher};
270
271    #[test]
272    fn test_get_records() {
273        viaduct_reqwest::use_reqwest_backend();
274        let m = mock(
275            "GET",
276            "/v1/buckets/the-bucket/collections/the-collection/records",
277        )
278        .with_body(response_body())
279        .with_status(200)
280        .with_header("content-type", "application/json")
281        .with_header("etag", "\"1000\"")
282        .create();
283
284        let config = RemoteSettingsConfig {
285            server: Some(RemoteSettingsServer::Custom {
286                url: mockito::server_url(),
287            }),
288            server_url: None,
289            bucket_name: Some(String::from("the-bucket")),
290            collection_name: String::from("the-collection"),
291        };
292        let remote_settings = RemoteSettings::new(config).unwrap();
293
294        let resp = remote_settings.get_records().unwrap();
295
296        assert!(are_equal_json(JPG_ATTACHMENT, &resp.records[0]));
297        assert_eq!(1000, resp.last_modified);
298        m.expect(1).assert();
299    }
300
301    #[test]
302    fn test_get_records_since() {
303        viaduct_reqwest::use_reqwest_backend();
304        let m = mock(
305            "GET",
306            "/v1/buckets/the-bucket/collections/the-collection/records",
307        )
308        .match_query(Matcher::UrlEncoded("gt_last_modified".into(), "500".into()))
309        .with_body(response_body())
310        .with_status(200)
311        .with_header("content-type", "application/json")
312        .with_header("etag", "\"1000\"")
313        .create();
314
315        let config = RemoteSettingsConfig {
316            server: Some(RemoteSettingsServer::Custom {
317                url: mockito::server_url(),
318            }),
319            server_url: None,
320            bucket_name: Some(String::from("the-bucket")),
321            collection_name: String::from("the-collection"),
322        };
323        let remote_settings = RemoteSettings::new(config).unwrap();
324
325        let resp = remote_settings.get_records_since(500).unwrap();
326        assert!(are_equal_json(JPG_ATTACHMENT, &resp.records[0]));
327        assert_eq!(1000, resp.last_modified);
328        m.expect(1).assert();
329    }
330
331    // This test was designed as a proof-of-concept and requires a locally-run Remote Settings server.
332    // If this were to be included in CI, it would require pulling the RS docker image and scripting
333    // its configuration, as well as dynamically finding the attachment id, which would more closely
334    // mimic a real world usecase.
335    // #[test]
336    #[allow(dead_code)]
337    fn test_download() {
338        viaduct_reqwest::use_reqwest_backend();
339        let config = RemoteSettingsConfig {
340            server: Some(RemoteSettingsServer::Custom {
341                url: "http://localhost:8888".into(),
342            }),
343            server_url: None,
344            bucket_name: Some(String::from("the-bucket")),
345            collection_name: String::from("the-collection"),
346        };
347        let remote_settings = RemoteSettings::new(config).unwrap();
348
349        remote_settings
350            .download_attachment_to_path(
351                "d3a5eccc-f0ca-42c3-b0bb-c0d4408c21c9.jpg".to_string(),
352                "test.jpg".to_string(),
353            )
354            .unwrap();
355    }
356
357    fn are_equal_json(str: &str, rec: &RemoteSettingsRecord) -> bool {
358        let r1: RemoteSettingsRecord = serde_json::from_str(str).unwrap();
359        &r1 == rec
360    }
361
362    fn response_body() -> String {
363        format!(
364            r#"
365        {{
366            "data": [
367                {},
368                {},
369                {}
370            ]
371          }}"#,
372            JPG_ATTACHMENT, PDF_ATTACHMENT, NO_ATTACHMENT
373        )
374    }
375
376    const JPG_ATTACHMENT: &str = r#"
377          {
378            "title": "jpg-attachment",
379            "content": "content",
380            "attachment": {
381            "filename": "jgp-attachment.jpg",
382            "location": "the-bucket/the-collection/d3a5eccc-f0ca-42c3-b0bb-c0d4408c21c9.jpg",
383            "hash": "2cbd593f3fd5f1585f92265433a6696a863bc98726f03e7222135ff0d8e83543",
384            "mimetype": "image/jpeg",
385            "size": 1374325
386            },
387            "id": "c5dcd1da-7126-4abb-846b-ec85b0d4d0d7",
388            "schema": 1677694447771,
389            "last_modified": 1677694949407
390          }
391        "#;
392
393    const PDF_ATTACHMENT: &str = r#"
394          {
395            "title": "with-attachment",
396            "content": "content",
397            "attachment": {
398                "filename": "pdf-attachment.pdf",
399                "location": "the-bucket/the-collection/5f7347c2-af92-411d-a65b-f794f9b5084c.pdf",
400                "hash": "de1cde3571ef3faa77ea0493276de9231acaa6f6651602e93aa1036f51181e9b",
401                "mimetype": "application/pdf",
402                "size": 157
403            },
404            "id": "ff301910-6bf5-4cfe-bc4c-5c80308661a5",
405            "schema": 1677694447771,
406            "last_modified": 1677694470354
407          }
408        "#;
409
410    const NO_ATTACHMENT: &str = r#"
411          {
412            "title": "no-attachment",
413            "content": "content",
414            "schema": 1677694447771,
415            "id": "7403c6f9-79be-4e0c-a37a-8f2b5bd7ad58",
416            "last_modified": 1677694455368
417          }
418        "#;
419}