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

../../_images/search-service-diagram-2.png

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. browser.js calls Services.search.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 SearchEngineSelector.fetchEngineConfiguration which makes a call to Remote Settings 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 search configuration dump file 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 loads the JSON file containing the SearchSettings. 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 Extension System 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.

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