browser/components/urlbar/docs/lifetime.rst

   1 Search Lifecycle
   2 ================
   3
   4 When a character is typed into the address bar, or the address bar is focused,
   5 we initiate a search. What follows is a simplified version of the
   6 lifetime of a search, describing the pipeline that returns results for a typed
   7 string. Some parts of the query lifetime are intentionally omitted from this
   8 document for clarity.
   9
  10 The search described in this document is internal to the address bar. It is not
  11 the search sent to the default search engine when you press Enter. Parts of this
  12 process often occur multiple times per keystroke, as described below.
  13
  14 It is recommended that you first read the :doc:`nontechnical-overview` to become
  15 familiar with the terminology in this document. This document is current as
  16 of April 2023.
  17
  18 #.
  19    The user types a query (e.g. "coffee near me") into the *UrlbarInput*
  20    `<input> DOM element <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/base/content/navigator-toolbox.inc.xhtml#330-336>`_.
  21    That DOM element `tells <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#3312>`_
  22    *UrlbarInput* that text is being input.
  23
  24 #.
  25    *UrlbarInput* `starts a search <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#3395>`_.
  26    It `creates <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#1549>`_
  27    a `UrlbarQueryContext <https://firefox-source-docs.mozilla.org/browser/urlbar/overview.html#the-urlbarquerycontext>`_
  28    and `passes it to UrlbarController <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#1548>`_.
  29    The query context is an object that will exist for the lifetime of the query
  30    and it's how we keep track of what results to show. It contains information
  31    like what kind of results are allowed, the search string ("coffee near me",
  32    in this case), and other information about the state of the Urlbar. A new
  33    *UrlbarQueryContext* is created every time the text in the input changes.
  34
  35 #.
  36    *UrlbarController* `tells UrlbarProvidersManager <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarController.sys.mjs#140>`_
  37    that the providers should fetch results.
  38
  39 #.
  40    *UrlbarProvidersManager* tells `each <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#408>`_
  41    provider to decide if it wants to provide results for this query by calling
  42    their `isActive <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#422>`_
  43    methods. The provider can decide whether or not it will be active for this
  44    query. Some providers are rarely active: for example,
  45    *UrlbarProviderTopSites* `isn't active if the user has typed a search string <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProviderTopSites.sys.mjs#97>`_.
  46
  47 #.
  48    *UrlbarProvidersManager* then tells the *active* providers to fetch results by
  49    `calling their startQuery method <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#462>`_.
  50
  51 #.
  52    The providers fetch results for the query asynchronously. Each provider
  53    fetches results in a different way. As one example, if the default search
  54    engine is Google, *UrlbarProviderSearchSuggestions* would send the string
  55    "coffee near me" to Google. Google would return a list of suggestions and
  56    *UrlbarProviderSearchSuggestions* would create a *UrlbarResult* for each one.
  57
  58 #.
  59    The providers send their results back to *UrlbarProvidersManager*. They do
  60    this one result at a time by `calling the addCallback callback <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProviderSearchSuggestions.sys.mjs#292>`_
  61    passed into startQuery. *UrlbarProvidersManager* takes all the results from all the
  62    providers and `puts them into the list of unsorted results <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#607>`_.
  63
  64    Due to the asynchronous and parallel nature of providers, this and the
  65    following steps may occur multiple times per search. Some providers may take
  66    longer than others to return their results. We don't want to wait for slow
  67    providers before showing results. To handle slow providers,
  68    *UrlbarProvidersManager* gathers results from providers in "chunks". A timer
  69    fires on an internal. Every time the timer fires, we take whatever results we
  70    have from the active providers (the "chunk" of results) and perform the
  71    following steps.
  72
  73 #.
  74    *UrlbarProvidersManager* `asks <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#648>`_
  75    *UrlbarMuxer* to sort the unsorted results.
  76
  77 #.
  78    *UrlbarMuxer* chooses the results that will be shown to the user. It groups
  79    and sorts the results to determine the order in which the results will be
  80    shown. This process usually involves discarding irrelevant and duplicate
  81    results. We also cap results at a limit, defined in the
  82    ``browser.urlbar.maxRichResults`` preference.
  83
  84 #.
  85    Once the results are sorted, *UrlbarProvidersManager*
  86    `tells UrlbarController <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#675>`_
  87    that results are ready to be shown.
  88
  89 #.
  90    *UrlbarController* `sends out a notification <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarController.sys.mjs#213>`_
  91    that results are ready to be shown. *UrlbarView* was `listening <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#662>`_
  92    for that notification. Once the view gets the notification, it `calls #updateResults <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#670>`_
  93    to create `DOM nodes <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#1185>`_
  94    for each *UrlbarResult* and `inserts them <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#1156>`_
  95    into the view's DOM element.
  96
  97    As described above, we may reach this step multiple times per search. That
  98    means we may be updating the view multiple times per keystroke. A view that
  99    visibly changes many times after a single keystroke is perceived as
 100    "flickering" by the user. As a result, we try to limit the number of times
 101    the view needs to update.
 102
 103
 104    .. figure:: assets/lifetime/lifetime.png
 105       :alt: A chart with boxes representing the various components of the
 106             address bar. An arrow moves between the boxes to illustrate a query
 107             moving through the components.
 108       :scale: 80%
 109       :align: center