From b6a5418cb5f1b13a3feaea4e04eadbabb85efd37 Mon Sep 17 00:00:00 2001 From: Carl Wiedemann Date: Sun, 14 May 2023 15:38:29 -0600 Subject: [PATCH 1/2] docs: Issue 1548 (sinatra) Add some clarifying language to the configuration markdown. --- configuration.markdown | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/configuration.markdown b/configuration.markdown index 66ced7a2..aca04c4f 100644 --- a/configuration.markdown +++ b/configuration.markdown @@ -238,14 +238,22 @@ default in classic style apps. Disable with: Boolean specifying whether exceptions raised from routes and filters should escape the application. When disabled, exceptions are rescued and mapped to error handlers which typically set a 5xx status code and render a custom -error page. Enabling the `:raise_errors` setting causes exceptions to be -raised outside of the application where it may be handled by the server +error page. Enabling the `:raise_errors` setting causes unhandled exceptions +to be raised outside of the application where it may be handled by the server handler or Rack middleware, such as [`Rack::ShowExceptions`][se] or [`Rack::MailExceptions`][me]. [se]: http://www.rubydoc.info/github/rack/rack/Rack/ShowExceptions [me]: https://github.com/rack/rack-contrib/blob/master/lib/rack/contrib/mailexceptions.rb +The behavior of `:raise_errors` for unhandled errors depends on environment +when set to `true`. 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. + +In the `test` environment, `raise_errors` is set to `true` by default. + ### `:lock` - ensure single request concurrency with a mutex lock Sinatra can be used in threaded environments where more than a single @@ -260,4 +268,6 @@ The `:lock` setting is disabled by default. Enable error pages that show backtrace and environment information when an unhandled exception occurs. Enabled in development environments by -default. +default. Regardless of environment, if `show_exceptions` is set to +`:after_handler`, the HTTP response body will contain the verbose error +backtrace. From fffc05b4357b0bc8eda39f2e82f6dc4ab4da5f4a Mon Sep 17 00:00:00 2001 From: Carl Wiedemann Date: Sun, 14 May 2023 15:51:18 -0600 Subject: [PATCH 2/2] docs: Issue 1548 (sinatra) Regen prebuilt files. --- _includes/README.html | 67 ++++++++++++++++++++++++++- _includes/rack-protection-readme.html | 7 +-- 2 files changed, 69 insertions(+), 5 deletions(-) diff --git a/_includes/README.html b/_includes/README.html index b3d998df..5a8875f2 100644 --- a/_includes/README.html +++ b/_includes/README.html @@ -1905,9 +1905,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
@@ -2052,6 +2056,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 +2070,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 +2111,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
diff --git a/_includes/rack-protection-readme.html b/_includes/rack-protection-readme.html
index aee63cad..86ae0dda 100644
--- a/_includes/rack-protection-readme.html
+++ b/_includes/rack-protection-readme.html
@@ -87,7 +87,8 @@ 

 
Prevented by:

 
 
 
 
IP Spoofing

@@ -114,9 +115,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’.