sinatra 2.1.0 → 4.1.1

data/README.md

@@ -1,8 +1,7 @@
 # Sinatra
 
-[![Gem Version](https://badge.fury.io/rb/sinatra.svg)](http://badge.fury.io/rb/sinatra)
-[![Build Status](https://secure.travis-ci.org/sinatra/sinatra.svg)](https://travis-ci.org/sinatra/sinatra)
-[![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=sinatra&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=sinatra&package-manager=bundler&version-scheme=semver)
+[![Gem Version](https://badge.fury.io/rb/sinatra.svg)](https://badge.fury.io/rb/sinatra)
+[![Testing](https://github.com/sinatra/sinatra/actions/workflows/test.yml/badge.svg)](https://github.com/sinatra/sinatra/actions/workflows/test.yml)
 
 Sinatra is a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for
 quickly creating web applications in Ruby with minimal effort:
@@ -16,10 +15,10 @@ get '/' do
 end
 ```
 
-Install the gem:
+Install the gems needed:
 
 ```shell
-gem install sinatra
+gem install sinatra rackup puma
 ```
 
 And run with:
@@ -31,101 +30,95 @@ 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).
+Please restart the server every time you change or use a code reloader
+like [rerun](https://github.com/alexch/rerun) or
+[rack-unreloader](https://github.com/jeremyevans/rack-unreloader).
 
 It is recommended to also run `gem install puma`, which Sinatra will
 pick up if available.
 
 ## Table of Contents
 
-* [Sinatra](#sinatra)
-    * [Table of Contents](#table-of-contents)
-    * [Routes](#routes)
-    * [Conditions](#conditions)
-    * [Return Values](#return-values)
-    * [Custom Route Matchers](#custom-route-matchers)
-    * [Static Files](#static-files)
-    * [Views / Templates](#views--templates)
-        * [Literal Templates](#literal-templates)
-        * [Available Template Languages](#available-template-languages)
-            * [Haml Templates](#haml-templates)
-            * [Erb Templates](#erb-templates)
-            * [Builder Templates](#builder-templates)
-            * [Nokogiri Templates](#nokogiri-templates)
-            * [Sass Templates](#sass-templates)
-            * [SCSS Templates](#scss-templates)
-            * [Less Templates](#less-templates)
-            * [Liquid Templates](#liquid-templates)
-            * [Markdown Templates](#markdown-templates)
-            * [Textile Templates](#textile-templates)
-            * [RDoc Templates](#rdoc-templates)
-            * [AsciiDoc Templates](#asciidoc-templates)
-            * [Radius Templates](#radius-templates)
-            * [Markaby Templates](#markaby-templates)
-            * [RABL Templates](#rabl-templates)
-            * [Slim Templates](#slim-templates)
-            * [Creole Templates](#creole-templates)
-            * [MediaWiki Templates](#mediawiki-templates)
-            * [CoffeeScript Templates](#coffeescript-templates)
-            * [Stylus Templates](#stylus-templates)
-            * [Yajl Templates](#yajl-templates)
-            * [WLang Templates](#wlang-templates)
-        * [Accessing Variables in Templates](#accessing-variables-in-templates)
-        * [Templates with `yield` and nested layouts](#templates-with-yield-and-nested-layouts)
-        * [Inline Templates](#inline-templates)
-        * [Named Templates](#named-templates)
-        * [Associating File Extensions](#associating-file-extensions)
-        * [Adding Your Own Template Engine](#adding-your-own-template-engine)
-        * [Using Custom Logic for Template Lookup](#using-custom-logic-for-template-lookup)
-    * [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)
-        * [Setting Body, Status Code and Headers](#setting-body-status-code-and-headers)
-        * [Streaming Responses](#streaming-responses)
-        * [Logging](#logging)
-        * [Mime Types](#mime-types)
-        * [Generating URLs](#generating-urls)
-        * [Browser Redirect](#browser-redirect)
-        * [Cache Control](#cache-control)
-        * [Sending Files](#sending-files)
-        * [Accessing the Request Object](#accessing-the-request-object)
-        * [Attachments](#attachments)
-        * [Dealing with Date and Time](#dealing-with-date-and-time)
-        * [Looking Up Template Files](#looking-up-template-files)
-    * [Configuration](#configuration)
-        * [Configuring attack protection](#configuring-attack-protection)
-        * [Available Settings](#available-settings)
-    * [Environments](#environments)
-    * [Error Handling](#error-handling)
-        * [Not Found](#not-found)
-        * [Error](#error)
-    * [Rack Middleware](#rack-middleware)
-    * [Testing](#testing)
-    * [Sinatra::Base - Middleware, Libraries, and Modular Apps](#sinatrabase---middleware-libraries-and-modular-apps)
-        * [Modular vs. Classic Style](#modular-vs-classic-style)
-        * [Serving a Modular Application](#serving-a-modular-application)
-        * [Using a Classic Style Application with a config.ru](#using-a-classic-style-application-with-a-configru)
-        * [When to use a config.ru?](#when-to-use-a-configru)
-        * [Using Sinatra as Middleware](#using-sinatra-as-middleware)
-        * [Dynamic Application Creation](#dynamic-application-creation)
-    * [Scopes and Binding](#scopes-and-binding)
-        * [Application/Class Scope](#applicationclass-scope)
-        * [Request/Instance Scope](#requestinstance-scope)
-        * [Delegation Scope](#delegation-scope)
-    * [Command Line](#command-line)
-        * [Multi-threading](#multi-threading)
-    * [Requirement](#requirement)
-    * [The Bleeding Edge](#the-bleeding-edge)
-        * [With Bundler](#with-bundler)
-    * [Versioning](#versioning)
-    * [Further Reading](#further-reading)
+- [Sinatra](#sinatra)
+  - [Table of Contents](#table-of-contents)
+  - [Routes](#routes)
+  - [Conditions](#conditions)
+  - [Return Values](#return-values)
+  - [Custom Route Matchers](#custom-route-matchers)
+  - [Static Files](#static-files)
+  - [Views / Templates](#views--templates)
+    - [Literal Templates](#literal-templates)
+    - [Available Template Languages](#available-template-languages)
+      - [Haml Templates](#haml-templates)
+      - [Erb Templates](#erb-templates)
+      - [Builder Templates](#builder-templates)
+      - [Nokogiri Templates](#nokogiri-templates)
+      - [Sass Templates](#sass-templates)
+      - [Scss Templates](#scss-templates)
+      - [Liquid Templates](#liquid-templates)
+      - [Markdown Templates](#markdown-templates)
+      - [RDoc Templates](#rdoc-templates)
+      - [AsciiDoc Templates](#asciidoc-templates)
+      - [Markaby Templates](#markaby-templates)
+      - [RABL Templates](#rabl-templates)
+      - [Slim Templates](#slim-templates)
+      - [Yajl Templates](#yajl-templates)
+    - [Accessing Variables in Templates](#accessing-variables-in-templates)
+    - [Templates with `yield` and nested layouts](#templates-with-yield-and-nested-layouts)
+    - [Inline Templates](#inline-templates)
+    - [Named Templates](#named-templates)
+    - [Associating File Extensions](#associating-file-extensions)
+    - [Adding Your Own Template Engine](#adding-your-own-template-engine)
+    - [Using Custom Logic for Template Lookup](#using-custom-logic-for-template-lookup)
+  - [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)
+    - [Setting Body, Status Code, and Headers](#setting-body-status-code-and-headers)
+    - [Streaming Responses](#streaming-responses)
+    - [Logging](#logging)
+    - [Mime Types](#mime-types)
+    - [Generating URLs](#generating-urls)
+    - [Browser Redirect](#browser-redirect)
+    - [Cache Control](#cache-control)
+    - [Sending Files](#sending-files)
+    - [Accessing the Request Object](#accessing-the-request-object)
+    - [Attachments](#attachments)
+    - [Dealing with Date and Time](#dealing-with-date-and-time)
+    - [Looking Up Template Files](#looking-up-template-files)
+  - [Configuration](#configuration)
+    - [Configuring attack protection](#configuring-attack-protection)
+    - [Available Settings](#available-settings)
+  - [Lifecycle Events](#lifecycle-events)
+  - [Environments](#environments)
+  - [Error Handling](#error-handling)
+    - [Not Found](#not-found)
+    - [Error](#error)
+  - [Rack Middleware](#rack-middleware)
+  - [Testing](#testing)
+  - [Sinatra::Base - Middleware, Libraries, and Modular Apps](#sinatrabase---middleware-libraries-and-modular-apps)
+    - [Modular vs. Classic Style](#modular-vs-classic-style)
+    - [Serving a Modular Application](#serving-a-modular-application)
+    - [Using a Classic Style Application with a config.ru](#using-a-classic-style-application-with-a-configru)
+    - [When to use a config.ru?](#when-to-use-a-configru)
+    - [Using Sinatra as Middleware](#using-sinatra-as-middleware)
+    - [Dynamic Application Creation](#dynamic-application-creation)
+  - [Scopes and Binding](#scopes-and-binding)
+    - [Application/Class Scope](#applicationclass-scope)
+    - [Request/Instance Scope](#requestinstance-scope)
+    - [Delegation Scope](#delegation-scope)
+  - [Command Line](#command-line)
+    - [Multi-threading](#multi-threading)
+  - [Requirement](#requirement)
+  - [The Bleeding Edge](#the-bleeding-edge)
+    - [With Bundler](#with-bundler)
+  - [Versioning](#versioning)
+  - [Further Reading](#further-reading)
 
 ## Routes
 
@@ -344,11 +337,11 @@ 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
+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
+You can return an object that would either be a valid Rack response, Rack
 body object or HTTP status code:
 
 * An Array with three elements: `[status (Integer), headers (Hash), response
@@ -372,7 +365,7 @@ get('/') { Stream.new }
 ```
 
 You can also use the `stream` helper method ([described below](#streaming-responses)) to reduce
-boiler plate and embed the streaming logic in the route.
+boilerplate and embed the streaming logic in the route.
 
 ## Custom Route Matchers
 
@@ -382,15 +375,16 @@ stop there. You can easily define your own matchers:
 
 ```ruby
 class AllButPattern
-  Match = Struct.new(:captures)
-
   def initialize(except)
-    @except   = except
-    @captures = Match.new([])
+    @except = except
+  end
+
+  def to_pattern(options)
+    return self
   end
 
-  def match(str)
-    @captures unless @except === str
+  def params(route)
+    return {} unless @except === route
   end
 end
 
@@ -407,20 +401,12 @@ Note that the above example might be over-engineered, as it can also be
 expressed as:
 
 ```ruby
-get // do
+get /.*/ do
   pass if request.path_info == "/index"
   # ...
 end
 ```
 
-Or, using negative look ahead:
-
-```ruby
-get %r{(?!/index)} do
-  # ...
-end
-```
-
 ## Static Files
 
 Static files are served from the `./public` directory. You can specify
@@ -584,7 +570,7 @@ Some languages have multiple implementations. To specify what implementation
 to use (and to be thread-safe), you should simply require it first:
 
 ```ruby
-require 'rdiscount' # or require 'bluecloth'
+require 'rdiscount'
 get('/') { markdown :index }
 ```
 
@@ -612,14 +598,12 @@ get('/') { markdown :index }
     <td>Dependency</td>
     <td>
       <a href="https://github.com/jeremyevans/erubi" title="erubi">erubi</a>
-      or <a href="http://www.kuwata-lab.com/erubis/" title="erubis">erubis</a>
       or erb (included in Ruby)
     </td>
   </tr>
   <tr>
     <td>File Extensions</td>
-    <td><tt>.erb</tt>, <tt>.rhtml</tt> or <tt>.erubi</tt> (Erubi only)
- or <tt>.erubis</tt> (Erubis only)</td>
+    <td><tt>.erb</tt>, <tt>.rhtml</tt> or <tt>.erubi</tt> (Erubi only)</td>
   </tr>
   <tr>
     <td>Example</td>
@@ -672,7 +656,7 @@ It also takes a block for inline templates (see [example](#inline-templates)).
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="https://sass-lang.com/" title="sass">sass</a></td>
+    <td><a href="https://github.com/ntkme/sass-embedded-host-ruby" title="sass-embedded">sass-embedded</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -684,12 +668,12 @@ It also takes a block for inline templates (see [example](#inline-templates)).
   </tr>
 </table>
 
-#### SCSS Templates
+#### Scss Templates
 
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="https://sass-lang.com/" title="sass">sass</a></td>
+    <td><a href="https://github.com/ntkme/sass-embedded-host-ruby" title="sass-embedded">sass-embedded</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -701,23 +685,6 @@ It also takes a block for inline templates (see [example](#inline-templates)).
   </tr>
 </table>
 
-#### Less Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="http://lesscss.org/" title="less">less</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.less</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>less :stylesheet</tt></td>
-  </tr>
-</table>
-
 #### Liquid Templates
 
 <table>
@@ -747,9 +714,7 @@ 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="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>
         <a href="https://github.com/gjtorikian/commonmarker" title="commonmarker">commonmarker</a>
         <a href="https://github.com/alphabetum/pandoc-ruby" title="pandoc">pandoc</a>
     </td>
@@ -784,42 +749,6 @@ Since you cannot call Ruby from Markdown, you cannot use layouts written in
 Markdown. However, it is possible to use another rendering engine for the
 template than for the layout by passing the `:layout_engine` option.
 
-#### Textile Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="http://redcloth.org/" title="RedCloth">RedCloth</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.textile</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>textile :index, :layout_engine => :erb</tt></td>
-  </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:
-
-```ruby
-erb :overview, :locals => { :text => textile(:introduction) }
-```
-
-Note that you may also call the `textile` method from within other templates:
-
-```ruby
-%h1 Hello From Haml!
-%p= textile(:greetings)
-```
-
-Since you cannot call Ruby from Textile, you cannot use layouts written in
-Textile. However, it is possible to use another rendering engine for the
-template than for the layout by passing the `:layout_engine` option.
-
 #### RDoc Templates
 
 <table>
@@ -875,26 +804,6 @@ template than for the layout by passing the `:layout_engine` option.
 Since you cannot call Ruby methods directly from an AsciiDoc template, you
 almost always want to pass locals to it.
 
-#### Radius Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/jlong/radius" title="Radius">Radius</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.radius</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>radius :index, :locals => { :key => 'value' }</tt></td>
-  </tr>
-</table>
-
-Since you cannot call Ruby methods directly from a Radius template, you
-almost always want to pass locals to it.
-
 #### Markaby Templates
 
 <table>
@@ -936,7 +845,7 @@ It also takes a block for inline templates (see [example](#inline-templates)).
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="http://slim-lang.com/" title="Slim Lang">Slim Lang</a></td>
+    <td><a href="https://slim-template.github.io/" title="Slim Lang">Slim Lang</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -948,139 +857,6 @@ It also takes a block for inline templates (see [example](#inline-templates)).
   </tr>
 </table>
 
-#### Creole Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/minad/creole" title="Creole">Creole</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.creole</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>creole :wiki, :layout_engine => :erb</tt></td>
-  </tr>
-</table>
-
-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
-erb :overview, :locals => { :text => creole(:introduction) }
-```
-
-Note that you may also call the `creole` method from within other templates:
-
-```ruby
-%h1 Hello From Haml!
-%p= creole(:greetings)
-```
-
-Since you cannot call Ruby from Creole, you cannot use layouts written in
-Creole. However, it is possible to use another rendering engine for the
-template than for the layout by passing the `:layout_engine` option.
-
-#### MediaWiki Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/nricciar/wikicloth" title="WikiCloth">WikiCloth</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.mediawiki</tt> and <tt>.mw</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>mediawiki :wiki, :layout_engine => :erb</tt></td>
-  </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:
-
-```ruby
-erb :overview, :locals => { :text => mediawiki(:introduction) }
-```
-
-Note that you may also call the `mediawiki` method from within other
-templates:
-
-```ruby
-%h1 Hello From Haml!
-%p= mediawiki(:greetings)
-```
-
-Since you cannot call Ruby from MediaWiki, you cannot use layouts written in
-MediaWiki. However, it is possible to use another rendering engine for the
-template than for the layout by passing the `:layout_engine` option.
-
-#### CoffeeScript Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td>
-      <a href="https://github.com/josh/ruby-coffee-script" title="Ruby CoffeeScript">
-        CoffeeScript
-      </a> and a
-      <a href="https://github.com/sstephenson/execjs" title="ExecJS">
-        way to execute javascript
-      </a>
-    </td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.coffee</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>coffee :index</tt></td>
-  </tr>
-</table>
-
-#### Stylus Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td>
-      <a href="https://github.com/forgecrafted/ruby-stylus" title="Ruby Stylus">
-        Stylus
-      </a> and a
-      <a href="https://github.com/sstephenson/execjs" title="ExecJS">
-        way to execute javascript
-      </a>
-    </td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.styl</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>stylus :index</tt></td>
-  </tr>
-</table>
-
-Before being able to use Stylus templates, you need to load `stylus` and
-`stylus/tilt` first:
-
-```ruby
-require 'sinatra'
-require 'stylus'
-require 'stylus/tilt'
-
-get '/' do
-  stylus :example
-end
-```
-
 #### Yajl Templates
 
 <table>
@@ -1122,27 +898,6 @@ var resource = {"foo":"bar","baz":"qux"};
 present(resource);
 ```
 
-#### WLang Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/blambeau/wlang" title="WLang">WLang</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.wlang</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>wlang :index, :locals => { :key => 'value' }</tt></td>
-  </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.
-
 ### Accessing Variables in Templates
 
 Templates are evaluated within the same context as route handlers. Instance
@@ -1201,7 +956,7 @@ end
 ```
 
 Currently, the following rendering methods accept a block: `erb`, `haml`,
-`liquid`, `slim `, `wlang`. Also the general `render` method accepts a block.
+`liquid`, `slim `. Also, the general `render` method accepts a block.
 
 ### Inline Templates
 
@@ -1218,13 +973,13 @@ __END__
 
 @@ layout
 %html
-  = yield
+  != yield
 
 @@ index
 %div.title Hello world.
 ```
 
-NOTE: Inline templates defined in the source file that requires sinatra are
+NOTE: Inline templates defined in the source file that requires Sinatra are
 automatically loaded. Call `enable :inline_templates` explicitly if you
 have inline templates in other source files.
 
@@ -1261,10 +1016,10 @@ end
 
 To associate a file extension with a template engine, use
 `Tilt.register`. For instance, if you like to use the file extension
-`tt` for Textile templates, you can do the following:
+`tt` for Haml templates, you can do the following:
 
 ```ruby
-Tilt.register :tt, Tilt[:textile]
+Tilt.register Tilt[:haml], :tt
 ```
 
 ### Adding Your Own Template Engine
@@ -1272,7 +1027,7 @@ Tilt.register :tt, Tilt[:textile]
 First, register your engine with Tilt, then create a rendering method:
 
 ```ruby
-Tilt.register :myat, MyAwesomeTemplateEngine
+Tilt.register MyAwesomeTemplateEngine, :myat
 
 helpers do
   def myat(*args) render(:myat, *args) end
@@ -1434,7 +1189,7 @@ For better security and usability it's
 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:
+Here are some examples of how you might create a 64-byte secret and set it:
 
 **Session Secret Generation**
 
@@ -1443,22 +1198,6 @@ $ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
 99ae8af...snip...ec0f262ac
 ```
 
-**Session Secret Generation (Bonus Points)**
-
-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
-$ 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
@@ -1472,15 +1211,11 @@ purposes only:
 
 **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#readme) here as well:
+Set up your app config to fail-safe to a secure random secret
+if the `SESSION_SECRET` environment variable is not available:
 
 ```ruby
 require 'securerandom'
-# -or- require 'sysrandom/securerandom'
 set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }
 ```
 
@@ -1593,7 +1328,7 @@ 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
+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
@@ -1616,13 +1351,13 @@ 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
+### 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
+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:
+thereon to access the body:
 
 ```ruby
 get '/foo' do
@@ -1645,7 +1380,7 @@ get '/foo' do
   headers \
     "Allow"   => "BREW, POST, GET, PROPFIND, WHEN",
     "Refresh" => "Refresh: 20; https://ietf.org/rfc/rfc2324.txt"
-  body "I'm a tea pot!"
+  body "I'm a teapot!"
 end
 ```
 
@@ -1678,60 +1413,16 @@ 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.
+requests, highly depends on the webserver 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
-execution flow. This only works on evented servers, like Rainbows.
-Other servers will still close the stream:
-
-```ruby
-# config.ru
-require 'sinatra/base'
-
-class App < Sinatra::Base
-  connections = []
-
-  get '/subscribe', provides: 'text/event-stream'  do
-    # register a client's interest in server events
-    stream(:keep_open) do |out|
-      connections << out
-      # purge dead connections
-      connections.reject!(&:closed?)
-    end
-  end
-
-  post '/' do
-    connections.each do |out|
-      # notify client that a new message has arrived
-      out << "data: #{params[:msg]}\n\n"
-
-      # indicate client to connect again
-      out.close
-    end
-
-    204 # response without entity body
-  end
-end
+execution flow.
 
-run App
-```
-
-```ruby
-# rainbows.conf
-Rainbows! do
-  use :EventMachine
-end
-````
-
-Run:
-
-```shell
-rainbows -c rainbows.conf
-```
+You can have a look at the [chat example](https://github.com/sinatra/sinatra/blob/main/examples/chat.rb)
 
 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
@@ -1763,7 +1454,7 @@ class MyApp < Sinatra::Base
 end
 ```
 
-To avoid any logging middleware to be set up, set the `logging` setting to
+To avoid any logging middleware to be set up, set the `logging` option to
 `nil`. However, keep in mind that `logger` will in that case return `nil`. A
 common use case is when you want to set your own logger. Sinatra will use
 whatever it will find in `env['rack.logger']`.
@@ -1797,7 +1488,7 @@ Haml:
 %a{:href => url('/foo')} foo
 ```
 
-It takes reverse proxies and Rack routers into account, if present.
+It takes reverse proxies and Rack routers into account - if present.
 
 This method is also aliased to `to` (see [below](#browser-redirect) for an example).
 
@@ -2136,7 +1827,7 @@ end
 Another example would be using different directories for different engines:
 
 ```ruby
-set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'
+set :views, :haml => 'templates', :default => 'views'
 
 helpers do
   def find_template(views, name, engine, &block)
@@ -2147,7 +1838,7 @@ helpers do
 end
 ```
 
-You can also easily wrap this up in an extension and share with others!
+You can also easily wrap this up in an extension and share it 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
@@ -2213,7 +1904,7 @@ end
 ### Configuring attack protection
 
 Sinatra is using
-[Rack::Protection](https://github.com/sinatra/sinatra/tree/master/rack-protection#readme) to
+[Rack::Protection](https://github.com/sinatra/sinatra/tree/main/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):
@@ -2230,13 +1921,13 @@ set :protection, :except => :path_traversal
 You can also hand in an array in order to disable a list of protections:
 
 ```ruby
-set :protection, :except => [:path_traversal, :session_hijacking]
+set :protection, :except => [:path_traversal, :remote_token]
 ```
 
 By default, Sinatra will only set up session based protection if `:sessions`
 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
+separate `Rack::Builder` instance. In that case, you can still set up session
 based protection by passing the `:session` option:
 
 ```ruby
@@ -2293,7 +1984,7 @@ set :protection, :session => true
     <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. Enabled by default unless environment is "test".</dd>
 
   <dt>environment</dt>
     <dd>
@@ -2301,6 +1992,33 @@ set :protection, :session => true
       <tt>"development"</tt> if not available.
     </dd>
 
+  <dt>host_authorization</dt>
+  <dd>
+    <p>
+      You can pass a hash of options to <tt>host_authorization</tt>,
+      to be used by the <tt>Rack::Protection::HostAuthorization</tt> middleware.
+    </p>
+    <p>
+      The middleware can block requests with unrecognized hostnames, to prevent DNS rebinding
+      and other host header attacks. It checks the <tt>Host</tt>, <tt>X-Forwarded-Host</tt>
+      and <tt>Forwarded</tt> headers.
+    </p>
+    <p>
+      Useful options are:
+      <ul>
+        <li><tt>permitted_hosts</tt> – an array of hostnames (and <tt>IPAddr</tt> objects) your app recognizes
+          <ul>
+            <li>in the <tt>development</tt> environment, it is set to <tt>.localhost</tt>, <tt>.test</tt> and any IPv4/IPv6 address</li>
+            <li>if empty, any hostname is permitted (the default for any other environment)</li>
+          </ul>
+        </li>
+        <li><tt>status</tt> – the HTTP status code used in the response when a request is blocked (defaults to <tt>403</tt>)</li>
+        <li><tt>message</tt> – the body used in the response when a request is blocked (defaults to <tt>Host not permitted</tt>)</li>
+        <li><tt>allow_if</tt> – supply a <tt>Proc</tt> to use custom allow/deny logic, the proc is passed the request environment</li>
+      </ul>
+    </p>
+  </dd>
+
   <dt>logging</dt>
     <dd>Use the logger.</dd>
 
@@ -2369,9 +2087,13 @@ set :protection, :session => true
 
   <dt>raise_errors</dt>
     <dd>
-      Raise exceptions (will stop application). Enabled by default when
+      Raise unhandled errors (will stop application). Enabled by default when
       <tt>environment</tt> is set to <tt>"test"</tt>, disabled otherwise.
     </dd>
+    <dd>
+      Any explicitly defined error handlers always override this setting. See 
+      the "Error" section below.
+    </dd>
 
   <dt>run</dt>
     <dd>
@@ -2390,12 +2112,8 @@ set :protection, :session => true
 
   <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 do not support this, so you can set
-      <tt>server_settings</tt> by defining it as a method when you call
-      <tt>configure</tt>.
+      You can pass a hash of options to <tt>server_settings</tt>,
+      such as <tt>Host</tt> or <tt>Port</tt>.
     </dd>
 
   <dt>sessions</dt>
@@ -2464,6 +2182,24 @@ set :protection, :session => true
     </dd>
 </dl>
 
+## Lifecycle Events
+
+There are 2 lifecycle events currently exposed by Sinatra. One when the server starts and one when it stops.
+
+They can be used like this:
+
+```ruby
+on_start do
+  puts "===== Booting up ====="
+end
+
+on_stop do
+  puts "===== Shutting down ====="
+end
+```
+
+Note that these callbacks only work when using Sinatra to start the web server.
+
 ## Environments
 
 There are three predefined `environments`: `"development"`,
@@ -2520,6 +2256,14 @@ show exceptions option to `:after_handler`:
 set :show_exceptions, :after_handler
 ```
 
+A catch-all error handler can be defined with `error` and a block:
+
+```ruby
+error do
+  'Sorry there was a nasty error'
+end
+```
+
 The exception object can be obtained from the `sinatra.error` Rack variable:
 
 ```ruby
@@ -2528,7 +2272,7 @@ error do
 end
 ```
 
-Custom errors:
+Pass an error class as an argument to create handlers for custom errors:
 
 ```ruby
 error MyCustomError do
@@ -2574,6 +2318,51 @@ Sinatra installs special `not_found` and `error` handlers when
 running under the development environment to display nice stack traces
 and additional debugging information in your browser.
 
+### Behavior with `raise_errors` option
+
+When `raise_errors` option is `true`, errors that are unhandled are raised 
+outside of the application. Additionally, any errors that would have been 
+caught by the catch-all error handler are raised.
+
+For example, consider the following configuration:
+
+```ruby
+# First handler
+error MyCustomError do
+  'A custom message'
+end
+
+# Second handler
+error do
+  'A catch-all message'
+end
+```
+
+If `raise_errors` is `false`:
+
+* When `MyCustomError` or descendant is raised, the first handler is invoked.
+  The HTTP response body will contain `"A custom message"`.
+* When any other error is raised, the second handler is invoked. The HTTP 
+  response body will contain `"A catch-all message"`.
+
+If `raise_errors` is `true`:
+
+* When `MyCustomError` or descendant is raised, the behavior is identical to 
+  when `raise_errors` is `false`, described above.
+* When any other error is raised, the second handler is *not* invoked, and 
+  the error is raised outside of the application.
+  * If the environment is `production`, the HTTP response body will contain 
+    a generic error message, e.g. `"An unhandled lowlevel error occurred. The
+    application logs may have details."`
+  * If the environment is not `production`, the HTTP response body will contain
+    the verbose error backtrace.
+  * Regardless of environment, if `show_exceptions` is set to `:after_handler`, 
+    the HTTP response body will contain the verbose error backtrace.
+
+In the `test` environment, `raise_errors` is set to `true` by default. This 
+means that in order to write a test for a catch-all error handler, 
+`raise_errors` must temporarily be set to `false` for that particular test.
+
 ## Rack Middleware
 
 Sinatra rides on [Rack](https://rack.github.io/), a minimal standard
@@ -2599,7 +2388,7 @@ end
 ```
 
 The semantics of `use` are identical to those defined for the
-[Rack::Builder](http://www.rubydoc.info/github/rack/rack/master/Rack/Builder) DSL
+[Rack::Builder](https://www.rubydoc.info/github/rack/rack/main/Rack/Builder) DSL
 (most frequently used from rackup files). For example, the `use` method
 accepts multiple/variable args as well as blocks:
 
@@ -2615,7 +2404,7 @@ many of these components automatically based on configuration so you
 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](https://github.com/rack/rack/tree/main/lib/rack),
 [rack-contrib](https://github.com/rack/rack-contrib#readme),
 or in the [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
 
@@ -2623,7 +2412,7 @@ or in the [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
 
 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)
+[Rack::Test](https://www.rubydoc.info/github/rack/rack-test/main/frames)
 is recommended:
 
 ```ruby
@@ -2717,7 +2506,7 @@ 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.
+There is no reason you cannot mix the modular and classic styles.
 
 If switching from one style to the other, you should be aware of
 slightly different default settings:
@@ -2846,7 +2635,7 @@ 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
+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/...):
 
@@ -2937,7 +2726,7 @@ 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
+created explicitly. At the 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.
 
@@ -2960,7 +2749,7 @@ You have the application scope binding inside:
 * Your application class body
 * Methods defined by extensions
 * The block passed to `helpers`
-* Procs/blocks used as value for `set`
+* Procs/blocks used as a value for `set`
 * The block passed to `Sinatra.new`
 
 You can reach the scope object (the class) like this:
@@ -3011,7 +2800,7 @@ do not share variables/state with the class scope (read: you have a different
 
 You have the delegate scope binding inside:
 
-* The top level binding, if you did `require "sinatra"`
+* The top-level binding, if you did `require "sinatra"`
 * An object extended with the `Sinatra::Delegator` mixin
 
 Have a look at the code for yourself: here's the
@@ -3044,98 +2833,43 @@ _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 Puma or WEBrick. Sinatra
+Sinatra doesn't impose any concurrency model but leaves that to the
+underlying Rack handler (server) like Puma or Falcon. Sinatra
 itself is thread-safe, so there won't be any problem if the Rack handler
-uses a threaded model of concurrency. This would mean that when starting
-the server, you'd have to specify the correct invocation method for the
-specific Rack handler. The following example is a demonstration of how
-to start a multi-threaded Rainbows server:
-
-```ruby
-# config.ru
-
-require 'sinatra/base'
-
-class App < Sinatra::Base
-  get '/' do
-    "Hello, World"
-  end
-end
-
-run App
-```
-
-```ruby
-# rainbows.conf
-
-# Rainbows configurator is based on Unicorn.
-Rainbows! do
-  use :ThreadSpawn
-end
-```
-
-To start the server, the command would be:
-
-```shell
-rainbows -c rainbows.conf
-```
+uses a threaded model of concurrency.
 
 ## Requirement
 
 The following Ruby versions are officially supported:
 <dl>
-  <dt>Ruby 2.3</dt>
+  <dt>Ruby</dt>
   <dd>
-    2.3 is fully supported and recommended. There are currently no plans to
-    drop official support for it.
+    <a href="https://www.ruby-lang.org/en/downloads/">The stable releases</a> are fully supported and recommended.
   </dd>
 
-  <dt>Rubinius</dt>
+  <dt>TruffleRuby</dt>
   <dd>
-    Rubinius is officially supported (Rubinius >= 2.x). It is recommended to
-    <tt>gem install puma</tt>.
+    The latest stable release of TruffleRuby is supported.
   </dd>
 
   <dt>JRuby</dt>
   <dd>
-    The latest stable release of JRuby is officially supported. It is not
-    recommended to use C extensions with JRuby. It is recommended to
-    <tt>gem install trinidad</tt>.
+    The latest stable release of JRuby is supported. It is not
+    recommended to use C extensions with JRuby.
   </dd>
 </dl>
 
-Versions of Ruby prior to 2.3 are no longer supported as of Sinatra 2.1.0.
-
-We also keep an eye on upcoming Ruby versions.
-
-The following Ruby implementations are not officially supported but still are
-known to run Sinatra:
-
-* Older versions of JRuby and Rubinius
-* Ruby Enterprise Edition
-* MacRuby, Maglev, IronRuby
-* Ruby 1.9.0 and 1.9.1 (but we do recommend against using those)
-
-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.
+Versions of Ruby before 2.7.8 are no longer supported as of Sinatra 4.0.0.
 
 Sinatra should work on any operating system supported by the chosen Ruby
 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 2.2.
+Running Sinatra on a not officially supported Ruby flavor means that if things only break there we assume it's not our issue but theirs.
 
 ## 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
+to run your application against the main branch, it should be rather
 stable.
 
 We also push out prerelease gems from time to time, so you can do a
@@ -3184,20 +2918,19 @@ SemVerTag.
 
 ## Further Reading
 
-* [Project Website](http://www.sinatrarb.com/) - Additional documentation,
+* [Project Website](https://sinatrarb.com/) - Additional documentation,
   news, and links to other resources.
-* [Contributing](http://www.sinatrarb.com/contributing) - Find a bug? Need
+* [Contributing](https://sinatrarb.com/contributing) - Find a bug? Need
   help? Have a patch?
 * [Issue tracker](https://github.com/sinatra/sinatra/issues)
 * [Twitter](https://twitter.com/sinatra)
 * [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 & Friends](https://discord.gg/ncjsfsNHh7) on Discord
 * [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
-  [RubyDoc](http://www.rubydoc.info/)
-* [CI server](https://travis-ci.org/sinatra/sinatra)
+* API documentation for the [latest release](https://www.rubydoc.info/gems/sinatra)
+  or the [current HEAD](https://www.rubydoc.info/github/sinatra/sinatra) on
+  [RubyDoc](https://www.rubydoc.info/)
+* [CI Actions](https://github.com/sinatra/sinatra/actions)