Now that you’ve skimmed the basics of mounting your Rack app (e.g. API) in your Rails app without touching your rackup file, you’re all set for the next step: throttling! testing!

Let’s go over a quick example with Cucumber. Don’t worry, I’ll keep it simple.

Go ahead and install cucumber-rails and database_cleaner into your Gemfile, if you aren’t using them already.

Note: You can use anything for your Rack app here, Sinatra, Grape, etc. as long as it returns a 200 status code for its base path. If you want to follow along, you can use this dumb rack app. There’s a link to a Github repo at the end of the post.

Here it is, a simple Rack app (a proc!) mounted in your Rails app at “/api”. It always responds “OK”, with status code 200.

# routes.rb
RailsApp::Application.routes.draw do
  mount proc { |env|
    [200, {}, ["OK"]]
  } => "/api"

  # your other Rails routes
end

At this point, you can start up the Rails server and hit your “API” at http://localhost:3000/api. You should see the word “OK” — that means it’s running. You just created a Rack app in your Rails app. Wasn’t that easy?

Now for the cuking. A simple feature to start off:

# features/my_dumb_api.feature
Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  Scenario: API is available
    When I send a GET request for "http://example.com/api/"
    Then the response code should be "200"

And some step definitions:

When /^I send a GET request for "([^"]*)"$/ do |path|
    get path
end

Then /^the response code should be "([^"]*)"$/ do |code|
    last_response.status.should == code.to_i
end

Now give cucumber a run.

$ cucumber features/my_dumb_api.feature

Using the default profile...
# features/my_dumb_api.feature
Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  Scenario: API is available                                # features/my_dumb_api.feature:7
    When I send a GET request for "http://example.com/api/" # features/step_definitions/api_steps.rb:1
    Then the response code should be "200"                  # features/step_definitions/api_steps.rb:5

1 scenario (1 passed)
2 steps (2 passed)
0m0.154s

Excellent! It picked it up right away. Now we can start thinking about throttling. Jump over to your Gemfile and add rack-throttle:

gem 'rack-throttle', :require => 'rack/throttle'

Update your bundle. Now, let’s start with the Cucumber feature this time.

Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  Scenario: API is available
    When I send a GET request for "http://example.com/api/"
    Then the response code should be "200"

  Scenario: Exceeding API Query Rate
    When I send more than one GET request in a second to "http://example.com/api"
    Then the response code should be "403"

And it’s corresponding steps file:

When /^I send a GET request for "([^"]*)"$/ do |path|
    get path
end

When /^I send more than one GET request in a second to "([^"]*)"$/ do |path|
    # We'll assume this happens in < 1 second
    get path
    get path
end

Then /^the response code should be "([^"]*)"$/ do |code|
    last_response.status.should == code.to_i
end

If we run this through Cucumber, it fails, because we haven’t done throttling yet. Jump to your routes file, and switch it to:

RailsApp::Application.routes.draw do
  mount Rack::Builder.new {
    use Rack::Throttle::Interval, :min => 1.0
    run proc { |env|
      [200, {}, ["OK"]]
    }
  } => "/api"
end

There, we just built a Rack app with middleware (the Rack::Throttle line), which defers to our Rack app (the proc) when the middleware passes the request onwards. Now when you run Cucumber, everything passes! You may think you’re ready to Cuke out the rest of your API, but you’re about to hit a roadblock — throttling hits all your Cucumber features. I have considered two ways to deal with this:

1. Stub out Rack::Throttle and tell it which features you specifically want to throttle using Cucumber tags.
2. Use a separate Rack app for Cucumber testing, and turn throttling on for certain features with Cucumber tags.

I chose the second option. First, I added the @no-throttle tag to the scenarios where throttling was not relevant:

Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  @no-throttle
  Scenario: API is available
    When I send a GET request for "http://example.com/api/"
    Then the response code should be "200"

  Scenario: Exceeding API Query Rate
    When I send more than one GET request in a second to "http://example.com/api"
    Then the response code should be "403"

And then a before filter in the steps file:

Before "@no-throttle" do
  @app = Rack::Builder.new {
    map "/api" do
      run proc { |env|
        [200, {}, ["OK"]]
      }
    end
  } 
end

When /^I send a GET request for "([^"]*)"$/ do |path|
    get path
end

When /^I send more than one GET request in a second to "([^"]*)"$/ do |path|
    # We'll assume this happens in < 1 second
    get path
    get path
end 
      
Then /^the response code should be "([^"]*)"$/ do |code|
    last_response.status.should == code.to_i
end

Now when you run your Cucumber features, the unthrottled scenarios will use a separate rack app, mounted without throttling. The downside to this method is that your have to keep the Rack app in api_steps.rb up to date with the one in routes.rb. A small price to pay, but less work than stubbing out Rack::Throttle.

You can browse the source code for this example Rails app on Github.

<VirtualHost *:80>
	ServerName www.example.com
	DocumentRoot /u/apps/example/current/public
	ErrorDocument 503 /maintenance.html
	RewriteEngine on
	RewriteCond %{DOCUMENT_ROOT}/../tmp/stop.txt -f
	RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
	RewriteCond %{SCRIPT_FILENAME} !maintenance.html
	RewriteRule ^(.*)$ /$1 [R=503,L]

	<Directory /u/apps/example/current/public>
		RailsEnv production
		Options -MultiViews
		AllowOverride None
		Order allow,deny
		allow from all
	</Directory>
</VirtualHost>

This worked perfectly, and allowed me to use images/css/etc on my error documents without them being redirected to 503s as well. Based on Eli Miller’s solution, I was able to write something similar for my nginx server config:

server {
	listen 80;
	server_name www.example.com;
	error_page 503 /maintenance.html;
	root /u/apps/example/current/public;
	passenger_enabled on;
	rails_env production;

	# If the maintenance stop file exists
	if (-f $document_root/../tmp/stop.txt) {
		set $maintenance 1;
	}

	# If the request exists as a static file in public
	if (-f $document_root/$uri) {
		set $maintenance 0;
	}

	if ($maintenance) {
		return 503;
	}
}

I was able to test this successfully with nginx 0.7.67 and 0.8.53, and Passenger 2.2.15 and 3.0.1. If you know a better/clearer way to do this, please share!

I learned quite a bit trying to get it working, and I hope I can help someone else with how I did it. I started this last fall, so some of the software may have been updated. Also, I would like to thank Joseph Jaramillo for his post on Deploying to IIS with lighttpd and Mongrel which was a huge help setting this up.

1. Install Ruby

For Ruby, I used the 1.8.6 one-click installer. Download, and install.

2. Install Ruby Gems

Hop on over to RubyForge and grab the latest zip file (rubygems-1.3.2.zip as of this article). Download, and install.

3. Install Rails and Mongrel

Open a command prompt and run gem install rails to get rails installed. Next, run gem install mongrel mongrel_service which will install the Mongrel server.

4. Setup a Rails Application

I will assume you have setup a Rails application before, and know how to create one from scratch or that you have one ready to drop in to be served. If you are not that experienced with Rails yet, I would recommend starting with Mongrel only for development.

Try out your Rails install by opening a command prompt to your Rails directory and running script\server (note the backslash), and then see if rails loads at http://localhost:3000/. You may get a Windows Security Alert that you need to unblock to allow outgoing connections. At this point, you have enough to run a Rails server for development, but the aim of this article is to be more robust.

5. Install lighttpd

Lighttpd is a great lightweight server that will be an excellent load-balancing proxy for this setup. We could have hooked into the Apache install from XAMPP, but I did not want to cause any problems for the group running that server.
To install lighttpd, download the most recent lighttpd installer from the WLMP project (I used LightTPD-1.4.22-1-Win32-SSL.exe). I had major problems with a Cygwin1.dll from an openSSH install conflicting with the ones for lighttpd, and had to remove the openSSH Cygwin1.dll before lighttpd would work properly; you can check for this error by running lighttpd from a command prompt and seeing if you get an error.

6. Install Windows Server 2003 Resource Kit

To get lighttpd running as the kind of service we need, download and install the Windows Server 2003 Resource Kit.

7. Install Mongrel Rails Service

We are going to have two Mongrel servers serving our Rails application, although you can run more (See How Many Mongrel Instances Should I Run?). To do this, open a command prompt and goto your Rails app directory. For each Mongrel server you want to run, enter the following command:
mongrel_rails service::install -N rails_app_4001 -p 4001
Increase the number by one for each service (4002, 4003, etc) as you run the command. This command will install Windows services that will run our Mongrel servers in the background. To start these servers, run the following command for each server, incrementing the number for each server (4001, 4002, etc.):
net start rails_app_4001
To make it easy to start and stop these servers, create a mserver.bat file in your Rails directory with the following contents:

@echo off
net %1 rails_app_4001
net %1 rails_app_4002

Add additional lines for each extra Mongrel server, again incrementing the number. This script will allow you to start/stop all the servers by opening a command prompt, going to the Rails directory, and typing mserver.bat start or mserver.bat stop , which will come in handy when restarting your Rails app. To test if these servers are running, open a web browser and navigate to ports 4001, 4002, etc on your server and see if your Rails app shows up.

8. Setup lighttpd Proxy

Download and install Joseph Jaramillo’s lighttpd conf file to your Rails directory, and put it in your config directory.

Edit the file with an app that supports UNIX-style line endings (not notepad), changing the following values:

var.basedir = “C:/Rails/myrailsapp” (point to your Rails app directory, use forward slashes)
server.bind = “” (do not bind to a specific address)
server.port = 3000 (the port you want your users to use. 80 is a good default, or if already used as in my case, 3000)
and under proxy.server, add extra entries for any additional Mongrel servers you are running.

Next, setup lighttpd to run as a Windows service. Follow Joseph’s instructions on step 3, of course changing the AppParameters to use the path to your lighttpd config file in your rails directory. Test your setup by pointing your browser at your server’s main address (or other port if you chose one other than 80), and you should see your Rails application!

If you have any comments, suggestions, or problems let me know in the comments.