sinatra 2.0.0 → 2.0.1

data/README.md

@@ -1,6 +1,6 @@
 # Sinatra
 
-[![Build Status](https://secure.travis-ci.org/sinatra/sinatra.svg)](http://travis-ci.org/sinatra/sinatra)
+[![Build Status](https://secure.travis-ci.org/sinatra/sinatra.svg)](https://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:
@@ -28,6 +28,10 @@ ruby myapp.rb
 
 View at: [http://localhost:4567](http://localhost:4567)
 
+The code you changed will not take effect until you restart the server.
+Please restart the server every time you change or use
+[sinatra/reloader](http://www.sinatrarb.com/contrib/reloader).
+
 It is recommended to also run `gem install thin`, which Sinatra will
 pick up if available.
 
@@ -75,9 +79,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)
+            * [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)
@@ -253,11 +257,11 @@ 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.
+[below](#configuring-attack-protection)), 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:
+You may customize the [Mustermann](https://github.com/sinatra/mustermann#readme)
+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
@@ -365,7 +369,7 @@ end
 get('/') { Stream.new }
 ```
 
-You can also use the `stream` helper method (described below) to reduce
+You can also use the `stream` helper method ([described below](#streaming-responses)) to reduce
 boiler plate and embed the streaming logic in the route.
 
 ## Custom Route Matchers
@@ -428,7 +432,7 @@ Note that the public directory name is not included in the URL. A file
 `./public/css/style.css` is made available as
 `http://example.com/css/style.css`.
 
-Use the `:static_cache_control` setting (see below) to add
+Use the `:static_cache_control` setting (see [below](#cache-control)) to add
 `Cache-Control` header info.
 
 ## Views / Templates
@@ -638,7 +642,7 @@ get('/') { markdown :index }
   </tr>
 </table>
 
-It also takes a block for inline templates (see example).
+It also takes a block for inline templates (see [example](#inline-templates)).
 
 #### Nokogiri Templates
 
@@ -657,14 +661,14 @@ It also takes a block for inline templates (see example).
   </tr>
 </table>
 
-It also takes a block for inline templates (see example).
+It also takes a block for inline templates (see [example](#inline-templates)).
 
 #### Sass Templates
 
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="http://sass-lang.com/" title="sass">sass</a></td>
+    <td><a href="https://sass-lang.com/" title="sass">sass</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -681,7 +685,7 @@ It also takes a block for inline templates (see example).
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="http://sass-lang.com/" title="sass">sass</a></td>
+    <td><a href="https://sass-lang.com/" title="sass">sass</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -739,8 +743,8 @@ template, you almost always want to pass locals to it.
       Anyone of:
         <a href="https://github.com/davidfstr/rdiscount" title="RDiscount">RDiscount</a>,
         <a href="https://github.com/vmg/redcarpet" title="RedCarpet">RedCarpet</a>,
-        <a href="http://deveiate.org/projects/BlueCloth" title="BlueCloth">BlueCloth</a>,
-        <a href="http://kramdown.gettalong.org/" title="kramdown">kramdown</a>,
+        <a href="https://github.com/ged/bluecloth" title="BlueCloth">BlueCloth</a>,
+        <a href="https://kramdown.gettalong.org/" title="kramdown">kramdown</a>,
         <a href="https://github.com/bhollis/maruku" title="maruku">maruku</a>
     </td>
   </tr>
@@ -890,7 +894,7 @@ almost always want to pass locals to it.
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="http://markaby.github.io/" title="Markaby">Markaby</a></td>
+    <td><a href="https://markaby.github.io/" title="Markaby">Markaby</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -902,7 +906,7 @@ almost always want to pass locals to it.
   </tr>
 </table>
 
-It also takes a block for inline templates (see example).
+It also takes a block for inline templates (see [example](#inline-templates)).
 
 #### RABL Templates
 
@@ -1019,7 +1023,7 @@ template than for the layout by passing the `:layout_engine` option.
       <a href="https://github.com/josh/ruby-coffee-script" title="Ruby CoffeeScript">
         CoffeeScript
       </a> and a
-      <a href="https://github.com/sstephenson/execjs/blob/master/README.md#readme" title="ExecJS">
+      <a href="https://github.com/sstephenson/execjs" title="ExecJS">
         way to execute javascript
       </a>
     </td>
@@ -1043,7 +1047,7 @@ template than for the layout by passing the `:layout_engine` option.
       <a href="https://github.com/forgecrafted/ruby-stylus" title="Ruby Stylus">
         Stylus
       </a> and a
-      <a href="https://github.com/sstephenson/execjs/blob/master/README.md#readme" title="ExecJS">
+      <a href="https://github.com/sstephenson/execjs" title="ExecJS">
         way to execute javascript
       </a>
     </td>
@@ -1117,7 +1121,7 @@ present(resource);
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="https://github.com/blambeau/wlang/" title="WLang">WLang</a></td>
+    <td><a href="https://github.com/blambeau/wlang" title="WLang">WLang</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -1273,8 +1277,8 @@ get '/' do
 end
 ```
 
-Renders `./views/index.myat`. See https://github.com/rtomayko/tilt to
-learn more about Tilt.
+Renders `./views/index.myat`. Learn more about
+[Tilt](https://github.com/rtomayko/tilt#readme).
 
 ### Using Custom Logic for Template Lookup
 
@@ -1435,8 +1439,8 @@ $ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
 
 **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
+Use the [sysrandom gem](https://github.com/cryptosphere/sysrandom#readme) to
+prefer use of system RNG facilities to generate random values instead of
 userspace `OpenSSL` which MRI Ruby currently defaults to:
 
 ```text
@@ -1466,7 +1470,7 @@ 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:
+gem](https://github.com/cryptosphere/sysrandom#readme) here as well:
 
 ```ruby
 require 'securerandom'
@@ -1523,7 +1527,7 @@ use Rack::Protection::RemoteToken
 use Rack::Protection::SessionHijacking
 ```
 
-See 'Configuring attack protection' for more information.
+See '[Configuring attack protection](#configuring-attack-protection)' for more information.
 
 ### Halting
 
@@ -1625,7 +1629,7 @@ end
 ```
 
 It is also possible to pass a block to `body`, which will be executed by the
-Rack handler (this can be used to implement streaming, see "Return Values").
+Rack handler (this can be used to implement streaming, [see "Return Values"](#return-values)).
 
 Similar to the body, you can also set the status code and headers:
 
@@ -1634,7 +1638,7 @@ get '/foo' do
   status 418
   headers \
     "Allow"   => "BREW, POST, GET, PROPFIND, WHEN",
-    "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
+    "Refresh" => "Refresh: 20; https://ietf.org/rfc/rfc2324.txt"
   body "I'm a tea pot!"
 end
 ```
@@ -1773,7 +1777,7 @@ Haml:
 
 It takes reverse proxies and Rack routers into account, if present.
 
-This method is also aliased to `to` (see below for an example).
+This method is also aliased to `to` (see [below](#browser-redirect) for an example).
 
 ### Browser Redirect
 
@@ -1881,7 +1885,7 @@ 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):
+[rack-cache](https://github.com/rtomayko/rack-cache#readme):
 
 ```ruby
 require "rack/cache"
@@ -1896,7 +1900,7 @@ get '/' do
 end
 ```
 
-Use the `:static_cache_control` setting (see below) to add
+Use the `:static_cache_control` setting (see [below](#cache-control)) to add
 `Cache-Control` header info to static files.
 
 According to RFC 2616, your application should behave differently if the
@@ -2208,7 +2212,7 @@ set :protection, :except => [:path_traversal, :session_hijacking]
 ```
 
 By default, Sinatra will only set up session based protection if `:sessions`
-have been enabled. See 'Using Sessions'. Sometimes you may want to set up
+have been enabled. See '[Using Sessions](#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:
@@ -2353,6 +2357,16 @@ set :protection, :session => true
       priority, default depends on Ruby implementation.
     </dd>
 
+  <dt>server_settings</dt>
+    <dd>
+      If you are using a WEBrick web server, presumably for your development
+      environment, you can pass a hash of options to <tt>server_settings</tt>,
+      such as <tt>SSLEnable</tt> or <tt>SSLVerifyClient</tt>. However, web
+      servers such as Puma and Thin do not support this, so you can set
+      <tt>server_settings</tt> by defining it as a method when you call
+      <tt>configure</tt>.
+    </dd>
+
   <dt>sessions</dt>
     <dd>
       Enable cookie-based sessions support using
@@ -2531,7 +2545,7 @@ and additional debugging information in your browser.
 
 ## Rack Middleware
 
-Sinatra rides on [Rack](http://rack.github.io/), a minimal standard
+Sinatra rides on [Rack](https://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
@@ -2571,7 +2585,7 @@ typically don't have to `use` them explicitly.
 
 You can find useful middleware in
 [rack](https://github.com/rack/rack/tree/master/lib/rack),
-[rack-contrib](https://github.com/rack/rack-contrib#readm),
+[rack-contrib](https://github.com/rack/rack-contrib#readme),
 or in the [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
 
 ## Testing
@@ -2995,7 +3009,9 @@ Options are:
 
 ### Multi-threading
 
-_Paraphrasing from [this StackOverflow answer][so-answer] by Konstantin_
+_Paraphrasing from
+[this StackOverflow answer](https://stackoverflow.com/a/6282999/5245129)
+by Konstantin_
 
 Sinatra doesn't impose any concurrency model, but leaves that to the
 underlying Rack handler (server) like Thin, Puma or WEBrick. Sinatra
@@ -3026,9 +3042,6 @@ To start the server, the command would be:
 thin --threaded start
 ```
 
-
-[so-answer]: http://stackoverflow.com/questions/6278817/is-sinatra-multi-threaded/6282999#6282999)
-
 ## Requirement
 
 The following Ruby versions are officially supported:
@@ -3097,7 +3110,7 @@ to get some of the latest features.
 ### With Bundler
 
 If you want to run your application with the latest Sinatra, using
-[Bundler](http://bundler.io) is the recommended way.
+[Bundler](https://bundler.io) is the recommended way.
 
 First, install bundler, if you haven't:
 
@@ -3127,7 +3140,7 @@ bundle exec ruby myapp.rb
 
 ## Versioning
 
-Sinatra follows [Semantic Versioning](http://semver.org/), both SemVer and
+Sinatra follows [Semantic Versioning](https://semver.org/), both SemVer and
 SemVerTag.
 
 ## Further Reading
@@ -3138,14 +3151,14 @@ SemVerTag.
   help? Have a patch?
 * [Issue tracker](https://github.com/sinatra/sinatra/issues)
 * [Twitter](https://twitter.com/sinatra)
-* [Mailing List](http://groups.google.com/group/sinatrarb/topics)
-* IRC: [#sinatra](irc://chat.freenode.net/#sinatra) on http://freenode.net
-* [Sinatra & Friends](https://sinatrarb.slack.com) on Slack and see
-  [here](https://sinatra-slack.herokuapp.com/) for an invite.
-* [Sinatra Book](https://github.com/sinatra/sinatra-book/) Cookbook Tutorial
-* [Sinatra Recipes](http://recipes.sinatrarb.com/) Community
-  contributed recipes
+* [Mailing List](https://groups.google.com/forum/#!forum/sinatrarb)
+* IRC: [#sinatra](irc://chat.freenode.net/#sinatra) on [Freenode](https://freenode.net)
+* [Sinatra & Friends](https://sinatrarb.slack.com) on Slack
+  ([get an invite](https://sinatra-slack.herokuapp.com/))
+* [Sinatra Book](https://github.com/sinatra/sinatra-book) - Cookbook Tutorial
+* [Sinatra Recipes](http://recipes.sinatrarb.com/) - Community contributed
+  recipes
 * API documentation for the [latest release](http://www.rubydoc.info/gems/sinatra)
   or the [current HEAD](http://www.rubydoc.info/github/sinatra/sinatra) on
-  http://www.rubydoc.info/
+  [RubyDoc](http://www.rubydoc.info/)
 * [CI server](https://travis-ci.org/sinatra/sinatra)