Sinatra is a Domain Specific Language(DSL) for quickly creating web-applications in ruby. It keeps a minimal feature set, leaving the developer to use the tools that best suit them and their application.
The simplest way to obtain Sinatra is through rubygems
$ sudo gem install sinatraSinatra is installed and you’re done eating cake, how about making your first application?
# myapp.rb
require 'rubygems'
require 'sinatra'
get '/' do
'Hello world!'
endRun this by doing $ ruby myapp.rb and view it at http://localhost:4567
Looking to live life (or Sinatra I should say) on the edge, huh? Well, it’s rather simple. The latest greatest Sinatra is on Github; so using the power of git and the power of our minds–we can do the following
To use this unholy power, simply add this line to your sinatra.rb file
$:.unshift File.dirname(__FILE__) + '/sinatra/lib'
require 'sinatra'That is certainly life on the edge.
This book will assume you have a basic knowledge of the Ruby scripting language and a working ruby interpreter.
For more information about the Ruby language visit the following links:
Sinatra’s routes are designed to respond to the HTTP request methods.
Simple
get '/hi' do
...
endWith params
get '/:name' do
# matches /sinatra and the like and sets params[:name]
endget '/say/*/to/*' do
# matches /say/hello/to/world
params["splat"] # => ["hello", "world"]
end
get '/download/*.*' do
# matches /download/path/to/file.xml
params["splat"] # => ["path/to/file", "xml"]
endget '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
"You're using Songbird version #{params[:agent][0]}"
end
get '/foo' do
# matches non-songbird browsers
endOther methods are requested exactly the same as “get” routes. You simply use the “post”, “put”, or “delete” functions to define the route, rather then the “get” one. To access POSTed parameters, use params[:xxx] where xxx is the name of the form element that was posted.
post '/foo' do
"You just asked for foo, with post param bar equal to #{params[:bar]}"
endSince browsers don’t natively support the PUT and DELETE methods, a hacky workaround has been adopted by the web community. Simply add a hidden element with the name “_method” and the value equal to the HTTP method you want to use. The form itself is sent as a POST, but Sinatra will interpret it as the desired method.
When you want to use PUT or DELETE form a client that does support them (like Curl, or ActiveResource), just go ahead and use them as you normally would, and ignore the _method advice above. That is only for hacking in support for browsers.
Each time you add a new route to your application, it gets compiled down into a regular expression that will match it. That is stored in an array along with the handler block attached to that route.
When a new request comes in, each regex is run in turn, until one matches. Then the the handler (the code block) attached to that route gets executed.
Handler is the generic term that Sinatra uses for the “controllers”. A handler is the initial point of entry for new http requests into your application.
To find more about the routes, head to the Routes section (right above this one)
The redirect helper is a shortcut to a common http response code (302).
Basic usage is easy:
redirect '/'
redirect '/posts/1'
redirect 'http://www.google.com'The redirect actually sends back a Location header to the browser, and the browser makes a followup request to the location indicated. Since the browser makes that followup request, you can redirect to any page, in your application, or another site entirely.
The flow of requests during a redirect is: Browser –> Server (redirect to ’/’) –> Browser (request ’/’) –> Server (result for ’/’)
Sinatra sends a 302 response code as a redirect by default. According to the spec, 302 shouldn’t change the request method, but you can see a note saying that most clients do change it. Apparently the mobile browser that person was using did things correctly (instead of the mainstream misinterpretation).
The fix for this in the spec is 2 different response codes: 303 and 307. 303 resets to GET, 307 keeps the same method.
To force Sinatra to send a different response code, it’s very simple:
redirect '/', 303 # forces the 303 return code
redirect '/', 307 # forces the 307 return codeSinatra ships with basic support for cookie based sessions. To enable it, in a configure block, or at the top of your application, you just need to enable to option.
enable :sessionsThe downside to this session approach is that all the data is stored in the cookie. Since cookies have a fairly hard limit of 4 kilobytes, you can’t store much data. The other issue is that the cookie is not tamper proof. The user can change any data in their session. But… it is easy, and it doesn’t have the scaling problems that memory or database backed sessions run into.
Cookies are a fairly simple thing to use in Sinatra, but they have a few quirks.
Lets first look at the simple use case:
require 'sinatra'
get '/' do
# Get the string representation
cookie = request.cookies["thing"]
# Set a default
cookie ||= 0
# Convert to an integer
cookie = cookie.to_i
# Do something with the value
cookie += 1
# Reset the cookie
set_cookie("thing", cookie)
# Render something
"Thing is now: #{cookie}"
endSetting a path, expiration date, or domain gets a little more complicated - see the source code for set_cookie if you want to dig deeper.
set_cookie("thing", { :domain => myDomain,
:path => myPath,
:expires => Date.new } )That’s the easy stuff with cookies - It can also serialize Array objects, separating them with ampersands (&), but when they come back, it doesn’t deserialize or split them in any way, it hands you the raw, encoded string for your parsing pleasure.
If you want to set your own status response instead of the normal 200 (Success), you can use the status-helper to set the code, and then still render normally:
get '/' do
status 404
"Not found"
endAlternatively you can use throw :halt, [404, "Not found"] to immediately stop any further actions and return the specified status code and string to the client. throw supports more options in this regard, see the appropriate section for more info.
These are run in Sinatra::EventContext
before do .. this code will run before each event .. end
All file-based views are looked up in:
root
| - views/get '/' do
haml :index
endThis will render ./views/index.haml
get '/' do
sass :styles
endThis will render ./views/styles.sass
get '/' do
erb :index
endThis will render ./views/index.erb
get '/' do
builder :index
endThis will render ./views/index.builder
get '/' do
builder do |xml|
xml.node do
xml.subnode "Inner text"
end
end
endThis will render the xml inline, directly from the handler.
Layouts are simple in Sinatra. Put a file in your views directory named “layout.erb”, “layout.haml”, or “layout.builder”. When you render a page, the appropriate layout will be grabbed (of the same filetype), and used.
The layout itself should call yield at the point you want the content to be included.
An example haml layout file could look something like this:
%html
%head
%title SINATRA BOOK
%body
#container
= yieldlayout => false, and you’re good.
get ’/’ do haml :index, :layout => false end
This one is cool:
get '/' do
haml :index
end
use_in_file_templates!
__END__
@@ layout
X
= yield
X
@@ index
%div.title Hello world!!!!!Try it!
It is ill-advised to create helpers on the root level of your application. They muddy the global namespace, and don’t have easy access to the request, response, session or cookie variables.
Instead, use the handy helpers method to install methods on Sinatra::EventContext for use inside events and templates.
Example:
helpers do
def bar(name)
"#{name}bar"
end
end
get '/:name' do
bar(params[:name])
endUsing partials in your views is a great way to keep them clean. Since Sinatra takes the hands off approach to framework design, you’ll have to implement a partial handler yourself.
Here is a really basic version:
# Usage: partial :foo
helpers do
def partial(page, options={})
haml page, options.merge!(:layout => false)
end
endA more advanced version that would handle passing local options, and looping over a hash would look like:
# Render the page once:
# Usage: partial :foo
#
# foo will be rendered once for each element in the array, passing in a local variable named "foo"
# Usage: partial :foo, :collection => @my_foos
helpers do
def partial(template, *args)
options = args.extract_options!
options.merge!(:layout => false)
if collection = options.delete(:collection) then
collection.inject([]) do |buffer, member|
buffer << haml(template, options.merge(
:layout => false,
:locals => {template.to_sym => member}
)
)
end.join("\n")
else
haml(template, options)
end
end
end// TODO: What useful rack middleware is out there? Is there any 3rd party stuff available outside of the builtin ones?
Remember: These are run inside the Sinatra::EventContext which means you get all the goodies is has to offer (i.e. haml, erb, :halt, etc.)
Whenever NotFound is raised this will be called
not_found do
'This is nowhere to be found'
endBy default error will catch Sinatra::ServerError
Sinatra will pass you the error via the ‘sinatra.error’ in request.env
error do
'Sorry there was a nasty error - ' + request.env['sinatra.error'].name
endCustom error mapping:
error MyCustomError do
'So what happened was...' + request.env['sinatra.error'].message
endthen if this happens:
get '/' do
raise MyCustomError, 'something bad'
endyou gets this:
So what happened was... something badBecause Sinatra give you a default not_found and error do :production that are secure. If you want to customize only for :production but want to keep the friendly helper screens for :development then do this:
configure :production do
not_found do
"We're so sorry, but we don't what this is"
end
error do
"Something really nasty happened. We're on it!"
end
endThis will cover how to deploy Sinatra to a load balanced reverse proxy setup using Lighttpd and Thin.
Install Lighttpd and Thin
# Figure out lighttpd yourself, it should be handled by your
# linux distro's package manager
# For thin:
gem install thinCreate your rackup file - the “require ‘app’” line should require the actual Sinatra app you have written.
require 'app'
set :env, :production
set :port, 4567
disable :run, :reload
run Sinatra.applicationSetup a config.yml - change the /path/to/my/app path to reflect reality.
---
environment: production
chdir: /path/to/my/app
address: 127.0.0.1
user: root
group: root
port: 4567
pid: /path/to/my/app/thin.pid
rackup: /path/to/my/app/config.ru
log: /path/to/my/app/thin.log
max_conns: 1024
timeout: 30
max_persistent_conns: 512
daemonize: trueSetup lighttpd.conf - change mydomain to reflect reality. Also make sure the first port here matches up with the port setting in config.yml.
$HTTP["host"] =~ "(www\.)?mydomain\.com" {
proxy.balance = "fair"
proxy.server = ("/" =>
(
( "host" => "127.0.0.1", "port" => 4567 ),
( "host" => "127.0.0.1", "port" => 4568 )
)
)
}Start thin and your application. I have a rake script so I can just call “rake start” rather than typing this in.
thin -s 2 -C config.yml -R config.ru startYou’re done! Go to mydomain.com/ and see the result! Everything should be setup now, check it out at the domain you setup in your lighttpd.conf file.
Variation - nginx via proxy - The same approach to proxying can be applied to the nginx web server
upstream www_mydomain_com {
server 127.0.0.1:5000;
server 127.0.0.1:5001;
}
server {
listen www.mydomain.com:80
server_name www.mydomain.com live;
access_log /path/to/logfile.log
location / {
proxy_pass http://www_mydomain_com;
}
}Variation - More Thin instances - To add more thin instances, change the -s 2 parameter on the thin start command to be how ever many servers you want. Then be sure lighttpd proxies to all of them by adding more lines to the proxy statements. Then restart lighttpd and everything should come up as expected.
Hate deployment via FastCGI? You’re not alone. But guess what, Passenger supports Rack; and this book tells you how to get it all going.
You can find additional documentation at the Passenger Github repository.
Setting up the account in the Dreamhost interface
Domains -> Manage Domains -> Edit (web hosting column)
Enable 'Ruby on Rails Passenger (mod_rails)'
Add the public directory to the web directory box. So if you were using 'rails.com', it would change to 'rails.com/public'
Save your changesCreating the directory structure
domain.com/
domain.com/tmp
domain.com/public
# a vendored version of sinatra - not necessary if you use the gem
domain.com/sinatraCreating the “Rackup file” (rack configuration file) config.ru
# This file goes in domain.com/config.ru
require 'sinatra/lib/sinatra.rb' # "require 'sinatra'" if installed as a gem
require 'rubygems'
require 'test.rb' # assumes your Sinatra application file is 'test.rb'
set :env, :production
disable :run
run Sinatra.applicationA very simple Sinatra application
# this is test.rb referred to above
get '/' do
"Worked on dreamhost"
end
get '/foo/:bar' do
"You asked for foo/#{params[:bar]}"
endAnd that’s all there is to it! Once it’s all setup, point your browser at your domain, and you should see a ‘Worked on Dreamhost’ page. To restart the application after making changes, you need to run touch tmp/restart.txt.
Please note that currently passenger 2.0.3 has a bug where it can cause Sinatra to not find the view directory. In that case, add :views => '/path/to/views/' to the Sinatra options in your Rackup file.
Additional note: some documentation sources will have a different format for passing options to Sinatra in the Rackup file, e.g.:
Sinatra::Application.default_options.merge!(
:run => false,
:env => :production,
:raise_errors => true
)The standard method for deployment is to use Thin or Mongrel, and have a reverse proxy (lighttpd, nginx, or even Apache) point to your bundle of servers.
But that isn’t always possible. Cheaper shared hosting (like Dreamhost) won’t let you run Thin or Mongrel, or setup reverse proxies (at least on the default shared plan).
Luckily, Rack supports various connectors, including CGI and FastCGI. Unluckily for us, FastCGI doesn’t quite work with the current Sinatra release.
To get a simple ‘hello world’ Sinatra application up and running on Dreamhost involves pulling down the current Sinatra code, and hacking at it a bit. Don’t worry though, it only requires commenting out a few lines, and tweaking another.
Steps to deploy via FastCGI:
.htaccess RewriteEngine on
AddHandler fastcgi-script .fcgi
Options +FollowSymLinks +ExecCGI
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]dispatch.fcgi #!/usr/bin/ruby
require 'sinatra/lib/sinatra.rb'
require 'rubygems'
fastcgi_log = File.open("fastcgi.log", "a")
STDOUT.reopen fastcgi_log
STDERR.reopen fastcgi_log
STDOUT.sync = true
set :logging, false
set :server, "FastCGI"
module Rack
class Request
def path_info
@env["SCRIPT_URL"].to_s
end
def path_info=(s)
@env["SCRIPT_URL"] = s.to_s
end
end
end
load 'test.rb'sinatra.rb - Replace this function with the new version here (commenting out the puts lines)
def run
begin
#puts "== Sinatra has taken the stage on port #{port} for #{env} with backup by #{server.name}"
require 'pp'
server.run(application) do |server|
trap(:INT) do
server.stop
#puts "\n== Sinatra has ended his set (crowd applauds)"
end
end
rescue Errno::EADDRINUSE => e
#puts "== Someone is already performing on port #{port}!"
end
end// TODO: Talk with Blake about this.
// TODO: What other deployment strategies are there?
First of all, you’ll need the Git version control system. Git is available for all major platforms:
After that, cloning the Sinatra repository is as easy as typing the following into your command line:
git clone git://github.com/bmizerany/sinatra.git