kotovalexarian-likes-github/sinatra
1
0
Fork 0
mirror of https://github.com/sinatra/sinatra synced 2023-03-27 23:18:01 -04:00
Code Releases Activity
sinatra/README.es.md
ceclinux f47b178ef6 change all Fixnum to Integer in readmes
2018-11-07 16:02:10 +08:00

83 KiB
Raw Blame History

Sinatra

Build Status

Sinatra es un DSL para crear aplicaciones web rápidamente en Ruby con un mínimo esfuerzo:

# miapp.rb
require 'sinatra'

get '/' do
  'Hola mundo!'
end

Instala la gema:

gem install sinatra
ruby miapp.rb

Y corre la aplicación:

gem install sinatra
ruby miapp.rb

Ver en http://localhost:4567.

El código que cambiaste no tendra efecto hasta que reinicies el servidor. Por favor reinicia el servidor cada vez que cambies tu código o usa sinatra/reloader.

Se recomienda ejecutar gem install thin, porque Sinatra lo utilizará si está disponible.

Tabla de Contenidos

Rutas

En Sinatra, una ruta es un método HTTP junto a un patrón de un URL. Cada ruta está asociada a un bloque:

get '/' do
  .. mostrar algo ..
end

post '/' do
  .. crear algo ..
end

put '/' do
  .. reemplazar algo ..
end

patch '/' do
  .. modificar algo ..
end

delete '/' do
  .. aniquilar algo ..
end

options '/' do
  .. informar algo ..
end

link '/' do
  .. afiliar a algo ..
end

unlink '/' do
  .. separar algo ..
end

Las rutas son comparadas en el orden en el que son definidas. La primera ruta que coincide con la petición es invocada.

Las rutas con barras al final son distintas a las que no tienen:

get '/foo' do
  # no es igual que "GET /foo/"
end

Los patrones de las rutas pueden incluir parámetros nombrados, accesibles a través del hash params:

get '/hola/:nombre' do
  # coincide con "GET /hola/foo" y "GET /hola/bar"
  # params['nombre'] es 'foo' o 'bar'
  "Hola #{params['nombre']}!"
end

También puede acceder a los parámetros nombrados usando parámetros de bloque:

get '/hola/:nombre' do |n|
  # coincide con "GET /hola/foo" y "GET /hola/bar"
  # params['nombre'] es 'foo' o 'bar'
  # n almacena params['nombre']
  "Hola #{n}!"
end

Los patrones de ruta también pueden incluir parámetros splat (o wildcard), accesibles a través del arreglo params['splat']:

get '/decir/*/al/*' do
  # coincide con /decir/hola/al/mundo
  params['splat'] # => ["hola", "mundo"]
end

get '/descargar/*.*' do
  # coincide con /descargar/path/al/archivo.xml
  params['splat'] # => ["path/al/archivo", "xml"]
end

O, con parámetros de bloque:

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

Rutas con Expresiones Regulares:

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

O con un parámetro de bloque:

get %r{/hola/([\w]+)} do |c|
  "Hola, #{c}!"
end

Los patrones de ruta pueden contener parámetros opcionales:

get '/posts/:formato?' do
  # coincide con "GET /posts/" y además admite cualquier extensión, por
  # ejemplo, "GET /posts/json", "GET /posts/xml", etc.
end

Las rutas también pueden usar parámetros de consulta:

get '/posts' do
  # es igual que "GET /posts?title=foo&author=bar"
  title = params['title']
  author = params['author']
  # usa las variables title y author; la consulta es opcional para la ruta /posts
end

A propósito, a menos que desactives la protección para el ataque path traversal (ver más abajo), el path de la petición puede ser modificado antes de que se compare con los de tus rutas.

Puedes perzonalizar las opciones de Mustermann usadas para una ruta pasando el hash :mustermann_opts:

get '\A/posts\z', :mustermann_opts => { :type => :regexp, :check_anchors => false } do
  # es exactamente igual a /posts, con anclaje explícito
  "¡Si igualas un patrón anclado aplaude!"
end

Condiciones

Las rutas pueden incluir una variedad de condiciones de selección, como por ejemplo el user agent:

get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
  "Estás usando la versión de Songbird #{params['agent'][0]}"
end

get '/foo' do
  # Coincide con navegadores que no sean songbird
end

Otras condiciones disponibles son host_name y provides:

get '/', :host_name => /^admin\./ do
  "Área de Administración, Acceso denegado!"
end

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

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

provides busca el encabezado Accept de la solicitud

Puede definir sus propias condiciones fácilmente:

set(:probabilidad) { |valor| condition { rand <= valor } }

get '/gana_un_auto', :probabilidad => 0.1 do
  "Ganaste!"
end

get '/gana_un_auto' do
  "Lo siento, perdiste."
end

Para una condición que toma multiples valores usa splat:

set(:autorizar) do |*roles|   # <- mira el splat
  condition do
    unless sesion_iniciada? && roles.any? {|rol| usuario_actual.tiene_rol? rol }
      redirect "/iniciar_sesion/", 303
    end
  end
end

get "/mi/cuenta/", :autorizar => [:usuario, :administrador] do
  "Detalles de mi cuenta"
end

get "/solo/administradores/", :autorizar => :administrador do
  "Únicamente para administradores!"
end

Valores de Retorno

El valor de retorno de un bloque de ruta determina por lo menos el cuerpo de la respuesta transmitida al cliente HTTP o por lo menos al siguiente middleware en la pila de Rack. Lo más común es que sea un string, como en los ejemplos anteriores. Sin embargo, otros valores también son aceptados.

Puedes retornar cualquier objeto que sea una respuesta Rack válida, un objeto que represente el cuerpo de una respuesta Rack o un código de estado HTTP:

  • Un arreglo con tres elementos: [estado (Integer), cabeceras (Hash), cuerpo de la respuesta (responde a #each)]
  • Un arreglo con dos elementos: [estado (Integer), cuerpo de la respuesta (responde a #each)]
  • Un objeto que responde a #each y que le pasa únicamente strings al bloque dado
  • Un Integer representando el código de estado

De esa manera, por ejemplo, podemos fácilmente implementar un ejemplo de streaming:

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

get('/') { Stream.new }

También puedes usar el stream helper (descrito abajo) para reducir el código repetitivo e incrustar la lógica de stream a la ruta

Comparadores de Rutas Personalizados

Como se mostró anteriormente, Sinatra permite utilizar strings y expresiones regulares para definir las rutas. Sin embargo, no termina ahí.Puedes definir tus propios comparadores muy fácilmente:

class TodoMenosElPatron
  Match = Struct.new(:captures)

  def initialize(excepto)
    @excepto  = excepto
    @capturas = Match.new([])
  end

  def match(str)
    @capturas unless @excepto === str
  end
end

def cualquiera_menos(patron)
  TodoMenosElPatron.new(patron)
end

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

Tenga en cuenta que el ejemplo anterior es un poco rebuscado. Un resultado similar puede conseguirse más sencillamente:

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

O, usando un look ahead negativo:

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

Archivos Estáticos

Los archivos estáticos son servidos desde el directorio público ./public. Puede especificar una ubicación diferente ajustando la opción :public_folder:

set :public_folder, File.dirname(__FILE__) + '/static'

Note que el nombre del directorio público no está incluido en la URL. Por ejemplo, el archivo ./public/css/style.css se accede a través de http://ejemplo.com/css/style.css.

Use la configuración :static_cache_control para agregar el encabezado Cache-Control (Ver mas abajo).

Vistas / Plantillas

Cada lenguaje de plantilla se expone a través de un método de renderizado que lleva su nombre. Estos métodos simplemente devuelven un string:

get '/' do
  erb :index
end

Renderiza views/index.erb.

En lugar del nombre de la plantilla puedes proporcionar directamente el contenido de la misma:

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

Los métodos de renderizado, aceptan además un segundo argumento, el hash de opciones:

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

Renderiza views/index.erb incrustado en views/post.erb (por defecto, la plantilla :index es incrustada en views/layout.erb siempre y cuando este último archivo exista).

Cualquier opción que Sinatra no entienda le será pasada al motor de renderizado de la plantilla:

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

Además, puede definir las opciones para un lenguaje de plantillas de forma general:

set :haml, :format => :html5

get '/' do
  haml :index
end

Las opciones pasadas al método de renderizado tienen precedencia sobre las definidas mediante set.

Opciones disponibles:

locals
Lista de variables locales pasadas al documento. Resultan muy útiles cuando se combinan con parciales. Ejemplo: erb "<%= foo %>", :locals => {:foo => "bar"}
default_encoding
Encoding utilizado cuando el de un string es dudoso. Por defecto toma el valor de settings.default_encoding.
views
Directorio desde donde se cargan las vistas. Por defecto toma el valor de settings.views.
layout
Si es true o false indica que se debe usar, o no, un layout, respectivamente. También puede ser un Symbol que especifique qué plantilla usar. Ejemplo: erb :index, :layout => !request.xhr?
content_type
Content-Type que produce la plantilla. El valor por defecto depende de cada lenguaje de plantillas.
scope
Ámbito en el que se renderiza la plantilla. Por defecto utiliza la instancia de la aplicación. Ten en cuenta que si cambiás esta opción las variables de instancia y los helpers van a dejar de estar disponibles.
layout_engine
Motor de renderizado de plantillas que usa para el layout. Resulta conveniente para lenguajes que no soportan layouts. Por defecto toma el valor del motor usado para renderizar la plantilla. Ejemplo: set :rdoc, :layout_engine => :erb
layout_options
Opciones especiales usadas únicamente para renderizar el layout. Ejemplo: set :rdoc, :layout_options => { :views => 'views/layouts' }

Se asume que las plantillas están ubicadas directamente bajo el directorio ./views. Para usar un directorio diferente:

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

Es importante acordarse que siempre tienes que referenciar a las plantillas con símbolos, incluso cuando se encuentran en un subdirectorio (en este caso tienes que usar: :'subdir/plantilla' o 'subdir/plantilla'.to_sym). Esto es debido a que los métodos de renderización van a renderizar directamente cualquier string que se les pase como argumento.

Plantillas Literales

get '/' do
  haml '%div.titulo Hola Mundo'
end

Renderiza el string de la plantilla. Opcionalmente puedes especificar :path y :line para un backtrace más claro si hay una ruta del sistema de archivos o una línea asociada con ese string

get '/' do
  haml '%div.titulo Hola Mundo', :path => 'ejemplos/archivo.haml', :line => 3
end

Lenguajes de Plantillas Disponibles

Algunos lenguajes tienen varias implementaciones. Para especificar que implementación usar (y para ser thread-safe), deberías requerirla antes de usarla:

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

Plantillas Haml

Dependencias haml
Expresiones de Archivo .haml
Ejemplo haml :index, :format => :html5

Plantillas Erb

Dependencias erubis o erb (incluida en Ruby)
Extensiones de Archivo .erb, .rhtml o .erubis (solamente con Erubis)
Ejemplo erb :index

Plantillas Builder

Dependencias builder
Extensiones de Archivo .builder
Ejemplo builder { |xml| xml.em "hola" }

También toma un bloque para plantillas inline (ver ejemplo).

Plantillas Nokogiri

Dependencias nokogiri
Extensiones de Archivo .nokogiri
Ejemplo nokogiri { |xml| xml.em "hola" }

También toma un bloque para plantillas inline (ver ejemplo).

Plantillas Sass

Dependencias sass
Extensiones de Archivo .sass
Ejemplo sass :stylesheet, :style => :expanded

Plantillas SCSS

Dependencias sass
Extensiones de Archivo .scss
Ejemplo scss :stylesheet, :style => :expanded

Plantillas Less

Dependencias less
Extensiones de Archivo .less
Ejemplo less :stylesheet

Plantillas Liquid

Dependencias liquid
Extensiones de Archivo .liquid
Ejemplo liquid :index, :locals => { :clave => 'valor' }

Como no va a poder llamar a métodos de Ruby (excepto por yield) desde una plantilla Liquid, casi siempre va a querer pasarle locales.

Plantillas Markdown

Dependencias RDiscount, RedCarpet, BlueCloth, kramdown o maruku
Extensiones de Archivo .markdown, .mkd y .md
Ejemplo markdown :index, :layout_engine => :erb

No es posible llamar métodos desde markdown, ni pasarle locales. Por lo tanto, generalmente va a usarlo en combinación con otro motor de renderizado:

erb :resumen, :locals => { :texto => markdown(:introduccion) }

Tenga en cuenta que también puedes llamar al método markdown desde otras plantillas:

%h1 Hola Desde Haml!
%p= markdown(:saludos)

Como no puede utilizar Ruby desde Markdown, no puede usar layouts escritos en Markdown. De todos modos, es posible usar un motor de renderizado para el layout distinto al de la plantilla pasando la opción :layout_engine.

Plantillas Textile

Dependencias RedCloth
Extensiones de Archivo .textile
Ejemplo textile :index, :layout_engine => :erb

No es posible llamar métodos desde textile, ni pasarle locales. Por lo tanto, generalmente vas a usarlo en combinación con otro motor de renderizado:

erb :resumen, :locals => { :texto => textile(:introduccion) }

Ten en cuenta que también puedes llamar al método textile desde otras plantillas:

%h1 Hola Desde Haml!
%p= textile(:saludos)

Como no puedes utilizar Ruby desde Textile, no puedes usar layouts escritos en Textile. De todos modos, es posible usar un motor de renderizado para el layout distinto al de la plantilla pasando la opción :layout_engine.

Plantillas RDoc

Dependencias RDoc
Extensiones de Archivo .rdoc
Ejemplo rdoc :README, :layout_engine => :erb

No es posible llamar métodos desde rdoc, ni pasarle locales. Por lo tanto, generalmente vas a usarlo en combinación con otro motor de renderizado:

erb :resumen, :locals => { :texto => rdoc(:introduccion) }

Ten en cuenta que también puedes llamar al método rdoc desde otras plantillas:

%h1 Hola Desde Haml!
%p= rdoc(:saludos)

Como no puedes utilizar Ruby desde RDoc, no puedes usar layouts escritos en RDoc. De todos modos, es posible usar un motor de renderizado para el layout distinto al de la plantilla pasando la opción :layout_engine.

Plantillas AsciiDoc

Dependencia Asciidoctor
Extensiones de Archivo .asciidoc, .adoc and .ad
Ejemplo asciidoc :README, :layout_engine => :erb

Desde que no se puede utilizar métodos de Ruby desde una plantilla AsciiDoc, casi siempre va a querer pasarle locales.

Plantillas Radius

Dependencias Radius
Extensiones de Archivo .radius
Ejemplo radius :index, :locals => { :clave => 'valor' }

Desde que no se puede utilizar métodos de Ruby (excepto por yield) de una plantilla Radius, casi siempre se necesita pasar locales.

Plantillas Markaby

Dependencias Markaby
Extensiones de Archivo .mab
Ejemplo markaby { h1 "Bienvenido!" }

También toma un bloque para plantillas inline (ver ejemplo).

Plantillas RABL

Dependencias Rabl
Extensiones de Archivo .rabl
Ejemplo rabl :index

Plantillas Slim

Dependencias Slim Lang
Extensiones de Archivo .slim
Ejemplo slim :index

Plantillas Creole

Dependencias Creole
Extensiones de Archivo .creole
Ejemplo creole :wiki, :layout_engine => :erb

No es posible llamar métodos desde creole, ni pasarle locales. Por lo tanto, generalmente va a usarlo en combinación con otro motor de renderizado:

erb :resumen, :locals => { :texto => cerole(:introduccion) }

Debe tomar en cuenta que también puede llamar al método creole desde otras plantillas:

%h1 Hola Desde Haml!
%p= creole(:saludos)

Como no puedes utilizar Ruby desde Creole, no puedes usar layouts escritos en Creole. De todos modos, es posible usar un motor de renderizado para el layout distinto al de la plantilla pasando la opción :layout_engine.

MediaWiki Templates

Dependencia WikiCloth
Extension de Archivo .mediawiki and .mw
Ejemplo mediawiki :wiki, :layout_engine => :erb

No es posible llamar métodos desde el markup de MediaWiki, ni pasar locales al mismo. Por lo tanto usualmente lo usarás en combinación con otro motor de renderizado:

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

Nota que también puedes llamar al método mediawiki desde dentro de otras plantillas:

%h1 Hello From Haml!
%p= mediawiki(:greetings)

Debido a que no puedes llamar a Ruby desde MediaWiki, no puedes usar los diseños escritos en MediaWiki. De todas maneras, es posible usar otro motor de renderizado para esa plantilla pasando la opción :layout_engine.

Plantillas CoffeeScript

Dependencias CoffeeScript y un mecanismo para ejecutar javascript
Extensiones de Archivo .coffee
Ejemplo coffee :index

Plantillas Stylus

Dependencias Stylus y un mecanismo para ejecutar javascript
Extensiones de Archivo .styl
Ejemplo stylus :index

Antes de poder usar las plantillas de Stylus, necesitas cargar stylus y stylus/tilt:

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

get '/' do
  stylus :example
end

Plantillas Yajl

Dependencias yajl-ruby
Extensiones de Archivo .yajl
Ejemplo yajl :index, :locals => { :key => 'qux' }, :callback => 'present', :variable => 'resource'

El contenido de la plantilla se evalúa como código Ruby, y la variable json es convertida a JSON mediante #to_json.

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

Las opciones :callback y :variable se pueden utilizar para decorar el objeto renderizado:

var contenido = {"foo":"bar","baz":"qux"};
present(contenido);

Plantillas WLang

Dependencias wlang
Extensiones de Archivo .wlang
Ejemplo wlang :index, :locals => { :clave => 'valor' }

Como no vas a poder llamar a métodos de Ruby (excepto por yield) desde una plantilla WLang, casi siempre vas a querer pasarle locales.

Accediendo a Variables en Plantillas

Las plantillas son evaluadas dentro del mismo contexto que los manejadores de ruta. Las variables de instancia asignadas en los manejadores de ruta son accesibles directamente por las plantillas:

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

O es posible especificar un Hash de variables locales explícitamente:

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

Esto es usado típicamente cuando se renderizan plantillas como parciales desde adentro de otras plantillas.

Plantillas con yield y layout anidado

Un layout es usualmente una plantilla que llama a yield. Dicha plantilla puede ser usada tanto a travé de la opción :template como describimos arriba, o puede ser rederizada con un bloque como a continuación:

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

Este código es principalmente equivalente a erb :index, :layout => :post.

Pasar bloques a métodos de renderizado es la forma mas útil de crear layouts anidados:

erb :main_layout, :layout => false do
  erb :admin_layout do
    erb :user
  end
end

Esto también se puede hacer en menos líneas de código con:

erb :admin_layout, :layout => :main_layout do
  erb :user
end

Actualmente, los siguientes métodos de renderizado aceptan un bloque: erb, haml, liquid, slim , wlang. También el método general de render acepta un bloque.

Plantillas Inline

Las plantillas pueden ser definidas al final del archivo fuente:

require 'sinatra'

get '/' do
  haml :index
end

__END__

@@ layout
%html
  = yield

@@ index
%div.titulo Hola Mundo

NOTA: Únicamente las plantillas inline definidas en el archivo fuente que requiere Sinatra son cargadas automáticamente. Llamá enable :inline_templates explícitamente si tienes plantillas inline en otros archivos fuente.

Plantillas Nombradas

Las plantillas también pueden ser definidas usando el método top-level template:

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

template :index do
  '%div.titulo Hola Mundo!'
end

get '/' do
  haml :index
end

Si existe una plantilla con el nombre "layout", va a ser usada cada vez que una plantilla es renderizada.Puedes desactivar los layouts individualmente pasando :layout => false o globalmente con set :haml, :layout => false:

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

Asociando Extensiones de Archivo

Para asociar una extensión de archivo con un motor de renderizado, usa Tilt.register. Por ejemplo, si quieres usar la extensión tt para las plantillas Textile, puedes hacer lo siguiente:

Tilt.register :tt, Tilt[:textile]

Añadiendo Tu Propio Motor de Plantillas

Primero, registra tu motor con Tilt, y después, creá tu método de renderizado:

Tilt.register :mipg, MiMotorDePlantilla

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

get '/' do
  mypg :index
end

Renderiza ./views/index.mypg. Mirá https://github.com/rtomayko/tilt para aprender más de Tilt.

Usando Lógica Personalizada para la Búsqueda en Plantillas

Para implementar tu propio mecanismo de búsqueda de plantillas puedes escribir tu propio método #find_template

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

def find_template(views, name, engine, &block)
  Array(views).each do |v|
    super(v, name, engine, &block)
  end
end

Filtros

Los filtros before son evaluados antes de cada petición dentro del mismo contexto que las rutas. Pueden modificar la petición y la respuesta. Las variables de instancia asignadas en los filtros son accesibles por las rutas y las plantillas:

before do
  @nota = 'Hey!'
  request.path_info = '/foo/bar/baz'
end

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

Los filtros after son evaluados después de cada petición dentro del mismo contexto y también pueden modificar la petición y la respuesta. Las variables de instancia asignadas en los filtros before y en las rutas son accesibles por los filtros after:

after do
  puts response.status
end

Nota: A menos que uses el método body en lugar de simplemente devolver un string desde una ruta, el cuerpo de la respuesta no va a estar disponible en un filtro after, debido a que todavía no se ha generado.

Los filtros aceptan un patrón opcional, que cuando está presente causa que los mismos sean evaluados únicamente si el path de la petición coincide con ese patrón:

before '/protegido/*' do
  autenticar!
end

after '/crear/:slug' do |slug|
  session[:ultimo_slug] = slug
end

Al igual que las rutas, los filtros también pueden aceptar condiciones:

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

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

Helpers

Usá el método top-level helpers para definir métodos ayudantes (helpers) que pueden ser utilizados dentro de los manejadores de rutas y las plantillas:

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

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

Por cuestiones organizativas, puede resultar conveniente organizar los métodos helpers en distintos módulos:

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

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

helpers FooUtils, BarUtils

El efecto de utilizar helpers de esta manera es el mismo que resulta de incluir los módulos en la clase de la aplicación.

Usando Sesiones

Una sesión es usada para mantener el estado a través de distintas peticiones. Cuando están activadas, proporciona un hash de sesión para cada sesión de usuario:

enable :sessions

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

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

Secreto de Sesión

Para mejorar la seguridad, los datos de la sesión en la cookie se firman con un secreto usando HMAC-SHA1. El secreto de esta sesión debería ser de manera óptima un valor aleatorio criptográficamente seguro de una longitud adecuada para HMAC-SHA1 que es mayor o igual que 64 bytes (512 bits, 128 hex caracteres). Se le aconsejará que no use un secreto que sea inferior a 32 bytes de aleatoriedad (256 bits, 64 caracteres hexadecimales). Por lo tanto, es muy importante que no solo invente el secreto, sino que use un generador de números aleatorios para crearlo. Los humanos somos extremadamente malos generando valores aleatorios

De forma predeterminada, un secreto de sesión aleatorio seguro de 32 bytes se genera para usted por Sinatra, pero cambiará con cada reinicio de su aplicación. Si tienes varias instancias de tu aplicación y dejas que Sinatra genere la clave, cada instancia tendría una clave de sesión diferente y probablemente no es lo que quieres.

Para una mejor seguridad y usabilidad es recomendado que genere un secreto de sesión aleatorio seguro y se guarde en las variables de entorno en cada host que ejecuta su aplicación para que todas las instancias de su aplicación compartan el mismo secreto. Debería rotar periódicamente esta sesión secreta a un nuevo valor. Aquí hay algunos ejemplos de cómo puede crear un secreto de 64 bytes y configurarlo:

Generación de Secreto de Sesión

$ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
99ae8af...snip...ec0f262ac

Generación de Secreto de Sesión (Puntos Extras)

Usa la gema sysrandom para preferir el uso de el sistema RNG para generar valores aleatorios en lugar de espacio de usuario OpenSSL que MRI Ruby tiene por defecto:

$ gem install sysrandom
Building native extensions.  This could take a while...
Successfully installed sysrandom-1.x
1 gem installed

$ ruby -e "require 'sysrandom/securerandom'; puts SecureRandom.hex(64)"
99ae8af...snip...ec0f262ac

Secreto de Sesión en Variable de Entorno

Establezca una variable de entorno SESSION_SECRET para Sinatra en el valor que generaste. Haz que este valor sea persistente durante los reinicios de su host. El método para hacer esto variará a través de los sistemas operativos, esto es para propósitos ilustrativos solamente:

# echo "export SESSION_SECRET=99ae8af...snip...ec0f262ac" >> ~/.bashrc

Configuración de la Aplicación y su Secreto de Sesión

Configura tu aplicación a prueba de fallas si la variable de entorno SESSION_SECRET no esta disponible

Para puntos extras usa la gema sysrandom acá tambien:

require 'securerandom'
# -or- require 'sysrandom/securerandom'
set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }

Configuración de Sesión

Si desea configurarlo más, también puede almacenar un hash con opciones en la configuración sessions:

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

Para compartir su sesión en otras aplicaciones en subdominios de foo.com, agregue el prefijo dominio con un . como este en su lugar:

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

Escogiendo tu Propio Middleware de Sesión

Tenga en cuenta que enable :sessions en realidad almacena todos los datos en una cookie. Esto no siempre podria ser lo que quieres (almacenar muchos datos aumentará su tráfico, por ejemplo). Puede usar cualquier middleware de sesión proveniente de Rack para hacerlo, se puede utilizar uno de los siguientes métodos:

enable :sessions
set :session_store, Rack::Session::Pool

O para configurar sesiones con un hash de opciones:

set :sessions, :expire_after => 2592000
set :session_store, Rack::Session::Pool

Otra opción es no llamar a enable :sessions, sino su middleware de elección como lo haría con cualquier otro middleware.

Es importante tener en cuenta que al usar este método, la protección de sesiones no estará habilitada por defecto.

También será necesario agregar el middleware de Rack para hacer eso:

use Rack::Session::Pool, :expire_after => 2592000
use Rack::Protection::RemoteToken
use Rack::Protection::SessionHijacking

Mira 'Configurando la protección contra ataques' para mas información.

Interrupción

Para detener inmediatamente una petición dentro de un filtro o una ruta debes usar:

halt

También puedes especificar el estado:

halt 410

O el cuerpo:

halt 'esto va a ser el cuerpo'

O los dos:

halt 401, 'salí de acá!'

Con cabeceras:

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

Obviamente, es posible utilizar halt con una plantilla:

halt erb(:error)

Paso

Una ruta puede pasarle el procesamiento a la siguiente ruta que coincida con la petición usando pass:

get '/adivina/:quien' do
  pass unless params['quien'] == 'Franco'
  'Adivinaste!'
end

get '/adivina/*' do
  'Erraste!'
end

Se sale inmediatamente del bloque de la ruta y se le pasa el control a la siguiente ruta que coincida. Si no coincide ninguna ruta, se devuelve 404.

Desencadenando Otra Ruta

A veces, pass no es lo que quieres, sino obtener el resultado de la llamada a otra ruta. Simplemente use call para lograr esto:

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

get '/bar' do
  "bar"
end

Nota que en el ejemplo anterior, es conveniente mover "bar" a un helper, y llamarlo desde /foo y /bar. Así, vas a simplificar las pruebas y a mejorar el rendimiento.

Si quieres que la petición se envíe a la misma instancia de la aplicación en lugar de otra, usá call! en lugar de call.

En la especificación de Rack puedes encontrar más información sobre call.

Configurando el Cuerpo, Código de Estado y los Encabezados

Es posible, y se recomienda, asignar el código de estado y el cuerpo de una respuesta con el valor de retorno de una ruta. Sin embargo, en algunos escenarios puede que sea conveniente asignar el cuerpo en un punto arbitrario del flujo de ejecución con el método helper body. A partir de ahí, puedes usar ese mismo método para acceder al cuerpo de la respuesta:

get '/foo' do
  body "bar"
end

after do
  puts body
end

También es posible pasarle un bloque a body, que será ejecutado por el Rack handler (puedes usar esto para implementar streaming, mira "Valores de Retorno").

De manera similar, también puedes asignar el código de estado y encabezados:

get '/foo' do
  status 418
  headers \
    "Allow"   => "BREW, POST, GET, PROPFIND, WHEN",
    "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
  body "I'm a tea pot!"
end

También, al igual que body, status y headers sin agregarles argumentos pueden usarse para acceder a sus valores actuales.

Streaming De Respuestas

A veces vas a querer empezar a enviar la respuesta a pesar de que todavía no terminaste de generar su cuerpo. También es posible que, en algunos casos, quieras seguir enviando información hasta que el cliente cierre la conexión. Cuando esto ocurra, el helper stream te va a ser de gran ayuda:

get '/' do
  stream do |out|
    out << "Esto va a ser legen -\n"
    sleep 0.5
    out << " (esperalo) \n"
    sleep 1
    out << "- dario!\n"
  end
end

Puedes implementar APIs de streaming, Server-Sent Events y puede ser usado como base para WebSockets. También puede ser usado para incrementar el throughput si solo una parte del contenido depende de un recurso lento.

Hay que tener en cuenta que el comportamiento del streaming, especialmente el número de peticiones concurrentes, depende del servidor web utilizado para alojar la aplicación. Puede que algunos servidores no soporten streaming directamente, así el cuerpo de la respuesta será enviado completamente de una vez cuando el bloque pasado a stream finalice su ejecución. Si estás usando Shotgun, el streaming no va a funcionar.

Cuando se pasa keep_open como parámetro, no se va a enviar el mensaje close al objeto de stream. Permite que tu lo cierres en el punto de ejecución que quieras. Nuevamente, hay que tener en cuenta que este comportamiento es posible solo en servidores que soporten eventos, como Thin o Rainbows. El resto de los servidores van a cerrar el stream de todos modos:

# long polling

set :server, :thin
connections = []

get '/subscribe' do
  # registrar a un cliente interesado en los eventos del servidor
  stream(:keep_open) do |out|
    connections << out
    # purgar conexiones muertas
    connections.reject!(&:closed?)
  end
end

post '/:message' do
  connections.each do |out|
    # notificar al cliente que ha llegado un nuevo mensaje
    out << params['message'] << "\n"

    # indicar al cliente para conectarse de nuevo
    out.close
  end

  # reconocer
  "message received"
end

También es posible que el cliente cierre la conexión cuando intenta escribir en el socket. Debido a esto, se recomienda verificar con out.closed? antes de intentar escribir.

Logging

En el ámbito de la petición, el helper logger (registrador) expone una instancia de Logger:

get '/' do
  logger.info "cargando datos"
  # ...
end

Este logger tiene en cuenta la configuración de logueo de tu Rack handler. Si el logueo está desactivado, este método va a devolver un objeto que se comporta como un logger pero que en realidad no hace nada. Así, no vas a tener que preocuparte por esta situación.

Ten en cuenta que el logueo está habilitado por defecto únicamente para Sinatra::Application. Si heredaste de Sinatra::Base, probablemente quieras habilitarlo manualmente:

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

Para evitar que se inicialice cualquier middleware de logging, configurá logging a nil. Ten en cuenta que, cuando hagas esto, logger va a devolver nil. Un caso común es cuando quieres usar tu propio logger. Sinatra va a usar lo que encuentre en env['rack.logger'].

Tipos Mime

Cuando usás send_file o archivos estáticos tal vez tengas tipos mime que Sinatra no entiende. Usá mime_type para registrarlos a través de la extensión de archivo:

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

También lo puedes usar con el helper content_type:

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

Generando URLs

Para generar URLs deberías usar el método url. Por ejemplo, en Haml:

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

Tiene en cuenta proxies inversos y encaminadores de Rack, si están presentes.

Este método también puede invocarse mediante su alias to (mirá un ejemplo a continuación).

Redirección del Navegador

Puedes redireccionar al navegador con el método redirect:

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

Cualquier parámetro adicional se utiliza de la misma manera que los argumentos pasados a halt:

redirect to('/bar'), 303
redirect 'http://www.google.com/', 'te confundiste de lugar, compañero'

También puedes redireccionar fácilmente de vuelta hacia la página desde donde vino el usuario con redirect back:

get '/foo' do
  "<a href='/bar'>hacer algo</a>"
end

get '/bar' do
  hacer_algo
  redirect back
end

Para pasar argumentos con una redirección, puedes agregarlos a la cadena de búsqueda:

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

O usar una sesión:

enable :sessions

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

get '/bar' do
  session[:secreto]
end

Control del Cache

Asignar tus encabezados correctamente es el cimiento para realizar un cacheo HTTP correcto.

Puedes asignar el encabezado Cache-Control fácilmente:

get '/' do
  cache_control :public
  "cachealo!"
end

Pro tip: configurar el cacheo en un filtro before:

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

Si estás usando el helper expires para definir el encabezado correspondiente, Cache-Control se va a definir automáticamente:

before do
  expires 500, :public, :must_revalidate
end

Para usar cachés adecuadamente, deberías considerar usar etag o last_modified. Es recomendable que llames a estos asistentes antes de hacer cualquier trabajo pesado, ya que van a enviar la respuesta inmediatamente si el cliente ya tiene la versión actual en su caché:

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

También es posible usar una weak ETag:

etag @articulo.sha1, :weak

Estos helpers no van a cachear nada por vos, sino que van a facilitar la información necesaria para poder hacerlo. Si estás buscando soluciones rápidas de cacheo con proxys reversos, mirá rack-cache:

require "rack/cache"
require "sinatra"

use Rack::Cache

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

Usá la configuración :static_cache_control para agregar el encabezado Cache-Control a archivos estáticos (ver la sección de configuración para más detalles).

De acuerdo con la RFC 2616 tu aplicación debería comportarse diferente si a las cabeceras If-Match o If-None-Match se le asigna el valor * cuando el recurso solicitado ya existe. Sinatra asume para peticiones seguras (como get) y potentes (como put) que el recurso existe, mientras que para el resto (como post) asume que no. Puedes cambiar este comportamiento con la opción :new_resource:

get '/crear' do
  etag '', :new_resource => true
  Articulo.create
  erb :nuevo_articulo
end

Si quieres seguir usando una weak ETag, indicalo con la opción :kind:

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

Enviando Archivos

Para enviar archivos, puedes usar el método send_file:

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

Además acepta un par de opciones:

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

Estas opciones son:

filename
Nombre del archivo devuelto, por defecto es el nombre real del archivo.
last_modified
Valor para el encabezado Last-Modified, por defecto toma el mtime del archivo.
type
El Content-Type que se va a utilizar, si no está presente se intenta adivinar a partir de la extensión del archivo.
disposition
Se utiliza para el encabezado Content-Disposition, y puede tomar alguno de los siguientes valores: nil (por defecto), :attachment y :inline
length
Encabezado Content-Length, por defecto toma el tamaño del archivo
status
Código de estado a enviar. Útil cuando se envía un archivo estático como un error página. Si es compatible con el controlador de Rack, otros medios que no sean la transmisión del proceso de Ruby será utilizado. Si usas este método de ayuda, Sinatra manejará automáticamente las solicitudes de rango.

Accediendo al objeto Request

El objeto de la petición entrante puede ser accedido desde el nivel de la petición (filtros, rutas y manejadores de errores) a través del método request:

# app corriendo en http://ejemplo.com/ejemplo
get '/foo' do
  t = %w[text/css text/html application/javascript]
  request.accept              # ['text/html', '*/*']
  request.accept? 'text/xml'  # true
  request.preferred_type(t)   # 'text/html'
  request.body                # cuerpo de la petición enviado por el cliente (ver más abajo)
  request.scheme              # "http"
  request.script_name         # "/ejemplo"
  request.path_info           # "/foo"
  request.port                # 80
  request.request_method      # "GET"
  request.query_string        # ""
  request.content_length      # longitud de request.body
  request.media_type          # tipo de medio de request.body
  request.host                # "ejemplo.com"
  request.get?                # true (hay métodos análogos para los otros verbos)
  request.form_data?          # false
  request["UNA_CABECERA"]     # valor de la cabecera UNA_CABECERA
  request.referrer            # la referencia del cliente o '/'
  request.user_agent          # user agent (usado por la condición :agent)
  request.cookies             # hash de las cookies del navegador
  request.xhr?                # es una petición ajax?
  request.url                 # "http://ejemplo.com/ejemplo/foo"
  request.path                # "/ejemplo/foo"
  request.ip                  # dirección IP del cliente
  request.secure?             # false (sería true sobre ssl)
  request.forwarded?          # true (si se está corriendo atrás de un proxy reverso)
  request.env                 # hash de entorno directamente entregado por Rack
end

Algunas opciones, como script_name o path_info pueden también ser escritas:

before { request.path_info = "/" }

get "/" do
  "todas las peticiones llegan acá"
end

El objeto request.body es una instancia de IO o StringIO:

post "/api" do
  request.body.rewind  # en caso de que alguien ya lo haya leído
  datos = JSON.parse request.body.read
  "Hola #{datos['nombre']}!"
end

Archivos Adjuntos

Puedes usar el helper attachment para indicarle al navegador que almacene la respuesta en el disco en lugar de mostrarla en pantalla:

get '/' do
  attachment
  "guardalo!"
end

También puedes pasarle un nombre de archivo:

get '/' do
  attachment "info.txt"
  "guardalo!"
end

Fecha y Hora

Sinatra pone a tu disposición el helper time_for, que genera un objeto Time a partir del valor que recibe como argumento. Este valor puede ser un String, pero también es capaz de convertir objetos DateTime, Date y de otras clases similares:

get '/' do
  pass if Time.now > time_for('Dec 23, 2012')
  "todavía hay tiempo"
end

Este método es usado internamente por métodos como expires y last_modified, entre otros. Por lo tanto, es posible extender el comportamiento de estos métodos sobreescribiendo time_for en tu aplicación:

helpers do
  def time_for(value)
    case value
    when :ayer then Time.now - 24*60*60
    when :mañana then Time.now + 24*60*60
    else super
    end
  end
end

get '/' do
  last_modified :ayer
  expires :mañana
  "hola"
end

Buscando los Archivos de las Plantillas

El helper find_template se utiliza para encontrar los archivos de las plantillas que se van a renderizar:

find_template settings.views, 'foo', Tilt[:haml] do |archivo|
  puts "podría ser #{archivo}"
end

Si bien esto no es muy útil, lo interesante es que puedes sobreescribir este método, y así enganchar tu propio mecanismo de búsqueda. Por ejemplo, para poder utilizar más de un directorio de vistas:

set :views, ['vistas', 'plantillas']

helpers do
  def find_template(views, name, engine, &block)
    Array(views).each { |v| super(v, name, engine, &block) }
  end
end

Otro ejemplo consiste en usar directorios diferentes para los distintos motores de renderizado:

set :views, :sass => 'vistas/sass', :haml => 'plantillas', :defecto => 'vistas'

helpers do
  def find_template(views, name, engine, &block)
    _, folder = views.detect { |k,v| engine == Tilt[k] }
    folder ||= views[:defecto]
    super(folder, name, engine, &block)
  end
end

¡Es muy fácil convertir estos ejemplos en una extensión y compartirla!

Notá que find_template no verifica si un archivo existe realmente, sino que llama al bloque que recibe para cada path posible. Esto no representa un problema de rendimiento debido a que render va a usar break ni bien encuentre un archivo que exista. Además, las ubicaciones de las plantillas (y su contenido) se cachean cuando no estás en el modo de desarrollo. Es bueno tener en cuenta lo anterior si escribís un método extraño.

Configuración

Ejecutar una vez, en el inicio, en cualquier entorno:

configure do
  # asignando una opción
  set :opcion, 'valor'

  # asignando varias opciones
  set :a => 1, :b => 2

  # atajo para `set :opcion, true`
  enable :opcion

  # atajo para `set :opcion, false`
  disable :opcion

  # también puedes tener configuraciones dinámicas usando bloques
  set(:css_dir) { File.join(views, 'css') }
end

Ejecutar únicamente cuando el entorno (la variable de entorno APP_ENV) es :production:

configure :production do
  ...
end

Ejecutar cuando el entorno es :production o :test:

configure :production, :test do
  ...
end

Puedes acceder a estas opciones utilizando el método settings:

configure do
  set :foo, 'bar'
end

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

Configurando la Protección Contra Ataques

Sinatra usa Rack::Protection para defender a tu aplicación de los ataques más comunes. Si por algún motivo, quieres desactivar esta funcionalidad, puedes hacerlo como se indica a continuación (ten en cuenta que tu aplicación va a quedar expuesta a un montón de vulnerabilidades bien conocidas):

disable :protection

También es posible desactivar una única capa de defensa:

set :protection, :except => :path_traversal

O varias:

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

Configuraciones Disponibles

absolute_redirects
Si está deshabilitada, Sinatra va a permitir redirecciones relativas, sin embargo, como consecuencia de esto, va a dejar de cumplir con el RFC 2616 (HTTP 1.1), que solamente permite redirecciones absolutas.
Activalo si tu apliación está corriendo atrás de un proxy reverso que no se ha configurado adecuadamente. Notá que el helper url va a seguir produciendo URLs absolutas, a menos que le pasés false como segundo parámetro.
Deshabilitada por defecto.
add_charset
Tipos mime a los que el helper content_type les añade automáticamente el charset. En general, no deberías asignar directamente esta opción, sino añadirle los charsets que quieras: settings.add_charset << "application/foobar"
app_file
Path del archivo principal de la aplicación, se utiliza para detectar la raíz del proyecto, el directorio de las vistas y el público, así como las plantillas inline.
bind
Dirección IP que utilizará el servidor integrado (por defecto: 0.0.0.0 o localhost si su `environment` está configurado para desarrollo).
default_encoding
Encoding utilizado cuando el mismo se desconoce (por defecto "utf-8").
dump_errors
Mostrar errores en el log.
environment
Entorno actual, por defecto toma el valor de ENV['APP_ENV'], o "development" si no está disponible.
logging
Define si se utiliza el logger.
lock
Coloca un lock alrededor de cada petición, procesando solamente una por proceso.
Habilitá esta opción si tu aplicación no es thread-safe. Se encuentra deshabilitada por defecto.
method_override
Utiliza el parámetro _method para permtir formularios put/delete en navegadores que no los soportan.
mustermann_opts
Un hash predeterminado de opciones para pasar a Mustermann.new al compilar las rutas.
port
Puerto en el que escuchará el servidor integrado.
prefixed_redirects
Define si inserta request.script_name en las redirecciones cuando no se proporciona un path absoluto. De esta manera, cuando está habilitada, redirect '/foo' se comporta de la misma manera que redirect to('/foo'). Se encuentra deshabilitada por defecto.
protection
Define si se habilitan o no las protecciones de ataques web. Ver la sección de protección encima.
public_folder
Lugar del directorio desde donde se sirven los archivos públicos. Solo se utiliza cuando se sirven archivos estáticos (ver la opción static). Si no está presente, se infiere del valor de la opción app_file.
quiet
Inhabilita los logs generados por los comandos de inicio y detención de Sinatra. false por defecto.
reload_templates
Define Si se vuelven a cargar plantillas entre las solicitudes o no. Habilitado en modo de desarrollo.
root
Lugar del directorio raíz del proyecto. Si no está presente, se infiere del valor de la opción app_file.
raise_errors
Elevar excepciones (detiene la aplicación). Se encuentra activada por defecto cuando el valor de environment es "test". En caso contrario estará desactivada.
run
Cuando está habilitada, Sinatra se va a encargar de iniciar el servidor web, no la habilites cuando estés usando rackup o algún otro medio.
running
Indica si el servidor integrado está ejecutándose, ¡no cambiés esta configuración!.
server
Servidor, o lista de servidores, para usar como servidor integrado. Por defecto: ['thin', 'mongrel', 'webrick'], el orden establece la prioridad.
server_settings
Si está utilizando un servidor web WEBrick, presumiblemente para su entorno de desarrollo, puede pasar un hash de opciones a server_settings , como SSLEnable o SSLVerifyClient . Sin embargo, los servidores web como Puma y Thin no son compatibles, por lo que puede establecer server_settings definiéndolo como un método cuando llame a configure .
sessions
Habilita el soporte de sesiones basadas en cookies a través de Rack::Session::Cookie. Ver la sección 'Usando Sesiones' para más información.
session_store
Define el middleware de sesión Rack utilizado. Predeterminado a Rack::Session::Cookie. Consulte la sección 'Uso de sesiones' para obtener más información. información.
show_exceptions
Muestra un stack trace en el navegador cuando ocurre una excepción. Se encuentra activada por defecto cuando el valor de environment es "development". En caso contrario estará desactivada.
También se puede establecer en :after_handler para activar la aplicación especificada que hara el manejo de errores antes de mostrar un stack trace en el navegador.
static
Define si Sinatra debe servir los archivos estáticos.
Deshabilitar cuando se utiliza un servidor capaz de hacer esto por su cuenta.
La desactivación aumentará el rendimiento.
Habilitado por defecto en estilo clásico, deshabilitado para aplicaciones modulares.
static_cache_control
Cuando Sinatra está sirviendo archivos estáticos, y esta opción está habilitada, les va a agregar encabezados Cache-Control a las respuestas. Para esto utiliza el helper cache_control. Se encuentra deshabilitada por defecto. Notar que es necesario utilizar un array cuando se asignan múltiples valores: set :static_cache_control, [:public, :max_age => 300].
threaded
Si se establece en true , le dirá a Thin que use EventMachine.defer para procesar la solicitud.
traps
Define si Sinatra debería manejar las señales del sistema.
views
Path del directorio de las vistas. Si no está presente, se infiere del valor de la opción app_file.
x_cascade
Establece o no el encabezado de X-Cascade si no hay una coincidencia de ruta. verdadero por defecto.

Entornos

Existen tres entornos (environments) predefinidos: development, production y test. El entorno por defecto es development y tiene algunas particularidades:

  • Se recargan las plantillas entre una petición y la siguiente, a diferencia de production y test, donde se cachean.
  • Se instalan manejadores de errores not_found y error especiales que muestran un stack trace en el navegador cuando son disparados.

Para utilizar alguno de los otros entornos puede asignarse el valor correspondiente a la variable de entorno APP_ENV:

APP_ENV=production ruby my_app.rb

Los métodos development?, test? y production? te permiten conocer el entorno actual.

get '/' do
  if settings.development?
    "development!"
  else
    "not development!"
  end
end

Manejo de Errores

Los manejadores de errores se ejecutan dentro del mismo contexto que las rutas y los filtros before, lo que significa que puedes usar, por ejemplo, haml, erb, halt, etc.

Not Found

Cuando se eleva una excepción Sinatra::NotFound, o el código de estado de la respuesta es 404, el manejador not_found es invocado:

not_found do
  'No existo'
end

Error

El manejador error es invocado cada vez que una excepción es elevada desde un bloque de ruta o un filtro. El objeto de la excepción se puede obtener de la variable Rack sinatra.error:

error do
  'Disculpá, ocurrió un error horrible - ' + env['sinatra.error'].message
end

Errores personalizados:

error MiErrorPersonalizado do
  'Lo que pasó fue...' + env['sinatra.error'].message
end

Entonces, si pasa esto:

get '/' do
  raise MiErrorPersonalizado, 'algo malo'
end

Obtienes esto:

  Lo que pasó fue... algo malo

También, puedes instalar un manejador de errores para un código de estado:

error 403 do
  'Acceso prohibido'
end

get '/secreto' do
  403
end

O un rango:

error 400..510 do
  'Boom'
end

Sinatra instala manejadores not_found y error especiales cuando se ejecuta dentro del entorno de desarrollo "development" y se muestran en tu navegador para que tengas información adicional sobre el error.

Rack Middleware

Sinatra corre sobre Rack, una interfaz minimalista que es un estándar para frameworks webs escritos en Ruby. Una de las características más interesantes de Rack para los desarrolladores de aplicaciones es el soporte de "middleware" -- componentes que se ubican entre el servidor y tu aplicación, supervisando y/o manipulando la petición/respuesta HTTP para proporcionar varios tipos de funcionalidades comunes.

Sinatra hace muy sencillo construir tuberías de Rack middleware a través del método top-level use:

require 'sinatra'
require 'mi_middleware_personalizado'

use Rack::Lint
use MiMiddlewarePersonalizado

get '/hola' do
  'Hola Mundo'
end

La semántica de use es idéntica a la definida para el DSL Rack::Builder (más frecuentemente usado en archivos rackup). Por ejemplo, el método use acepta argumentos múltiples/variables así como bloques:

use Rack::Auth::Basic do |nombre_de_usuario, password|
  nombre_de_usuario == 'admin' && password == 'secreto'
end

Rack es distribuido con una variedad de middleware estándar para logging, debugging, enrutamiento URL, autenticación y manejo de sesiones. Sinatra usa muchos de estos componentes automáticamente de acuerdo a su configuración para que usualmente no tengas que usarlas (con use) explícitamente.

Puedes encontrar middleware útil en rack, rack-contrib, o en la Rack wiki.

Pruebas

Las pruebas para las aplicaciones Sinatra pueden ser escritas utilizando cualquier framework o librería de pruebas basada en Rack. Se recomienda usar Rack::Test:

require 'mi_app_sinatra'
require 'minitest/autorun'
require 'rack/test'

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

  def app
    Sinatra::Application
  end

  def test_mi_defecto
    get '/'
    assert_equal 'Hola Mundo!', last_response.body
  end

  def test_con_parametros
    get '/saludar', :name => 'Franco'
    assert_equal 'Hola Frank!', last_response.body
  end

  def test_con_entorno_rack
    get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
    assert_equal "Estás usando Songbird!", last_response.body
  end
end

Nota: Si está utilizando Sinatra en el estilo modular, reemplace Sinatra::Application anterior con el nombre de clase de su aplicación.

Sinatra::Base - Middleware, Librerías, y Aplicaciones Modulares

Definir tu aplicación en el nivel superior funciona bien para micro-aplicaciones pero trae inconvenientes considerables a la hora de construir componentes reutilizables como Rack middleware, Rails metal, librerías simples con un componente de servidor o incluso extensiones de Sinatra. El DSL de alto nivel asume una configuración apropiada para micro-aplicaciones (por ejemplo, un único archivo de aplicación, los directorios ./public y ./views, logging, página con detalles de excepción, etc.). Ahí es donde Sinatra::Base entra en el juego:

require 'sinatra/base'

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

  get '/' do
    'Hola Mundo!'
  end
end

Las subclases de Sinatra::Base tienen disponibles exactamente los mismos métodos que los provistos por el DSL de top-level. La mayoría de las aplicaciones top-level se pueden convertir en componentes Sinatra::Base con dos modificaciones:

  • Tu archivo debe requerir sinatra/base en lugar de sinatra; de otra manera, todos los métodos del DSL de sinatra son importados dentro del espacio de nombres principal.
  • Poné las rutas, manejadores de errores, filtros y opciones de tu aplicación en una subclase de Sinatra::Base.

Sinatra::Base es una pizarra en blanco. La mayoría de las opciones están desactivadas por defecto, incluyendo el servidor incorporado. Mirá Opciones y Configuraciones para detalles sobre las opciones disponibles y su comportamiento. Si quieres un comportamiento más similar a cuando defines tu aplicación en el nivel superior (también conocido como Clásico) estilo), puede subclase Sinatra::Aplicación

require 'sinatra/base'

class MiAplicacion < Sinatra::Application
  get '/' do
    'Hola Mundo!'
  end
end

Estilo Modular vs. Clásico

Contrariamente a la creencia popular, no hay nada de malo con el estilo clásico. Si se ajusta a tu aplicación, no es necesario que la cambies a una modular.

La desventaja de usar el estilo clásico en lugar del modular consiste en que solamente puedes tener una aplicación Sinatra por proceso Ruby. Si tienes planificado usar más, cambiá al estilo modular. Al mismo tiempo, ten en cuenta que no hay ninguna razón por la cuál no puedas mezclar los estilos clásico y modular.

A continuación se detallan las diferencias (sútiles) entre las configuraciones de ambos estilos:

Configuración Clásica Modular Modular
app_file archivo que carga sinatra archivo con la subclase de Sinatra::Base archivo con la subclase 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

Sirviendo una Aplicación Modular

Las dos opciones más comunes para iniciar una aplicación modular son, iniciarla activamente con run!:

# mi_app.rb
require 'sinatra/base'

class MiApp < Sinatra::Base
  # ... código de la app  ...

  # iniciar el servidor si el archivo fue ejecutado directamente
  run! if app_file == $0
end

Iniciar con:

ruby mi_app.rb

O, con un archivo config.ru, que permite usar cualquier handler Rack:

# config.ru
require './mi_app'
run MiApp

Después ejecutar:

rackup -p 4567

Usando una Aplicación Clásica con un Archivo config.ru

Escribí el archivo de tu aplicación:

# app.rb
require 'sinatra'

get '/' do
  'Hola mundo!'
end

Y el config.ru correspondiente:

require './app'
run Sinatra::Application

¿Cuándo usar config.ru?

Indicadores de que probablemente quieres usar config.ru:

  • Quieres realizar el deploy con un handler Rack distinto (Passenger, Unicorn, Heroku, ...).
  • Quieres usar más de una subclase de Sinatra::Base.
  • Quieres usar Sinatra únicamente para middleware, pero no como un endpoint.

No hay necesidad de utilizar un archivo config.ru exclusivamente porque tienes una aplicación modular, y no necesitás una aplicación modular para iniciarla con config.ru.

Utilizando Sinatra como Middleware

Sinatra no solo es capaz de usar otro Rack middleware, sino que a su vez, cualquier aplicación Sinatra puede ser agregada delante de un endpoint Rack como middleware. Este endpoint puede ser otra aplicación Sinatra, o cualquier aplicación basada en Rack (Rails/Ramaze/Camping/...):

require 'sinatra/base'

class PantallaDeLogin < Sinatra::Base
  enable :sessions

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

  post('/login') do
    if params['nombre'] == 'admin' && params['password'] == 'admin'
      session['nombre_de_usuario'] = params['nombre']
    else
      redirect '/login'
    end
  end
end

class MiApp < Sinatra::Base
  # el middleware se ejecutará antes que los filtros
  use PantallaDeLogin

  before do
    unless session['nombre_de_usuario']
      halt "Acceso denegado, por favor <a href='/login'>iniciá sesión</a>."
    end
  end

  get('/') { "Hola #{session['nombre_de_usuario']}." }
end

Creación Dinámica de Aplicaciones

Puede que en algunas ocasiones quieras crear nuevas aplicaciones en tiempo de ejecución sin tener que asignarlas a una constante. Para esto tienes Sinatra.new:

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

Acepta como argumento opcional una aplicación desde la que se heredará:

# config.ru
require 'sinatra/base'

controller = Sinatra.new do
  enable :logging
  helpers MisHelpers
end

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

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

Construir aplicaciones de esta forma resulta especialmente útil para testear extensiones Sinatra o para usar Sinatra en tus librerías.

Por otro lado, hace extremadamente sencillo usar Sinatra como middleware:

require 'sinatra/base'

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

run ProyectoRails::Application

Ámbitos y Ligaduras

El ámbito en el que te encuentras determina que métodos y variables están disponibles.

Ámbito de Aplicación/Clase

Cada aplicación Sinatra es una subclase de Sinatra::Base. Si estás usando el DSL de top-level (require 'sinatra'), entonces esta clase es Sinatra::Application, de otra manera es la subclase que creaste explícitamente. Al nivel de la clase tienes métodos como get o before, pero no puedes acceder a los objetos request o session, ya que hay una única clase de la aplicación para todas las peticiones.

Las opciones creadas utilizando set son métodos al nivel de la clase:

class MiApp < Sinatra::Base
  # Ey, estoy en el ámbito de la aplicación!
  set :foo, 42
  foo # => 42

  get '/foo' do
    # Hey, ya no estoy en el ámbito de la aplicación!
  end
end

Tienes la ligadura al ámbito de la aplicación dentro de:

  • El cuerpo de la clase de tu aplicación
  • Métodos definidos por extensiones
  • El bloque pasado a helpers
  • Procs/bloques usados como el valor para set
  • El bloque pasado a Sinatra.new

Este ámbito puede alcanzarse de las siguientes maneras:

  • A través del objeto pasado a los bloques de configuración (configure { |c| ...})
  • Llamando a settings desde dentro del ámbito de la petición

Ámbito de Petición/Instancia

Para cada petición entrante, una nueva instancia de la clase de tu aplicación es creada y todos los bloques de rutas son ejecutados en ese ámbito. Desde este ámbito puedes acceder a los objetos request y session o llamar a los métodos de renderización como erb o haml. Puedes acceder al ámbito de la aplicación desde el ámbito de la petición utilizando settings:

class MiApp < Sinatra::Base
  # Ey, estoy en el ámbito de la aplicación!
  get '/definir_ruta/:nombre' do
    # Ámbito de petición para '/definir_ruta/:nombre'
    @valor = 42

    settings.get("/#{params['nombre']}") do
      # Ámbito de petición para "/#{params['nombre']}"
      @valor # => nil (no es la misma petición)
    end

    "Ruta definida!"
  end
end

Tienes la ligadura al ámbito de la petición dentro de:

  • bloques pasados a get, head, post, put, delete, options, patch, link y unlink
  • filtros before/after
  • métodos helpers
  • plantillas/vistas

Ámbito de Delegación

El ámbito de delegación solo reenvía métodos al ámbito de clase. De cualquier manera, no se comporta 100% como el ámbito de clase porque no tienes la ligadura de la clase: únicamente métodos marcados explícitamente para delegación están disponibles y no compartís variables/estado con el ámbito de clase (léase: tienes un self diferente). Puedes agregar delegaciones de método llamando a Sinatra::Delegator.delegate :nombre_del_metodo.

Tienes és la ligadura al ámbito de delegación dentro de:

  • La ligadura del top-level, si hiciste require "sinatra"
  • Un objeto extendido con el mixin Sinatra::Delegator

Hechale un vistazo al código: acá está el Sinatra::Delegator mixin que extiende el objeto main.

Línea de Comandos

Las aplicaciones Sinatra pueden ser ejecutadas directamente:

ruby myapp.rb [-h] [-x] [-q] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]

Las opciones son:

-h # ayuda
-p # asigna el puerto (4567 es usado por defecto)
-o # asigna el host (0.0.0.0 es usado por defecto)
-e # asigna el entorno (development es usado por defecto)
-s # especifica el servidor/manejador rack (thin es usado por defecto)
-q # activar el modo silecioso para el servidor (está desactivado por defecto)
-x # activa el mutex lock (está desactivado por defecto)

Multi-threading

Basado en esta respuesta en StackOverflow escrita por Konstantin

Sinatra no impone ningún modelo de concurrencia, sino que lo deja en manos del handler Rack que se esté usando (Thin, Puma, WEBrick). Sinatra en sí mismo es thread-safe, así que no hay problema en que el Rack handler use un modelo de concurrencia basado en hilos.

Esto significa que, cuando estemos arrancando el servidor, tendríamos que especificar la opción adecuada para el handler Rack específico. En este ejemplo vemos cómo arrancar un servidor Thin multihilo:

# app.rb

require 'sinatra/base'

class App < Sinatra::Base
  get '/' do
    "¡Hola, Mundo!"
  end
end

App.run!

Para arrancar el servidor, el comando sería:

thin --threaded start

Requerimientos

Las siguientes versiones de Ruby son soportadas oficialmente:

Ruby 2.2
2.2 Es totalmente compatible y recomendado. Actualmente no hay planes soltar el apoyo oficial para ello.
Rubinius
Rubinius es oficialmente compatible (Rubinius> = 2.x). Se recomienda instalar la gema puma gem install puma.
JRuby
La última versión estable de JRuby es oficialmente compatible. No lo es recomienda usar extensiones C con JRuby. Se recomienda instalar la gema trinidad gem install trinidad .

Las versiones de Ruby anteriores a 2.2.2 ya no son compatibles con Sinatra 2.0 .

Siempre le prestamos atención a las nuevas versiones de Ruby.

Las siguientes implementaciones de Ruby no se encuentran soportadas oficialmente. De cualquier manera, pueden ejecutar Sinatra:

  • Versiones anteriores de JRuby y Rubinius
  • Ruby Enterprise Edition
  • MacRuby, Maglev e IronRuby
  • Ruby 1.9.0 y 1.9.1 (pero no te recomendamos que los uses)

No ser soportada oficialmente, significa que si las cosas se rompen ahí y no en una plataforma soportada, asumimos que no es nuestro problema sino el suyo.

También ejecutamos nuestro CI contra ruby-head (futuras versiones de MRI), pero no puede garantizar nada, ya que se mueve constantemente. Esperar próxima 2.x versiones para ser totalmente compatibles.

Sinatra debería trabajar en cualquier sistema operativo compatible la implementación de Ruby elegida

Si ejecuta MacRuby, debe gem install control_tower.

Sinatra actualmente no funciona con Cardinal, SmallRuby, BlueRuby o cualquier versión de Ruby anterior a 2.2.

A la Vanguardia

Si quieres usar el código de Sinatra más reciente, sientete libre de ejecutar tu aplicación sobre la rama master, en general es bastante estable.

También liberamos prereleases de vez en cuando, así, puedes hacer:

gem install sinatra --pre

Para obtener algunas de las últimas características.

Usando Bundler

Esta es la manera recomendada para ejecutar tu aplicación sobre la última versión de Sinatra usando Bundler.

Primero, instala Bundler si no lo hiciste todavía:

gem install bundler

Después, en el directorio de tu proyecto, creá un archivo Gemfile:

source :rubygems
gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"

# otras dependencias
gem 'haml'                    # por ejemplo, si usás haml

Ten en cuenta que tienes que listar todas las dependencias directas de tu aplicación. No es necesario listar las dependencias de Sinatra (Rack y Tilt) porque Bundler las agrega directamente.

Ahora puedes arrancar tu aplicación así:

bundle exec ruby miapp.rb

Versionado

Sinatra utiliza el Versionado Semántico, siguiendo las especificaciones SemVer y SemVerTag.

Lecturas Recomendadas