RustSuggest.sys.mjs

class RustSuggest.sys.AlternateNames()

A set of names for a single entity.

RustSuggest.sys.AlternateNames.abbreviation

type: string

The entity’s abbreviation, if any.

RustSuggest.sys.AlternateNames.localized

type: string

The entity’s name in the language that was ingested according to the locale in the remote settings context. If none exists and this AlternateNames is for a Geoname, then this will be its primary name.

RustSuggest.sys.AlternateNames.primary

type: string

The entity’s primary name. For a Geoname, this is Geoname::name.

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

class RustSuggest.sys.FtsMatchInfo()

Additional data about how an FTS match was made

RustSuggest.sys.FtsMatchInfo.prefix

type: boolean

Was this a prefix match (water b matched against water bottle)

RustSuggest.sys.FtsMatchInfo.stemming

type: boolean

Did the match require stemming? (run shoes matched against running shoes)

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.adminDivisionCodes

type: Map

Administrative divisions. This maps admin division levels (1-based) to their corresponding codes. For example, Liverpool has two admin divisions: “ENG” at level 1 and “H8” at level 2. They would be represented in this map with entries (1, "ENG") and (2, "H8").

RustSuggest.sys.Geoname.countryCode

type: string

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

RustSuggest.sys.Geoname.featureClass

type: string

Primary geoname category. Examples:

“PCLI” - Independent political entity: country “A” - Administrative division: state, province, borough, district, etc. “P” - Populated place: city, village, etc.

RustSuggest.sys.Geoname.featureCode

type: string

Secondary geoname category, depends on feature_class. Examples:

“ADM1” - Administrative division 1 “PPL” - Populated place like a city

RustSuggest.sys.Geoname.geonameId

type: number

The geonameid straight from the geoname table.

RustSuggest.sys.Geoname.geonameType

type: GeonameType[keyof GeonameType]

The geoname type. This is derived from feature_class and feature_code as a more convenient representation of the type.

RustSuggest.sys.Geoname.latitude

type: string

Latitude in decimal degrees (as a string).

RustSuggest.sys.Geoname.longitude

type: string

Longitude in decimal degrees (as a string).

RustSuggest.sys.Geoname.name

type: string

The place’s primary name.

RustSuggest.sys.Geoname.population

type: number

Population size.

class RustSuggest.sys.GeonameAlternates()

Alternate names for a geoname and its country and admin divisions.

RustSuggest.sys.GeonameAlternates.adminDivisions

type: Map

Names for the geoname’s admin divisions. This is parallel to Geoname::admin_division_codes. If there are no names in the ingested data for an admin division, then it will be absent from this map.

RustSuggest.sys.GeonameAlternates.country

type: AlternateNames

Names for the geoname’s country. This will be Some as long as the country is also in the ingested data, which should typically be true.

RustSuggest.sys.GeonameAlternates.geoname

type: AlternateNames

Names for the geoname itself.

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[keyof GeonameMatchType]

The type of name that was matched.

RustSuggest.sys.GeonameMatch.prefix

type: boolean

Whether the name was matched by prefix.

class RustSuggest.sys.GeonameType()

The type of a geoname.

RustSuggest.sys.GeonameType.AdminDivision

RustSuggest.sys.GeonameType.AdminDivisionOther

RustSuggest.sys.GeonameType.City

RustSuggest.sys.GeonameType.Country

RustSuggest.sys.GeonameType.Other

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 other operations may also be interrupted.

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

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.Network(): Network

class RustSuggest.sys.Other(): Other

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.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[keyof 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.SuggestProviderConfig()

Per-provider configuration data.

RustSuggest.sys.SuggestProviderConfig.Weather

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.anyDismissedSuggestions()

Return whether any suggestions have been dismissed.

Returns:: Promise.<boolean> – }

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

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

RustSuggest.sys.SuggestStore.dismissByKey(key)

Dismiss a suggestion by its dismissal key.

Dismissed suggestions cannot be fetched again.

Prefer [SuggestStore::dismiss_by_suggestion] if you have a crate::Suggestion. This method is intended for cases where a suggestion originates outside this component.

Arguments:

key (string)

RustSuggest.sys.SuggestStore.dismissBySuggestion(suggestion)

Dismiss a suggestion.

Dismissed suggestions cannot be fetched again.

Arguments:

suggestion (Suggestion[keyof Suggestion])

RustSuggest.sys.SuggestStore.dismissSuggestion(suggestionUrl)

Deprecated, use [SuggestStore::dismiss_by_suggestion] or [SuggestStore::dismiss_by_key] instead.

Dismiss a suggestion

Dismissed suggestions will not be returned again

Arguments:

suggestionUrl (string)

RustSuggest.sys.SuggestStore.fetchGeonameAlternates(geoname)

Fetches a geoname’s names stored in the database.

See fetch_geoname_alternates in geoname.rs for documentation.

Arguments:

geoname (Geoname)

Returns:

Promise.<GeonameAlternates> – }

RustSuggest.sys.SuggestStore.fetchGeonames(query, matchNamePrefix, filter)

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

See fetch_geonames in geoname.rs for documentation.

Arguments:

query (string)
matchNamePrefix (boolean)
filter (Array.<Geoname>)

Returns:

Promise.<Array.<GeonameMatch>> – }

RustSuggest.sys.SuggestStore.fetchGlobalConfig()

Returns global Suggest configuration data.

Returns:: Promise.<SuggestGlobalConfig> – }

RustSuggest.sys.SuggestStore.fetchProviderConfig(provider)

Returns per-provider Suggest configuration data.

Arguments:

provider (SuggestionProvider[keyof SuggestionProvider])

Returns:

Promise<?SuggestProviderConfig[keyof SuggestProviderConfig]> – }

RustSuggest.sys.SuggestStore.ingest(constraints)

Ingests new suggestions from Remote Settings.

Arguments:

constraints (SuggestIngestionConstraints)

Returns:

Promise.<SuggestIngestionMetrics> – }

RustSuggest.sys.SuggestStore.interrupt(kind=null)

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.

Arguments:

kind (?InterruptKind[keyof InterruptKind])

RustSuggest.sys.SuggestStore.isDismissedByKey(key)

Return whether a suggestion has been dismissed given its dismissal key.

[SuggestStore::query] will never return dismissed suggestions, so normally you never need to know whether a suggestion has been dismissed. This method is intended for cases where a dismissal key originates outside this component.

Arguments:

key (string)

Returns:

Promise.<boolean> – }

RustSuggest.sys.SuggestStore.isDismissedBySuggestion(suggestion)

Return whether a suggestion has been dismissed.

[SuggestStore::query] will never return dismissed suggestions, so normally you never need to know whether a Suggestion has been dismissed, but this method can be used to do so.

Arguments:

suggestion (Suggestion[keyof Suggestion])

Returns:

Promise.<boolean> – }

RustSuggest.sys.SuggestStore.query(query)

Queries the database for suggestions.

Arguments:

query (SuggestionQuery)

Returns:

Promise<Array.<Suggestion[keyof Suggestion]>> – }

RustSuggest.sys.SuggestStore.queryWithMetrics(query)

Queries the database for suggestions.

Arguments:

query (SuggestionQuery)

Returns:

Promise.<QueryWithMetricsResult> – }

static RustSuggest.sys.SuggestStore.init(path, remoteSettingsService)

Creates a Suggest store.

Arguments:

path (string)
remoteSettingsService (RemoteSettingsService)

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.

Arguments:

path (string)

Returns:

Promise.<SuggestStoreBuilder> – }

RustSuggest.sys.SuggestStoreBuilder.dataPath(path)

dataPath

Arguments:

path (string)

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).

Arguments:

library (string)
entryPoint (string)

Returns:

SuggestStoreBuilder

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsBucketName(bucketName)

remoteSettingsBucketName

Arguments:

bucketName (string)

Returns:

SuggestStoreBuilder

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsServer(server)

remoteSettingsServer

Arguments:

server (RemoteSettingsServer[keyof RemoteSettingsServer])

Returns:

SuggestStoreBuilder

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsService(rsService)

remoteSettingsService

Arguments:

rsService (RemoteSettingsService)

Returns:

SuggestStoreBuilder

static RustSuggest.sys.SuggestStoreBuilder.init()

init

Returns:: SuggestStoreBuilder

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.Dynamic

RustSuggest.sys.Suggestion.Mdn

RustSuggest.sys.Suggestion.Weather

RustSuggest.sys.Suggestion.Wikipedia

RustSuggest.sys.Suggestion.Yelp

class RustSuggest.sys.SuggestionProvider()

A provider is a source of search suggestions. Please preserve the integer values after removing or adding providers. Provider configs are associated with integer keys stored in the database.

RustSuggest.sys.SuggestionProvider.AMO: AMO

RustSuggest.sys.SuggestionProvider.AMP: AMP

RustSuggest.sys.SuggestionProvider.DYNAMIC: DYNAMIC

RustSuggest.sys.SuggestionProvider.MDN: MDN

RustSuggest.sys.SuggestionProvider.WEATHER: WEATHER

RustSuggest.sys.SuggestionProvider.WIKIPEDIA: WIKIPEDIA

RustSuggest.sys.SuggestionProvider.YELP: YELP

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.ampAlternativeMatching

type: ?AmpMatchingStrategy[keyof AmpMatchingStrategy]

Which strategy should we use for the AMP queries? Use None for the default strategy.

RustSuggest.sys.SuggestionProviderConstraints.dynamicSuggestionTypes

type: Array.<string>

Which dynamic suggestions should we fetch or ingest? Corresponds to the suggestion_type value in dynamic suggestions remote settings records.

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[keyof SuggestionProvider]>

class RustSuggest.sys.YelpSubjectType()

Subject type for Yelp suggestion.

RustSuggest.sys.YelpSubjectType.BUSINESS: BUSINESS

RustSuggest.sys.YelpSubjectType.SERVICE: SERVICE

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.

Arguments:

rawUrl (string)
cookedUrl (string)

Returns:

boolean