I recently wrote an article introducing Repose which is a sponsored open-source project that is built to scale for the cloud. Repose is used within Rackspace as a a key element of our internal OpenStack.

Repose has many features such as rate limiting, client authentication, translation,API validation, versioning, *logging, *with more on the way. Today I want to show you how you can use Repose for your own projects and in particular I'm going to focus on Rate Limiting. Since Repose doesn't care what programming language my particular web service is written in, I'm going to write a very simple Node.js API server and then use Repose to enforce rate limiting on it. At the same time I will also be using Repose's HTTP Logging and IP Identity filters.

Note: I will be assuming from here that you are working in a Linux or OS X environment.

Creating the Node.js API Server

Make sure you have Node.js installed and ready to go. On your computer create a new folder called APIDemo and add a new JavaScript file called app.js in it.

The contents of the app.js file are very simple: they return the current date to the user.

Setting up and Configuring Repose

Repose requires that a few folders exist on your system. Create the following folders:
* Configuration files are located in: /etc/repose/
* The EAR file drop location is located at: /usr/share/repose/filters/
* The standalone location for Repose is at: /usr/share/lib/repose/ You can also run Repose in a container such as Apache Tomcat
* Log files are located at: /var/log/repose/
* The deployment location (where the EAR file is extracted) is at: /var/repose/

You will also need to ensure that the user account that is running Repose has the necessary access to read and execute on the appropriate folders.

With those folders created, we can move on to gathering the binary artifacts required to run Repose. Alternatively, you can grab the source code from the GitHub repository for Repose and compile the code yourself.

Here are the steps to get the configuration and binary files copied over:

Copy all of the example Repose configuration files from this location into the /etc/repose/ folder.

Copy the IP Identity configuration example file from this location into the /etc/repose/ folder

Next we will modify the example IP Identity and Rate Limiting configuration files to suit our needs. Let's start with the IP Identity file. We'll modify it to accept requests from localhost only. Of course, this is just for demonstration purposes and does not reflect a real world scenario.

Save the changes to the file and then edit the Rate Limiting config file next. What we will do here for the demonstration is lock down our API endpoint to only accept 1 HTTP GET request per minute for standard users. This value can be configured easily and any changes you make will get picked up by Repose and reloaded automatically.

rate-limiting.cfg.xml

<?xml version="1.0" encoding="UTF-8"?><rate-limitingdelegation="false"xmlns="http://docs.rackspacecloud.com/repose/rate-limiting/v1.0"><!-- Defining a limit group. The following headers can be found in the class com.rackspace.cloud.powerapi.http.PowerApiHeader in the Power API Filterlet library, maven group id com.rackspace.cloud.powerapi, artifact id filterlet. Groups are matched on the HTTP header: X-PP-Groups User information is matched on the HTTP header: X-PP-User --><limit-groupid="standard-ip-limits"groups="IP_Standard"><limituri="/*"uri-regex="/(.*)"http-methods="GET"unit="MINUTE"value="1"/></limit-group><limit-groupid="standard-ip-limits-superuser"groups="IP_Super"><limituri="/*"uri-regex="/(.*)"http-methods="GET"unit="SECOND"value="5"/></limit-group></rate-limiting>

Save the changes to the file and then edit the following config file next.

http-logging.cfg.xml

<?xml version="1.0" encoding="UTF-8"?><http-loggingxmlns="http://docs.rackspacecloud.com/repose/http-logging/v1.0"><!-- The id attribute is to help the user easily identify the log --><!-- The format includes what will be logged. The arguments with % are a subset of the apache mod_log_config found at http://httpd.apache.org/docs/2.2/mod/mod_log_config.html#formats --><http-logid="my-special-log"format="Response Code Modifiers=%200,201U\tModifier Negation=%!401a\tRemote IP=%a\tLocal IP=%A\tResponse Size(bytes)=%b\tRemote Host=%h\tRequest Method=%m\tServer Port=%p\tQuery String=%q\tTime Request Received=%t\tStatus=%s\tRemote User=%u\tURL Path Requested=%U\n"><targets><!-- The actual log file --><filelocation="/var/log/repose/repose.log"/></targets></http-log></http-logging>

Save the changes to the file and then edit the following config file next. We will just set a few simple defaults.

This file is used to enable the filters we want to use and define the order in which they should be called. It also sets the endpoint which I pointed back to our Node.js API server running on port 8080. Repose will be running on port 8888 but in a real-world environment you would probably be using port 80 for Repose.

Issue this command to make Repose listen on port 8888 (which is configured to proxy to the Node.js API server on port 8080):

$ java -jar valve-2.3.5.jar start -p 8888 -s 8188 -c /etc/repose/

Port 8188 is the port Repose listens on for a shutdown command; in a production environment, you should make sure to disable access to port 8188 from outside networks. The shutdown command can be triggered with a simple HTTP GET to this address: http://localhost:8188/ The final argument tells Repose to look in the /etc/repose/ folder for the configuration files.

<?xml version="1.0" encoding="UTF-8"?><rate-limitingdelegation="false"xmlns="http://docs.rackspacecloud.com/repose/rate-limiting/v1.0"><!-- Defining a limit group. The following headers can be found in the class com.rackspace.cloud.powerapi.http.PowerApiHeader in the Power API Filterlet library, maven group id com.rackspace.cloud.powerapi, artifact id filterlet. Groups are matched on the HTTP header: X-PP-Groups User information is matched on the HTTP header: X-PP-User --><limit-groupid="standard-ip-limits"groups="IP_Standard"><limituri="/*"uri-regex="/(.*)"http-methods="GET"unit="SECOND"value="10"/></limit-group><limit-groupid="standard-ip-limits-superuser"groups="IP_Super"><limituri="/*"uri-regex="/(.*)"http-methods="GET"unit="SECOND"value="5"/></limit-group></rate-limiting>

Rate limiting is only one small piece of what Repose can do. To learn more about Repose, the Open Repose website is your starting point providing links to the source code in GitHub. This is also the right place to find our documentation, including an FAQ and wiki; the wiki has the most current information. If you have ideas about how Repose can grow to suit your needs, you are welcome to contribute back to this project.