JarCasting[_] Gateleen
Gateleen is a RESTFul middleware toolkit for building API gateways.
Getting Started
Install
- Clone this repository or unzip archive
- Install and start Redis
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 |
| 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
