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 routing engine. Later, at the forwarding stage, the request needs to be forwarded to the specific backend pool, 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.

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 developer 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.

- 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.

- 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 developer documentation for more information.

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:

- 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.

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