Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 586 insertions, 0 deletions

diff --git a/toolkit/components/search/docs/SearchConfigurationSchema.rst b/toolkit/components/search/docs/SearchConfigurationSchema.rst
new file mode 100644
index 0000000000..b57f69fe13
--- /dev/null
+++ b/toolkit/components/search/docs/SearchConfigurationSchema.rst
@@ -0,0 +1,586 @@
+===========================
+Search Configuration Schema
+===========================
+
+This document outlines the details of the schema and how the various sub-parts
+interact. For the full fields and descriptions, please see the `schema itself`_.
+
+.. note::
+    In the examples, only relevant properties are displayed.
+
+Overview
+========
+
+The configuration is a JSON blob which is object with a `data` property which
+is an array of engines:
+
+.. code-block:: js
+
+    {
+      data: [
+        {
+          // engine 1 details
+        },
+        {
+          // engine 2 details
+        }
+      ]
+    }
+
+Engine Objects
+==============
+
+An engine's details are located in the properties of the object associated with it.
+An engine that is deployed globally could be listed simply as:
+
+.. code-block:: js
+
+    {
+      "default": "no",
+      "telemetryId": "engine1-telem",
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+        }
+      }]
+    }
+
+The ``appliesTo`` section is an array of objects. At least one object is required
+to specify which regions/locales the engine is included within. If an
+``appliesTo`` object lists additional attributes then these will override any
+attributes at the top-level.
+
+For example, a more complex engine definition may be available only to users
+located specific regions or with certain locales. For example:
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "region": "us"
+        },
+        "webExtension": {
+          "id": "web-us@ext"
+        }
+      }, {
+        "included": {
+          "region": "gb"
+        },
+        "webExtension": {
+          "id": "web-gb@ext"
+        }
+      }]
+    }
+
+In this case users identified as being in the US region would use the WebExtension
+with identifier ``web-us@ext``. GB region users would get
+``web-gb@ext``, and all other users would get ``web@ext``.
+
+To direct search engines to pull ``_locale`` data from a specific locale
+directory, you can use ``webExtension.locales``.
+
+For example, in this code block:
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [
+        {
+          "included": {
+            "locales": "en-US"
+          },
+          "webExtension": {
+            "locales": [
+              "us"
+            ]
+          }
+        }, {
+          "included": {
+            "locales": "en-GB"
+          },
+          "webExtension": {
+            "locales": [
+              "uk"
+            ]
+          }
+        }
+      ]
+    }
+
+There should exist a ``us`` and ``uk`` folder in the ``locales`` directory
+of the extension, ``web``.
+
+If a locale is not provided, ``webExtension.locales`` is set to
+``SearchUtils.DEFAULT_TAG``.
+
+`Search Extensions directory <https://searchfox.org/mozilla-central/source/browser/components/search/extensions>`__
+
+`Example of a locales directory <https://searchfox.org/mozilla-central/source/browser/components/search/extensions/wikipedia/_locales>`__
+
+
+Special Attributes
+==================
+
+$USER_LOCALE
+------------
+
+If a ``webExtension.locales`` property contains an element with the value
+``"$USER_LOCALE"`` then the special value will be replaced in the
+configuration object with the users locale. For example:
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "locales": {
+            "matches": [
+              "en-US",
+              "en-GB"
+            ]
+          }
+        },
+        "webExtension": {
+          "locales": ["$USER_LOCALE"]
+        }
+      }]
+    }
+
+Will report either ``[en-US]`` or ``[en-GB]`` as the ``webExtension.locales``
+property depending on the user's locale.
+
+Since the special string is replaced, custom folder names can be searched for
+by adding the keyword in between a consistent prefix/suffix.
+
+For example, if ``webExtension.locales`` was ``["example-$USER_LOCALE"]``,
+the locale generator will generate locale names in the form of ``example-en-US``
+and ``example-en-GB``.
+
+Note: Prior to Firefox 100.0, $USER_LOCALE used an exact match.
+In Firefox 100.0 the replacement was updated to use a standard string replacement.
+
+From Firefox 98.0.1 and 97.7.1esr, ``"$USER_LOCALE"`` may also be used in the
+``telemetryId`` field.
+
+$USER_REGION
+------------
+
+This can be used in the same situations as ``"$USER_LOCALE"``, instead
+replacing ``webExtension.locale`` with a string that uses the users region.
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+        },
+        "webExtension": {
+          "locales": ["foo-$USER_REGION"]
+        }
+      }]
+    }
+
+In this example, if the user's region is ``fr``, the ``webExtension.locale``
+will be ``foo-fr``, and the code will look for the ``messages.json`` in
+the ``foo-fr`` folder of the ``_locales`` folder for this extension.
+
+Note: ``"$USER_REGION"`` was added in Firefox 98.0.1 and 97.7.1esr and used an exact match.
+In Firefox 100.0 the replacement was updated to use a standard string replacement.
+
+"default"
+---------
+
+You can specify ``"default"`` as a region in the configuration if
+the engine is to be included when we do not know the user's region.
+
+"override"
+----------
+
+The ``"override"`` field can be set to true if you want a section to
+only override otherwise included engines. ``"override"`` will only work for
+sections which apply to distributions or experiments. The experiment case was
+added in Firefox 81.
+
+Starting with Firefox 96, ``"override"`` sections may include ``included`` and
+``excluded`` information which will be applied accordingly. If they are not
+supplied, then the override section will be applied to everywhere.
+
+Example:
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        // Complicated and lengthy inclusion rules
+      }, {
+        "override": true,
+        "application": { "distributions": ["mydistrocode"]},
+        "params": {
+          "searchUrlGetParams": [
+            { "name": "custom", "value": "foobar" }
+          ]
+        }
+      }]
+    }
+
+Application Scoping
+===================
+
+An engine configuration may be scoped to a particular application.
+
+Name
+----
+
+One or more application names may be specified. Currently the only application
+type supported is ``firefox``. If an application name is specified, then it
+must be matched for the section to apply. If there are no application names
+specified, then the section will match any consumer of the configuration.
+
+In the following example, ``web@ext`` would be included on any consumer
+of the configuration, but ``web1@ext`` would only be included on Firefox desktop.
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "application": {
+            "name": []
+          }
+        }
+      ]}
+    },
+    {
+      "webExtension": {
+        "id": "web1@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "application": {
+            "name": ["firefox"]
+          }
+        }
+      ]}
+    }
+
+Channel
+-------
+
+One or more channels may be specified in an array to restrict a configuration
+to just those channels. The current known channels are:
+
+    - default: Self-builds of Firefox, or possibly some self-distributed versions.
+    - nightly: Firefox Nightly builds.
+    - aurora: Firefox Developer Edition
+    - beta: Firefox Beta
+    - release: The main Firefox release channel.
+    - esr: The ESR Channel. This will also match versions of Firefox where the
+      displayed version number includes ``esr``. We do this to include Linux
+      distributions and other manual builds of ESR.
+
+In the following example, ``web@ext`` would be set as default on the default
+channel only, whereas ``web1@ext`` would be set as default on release and esr
+channels.
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "default": "yes",
+          "application": {
+            "channel": ["default"]
+          }
+        }
+      ]}
+    },
+    {
+      "webExtension": {
+        "id": "web1@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "default": "yes",
+          "application": {
+            "channel": ["release", "esr"]
+          }
+        }
+      ]}
+    }
+
+Distributions
+-------------
+
+Distributions may be specified to be included or excluded in an ``appliesTo``
+section. The ``distributions`` field in the ``application`` section is an array
+of distribution identifiers. The identifiers match those supplied by the
+``distribution.id`` preference.
+
+In the following, ``web@ext`` would be included in only the ``cake``
+distribution. ``web1@ext`` would be excluded from the ``apples`` distribution
+but included in the main desktop application, and all other distributions.
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "application": {
+            "distributions": ["cake"]
+          }
+        }
+      ]}
+    },
+    {
+      "webExtension": {
+        "id": "web1@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "application": {
+            "excludedDistributions": ["apples"]
+          }
+        }
+      ]}
+    }
+
+Version
+-------
+
+Minimum and Maximum versions may be specified to restrict a configuration to
+specific ranges. These may be open-ended. Version comparison is performed
+using `the version comparator`_.
+
+Note: comparison against ``maxVersion`` is a less-than comparison. The
+``maxVersion`` won't be matched directly.
+
+In the following example, ``web@ext`` would be included for any version after
+72.0a1, whereas ``web1@ext`` would be included only between 68.0a1 and 71.x
+version.
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "application": {
+            "minVersion": "72.0a1"
+          }
+        }
+      ]}
+    },
+    {
+      "webExtension": {
+        "id": "web1@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+          "default": "yes",
+          "application": {
+            "minVersion": "68.0a1"
+            "maxVersion": "72.0a1"
+          }
+        }
+      ]}
+    }
+
+Experiments
+===========
+
+We can run experiments by giving sections within ``appliesTo`` a
+``experiment`` value, the Search Service can then optionally pass in a
+matching ``experiment`` value to match those sections.
+
+Sections which have a ``experiment`` will not be used unless a matching
+``experiment`` has been passed in, for example:
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "web@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+        },
+        "experiment": "nov-16",
+        "webExtension": {
+          "id": "web-experimental@ext"
+        }
+      }, {
+        "included": {
+          "everywhere": true
+        },
+        "webExtension": {
+          "id": "web-gb@ext"
+        }
+      }]
+    }
+
+Engine Defaults
+===============
+
+An engine may be specified as the default for one of two purposes:
+
+#. normal browsing mode,
+#. private browsing mode.
+
+If there is no engine specified for private browsing mode for a particular region/locale
+pair, then the normal mode engine is used.
+
+If the instance of the application does not support a separate private browsing mode engine,
+then it will only use the normal mode engine.
+
+An engine may or may not be default for particular regions/locales. The ``default``
+property is a tri-state value with states of ``yes``, ``yes-if-no-other`` and
+``no``. Here's an example of how they apply:
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "engine1@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "region": "us"
+        },
+        "default": "yes"
+      }, {
+        "excluded": {
+          "region": "us"
+        },
+        "default": "yes-if-no-other"
+      }]
+    },
+    {
+      "webExtension": {
+        "id": "engine2@ext"
+      },
+      "appliesTo": [{
+        "included": {
+          "region": "gb"
+        },
+        "default": "yes"
+      }]
+    },
+      "webExtension": {
+        "id": "engine3@ext"
+      },
+      "default": "no"
+      "appliesTo": [{
+        "included": {
+          "everywhere": true
+        },
+      }]
+    },
+    {
+      "webExtension": {
+        "id": "engine4@ext"
+      },
+      "defaultPrivate": "yes",
+      "appliesTo": [{
+        "included": {
+          "region": "fr"
+        }
+      }]
+    }
+
+In this example, for normal mode:
+
+    - engine1@ext is default in the US region, and all other regions except for GB
+    - engine2@ext is default in only the GB region
+    - engine3@ext and engine4 are never default anywhere
+
+In private browsing mode:
+
+    - engine1@ext is default in the US region, and all other regions except for GB and FR
+    - engine2@ext is default in only the GB region
+    - engine3@ext is never default anywhere
+    - engine4@ext is default in the FR region.
+
+Engine Ordering
+===============
+
+The ``orderHint`` field indicates the suggested ordering of an engine relative to
+other engines when displayed to the user, unless the user has customized their
+ordering.
+
+The default ordering of engines is based on a combination of if the engine is
+default, and the ``orderHint`` fields. The ordering is structured as follows:
+
+#. Default engine in normal mode
+#. Default engine in private browsing mode (if different from the normal mode engine)
+#. Other engines in order from the highest ``orderHint`` to the lowest.
+
+Example:
+
+.. code-block:: js
+
+    {
+      "webExtension": {
+        "id": "engine1@ext"
+      },
+      "orderHint": 2000,
+      "default": "no",
+    },
+    {
+      "webExtension": {
+        "id": "engine2@ext"
+      },
+      "orderHint": 1000,
+      "default": "yes"
+    },
+    {
+      "webExtension": {
+        "id": "engine3@ext"
+      },
+      "orderHint": 500,
+      "default": "no"
+    }
+
+This would result in the order: ``engine2@ext, engine1@ext, engine3@ext``.
+
+.. _schema itself: https://searchfox.org/mozilla-central/source/toolkit/components/search/schema/
+.. _the version comparator: https://developer.mozilla.org/en-US/docs/Mozilla/Toolkit_version_format