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.fetchGeonames(query, matchNamePrefix, geonameType, filter)¶

Fetches geonames stored in the database. A geoname represents a geographic place.

query is a string that will be matched directly against geoname names. It is not a query string in the usual Suggest sense. match_name_prefix determines whether prefix matching is performed on names excluding abbreviations and airport codes. When true, names that start with query will match. When false, names that equal query will match.

geoname_type restricts returned geonames to a [GeonameType].

filter restricts returned geonames to certain cities or regions. Cities can be restricted to regions by including the regions in filter, and regions can be restricted to those containing certain cities by including the cities in filter. This is especially useful since city and region names are not unique. filter is disjunctive: If any item in filter matches a geoname, the geoname will be filtered in.

The query can match a geoname in more than one way, for example both a full name and an abbreviation. The returned vec of [GeonameMatch] values will include all matches for a geoname, one match per geoname.

Returns:: Array.<GeonameMatch> –

RustSuggest.sys.SuggestStore.fetchGlobalConfig()¶

Returns global Suggest configuration data.

Returns:: SuggestGlobalConfig –

RustSuggest.sys.SuggestStore.fetchProviderConfig(provider)¶

Returns per-provider Suggest configuration data.

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.Geoname()¶

A single geographic place.

This corresponds to a single row in the main “geoname” table described in the GeoNames documentation [1]. We exclude fields we don’t need.

[1]: https://download.geonames.org/export/dump/readme.txt

RustSuggest.sys.Geoname.admin1Code¶

type: string

The top-level administrative region for the place within its country, like a state or province. For the U.S., the two-letter uppercase state abbreviation.

RustSuggest.sys.Geoname.countryCode¶

type: string

ISO-3166 two-letter uppercase country code, e.g., “US”.

RustSuggest.sys.Geoname.geonameId¶

type: number

The geonameid straight from the geoname table.

RustSuggest.sys.Geoname.latitude¶

type: number

Latitude in decimal degrees.

RustSuggest.sys.Geoname.longitude¶

type: number

Longitude in decimal degrees.

RustSuggest.sys.Geoname.name¶

type: string

This is pretty much the place’s canonical name. Usually there will be a row in the alternates table with the same name, but not always. When there is such a row, it doesn’t always have is_preferred_name set, and in fact fact there may be another row with a different name with is_preferred_name set.

RustSuggest.sys.Geoname.population¶

type: number

Population size.

class RustSuggest.sys.GeonameMatch()¶

A fetched geoname with info on how it was matched.

RustSuggest.sys.GeonameMatch.geoname¶

type: Geoname

The geoname that was matched.

RustSuggest.sys.GeonameMatch.matchType¶

type: GeonameMatchType

The type of name that was matched.

RustSuggest.sys.GeonameMatch.prefix¶

type: Boolean

Whether the name was matched by prefix.

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.GeonameType()¶

The type of a geoname.

RustSuggest.sys.GeonameType.CITY¶: CITY

RustSuggest.sys.GeonameType.REGION¶: REGION

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 –