Sinatra

Attention : Ce document correspond à la traduction de la version anglaise et il n'est peut-être plus à jour.

Sinatra est un DSL pour créer rapidement et facilement des applications web en Ruby :

# mon_application.rb
require 'sinatra'

get '/' do
  'Bonjour le monde !'
end

Installez la gem Sinatra :

gem install sinatra

Puis lancez votre programme :

ruby mon_application.rb

Le résultat est visible sur : http://localhost:4567

Le code que vous avez modifié ne sera pas pris en compte tant que vous ne redémarrerez pas le serveur. Pensez à redémarrer le serveur à chaque modification ou utilisez sinatra/reloader.

Il est recommandé d'exécuter également gem install thin, pour que Sinatra utilise le server Thin quand il est disponible.

Table des matières

Routes

Dans Sinatra, une route est une méthode HTTP couplée à un masque (pattern) URL. Chaque route est associée à un bloc :

get '/' do
  .. montrer quelque chose ..
end

post '/' do
  .. créer quelque chose ..
end

put '/' do
  .. remplacer quelque chose ..
end

patch '/' do
  .. changer quelque chose ..
end

delete '/' do
  .. effacer quelque chose ..
end

options '/' do
  .. paramétrer quelque chose ..
end

link '/' do
  .. relier quelque chose ..
end

unlink '/' do
  .. séparer quelque chose ..
end

Les routes sont évaluées dans l'ordre où elles ont été définies. La première route qui correspond à la requête est appelée.

Les routes se terminant par un slash sont différentes de celles qui n'en comportent pas :

get '/foo' do
  # Ne correspond pas à "GET /foo/"
end

Les masques peuvent inclure des paramètres nommés, accessibles par l'intermédiaire du hash params :

get '/bonjour/:nom' do
  # répond aux requêtes "GET /bonjour/foo" et "GET /bonjour/bar"
  # params['nom'] est 'foo' ou 'bar'
  "Bonjour #{params['nom']} !"
end

Vous pouvez aussi accéder aux paramètres nommés directement grâce aux paramètres du bloc comme ceci :

get '/bonjour/:nom' do |n|
  # répond aux requêtes "GET /bonjour/foo" et "GET /bonjour/bar"
  # params['nom'] est 'foo' ou 'bar'
  # n contient params['nom']
  "Bonjour #{n} !"
end

Une route peut contenir un splat (caractère joker), accessible par l'intermédiaire du tableau params['splat'] :

get '/dire/*/a/*' do
  # répond à /dire/bonjour/a/monde
  params['splat'] # => ["bonjour", "monde"]
end

get '/telecharger/*.*' do
  # répond à /telecharger/chemin/vers/fichier.xml
  params['splat'] # => ["chemin/vers/fichier", "xml"]
end

Ou par l'intermédiaire des paramètres du bloc :

get '/telecharger/*.*' do |chemin, ext|
  [chemin, ext] # => ["path/to/file", "xml"]
end

Une route peut aussi être définie par une expression régulière :

get /\/bonjour\/([\w]+)/ do
  "Bonjour, #{params['captures'].first} !"
end

Là encore on peut utiliser les paramètres de bloc :

get %r{/bonjour/([\w]+)} do |c|
  # répond à "GET /meta/bonjour/monde", "GET /bonjour/monde/1234" etc.
  "Bonjour, #{c} !"
end

Les routes peuvent aussi comporter des paramètres optionnels :

get '/articles/:format?' do
  # répond à "GET /articles/" ou avec une extension "GET /articles/json", "GET /articles/xml" etc...
end

Ainsi que des paramètres d'URL :

get '/articles' do
  # répond à "GET /articles?titre=foo&auteur=bar"
  titre = params['titre']
  auteur = params['auteur']
  # utilise les variables titre et auteur qui sont des paramètres d'URL optionnels pour la route /articles
end

À ce propos, à moins d'avoir désactivé la protection contre les attaques par "path transversal" (voir plus loin), l'URL demandée peut avoir été modifiée avant d'être comparée à vos routes.

Vous pouvez personnaliser les options Mustermann utilisées pour une route donnée en fournissant un hash :mustermann_opts :

get '\A/articles\z', :mustermann_opts => { :type => :regexp, :check_anchors => false } do
  # répond exactement à /articles, avec un ancrage explicite
  "Si tu réponds à un pattern ancré tape dans tes mains !
end

Cela ressemble à une condition, mais ce n'en est pas une ! Ces options seront mergées dans le hash global :mustermann_opts décrit plus bas.

Conditions

Les routes peuvent définir toutes sortes de conditions, comme par exemple le "user agent" :

get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
  "Vous utilisez Songbird version #{params['agent'][0]}"
end

get '/foo' do
  # Correspond à tous les autres navigateurs
end

Les autres conditions disponibles sont host_name et provides :

get '/', :host_name => /^admin\./ do
  "Zone Administrateur, Accès refusé !"
end

get '/', :provides => 'html' do
  haml :index
end

get '/', :provides => ['rss', 'atom', 'xml'] do
  builder :feed
end

provides se base sur l'en-tête Accept de la requête.

Vous pouvez facilement définir vos propres conditions :

set(:chance) { |valeur| condition { rand <= valeur } }

get '/gagner_une_voiture', :chance => 0.1 do
  "Vous avez gagné !"
end

get '/gagner_une_voiture' do
  "Désolé, vous avez perdu."
end

Utilisez un splat (caractère joker) dans le cas d'une condition qui prend plusieurs valeurs :

set(:auth) do |*roles|   # <- ici on utilise un splat
  condition do
    unless logged_in? && roles.any? {|role| current_user.in_role? role }
      redirect "/login/", 303
    end
  end
end

get "/mon/compte/", :auth => [:user, :admin] do
  "Informations sur votre compte"
end

get "/reserve/aux/admins/", :auth => :admin do
  "Seuls les administrateurs sont acceptés ici !"
end

Valeurs de retour

La valeur renvoyée par le bloc correspondant à une route constitue le corps de la réponse qui sera transmise au client HTTP ou du moins au prochain middleware dans la pile Rack. Le plus souvent, il s'agit d'une chaîne de caractères, comme dans les exemples précédents. Cependant, d'autres valeurs sont acceptées.

Vous pouvez renvoyer n'importe quel objet qu'il s'agisse d'une réponse Rack valide, d'un corps de réponse Rack ou d'un code statut HTTP :

  • Un tableau de 3 éléments : [code statut (Integer), en-têtes (Hash), corps de la réponse (répondant à #each)]
  • Un tableau de 2 élements : [code statut (Integer), corps de la réponse (répondant à #each)]
  • Un objet qui répond à #each et qui ne transmet que des chaînes de caractères au bloc fourni
  • Un Integer représentant le code statut

Ainsi, on peut facilement implémenter un exemple de streaming :

class Stream
  def each
    100.times { |i| yield "#{i}\n" }
  end
end

get('/') { Stream.new }

Vous pouvez aussi utiliser le helper stream (présenté un peu plus loin) pour éviter les répétitions et intégrer le traitement relatif au streaming dans le bloc de code de la route.

Masques de route spécifiques

Comme cela a été vu auparavant, Sinatra offre la possibilité d'utiliser des masques sous forme de chaines de caractères ou des expressions régulières pour définir les routes. Mais il est possible de faire bien plus. Vous pouvez facilement définir vos propres masques :

class MasqueToutSauf
  Masque = Struct.new(:captures)

  def initialize(except)
    @except   = except
    @captures = Masque.new([])
  end

  def match(str)
    @caputres unless @except === str
  end
end

def tout_sauf(masque)
  MasqueToutSauf.new(masque)
end

get tout_sauf("/index") do
  # ...
end

Notez que l'exemple ci-dessus est plus compliqué qu'il ne devrait et peut être implémenté de la façon suivante :

get // do
  pass if request.path_info == "/index"
  # ...
end

Ou bien en utilisant cette expression regulière :

get %r{(?!/index)} do
  # ...
end

Fichiers statiques

Les fichiers du dossier ./public sont servis de façon statique. Vous pouvez spécifier un autre dossier avec le paramètre :public_folder :

set :public_folder, __dir__ + '/statique'

Notez que le nom du dossier public n'apparait pas dans l'URL. Le fichier ./public/css/style.css sera accessible à l'URL : http://exemple.com/css/style.css.

Utilisez le paramètre :static_cache_control pour ajouter l'information d'en-tête Cache-Control (voir plus bas).

Vues / Templates

Chaque langage de template est disponible via sa propre méthode de rendu, lesquelles renvoient tout simplement une chaîne de caractères.

get '/' do
  erb :index
end

Ceci génère la vue views/index.erb.

Plutôt que d'utiliser le nom d'un template, vous pouvez directement passer le contenu du template :

get '/' do
  code = "<%= Time.now %>"
  erb code
end

Les méthodes de templates acceptent un hash d'options comme second argument :

get '/' do
  erb :index, :layout => :post
end

Ceci génèrera la vue views/index.erb en l'intégrant au layout views/post.erb (views/layout.erb est la valeur par défaut si ce fichier existe).

Toute option que Sinatra ne comprend pas sera passée au moteur de rendu :

get '/' do
  haml :index, :format => :html5
end

Vous pouvez également définir les options de chaque langage de template de façon générale :

set :haml, :format => html5

get '/' do
  haml :index
end

Les arguments passés à la méthode de rendu prennent le pas sur les options définies au moyen de set.

Options disponibles :

locals
Liste de variables locales passées au document. Pratique pour les vues partielles. Exemple : erb "<%= foo %>", :locals => {:foo => "bar"}.
default_encoding
Encodage de caractères à utiliser en cas d'incertitude. Par défaut settings.default_encoding.
views
Dossier de vues dans lequel chercher les templates. Par défaut settings.views.
layout
S'il faut ou non utiliser un layout (true ou false). Ou indique le template à utiliser lorsque c'est un symbole. Exemple : erb :index, :layout => !request.xhr?.
content_type
Content-Type que le template génère. La valeur par défaut dépend du langage de template.
scope
Contexte dans lequel effectuer le rendu du template. Par défaut il s'agit de l'instance de l'application. Si vous changez cela, les variables d'instance et les méthodes utilitaires ne seront pas disponibles.
layout_engine
Moteur de rendu à utiliser pour le layout. Utile pour les langages ne supportant pas les layouts. Il s'agit par défaut du moteur utilisé pour le rendu du template. Exemple : set :rdoc, :layout_engine => :erb
layout_options
Options spécifiques à la génération du layout. Exemple : set :rdoc, :layout_options => { :views => 'views/layouts' }

Les templates sont supposés se trouver directement dans le dossier ./views. Pour utiliser un dossier de vues différent :

set :views, settings.root + '/templates'

Il est important de se souvenir que les templates sont toujours référencés sous forme de symboles, même lorsqu'ils sont dans un sous-répertoire (dans ce cas, utilisez :'sous_repertoire/template'). Il faut utiliser un symbole car les méthodes de rendu évaluent le contenu des chaînes de caractères au lieu de les considérer comme un chemin vers un fichier.

Templates littéraux

get '/' do
  haml '%div.title Bonjour le monde'
end

Utilisera la chaine de caractères comme template pour générer la réponse. Vous pouvez spécifier un :path et :line optionnels pour une trace plus claire s'il existe un chemin dans le système de fichiers ou une ligne associés à cette chaîne de caractères :

get '/' do
  haml '%div.title Bonjour le monde', :path => 'exemples/fichier.haml', :line => 3
end

Langages de template disponibles

Certains langages ont plusieurs implémentations. Pour préciser l'implémentation à utiliser (et garantir l'aspect thread-safe), vous devez simplement l'avoir chargée au préalable :

require 'rdiscount' # ou require 'bluecloth'
get('/') { markdown :index }

Templates Haml

Dépendances haml
Extensions de fichier .haml
Exemple haml :index, :format => :html5

Templates Erb

Dépendances erubis ou erb (inclus avec Ruby)
Extensions de fichier .erb, .rhtml ou .erubis (Erubis seulement)
Exemple erb :index

Templates Builder

Dépendances builder
Extensions de fichier .builder
Exemple builder { |xml| xml.em "salut" }

Ce moteur accepte également un bloc pour des templates en ligne (voir exemple).

Templates Nokogiri

Dépendances nokogiri
Extensions de fichier .nokogiri
Exemple nokogiri { |xml| xml.em "salut" }

Ce moteur accepte également un bloc pour des templates en ligne (voir exemple).

Templates Sass

Dépendances sass
Extensions de fichier .sass
Exemple sass :stylesheet, :style => :expanded

Templates SCSS

Dépendances sass
Extensions de fichier .scss
Exemple scss :stylesheet, :style => :expanded

Templates Less

Dépendances less
Extensions de fichier .less
Exemple less :stylesheet

Templates Liquid

Dépendances liquid
Extensions de fichier .liquid
Exemple liquid :index, :locals => { :key => 'value' }

Comme vous ne pouvez appeler de méthodes Ruby (autres que yield) dans un template Liquid, vous aurez sûrement à lui passer des variables locales.

Templates Markdown

Dépendances

 Au choix : RDiscount, RedCarpet, BlueCloth, kramdown, maruku
Extensions de fichier .markdown, .mkd et .md
Exemple markdown :index, :layout_engine => :erb

Il n’est pas possible d’appeler des méthodes depuis markdown, ni de lui passer de variables locales. Par conséquent, il sera souvent utilisé en combinaison avec un autre moteur de rendu :

erb :accueil, :locals => { :text => markdown(:introduction) }

Notez que vous pouvez également appeler la méthode markdown depuis un autre template :

%h1 Bonjour depuis Haml !
%p= markdown(:bienvenue)

Comme vous ne pouvez pas appeler de méthode Ruby depuis Markdown, vous ne pouvez pas utiliser de layouts écrits en Markdown. Toutefois, il est possible d’utiliser un moteur de rendu différent pour le template et pour le layout en utilisant l’option :layout_engine.

Templates Textile

Dépendances RedCloth
Extensions de fichier .textile
Exemple textile :index, :layout_engine => :erb

Il n’est pas possible d’appeler de méthodes depuis textile, ni de lui passer de variables locales. Par conséquent, il sera souvent utilisé en combinaison avec un autre moteur de rendu :

erb :accueil, :locals => { :text => textile(:introduction) }

Notez que vous pouvez également appeler la méthode textile depuis un autre template :

%h1 Bonjour depuis Haml !
%p= textile(:bienvenue)

Comme vous ne pouvez pas appeler de méthode Ruby depuis Textile, vous ne pouvez pas utiliser de layouts écrits en Textile. Toutefois, il est possible d’utiliser un moteur de rendu différent pour le template et pour le layout en utilisant l’option :layout_engine.

Templates RDoc

Dépendances RDoc
Extensions de fichier .rdoc
Exemple rdoc :README, :layout_engine => :erb

Il n’est pas possible d’appeler de méthodes Ruby depuis rdoc, ni de lui passer de variables locales. Par conséquent, il sera souvent utilisé en combinaison avec un autre moteur de rendu :

erb :accueil, :locals => { :text => rdoc(:introduction) }

Notez que vous pouvez également appeler la méthode rdoc depuis un autre template :

%h1 Bonjour depuis Haml !
%p= rdoc(:bienvenue)

Comme vous ne pouvez pas appeler de méthodes Ruby depuis RDoc, vous ne pouvez pas utiliser de layouts écrits en RDoc. Toutefois, il est possible d’utiliser un moteur de rendu différent pour le template et pour le layout en utilisant l’option :layout_engine.

Templates Asciidoc

Dépendances Asciidoctor
Extensions de fichier .asciidoc, .adoc and .ad
Exemple asciidoc :README, :layout_engine => :erb

Comme vous ne pouvez pas appeler de méthodes Ruby depuis un template AsciiDoc, vous aurez sûrement à lui passer des variables locales.

Templates Radius

Dépendances Radius
Extensions de fichier .radius
Exemple radius :index, :locals => { :key => 'value' }

Comme vous ne pouvez pas appeler de méthodes Ruby depuis un template Radius, vous aurez sûrement à lui passer des variables locales.

Templates Markaby

Dépendances Markaby
Extensions de fichier .mab
Exemple markaby { h1 "Bienvenue !" }

Ce moteur accepte également un bloc pour des templates en ligne (voir exemple).

Templates RABL

Dépendances Rabl
Extensions de fichier .rabl
Exemple rabl :index

Templates Slim

Dépendances Slim Lang
Extensions de fichier .slim
Exemple slim :index

Templates Creole

Dépendances Creole
Extensions de fichier .creole
Exemple creole :wiki, :layout_engine => :erb

Il n'est pas possible d'appeler de méthodes Ruby depuis creole, ni de lui passer de variables locales. Par conséquent, il sera souvent utilisé en combinaison avec un autre moteur de rendu :

erb :accueil, :locals => { :text => markdown(:introduction) }

Notez que vous pouvez également appeler la méthode creole depuis un autre template :

%h1 Bonjour depuis Haml !
%p= creole(:bienvenue)

Comme vous ne pouvez pas appeler de méthodes Ruby depuis Creole, vous ne pouvez pas utiliser de layouts écrits en Creole. Toutefois, il est possible d'utiliser un moteur de rendu différent pour le template et pour le layout en utilisant l'option :layout_engine.

Templates MediaWiki

Dépendances WikiCloth
Extensions de fichier .mediawiki and .mw
Exemple mediawiki :wiki, :layout_engine => :erb

Il n’est pas possible d’appeler de méthodes Ruby depuis Mediawiki, ni de lui passer de variables locales. Par conséquent, il sera souvent utilisé en combinaison avec un autre moteur de rendu :

erb :overview, :locals => { :text => mediawiki(:introduction) }

Notez que vous pouvez également appeler la méthode mediawiki depuis un autre template :

%h1 Bonjour depuis Haml !
%p= mediawiki(:bienvenue)

Comme vous ne pouvez pas appeler de méthodes Ruby depuis MediaWiki, vous ne pouvez pas utiliser de layouts écrits en MediaWiki. Toutefois, il est possible d’utiliser un moteur de rendu différent pour le template et pour le layout en utilisant l’option :layout_engine.

Templates CoffeeScript

Dépendances CoffeeScript et un moyen d'exécuter javascript
Extensions de fichier .coffee
Exemple coffee :index

Templates Stylus

Dépendances Stylus et un moyen d'exécuter javascript
Extensions de fichier .styl
Exemple stylus :index

Avant de pouvoir utiliser des templates Stylus, vous devez auparavant charger stylus et stylus/tilt :

require 'sinatra'
require 'stylus'
require 'stylus/tilt'

get '/' do
  stylus :exemple
end

Templates Yajl

Dépendances yajl-ruby
Extensions de fichier .yajl
Exemple yajl :index, :locals => { :key => 'qux' }, :callback => 'present', :variable => 'ressource'

La source du template est évaluée en tant que chaine Ruby, puis la variable json obtenue est convertie avec #to_json.

json = { :foo => 'bar' }
json[:baz] = key

Les options :callback et :variable peuvent être utilisées pour décorer l’objet retourné.

var ressource = {"foo":"bar","baz":"qux"}; present(ressource);</pre>

Templates WLang

Dépendances wlang
Extensions de fichier .wlang
Exemple wlang :index, :locals => { :key => 'value' }

L’appel de code ruby au sein des templates n’est pas idiomatique en wlang. L’écriture de templates sans logique est encouragée, via le passage de variables locales. Il est néanmoins possible d’écrire un layout en wlang et d’y utiliser yield.

Accéder aux variables dans un Template

Un template est évalué dans le même contexte que l'endroit d'où il a été appelé (gestionnaire de route). Les variables d'instance déclarées dans le gestionnaire de route sont directement accessibles dans le template :

get '/:id' do
  @foo = Foo.find(params['id'])
  haml '%h1= @foo.nom'
end

Alternativement, on peut passer un hash contenant des variables locales :

get '/:id' do
  foo = Foo.find(params['id'])
  haml '%h1= foo.nom', :locals => { :foo => foo }
end

Ceci est généralement nécessaire lorsque l'on veut utiliser un template depuis un autre template (partiel) et qu'il faut donc adapter le nom des variables.

Templates avec yield et layouts imbriqués

En général, un layout est un simple template qui appelle yield. Ce genre de template peut s'utiliser via l'option :template comme décrit précédemment ou peut être rendu depuis un bloc :

erb :post, :layout => false do
  erb :index
end

Ce code est plus ou moins équivalent à erb :index, :layout => :post.

Le fait de passer des blocs aux méthodes de rendu est particulièrement utile pour gérer des templates imbriqués :

erb :layout_principal, :layout => false do
  erb :layout_admin do
    erb :utilisateur
  end
end

Ou plus brièvement :

erb :layout_admin, :layout => :layout_principal do
  erb :utilisateur
end

Actuellement, les méthodes de rendu qui acceptent un bloc sont : erb, haml, liquid, slim et wlang. La méthode générale render accepte elle aussi un bloc.

Templates dans le fichier source

Des templates peuvent être définis dans le fichier source comme ceci :

require 'sinatra'

get '/' do
  haml :index
end

__END__

NOTE : Les templates du fichier source qui contient require 'sinatra' sont automatiquement chargés. Si vous avez des templates dans d'autres fichiers source, il faut explicitement les déclarer avec enable :inline_templates.

Templates nommés

Les templates peuvent aussi être définis grâce à la méthode de haut niveau template :

template :layout do
  "%html\n  =yield\n"
end

template :index do
  '%div.title Bonjour le monde !'
end

get '/' do
  haml :index
end

Si un template nommé "layout" existe, il sera utilisé à chaque fois qu'un template sera affiché. Vous pouvez désactivez les layouts au cas par cas en passant :layout => false ou bien les désactiver par défaut au moyen de set :haml, :layout => false :

get '/' do
  haml :index, :layout => !request.xhr?
end

Associer des extensions de fichier

Pour associer une extension de fichier avec un moteur de rendu, utilisez Tilt.register. Par exemple, si vous désirez utiliser l'extension de fichier tt pour les templates Textile, vous pouvez faire comme suit :

Tilt.register :tt, Tilt[:textile]

Ajouter son propre moteur de rendu

En premier lieu, déclarez votre moteur de rendu avec Tilt, ensuite créez votre méthode de rendu :

Tilt.register :monmoteur, MonMerveilleuxMoteurDeRendu

helpers do
  def monmoteur(*args) render(:monmoteur, *args) end
end

get '/' do
  monmoteur :index
end

Utilisera ./views/index.monmoteur. Voir le projet Github pour en savoir plus sur Tilt.

Utiliser des règles personnalisées pour la recherche de templates

Pour implémenter votre propre mécanisme de recherche de templates, vous pouvez écrire votre propre méthode #find_template :

configure do
  set :views, [ './vues/a', './vues/b' ]
end

def find_template(vues, nom, moteur, &bloc)
  Array(vues).each do |v|
    super(v, nom, moteur, &bloc)
  end
end

Filtres

Les filtres before sont exécutés avant chaque requête, dans le même contexte que les routes, et permettent de modifier la requête et sa réponse. Les variables d'instance déclarées dans les filtres sont accessibles au niveau des routes et des templates :

before do
  @note = 'Coucou !'
  request.path_info = '/foo/bar/baz'
end

get '/foo/*' do
  @note #=> 'Coucou !'
  params['splat'] #=> 'bar/baz'
end

Les filtres after sont exécutés après chaque requête à l'intérieur du même contexte et permettent de modifier la requête et sa réponse. Les variables d'instance déclarées dans les filtres before ou les routes sont accessibles au niveau des filtres after :

after do
  puts response.status
end

Note : Le corps de la réponse n'est pas disponible au niveau du filtre after car il ne sera généré que plus tard (sauf dans le cas où vous utilisez la méthode body au lieu de simplement renvoyer une chaine depuis vos routes).

Les filtres peuvent être associés à un masque, ce qui permet de limiter leur exécution aux cas où la requête correspond à ce masque :

before '/secret/*' do
  authentification!
end

after '/faire/:travail' do |travail|
  session['dernier_travail'] = travail
end

Tout comme les routes, les filtres acceptent également des conditions :

before :agent => /Songbird/ do
  # ...
end

after '/blog/*', :host_name => 'example.com' do
  # ...
end

Helpers

Utilisez la méthode de haut niveau helpers pour définir des méthodes qui seront accessibles dans vos gestionnaires de route et dans vos templates :

helpers do
  def bar(nom)
    "#{nom}bar"
  end
end

get '/:nom' do
  bar(params['nom'])
end

Vous pouvez aussi définir les méthodes helper dans un module séparé :

module FooUtils
  def foo(nom) "#{nom}foo" end
end

module BarUtils
  def bar(nom) "#{nom}bar" end
end

helpers FooUtils, BarUtils

Cela a le même résultat que d'inclure les modules dans la classe de l'application.

Utiliser les sessions

Les sessions sont utilisées pour conserver un état entre les requêtes. Une fois activées, vous avez un hash de session par session utilisateur :

enable :sessions

get '/' do
  "valeur = " << session['valeur'].inspect
end

get '/:valeur' do
  session['valeur'] = params['valeur']
end

Notez que enable :sessions enregistre en fait toutes les données dans un cookie. Ce n'est pas toujours ce que vous voulez (enregistrer beaucoup de données va augmenter le traffic par exemple). Vous pouvez utiliser n'importe quel middleware Rack de session afin d'éviter cela. N'utilisez pas enable :sessions dans ce cas mais chargez le middleware de votre choix comme vous le feriez pour n'importe quel autre middleware :

use Rack::Session::Pool, :expire_after => 2592000

get '/' do
  "valeur = " << session['valeur'].inspect
end

get '/:valeur' do
  session['valeur'] = params['valeur']
end

Pour renforcer la sécurité, les données de session dans le cookie sont signées avec une clé secrète de session. Une clé secrète est générée pour vous au hasard par Sinatra. Toutefois, comme cette clé change à chaque démarrage de votre application, vous pouvez définir cette clé vous-même afin que toutes les instances de votre application la partage :

set :session_secret, 'super secret'

Si vous souhaitez avoir plus de contrôle, vous pouvez également enregistrer un hash avec des options lors de la configuration de sessions :

set :sessions, :domain => 'foo.com'

Pour que les différents sous-domaines de foo.com puissent partager une session, vous devez précéder le domaine d'un . (point) :

set :sessions, :domain => '.foo.com'

Halt

Pour arrêter immédiatement la requête dans un filtre ou un gestionnaire de route :

halt

Vous pouvez aussi passer le code retour ...

halt 410

Ou le texte ...

halt 'Ceci est le texte'

Ou les deux ...

halt 401, 'Partez !'

Ainsi que les en-têtes ...

halt 402, {'Content-Type' => 'text/plain'}, 'revanche'

Bien sûr il est possible de combiner un template avec halt :

halt erb(:erreur)

Passer

Une route peut passer le relais aux autres routes qui correspondent également avec pass :

get '/devine/:qui' do
  pass unless params['qui'] == 'Frank'
  "Tu m'as eu !"
end

get '/devine/*' do
  'Manqué !'
end

On sort donc immédiatement de ce gestionnaire et on continue à chercher, dans les masques suivants, le prochain qui correspond à la requête. Si aucun des masques suivants ne correspond, un code 404 est retourné.

Déclencher une autre route

Parfois, pass n'est pas ce que vous recherchez, au lieu de cela vous souhaitez obtenir le résultat d'une autre route. Pour cela, utilisez simplement call :

get '/foo' do
  status, headers, body = call env.merge("PATH_INFO" => '/bar')
  [status, headers, body.map(&:upcase)]
end

get '/bar' do
  "bar"
end

Notez que dans l'exemple ci-dessus, vous faciliterez les tests et améliorerez la performance en déplaçant simplement "bar" dans un helper utilisé à la fois par /foo et /bar.

Si vous souhaitez que la requête soit envoyée à la même instance de l'application plutôt qu'à une copie, utilisez call! au lieu de call.

Lisez la spécification Rack si vous souhaitez en savoir plus sur call.

Définir le corps, le code retour et les en-têtes

Il est possible et recommandé de définir le code retour et le corps de la réponse au moyen de la valeur de retour d'un bloc définissant une route. Quoiqu'il en soit, dans certains cas vous pourriez avoir besoin de définir le coprs de la réponse à un moment arbitraire de l'exécution. Vous pouvez le faire au moyen de la méthode body. Si vous faites ainsi, vous pouvez alors utiliser cette même méthode pour accéder au corps de la réponse :

get '/foo' do
  body "bar"
end

after do
  puts body
end

Il est également possible de passer un bloc à body, qui sera exécuté par le gestionnaire Rack (ceci peut être utilisé pour implémenter un streaming, voir "Valeurs de retour").

Pareillement au corps de la réponse, vous pouvez également définir le code retour et les en-têtes :

get '/foo' do
  status 418
  headers \
    "Allow"   => "BREW, POST, GET, PROPFIND, WHEN",
    "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
  body "Je suis une théière !"
end

Comme pour body, headers et status peuvent être utilisés sans arguments pour accéder à leurs valeurs.

Faire du streaming

Il y a des cas où vous voulez commencer à renvoyer des données pendant que vous êtes en train de générer le reste de la réponse. Dans les cas les plus extrèmes, vous souhaitez continuer à envoyer des données tant que le client n'abandonne pas la connexion. Vous pouvez alors utiliser le helper stream pour éviter de créer votre propre système :

get '/' do
  stream do |out|
    out << "Ca va être hallu -\n"
    sleep 0.5
    out << " (attends la suite) \n"
    sleep 1
    out << "- cinant !\n"
  end
end

Cela permet d'implémenter des API de streaming ou de Server Sent Events et peut servir de base pour des WebSockets. Vous pouvez aussi l'employer pour augmenter le débit quand une partie du contenu provient d'une ressource lente.

Le fonctionnement du streaming, notamment le nombre de requêtes simultanées, dépend énormément du serveur web utilisé. Certains ne prennent pas du tout en charge le streaming. Lorsque le serveur ne gère pas le streaming, la partie body de la réponse sera envoyée au client en une seule fois, après l'exécution du bloc passé au helper stream. Le streaming ne fonctionne pas du tout avec Shotgun.

En utilisant le helper stream avec le paramètre keep_open, il n'appelera pas la méthode close du flux, vous laissant la possibilité de le fermer à tout moment au cours de l'exécution. Ceci ne fonctionne qu'avec les serveurs evented (ie non threadés) tels que Thin et Rainbows. Les autres serveurs fermeront malgré tout le flux :

# interrogation prolongée

set :server, :thin
connexions = []

get '/souscrire' do
  # abonne un client aux évènements du serveur
  stream(:keep_open) do |out|
    connexions << out
    # purge les connexions abandonnées
    connexions.reject!(&:closed?)
  end
end

post '/message' do
  connexions.each do |out|
    # prévient le client qu'un nouveau message est arrivé
    out << params['message'] << "\n"

    # indique au client de se connecter à nouveau
    out.close
  end

  # compte-rendu
  "message reçu"
end

Il est aussi possible pour le client de fermer la connexion en essayant d'écrire sur le socket. Pour cette raison, il est recommandé de vérifier out.closed? avant d'essayer d'y écrire.

Journalisation (Logging)

Dans le contexte de la requête, la méthode utilitaire logger expose une instance de Logger :

get '/' do
  logger.info "chargement des données"
  # ...
end

Ce logger va automatiquement prendre en compte les paramètres de configuration pour la journalisation de votre gestionnaire Rack. Si la journalisation est désactivée, cette méthode renverra un objet factice et vous n'avez pas à vous en inquiéter dans vos routes en le filtrant.

Notez que la journalisation est seulement activée par défaut pour Sinatra::Application, donc si vous héritez de >Sinatra::Base, vous aurez à l'activer vous-même :

class MonApp < Sinatra::Base
  configure :production, :development do
    enable :logging
  end
end

Si vous souhaitez utiliser votre propre logger, vous devez définir le paramètre logging à nil pour être certain qu'aucun middleware de logging ne sera installé (notez toutefois que logger renverra alors nil). Dans ce cas, Sinatra utilisera ce qui sera présent dans env['rack.logger'].

Types Mime

Quand vous utilisez send_file ou des fichiers statiques, vous pouvez rencontrer des types mime que Sinatra ne connaît pas. Utilisez mime_type pour les déclarer par extension de fichier :

configure do
  mime_type :foo, 'text/foo'
end

Vous pouvez également les utiliser avec la méthode content_type :

get '/' do
  content_type :foo
  "foo foo foo"
end

Former des URLs

Pour former des URLs, vous devriez utiliser la méthode url, par exemple en Haml :

%a{:href => url('/foo')} foo

Cela prend en compte les proxy inverse et les routeurs Rack, s'ils existent.

Cette méthode est également disponible sous l'alias to (voir ci-dessous pour un exemple).

Redirection du navigateur

Vous pouvez déclencher une redirection du navigateur avec la méthode redirect :

get '/foo' do
  redirect to('/bar')
end

Tout paramètre additionnel sera utilisé comme argument pour la méthode halt :

redirect to('/bar'), 303
redirect 'http://www.google.com/', 'mauvais endroit mon pote'

Vous pouvez aussi rediriger vers la page dont l'utilisateur venait au moyen de redirect back :

get '/foo' do
  "<a href='/bar'>faire quelque chose</a>"
end

get '/bar' do
  faire_quelque_chose
  redirect back
end

Pour passer des arguments à une redirection, ajoutez-les soit à la requête :

redirect to('/bar?sum=42')

Ou bien utilisez une session :

enable :sessions

get '/foo' do
  session['secret'] = 'foo'
  redirect to('/bar')
end

get '/bar' do
  session['secret']
end

Contrôle du cache

Définissez correctement vos en-têtes à la base pour un bon cache HTTP.

Vous pouvez facilement définir l'en-tête Cache-Control de la manière suivante :

get '/' do
  cache_control :public
  "met le en cache !"
end

Conseil de pro : définir le cache dans un filtre before :

before do
  cache_control :public, :must_revalidate, :max_age => 60
end

Si vous utilisez la méthode expires pour définir l'en-tête correspondant, Cache-Control sera alors défini automatiquement :

before do
  expires 500, :public, :must_revalidate
end

Pour utiliser correctement le cache, vous devriez utiliser etag ou last_modified. Il est recommandé d'utiliser ces méthodes avant de faire d'importantes modifications, car elles vont immédiatement déclencher la réponse si le client a déjà la version courante dans son cache :

get '/article/:id' do
  @article = Article.find params['id']
  last_modified @article.updated_at
  etag @article.sha1
  erb :article
end

Il est également possible d'utiliser un weak ETag :

etag @article.sha1, :weak

Ces méthodes ne sont pas chargées de mettre des données en cache, mais elles fournissent les informations nécessaires pour le cache de votre navigateur. Si vous êtes à la recherche d'une solution rapide pour un reverse-proxy de cache, essayez rack-cache :

require "rack/cache"
require "sinatra"

use Rack::Cache

get '/' do
  cache_control :public, :max_age => 36000
  sleep 5
  "hello"
end

Utilisez le paramètre :static_cache_control pour ajouter l'information d'en-tête Cache-Control (voir plus loin).

D'après la RFC 2616, votre application devrait se comporter différement lorsque l'en-tête If-Match ou If-None-Match est défini à * en tenant compte du fait que la ressource demandée existe déjà ou pas. Sinatra considère que les requêtes portant sur des ressources sûres (tel que get) ou idempotentes (tel que put) existent déjà et pour les autres ressources (par exemple dans le cas de requêtes post) qu'il s'agit de nouvelles ressources. Vous pouvez modifier ce comportement en passant une option :new_resource :

get '/create' do
  etag '', :new_resource => true
  Article.create
  erb :nouvel_article
end

Si vous souhaitez avoir un ETag faible, utilisez l'option :kind :

etag '', :new_resource => true, :kind => :weak

Envoyer des fichiers

Pour envoyer des fichiers, vous pouvez utiliser la méthode send_file :

get '/' do
  send_file 'foo.png'
end

Quelques options sont également acceptées :

send_file 'foo.png', :type => :jpg

Les options sont :

filename
le nom du fichier dans la réponse, par défaut le nom du fichier envoyé.
type
type de contenu à utiliser, deviné à partir de l’extension de fichier si absent
disposition
utilisé pour Content-Disposition, les valeurs possibles étant : nil (par défaut), :attachment et :inline
length
en-tête Content-Length, par défaut la taille du fichier
status
code état à renvoyer. Utile quand un fichier statique sert de page d’erreur. Si le gestionnaire Rack le supporte, d'autres moyens que le streaming via le processus Ruby seront utilisés. Si vous utilisez cette méthode, Sinatra gérera automatiquement les requêtes de type range.

Accéder à l'objet requête

L'objet correspondant à la requête envoyée peut être récupéré dans le contexte de la requête (filtres, routes, gestionnaires d'erreur) au moyen de la méthode request :

# application tournant à l'adresse http://exemple.com/exemple
get '/foo' do
  t = %w[text/css text/html application/javascript]
  request.accept              # ['text/html', '*/*']
  request.accept? 'text/xml'  # vrai
  request.preferred_type(t)   # 'text/html'
  request.body                # corps de la requête envoyée par le client
                              # (voir ci-dessous)
  request.scheme              # "http"
  request.script_name         # "/exemple"
  request.path_info           # "/foo"
  request.port                # 80
  request.request_method      # "GET"
  request.query_string        # ""
  request.content_length      # taille de request.body
  request.media_type          # type de média pour request.body
  request.host                # "exemple.com"
  request.get?                # vrai (méthodes similaires pour les autres
                              # verbes HTTP)
  request.form_data?          # faux
  request["UN_ENTETE"]        # valeur de l'en-tête UN_ENTETE
  request.referrer            # référant du client ou '/'
  request.user_agent          # user agent (utilisé par la condition :agent)
  request.cookies             # tableau contenant les cookies du navigateur
  request.xhr?                # requête AJAX ?
  request.url                 # "http://exemple.com/exemple/foo"
  request.path                # "/exemple/foo"
  request.ip                  # adresse IP du client
  request.secure?             # faux
  request.forwarded?          # vrai (si on est derrière un proxy inverse)
  request.env                 # tableau brut de l'environnement fourni par Rack
end

Certaines options, telles que script_name ou path_info peuvent également être modifiées :

before { request.path_info = "/" }

get "/" do
  "toutes les requêtes arrivent ici"
end

request.body est un objet IO ou StringIO :

post "/api" do
  request.body.rewind  # au cas où il a déjà été lu
  donnees = JSON.parse request.body.read
  "Bonjour #{donnees['nom']} !"
end

Fichiers joints

Vous pouvez utiliser la méthode attachment pour indiquer au navigateur que la réponse devrait être stockée sur le disque plutôt qu'affichée :

get '/' do
  attachment
  "enregistre-le !"
end

Vous pouvez également lui passer un nom de fichier :

get '/' do
  attachment "info.txt"
  "enregistre-le !"
end

Gérer Date et Time

Sinatra fourni un helper time_for pour convertir une valeur donnée en objet Time. Il peut aussi faire la conversion à partir d'objets DateTime, Date ou de classes similaires :

get '/' do
  pass if Time.now > time_for('Dec 23, 2012')
  "encore temps"
end

Cette méthode est utilisée en interne par expires, last_modified et consorts. Par conséquent, vous pouvez très facilement étendre le fonctionnement de ces méthodes en surchargeant le helper time_for dans votre application :

helpers do
  def time_for(value)
    case value
    when :yesterday then Time.now - 24*60*60
    when :tomorrow  then Time.now + 24*60*60
    else super
    end
  end
end

get '/' do
  last_modified :yesterday
  expires :tomorrow
  "salut"
end

Chercher les fichiers de templates

La méthode find_template est utilisée pour trouver les fichiers de templates à générer :

find_template settings.views, 'foo', Tilt[:haml] do |file|
  puts "pourrait être #{file}"
end

Ce n'est pas très utile. En revanche, il est utile de pouvoir surcharger cette méthode afin de définir son propre mécanisme de recherche. Par exemple, vous pouvez utiliser plus d'un répertoire de vues :

set :views, ['views', 'templates']

helpers do
  def find_template(vues, nom, moteur, &bloc)
    Array(vues).each { |v| super(v, nom, moteur, &bloc) }
  end
end

Un autre exemple est d'utiliser des répertoires différents pour des moteurs de rendu différents :

set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'

helpers do
  def find_template(vues, nom, moteur, &bloc)
    _, dossier = vues.detect { |k,v| moteur == Tilt[k] }
    dossier ||= vues[:default]
    super(dossier, nom, moteur, &bloc)
  end
end

Vous pouvez également écrire cela dans une extension et la partager avec d'autres !

Notez que find_template ne vérifie pas que le fichier existe mais va plutôt exécuter le bloc pour tous les chemins possibles. Cela n'induit pas de problème de performance dans le sens où render va utiliser break dès qu'un fichier sera trouvé. De plus, l'emplacement des templates (et leur contenu) est mis en cache si vous n'êtes pas en mode développement. Vous devez garder cela en tête si vous écrivez une méthode vraiment dingue.

Configuration

Lancé une seule fois au démarrage de tous les environnements :

configure do
  # définir un paramètre
  set :option, 'valeur'

  # définir plusieurs paramètres
  set :a => 1, :b => 2

  # équivalent à "set :option, true"
  enable :option

  # équivalent à "set :option, false""
  disable :option

  # vous pouvez également avoir des paramètres dynamiques avec des blocs
  set(:css_dir) { File.join(views, 'css') }
end

Lancé si l'environnement (variable d'environnement APP_ENV) est :production :

  configure :production do
    ...
  end

Lancé si l'environnement est :production ou :test :

  configure :production, :test do
    ...
  end

Vous pouvez accéder à ces paramètres via settings :

configure do
  set :foo, 'bar'
end

get '/' do
  settings.foo? # => true
  settings.foo  # => 'bar'
  ...
end

Se protéger des attaques

Sinatra utilise Rack::Protection pour protéger votre application contre les principales attaques opportunistes. Vous pouvez très simplement désactiver cette fonctionnalité (ce qui exposera votre application à beaucoup de vulnerabilités courantes) :

disable :protection

Pour désactiver seulement un type de protection, vous pouvez définir protection avec un hash d'options :

set :protection, :except => :path_traversal

Vous pouvez également lui passer un tableau pour désactiver plusieurs types de protection :

set :protection, :except => [:path_traversal, :session_hijacking]

Par défaut, il faut que :sessions soit activé pour que Sinatra mette en place un système de protection au niveau de la session. Dans le cas où vous gérez vous même les sessions, vous devez utiliser l'option :session pour que cela soit le cas :

use Rack::Session::Pool
set :protection, :session => true

Paramètres disponibles

absolute_redirects
Si désactivé, Sinatra permettra les redirections relatives. Toutefois, Sinatra ne sera plus conforme à la RFC 2616 (HTTP 1.1), qui n’autorise que les redirections absolues.

Activez si votre application tourne derrière un proxy inverse qui n’a pas été correctement configuré. Notez que la méthode url continuera de produire des URLs absolues, sauf si vous lui passez false comme second argument.

Désactivé par défaut.

add_charset

types mime pour lesquels la méthode content_type va automatiquement ajouter l’information du charset.

Vous devriez lui ajouter des valeurs plutôt que de l’écraser :

settings.add_charset >> "application/foobar"
app_file

chemin pour le fichier de l’application principale, utilisé pour détecter la racine du projet, les dossiers public et vues, et les templates en ligne.

bind
adresse IP sur laquelle se brancher (par défaut : 0.0.0.0). Utiliser seulement pour le serveur intégré.
default_encoding
encodage à utiliser si inconnu (par défaut "utf-8")
dump_errors
afficher les erreurs dans le log.
environment
environnement courant, par défaut ENV['APP_ENV'], ou "development" si absent.
logging
utiliser le logger.
lock

Place un lock autour de chaque requête, n’exécutant donc qu’une seule requête par processus Ruby.

Activé si votre application n’est pas thread-safe. Désactivé par défaut.

method_override
utilise la magie de _method afin de permettre des formulaires put/delete dans des navigateurs qui ne le permettent pas.
port
port à écouter. Utiliser seulement pour le serveur intégré.
mustermann_opts
Un hash d'options à passer à Mustermann.new lors de la compilation des chemins de routes
prefixed_redirects
si oui ou non request.script_name doit être inséré dans les redirections si un chemin non absolu est utilisé. Ainsi, redirect '/foo' se comportera comme redirect to('/foo'). Désactivé par défaut.
protection
défini s’il faut activer ou non la protection contre les attaques web. Voir la section protection précédente.
public_dir
alias pour public_folder. Voir ci-dessous.
public_folder
chemin pour le dossier à partir duquel les fichiers publics sont servis. Utilisé seulement si les fichiers statiques doivent être servis (voir le paramètre static). Si non défini, il découle du paramètre app_file.
quiet
Désactive les journaux (logs) générés par les commandes start et stop de Sinatra. false par défaut.
reload_templates
si oui ou non les templates doivent être rechargés entre les requêtes. Activé en mode développement.
root
chemin pour le dossier racine du projet. Si non défini, il découle du paramètre app_file.
raise_errors
soulever les erreurs (ce qui arrêtera l’application). Désactivé par défaut sauf lorsque environment est défini à "test".
run
si activé, Sinatra s’occupera de démarrer le serveur, ne pas activer si vous utiliser rackup ou autres.
running
est-ce que le serveur intégré est en marche ? ne changez pas ce paramètre !
server
serveur ou liste de serveurs à utiliser pour le serveur intégré. Par défaut [‘thin’, ‘mongrel’, ‘webrick’], l’ordre indiquant la priorité.
server_settings
Si vous utilisez un serveur Webrick, sans doute pour votre environnement de développement, vous pouvez passer des options à server_settings, comme SSLEnable ou SSLVerifyClient. Cependant, les serveurs comme Puma et Thin ne le permettent pas, et vous pouvez donc définir server_settings en tant que méthode lorsque vous appelez configure.
sessions
active le support des sessions basées sur les cookies, en utilisant Rack::Session::Cookie. Reportez-vous à la section ‘Utiliser les sessions’ pour plus d’informations.
session_store
Le middleware Rack utilisé pour les sessions. Rack::Session::Cookie par défaut. Voir la section 'Utiliser les sessions' pour plus de détails.
show_exceptions
affiche la trace de l’erreur dans le navigateur lorsqu’une exception se produit. Désactivé par défaut sauf lorsque environment est défini à "development".
static
Si oui ou non Sinatra doit s’occuper de servir les fichiers statiques. Désactivez si vous utilisez un serveur capable de le gérer lui même. Le désactiver augmentera la performance. Activé par défaut pour le style classique, désactivé pour le style modulaire.
static_cache_control
A définir quand Sinatra rend des fichiers statiques pour ajouter les en-têtes Cache-Control. Utilise le helper cache_control. Désactivé par défaut. Utiliser un array explicite pour définir des plusieurs valeurs : set :static_cache_control, [:public, :max_age => 300]
threaded
à définir à true pour indiquer à Thin d’utiliser EventMachine.defer pour traiter la requête.
traps
Indique si Sinatra doit gérer les signaux système.
views
chemin pour le dossier des vues. Si non défini, il découle du paramètre app_file.
x_cascade
Indique s'il faut ou non définir le header X-Cascade lorsqu'aucune route ne correspond. Défini à true par défaut.

Environnements

Il existe trois environnements prédéfinis : "development", "production" et "test". Les environnements peuvent être sélectionné via la variable d'environnement APP_ENV. Sa valeur par défaut est "development". Dans ce mode, tous les templates sont rechargés à chaque requête. Des handlers spécifiques pour not_found et error sont installés pour vous permettre d'avoir une pile de trace dans votre navigateur. En mode "production" et "test" les templates sont mis en cache par défaut.

Pour exécuter votre application dans un environnement différent, définissez la variable d'environnement APP_ENV :

APP_ENV=production ruby my_app.rb

Vous pouvez utiliser une des méthodes development?, test? et production? pour déterminer quel est l'environnement en cours :

get '/' do
  if settings.development?
    "développement !"
  else
    "pas en développement !"
  end
end

Gérer les erreurs

Les gestionnaires d'erreur s'exécutent dans le même contexte que les routes ou les filtres, ce qui veut dire que vous avez accès (entre autres) aux bons vieux haml, erb, halt, etc.

NotFound

Quand une exception Sinatra::NotFound est soulevée, ou que le code retour est 404, le gestionnaire not_found est invoqué :

not_found do
  'Pas moyen de trouver ce que vous cherchez'
end

Error

Le gestionnaire error est invoqué à chaque fois qu'une exception est soulevée dans une route ou un filtre. Notez qu'en développement, il ne sera exécuté que si vous définissez l'option show exceptions à :after_handler :

set :show_exceptions, :after_handler

L'objet exception est accessible via la variable Rack sinatra.error :

error do
  'Désolé mais une méchante erreur est survenue - ' + env['sinatra.error'].message
end

Erreur personnalisée :

error MonErreurSurMesure do
  'Oups ! Il est arrivé...' + env['sinatra.error'].message
end

Donc si cette erreur est soulevée :

get '/' do
  raise MonErreurSurMesure, 'quelque chose de mal'
end

La réponse sera :

Oups ! Il est arrivé... quelque chose de mal

Alternativement, vous pouvez avoir un gestionnaire d'erreur associé à un code particulier :

error 403 do
  'Accès interdit'
end

get '/secret' do
  403
end

Ou un intervalle :

error 400..510 do
  'Boom'
end

Sinatra installe pour vous quelques gestionnaires not_found et error génériques lorsque vous êtes en environnement de development.

Les Middlewares Rack

Sinatra fonctionne avec Rack, une interface standard et minimale pour les web frameworks Ruby. Un des points forts de Rack est le support de ce que l'on appelle des "middlewares" -- composants qui viennent se situer entre le serveur et votre application, et dont le but est de visualiser/manipuler la requête/réponse HTTP, et d'offrir diverses fonctionnalités classiques.

Sinatra permet d'utiliser facilement des middlewares Rack via la méthode de haut niveau use :

require 'sinatra'
require 'mon_middleware_perso'

use Rack::Lint
use MonMiddlewarePerso

get '/bonjour' do
  'Bonjour le monde'
end

La sémantique de use est identique à celle définie dans le DSL de Rack::Builder (le plus souvent utilisé dans un fichier rackup). Par exemple, la méthode use accepte divers arguments ainsi que des blocs :

use Rack::Auth::Basic do |identifiant, mot_de_passe|
  identifiant == 'admin' && mot_de_passe == 'secret'
end

Rack est distribué avec de nombreux middlewares standards pour loguer, débuguer, faire du routage URL, de l'authentification ou gérer des sessions. Sinatra gère plusieurs de ces composants automatiquement via son système de configuration, ce qui vous dispense de faire un use pour ces derniers.

Vous trouverez d'autres middlewares intéressants sur rack, rack-contrib, ou en consultant le wiki de Rack.

Tester

Les tests pour Sinatra peuvent être écrit avec n'importe quelle bibliothèque basée sur Rack. Rack::Test est recommandé :

require 'mon_application_sinatra'
require 'minitest/autorun'
require 'rack/test'

class MonTest < Minitest::Test
  include Rack::Test::Methods

  def app
    Sinatra::Application
  end

  def test_ma_racine
    get '/'
    assert_equal 'Bonjour le monde !', last_response.body
  end

  def test_avec_des_parametres
    get '/rencontrer', :nom => 'Frank'
    assert_equal 'Salut Frank !', last_response.body
  end

  def test_avec_agent
    get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
    assert_equal "Vous utilisez Songbird !", last_response.body
  end
end

Note : si vous utilisez le style modulaire de Sinatra, remplacez Sinatra::Application par le nom de la classe de votre application.

Sinatra::Base - Les Middlewares, Bibliothèques, et Applications Modulaires

Définir votre application au niveau supérieur fonctionne bien dans le cas des micro-applications mais présente pas mal d'inconvénients pour créer des composants réutilisables sous forme de middlewares Rack, de Rails metal, de simples librairies avec un composant serveur ou même d'extensions Sinatra. Le niveau supérieur suppose une configuration dans le style des micro-applications (une application d'un seul fichier, des répertoires ./public et ./views, des logs, une page d'erreur, etc...). C'est là que Sinatra::Base prend tout son intérêt :

require 'sinatra/base'

class MonApplication < Sinatra::Base
  set :sessions, true
  set :foo, 'bar'

  get '/' do
    'Bonjour le monde !'
  end
end

Les méthodes de la classe Sinatra::Base sont parfaitement identiques à celles disponibles via le DSL de haut niveau. Il suffit de deux modifications pour transformer la plupart des applications de haut niveau en un composant Sinatra::Base :

  • Votre fichier doit charger sinatra/base au lieu de sinatra, sinon toutes les méthodes du DSL Sinatra seront importées dans l'espace de nom principal.
  • Les gestionnaires de routes, la gestion d'erreur, les filtres et les options doivent être placés dans une classe héritant de Sinatra::Base.

Sinatra::Base est une page blanche. La plupart des options sont désactivées par défaut, y compris le serveur intégré. Reportez-vous à Options et Configuration pour plus d'informations sur les options et leur fonctionnement. Si vous souhaitez un comportement plus proche de celui obtenu lorsque vous définissez votre application au niveau supérieur (aussi connu sous le nom de style Classique), vous pouvez créer une classe héritant de Sinatra::Application.

require 'sinatra/base'

class MyApp < Sinatra::Application
  get '/' do
    'Bonjour le monde !'
  end
end

Style modulaire vs. style classique

Contrairement aux idées reçues, il n'y a rien de mal à utiliser le style classique. Si c'est ce qui convient pour votre application, vous n'avez aucune raison de passer à une application modulaire.

Le principal inconvénient du style classique sur le style modulaire est que vous ne pouvez avoir qu'une application par processus Ruby. Si vous pensez en utiliser plus, passez au style modulaire. Et rien ne vous empêche de mixer style classique et style modulaire.

Si vous passez d'un style à l'autre, souvenez-vous des quelques différences mineures en ce qui concerne les paramètres par défaut :

Paramètre Classique Modulaire Modulaire
app_file fichier chargeant sinatra fichier héritant de Sinatra::Base fichier héritant de Sinatra::Application
run $0 == app_file false false
logging true false true
method_override true false true
inline_templates true false true
static true File.exist?(public_folder) true

Servir une application modulaire

Il y a deux façons de faire pour démarrer une application modulaire, démarrez avec run! :

# my_app.rb
require 'sinatra/base'

class MyApp < Sinatra::Base
  # ... code de l'application ici ...

  # démarre le serveur si ce fichier est directement exécuté
  run! if app_file == $0
end

Démarrez ensuite avec :

ruby my_app.rb

Ou alors avec un fichier config.ru, qui permet d'utiliser n'importe quel gestionnaire Rack :

# config.ru
require './my_app'
run MyApp

Exécutez :

rackup -p 4567

Utiliser une application de style classique avec un fichier config.ru

Ecrivez votre application :

# app.rb
require 'sinatra'

get '/' do
  'Bonjour le monde !'
end

Et un fichier config.ru correspondant :

require './app'
run Sinatra::Application

Quand utiliser un fichier config.ru ?

Quelques cas où vous devriez utiliser un fichier config.ru :

  • Vous souhaitez déployer avec un autre gestionnaire Rack (Passenger, Unicorn, Heroku, ...).
  • Vous souhaitez utiliser plus d'une sous-classe de Sinatra::Base.
  • Vous voulez utiliser Sinatra comme un middleware, non en tant que endpoint.

Il n'est pas nécessaire de passer par un fichier config.ru pour la seule raison que vous êtes passé au style modulaire, et vous n'avez pas besoin de passer au style modulaire pour utiliser un fichier config.ru.

Utiliser Sinatra comme Middleware

Non seulement Sinatra peut utiliser d'autres middlewares Rack, il peut également être à son tour utilisé au-dessus de n'importe quel endpoint Rack en tant que middleware. Cet endpoint peut très bien être une autre application Sinatra, ou n'importe quelle application basée sur Rack (Rails/Ramaze/Camping/...) :

require 'sinatra/base'

class EcranDeConnexion < Sinatra::Base
  enable :sessions

  get('/connexion') { haml :connexion }

  post('/connexion') do
    if params['nom'] = 'admin' && params['motdepasse'] = 'admin'
      session['nom_utilisateur'] = params['nom']
    else
      redirect '/connexion'
    end
  end
end

class MonApp < Sinatra::Base
  # le middleware sera appelé avant les filtres
  use EcranDeConnexion

  before do
    unless session['nom_utilisateur']
      halt "Accès refusé, merci de vous <a href='/connexion'>connecter</a>."
    end
  end

  get('/') { "Bonjour #{session['nom_utilisateur']}." }
end

Création dynamique d'applications

Il se peut que vous ayez besoin de créer une nouvelle application à l'exécution sans avoir à les assigner à une constante, vous pouvez le faire grâce à Sinatra.new :

require 'sinatra/base'
mon_app = Sinatra.new { get('/') { "salut" } }
mon_app.run!

L'application dont elle hérite peut être passé en argument optionnel :

# config.ru
require 'sinatra/base'

controleur = Sinatra.new do
  enable :logging
  helpers MyHelpers
end

map('/a') do
  run Sinatra.new(controleur) { get('/') { 'a' } }
end

map('/b') do
  run Sinatra.new(controleur) { get('/') { 'b' } }
end

C'est notamment utile pour tester des extensions pour Sinatra ou bien pour utiliser Sinatra dans votre propre bibliothèque.

Cela permet également d'utiliser très facilement Sinatra comme middleware :

require 'sinatra/base'

use Sinatra do
  get('/') { ... }
end

run RailsProject::Application

Contextes et Binding

Le contexte dans lequel vous êtes détermine les méthodes et variables disponibles.

Contexte de l'application/classe

Une application Sinatra correspond à une sous-classe de Sinatra::Base. Il s'agit de Sinatra::Application si vous utilisez le DSL de haut niveau (require 'sinatra'). Sinon c'est la sous-classe que vous avez définie. Dans le contexte de cette classe, vous avez accès aux méthodes telles que get ou before, mais pas aux objets request ou session étant donné que toutes les requêtes sont traitées par une seule classe d'application.

Les options définies au moyen de set deviennent des méthodes de classe :

class MonApp < Sinatra::Base
  # Eh, je suis dans le contexte de l'application !
  set :foo, 42
  foo # => 42

  get '/foo' do
    # Eh, je ne suis plus dans le contexte de l'application !
  end
end

Vous avez le binding du contexte de l'application dans :

  • Le corps de la classe d'application
  • Les méthodes définies par les extensions
  • Le bloc passé à helpers
  • Les procs/blocs utilisés comme argument pour set
  • Le bloc passé à Sinatra.new

Vous pouvez atteindre ce contexte (donc la classe) de la façon suivante :

  • Via l'objet passé dans les blocs configure (configure { |c| ... })
  • En utilisant settings dans le contexte de la requête

Contexte de la requête/instance

Pour chaque requête traitée, une nouvelle instance de votre classe d'application est créée et tous vos gestionnaires sont exécutés dans ce contexte. Depuis celui-ci, vous pouvez accéder aux objets request et session ou faire appel aux fonctions de rendu telles que erb ou haml. Vous pouvez accéder au contexte de l'application depuis le contexte de la requête au moyen de settings :

class MonApp < Sinatra::Base
  # Eh, je suis dans le contexte de l'application !
  get '/ajouter_route/:nom' do
    # Contexte de la requête pour '/ajouter_route/:nom'
    @value = 42

    settings.get("/#{params['nom']}") do
      # Contexte de la requête pour "/#{params['nom']}"
      @value # => nil (on est pas au sein de la même requête)
    end

    "Route ajoutée !"
  end
end

Vous avez le binding du contexte de la requête dans :

  • les blocs get, head, post, put, delete, options, patch, link et unlink
  • les filtres before et after
  • les méthodes utilitaires (définies au moyen de helpers)
  • les vues et templates

Le contexte de délégation

Le contexte de délégation se contente de transmettre les appels de méthodes au contexte de classe. Toutefois, il ne se comporte pas à 100% comme le contexte de classe car vous n'avez pas le binding de la classe : seules les méthodes spécifiquement déclarées pour délégation sont disponibles et il n'est pas possible de partager de variables/états avec le contexte de classe (comprenez : self n'est pas le même). Vous pouvez ajouter des délégations de méthode en appelant Sinatra::Delegator.delegate :method_name.

Vous avez le binding du contexte de délégation dans :

  • Le binding de haut niveau, si vous avez utilisé require "sinatra"
  • Un objet qui inclut le module Sinatra::Delegator

Pour vous faire une idée, vous pouvez jeter un coup d'oeil au mixin Sinatra::Delegator qui étend l'objet principal.

Ligne de commande

Les applications Sinatra peuvent être lancées directement :

ruby mon_application.rb [-h] [-x] [-e ENVIRONNEMENT] [-p PORT] [-o HOTE] [-s SERVEUR]

Avec les options :

-h # aide
-p # déclare le port (4567 par défaut)
-o # déclare l'hôte (0.0.0.0 par défaut)
-e # déclare l'environnement (development par défaut)
-s # déclare le serveur/gestionnaire à utiliser (thin par défaut)
-x # active le mutex lock (off par défaut)

Multi-threading

Cette partie est basée sur une réponse StackOverflow de Konstantin.

Sinatra n'impose pas de modèle de concurrence. Sinatra est thread-safe, vous pouvez donc utiliser n'importe quel gestionnaire Rack, comme Thin, Puma ou WEBrick en mode multi-threaded.

Cela signifie néanmoins qu'il vous faudra spécifier les paramètres correspondant au gestionnaire Rack utilisé lors du démarrage du serveur.

L'exemple ci-dessous montre comment vous pouvez exécuter un serveur Thin de manière multi-threaded:

# app.rb
require 'sinatra/base'

classe App < Sinatra::Base
  get '/' do
    'Bonjour le monde !'
  end
end

App.run!

Pour démarrer le serveur, exécuter la commande suivante:

thin --threaded start

Configuration nécessaire

Les versions suivantes de Ruby sont officiellement supportées :

Ruby 2.2
2.2 est totalement supporté et recommandé. L'abandon de son support officiel n'est pas à l'ordre du jour.
Rubinius
Rubinius est officiellement supporté (Rubinius >= 2.x). Un gem install puma est recommandé.
JRuby
La dernière version stable de JRuby est officiellement supportée. Il est déconseillé d'utiliser des extensions C avec JRuby. Un gem install trinidad est recommandé.

Les versions antérieures à 2.2.2 ne sont plus supportées depuis Sinatra 2.0.

Nous gardons également un oeil sur les versions Ruby à venir.

Les implémentations Ruby suivantes ne sont pas officiellement supportées mais sont malgré tout connues pour permettre de faire fonctionner Sinatra :

  • Versions plus anciennes de JRuby et Rubinius
  • Ruby Enterprise Edition
  • MacRuby, Maglev, IronRuby
  • Ruby 1.9.0 et 1.9.1 (mais nous déconseillons leur utilisation)

Le fait de ne pas être officiellement supporté signifie que si quelque chose ne fonctionne pas sur cette plateforme uniquement alors c'est un problème de la plateforme et pas un bug de Sinatra.

Nous lançons également notre intégration continue (CI) avec ruby-head (la future 2.1.0), mais nous ne pouvont rien garantir étant donné les évolutions continuelles. La version 2.1.0 devrait être totalement supportée.

Sinatra devrait fonctionner sur n'importe quel système d'exploitation supporté par l'implémentation Ruby choisie.

Si vous utilisez MacRuby, vous devriez gem install control_tower.

Il n'est pas possible d'utiliser Sinatra sur Cardinal, SmallRuby, BlueRuby ou toute version de Ruby antérieure à 1.8.7 à l'heure actuelle.

Essuyer les plâtres

Si vous souhaitez tester la toute dernière version de Sinatra, n'hésitez pas à faire tourner votre application sur la branche master, celle-ci devrait être stable.

Pour cela, la méthode la plus simple est d'installer une gem de prerelease que nous publions de temps en temps :

gem install sinatra --pre

Ce qui permet de bénéficier des toutes dernières fonctionnalités.

Installer avec Bundler

Il est cependant conseillé de passer par Bundler pour faire tourner votre application avec la dernière version de Sinatra.

Pour commencer, installez bundler si nécessaire :

gem install bundler

Ensuite, créez un fichier Gemfile dans le dossier de votre projet :

source 'https://rubygems.org'
gem 'sinatra', :github => "sinatra/sinatra"

# autres dépendances
gem 'haml'                    # si par exemple vous utilisez haml
gem 'activerecord', '~> 3.0'  # au cas où vous auriez besoin de ActiveRecord 3.x

Notez que vous devez lister toutes les dépendances de votre application dans ce fichier Gemfile. Les dépendances directes de Sinatra (Rack et Tilt) seront automatiquement téléchargées et ajoutées par Bundler.

Vous pouvez alors lancer votre application de la façon suivante :

bundle exec ruby myapp.rb

Versions

Sinatra se conforme aux versions sémantiques, aussi bien SemVer que SemVerTag.

Mais encore