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 : localhost:4567
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¶ ↑
Sinatra Table des matières Routes Conditions Valeurs de retour Masques de route spécifiques Fichiers statiques Vues / Templates Templates littéraux Langages de template disponibles Templates Haml Templates Erb Templates Builder Templates Nokogiri Templates Sass Templates SCSS Templates Less Templates Liquid Templates Markdown Templates Textile Templates RDoc Templates Radius Templates Markaby Templates RABL Templates Slim Templates Creole Templates CoffeeScript Templates Stylus Templates Yajl Templates WLang Accéder aux variables dans un Template Templates avec yield et layouts imbriqués Templates dans le fichier source Templates nommés Associer des extensions de fichier Ajouter son propre moteur de rendu Filtres Helpers Utiliser les sessions Halt Passer Déclencher une autre route Définir le corps, le code retour et les en-têtes Faire du streaming Journalisation (Logging) Types Mime Former des URLs Redirection du navigateur Contrôle du cache Envoyer des fichiers Accéder à l’objet requête Fichiers joints Gérer Date et Time Chercher les fichiers de templates Configuration Se protéger des attaques Paramètres disponibles Environements Gérer les erreurs NotFound Error Les Middlewares Rack Tester Sinatra::Base - Les Middlewares, Bibliothèques, et Applications Modulaires Style modulaire vs. style classique Servir une application modulaire Utiliser une application de style classique avec un fichier config.ru Quand utiliser un fichier config.ru ? Utiliser Sinatra comme Middleware Création dynamique d’applications Contextes et Binding Contexte de l’application/classe Contexte de la requête/instance Le contexte de délégation Ligne de commande Multi-threading Configuration nécessaire Essuyer les plâtres Installer avec Bundler Faire un clone local Installer globalement Versions Mais encore
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 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
A 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.
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 (Fixnum), en-têtes (Hash),
corps de la réponse (répondant à #each)]
Un tableau de 2 élements
: [code statut (Fixnum), 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 Fixnum 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, File.dirname(__FILE__) + '/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.
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 :
%1 Bonjour depuis Haml ! %= 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 :
%1 Bonjour depuis Haml ! %= 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 :
%1 Bonjour depuis Haml ! %= 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 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 :
%1 Bonjour depuis Haml ! %= 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 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__ @@ layout %tml = yield @@ index %iv.title Bonjour le monde !
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.
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
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 :
%{: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é.
- last_modified
- valeur pour l’en-tête Last-Modified, par défaut la date de modification du fichier.
- 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(views, name, engine, &block) Array(views).each { |v| super(v, name, engine, &block) } 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é.
- 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.
- 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é.
- 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.
- 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.
- 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.
Environements¶ ↑
Il existe trois environnements prédéfinis :
"development"
, "production"
et "test"
. Les environements 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. 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 sur mesure :
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
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 1.8.7
- 1.8.7 est complètement supporté, toutefois si rien ne vous en empêche, nous vous recommandons de faire une mise à jour ou bien de passer à JRuby ou Rubinius. Le support de Ruby 1.8.7 ne sera pas supprimé avant la sortie de Sinatra 2.0. Ruby 1.8.6 n’est plus supporté.
- Ruby 1.9.2
- 1.9.2 est totalement supporté. N’utilisez pas 1.9.2p0 car il provoque des erreurs de segmentation à l’exécution de Sinatra. Son support continuera au minimum jusqu’à la sortie de Sinatra 1.5.
- Ruby 1.9.3
- 1.9.3 est totalement supporté et recommandé. Nous vous rappelons que passer à 1.9.3 depuis une version précédente annulera toutes les sessions. 1.9.3 sera supporté jusqu'à la sortie de Sinatra 2.0.
- Ruby 2.0.0
- 2.0.0 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é.
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
Faire un clone local¶ ↑
Si vous ne souhaitez pas employer Bundler, vous pouvez cloner Sinatra en local dans votre projet et démarrez
votre application avec le dossier sinatra/lib
dans le
$LOAD_PATH
:
cd myapp git clone git://github.com/sinatra/sinatra.git ruby -I sinatra/lib myapp.rb
Et de temps en temps, vous devrez récupérer la dernière version du code source de Sinatra :
cd myapp/sinatra git pull
Installer globalement¶ ↑
Une dernière méthode consiste à construire la gem vous-même :
git clone git://github.com/sinatra/sinatra.git cd sinatra rake sinatra.gemspec rake install
Si vous installez les gems en tant que root, vous devez encore faire un :
sudo rake install
Versions¶ ↑
Sinatra se conforme aux versions sémantiques, aussi bien SemVer que SemVerTag.
Mais encore¶ ↑
Site internet - Plus de documentation, de news, et des liens vers d'autres ressources. Contribuer - Vous avez trouvé un bug ? Besoin d'aide ? Vous avez un patch ? Suivi des problèmes Twitter Mailing List IRC : #sinatra sur freenode.net Sinatra Book Tutoriels et recettes Sinatra Recipes trucs et astuces rédigés par la communauté Documentation API de la dernière version ou du HEAD courant sur www.rubydoc.info/ CI server