diff --git a/_includes/README.html b/_includes/README.html index b3d998d..5a8875f 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 aee63ca..86ae0dd 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’.

diff --git a/configuration.markdown b/configuration.markdown
index 66ced7a..aca04c4 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.