RustSuggest.sys.mjs¶

class RustSuggest.sys.SuggestStore()¶

The store is the entry point to the Suggest component. It incrementally downloads suggestions from the Remote Settings service, stores them in a local database, and returns them in response to user queries.

Your application should create a single store, and manage it as a singleton. The store is thread-safe, and supports concurrent queries and ingests. We expect that your application will call [SuggestStore::query()] to show suggestions as the user types into the address bar, and periodically call [SuggestStore::ingest()] in the background to update the database with new suggestions from Remote Settings.

For responsiveness, we recommend always calling query() on a worker thread. When the user types new input into the address bar, call [SuggestStore::interrupt()] on the main thread to cancel the query for the old input, and unblock the worker thread for the new query.

The store keeps track of the state needed to support incremental ingestion, but doesn’t schedule the ingestion work itself, or decide how many suggestions to ingest at once. This is for two reasons:

1. The primitives for scheduling background work vary between platforms, and aren’t available to the lower-level Rust layer. You might use an idle timer on Desktop, WorkManager on Android, or BGTaskScheduler on iOS. 2. Ingestion constraints can change, depending on the platform and the needs of your application. A mobile device on a metered connection might want to request a small subset of the Suggest data and download the rest later, while a desktop on a fast link might download the entire dataset on the first launch.

RustSuggest.sys.SuggestStore.clear()¶: Removes all content from the database.

RustSuggest.sys.SuggestStore.clearDismissedSuggestions()¶: Clear dismissed suggestions

RustSuggest.sys.SuggestStore.dismissSuggestion(suggestionUrl)¶

Dismiss a suggestion

Dismissed suggestions will not be returned again

In the case of AMP suggestions this should be the raw URL.

RustSuggest.sys.SuggestStore.fetchGlobalConfig()¶

fetchGlobalConfig

Returns:: SuggestGlobalConfig –

RustSuggest.sys.SuggestStore.fetchProviderConfig(provider)¶

fetchProviderConfig

Returns:: SuggestProviderConfig –

RustSuggest.sys.SuggestStore.ingest(constraints)¶

Ingests new suggestions from Remote Settings.

Returns:: SuggestIngestionMetrics –

RustSuggest.sys.SuggestStore.interrupt(kind)¶

Interrupts any ongoing queries.

This should be called when the user types new input into the address bar, to ensure that they see fresh suggestions as they type. This method does not interrupt any ongoing ingests.

RustSuggest.sys.SuggestStore.query(query)¶

Queries the database for suggestions.

Returns:: Array.<Suggestion> –

RustSuggest.sys.SuggestStore.queryWithMetrics(query)¶

Queries the database for suggestions.

Returns:: QueryWithMetricsResult –

static RustSuggest.sys.SuggestStore.init(path, settingsConfig)¶

Creates a Suggest store.

Returns:: SuggestStore –

class RustSuggest.sys.SuggestStoreBuilder()¶

Builder for [SuggestStore]

Using a builder is preferred to calling the constructor directly since it’s harder to confuse the data_path and cache_path strings.

RustSuggest.sys.SuggestStoreBuilder.build()¶

build

Returns:: SuggestStore –

RustSuggest.sys.SuggestStoreBuilder.cachePath(path)¶

Deprecated: this is no longer used by the suggest component.

Returns:: SuggestStoreBuilder –

RustSuggest.sys.SuggestStoreBuilder.dataPath(path)¶

dataPath

Returns:: SuggestStoreBuilder –

RustSuggest.sys.SuggestStoreBuilder.loadExtension(library, entryPoint)¶

Add an sqlite3 extension to load

library_name should be the name of the library without any extension, for example libmozsqlite3. entrypoint should be the entry point, for example sqlite3_fts5_init. If null (the default) entry point will be used (see https://sqlite.org/loadext.html for details).

Returns:: SuggestStoreBuilder –

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsBucketName(bucketName)¶

remoteSettingsBucketName

Returns:: SuggestStoreBuilder –

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsServer(server)¶

remoteSettingsServer

Returns:: SuggestStoreBuilder –

static RustSuggest.sys.SuggestStoreBuilder.init()¶

init

Returns:: SuggestStoreBuilder –

class RustSuggest.sys.LabeledTimingSample()¶

Single sample for a Glean labeled_timing_distribution

RustSuggest.sys.LabeledTimingSample.label¶: type: string

RustSuggest.sys.LabeledTimingSample.value¶

type: number

Time in microseconds

class RustSuggest.sys.SuggestGlobalConfig()¶

Global Suggest configuration data.

RustSuggest.sys.SuggestGlobalConfig.showLessFrequentlyCap¶: type: number

class RustSuggest.sys.SuggestIngestionConstraints()¶

Constraints limit which suggestions to ingest from Remote Settings.

RustSuggest.sys.SuggestIngestionConstraints.emptyOnly¶

type: Boolean

Only run ingestion if the table suggestions is empty

RustSuggest.sys.SuggestIngestionConstraints.providerConstraints¶: type: SuggestionProviderConstraints

RustSuggest.sys.SuggestIngestionConstraints.providers¶: type: Array.<SuggestionProvider>

class RustSuggest.sys.SuggestIngestionMetrics()¶

Ingestion metrics

These are recorded during [crate::Store::ingest] and returned to the consumer to record.

RustSuggest.sys.SuggestIngestionMetrics.downloadTimes¶

type: Array.<LabeledTimingSample>

Samples for the suggest.ingestion_download_time metric

RustSuggest.sys.SuggestIngestionMetrics.ingestionTimes¶

type: Array.<LabeledTimingSample>

Samples for the suggest.ingestion_time metric

class RustSuggest.sys.SuggestionProviderConstraints()¶

Some providers manage multiple suggestion subtypes. Queries, ingests, and other operations on those providers must be constrained to a desired subtype.

RustSuggest.sys.SuggestionProviderConstraints.exposureSuggestionTypes¶

type: Array.<string>

Exposure provider - For each desired exposure suggestion type, this should contain the value of the suggestion_type field of its remote settings record(s).

class RustSuggest.sys.SuggestionQuery()¶

A query for suggestions to show in the address bar.

RustSuggest.sys.SuggestionQuery.keyword¶: type: string

RustSuggest.sys.SuggestionQuery.limit¶: type: number

RustSuggest.sys.SuggestionQuery.providerConstraints¶: type: SuggestionProviderConstraints

RustSuggest.sys.SuggestionQuery.providers¶: type: Array.<SuggestionProvider>

class RustSuggest.sys.InterruptKind()¶

What should be interrupted when [SuggestStore::interrupt] is called?

RustSuggest.sys.InterruptKind.READ¶: Interrupt read operations like [SuggestStore::query]

RustSuggest.sys.InterruptKind.READ_WRITE¶: Interrupt both read and write operations,

RustSuggest.sys.InterruptKind.WRITE¶: Interrupt write operations. This mostly means [SuggestStore::ingest], but [SuggestStore::dismiss_suggestion] may also be interrupted.

class RustSuggest.sys.SuggestApiError()¶: The error type for all Suggest component operations. These errors are exposed to your application, which should handle them as needed.

class RustSuggest.sys.SuggestProviderConfig()¶

Per-provider configuration data.

RustSuggest.sys.SuggestProviderConfig.Weather¶

class RustSuggest.sys.Suggestion()¶

A suggestion from the database to show in the address bar.

RustSuggest.sys.Suggestion.Amo¶

RustSuggest.sys.Suggestion.Amp¶

RustSuggest.sys.Suggestion.Exposure¶

RustSuggest.sys.Suggestion.Fakespot¶

RustSuggest.sys.Suggestion.Mdn¶

RustSuggest.sys.Suggestion.Pocket¶

RustSuggest.sys.Suggestion.Weather¶

RustSuggest.sys.Suggestion.Wikipedia¶

RustSuggest.sys.Suggestion.Yelp¶

class RustSuggest.sys.SuggestionProvider()¶

A provider is a source of search suggestions.

RustSuggest.sys.SuggestionProvider.AMO¶: AMO

RustSuggest.sys.SuggestionProvider.AMP¶: AMP

RustSuggest.sys.SuggestionProvider.AMP_MOBILE¶: AMP_MOBILE

RustSuggest.sys.SuggestionProvider.EXPOSURE¶: EXPOSURE

RustSuggest.sys.SuggestionProvider.FAKESPOT¶: FAKESPOT

RustSuggest.sys.SuggestionProvider.MDN¶: MDN

RustSuggest.sys.SuggestionProvider.POCKET¶: POCKET

RustSuggest.sys.SuggestionProvider.WEATHER¶: WEATHER

RustSuggest.sys.SuggestionProvider.WIKIPEDIA¶: WIKIPEDIA

RustSuggest.sys.SuggestionProvider.YELP¶: YELP

class RustSuggest.sys.Network()¶: Network

class RustSuggest.sys.Backoff()¶: The server requested a backoff after too many requests

class RustSuggest.sys.Interrupted()¶: An operation was interrupted by calling SuggestStore.interrupt()

class RustSuggest.sys.Other()¶: Other

RustSuggest.sys.rawSuggestionUrlMatches(rawUrl, cookedUrl)¶

Determines whether a “raw” sponsored suggestion URL is equivalent to a “cooked” URL. The two URLs are equivalent if they are identical except for their replaced template parameters, which can be different.

Returns:: Boolean –