.. _configuration_escaper_route_upstream:

route_upstream
==============

This escaper chooses the next escaper from rules that match the upstream host
or address.

There is no path selection support for this escaper.

The following common keys are supported:

* :ref:`default_next <conf_escaper_common_default_next>`

Selection order is fixed by the runtime:

* For IP upstreams: ``exact_match`` then ``subnet_match`` then ``default_next``
* For domain upstreams: ``exact_match`` then ``suffix_match`` then ``regex_match`` then ``default_next``

Rules duplicated across different next escapers are rejected during config
loading.

exact_match
-----------

**optional**, **type**: seq | map

If the host part of the upstream address exactly matches a configured rule, the corresponding escaper is selected.

For seq format:

  Each rule is in *map* format, with two keys:

  * next

    **required**, **type**: :external+values:ref:`metric node name <conf_value_metric_node_name>`

    Set the next escaper.

  * hosts

    **optional**, **type**: seq, **alias**: host

    Each element should be :external+values:ref:`host <conf_value_host>`.

    A host must not appear in rules for different next escapers.

  Example:

  .. code-block:: yaml

    - next: deny
      hosts:
        - example.net
    - next: allow
      hosts:
        - 192.168.1.1

For map format:

  Each key is the next escaper name, and each value has the same format as ``hosts`` in the sequence form.

  Example:

  .. code-block:: yaml

    deny:
      - example.net
    allow:
      - 192.168.1.1

.. versionchanged:: 1.11.5 support map format

Example
-------

.. code-block:: yaml

   default_next: direct
   exact_match:
     deny:
       - blocked.example.net
   suffix_match:
     internal:
       - corp.example.net
   suffix_match:
     canary:
       - s1.example.net
   regex_match:
     debug:
       - suffix: corp.example.net
         regex: '^test[0-9]+$'

subnet_match
------------

**optional**, **type**: seq | map

If the host is an IP address and matches multiple subnets, the longest-prefix match is used.

For seq format:

  Each rule is in *map* format, with two keys:

  * next

    **required**, **type**: :external+values:ref:`metric node name <conf_value_metric_node_name>`

    Set the next escaper.

  * subnets

    **optional**, **type**: seq, **alias**: subnet

    Each element should be :external+values:ref:`ip network str <conf_value_ip_network_str>`.

    A subnet must not appear in rules for different next escapers.

  Example:

  .. code-block:: yaml

    - next: deny
      subnets:
        - 192.168.0.0/16
    - next: allow
      subnets:
        - 192.168.0.0/24

For map format:

  Each key is the next escaper name, and each value has the same format as ``subnets`` in the sequence form.

  Example:

  .. code-block:: yaml

    deny:
      - 192.168.0.0/16
    allow:
      - 192.168.0.0/24

.. versionchanged:: 1.11.5 support map format

suffix_match
------------

**optional**, **type**: seq | map, **alias**: child_match

If the upstream domain ends with the suffix domain (a child of that domain), the corresponding escaper is selected.

For seq format:

  Each rule is in *map* format, with two keys:

  * next

    **required**, **type**: :external+values:ref:`metric node name <conf_value_metric_node_name>`

    Set the next escaper.

  * domains

    **optional**, **type**: seq, **alias**: domain

    Each element should be :external+values:ref:`domain <conf_value_domain>`.

    A domain must not appear in rules for different next escapers.

  Example:

  .. code-block:: yaml

    - next: deny
      domains:
        - example.net
    - next: allow
      domains:
        - test.example.net

For map format:

  Each key is the next escaper name, and each value has the same format as ``domains`` in the sequence form.

  Example:

  .. code-block:: yaml

    deny:
      - example.net
    allow:
      - test.example.net

.. versionchanged:: 1.11.5 support map format
.. versionchanged:: 1.13.3 suffix_match now matches by domain hierarchy instead of string suffix

regex_match
-----------

**optional**, **type**: seq | map

If the upstream domain matches one of the configured regular expressions, the corresponding escaper is selected.

For seq format:

  Each rule is in *map* format, with two keys:

  * next

    **required**, **type**: :external+values:ref:`metric node name <conf_value_metric_node_name>`

    Set the next escaper.

  * rules

    **optional**, **type**: seq, **alias**: rule

    Each element should be a map or :external+values:ref:`regex str <conf_value_regex_str>`.

    The following keys are used in the map format:

      - suffix | parent

        **optional**, **type**: :external+values:ref:`domain <conf_value_domain>`

        Parent domain to strip off, including the trailing ``.``, before applying the regex.
        If omitted, the full domain is matched.

        .. versionchanged:: added suffix key since version 1.13.3

      - regex

        **required**, **type**: :external+values:ref:`regex str <conf_value_regex_str>`

        Regular expression to apply.

    A rule must not appear in rules for different next escapers.

  Example:

  .. code-block:: yaml

    - next: deny
      rules:
        - suffix: example.net
          regex: abc.*  # only match the sub part
    - next: allow
      rules:
        - suffix: example.net
          regex: tes.+ # only match the sub part
        - .*[.]example[.]org  # match the full domain
    # test.example.net will match `allow`

For map format:

  Each key is the next escaper name, and each value has the same format as ``rules`` in the sequence form.

  Example:

  .. code-block:: yaml

    deny:
      - suffix: example.net
        regex: abc.*  # only match the sub part
    allow:
      - suffix: example.net
        regex: tes.+ # only match the sub part
      - .*[.]example[.]org  # match the full domain
    # test.example.net will match `allow`

.. versionadded:: 1.11.5