RustRemoteSettings.sys.mjs

class RustRemoteSettings.sys.RemoteSettingsClient()

Client for a single Remote Settings collection

Use [RemoteSettingsService::make_client] to create these.

RustRemoteSettings.sys.RemoteSettingsClient.collectionName()

Collection this client is for

Returns:: string –

RustRemoteSettings.sys.RemoteSettingsClient.getAttachment(record)

Get attachment data for a remote settings record

Attachments are large binary blobs used for data that doesn’t fit in a normal record. They are handled differently than other record data:

Attachments are not downloaded in [RemoteSettingsService::sync]
This method will make network requests if the attachment is not cached
This method will throw if there is a network or other error when fetching the

attachment data.

Returns:: string –

RustRemoteSettings.sys.RemoteSettingsClient.getRecords(syncIfEmpty)

Get the current set of records.

This method normally fetches records from the last sync. This means that it returns fast and does not make any network requests.

If records have not yet been synced it will return None. Use sync_if_empty = true to change this behavior and perform a network request in this case. That this is probably a bad idea if you want to fetch the setting in application startup or when building the UI.

None will also be returned on disk IO errors or other unexpected errors. The reason for this is that there is not much an application can do in this situation other than fall back to the same default handling as if records have not been synced.

Application-services schedules regular dumps of the server data for specific collections. For these collections, get_records will never return None. If you would like to add your collection to this list, please reach out to the DISCO team.

Returns:: Array.<RemoteSettingsRecord> –

RustRemoteSettings.sys.RemoteSettingsClient.getRecordsMap(syncIfEmpty)

Get the current set of records as a map of record_id -> record.

See [Self::get_records] for an explanation of when this makes network requests, error handling, and how the sync_if_empty param works.

Returns:: object –

RustRemoteSettings.sys.RemoteSettingsClient.sync(): sync

class RustRemoteSettings.sys.RemoteSettingsService()

Application-level Remote Settings manager.

This handles application-level operations, like syncing all the collections, and acts as a factory for creating clients.

RustRemoteSettings.sys.RemoteSettingsService.makeClient(collectionName)

Create a new Remote Settings client

This method performs no IO or network requests and is safe to run in a main thread that can’t be blocked.

Returns:: RemoteSettingsClient –

RustRemoteSettings.sys.RemoteSettingsService.sync()

Sync collections for all active clients

Returns:: Array.<string> –

RustRemoteSettings.sys.RemoteSettingsService.updateConfig(config)

Update the remote settings config

This will cause all current and future clients to use new config and will delete any stored records causing the clients to return new results from the new config.

Only intended for QA/debugging. Swapping the remote settings server in the middle of execution can cause weird effects.

static RustRemoteSettings.sys.RemoteSettingsService.init(storageDir, config)

Construct a [RemoteSettingsService]

This is typically done early in the application-startup process.

This method performs no IO or network requests and is safe to run in a main thread that can’t be blocked.

storage_dir is a directory to store SQLite files in – one per collection. If the directory does not exist, it will be created when the storage is first used. Only the directory and the SQLite files will be created, any parent directories must already exist.

Returns:: RemoteSettingsService –

class RustRemoteSettings.sys.Attachment()

Attachment metadata that can be optionally attached to a [Record]. The [location] should included in calls to [Client::get_attachment].

RustRemoteSettings.sys.Attachment.filename: type: string

RustRemoteSettings.sys.Attachment.hash: type: string

RustRemoteSettings.sys.Attachment.location: type: string

RustRemoteSettings.sys.Attachment.mimetype: type: string

RustRemoteSettings.sys.Attachment.size: type: number

class RustRemoteSettings.sys.RemoteSettingsConfig()

Custom configuration for the client. Currently includes the following: - server: The Remote Settings server to use. If not specified, defaults to the production server (RemoteSettingsServer::Prod). - server_url: An optional custom Remote Settings server URL. Deprecated; please use server instead. - bucket_name: The optional name of the bucket containing the collection on the server. If not specified, the standard bucket will be used. - collection_name: The name of the collection for the settings server.

RustRemoteSettings.sys.RemoteSettingsConfig.bucketName: type: string

RustRemoteSettings.sys.RemoteSettingsConfig.collectionName: type: string

RustRemoteSettings.sys.RemoteSettingsConfig.server: type: RemoteSettingsServer

RustRemoteSettings.sys.RemoteSettingsConfig.serverUrl: type: string

class RustRemoteSettings.sys.RemoteSettingsConfig2()

Remote settings configuration

This is the version used in the new API, hence the 2 at the end. The plan is to move consumers to the new API, remove the RemoteSettingsConfig struct, then remove the 2 from this name.

RustRemoteSettings.sys.RemoteSettingsConfig2.appContext

type: RemoteSettingsContext

App context to use for JEXL filtering (when the jexl feature is present).

RustRemoteSettings.sys.RemoteSettingsConfig2.bucketName

type: string

Bucket name to use, defaults to “main”. Use “main-preview” for a preview bucket

RustRemoteSettings.sys.RemoteSettingsConfig2.server

type: RemoteSettingsServer

The Remote Settings server to use. Defaults to [RemoteSettingsServer::Prod],

class RustRemoteSettings.sys.RemoteSettingsContext()

Remote settings context object

This is used to filter the records returned. We always fetch all records from the remote-settings storage. Some records could have a filter_expression. If this is passed in and the record has a filter_expression, then only returns where the expression is true will be returned.

See https://remote-settings.readthedocs.io/en/latest/target-filters.html for details.

RustRemoteSettings.sys.RemoteSettingsContext.appId

type: string

String containing the XUL application app_id

RustRemoteSettings.sys.RemoteSettingsContext.appVersion

type: string

User visible version string (e.g. “1.0.3”)

RustRemoteSettings.sys.RemoteSettingsContext.channel

type: string

The delivery channel of the application (e.g “nightly”)

RustRemoteSettings.sys.RemoteSettingsContext.country

type: string

Country of the user.

This is usually populated in one of two ways: - The second component of the locale - By using a geolocation service, which determines country via the user’s IP. Firefox apps usually have a module that integrates with these services, for example Region on Desktop and RegionMiddleware on Android.

RustRemoteSettings.sys.RemoteSettingsContext.customTargettingAttributes

type: object

Extra attributes to add to the env for JEXL filtering.

Use this for prototyping / testing new features. In the long-term, new fields should be added to the official list and supported by both the Rust and Gecko clients.

RustRemoteSettings.sys.RemoteSettingsContext.formFactor

type: string

Form-factor of the device (“phone”, “tablet”, or “desktop”)

RustRemoteSettings.sys.RemoteSettingsContext.locale

type: string

The locale of the application during initialization (e.g. “es-ES”)

RustRemoteSettings.sys.RemoteSettingsContext.os

type: string

The name of the operating system (e.g. “Android”, “iOS”, “Darwin”, “WINNT”)

RustRemoteSettings.sys.RemoteSettingsContext.osVersion

type: string

The user-visible version of the operating system (e.g. “1.2.3”)

class RustRemoteSettings.sys.RemoteSettingsRecord()

A parsed Remote Settings record. Records can contain arbitrary fields, so clients are required to further extract expected values from the [fields] member.

RustRemoteSettings.sys.RemoteSettingsRecord.attachment: type: Attachment

RustRemoteSettings.sys.RemoteSettingsRecord.deleted

type: Boolean

Tombstone flag (see https://remote-settings.readthedocs.io/en/latest/client-specifications.html#local-state)

RustRemoteSettings.sys.RemoteSettingsRecord.fields: type: RsJsonObject

RustRemoteSettings.sys.RemoteSettingsRecord.id: type: string

RustRemoteSettings.sys.RemoteSettingsRecord.lastModified: type: number

class RustRemoteSettings.sys.RemoteSettingsResponse()

Data structure representing the top-level response from the Remote Settings. [last_modified] will be extracted from the etag header of the response.

RustRemoteSettings.sys.RemoteSettingsResponse.lastModified: type: number

RustRemoteSettings.sys.RemoteSettingsResponse.records: type: Array.<RemoteSettingsRecord>

class RustRemoteSettings.sys.RemoteSettingsError(): Public error class, this is what we return to consumers

class RustRemoteSettings.sys.RemoteSettingsServer()

The Remote Settings server that the client should use.

RustRemoteSettings.sys.RemoteSettingsServer.Custom

RustRemoteSettings.sys.RemoteSettingsServer.Dev

RustRemoteSettings.sys.RemoteSettingsServer.Prod

RustRemoteSettings.sys.RemoteSettingsServer.Stage

class RustRemoteSettings.sys.Network(): Network error while making a remote settings request

class RustRemoteSettings.sys.Backoff(): The server has asked the client to backoff.

class RustRemoteSettings.sys.Other(): Other