Sylvestre Ledru
9a84c975d6
Follow-up to D304232. Fix broken {ref} cross-references, escaped-asterisk nested lists and a blockquoted list in AMRemoteSettings-overview, indent a numbered-list continuation in SearchServiceHighlevelOverview, and correct the event-ping serialization-format reference.
Differential Revision: https://phabricator.services.mozilla.com/D310483
79 lines
4.4 KiB
Markdown
79 lines
4.4 KiB
Markdown
# SearchService High-level Overview
|
|
|
|
`SearchService` is the core component that manages Search Engines on the
|
|
Firefox browser.
|
|
|
|
The following diagram is a high level systems context diagram of the
|
|
`SearchService`. The diagram illustrates which systems interface with the
|
|
`SearchService` so that it can do its job of managing the Search Engines.
|
|
|
|
The diagram and description is an over-simplification of the `SearchService's`
|
|
responsibilities. It specifically highlights how the `SearchService` serves
|
|
search engines to the browser on startup. However, the `SearchService` has
|
|
many other responsibilities that are not outlined in the diagram such as
|
|
maintaining and managing the Search Engines when various items change, e.g. the
|
|
user's region or locale, configuration changes received from remote settings,
|
|
updates received to search engine data. Nonetheless, the diagram gives a broad
|
|
overview of the main components the `SearchService` interacts with most often.
|
|
|
|
## Diagram
|
|
|
|
:::{figure} assets/search-service-diagram-2.png
|
|
:align: center
|
|
:scale: 30%
|
|
:::
|
|
|
|
## Description of the Diagram
|
|
|
|
These steps follow the same number on the diagram. Number 1 on the diagram is
|
|
described by number 1 below.
|
|
|
|
1. When the user opens the Firefox Browser, the code starts to build the browser
|
|
UI components. During this startup phase, we have various systems making
|
|
calls to the `SearchService`. E.g. {searchfox}`browser.js <mozilla-central/rev/47db1be98f8069b387ce07dcbea22d09f1854515:browser/base/content/browser.js#3325>`
|
|
calls `SearchService.getDefault` to fetch the default Search Engine.
|
|
|
|
2. The `SearchService` needs information from `Extension System`,
|
|
`SearchSettings`, and `Remote Settings` to build the correct engines in
|
|
the right order and to return the list of engines to its callers.
|
|
|
|
a) First, the `SearchService` makes a request for the search configuration.
|
|
`SearchService` calls {searchfox}`SearchEngineSelector.fetchEngineConfiguration <mozilla-central/rev/47db1be98f8069b387ce07dcbea22d09f1854515:toolkit/components/search/SearchService.sys.mjs#2602>`
|
|
which makes a call to {searchfox}`Remote Settings <mozilla-central/rev/47db1be98f8069b387ce07dcbea22d09f1854515:toolkit/components/search/SearchEngineSelector.sys.mjs#119>`
|
|
for the search configuration. Remote Settings does not fetch the search
|
|
configuration from the remote database on startup. Instead Remote Settings
|
|
tries to load the {searchfox}`search configuration dump file <services/settings/dumps/main/search-config-v2.json>`
|
|
from its local database and if that is empty, it will load the dump file into
|
|
its local database. Only after startup will Remote Settings connect to the
|
|
remote database when necessary. By connecting after startup, it avoids
|
|
a potential network request that could delay startup.
|
|
|
|
b) Second, the `SearchService` {searchfox}`loads the JSON file <mozilla-central/rev/47db1be98f8069b387ce07dcbea22d09f1854515:toolkit/components/search/SearchService.sys.mjs#1368>`
|
|
containing the {searchfox}`SearchSettings <toolkit/components/search/SearchSettings.sys.mjs>`.
|
|
This JSON file contains Search Engine metadata that is saved on the user's
|
|
computer. It's information that helps the `SearchService` remember the
|
|
user's custom settings for the Search Engines.
|
|
|
|
c) Third, the {searchfox}`Extension System <mozilla-central/rev/cb6f8d7b1f1782b9d4b2ee7312de1dcc284aaf06:browser/components/extensions/parent/ext-chrome-settings-overrides.js#536>`
|
|
passes the extension data to the `SearchService`. At this point, the
|
|
`SearchService` only installs user installed search extensions.
|
|
|
|
After steps 2a, 2b, and 2c the `SearchService` has finished gathering
|
|
search engine data from `System Add-ons`, `SearchSettings`, and
|
|
`Remote Settings`. Now the `SearchService` can build the different
|
|
types of Search Engines.
|
|
|
|
3. The `SearchService` creates new instances of the various
|
|
[SearchEngine Subclasses](https://firefox-source-docs.mozilla.org/toolkit/search/SearchEngines.html).
|
|
|
|
4. The `SearchService` returns the engines to the caller that requested it.
|
|
E.g. the `SearchService` passes the default Search Engine back to
|
|
`browser.js`, the system that initially requested it.
|
|
|
|
## Updates
|
|
|
|
This page is up to date as of April 18, 2024. If the diagram or description
|
|
becomes out of date, please find access to the `Search Service Diagram` in
|
|
`Firefox Search > Search Service Documentation` folder in the Firefox Search
|
|
shared drive. Contributions are welcomed to keep this page up to date.
|