[_] Gateleen

Gateleen is a RESTFul middleware toolkit for building API gateways.

Getting Started

Install

• Clone this repository or unzip archive
• Install and start Redis
  • Debian/Ubuntu: apt-get install redis-server
  • Fedora/RedHat/CentOS: yum install redis
  • OS X: brew install redis
  • Windows
  • Other

Build

You need Java 8 and Maven

cd gateleen
mvn install

We're using a (private) mirror where we download npm/node from. In case you've no access to that mirror, you can use maven profile publicRepos (Eg: mvn install -PpublicRepos).

Play

A Redis is needed for this

redis-server

The gateleen-playground module provides a server example.

java -jar gateleen-playground/target/playground.jar

It starts on http://localhost:7012/playground

The storage is currently empty, that's why you get 404 Not Found

Upload some demo stuff using

mvn deploy -PuploadStaticFiles

The playground module provides a convenient web client for manipulating resources and a basic configuration.

Create your first resource with

curl -X PUT -d '{ "foo": "bar" }' http://localhost:7012/playground/hello/world

or any other REST Client

Now you can see the resource appear in http://localhost:7012/playground

Run integration tests

Once the playground is up the UI based integration tests can be executed using

mvn install -PuiIntegrationTests -Dsel_chrome_driver=/usr/local/chromedriver

there are also integration tests that are not based on the playground UI.

Note: Stop the playground prior to running these test:

mvn install -PnonUiIntegrationTests 

Modules

Module	Description
core	HTTP infrastructure and hierarchical resource storage that can be used as cache, intermediate storage for backend-pushed data, user and apps data
cache	Cache JSON responses locally to reduce load on backends and increase performance.
delegate	With the delegate feature a client is able to delegate requests to perform prespecified tasks.
delta	Traffic optimization allowing clients to fetch only data that actually changed from the last time they fetched it
expansion	Traffic optimization allowing clients to fetch a sub-tree of data in one request instead of many requests
hook	Server push and callback support allowing backends to push data to clients and be notified when data is pushed by clients
integrationtest	Test infrastructure
logging	Logs request with configurable filtering for later data analysis
monitoring	Monitor useful information like number of requests, queue sizes, etc.
packing	Traffic optimization gathering multiple requests in one
performancetest	Execute load tests using Gatling.io against a running playground instance
player	Test tool to replay traffic recorded with gateleen-logging for automated tests and troubleshooting
playground	Server example
qos	Traffic priorization by rejecting requests to low-priority routes to keep more important features working when backends go down and load increases due to timeouts and retries
queue	Request queuing to be robust to slow and available backends keeping the client connections short-lived
routing	Configurable URL patterns and method based routing to backends and resource storage
runconfig	Test infrastructure
scheduler	Performs planned operations like data cleaning
security	Fine grained authorization for URL patterns and methods against principal headers
test	Integration tests
user	Manages user profile merges user preferences and identity information
validation	Validates data according to JSON schemas
kafka	Forward requests to Kafka topics

Headers

This is a list of the custom headers used by Gateleen.

Header	Description	Link to documentation
x-rp-unique-id	unique id
x-request-id	id of the request (unique?)
x-self-request	indicates if the request is triggered by a communication server and the target is the communication server itself
x-rp-grp	group header	gateleen-user
x-roles	role header
x-delta	used by the delta parameter to mark a delta request	gateleen-delta
x-delta-backend	used by the delta parameter as a marker header to know that we should let the request continue to the router	gateleen-delta
x-expire-After	indicates how long (in seconds) a request is 'valid' before it expires
x-hooked	used by the HookHandler to indicate the original hook request as hooked	gateleen-hook
x-pack-size	indicates if a request is packed	gateleen-packing
x-client-timestamp	timestamp of the client while sending the request
x-server-timestamp	timestamp of the server while sending the request
x-queue	indicates a queued request	gateleen-queue
x-duplicate-check	indicates if a request is a duplicate or not
x-on-behalf-of	indicates the user the request originally was made from. This header is used when the request of a user is sent by another user because it couldn't be sent at that time (offline)
x-user-<pattern>	used for the user profile
x-rp-deviceid	used to check if device is authorized
x-rp-usr	used to check if user is authorized	gateleen-user
x-rp-lang	used to specify the language of the user profile	gateleen-user
x-valid	indicates if a request is to be validated or not	gateleen-validation
x-sync
x-log
x-service	contains the name of the service, which created the request
x-queue-expire-after	indicates how long (in seconds) a request is 'valid' in the queue before it expires

Performance Tuning

• The amount of max open files per process should be at least 16384. You can check your max open files per process with this command cat /proc/<process id>/limits.
• The amount of open files depends on the amount of open Http Requests, which are holding a tcp connection which are holding a file handle.
• The important number to control the open HTTP requests is the pool size of the Http Client. The higher the pool size the higher the open files.

Dependencies

• vertx-rest-storage at least release v2.0.2
• vertx-redisques at least release v.2.0.1