From 59203c63bb777a3bacec32fb8830fba33540e809 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 07:35:29 +0200 Subject: Adding upstream version 127.0. Signed-off-by: Daniel Baumann --- .../docs/SearchServiceHighlevelOverviewArchive.rst | 85 ++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 toolkit/components/search/docs/SearchServiceHighlevelOverviewArchive.rst (limited to 'toolkit/components/search/docs/SearchServiceHighlevelOverviewArchive.rst') diff --git a/toolkit/components/search/docs/SearchServiceHighlevelOverviewArchive.rst b/toolkit/components/search/docs/SearchServiceHighlevelOverviewArchive.rst new file mode 100644 index 0000000000..a409a37ed4 --- /dev/null +++ b/toolkit/components/search/docs/SearchServiceHighlevelOverviewArchive.rst @@ -0,0 +1,85 @@ +============================================ +SearchService High-level Overview (Archived) +============================================ +``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-1.png + :scale: 85% + :align: center + +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 ``System Add-ons``, + ``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 :searchfox:`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`` `fetches a JSON file `_ + from 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 `System Add-ons `_ + passes the extension data to the ``SearchService``. At this point, the + ``SearchService`` only installs user installed search extensions. For the + Application Provided engines we create those when ``SearchService`` calls `_makeEngineFromConfig `_. + Then ``_makeEngineFromConfig`` will create a new ``AddonSearchEngine``. + When the `AddonSearchEngine.init `_ + method is called, it combines both the extension and search configuration + data to create the correct engine for the user based on locale, region and + other information. + + 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 :searchfox:`SearchEngines ` + by making an `Add-on, Open Search, or Enterprise Policy Search Engine `_. + +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 March 10, 2023. If the diagram or description +becomes out of date, please find access to the +``Search Service Diagram`` through the ``Firefox Search > Search Service +Documentation`` folder in the shared drive or through this link `here `_. +Contributions are welcomed to keep this page up to date. -- cgit v1.2.3