Skip to content

Latest commit

 

History

History
137 lines (113 loc) · 4.95 KB

README_routing.md

File metadata and controls

137 lines (113 loc) · 4.95 KB

gateleen-routing

Schema validation

Updating the routing rules requires a validation against a schema to be positive. Check the schema gateleen_routing_schema_routing_rules

Routing configuration

To configure the routing, the ConfigurationResourceManager and the path to the configuration resource have to be configured in the Router by calling:

router.enableRoutingConfiguration(configurationResourceManager, SERVER_ROOT + "/admin/v1/routing/config")

The routing configuration is a json resource defining the limit for the maximum request routings (hops) called request.hops.limit and OAuth configuration called authConfigs. Check the schema gateleen_routing_schema_config

Example:

{
  "request.hops.limit": 10,
  "authConfigs": {
    "demo-config-1": {
      "flowType": "CLIENT",
      "clientId": "543567344a5005",
      "clientSecret": "212636219b3a5b",
      "site": "https://api.swisspost.ch",
      "tokenPath": "/OAuth/token",
      "authPath": "/OAuth/authorization",
      "scopes": [
        "APIM_SANDBOX_RESOURCE_SERVER_READ"
      ],
      "supportedGrantTypes": [
        "client_credentials"
      ]
    }
  }
}

Request hop validation

To protect gateleen from routing rules configured to result in an endless loop, the request hop validation feature has been introduced.

When the request hop validation is activated, a x-hops request header will be added to the request before routing. Initially, this header will receive the value 1. When the x-hops header already exists (in alredy routed requests for example), the value will be increased by 1.

Before the request is routed, the x-hops header value will be checked against a configurable limit. When the limit is exceeded, the request will be answered with a http status code 500 and a http status message: Request hops limit exceeded

OAuth2 authentication

To activate OAuth2 authentication for forwarding requests, a configuration with the required properties like flowType, clientId, clientSecret, etc. can be provided. See vertx-auth-oauth2 documentation for more information. The id of the configuration called oAuthId (demo-config-1 in the example) is used in the routing rule.

Example:

{
  "/gateleen/server/rule/1/(.*)": {
    "oAuthId": "demo-config-1",
    "url": "http://localhost/some/backend/path/$1"
  }
}

Log routing rule changes

To log the payload of changes to the routing rules, the RequestLogger can be used.

Make sure to instantiate the RequestLoggingConsumer by calling

RequestLoggingConsumer requestLoggingConsumer = new RequestLoggingConsumer(vertx, loggingResourceManager);

To enable the logging of the routing rules, make sure the url to the routing rules is enabled in the logging resource.

Example:

{
  "headers": [],
  "payload": {
    "filters": [
      {
        "url": "/playground/server/admin/v1/routing/.*",
        "method": "PUT"
      }
    ]
  }
}

Also you have to enable the logging on the Router by calling

router.enableResourceLogging(true);

Use CustomHttpResponseHandler

The CustomHttpResponseHandler can be used together with simple routing rules to respond with a configurable http status code.

Having a configured rootPath of

/gateleen/server/return-http-error

you can add the following routing rule to correctly respond every request on

/gateleen/server/unreachable/service

with a http status code 503

{
    "/gateleen/server/unreachable/service": {
        "path": "/gateleen/server/return-http-error/503",
        "methods": [
          "GET"
        ]
    }
}

Apply routing rules based on request headers

Routing rules are applied to requests based on the request url and the http method. By defining the headersFilter property, you are able to also apply a routing rule based on request headers.

Examples:

{
    "/gateleen/server/rule/1/(.*)": {
        "headersFilter": "x-foo.*",
        "url": "http://localhost/some/backend/path/$1"
    },
    "/gateleen/server/rule/2/(.*)": {
        "headersFilter": "x-foo: (A|B|C)",
        "url": "http://localhost/some/backend/path/$1"
    },
    "/gateleen/server/rule/3/(.*)": {
        "headersFilter": "x-foo: [0-9]{3}",
        "url": "http://localhost/some/backend/path/$1"
    }
}

Each request header entry is validated in the format <KEY>: <VALUE>, so you are able to filter for request header names and values.