sinatra 1.4.8 → 2.0.0

data/README.md

@@ -1,5 +1,7 @@
 # Sinatra
 
+[![Build Status](https://secure.travis-ci.org/sinatra/sinatra.svg)](http://travis-ci.org/sinatra/sinatra)
+
 Sinatra is a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for
 quickly creating web applications in Ruby with minimal effort:
 
@@ -73,6 +75,9 @@ pick up if available.
     * [Filters](#filters)
     * [Helpers](#helpers)
         * [Using Sessions](#using-sessions)
+          * [Session Secret Security](#session-secret-security)
+          * [Session Config](#session-config)
+          * [Choosing Your Own Session Middleware](#choosing-your-own-session-middleware)
         * [Halting](#halting)
         * [Passing](#passing)
         * [Triggering Another Route](#triggering-another-route)
@@ -113,8 +118,6 @@ pick up if available.
     * [Requirement](#requirement)
     * [The Bleeding Edge](#the-bleeding-edge)
         * [With Bundler](#with-bundler)
-        * [Roll Your Own](#roll-your-own)
-        * [Install Globally](#install-globally)
     * [Versioning](#versioning)
     * [Further Reading](#further-reading)
 
@@ -160,6 +163,14 @@ end
 Routes are matched in the order they are defined. The first route that
 matches the request is invoked.
 
+Routes with trailing slashes are different from the ones without:
+
+```ruby
+get '/foo' do
+  # Does not match "GET /foo/"
+end
+```
+
 Route patterns may include named parameters, accessible via the
 `params` hash:
 
@@ -208,7 +219,7 @@ end
 Route matching with Regular Expressions:
 
 ```ruby
-get /\A\/hello\/([\w]+)\z/ do
+get /\/hello\/([\w]+)/ do
   "Hello, #{params['captures'].first}!"
 end
 ```
@@ -241,8 +252,23 @@ get '/posts' do
 end
 ```
 
-By the way, unless you disable the path traversal attack protection (see below),
-the request path might be modified before matching against your routes.
+By the way, unless you disable the path traversal attack protection (see
+below), the request path might be modified before matching against your
+routes.
+
+You may customize the Mustermann options used for a given route by passing in a
+`:mustermann_opts` hash:
+
+```ruby
+get '\A/posts\z', :mustermann_opts => { :type => :regexp, :check_anchors => false } do
+  # matches /posts exactly, with explicit anchoring
+  "If you match an anchored pattern clap your hands!"
+end
+```
+
+It looks like a [condition](#conditions), but it isn't one! These options will
+be merged into the global `:mustermann_opts` hash described
+[below](#available-settings).
 
 ## Conditions
 
@@ -311,10 +337,10 @@ end
 
 ## Return Values
 
-The return value of a route block determines at least the response body passed
-on to the HTTP client, or at least the next middleware in the Rack stack.
-Most commonly, this is a string, as in the above examples. But other values are
-also accepted.
+The return value of a route block determines at least the response body
+passed on to the HTTP client, or at least the next middleware in the
+Rack stack. Most commonly, this is a string, as in the above examples.
+But other values are also accepted.
 
 You can return any object that would either be a valid Rack response, Rack
 body object or HTTP status code:
@@ -339,14 +365,14 @@ end
 get('/') { Stream.new }
 ```
 
-You can also use the `stream` helper method (described below) to reduce boiler
-plate and embed the streaming logic in the route.
+You can also use the `stream` helper method (described below) to reduce
+boiler plate and embed the streaming logic in the route.
 
 ## Custom Route Matchers
 
-As shown above, Sinatra ships with built-in support for using String patterns
-and regular expressions as route matches. However, it does not stop there. You
-can easily define your own matchers:
+As shown above, Sinatra ships with built-in support for using String
+patterns and regular expressions as route matches. However, it does not
+stop there. You can easily define your own matchers:
 
 ```ruby
 class AllButPattern
@@ -384,7 +410,7 @@ end
 Or, using negative look ahead:
 
 ```ruby
-get %r{^(?!/index$)} do
+get %r{(?!/index)} do
   # ...
 end
 ```
@@ -494,15 +520,17 @@ Available Options:
 
   <dt>scope</dt>
   <dd>
-    Scope to render template under. Defaults to the application instance. If you
-    change this, instance variables and helper methods will not be available.
+    Scope to render template under. Defaults to the application
+    instance. If you change this, instance variables and helper methods
+    will not be available.
   </dd>
 
   <dt>layout_engine</dt>
   <dd>
-    Template engine to use for rendering the layout. Useful for languages that
-    do not support layouts otherwise. Defaults to the engine used for the
-    template. Example: <tt>set :rdoc, :layout_engine => :erb</tt>
+    Template engine to use for rendering the layout. Useful for
+    languages that do not support layouts otherwise. Defaults to the
+    engine used for the template. Example: <tt>set :rdoc, :layout_engine
+    => :erb</tt>
   </dd>
 
   <dt>layout_options</dt>
@@ -512,19 +540,19 @@ Available Options:
   </dd>
 </dl>
 
-Templates are assumed to be located directly under the `./views` directory. To
-use a different views directory:
+Templates are assumed to be located directly under the `./views`
+directory. To use a different views directory:
 
 ```ruby
 set :views, settings.root + '/templates'
 ```
 
 
-One important thing to remember is that you always have to reference templates
-with symbols, even if they're in a subdirectory (in this case, use:
-`:'subdir/template'` or `'subdir/template'.to_sym`). You must use a symbol
-because otherwise rendering methods will render any strings passed to them
-directly.
+One important thing to remember is that you always have to reference
+templates with symbols, even if they're in a subdirectory (in this case,
+use: `:'subdir/template'` or `'subdir/template'.to_sym`). You must use a
+symbol because otherwise rendering methods will render any strings
+passed to them directly.
 
 ### Literal Templates
 
@@ -534,7 +562,15 @@ get '/' do
 end
 ```
 
-Renders the template string.
+Renders the template string. You can optionally specify `:path` and
+`:line` for a clearer backtrace if there is a filesystem path or line
+associated with that string:
+
+```ruby
+get '/' do
+  haml '%div.title Hello World', :path => 'examples/file.haml', :line => 3
+end
+```
 
 ### Available Template Languages
 
@@ -718,7 +754,7 @@ template, you almost always want to pass locals to it.
   </tr>
 </table>
 
-It is not possible to call methods from markdown, nor to pass locals to it.
+It is not possible to call methods from Markdown, nor to pass locals to it.
 You therefore will usually use it in combination with another rendering
 engine:
 
@@ -726,7 +762,8 @@ engine:
 erb :overview, :locals => { :text => markdown(:introduction) }
 ```
 
-Note that you may also call the `markdown` method from within other templates:
+Note that you may also call the `markdown` method from within other
+templates:
 
 ```ruby
 %h1 Hello From Haml!
@@ -754,8 +791,9 @@ template than for the layout by passing the `:layout_engine` option.
   </tr>
 </table>
 
-It is not possible to call methods from textile, nor to pass locals to it. You
-therefore will usually use it in combination with another rendering engine:
+It is not possible to call methods from Textile, nor to pass locals to
+it. You therefore will usually use it in combination with another
+rendering engine:
 
 ```ruby
 erb :overview, :locals => { :text => textile(:introduction) }
@@ -789,7 +827,7 @@ template than for the layout by passing the `:layout_engine` option.
   </tr>
 </table>
 
-It is not possible to call methods from rdoc, nor to pass locals to it. You
+It is not possible to call methods from RDoc, nor to pass locals to it. You
 therefore will usually use it in combination with another rendering engine:
 
 ```ruby
@@ -844,8 +882,8 @@ almost always want to pass locals to it.
   </tr>
 </table>
 
-Since you cannot call Ruby methods directly from a Radius template, you almost
-always want to pass locals to it.
+Since you cannot call Ruby methods directly from a Radius template, you
+almost always want to pass locals to it.
 
 #### Markaby Templates
 
@@ -917,7 +955,7 @@ It also takes a block for inline templates (see example).
   </tr>
 </table>
 
-It is not possible to call methods from creole, nor to pass locals to it. You
+It is not possible to call methods from Creole, nor to pass locals to it. You
 therefore will usually use it in combination with another rendering engine:
 
 ```ruby
@@ -952,15 +990,16 @@ template than for the layout by passing the `:layout_engine` option.
   </tr>
 </table>
 
-It is not possible to call methods from MediaWiki markup, nor to pass locals to
-it. You therefore will usually use it in combination with another rendering
-engine:
+It is not possible to call methods from MediaWiki markup, nor to pass
+locals to it. You therefore will usually use it in combination with
+another rendering engine:
 
 ```ruby
 erb :overview, :locals => { :text => mediawiki(:introduction) }
 ```
 
-Note that you may also call the `mediawiki` method from within other templates:
+Note that you may also call the `mediawiki` method from within other
+templates:
 
 ```ruby
 %h1 Hello From Haml!
@@ -1090,8 +1129,9 @@ present(resource);
   </tr>
 </table>
 
-Since calling ruby methods is not idiomatic in WLang, you almost always want to
-pass locals to it. Layouts written in WLang and `yield` are supported, though.
+Since calling ruby methods is not idiomatic in WLang, you almost always
+want to pass locals to it. Layouts written in WLang and `yield` are
+supported, though.
 
 ### Accessing Variables in Templates
 
@@ -1131,7 +1171,8 @@ end
 
 This code is mostly equivalent to `erb :index, :layout => :post`.
 
-Passing blocks to rendering methods is most useful for creating nested layouts:
+Passing blocks to rendering methods is most useful for creating nested
+layouts:
 
 ```ruby
 erb :main_layout, :layout => false do
@@ -1254,8 +1295,8 @@ end
 
 ## Filters
 
-Before filters are evaluated before each request within the same
-context as the routes will be and can modify the request and response. Instance
+Before filters are evaluated before each request within the same context
+as the routes will be and can modify the request and response. Instance
 variables set in filters are accessible by routes and templates:
 
 ```ruby
@@ -1270,9 +1311,10 @@ get '/foo/*' do
 end
 ```
 
-After filters are evaluated after each request within the same context as the
-routes will be and can also modify the request and response. Instance variables
-set in before filters and routes are accessible by after filters:
+After filters are evaluated after each request within the same context
+as the routes will be and can also modify the request and response.
+Instance variables set in before filters and routes are accessible by
+after filters:
 
 ```ruby
 after do
@@ -1280,9 +1322,9 @@ after do
 end
 ```
 
-Note: Unless you use the `body` method rather than just returning a String from
-the routes, the body will not yet be available in the after filter, since it is
-generated later on.
+Note: Unless you use the `body` method rather than just returning a
+String from the routes, the body will not yet be available in the after
+filter, since it is generated later on.
 
 Filters optionally take a pattern, causing them to be evaluated only if the
 request path matches that pattern:
@@ -1359,35 +1401,83 @@ get '/:value' do
 end
 ```
 
-Note that `enable :sessions` actually stores all data in a cookie. This
-might not always be what you want (storing lots of data will increase your
-traffic, for instance). You can use any Rack session middleware: in order to
-do so, do **not** call `enable :sessions`, but instead pull in your
-middleware of choice as you would any other middleware:
+#### Session Secret Security
 
-```ruby
-use Rack::Session::Pool, :expire_after => 2592000
+To improve security, the session data in the cookie is signed with a session
+secret using `HMAC-SHA1`. This session secret should optimally be a
+cryptographically secure random value of an appropriate length which for
+`HMAC-SHA1` is greater than or equal to 64 bytes (512 bits, 128 hex
+characters). You would be advised not to use a secret that is less than 32
+bytes of randomness (256 bits, 64 hex characters). It is therefore **very
+important** that you don't just make the secret up, but instead use a secure
+random number generator to create it. Humans are extremely bad at generating
+random values.
 
-get '/' do
-  "value = " << session[:value].inspect
-end
+By default, a 32 byte secure random session secret is generated for you by
+Sinatra, but it will change with every restart of your application. If you
+have multiple instances of your application, and you let Sinatra generate the
+key, each instance would then have a different session key which is probably
+not what you want.
 
-get '/:value' do
-  session['value'] = params['value']
-end
+For better security and usability it's
+[recommended](https://12factor.net/config) that you generate a secure random
+secret and store it in an environment variable on each host running your
+application so that all of your application instances will share the same
+secret. You should periodically rotate this session secret to a new value.
+Here are some examples of how you might create a 64 byte secret and set it:
+
+**Session Secret Generation**
+
+```text
+$ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
+99ae8af...snip...ec0f262ac
 ```
 
-To improve security, the session data in the cookie is signed with a session
-secret. A random secret is generated for you by Sinatra. However, since this
-secret will change with every start of your application, you might want to
-set the secret yourself, so all your application instances share it:
+**Session Secret Generation (Bonus Points)**
+
+Use the [sysrandom gem](https://github.com/cryptosphere/sysrandom) to prefer
+use of system RNG facilities to generate random values instead of
+userspace `OpenSSL` which MRI Ruby currently defaults to:
+
+```text
+$ 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
+```
+
+**Session Secret Environment Variable**
+
+Set a `SESSION_SECRET` environment variable for Sinatra to the value you
+generated. Make this value persistent across reboots of your host. Since the
+method for doing this will vary across systems this is for illustrative
+purposes only:
+
+```bash
+# echo "export SESSION_SECRET=99ae8af...snip...ec0f262ac" >> ~/.bashrc
+```
+
+**Session Secret App Config**
+
+Setup your app config to fail-safe to a secure random secret
+if the `SESSION_SECRET` environment variable is not available.
+
+For bonus points use the [sysrandom
+gem](https://github.com/cryptosphere/sysrandom) here as well:
 
 ```ruby
-set :session_secret, 'super secret'
+require 'securerandom'
+# -or- require 'sysrandom/securerandom'
+set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }
 ```
 
-If you want to configure it further, you may also store a hash with options in
-the `sessions` setting:
+#### Session Config
+
+If you want to configure it further, you may also store a hash with options
+in the `sessions` setting:
 
 ```ruby
 set :sessions, :domain => 'foo.com'
@@ -1400,6 +1490,41 @@ domain with a *.* like this instead:
 set :sessions, :domain => '.foo.com'
 ```
 
+#### Choosing Your Own Session Middleware
+
+Note that `enable :sessions` actually stores all data in a cookie. This
+might not always be what you want (storing lots of data will increase your
+traffic, for instance). You can use any Rack session middleware in order to
+do so, one of the following methods can be used:
+
+```ruby
+enable :sessions
+set :session_store, Rack::Session::Pool
+```
+
+Or to set up sessions with a hash of options:
+
+```ruby
+set :sessions, :expire_after => 2592000
+set :session_store, Rack::Session::Pool
+```
+
+Another option is to **not** call `enable :sessions`, but instead pull in
+your middleware of choice as you would any other middleware.
+
+It is important to note that when using this method, session based
+protection **will not be enabled by default**.
+
+The Rack middleware to do that will also need to be added:
+
+```ruby
+use Rack::Session::Pool, :expire_after => 2592000
+use Rack::Protection::RemoteToken
+use Rack::Protection::SessionHijacking
+```
+
+See 'Configuring attack protection' for more information.
+
 ### Halting
 
 To immediately stop a request within a filter or route use:
@@ -1458,8 +1583,8 @@ matching route. If no matching route is found, a 404 is returned.
 
 ### Triggering Another Route
 
-Sometimes `pass` is not what you want, instead you would like to get the result
-of calling another route. Simply use `call` to achieve this:
+Sometimes `pass` is not what you want, instead you would like to get the
+result of calling another route. Simply use `call` to achieve this:
 
 ```ruby
 get '/foo' do
@@ -1472,21 +1597,22 @@ get '/bar' do
 end
 ```
 
-Note that in the example above, you would ease testing and increase performance
-by simply moving `"bar"` into a helper used by both `/foo` and `/bar`.
+Note that in the example above, you would ease testing and increase
+performance by simply moving `"bar"` into a helper used by both `/foo` and
+`/bar`.
 
-If you want the request to be sent to the same application instance rather than
-a duplicate, use `call!` instead of `call`.
+If you want the request to be sent to the same application instance rather
+than a duplicate, use `call!` instead of `call`.
 
 Check out the Rack specification if you want to learn more about `call`.
 
 ### Setting Body, Status Code and Headers
 
-It is possible and recommended to set the status code and response body with the
-return value of the route block. However, in some scenarios you might want to
-set the body at an arbitrary point in the execution flow. You can do so with the
-`body` helper method. If you do so, you can use that method from there on to
-access the body:
+It is possible and recommended to set the status code and response body with
+the return value of the route block. However, in some scenarios you might
+want to set the body at an arbitrary point in the execution flow. You can do
+so with the `body` helper method. If you do so, you can use that method from
+there on to access the body:
 
 ```ruby
 get '/foo' do
@@ -1537,15 +1663,15 @@ end
 
 This allows you to implement streaming APIs,
 [Server Sent Events](https://w3c.github.io/eventsource/), and can be used as
-the basis for [WebSockets](https://en.wikipedia.org/wiki/WebSocket). It can also be
-used to increase throughput if some but not all content depends on a slow
-resource.
+the basis for [WebSockets](https://en.wikipedia.org/wiki/WebSocket). It can
+also be used to increase throughput if some but not all content depends on a
+slow resource.
 
-Note that the streaming behavior, especially the number of concurrent requests,
-highly depends on the web server used to serve the application. Some servers
-might not even support streaming at all. If the server does not support
-streaming, the body will be sent all at once after the block passed to `stream`
-finishes executing. Streaming does not work at all with Shotgun.
+Note that the streaming behavior, especially the number of concurrent
+requests, highly depends on the web server used to serve the application.
+Some servers might not even support streaming at all. If the server does not
+support streaming, the body will be sent all at once after the block passed
+to `stream` finishes executing. Streaming does not work at all with Shotgun.
 
 If the optional parameter is set to `keep_open`, it will not call `close` on
 the stream object, allowing you to close it at any later point in the
@@ -1581,6 +1707,10 @@ post '/:message' do
 end
 ```
 
+It's also possible for the client to close the connection when trying to
+write to the socket. Because of this, it's recommended to check
+`out.closed?` before trying to write.
+
 ### Logging
 
 In the request scope, the `logger` helper exposes a `Logger` instance:
@@ -1596,8 +1726,8 @@ This logger will automatically take your Rack handler's logging settings into
 account. If logging is disabled, this method will return a dummy object, so
 you do not have to worry about it in your routes and filters.
 
-Note that logging is only enabled for `Sinatra::Application` by default, so if
-you inherit from `Sinatra::Base`, you probably want to enable it yourself:
+Note that logging is only enabled for `Sinatra::Application` by default, so
+if you inherit from `Sinatra::Base`, you probably want to enable it yourself:
 
 ```ruby
 class MyApp < Sinatra::Base
@@ -1749,8 +1879,9 @@ etag @article.sha1, :weak
 ```
 
 These helpers will not do any caching for you, but rather feed the necessary
-information to your cache. If you are looking for a quick reverse-proxy caching
-solution, try [rack-cache](https://github.com/rtomayko/rack-cache):
+information to your cache. If you are looking for a quick
+reverse-proxy caching solution, try
+[rack-cache](https://github.com/rtomayko/rack-cache):
 
 ```ruby
 require "rack/cache"
@@ -1768,12 +1899,13 @@ end
 Use the `:static_cache_control` setting (see below) to add
 `Cache-Control` header info to static files.
 
-According to RFC 2616, your application should behave differently if the If-Match
-or If-None-Match header is set to `*`, depending on whether the resource
-requested is already in existence. Sinatra assumes resources for safe (like get)
-and idempotent (like put) requests are already in existence, whereas other
-resources (for instance post requests) are treated as new resources. You
-can change this behavior by passing in a `:new_resource` option:
+According to RFC 2616, your application should behave differently if the
+If-Match or If-None-Match header is set to `*`, depending on whether the
+resource requested is already in existence. Sinatra assumes resources for
+safe (like get) and idempotent (like put) requests are already in existence,
+whereas other resources (for instance post requests) are treated as new
+resources. You can change this behavior by passing in a `:new_resource`
+option:
 
 ```ruby
 get '/create' do
@@ -1810,8 +1942,8 @@ The options are:
 
 <dl>
   <dt>filename</dt>
-    <dd>File name to be used in the response, defaults to the real file name.</dd>
-
+    <dd>File name to be used in the response,
+    defaults to the real file name.</dd>
   <dt>last_modified</dt>
     <dd>Value for Last-Modified header, defaults to the file's mtime.</dd>
 
@@ -1830,18 +1962,17 @@ The options are:
 
   <dt>status</dt>
     <dd>
-      Status code to be sent. Useful when sending a static file as an error page.
-
-      If supported by the Rack handler, other means than streaming from the Ruby
-      process will be used. If you use this helper method, Sinatra will
-      automatically handle range requests.
+      Status code to be sent. Useful when sending a static file as an error
+      page. If supported by the Rack handler, other means than streaming
+      from the Ruby process will be used. If you use this helper method,
+      Sinatra will automatically handle range requests.
     </dd>
 </dl>
 
 ### Accessing the Request Object
 
-The incoming request object can be accessed from request level (filter, routes,
-error handlers) through the `request` method:
+The incoming request object can be accessed from request level (filter,
+routes, error handlers) through the `request` method:
 
 ```ruby
 # app running on http://example.com/example
@@ -1898,8 +2029,8 @@ end
 
 ### Attachments
 
-You can use the `attachment` helper to tell the browser the response should be
-stored on disk rather than displayed in the browser:
+You can use the `attachment` helper to tell the browser the response should
+be stored on disk rather than displayed in the browser:
 
 ```ruby
 get '/' do
@@ -1919,19 +2050,20 @@ end
 
 ### Dealing with Date and Time
 
-Sinatra offers a `time_for` helper method that generates a Time object from the
-given value. It is also able to convert `DateTime`, `Date` and similar classes:
+Sinatra offers a `time_for` helper method that generates a Time object from
+the given value. It is also able to convert `DateTime`, `Date` and similar
+classes:
 
 ```ruby
 get '/' do
-  pass if Time.now > time_for('Dec 23, 2012')
+  pass if Time.now > time_for('Dec 23, 2016')
   "still time"
 end
 ```
 
-This method is used internally by `expires`, `last_modified` and akin. You can
-therefore easily extend the behavior of those methods by overriding `time_for`
-in your application:
+This method is used internally by `expires`, `last_modified` and akin. You
+can therefore easily extend the behavior of those methods by overriding
+`time_for` in your application:
 
 ```ruby
 helpers do
@@ -1961,9 +2093,9 @@ find_template settings.views, 'foo', Tilt[:haml] do |file|
 end
 ```
 
-This is not really useful. But it is useful that you can actually override this
-method to hook in your own lookup mechanism. For instance, if you want to be
-able to use more than one view directory:
+This is not really useful. But it is useful that you can actually override
+this method to hook in your own lookup mechanism. For instance, if you want
+to be able to use more than one view directory:
 
 ```ruby
 set :views, ['views', 'templates']
@@ -1992,11 +2124,11 @@ end
 You can also easily wrap this up in an extension and share with others!
 
 Note that `find_template` does not check if the file really exists but
-rather calls the given block for all possible paths. This is not a performance
-issue, since `render` will use `break` as soon as a file is found. Also,
-template locations (and content) will be cached if you are not running in
-development mode. You should keep that in mind if you write a really crazy
-method.
+rather calls the given block for all possible paths. This is not a
+performance issue, since `render` will use `break` as soon as a file is
+found. Also, template locations (and content) will be cached if you are not
+running in development mode. You should keep that in mind if you write a
+really crazy method.
 
 ## Configuration
 
@@ -2021,7 +2153,7 @@ configure do
 end
 ```
 
-Run only when the environment (`RACK_ENV` environment variable) is set to
+Run only when the environment (`APP_ENV` environment variable) is set to
 `:production`:
 
 ```ruby
@@ -2055,10 +2187,10 @@ end
 ### Configuring attack protection
 
 Sinatra is using
-[Rack::Protection](https://github.com/sinatra/rack-protection#readme) to defend
-your application against common, opportunistic attacks. You can easily disable
-this behavior (which will open up your application to tons of common
-vulnerabilities):
+[Rack::Protection](https://github.com/sinatra/rack-protection#readme) to
+defend your application against common, opportunistic attacks. You can
+easily disable this behavior (which will open up your application to tons
+of common vulnerabilities):
 
 ```ruby
 disable :protection
@@ -2076,12 +2208,12 @@ set :protection, :except => [:path_traversal, :session_hijacking]
 ```
 
 By default, Sinatra will only set up session based protection if `:sessions`
-has been enabled. Sometimes you want to set up sessions on your own, though. In
-that case you can get it to set up session based protections by passing the
-`:session` option:
+have been enabled. See 'Using Sessions'. Sometimes you may want to set up
+sessions "outside" of the Sinatra app, such as in the config.ru or with a
+separate `Rack::Builder` instance. In that case you can still set up session
+based protection by passing the `:session` option:
 
 ```ruby
-use Rack::Session::Pool
 set :protection, :session => true
 ```
 
@@ -2089,191 +2221,218 @@ set :protection, :session => true
 
 <dl>
   <dt>absolute_redirects</dt>
-  <dd>
-    If disabled, Sinatra will allow relative redirects, however, Sinatra will no
-    longer conform with RFC 2616 (HTTP 1.1), which only allows absolute redirects.
-  </dd>
-  <dd>
-    Enable if your app is running behind a reverse proxy that has not been set up
-    properly. Note that the <tt>url</tt> helper will still produce absolute URLs, unless you
-    pass in <tt>false</tt> as the second parameter.
-  </dd>
-  <dd>Disabled by default.</dd>
+    <dd>
+      If disabled, Sinatra will allow relative redirects, however, Sinatra
+      will no longer conform with RFC 2616 (HTTP 1.1), which only allows
+      absolute redirects.
+    </dd>
+    <dd>
+      Enable if your app is running behind a reverse proxy that has not been
+      set up properly. Note that the <tt>url</tt> helper will still produce
+      absolute URLs, unless you pass in <tt>false</tt> as the second
+      parameter.
+    </dd>
+    <dd>Disabled by default.</dd>
 
   <dt>add_charset</dt>
-  <dd>
-    Mime types the <tt>content_type</tt> helper will automatically add the charset info to.
-    You should add to it rather than overriding this option:
-    <tt>settings.add_charset << "application/foobar"</tt>
-  </dd>
+    <dd>
+      Mime types the <tt>content_type</tt> helper will automatically add the
+      charset info to. You should add to it rather than overriding this
+      option: <tt>settings.add_charset << "application/foobar"</tt>
+    </dd>
 
   <dt>app_file</dt>
-  <dd>
-    Path to the main application file, used to detect project root, views and public
-    folder and inline templates.
-  </dd>
+    <dd>
+      Path to the main application file, used to detect project root, views
+      and public folder and inline templates.
+    </dd>
 
   <dt>bind</dt>
-  <dd>IP address to bind to (default: <tt>0.0.0.0</tt> <em>or</em>
-  <tt>localhost</tt> if your `environment` is set to development). Only used
-  for built-in server.</dd>
+    <dd>
+      IP address to bind to (default: <tt>0.0.0.0</tt> <em>or</em>
+      <tt>localhost</tt> if your `environment` is set to development). Only
+      used for built-in server.
+    </dd>
 
   <dt>default_encoding</dt>
-  <dd>Encoding to assume if unknown (defaults to <tt>"utf-8"</tt>).</dd>
+    <dd>Encoding to assume if unknown (defaults to <tt>"utf-8"</tt>).</dd>
 
   <dt>dump_errors</dt>
-  <dd>Display errors in the log.</dd>
+    <dd>Display errors in the log.</dd>
 
   <dt>environment</dt>
-  <dd>
-    Current environment. Defaults to <tt>ENV['RACK_ENV']</tt>, or
-    <tt>"development"</tt> if not available.
-  </dd>
+    <dd>
+      Current environment. Defaults to <tt>ENV['APP_ENV']</tt>, or
+      <tt>"development"</tt> if not available.
+    </dd>
 
   <dt>logging</dt>
-  <dd>Use the logger.</dd>
+    <dd>Use the logger.</dd>
 
   <dt>lock</dt>
-  <dd>
-    Places a lock around every request, only running processing on request
-    per Ruby process concurrently.
-  </dd>
-  <dd>Enabled if your app is not thread-safe. Disabled by default.</dd>
+    <dd>
+      Places a lock around every request, only running processing on request
+      per Ruby process concurrently.
+    </dd>
+    <dd>Enabled if your app is not thread-safe. Disabled by default.</dd>
 
   <dt>method_override</dt>
+    <dd>
+      Use <tt>_method</tt> magic to allow put/delete forms in browsers that
+      don't support it.
+    </dd>
+
+  <dt>mustermann_opts</dt>
   <dd>
-    Use <tt>_method</tt> magic to allow put/delete forms in browsers that
-    don't support it.
+    A default hash of options to pass to Mustermann.new when compiling routing
+    paths.
   </dd>
 
   <dt>port</dt>
-  <dd>Port to listen on. Only used for built-in server.</dd>
+    <dd>Port to listen on. Only used for built-in server.</dd>
 
   <dt>prefixed_redirects</dt>
-  <dd>
-    Whether or not to insert <tt>request.script_name</tt> into redirects if no
-    absolute path is given. That way <tt>redirect '/foo'</tt> would behave like
-    <tt>redirect to('/foo')</tt>. Disabled by default.
-  </dd>
+    <dd>
+      Whether or not to insert <tt>request.script_name</tt> into redirects
+      if no absolute path is given. That way <tt>redirect '/foo'</tt> would
+        behave like <tt>redirect to('/foo')</tt>. Disabled by default.
+    </dd>
 
   <dt>protection</dt>
-  <dd>Whether or not to enable web attack protections. See protection section
-  above.</dd>
+    <dd>
+      Whether or not to enable web attack protections. See protection section
+      above.
+    </dd>
 
   <dt>public_dir</dt>
-  <dd>Alias for <tt>public_folder</tt>. See below.</dd>
+    <dd>Alias for <tt>public_folder</tt>. See below.</dd>
 
   <dt>public_folder</dt>
-  <dd>
-    Path to the folder public files are served from. Only used if static
-    file serving is enabled (see <tt>static</tt> setting below). Inferred from
-    <tt>app_file</tt> setting if not set.
-  </dd>
+    <dd>
+      Path to the folder public files are served from. Only used if static
+      file serving is enabled (see <tt>static</tt> setting below). Inferred
+      from <tt>app_file</tt> setting if not set.
+    </dd>
+
+  <dt>quiet</dt>
+    <dd>
+      Disables logs generated by Sinatra's start and stop commands.
+      <tt>false</tt> by default.
+    </dd>
 
   <dt>reload_templates</dt>
-  <dd>
-    Whether or not to reload templates between requests. Enabled in development
-    mode.
-  </dd>
+    <dd>
+      Whether or not to reload templates between requests. Enabled in
+      development mode.
+    </dd>
 
   <dt>root</dt>
-  <dd>
-    Path to project root folder. Inferred from <tt>app_file</tt> setting if not
-    set.
-  </dd>
+    <dd>
+      Path to project root folder. Inferred from <tt>app_file</tt> setting
+      if not set.
+    </dd>
 
   <dt>raise_errors</dt>
-  <dd>
-    Raise exceptions (will stop application). Enabled by default when
-    <tt>environment</tt> is set to <tt>"test"</tt>, disabled otherwise.
-  </dd>
+    <dd>
+      Raise exceptions (will stop application). Enabled by default when
+      <tt>environment</tt> is set to <tt>"test"</tt>, disabled otherwise.
+    </dd>
 
   <dt>run</dt>
-  <dd>
-    If enabled, Sinatra will handle starting the web server. Do not
-    enable if using rackup or other means.
-  </dd>
+    <dd>
+      If enabled, Sinatra will handle starting the web server. Do not
+      enable if using rackup or other means.
+    </dd>
 
   <dt>running</dt>
-  <dd>Is the built-in server running now? Do not change this setting!</dd>
+    <dd>Is the built-in server running now? Do not change this setting!</dd>
 
   <dt>server</dt>
-  <dd>
-    Server or list of servers to use for built-in server. Order indicates
-    priority, default depends on Ruby implementation.
-  </dd>
+    <dd>
+      Server or list of servers to use for built-in server. Order indicates
+      priority, default depends on Ruby implementation.
+    </dd>
 
   <dt>sessions</dt>
-  <dd>
-    Enable cookie-based sessions support using <tt>Rack::Session::Cookie</tt>.
-    See 'Using Sessions' section for more information.
-  </dd>
+    <dd>
+      Enable cookie-based sessions support using
+      <tt>Rack::Session::Cookie</tt>. See 'Using Sessions' section for more
+      information.
+    </dd>
+
+  <dt>session_store</dt>
+    <dd>
+      The Rack session middleware used. Defaults to
+      <tt>Rack::Session::Cookie</tt>. See 'Using Sessions' section for more
+      information.
+    </dd>
 
   <dt>show_exceptions</dt>
-  <dd>
-    Show a stack trace in the browser when an exception happens. Enabled by
-    default when <tt>environment</tt> is set to <tt>"development"</tt>,
-    disabled otherwise.
-  </dd>
-  <dd>
-    Can also be set to <tt>:after_handler</tt> to trigger app-specified error
-    handling before showing a stack trace in the browser.
-  </dd>
+    <dd>
+      Show a stack trace in the browser when an exception happens. Enabled by
+      default when <tt>environment</tt> is set to <tt>"development"</tt>,
+      disabled otherwise.
+    </dd>
+    <dd>
+      Can also be set to <tt>:after_handler</tt> to trigger app-specified
+      error handling before showing a stack trace in the browser.
+    </dd>
 
   <dt>static</dt>
-  <dd>Whether Sinatra should handle serving static files.</dd>
-  <dd>Disable when using a server able to do this on its own.</dd>
-  <dd>Disabling will boost performance.</dd>
-  <dd>
-    Enabled by default in classic style, disabled for modular apps.
-  </dd>
+    <dd>Whether Sinatra should handle serving static files.</dd>
+    <dd>Disable when using a server able to do this on its own.</dd>
+    <dd>Disabling will boost performance.</dd>
+    <dd>
+      Enabled by default in classic style, disabled for modular apps.
+    </dd>
 
   <dt>static_cache_control</dt>
-  <dd>
-    When Sinatra is serving static files, set this to add <tt>Cache-Control</tt>
-    headers to the responses. Uses the <tt>cache_control</tt> helper. Disabled
-    by default.
-  </dd>
-  <dd>
-    Use an explicit array when setting multiple values:
-    <tt>set :static_cache_control, [:public, :max_age => 300]</tt>
-  </dd>
+    <dd>
+      When Sinatra is serving static files, set this to add
+      <tt>Cache-Control</tt> headers to the responses. Uses the
+      <tt>cache_control</tt> helper. Disabled by default.
+    </dd>
+    <dd>
+      Use an explicit array when setting multiple values:
+      <tt>set :static_cache_control, [:public, :max_age => 300]</tt>
+    </dd>
 
   <dt>threaded</dt>
-  <dd>
-    If set to <tt>true</tt>, will tell Thin to use <tt>EventMachine.defer</tt>
-    for processing the request.
-  </dd>
+    <dd>
+      If set to <tt>true</tt>, will tell Thin to use
+      <tt>EventMachine.defer</tt> for processing the request.
+    </dd>
 
   <dt>traps</dt>
-  <dd>Whether Sinatra should handle system signals.</dd>
+    <dd>Whether Sinatra should handle system signals.</dd>
 
   <dt>views</dt>
-  <dd>
-    Path to the views folder. Inferred from <tt>app_file</tt> setting if
-    not set.
-  </dd>
+    <dd>
+      Path to the views folder. Inferred from <tt>app_file</tt> setting if
+      not set.
+    </dd>
 
   <dt>x_cascade</dt>
-  <dd>
-    Whether or not to set the X-Cascade header if no route matches.
-    Defaults to <tt>true</tt>.
-  </dd>
+    <dd>
+      Whether or not to set the X-Cascade header if no route matches.
+      Defaults to <tt>true</tt>.
+    </dd>
 </dl>
 
 ## Environments
 
-There are three predefined `environments`: `"development"`, `"production"` and
-`"test"`. Environments can be set through the `RACK_ENV` environment variable.
-The default value is `"development"`. In the `"development"` environment all
-templates are reloaded between requests, and special `not_found` and `error`
-handlers display stack traces in your browser. In the `"production"` and
-`"test"` environments, templates are cached by default.
+There are three predefined `environments`: `"development"`,
+`"production"` and `"test"`. Environments can be set through the
+`APP_ENV` environment variable. The default value is `"development"`.
+In the `"development"` environment all templates are reloaded between
+requests, and special `not_found` and `error` handlers display stack
+traces in your browser. In the `"production"` and `"test"` environments,
+templates are cached by default.
 
-To run different environments, set the `RACK_ENV` environment variable:
+To run different environments, set the `APP_ENV` environment variable:
 
 ```shell
-RACK_ENV=production ruby my_app.rb
+APP_ENV=production ruby my_app.rb
 ```
 
 You can use predefined methods: `development?`, `test?` and `production?` to
@@ -2291,9 +2450,9 @@ end
 
 ## Error Handling
 
-Error handlers run within the same context as routes and before filters, which
-means you get all the goodies it has to offer, like `haml`,
-`erb`, `halt`, etc.
+Error handlers run within the same context as routes and before filters,
+which means you get all the goodies it has to offer, like `haml`, `erb`,
+`halt`, etc.
 
 ### Not Found
 
@@ -2373,10 +2532,11 @@ and additional debugging information in your browser.
 ## Rack Middleware
 
 Sinatra rides on [Rack](http://rack.github.io/), a minimal standard
-interface for Ruby web frameworks. One of Rack's most interesting capabilities
-for application developers is support for "middleware" -- components that sit
-between the server and your application monitoring and/or manipulating the
-HTTP request/response to provide various types of common functionality.
+interface for Ruby web frameworks. One of Rack's most interesting
+capabilities for application developers is support for "middleware" --
+components that sit between the server and your application monitoring
+and/or manipulating the HTTP request/response to provide various types
+of common functionality.
 
 Sinatra makes building Rack middleware pipelines a cinch via a top-level
 `use` method:
@@ -2416,7 +2576,8 @@ or in the [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
 
 ## Testing
 
-Sinatra tests can be written using any Rack-based testing library or framework.
+Sinatra tests can be written using any Rack-based testing library or
+framework.
 [Rack::Test](http://www.rubydoc.info/github/brynary/rack-test/master/frames)
 is recommended:
 
@@ -2442,7 +2603,7 @@ class MyAppTest < Minitest::Test
     assert_equal 'Hello Frank!', last_response.body
   end
 
-  def test_with_rack_env
+  def test_with_user_agent
     get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
     assert_equal "You're using Songbird!", last_response.body
   end
@@ -2475,9 +2636,9 @@ class MyApp < Sinatra::Base
 end
 ```
 
-The methods available to `Sinatra::Base` subclasses are exactly the same as
-those available via the top-level DSL. Most top-level apps can be converted to
-`Sinatra::Base` components with two modifications:
+The methods available to `Sinatra::Base` subclasses are exactly the same
+as those available via the top-level DSL. Most top-level apps can be
+converted to `Sinatra::Base` components with two modifications:
 
 * Your file should require `sinatra/base` instead of `sinatra`;
   otherwise, all of Sinatra's DSL methods are imported into the main
@@ -2486,12 +2647,11 @@ those available via the top-level DSL. Most top-level apps can be converted to
   of `Sinatra::Base`.
 
 `Sinatra::Base` is a blank slate. Most options are disabled by default,
-including the built-in server. See
-[Configuring Settings](http://www.sinatrarb.com/configuration.html)
-for details on available options and their behavior. If you want
-behavior more similar to when you define your app at the top level (also
-known as Classic style), you
-can subclass `Sinatra::Application`.
+including the built-in server. See [Configuring
+Settings](http://www.sinatrarb.com/configuration.html) for details on
+available options and their behavior. If you want behavior more similar
+to when you define your app at the top level (also known as Classic
+style), you can subclass `Sinatra::Application`:
 
 ```ruby
 require 'sinatra/base'
@@ -2505,16 +2665,17 @@ end
 
 ### Modular vs. Classic Style
 
-Contrary to common belief, there is nothing wrong with the classic style. If it
-suits your application, you do not have to switch to a modular application.
+Contrary to common belief, there is nothing wrong with the classic
+style. If it suits your application, you do not have to switch to a
+modular application.
 
-The main disadvantage of using the classic style rather than the modular style
-is that you will only have one Sinatra application per Ruby process. If you
-plan to use more than one, switch to the modular style. There is no reason you
-cannot mix the modular and the classic styles.
+The main disadvantage of using the classic style rather than the modular
+style is that you will only have one Sinatra application per Ruby
+process. If you plan to use more than one, switch to the modular style.
+There is no reason you cannot mix the modular and the classic styles.
 
-If switching from one style to the other, you should be aware of slightly
-different default settings:
+If switching from one style to the other, you should be aware of
+slightly different default settings:
 
 <table>
   <tr>
@@ -2569,8 +2730,8 @@ different default settings:
 
 ### Serving a Modular Application
 
-There are two common options for starting a modular app, actively starting with
-`run!`:
+There are two common options for starting a modular app, actively
+starting with `run!`:
 
 ```ruby
 # my_app.rb
@@ -2633,16 +2794,16 @@ A `config.ru` file is recommended if:
 * You want to use more than one subclass of `Sinatra::Base`.
 * You want to use Sinatra only for middleware, and not as an endpoint.
 
-**There is no need to switch to a `config.ru` simply because you switched to
-the modular style, and you don't have to use the modular style for running with
-a `config.ru`.**
+**There is no need to switch to a `config.ru` simply because you
+switched to the modular style, and you don't have to use the modular
+style for running with a `config.ru`.**
 
 ### Using Sinatra as Middleware
 
-Not only is Sinatra able to use other Rack middleware, any Sinatra application
-can in turn be added in front of any Rack endpoint as middleware itself. This
-endpoint could be another Sinatra application, or any other Rack-based
-application (Rails/Ramaze/Camping/...):
+Not only is Sinatra able to use other Rack middleware, any Sinatra
+application can in turn be added in front of any Rack endpoint as
+middleware itself. This endpoint could be another Sinatra application,
+or any other Rack-based application (Rails/Hanami/Roda/...):
 
 ```ruby
 require 'sinatra/base'
@@ -2731,9 +2892,9 @@ available.
 Every Sinatra application corresponds to a subclass of `Sinatra::Base`.
 If you are using the top-level DSL (`require 'sinatra'`), then this
 class is `Sinatra::Application`, otherwise it is the subclass you
-created explicitly. At class level you have methods like `get` or `before`, but
-you cannot access the `request` or `session` objects, as there is only a
-single application class for all requests.
+created explicitly. At class level you have methods like `get` or
+`before`, but you cannot access the `request` or `session` objects, as
+there is only a single application class for all requests.
 
 Options created via `set` are methods at class level:
 
@@ -2817,7 +2978,7 @@ being [extending the main object](https://github.com/sinatra/sinatra/blob/ca0636
 Sinatra applications can be run directly:
 
 ```shell
-ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]
+ruby myapp.rb [-h] [-x] [-q] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]
 ```
 
 Options are:
@@ -2828,6 +2989,7 @@ Options are:
 -o # set the host (default is 0.0.0.0)
 -e # set the environment (default is development)
 -s # specify rack server/handler (default is thin)
+-q # turn on quiet mode for server (default is off)
 -x # turn on the mutex lock (default is off)
 ```
 
@@ -2871,31 +3033,10 @@ thin --threaded start
 
 The following Ruby versions are officially supported:
 <dl>
-  <dt>Ruby 1.8.7</dt>
-  <dd>
-    1.8.7 is fully supported, however, if nothing is keeping you from it, we
-    recommend upgrading or switching to JRuby or Rubinius. Support for 1.8.7
-    will not be dropped before Sinatra 2.0. Ruby 1.8.6 is no longer supported.
-  </dd>
-
-  <dt>Ruby 1.9.2</dt>
+  <dt>Ruby 2.2</dt>
   <dd>
-    1.9.2 is fully supported. Do not use 1.9.2p0, as it is known to cause
-    segmentation faults when running Sinatra. Official support will continue
-    at least until the release of Sinatra 1.5.
-  </dd>
-
-  <dt>Ruby 1.9.3</dt>
-  <dd>
-    1.9.3 is fully supported and recommended. Please note that switching to 1.9.3
-    from an earlier version will invalidate all sessions. 1.9.3 will be supported
-    until the release of Sinatra 2.0.
-  </dd>
-
-  <dt>Ruby 2.x</dt>
-  <dd>
-    2.x is fully supported and recommended. There are currently no plans to drop
-    official support for it.
+    2.2 is fully supported and recommended. There are currently no plans to
+    drop official support for it.
   </dd>
 
   <dt>Rubinius</dt>
@@ -2912,6 +3053,8 @@ The following Ruby versions are officially supported:
   </dd>
 </dl>
 
+Versions of Ruby prior to 2.2.2 are no longer supported as of Sinatra 2.0.
+
 We also keep an eye on upcoming Ruby versions.
 
 The following Ruby implementations are not officially supported but still are
@@ -2925,9 +3068,9 @@ known to run Sinatra:
 Not being officially supported means if things only break there and not on a
 supported platform, we assume it's not our issue but theirs.
 
-We also run our CI against ruby-head (future releases of MRI), but we can't
-guarantee anything, since it is constantly moving. Expect upcoming 2.x releases
-to be fully supported.
+We also run our CI against ruby-head (future releases of MRI), but we
+can't guarantee anything, since it is constantly moving. Expect upcoming
+2.x releases to be fully supported.
 
 Sinatra should work on any operating system supported by the chosen Ruby
 implementation.
@@ -2935,12 +3078,13 @@ implementation.
 If you run MacRuby, you should `gem install control_tower`.
 
 Sinatra currently doesn't run on Cardinal, SmallRuby, BlueRuby or any
-Ruby version prior to 1.8.7.
+Ruby version prior to 2.2.
 
 ## The Bleeding Edge
 
-If you would like to use Sinatra's latest bleeding-edge code, feel free to run your
-application against the master branch, it should be rather stable.
+If you would like to use Sinatra's latest bleeding-edge code, feel free
+to run your application against the master branch, it should be rather
+stable.
 
 We also push out prerelease gems from time to time, so you can do a
 
@@ -2965,16 +3109,15 @@ Then, in your project directory, create a `Gemfile`:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'sinatra', :github => "sinatra/sinatra"
+gem 'sinatra', :github => 'sinatra/sinatra'
 
 # other dependencies
 gem 'haml'                    # for instance, if you use haml
-gem 'activerecord', '~> 3.0'  # maybe you also need ActiveRecord 3.x
 ```
 
-Note that you will have to list all your application's dependencies in the `Gemfile`.
-Sinatra's direct dependencies (Rack and Tilt) will, however, be automatically
-fetched and added by Bundler.
+Note that you will have to list all your application's dependencies in
+the `Gemfile`. Sinatra's direct dependencies (Rack and Tilt) will,
+however, be automatically fetched and added by Bundler.
 
 Now you can run your app like this:
 
@@ -2982,41 +3125,6 @@ Now you can run your app like this:
 bundle exec ruby myapp.rb
 ```
 
-### Roll Your Own
-
-Create a local clone and run your app with the `sinatra/lib` directory
-on the `$LOAD_PATH`:
-
-```shell
-cd myapp
-git clone git://github.com/sinatra/sinatra.git
-ruby -I sinatra/lib myapp.rb
-```
-
-To update the Sinatra sources in the future:
-
-```shell
-cd myapp/sinatra
-git pull
-```
-
-### Install Globally
-
-You can build the gem on your own:
-
-```shell
-git clone git://github.com/sinatra/sinatra.git
-cd sinatra
-rake sinatra.gemspec
-rake install
-```
-
-If you install gems as root, the last step should be:
-
-```shell
-sudo rake install
-```
-
 ## Versioning
 
 Sinatra follows [Semantic Versioning](http://semver.org/), both SemVer and