sinatra 1.3.0.e → 1.3.0.f

data/README.es.rdoc

@@ -100,6 +100,17 @@ O con un parámetro de bloque:
     "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
+
+A propósito, a menos que desactivés la protección para el ataque <em>path
+traversal</em> (ver más abajo), el path de la petición puede ser modificado
+antes de que se compare con los de tus rutas.
+
 === Condiciones
 
 Las rutas pueden incluir una variedad de condiciones de selección, como por
@@ -139,6 +150,26 @@ Podés definir tus propias condiciones fácilmente:
     "Lo siento, perdiste."
   end
 
+Si tu condición acepta más de un argumento, podés pasarle un arreglo.  Al
+definir la condición puede resultarte conveniente utilizar el operador splat en
+la lista de parámetros:
+
+  set(:autorizar) do |*roles|   # <- mirá 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 al menos el cuerpo de la
@@ -209,14 +240,17 @@ O, usando un lookahead negativo:
 
 Los archivos estáticos son servidos desde el directorio público
 <tt>./public</tt>. Podés especificar una ubicación diferente ajustando la
-opción <tt>:public</tt>:
+opción <tt>:public_folder</tt>:
 
-  set :public, File.dirname(__FILE__) + '/estaticos'
+  set :public_folder, File.dirname(__FILE__) + '/estaticos'
 
 Notá que el nombre del directorio público no está incluido en la URL. Por
 ejemplo, el archivo <tt>./public/css/style.css</tt> se accede a través de
 <tt>http://ejemplo.com/css/style.css</tt>.
 
+Usá la configuración <tt>:static_cache_control</tt> para agregar el encabezado
+<tt>Cache-Control</tt> (ver la sección de configuración para más detalles).
+
 == Vistas / Plantillas
 
 Cada lenguaje de plantilla se expone a través de un método de renderizado que
@@ -428,7 +462,7 @@ layout distinto al de la plantilla pasando la opción <tt>:layout_engine</tt>.
 
 Dependencias::             {rdoc}[http://rdoc.rubyforge.org/]
 Extensiones de Archivo::   <tt>.rdoc</tt>
-Ejemplo::                  <tt>textile :LEEME, :layout_engine => :erb</tt>
+Ejemplo::                  <tt>rdoc :LEEME, :layout_engine => :erb</tt>
 
 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:
@@ -804,7 +838,7 @@ De manera similar, también podés asignar el código de estado y encabezados:
   get '/foo' do
     status 418
     headers \
-      "Allow"   => "BREW, POST, GET, PROPFIND, WHEN"
+      "Allow"   => "BREW, POST, GET, PROPFIND, WHEN",
       "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
     body "I'm a tea pot!"
   end
@@ -812,6 +846,56 @@ De manera similar, también podés asignar el código de estado y encabezados:
 También, al igual que +body+, tanto +status+ como +headers+ pueden utilizarse
 para obtener sus valores cuando no se les pasa argumentos.
 
+=== 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 +stream+ helper 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
+
+Podés implementar APIs de streaming,
+{Server-Sent Events}[http://dev.w3.org/html5/eventsource/] y puede ser usado
+como base para {WebSockets}[http://es.wikipedia.org/wiki/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
+servir la aplicación.  Puede que algunos servidores, como es el caso de
+WEBRick, 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.
+
+Cuando se pasa +keep_open+ como parámetro, no se va a enviar el mensaje
++close+ al objeto de stream. Queda en vos cerrarlo 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:
+
+  set :server, :thin
+  conexiones = []
+
+  get '/' do
+    # mantenemos abierto el stream
+    stream(:keep_open) { |salida| conexiones << salida }
+  end
+
+  post '/' do
+    # escribimos a todos los streams abiertos
+    conexiones.each { |salida| salida << params[:mensaje] << "\n" }
+    "mensaje enviado"
+  end
+
 === Log (Registro)
 
 En el ámbito de la petición, el helper +logger+ (registrador) expone
@@ -898,7 +982,7 @@ búsqueda:
 
 O usar una sesión:
 
-  enable :session
+  enable :sessions
 
   get '/foo' do
     session[:secreto] = 'foo'
@@ -934,7 +1018,7 @@ Si estás usando el helper +expires+ para definir el encabezado correspondiente,
     expires 500, :public, :must_revalidate
   end
 
-Para usar cachés adecuadamente, deberías considerar usar +etag+ y
+Para usar cachés adecuadamente, deberías considerar usar +etag+ o
 +last_modified+.  Es recomendable que llames a estos helpers *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é:
@@ -953,7 +1037,8 @@ También es posible usar una
 
 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, mirá {rack-cache}[http://rtomayko.github.com/rack-cache/]:
+de cacheo con proxys inversos, mirá
+{rack-cache}[http://rtomayko.github.com/rack-cache/]:
 
   require "rack/cache"
   require "sinatra"
@@ -966,6 +1051,10 @@ de cacheo, mirá {rack-cache}[http://rtomayko.github.com/rack-cache/]:
     "hola"
   end
 
+Usá la configuración <tt>:static_cache_control</tt> para agregar el encabezado
+<tt>Cache-Control</tt> a archivos estáticos (ver la sección de configuración
+para más detalles).
+
 === Enviando Archivos
 
 Para enviar archivos, podés usar el método <tt>send_file</tt>:
@@ -1073,6 +1162,38 @@ También podés pasarle un nombre de archivo:
     "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 <tt>find_template</tt> se utiliza para encontrar los archivos de las
@@ -1162,99 +1283,131 @@ Podés acceder a estas opciones utilizando el método <tt>settings</tt>:
     ...
   end
 
+==== Configurando la Protección de Ataques
+
+Sinatra usa {Rack::Protection}[https://github.com/rkh/rack-protection#readme]
+para defender a tu aplicación de los ataques más comunes.  Tenés que tener en
+cuenta que como consecuencia de esto puede venir asociada una disminución del
+rendimiento de tu aplicación.  Si por este, o algún otro motivo, querés
+desactivar está funcionalidad, podés hacerlo:
+
+  disable :protection
+
+También es posible desactivar una única capa de defensa:
+
+  set :protection, :except => :path_traversal
+
+O varias:
+
+  set :protections, :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.
+[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
+                       inverso 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.
 
-                      Activalo si tu apliación está corriendo atrás de un proxy
-                      inverso 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.
+[add_charsets]         tipos mime a los que el helper <tt>content_type</tt> les
+                       añade automáticamente el charset.
 
-                      Deshabilitada por defecto.
+                       En general, no deberías asignar directamente esta opción,
+                       sino añadirle los charsets que quieras:
 
-[add_charsets]        tipos mime a los que el helper <tt>content_type</tt> les
-                      añade automáticamente el charset.
+                         settings.add_charsets << "application/foobar"
 
-                      En general, no deberías asignar directamente esta opción,
-                      sino añadirle los charsets que quieras:
+[app_file]             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.
 
-                        settings.add_charsets << "application/foobar"
+[bind]                 dirección IP que utilizará el servidor integrado (por
+                       defecto: 0.0.0.0).
 
-[app_file]            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.
+[default_encoding]     encoding utilizado cuando el mismo se desconoce (por
+                       defecto <tt>"utf-8"</tt>).
 
-[bind]                dirección IP que utilizará el servidor integrado (por
-                      defecto: 0.0.0.0).
+[dump_errors]          mostrar errores en el log.
 
-[default_encoding]    encoding utilizado cuando el mismo se desconoce (por
-                      defecto <tt>"utf-8"</tt>).
+[environment]          entorno actual, por defecto toma el valor de
+                       <tt>ENV['RACK_ENV']</tt>, o <tt>"development"</tt> si no
+                       está disponible.
 
-[dump_errors]         mostrar errores en el log.
+[logging]              define si se utiliza el logger.
 
-[environment]         entorno actual, por defecto toma el valor de
-                      <tt>ENV['RACK_ENV']</tt>, o <tt>"development"</tt> si no
-                      está disponible.
+[lock]                 coloca un lock alrededor de cada petición, procesando
+                       solamente una por proceso.
 
-[logging]             define si se utiliza el logger.
+                       Habilitá esta opción si tu aplicación no es thread-safe.
+                       Se encuentra deshabilitada por defecto.
 
-[lock]                coloca un lock alrededor de cada petición, procesando
-                      solamente una por proceso.
+[method_override]      utiliza el parámetro <tt>_method</tt> para permtir
+                       formularios put/delete en navegadores que no los
+                       soportan.
 
-                      Habilitá esta opción si tu aplicación no es thread-safe.
-                      Se encuentra deshabilitada por defecto.
+[port]                 puerto en el que escuchará el servidor integrado.
 
-[method_override]     utiliza el parámetro <tt>_method</tt> para permtir
-                      formularios put/delete en navegadores que no los soportan.
+[prefixed_redirects]   define si inserta <tt>request.script_name</tt> en las
+                       redirecciones cuando no se proporciona un path absoluto.
+                       De esta manera, cuando está habilitada,
+                       <tt>redirect '/foo'</tt> se comporta de la misma manera
+                       que <tt>redirect to('/foo')</tt>.  Se encuentra
+                       deshabilitada por defecto.
 
-[port]                puerto en el que escuchará el servidor integrado.
+[protection]           define si deben activarse las protecciones para los
+                       ataques web más comunes.  Para más detalles mirá la
+                       sección sobre la configuración de protección de ataques
+                       más arriba.
 
-[prefixed_redirects]  define si inserta <tt>request.script_name</tt> en las
-                      redirecciones cuando no se proporciona un path absoluto.
-                      De esta manera, cuando está habilitada,
-                      <tt>redirect '/foo'</tt> se comporta de la misma manera
-                      que <tt>redirect to('/foo')</tt>.  Se encuentra
-                      deshabilitada por defecto.
+[public_folder]        directorio desde donde se sirven los archivos públicos.
 
-[public]              directorio desde donde se sirven los archivos públicos.
+[reload_templates]     define si se recargan las plantillas entre peticiones.
 
-[reload_templates]    define si se recargan las plantillas entre peticiones.
+                       Se encuentra activado en el entorno de desarrollo.
 
-                      Se encuentra activado en el entorno de desarrollo.
+[root]                 directorio raíz del proyecto.
 
-[root]                directorio raíz del proyecto.
+[raise_errors]         elevar excepciones (detiene la aplicación).
 
-[raise_errors]        elevar excepciones (detiene la aplicación).
+[run]                  cuando está habilitada, Sinatra se va a encargar de
+                       iniciar el servidor web, no la habilités cuando estés
+                       usando rackup o algún otro medio.
 
-[run]                 cuando está habilitada, Sinatra se va a encargar de
-                      iniciar el servidor web, no la habilités cuando estés
-                      usando rackup o algún otro medio.
+[running]              indica si el servidor integrado está ejecutandose, ¡no
+                       cambiés esta configuración!.
 
-[running]             indica si el servidor integrado está ejecutandose, ¡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]              servidor, o lista de servidores, para usar como servidor
-                      integrado.  Por defecto: ['thin', 'mongrel', 'webrick'],
-                      el orden establece la prioridad.
+[sessions]             habilita sesiones basadas en cookies.
 
-[sessions]            habilita sesiones basadas en cookies.
+[show_exceptions]      muestra un stack trace en el navegador.
 
-[show_exceptions]     muestra un stack trace en el navegador.
+[static]               define si Sinatra debe encargarse de servir archivos
+                       estáticos.
 
-[static]              define si Sinatra debe encargarse de servir archivos
-                      estáticos.
+                       Deshabilitala cuando usés un servidor capaz de
+                       hacerlo por sí solo, porque mejorará el
+                       rendimiento.  Se encuentra habilitada por
+                       defecto en el estilo clásico y desactivado en el
+                       el modular.
 
-                      Deshabilitala cuando usés un servidor capaz de
-                      hacerlo por sí solo, porque mejorará el
-                      rendimiento.  Se encuentra habilitada por
-                      defecto en el estilo clásico y desactivado en el
-                      el modular.
+[static_cache_control] cuando Sinatra está sirviendo archivos estáticos, y
+                       está opción está habilitada, les va a agregar encabezados
+                       <tt>Cache-Control</tt> 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: 
+                       <tt>set :static_cache_control, [:public, :max_age => 300]</tt>.
 
-[views]               directorio de las vistas.
+[views]                directorio de las vistas.
 
 == Manejo de Errores
 
@@ -1565,6 +1718,7 @@ esto tenés <tt>Sinatra.new</tt>:
 Acepta como argumento opcional una aplicación desde la que se
 heredará:
 
+  # config.ru
   require 'sinatra/base'
 
   controller = Sinatra.new do
@@ -1701,7 +1855,14 @@ Las siguientes versiones de Ruby son soportadas oficialmente:
 
 [ Ruby 1.8.7 ]
   1.8.7 es soportado completamente.  Sin embargo, si no hay nada que te lo
-  prohíba, te recomendamos que usés 1.9.2 o cambies a JRuby o Rubinius.
+  prohíba, te recomendamos que usés 1.9.2 o cambies a JRuby o Rubinius.  No se
+  dejará de dar soporte a 1.8.7 hasta Sinatra 2.0 y Ruby 2.0, aunque si se
+  libera la versión 1.8.8 de Ruby las cosas podrían llegar a cambiar.  Sin
+  embargo, que eso ocurra es muy poco probable, e incluso el caso de que lo
+  haga, puede que se siga dando soporte a 1.8.7.  <b>Hemos dejado de soportar
+  Ruby 1.8.6.</b> Si querés ejecutar Sinatra sobre 1.8.6, podés utilizar la
+  versión 1.2, pero tené en cuenta que una vez que Sinatra 1.4.0 sea liberado,
+  ya no se corregirán errores por más que se reciban reportes de los mismos.
 
 [ Ruby 1.9.2 ]
   1.9.2 es soportado y recomendado.  Tené en cuenta que Radius y Markaby no
@@ -1709,11 +1870,11 @@ Las siguientes versiones de Ruby son soportadas oficialmente:
   fallos de segmentación cuando se ejecuta Sinatra.
 
 [ Rubinius ]
-  Rubinius es soportado oficialmente (Rubinius >= 1.2.3).  Todo
+  Rubinius es soportado oficialmente (Rubinius >= 1.2.4).  Todo
   funciona correctamente, incluyendo los lenguajes de plantillas.
 
 [ JRuby ]
-  JRuby es soportado oficialmente (JRuby >= 1.6.1).  No se conocen
+  JRuby es soportado oficialmente (JRuby >= 1.6.3).  No se conocen
   problemas con librerías de plantillas de terceras partes.  Sin
   embargo, si elegís usar JRuby, deberías examinar sus Rack handlers
   porque el servidor web Thin no es soportado completamente.  El
@@ -1721,32 +1882,31 @@ Las siguientes versiones de Ruby son soportadas oficialmente:
   experimental, sin embargo, de momento solamente RDiscount y Redcarpted
   se ven afectadas.
 
-<b>Hemos dejado de soportar Ruby 1.8.6.</b> Si querés ejecutar Sinatra sobre
-1.8.6, podés utilizar la versión 1.2, pero tené en cuenta que una vez que
-Sinatra 1.4.0 sea liberado, ya no se corregirán los reportes de errores que se
-reciban.
-
 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
+* Ruby 1.9.0 y 1.9.1 (pero no te recomendamos que los usés)
 
 No estar soportada oficialmente, significa que si las cosas solamente se rompen
 ahí y no en una plataforma soportada, asumimos que no es nuestro problema sino
 el suyo.
 
 Nuestro servidor CI también se ejecuta sobre ruby-head (que será la
-próxima versión 1.9.3).  Como está en movimiento constante, no podemos
-garantizar nada.  De todas formas, podés contar con que 1.9.3-p0 sea
+próxima versión 1.9.4).  Como está en movimiento constante, no podemos
+garantizar nada.  De todas formas, podés contar con que 1.9.4-p0 sea
 soportada.
 
 Sinatra debería funcionar en cualquier sistema operativo soportado por la
 implementación de Ruby elegida.
 
+En este momento, no vas a poder ejecutar Sinatra en Cardinal, SmallRuby,
+BlueRuby o cualquier versión de Ruby anterior a 1.8.7.
+
 == A la Vanguardia
 
 Si querés usar el código de Sinatra más reciente, sentite libre de ejecutar
@@ -1833,3 +1993,4 @@ siguiendo las especificaciones SemVer y SemVerTag.
   {última versión liberada}[http://rubydoc.info/gems/sinatra] o para la
   {rama de desarrollo actual}[http://rubydoc.info/github/sinatra/sinatra]
   en http://rubydoc.info/
+* {Servidor de IC}[http://ci.rkh.im/view/Sinatra/]