The HTTP specification is a network protocol that makes up the backbone of communication on the Internet between clients and servers.

When a client (which might be a web browser, a web application, a service, etc.) wants to interact with a web server over HTTP, it composes a message. An HTTP message is plain-text and line-oriented, making it very straightforward to construct and inspect. We saw this briefly in Chapter 1 when we composed requests to our application using Telnet.

Likewise, when a server is done processing a request, it can communicate information back to the client by creating its own HTTP message. The message usually contains information such as the status (did the client request succeed, was there an error in processing the request, etc.), what type of content is being sent back (plain text, an image, HTML, etc.) and other data which we’ll discuss throughout this chapter.

A message has the following characteristics, in order:

As mentioned, the start line of an HTTP message includes a verb. This defines the type of request being made and therefore how the server will interpret it; for instance, a GET will be treated very differently than a PUT (or at least it should be!).

For most development purposes, we can focus on five commonly-used verbs.

Collectively, these verbs make up the vocabulary that Sinatra uses to express the definition of a route. There are a variety of ways to configure routes in Sinatra; we’ll examine both the common and the more esoteric. Regardless of their individual semantics, all route forms revolve around the HTTP verbs and follow a general pattern.

We saw the basic type of route definition in the sample application in Chapter 1. To declare a route in Sinatra, you must supply the HTTP verb to respond to, the specific URL, and then optionally define the behavior desired for the route. See Example 2-1 for the common form of route definition.

require 'sinatra'

get '/' do
  "Triggered via GET"
end

post '/' do
  "Triggered via POST"
end

put '/' do
  "Triggered via PUT"
end

delete '/' do
  "Triggered via DELETE"
end

patch '/' do
  "Triggered via PATCH"
end

options '/' do
  "Triggered via OPTIONS"
end

Sometimes you may encounter situations where multiple routes should respond the same way. We’re always trying to keep our code DRY, and luckily there is an approach that comes in handy without being unwieldy; Example 2-2 demonstrates how to respond to an array of routes by verb.

require 'sinatra'

['/one', '/two', '/three'].each do |route|
  get route do
	  "Triggered #{route} via GET"
  end

  post route do
    "Triggered #{route} via POST"
  end

  put route do
    "Triggered #{route} via PUT"
  end

  delete route do
    "Triggered #{route} via DELETE"
  end

  patch route do
    "Triggered #{route} via PATCH"
  end
end

get('/one/?') { ... }

Routes in Sinatra can also accept parameters that are exposed in code via the params array, as shown in Example 2-3.

require 'sinatra'
						
get '/:name' do
  "Hello, #{params[:name]}!"
end

In the case of data submission requests, the data in the payload is available in the params array. Unlike GET and DELETE requests, you don’t need to specify the payload parameters in the URL. Example 2-4 shows this in practice.

require 'sinatra'
						
post '/login' do
  username = params[:username]
  password = params[:password]
end

put '/users/:id' do
  # let's assume we could retrieve a User
  u = User.find(params[:id])
  u.first_name = params[:first_name]
  u.last_name = params[:last_name]
  u.save
end

In addition to parameters that are used to compose the URL itself, Sinatra also stores query string parameters by name in the params array. See Example 2-5.

require 'sinatra'
						
get '/:name' do
  # assumes a URL in the form /some_name?foo=XYZ
  "You asked for #{params[:name]} as well as #{params[:foo]}"
end

Routes in Sinatra can also accept wildcards in the form of the “splat” (*) character, as demonstrated in Example 2-6. Anything passed in the wildcard position is stored in params[:splat], which itself contains an array.

require 'sinatra'

get '/*' do
  "You passed in #{params[:splat]}"
end

The route described in Example 2-6 is a greedy match; for example, if you run the code and browse to http://localhost:4567/foo/bar, the output on the screen will be You passed in ["foo/bar"]. If you browse to http://localhost:4567/foo/bar/baz/bop, the output will be You passed in ["foo/bar/baz/bop"].

This brings us to a very important Sinatra routing tenet. It’s a simple rule, but critical to emphasize, especially as we move into static files and views.

When Sinatra parses routes, the first sufficient match is the one that will be executed. This is true even when there is a better or more specific route definition later in the file. Let’s take a look at a route configuration in Example 2-7, where a greedy match eats up a more specific one.

require 'sinatra'
					
get '/*' do
  "NOM NOM NOM"
end

get '/specific' do
  "You'll never, ever see me."
end

Browsing to http://localhost:4567/specific should return NOM NOM NOM even though there is a better match later in the file. It is an easily avoidable problem, but very important to bear in mind when working with a complex set of route definitions.

Sinatra also accepts regular expressions as a way to match incoming requests to particular handlers. Because of their flexible nature, we’ll also use Example 2-8 to reinforce the dangers of greedy matches.

require 'sinatra'

get %r{/(sp|gr)eedy} do
  "You got caught in the greedy route!"
end

get '/speedy' do
  "No one calls me :("
end

get '/greedy' do
  "No one calls me either!"
end

As we’re sure you can guess, the regular expression match is the first sufficient match in comparison to the routes defined later, and therefore the later routes will not be executed. This isn’t to say that using regular expressions to match routes is a bad idea. We just mean to convey that some caution should be exercised (as well as for wildcard matches).

Sometimes we don’t want an operation to continue; maybe a critical error has occurred, or perhaps a process is taking too long and we’d like to bail out. Sinatra provides a halt method for just this purpose as shown in Example 2-9.

require 'sinatra'

get '/halt' do
  'You will not see this output.'
  halt 500
end

Now let’s use cURL to see what happens when this route is executed:

$ curl -v http://localhost:4567/halt
* About to connect() to localhost port 4567 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 4567 (#0)
> GET /halt HTTP/1.1
> User-Agent: curl/7.21.2 (x86_64-apple-darwin10.4.0)
> Host: localhost:4567
> Accept: */*
> 
< HTTP/1.1 500 Internal Server Error
< Connection: close
< Date: Sat, 17 Sep 2011 21:09:42 GMT
< Content-Type: text/html;charset=utf-8
< Content-Length: 0
< 
* Closing connection #0

A status code of “500 Internal Server Error” was returned, and the text we entered was not delivered to the client (further verified by a Content-Length header of value 0).

Depending on the structure of your application, there may be instances where you’d like to pass processing on to the next best matching route (if available). To do so, simply define the criteria on which to match, and use the pass method to look for the next available match. See Example 2-10.

require 'sinatra'

before do
  content_type :txt
end

get %r{/(sp|gr)eedy} do
  pass if request.path =~ //speedy/
  "You got caught in the greedy route!"
end

get '/speedy' do
  "You must have passed to me!"
end

Now, if a user requests “/speedy”, she will actually reach the regular expression-based route handler first, then be passed along to the latter handler:

$ curl http://localhost:4567/greedy
  You got caught in the greedy route!

$ curl http://localhost:4567/speedy
  You must have passed to me!

You can redirect a request to a different location using the redirect method. Optionally, you can provide a status code as shown in Example 2-11(to differentiate between a temporary and permanent redirection, for example).

require 'sinatra'

get '/redirect' do
  redirect 'http://www.google.com'
end

get '/redirect2' do
  redirect 'http://www.google.com', 301
end

Let’s examine these routes via cURL again to see the difference that the status codes make:

$ curl -v http://localhost:4567/redirect
* About to connect() to localhost port 4567 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 4567 (#0)
> GET /redirect HTTP/1.1
> User-Agent: curl/7.21.2 (x86_64-apple-darwin10.4.0)
> Host: localhost:4567
> Accept: */*
> 
< HTTP/1.1 302 Moved Temporarily
< Connection: close
< Date: Sat, 17 Sep 2011 21:27:45 GMT
< Content-Type: text/html;charset=utf-8
< Location: http://www.google.com
< Content-Length: 0
< 
* Closing connection #0

$ curl -v http://localhost:4567/redirect2
* About to connect() to localhost port 4567 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 4567 (#0)
> GET /redirect2 HTTP/1.1
> User-Agent: curl/7.21.2 (x86_64-apple-darwin10.4.0)
> Host: localhost:4567
> Accept: */*
> 
< HTTP/1.1 301 Moved Permanently
< Connection: close
< Date: Sat, 17 Sep 2011 21:27:47 GMT
< Content-Type: text/html;charset=utf-8
< Location: http://www.google.com
< Content-Length: 0
< 
* Closing connection #0

By default, if you do not provide a status code to the redirect method, it will assume you want a temporary redirection (code 302). This indicates to clients that they would normally find the resource they were looking for at the requested URL, but for the moment it is available elsewhere. A 301 redirection tells the client that the URL they requested may have been correct in the past, but the current location is elsewhere (and in the future, the client should only request that new location).

Inline templates, unsurprisingly, are defined in the application code file itself. They are located at the bottom of the file; Example 2-14 shows how to include templates directly in your application files.

require 'sinatra'

get '/index' do
  erb :index
end

__END__

@@index 

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Inline template</title>
  </head>
  <body>
    <h1>Worked!</h1>
  </body>
</html>

It’s important to note that the name of the view must be a symbol. Inline templates require that you create a class variable of the same name so that Sinatra knows which template to render.

Things can get pretty cluttered if you’re relying solely on inline templates for your view needs. If you’d prefer to store your views externally, Sinatra will look for them by default in the “views” subfolder. In Example 2-15, a symbol containing the filename (up to the extension) is passed as the parameter for rendering. Example 2-16 shows a simple Erb file that will be rendered by the route.

require 'sinatra'

get '/index' do
  erb :index
end

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>External template</title>
  </head>
  <body>
    <h1>Worked!</h1>
  </body>
</html>

require 'sinatra'
						
get '/:user/profile' do
  erb '/user/profile'.to_sym
end

get '/:user/help' do
  erb :'/user/help'
end

Information constructed in the back-end of the application can be shared to the front-end view through the use of instance variables, as shown in Examples 2-18 and 2-19.

require 'sinatra'
					
get '/home' do
  @name = 'Random User'
  erb :home
end

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Using instance variables</title>
</head>
<body>
  <h1>Hello, <%= @name %>!</h1>
</body>
</html>

Statements to be evaluated (displaying instance variables, performing transformation operations, etc.) are wrapped in <%= %> tags, while control statements (loops, etc.) are wrapped in <% %> tags. Example 2-20 shows how to create instance variables for use in a view, while Example 2-21 demonstrates the consumption of those variables (as well as the difference between evaluated and control statements in Erb).

require 'sinatra'
				
get '/home' do
  @users = ['Sally', 'Jerry', 'Rocko']
  erb :home
end

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Using instance variables</title>
</head>
<body>
  <% @users.each do |user| %>
    <p><%= user %></p>
  <% end %>
</body>
</html>

To easily handle the absence of a route or resource matching a particular request, you can render some form of output via the not_found block, as shown in Example 2-23.

require 'sinatra'

	before do
	  content_type :txt
	end

	not_found do
	  "Whoops! You requested a route that wasn't available."
	end

Now, since there are no conventional routes defined, any requests will be handled by the not_found call.

$ curl -v http://localhost:4567/foo
* About to connect() to localhost port 4567 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 4567 (#0)
> GET /foo HTTP/1.1
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0)
> Host: localhost:4567
> Accept: */*
> 
< HTTP/1.1 404 Not Found
< X-Frame-Options: sameorigin
< X-XSS-Protection: 1; mode=block
< Content-Type: text/html;charset=utf-8
< X-Cascade: pass
< Content-Length: 52
< Connection: keep-alive
< Server: thin 1.2.11 codename Bat-Shit Crazy
< 
* Connection #0 to host localhost left intact
* Closing connection #0
Whoops! You requested a route that wasn't available.

In the event that an unhandled exception occurs while processing a request, you can handle it by defining an error block, as shown in Example 2-24.

require 'sinatra'

	before do
	  content_type :txt
	end

	configure do
	  set :show_exceptions, false
	end

	get '/div_by_zero' do
	  0 / 0
	  "You won't see me."
	end

	error do
	  "Y U NO WORK?"
	end

The “/div_by_zero” has an obvious unhandled exception in the division by zero operation. When encountered, this will result in the output of the error block being returned to the client.

$ curl -v http://localhost:4567/div_by_zero
* About to connect() to localhost port 4567 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 4567 (#0)
> GET /div_by_zero HTTP/1.1
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0)
> Host: localhost:4567
> Accept: */*
> 
< HTTP/1.1 500 Internal Server Error
< X-Frame-Options: sameorigin
< X-XSS-Protection: 1; mode=block
< Content-Type: text/plain;charset=utf-8
< Content-Length: 12
< Connection: keep-alive
< Server: thin 1.2.11 codename Bat-Shit Crazy
< 
* Connection #0 to host localhost left intact
* Closing connection #0
Y U NO WORK?

Sinatra provides a method called headers that can be used to set HTTP headers in your responses, which is demonstrated in Example 2-26. It accepts a hash where the key is the name of the header.

require 'sinatra'

before do
  content_type :txt
end

get '/' do
  headers "X-Custom-Value" => "This is a custom HTTP header."
  'Custom header set'
end

get '/multiple' do
  headers "X-Custom-Value" => "foo", "X-Custom-Value-2" => "bar"
  'Multiple custom headers set'
end

You can check these headers with a quick run via cURL.

$ curl -v localhost:4567/
* About to connect() to localhost port 4567 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 4567 (#0)
> GET / HTTP/1.1
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0)
> Host: localhost:4567
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: text/plain;charset=utf-8
< X-Custom-Value: This is a custom HTTP header.
< Content-Length: 17
< Connection: keep-alive
< Server: thin 1.2.11 codename Bat-Shit Crazy
< 
* Connection #0 to host localhost left intact
* Closing connection #0

$ curl -v localhost:4567/multiple
* About to connect() to localhost port 4567 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 4567 (#0)
> GET /multiple HTTP/1.1
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0)
> Host: localhost:4567
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: text/plain;charset=utf-8
< X-Custom-Value: foo
< X-Custom-Value-2: bar
< Content-Length: 27
< Connection: keep-alive
< Server: thin 1.2.11 codename Bat-Shit Crazy
< 
* Connection #0 to host localhost left intact
* Closing connection #0

Sinatra exposes a variety of request information via the request object, as seen in Example 2-27. The request object holds a hash of request data such as who made the request, what version of the HTTP standard to use, and so on. We’ll discuss the underlying mechanics of this object further when we delve into Rack in Chapter 3.

require 'sinatra'

before do
  content_type :txt
end

get '/' do
  request.env.map { |e| e.to_s + "
" }
end

This application will iterate over all the values in the @env variable and display them as output.

$ curl http://localhost:9393/
["GATEWAY_INTERFACE", "CGI/1.1"]
["PATH_INFO", "/"]
["QUERY_STRING", ""]
["REMOTE_ADDR", "127.0.0.1"]
["REMOTE_HOST", "localhost"]
["REQUEST_METHOD", "GET"]
["REQUEST_URI", "http://localhost:9393/"]
["SCRIPT_NAME", ""]
["SERVER_NAME", "localhost"]
["SERVER_PORT", "9393"]
["SERVER_PROTOCOL", "HTTP/1.1"]
["SERVER_SOFTWARE", "WEBrick/1.3.1 (Ruby/1.9.2/2011-07-09)"]
["HTTP_USER_AGENT", "curl/7.19.7 (universal-apple-darwin10.0)"]
["HTTP_HOST", "localhost:9393"]
["HTTP_ACCEPT", "*/*"]
["rack.version", [1, 1]]
["rack.input", #<Rack::Lint::InputWrapper:0x0000010327f368 @input=#<StringIO:0x000001009c8500>>]
["rack.errors", #<Rack::Lint::ErrorWrapper:0x0000010327f2f0 @error=#<IO:<STDERR>>>]
["rack.multithread", true]
["rack.multiprocess", false]
["rack.run_once", false]
["rack.url_scheme", "http"]
["HTTP_VERSION", "HTTP/1.1"]
["REQUEST_PATH", "/"]
["rack.request.query_string", ""]
["rack.request.query_hash", {}]

Similarly, we can iterate over the methods defined for the request object for comparison purposes. See Example 2-28.

require 'sinatra'

before do
  content_type :txt
end

get '/' do
  request.methods.map { |m| m.to_s + "
" }
end

We’ve truncated the rendered output for brevity, but you’ll see a number of the @env fields represented.

$ curl localhost:4567/
accept
preferred_type
accept?
secure?
forwarded?
safe?
idempotent?
env
body
script_name
path_info
request_method
query_string
content_length
content_type
session
session_options
logger
media_type
media_type_params
content_charset
scheme
ssl?
referer
referrer
user_agent
cookies
xhr?
base_url
url
path
fullpath
accept_encoding
ip
parse_query
parse_multipart

Using the headers helper we discussed earlier, you can set any desired headers to influence downstream caching. The code in Example 2-29 will inform consumers that the content should be cached for one hour.

require 'sinatra'

before do
  content_type :txt
end

get '/' do
  headers "Cache-Control" => "public, must-revalidate, max-age=3600",
          "Expires" => Time.at(Time.now.to_i + (60 * 60)).to_s
  "This page rendered at #{Time.now}."
end

If you visit this page in a browser, refreshing will not update the time displayed on the page. The headers are shown in the cURL session below.

$ curl -v http://localhost:9393/
* About to connect() to localhost port 9393 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 9393 (#0)
> GET / HTTP/1.1
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0)
> Host: localhost:9393
> Accept: */*
>
< HTTP/1.1 200 OK 
< Content-Type: text/plain;charset=utf-8
< Cache-Control: public, must-revalidate, max-age=3600
< Expires: 2011-09-26 17:35:04 -0400
< Content-Length: 48
< Server: WEBrick/1.3.1 (Ruby/1.9.2/2011-07-09)
< Date: Mon, 26 Sep 2011 20:35:04 GMT
< Connection: Keep-Alive
< 
* Connection #0 to host localhost left intact
* Closing connection #0
This page rendered at 2011-09-26 16:35:04 -0400.

Sinatra has a convenient shortcut for defining cache control and content expiration that wraps up the behavior described above in a shorter method call. Specifically, you can set the appropriate headers using the expires helper as shown in Example 2-30.

You can use the cache_control helper if you only want to set the Cache-Control header.

require 'sinatra'

before do
  content_type :txt
end

get '/cache' do
  expires 3600, :public, :must_revalidate
  "This page rendered at #{Time.now}."
end

This will produce the same effect as Example 2-29.

ETags, short for entity tags, are another way to represent how fresh a resource is via HTTP. They are server-generated identifiers that are used to “fingerprint” a resource in a given state. A client can safely assume that if the ETag for a resource has changed, then the resource itself has changed and should be fetched from the server again.

require 'sinatra'
require 'uuid'

before do
  content_type :txt
  @guid = UUID.new.generate
end

get '/etag' do
  etag @guid
  "This resource has an ETag value of #{@guid}."
end

$ curl -v http://localhost:9393/etag
* About to connect() to localhost port 9393 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 9393 (#0)
> GET /etag HTTP/1.1
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0)
> Host: localhost:9393
> Accept: */*
> 
< HTTP/1.1 200 OK 
< Content-Type: text/plain;charset=utf-8
< Etag: "448c1ee0-cab2-012e-0f5e-482a14372ddf"
< Content-Length: 72
< Server: WEBrick/1.3.1 (Ruby/1.9.2/2011-07-09)
< Date: Mon, 26 Sep 2011 21:13:13 GMT
< Connection: Keep-Alive
< 
* Connection #0 to host localhost left intact
* Closing connection #0
This resource has an ETag value of 448c1ee0-cab2-012e-0f5e-482a14372ddf.

require 'sinatra'
require 'uuid'

before do
  content_type :txt
  @guid = UUID.new.generate
end

get '/etag' do
  etag @guid, :weak
  "This resource has an ETag value of #{@guid}."
end

$ curl -v http://localhost:9393/etag
* About to connect() to localhost port 9393 (#0)
*   Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 9393 (#0)
> GET /etag HTTP/1.1
> User-Agent: curl/7.19.7 (universal-apple-darwin10.0)
> Host: localhost:9393
> Accept: */*
> 
< HTTP/1.1 200 OK 
< Content-Type: text/plain;charset=utf-8
< Etag: W/"448c1ee0-cab2-012e-0f5e-482a14372ddf"
< Content-Length: 72
< Server: WEBrick/1.3.1 (Ruby/1.9.2/2011-07-09)
< Date: Mon, 26 Sep 2011 21:13:13 GMT
< Connection: Keep-Alive
< 
* Connection #0 to host localhost left intact
* Closing connection #0
This resource has an ETag value of 448c1ee0-cab2-012e-0f5e-482a14372ddf.

If you’d like to destroy a session, you can call session.clear in your routes to immediately wipe out that user’s session. See Example 2-34.

require 'sinatra'

configure do
  enable :sessions
end

before do
  content_type :txt
end

get '/set' do
  session[:foo] = Time.now
  "Session value set."
end

get '/fetch' do
  "Session value: #{session[:foo]}"
end

get '/logout' do
  session.clear
  redirect '/fetch'
end

There are a number of applications that lend themselves to a persistent, open connection. Perhaps you’re developing a chat program or something similar; Example 2-37 shows how to create this type of connection and broadcast messages to subscribers.

require 'sinatra'

before do
  content_type :txt
end

connections = []

get '/consume' do
  stream(:keep_open) do |out|
    # store connection for later on
    connections << out

    # remove connection when closed properly
    out.callback { connections.delete(out) }

    # remove connection when closed due to an error
    out.errback do
      logger.warn 'we just lost a connection!'
      connections.delete(out)
    end
  end
end

get '/broadcast/:message' do
  connections.each do |out| 
    out << "#{Time.now} -> #{params[:message]}" << "
"
  end

  "Sent #{params[:message]} to all clients."
end

It’s a little tricky to demonstrate the behavior in text, but a good demonstration would be to start the application, then open a web browser and navigate to http://localhost:4567/consume. Next, open a terminal and use cURL to send messages to the server.

$ curl http://localhost:4567/broadcast/hello
Sent hello to all clients.

If you look back at the web browser, you should see that the content of the page has been updated with a time stamp and the message that you sent via the terminal. The connection remains open, and the client continues to wait for further information from the server.

An alternative to the long-running open connection is to simply keep it open long enough to stream some finite amount of information down to the client; this approach is shown in Example 2-38.

require 'sinatra'

before do
  content_type :txt
end

get '/har-har' do
  stream do |out|
    out << "Wanna hear a joke about potassium?
"
    sleep 1.5
    out << "K.
"
    sleep 1.5
    out << "I also have one about sodium!
"
    sleep 1.5
    out << "Na.
"
  end
end

Open up a web browser or cURL, make a request to http://localhost:4567/har-har and enjoy!