Struct remote_settings_client::client::Client

source · [−]

pub struct Client { /* private fields */ }

Expand description

Client to fetch Remote Settings data.

Examples

Create a Client for the cid collection on the production server:

let client = Client::builder()
  .collection_name("cid")
  .build()
  .unwrap();

Or for a specific server or bucket:

let client = Client::builder()
  .server_url("https://settings-cdn.stage.mozaws.net/v1")
  .bucket_name("main-preview")
  .collection_name("cid")
  .build()
  .unwrap();

Signature verification

When no verifier is explicitly specified, a dummy verifier is used.

`ring`

With the ring_verifier feature, a signature verifier leveraging the ring crate.

use remote_settings_client::RingVerifier;

let client = Client::builder()
  .collection_name("cid")
  .verifier(Box::new(RingVerifier {}))
  .build()
  .unwrap();

`rc_crypto`

With the rc_crypto feature, a signature verifier leveraging the rc_crypto crate.

use remote_settings_client::RcCryptoVerifier;

let client = Client::builder()
  .collection_name("cid")
  .verifier(Box::new(RcCryptoVerifier {}))
  .build()
  .unwrap();

In order to use it, the NSS library must be available.

export NSS_DIR=/path/to/nss
export NSS_STATIC=1

cargo build --features=rc_crypto_verifier

See detailed NSS installation instructions.

Custom

See Verification for implementing a custom signature verifier.

Attachments

Attachments associated with records can be downloaded.

let mut client = Client::builder()
  .collection_name("cid")
  .build()
  .unwrap();

// Attachment operations store cache data on records, so they need mutable references.
let mut records = client.get().await?;
if let Some(attachment_metadata) = records[0].attachment_metadata()? {
    println!("The attachment should be {} bytes long", attachment_metadata.size);
}

// The type returned can be anything that implement `From<Vec<u8>>`.
if let Some(attachment_body) = client.fetch_attachment::<Vec<u8>, _>(&mut records[0]).await? {
    println!("Downloaded attachment with size {} bytes", attachment_body.len());
}

Attachment metadata contain a hash of the expected content. The provided verifier will be used to confirm that hash, and if it does not match a verification error will be returned.

Write Operations

let client = Client::builder()
  .authorization("Bearer abcdefghijkl")
  .collection_name("cid")
  .build()
  .unwrap();

client
  .store_record(Record::new(json!({
    "id": "my-key",
    "foo": "bar"
  }))).await?;

// Request review from peers.
client.request_review("I made changes").await?;

// Approve changes (publish).
let peer_reviewer = Client::builder()
  .authorization("Bearer zyxwvutsrqp")
  .collection_name("cid")
  .build()
  .unwrap();

peer_reviewer.approve_changes().await?;

Implementations

source

impl Client

source

pub fn builder() -> ClientBuilder

Creates a ClientBuilder to configure a Client.

source

pub async fn get(&mut self) -> Result<Vec<Record>, ClientError>

Return the records stored locally.

Examples

match client.get().await {
  Ok(records) => println!("{:?}", records),
  Err(error) => println!("Error fetching/verifying records: {:?}", error)
};

Behaviour

Return local data by default;
If local data is empty and if sync_if_empty is true (default), then synchronize the local data with the server and return records, otherwise return an error.

Note: with the DummyStorage, any call to .get() will trigger a synchronization.

Note: with sync_if_empty as false, if .sync() is never called then .get() will always return an error.

Errors

If an error occurs while fetching or verifying records, a ClientError is returned.

source

pub async fn sync<T>(&mut self, expected: T) -> Result<Collection, ClientError> where
T: Into<Option<u64>>,

Synchronize the local storage with the content of the server for this collection.

Behaviour

If stored data is up-to-date and signature of local data valid, then return local content;
Otherwise fetch content from server, merge with local content, verify signature, and return records;

Errors

If an error occurs while fetching or verifying records, a ClientError is returned.

source

pub async fn server_info(&mut self) -> Result<&Value, ClientError>

source

pub async fn fetch_attachment<T, E>(
 &mut self,
 record: &mut Record
) -> Result<Option<T>, ClientError> where
 T: TryFrom<Vec<u8>, Error = E>,
 E: 'static + Send + Sync + Error,

Download the attachment for a record.

Return values:

Ok(Some(T)) - There is an attachment for the record and it was successfully downloaded.
Err(_) - There is an attachment for the record, and there was a problem while downloading it. This should be considered a temporary error.
Ok(None) - There is no attachment for the record

source