# app running on https://example.com/example
+# app running on http://example.com/example
get '/foo' do
t = %w[text/css text/html application/javascript]
request.accept # ['text/html', '*/*']
@@ -1577,7 +1551,7 @@ Accessing the Request Object
request.user_agent # user agent (used by :agent condition)
request.cookies # hash of browser cookies
request.xhr? # is this an ajax request?
- request.url # "https://example.com/example/foo"
+ request.url # "http://example.com/example/foo"
request.path # "/example/foo"
request.ip # client IP address
request.secure? # false (would be true over ssl)
@@ -1767,7 +1741,7 @@ Configuring attack protection
You can also hand in an array in order to disable a list of protections:
-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
@@ -1905,9 +1879,13 @@
Available Settings
raise_errors
- Raise exceptions (will stop application). Enabled by default when
+ Raise unhandled errors (will stop application). Enabled by default when
environment is set to "test", disabled otherwise.
+
+ Any explicitly defined error handlers always override this setting. See
+ the "Error" section below.
+
run
@@ -2000,6 +1978,23 @@ Available Settings
+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:
+
+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"
,
@@ -2052,6 +2047,13 @@
Error
set :show_exceptions, :after_handler
+A catch-all error handler can be defined with error
and a block:
+
+error do
+ 'Sorry there was a nasty error'
+end
+
+
The exception object can be obtained from the sinatra.error
Rack variable:
error do
@@ -2059,7 +2061,7 @@ Error
end
-Custom errors:
+Pass an error class as an argument to create handlers for custom errors:
error MyCustomError do
'So what happened was...' + env['sinatra.error'].message
@@ -2100,6 +2102,58 @@ Error
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:
+
+# 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, a minimal standard
@@ -2216,7 +2270,7 @@
Sinatra::Base - Mid
Sinatra::Base
is a blank slate. Most options are disabled by default,
-including the built-in server. See Configuring
+including the built-in server. See Configuring
Settings 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
@@ -2571,65 +2625,30 @@
Multi-threading
Sinatra doesn’t impose any concurrency model but leaves that to the
underlying Rack handler (server) like Puma or WEBrick. 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:
-
-# config.ru
-
-require 'sinatra/base'
-
-class App < Sinatra::Base
- get '/' do
- "Hello, World"
- end
-end
-
-run App
-
-
-# rainbows.conf
-
-# Rainbows configurator is based on Unicorn.
-Rainbows! do
- use :ThreadSpawn
-end
-
-
-To start the server, the command would be:
-
-rainbows -c rainbows.conf
-
+uses a threaded model of concurrency.
Requirement
The following Ruby versions are officially supported:
- - Ruby 2.6
+ - Ruby
-
- 2.6 is fully supported and recommended. There are currently no plans to
- drop official support for it.
+ The stable releases are fully supported and recommended.
- - Rubinius
+ - TruffleRuby
-
- Rubinius is officially supported (Rubinius >= 2.x). It is recommended to
- gem install puma.
+ The latest stable release of TruffleRuby is supported.
- JRuby
-
- The latest stable release of JRuby is officially supported. It is not
- recommended to use C extensions with JRuby. It is recommended to
- gem install trinidad.
+ The latest stable release of JRuby is supported. It is not
+ recommended to use C extensions with JRuby.
-Versions of Ruby before 2.6 are no longer supported as of Sinatra 3.0.0.
-
-We also keep an eye on upcoming Ruby versions. Expect upcoming
-3.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.
@@ -2701,7 +2720,7 @@ Further Reading
Sinatra Book - Cookbook Tutorial
-Sinatra Recipes - Community contributed
+Sinatra Recipes - Community contributed
recipes
API documentation for the latest release
or the current HEAD on
diff --git a/_includes/rack-protection-authenticity-token.html b/_includes/rack-protection-authenticity-token.html
index 1b79409..78b3042 100644
--- a/_includes/rack-protection-authenticity-token.html
+++ b/_includes/rack-protection-authenticity-token.html
@@ -6,7 +6,7 @@
all
More infos
-en.wikipedia.org/wiki/Cross-site_request_forgery
+en.wikipedia.org/wiki/Cross-site_request_forgery
This middleware only accepts requests other than GET
, HEAD
, OPTIONS
, TRACE
if their given access token matches the token included in the session.
@@ -48,6 +48,7 @@
-Rack::Protection::FormToken
(not included by use Rack::Protection
)
- Rack::Protection::JsonCsrf
+Rack::Protection::FormToken
(not included by use Rack::Protection
)
+ Rack::Protection::JsonCsrf
-Rack::Protection::RemoteReferrer
(not included by use Rack::Protection
)
- Rack::Protection::RemoteToken
- Rack::Protection::HttpOrigin
+Rack::Protection::RemoteReferrer
(not included by use Rack::Protection
)
+ Rack::Protection::RemoteToken
+ Rack::Protection::HttpOrigin
Cross Site Scripting
@@ -52,10 +52,10 @@ Cross Site Scripting
Clickjacking
@@ -63,7 +63,7 @@ Clickjacking
Prevented by:
Directory Traversal
@@ -71,7 +71,7 @@ Directory Traversal
Prevented by:
Session Hijacking
@@ -79,7 +79,8 @@ Session Hijacking
Prevented by:
Cookie Tossing
@@ -87,7 +88,8 @@ Cookie Tossing
Prevented by:
IP Spoofing
@@ -95,7 +97,7 @@ IP Spoofing
Prevented by:
Helps to protect against protocol downgrade attacks and cookie hijacking
@@ -104,7 +106,7 @@ Rack::Protection::StrictTransport
(not included by use Rack::Protection
)
+Rack::Protection::StrictTransport
(not included by use Rack::Protection
)
Installation
@@ -114,9 +116,9 @@ Installation
Instrumentation
-
Instrumentation is enabled by passing in an instrumenter as an option.
+
Instrumentation is enabled by passing in an instrumenter as an option.
- use Rack::Protection, instrumenter: ActiveSupport::Notifications
+use Rack::Protection, instrumenter: ActiveSupport::Notifications
The instrumenter is passed a namespace (String) and environment (Hash). The namespace is ‘rack.protection’ and the attack type can be obtained from the environment key ‘rack.protection.attack’.
diff --git a/_includes/rack-protection-remote-referrer.html b/_includes/rack-protection-remote-referrer.html
index 9e91322..0fc1aa5 100644
--- a/_includes/rack-protection-remote-referrer.html
+++ b/_includes/rack-protection-remote-referrer.html
@@ -6,7 +6,7 @@
all
More infos
-en.wikipedia.org/wiki/Cross-site_request_forgery
+en.wikipedia.org/wiki/Cross-site_request_forgery
Does not accept unsafe HTTP requests if the Referer [sic] header is set to a different host.
diff --git a/_includes/rack-protection-remote-token.html b/_includes/rack-protection-remote-token.html
index 8e715ba..bf484fe 100644
--- a/_includes/rack-protection-remote-token.html
+++ b/_includes/rack-protection-remote-token.html
@@ -6,7 +6,7 @@
all
More infos
-en.wikipedia.org/wiki/Cross-site_request_forgery
+en.wikipedia.org/wiki/Cross-site_request_forgery
Only accepts unsafe HTTP requests if a given access token matches the token included in the session or the request comes from the same origin.
diff --git a/_includes/rack-protection-session-hijacking.html b/_includes/rack-protection-session-hijacking.html
index 8b1f17c..9098f02 100644
--- a/_includes/rack-protection-session-hijacking.html
+++ b/_includes/rack-protection-session-hijacking.html
@@ -6,7 +6,7 @@
all
More infos
-en.wikipedia.org/wiki/Session_hijacking
+en.wikipedia.org/wiki/Session_hijacking
Tracks request properties like the user agent in the session and empties the session if those properties change. This essentially prevents attacks from Firesheep. Since all headers taken into consideration can be spoofed, too, this will not prevent determined hijacking attempts.
diff --git a/_includes/rack-protection-xss-header.html b/_includes/rack-protection-xss-header.html
index 2b02071..363b0b2 100644
--- a/_includes/rack-protection-xss-header.html
+++ b/_includes/rack-protection-xss-header.html
@@ -6,7 +6,7 @@
Internet Explorer 8+ and Chrome
More infos
-blogs.msdn.com/b/ie/archive/2008/07/01/ie8-security-part-iv-the-xss-filter.aspx
+blogs.msdn.com/b/ie/archive/2008/07/01/ie8-security-part-iv-the-xss-filter.aspx
Sets X-XSS-Protection header to tell the browser to block attacks.
diff --git a/_includes/sinatra-contrib-readme.html b/_includes/sinatra-contrib-readme.html
index 1c6a2f0..6fa23fd 100644
--- a/_includes/sinatra-contrib-readme.html
+++ b/_includes/sinatra-contrib-readme.html
@@ -22,49 +22,49 @@ Common Extensions
@@ -77,7 +77,7 @@ Custom Extensions
-
-
sinatra/reloader
: Automatically reloads Ruby files on code changes. DEPRECATED: Please consider
+sinatra/reloader
: Automatically reloads Ruby files on code changes. DEPRECATED: Please consider
consider using an alternative like rerun or
rack-unreloader instead.
@@ -86,7 +86,7 @@ Other Tools