A Rack application is a Ruby object that implements a call method that receives a CGI-like Rack environment hash as its argument and returns a Rack response. A Rack response is an array containing three things: a response code, headers, and a response body. The response body is an object, such as an array, that responds to the method each. The each method must yield the response body as strings when invoked. The simplest example is a Ruby object, such as a that returns an empty response body.

We're going to use Rack and the rackup tool for these examples, so you'll need to have the rack gem installed on your system. Mongrel is also a much better web server than WEBrick, so it is good to have that installed as well. Let's install both Rack and Mongrel in one go:

gem install rack mongrel

Unless you specify a handler for a particular web server, the rackup command will first try to use Mongrel, and if that isn't available, fall back to WEBrick. Read the output of rackup -h for details on all the available options.

Now let's create a simple application. Add the following code to a file named config.ru:

class RailsNutshellApp
  def call(env)
    [200, {'Content-Type' => 'text/plain'}, []]
  end
end

run RailsNutshellApp.new

Believe it or not we can actually run this as a fully working web application. The config.ru file is called a Rackup file, which we'll take a look at in a later section.

This example could also be implemented as a Ruby Proc object. A Proc object's given block is called using the call method:

run lambda { |env| [200, {'Content-Type' => 'text/plain'}, []] }

Now we'll use the rackup command to fire up a web server and start serving the application. By default, rackup will start the web server on port 9292. Feel free to pass the -p option to specify a different port. Let's start up the web server and make a request to the application:

$ rackup

You can also explicitly specify the name of the Rackup file:

$ rackup config.ru

Now let's make a HEAD request to the application with curl.

$ curl -I http://localhost:9292
HTTP/1.1 200 OK
Connection: close
Date: Sun, 30 May 2010 21:51:50 GMT
Transfer-Encoding: chunked
Content-Type: text/plain

You can see that we get a valid HTTP response from the server with an empty body. Next, let's add a short message for the response body:

class RailsNutshellApp
  def call(env)
    [200, {'Content-Type' => 'text/plain'}, ['Hello from Rack!']]
  end
end

run RailsNutshellApp.new

The response body contains the message we set:

$ curl http://localhost:9292
Hello from Rack!

As you can see, the concept behind Rack is incredibly simple and easy to use. Next we're going to take a closer look at some of the main principles behind Rack.

Rack is based on the concept of a request environment. The environment is a hash of CGI-like headers. For details on the exact format and requirements of the Rack environment you can view the complete Rack spec at http://rack.rubyforge.org/doc/files/SPEC.html.

Let's create a simple Rack application that pretty prints the Rack environment as its response body:

require 'pp'

class InspectEnvApp
  def call(env)
    PP.pp(env, response = '')
    [200, {'Content-Type' => 'text/plain'}, [response]]
  end
end

run InspectEnvApp.new

The application pretty prints the Rack env variable into the response string. Then the application returns inspected environment as the response body. Requesting the application with curl yields the following response:

$ curl http://localhost:9292
{"HTTP_HOST"=>"localhost:9292",
 "HTTP_ACCEPT"=>"*/*",
 "SERVER_NAME"=>"localhost",
 "rack.url_scheme"=>"http",
 "REQUEST_PATH"=>"/",
 "HTTP_USER_AGENT"=>
  "curl/7.19.7 (i386-apple-darwin10.2.0) libcurl/7.19.7 OpenSSL/0.9.8l zlib/1.2.3",
 "rack.errors"=>
  #<Rack::Lint::ErrorWrapper:0x101a66c90 @error=#<IO:0x1001b4a80>>,
 "SERVER_PROTOCOL"=>"HTTP/1.1",
 "rack.version"=>[1, 1],
 "rack.run_once"=>false,
 "SERVER_SOFTWARE"=>"Mongrel 1.1.5",
 "PATH_INFO"=>"/",
 "REMOTE_ADDR"=>"127.0.0.1",
 "SCRIPT_NAME"=>"",
 "rack.multithread"=>true,
 "HTTP_VERSION"=>"HTTP/1.1",
 "rack.multiprocess"=>false,
 "REQUEST_URI"=>"/",
 "SERVER_PORT"=>"9292",
 "REQUEST_METHOD"=>"GET",
 "QUERY_STRING"=>"",
 "rack.input"=>
  #<Rack::Lint::InputWrapper:0x101a66d08 @input=#<StringIO:0x101a6bb28>>,
 "GATEWAY_INTERFACE"=>"CGI/1.2"}

In the output you can see the hash of CGI-like headers mentioned earlier. It is the fact that the Rack environment hash conforms to the Rack specification that makes Rack so powerful. Rack application and framework developers can rely on the fact that the environment follows the specification and stop having to worry about different web server APIs.

You can also add your own data to the environment hash, as well as change or delete any of the information. You have to be careful when changing the environment to ensure that your modified environment still conforms to the Rack spec. You never know what other components might be relying on the data in the environment.

A Rack middleware is a Rack application that is designed to run in conjunction with another Rack application, which acts as the endpoint. Middlewares are useful for performing granular tasks that can be performed independently from the main application. In fact, Rack itself ships with many useful middlewares for common tasks such as logging requests in the Apache common log format, calculating the Content-Length header based on the size of the response body, setting a default Content-Type header, calculating ETag headers, displaying unhandled exceptions in a pretty error page, and more.

You can think of a Rack middleware as a filter that receives the Rack environment for the request from the previous middleware, if any, does some work with or on the request's environment and then calls the next middleware in the chain. The last Rack application in the chain is the application itself. Any middleware in the chain can return the Rack response itself, thus preventing the rest of the middlewares in the chain from executing. You can think of a middleware as being similar to a controller's the section called “After and Around Filters”.

We've been using the rackup command to start up our application. Rackup actually adds a few middlewares on your behalf in the default Rack environment, which is development. Rackup automatically adds the Rack::ShowExceptions, Rack::CommonLogger, and Rack::Lint middlewares to your application's stack. In the environment named deployment, Rackup only adds the Rack::CommonLogger middleware and in all other named environments Rackup doesn't add any additional middlewares. The Rack::CommonLogger writes a log statement to STDOUT in the Apache common log format for each request:

$ curl -I http://localhost:9292
HTTP/1.1 200 OK
Connection: close
Date: Sun, 30 May 2010 22:21:56 GMT
Transfer-Encoding: chunked
Content-Type: text/plain

The Rack::ShowExceptions middleware renders a nice looking errors page for all unhandled exceptions and Rack::Lint ensures that your Rack application conforms to the Rack spec. Rack::Lint will generate an exception if the response of your application does not meet the Rack spec. To view the error page that Rack::ShowExceptions generates, let's return an empty Content-Type header, which violates the Rack spec and causes Rack::Lint to raise an exception:

class RailsNutshellApp
  def call(env)
    [200, {}, []]
  end
end

run RailsNutshellApp.new

Now when requesting the application we get a nice error page provided by the Rack::ShowExceptions middleware.

Figure 10.1. Error Diagnostic Page Provided By Rack::ShowExceptions

It is helpful to look at the sequence diagram for the request in Figure 10.2, “Sequence Diagram of a Request to a Rack Application”. The diagram assumes that Mongrel is the web server handling the request. From the diagram you can see how each middleware in the stack calls the call method on the subsequent middleware. The diagram assumes that none of the middlewares in the stack return the response themselves, which is possible in a real middleware. Each middleware in the chain has its call method executed and executes the next component's call method. This architecture is why Rack middlewares act like controller around filters: code can be executed both before and after the execution of the next component's call method.

Figure 10.2. Sequence Diagram of a Request to a Rack Application

In the config.ru Rackup file we can add the Rack::ContentLength middleware to with the use directive. The use directive adds a middleware to the application's middleware stack and the run directive specifies the main Rack application to run.

Let's add the Rack::ContentLength middleware to our application's Rackup file to automatically set a Content-Type header for us. The Rack::ContentType middleware sets the Content-Type to text/html by default, but we're going to configure it to return text/plain by default:

class RailsNutshellApp
  def call(env)
    [200, {}, []]
  end
end

use Rack::ContentType, 'text/plain'
run RailsNutshellApp.new

Now, we can request the application without raising an exception because the Rack::ContentType middleware is doing its job of setting the Content-Type header:

$ curl -I http://localhost:9292
HTTP/1.1 200 OK
Connection: close
Date: Sun, 30 May 2010 22:21:56 GMT
Transfer-Encoding: chunked
Content-Type: text/plain

In addition to all of the middlewares built-in to Rack itself, there is a companion project called Rack Contrib that contains many more useful middlewares that can help speed up your development. Additionally, there is the Rack Cache, which enables a ton of HTTP caching functionality for your Rack application.

Rackup files are a simple DSL for specifying which Rack components will be used by the application. The Rackup DSL is implemented by the Rack::Builder class in Rack. You can use any Ruby syntax you want in the Rackup file in addition to the following three methods provided by the DSL.

Rails has adopted the Rack philosophy throughout the framework. A Rails application is actually a collection of Rack and Rails middleware components that all work together to form the completed whole. However, it is not immediately obvious that Rails utilizes Rack so heavily because Rails' use of Rack is deep within the core infrastructure of the framework. This is because Rack is a low-level library and specification and Rails is a high-level framework. The concepts shown throughout the beginning of this chapter are more to give an understanding of Rack than to provide immediate benefit to your application development. It isn't often that you'll need to think about Rack while developing your application, but it can be a handy tool.

Depending on what your middleware does, there are two different ways to install Rack components into your Rails application. You can either configure your Rack application as part of your application's middleware stack or you can route URI paths directly to the Rack application from you application's routes.

$ rake middleware
use ActionDispatch::Static
use Rack::Lock
use ActiveSupport::Cache::Strategy::LocalCache
use Rack::Runtime
use Rails::Rack::Logger
use ActionDispatch::ShowExceptions
use ActionDispatch::RemoteIp
use Rack::Sendfile
use ActionDispatch::Callbacks
use ActiveRecord::ConnectionAdapters::ConnectionManagement
use ActiveRecord::QueryCache
use ActionDispatch::Cookies
use ActionDispatch::Session::CookieStore
use ActionDispatch::Flash
use ActionDispatch::ParamsParser
use Rack::MethodOverride
use ActionDispatch::Head
run RailsNutshell::Application.routes

class RackController < ApplicationController
  def index
    render :text => 'Rack all the way down'
  end
end

get 'rack/index'

app = RailsNutshell::Application.routes
app.class                # => ActionDispatch::Routing::RouteSet

env = { 'REQUEST_METHOD' => 'GET',
        'PATH_INFO' => '/rack/index',
        'rack.input' => StringIO.new }
        
code, headers, body = app.call(env)

code                     # => 200
headers.keys             # => ["ETag", "Content-Type", "Cache-Control"] 
headers['ETag']          # => "\"364cd4b7c6facba9ff60c3fd96f0ffd9\""
headers['Content-Type']  # => "text/html; charset=utf-8"
headers['Cache-Control'] # => "max-age=0, private, must-revalidate"
body.class               # => ActionDispatch::Response
body.body                # => "Rack all the way down"

app = RackController.action(:index)
env = { 'REQUEST_METHOD' => 'GET', 'rack.input' => StringIO.new }
code, headers, body = app.call(env)

code      # => 200
body.body # => "Rack all the way down"

class AverageRuntime
  @@requests = 0
  @@total_runtime = 0.0
  
  def initialize(app)
    @app = app
  end
  
  def call(env)    
    code, headers, body = @app.call(env)
    
    @@requests += 1
    @@total_runtime += headers['X-Runtime'].to_f
    headers['X-AverageRuntime'] = (@@total_runtime / @@requests).to_s

    [code, headers, body]
  end
end

config.middleware.insert_before Rack::Runtime, "AverageRuntime"

$ curl -I http://localhost:3000
HTTP/1.1 200 OK
Connection: close
Date: Sat, 05 Jun 2010 18:27:46 GMT
ETag: "0019716c49d9cfe3d66d3223729c3cdf"
Content-Type: text/html; charset=utf-8
X-Runtime: 0.038098
Content-Length: 0
Cache-Control: max-age=0, private, must-revalidate
X-AverageRuntime: 0.16787325

config.middleware.use "AverageResponse"

Rails.application.middleware.use "AverageResponse"

class RackApp
  def call(env)
    [200, {'Content-Type' => 'text/plain'}, ['Rack Powered!']]
  end
end

get 'rack' => RackApp.new

$ curl http://localhost:3000/rack
Rack Powered!

gem 'sinatra'

class SinatraApp < Sinatra::Base
  get '/sing' do
    'Singing with Sinatra!'
  end
  
  get '/sing/:song' do
    "Singing #{params[:song].capitalize}!"
  end
end

get 'sing(/:song)' => SinatraApp

$ curl http://localhost:3000/sinatra
Singing with Sinatra!

$ curl http://localhost:3000/sing/lovers
Singing Lovers!