Introduction

Policy Engine is a self contained web service that takes care of authentication and filters such as rate limits on behalf of other web services.

How it works

Policy Engine listens for incoming HTTP requests. Each request is matched with a list of endpoint definitions using the host request header and the request path. Let’s consider the following example request:

GET / HTTP/1.1
Host: example.com

If an endpoint definition matching the host example.com and the path / is found in the Policy Engine configuration, the request is run through a set of modules that are enabled for the specific endpoint. The modules may enrich the HTTP response by setting the response status and response headers. The request above might get the following response:

HTTP/1.1 200 OK
X-Endpoint: endpointname
X-Ratelimit-Limit: 200
X-Ratelimit-Remaining: 134
X-Ratelimit-Reset: 52
X-Upstream-Host: upstream.example.com
X-Upstream-Path: /
X-Upstream-Port: 80
X-Upstream-Proto: http
X-Upstream-Url: http://upstream.example.com:80/

The response status 200 OK means that the request has been accepted by all the modules that were enabled for the endpoint. The response headers show extra information such as information about rate limits, method filters, authentication and upstream servers - information that were added to the response by the modules.

It is worth noting at this point that the Policy Engine considers incoming requests as policy requests. Its responses will not contain the data/resource that was requested by the client, but instead they are to be considered as policy responses - or the responses to the policy requests.

Policy Engine is designed for integration with other services. The Integration section shows how this can be done.

Endpoints

Endpoints are configured by writing JSON files in /var/lib/policy-engine/endpoints/ or using the HTTP API. Changes done using the HTTP API are persisted as JSON files the same directory.

The following is a minimal endpoint definition, stored as articles.json in the /var/lib/policy-engine/endpoints/ directory.

{
    "name": "articles",
    "host": "api.example.com",
    "path": "/articles/*"
}

This specific endpoint will match client requests to the host api.example.com with the path /articles/ or any path below. Wildcards are supported both in host and path. The Endpoints section explains the way the matching logic works.

No modules are enabled in this configuration, so responses will only contain the name of the endpoint (articles) and the response status will always be 200 OK.

HTTP/1.1 200 OK
X-Endpoint: articles

Modules

Modules enable various functionality on specific endpoints, such as authentication, rate limiting and pointers to upstream. The minimal endpoint definition above can be extended with rate limiting capability and a pointer to upstream like this:

{
    "name": "articles",
    "host": "api.example.com",
    "path": "/articles/*",
    "modules": [
        {
            "order": 0,
            "name": "upstream-simple",
            "default": {
                "url":  "https://upstream.example.com/"
            }
        },
        {
            "order": 1,
            "name": "rate-limit",
            "default": {
                "second": 10,
                "minute": 1000
            }
        }
    ]
}

The following shows how this configuration will enrich the response headers with information about the rate limit and upstream.

GET /articles/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Date: Mon, 19 Sep 2016 11:08:54 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8
X-Endpoint: articles
X-Ratelimit-Limit: 10 1000
X-Ratelimit-Remaining: 9 999
X-Ratelimit-Reset: 0 59
X-Upstream-Host: upstream.example.com
X-Upstream-Path: /articles/42
X-Upstream-Port: 443
X-Upstream-Preserve-Host: false
X-Upstream-Proto: https
X-Upstream-Url: https://upstream.example.com:443/articles/42

The response status 200 OK indicates that the request was successfully matched with a valid endpoint and accepted by all of its modules. In this specific case, it means that the client is within its rate limits. A response status 429 Too Many Requests would indicate quota exceeded.

The response headers contain extra information about the request. In this example rate limit information that can be relayed to the client, and upstream information that is valuable when deciding where to fetch the content from.

The Modules section lists all the available modules.

Next step

Now it is time for installation and initial configuration, explained in the Get Started article.