.. _backend_sharding:

****************
Backend Sharding
****************

Backend services like App Suite Middleware might be operated in a way where multiple distinct clusters of application servers serve certain subsets of users. We call the concept of splitting up a backend service into independent deployments "sharding" and each deployment a "shard".

Any requesting facing a sharded backend service must therefore be assignable to a certain shard, i.e. the target shard must be determined during request processing in the :ref:`routing engine <request_routing>`. Later, at the forwarding stage, the request needs to be forwarded to the specific :ref:`backend pool <backend_pools>`, that maps to the actual shard.

App Suite Proxy was designed to support sharding as a first-class use-case. According configuration options and programmatic extension points exist for routing engine and the load balancing component.

.. image:: graphics/simple_sharding.png

Shard detectors
===============

A shard detector identifies a distinct shard for every incoming request. For this purpose the request is analyzed and the configured detection mechanism is applied. See the :ref:`developer <shard_detector_dev>` documentation for more information.

App Suite Http Api Shard Detector
`````````````````````````````````

This shard detector utilizes the cookie shard detector first to get a shard for the request. If this detector fails, the query shard detector is used as fallback.

Cookie shard detector
`````````````````````

The cookie shard detector checks for an existing ``open-xchange-shard`` cookie and return its value as a shard.

.. code-block:: yaml

  - name: cookie
    class: io.ox.proxy.sharding.impl.CookieShardDetector

Query shard detector
````````````````````

The query shard detector checks if the request query parameters contains a ``shard`` key and return its value as a shard. The query key can be altered by adding a list of potential keys with the ``defaultArgs`` parameters. The parameter has to be ``queryParameterNames`` and the value has to be a list of strings. The algorithm will check if any of the keys in the list is present and take the value of the first match.

.. code-block:: yaml

  - name: httpApi
    class: io.ox.proxy.sharding.impl.QueryShardDetector
      defaultArgs:
        queryParameterNames: ["shard"]

Shard bootstrap handler
=======================

The shard bootstrap handler is used, when no shard can be found for a given request. The bootstrap handler has a configured endpoint and a set of parameters that should be used to initialize the shard setting process. See the :ref:`developer <shard_bootstrap_handler_dev>` documentation for more information.

.. _oidc_shard_bootstrap_handler:

OIDC shard bootstrap handler
````````````````````````````

This bootstrap handler holds all information that is needed to redirect the user to an OpenID SSO provider for login. For this purpose the following variables have to be set in the parameters section:

.. code-block:: yaml

  - name: httpApi
    endpoint: io.ox.proxy.filters.endpoint.InitOidcSso
    parameters:
      endpoint: http://10.50.0.192:8080/c2id-login
      clientId: rr7adpursmnyw
      responseType: code
      scope: openid
      redirectUri: http://appsuite.example.com/appsuite/api/oidc/auth

:endpoint: **Mandatory:** The SSO login endpoint.

:clientId: **Mandatory:** The ID under which the App Suite client is registered.

:responseType: **Mandatory:** The response type to use. Default: code.

:scope: **Mandatory:** The scope to use. Default: openid

:redirectUri: **Mandatory:** The location where the user should be redirected after a successful login.

After that, the App Suite mechanisms for creating shard information in form of a cookie or by adding request path properties take over.

Configuration
=============

The ``sharding.yml`` file is used to configure all existing sharding detectors and bootstrap handlers.

.. code-block:: yaml

  sharding:
    # Define shard detectors for proxy rules
    detectors:
      - name: httpApi
        class: io.ox.proxy.sharding.impl.AppSuiteHttpApiShardDetector
        defaultArgs:
          queryParameterNames: ["shard"]
    bootstrapHandlers:
      - name: httpApi
        endpoint: io.ox.proxy.filters.endpoint.InitOidcSso
        parameters:
          endpoint: http://10.50.0.192:8080/c2id-login
          clientId: rr7adpursmnyw
          responseType: code
          scope: openid
          redirectUri: http://appsuite.example.com/appsuite/api/oidc/auth


**detectors**

A list of all available shard detectors.

:name: **Mandatory:** The name that identifies this detector

:class: **Mandatory:** The class that implements the detector features

:defaultArgs: **Optional:** A list of key/value pairs that hold additional information for the shard detector

**bootstrapHandlers**

A list of all available bootstrap handlers.

:name: **Mandatory:** The name that identifies this bootstrap handler

:endpoint: **Mandatory:** The destination of an endpoint filter that should be approached to initialize shard information creation

:parameters: **Optional:** A list of key/value pairs that hold additional information for the bootstrap handler