Skip to content

Latest commit

 

History

History
180 lines (149 loc) · 7.59 KB

README_routing.md

File metadata and controls

180 lines (149 loc) · 7.59 KB
Raw

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.

Micrometer metrics

The routing feature is monitored with micrometer. The following metrics are available:

  • gateleen_forwarded_total
  • gateleen_forwarded_seconds
  • gateleen_forwarded_seconds_max
  • gateleen_forwarded_seconds_count
  • gateleen_forwarded_seconds_sum

Additional tags are provided to split the forward count into sub counts.

tag description
metricName The metricName property from the corresponding routing rule. With this, you are able to count requests per rule
type Describes where the request was forwarded to. Possible values are local, external and null
quantile Values of 0.75 and 0.95 for percentile durations of requests

Example metrics:

# HELP gateleen_forwarded_total Amount of forwarded requests
# TYPE gateleen_forwarded_total counter
gateleen_forwarded_total{metricName="storage-resources",type="storage",} 67565.0
gateleen_forwarded_total{metricName="infotool_v1_informations",type="external",} 655.0
gateleen_forwarded_total{metricName="infotool-v1",type="storage",} 4320.0
# HELP gateleen_forwarded_seconds_max Durations of forwarded requests
# TYPE gateleen_forwarded_seconds_max gauge
gateleen_forwarded_seconds_max{metricName="storage-resources",type="storage",} 8.5515
gateleen_forwarded_seconds_max{metricName="infotool_v1_informations",type="external",} 3.456
# HELP gateleen_forwarded_seconds Durations of forwarded requests
# TYPE gateleen_forwarded_seconds summary
gateleen_forwarded_seconds{metricName="storage-resources",type="storage",quantile="0.75",} 6.2158
gateleen_forwarded_seconds{metricName="storage-resources",type="storage",quantile="0.95",} 8.2123
gateleen_forwarded_seconds_count{metricName="storage-resources",type="storage",} 67565.0
gateleen_forwarded_seconds_sum{metricName="storage-resources",type="storage",} 656434.0
gateleen_forwarded_seconds{metricName="infotool_v1_informations",type="external",quantile="0.75",} 4.2365
gateleen_forwarded_seconds{metricName="infotool_v1_informations",type="external",quantile="0.95",} 4.8998
gateleen_forwarded_seconds_count{metricName="infotool_v1_informations",type="external",} 7567.0
gateleen_forwarded_seconds_sum{metricName="infotool_v1_informations",type="external",} 256324.0

To enable the metrics, set a MeterRegistry instance by calling withMeterRegistry(MeterRegistry meterRegistry) method in RouterBuilder class.