rack-robustness 1.0.0 → 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 46cc2e7cca1b36e536f5e2e26a5e48c93e793b4c144944001464120fd6b01afa
+  data.tar.gz: 625f614030368429b7a2cd9290adfdab5ca1ec668784df94214b7a16528c7663
+SHA512:
+  metadata.gz: 6306779c8ba88fd038e9184604a995bd4694ce3f4d98428fbf2013a71f4cb8ede0d386df8b967c442baf7735f87a84773aab910b5e2b29b607182f90459042f6
+  data.tar.gz: 8dde80698d33fdc1bde9c605f69dfba631bbbe0649084d6c5b4a810f66bf9c66c818f81e56d7aab87846f0ef9a44122aad19e1702728d8cbec7d96d6a28b841f

data/CHANGELOG.md

@@ -1,4 +1,58 @@
-# 1.0.0 / 2013-02-26
+## 1.2.0 / 2023-06-09
+
+* Modernize with test matrix on ruby 2.7, 3.1, and 3.2
+
+* Fix usage of Fixnum to be compatible with Ruby 3.x
+
+## 1.1.0 / 2013-04-16
+
+* Fixed catching of non standard errors (e.g. SecurityError)
+
+* Global headers are now correctly overrided by specific per-exception headers
+
+* Renamed `#on` as `#rescue` for better capturing semantics of `on` blocks (now an alias).
+
+* Added last resort exception handling if an error occurs during exception handling itself.
+  In `no_catch_all` mode, the exception is simply reraised; otherwise a default 500 error
+  is returned with a safe message.
+
+* Added a shortcut form for `#rescue` clauses allowing values directly, e.g.,
+
+        use Rack::Robustness do |g|
+          g.rescue(SecurityError, 403)
+        end
+
+* Added suppport for ensure clause(s), always called after `rescue` blocks
+
+* Rack's `env` is now available in all error handling blocks, e.g.,
+
+        use Rack::Robustness do |g|
+          g.status{|ex| ... env ... }
+          g.body  {|ex| ... env ... }
+          g.rescue(SecurityError){|ex| ... env ... }
+          g.ensure{|ex| ... env ... }
+        end
+
+* Similarly, Rack::Robustness now internally uses instances of Rack::Request and Rack::Response;
+  `request` and `response` are available in all blocks. The specific Response
+  object to use can be built using the `response` DSL method, e.g.,
+
+        use Rack::Robustness do |g|
+          g.response{|ex| MyOwnRackResponse.new }
+        end
+
+* Rack::Robustness may now be subclassed as an alternative to inline `use`, e.g.
+
+        class Shield < Rack::Robustness
+          self.body  {|ex| ... }
+          self.rescue(SecurityError){|ex| ... }
+          ...
+        end
+
+        # in Rack-based configuration
+        use Shield
+
+## 1.0.0 / 2013-02-26
 
 * Enhancements
 

data/Gemfile

@@ -1,8 +1,8 @@
 source 'http://rubygems.org'
 
 group :development do
-  gem "rack", "~> 1.5"
-  gem "rake", "~> 10.0"
-  gem "rspec", "~> 2.12"
+  gem "rack", "~> 2"
+  gem "rake", "~> 13"
+  gem "rspec", "~> 3"
   gem "rack-test", "~> 0.6"
 end

data/Gemfile.lock

@@ -1,25 +1,33 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    diff-lcs (1.1.3)
-    rack (1.5.2)
+    diff-lcs (1.5.0)
+    rack (2.2.7)
     rack-test (0.6.2)
       rack (>= 1.0)
-    rake (10.0.3)
-    rspec (2.12.0)
-      rspec-core (~> 2.12.0)
-      rspec-expectations (~> 2.12.0)
-      rspec-mocks (~> 2.12.0)
-    rspec-core (2.12.2)
-    rspec-expectations (2.12.1)
-      diff-lcs (~> 1.1.3)
-    rspec-mocks (2.12.2)
+    rake (13.0.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  rack (~> 1.5)
+  rack (~> 2)
   rack-test (~> 0.6)
-  rake (~> 10.0)
-  rspec (~> 2.12)
+  rake (~> 13)
+  rspec (~> 3)
+
+BUNDLED WITH
+   2.4.6

data/README.md

@@ -1,15 +1,59 @@
 # Rack::Robustness, the rescue clause of your Rack stack.
 
-Rack::Robustness is the rescue clause of your Rack's call stack. In other words, a middleware that ensures the robustness of your web stack, because exceptions occur either intentionally or unintentionally. It scales from zero configuration (a default shield) to specific rescue clauses for specific errors.
+Rack::Robustness is the rescue clause of your Rack's call stack. In other words, a middleware that ensures the robustness of your web stack, because exceptions occur either intentionally or unintentionally. Rack::Robustness is the rack middleware you would have written manually (see below) but provides a DSL for scaling from zero configuration (a default shield) to specific rescue clauses for specific errors.
 
 [![Build Status](https://secure.travis-ci.org/blambeau/rack-robustness.png)](http://travis-ci.org/blambeau/rack-robustness)
 [![Dependency Status](https://gemnasium.com/blambeau/rack-robustness.png)](https://gemnasium.com/blambeau/rack-robustness)
 
+```ruby
+##
+#
+# The middleware you would have written
+#
+class Robustness
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    @app.call(env)
+  rescue ArgumentError => ex
+    [400, { 'Content-Type' => 'text/plain' }, [ ex.message ] ]  # suppose the message can be safely used
+  rescue SecurityError => ex
+    [403, { 'Content-Type' => 'text/plain' }, [ ex.message ] ]
+  ensure
+    env['rack.errors'].write(ex.message) if ex
+  end
+
+end
+```
+
+...becomes...
+
+```ruby
+use Rack::Robustness do |g|
+  g.on(ArgumentError){|ex| 400 }
+  g.on(SecurityError){|ex| 403 }
+
+  g.content_type 'text/plain'
+
+  g.body{|ex|
+    ex.message
+  }
+
+  g.ensure(true){|ex|
+    env['rack.errors'].write(ex.message)
+  }
+end
+```
+
 ## Links
 
-https://github.com/blambeau/rack-robustness
+* https://github.com/blambeau/rack-robustness
+* http://www.revision-zero.org/rack-robustness
 
-## Why? 
+## Why?
 
 In my opinion, Sinatra's error handling is sometimes a bit limited for real-case needs. So I came up with something a bit more Rack-ish, that allows handling exceptions actively, because exceptions occur and that you'll handle them... enventually. A more theoretic argumentation would be:
 
@@ -17,20 +61,22 @@ In my opinion, Sinatra's error handling is sometimes a bit limited for real-case
 * The behavior to adopt when obstacles occur is not necessary defined where the exception is thrown, but often higher in the call stack.
 * In ruby web apps, the Rack's call stack is a very important part of your stack. Middlewares, routes and controllers do rarely rescue all errors, so it's still your job to rescue errors higher in the call stack.
 
-Rack::Robustness is therefore a try/catch mechanism as a middleware, to be used along the Rack call stack as you would use a standard one in a more conventional call stack:
+Rack::Robustness is therefore a try/catch/finally mechanism as a middleware, to be used along the Rack call stack as you would use a standard one in a more conventional call stack:
 
 ```java
 try {
   // main shield, typically in a main
-  
+
   try {
     // try to achieve a goal here
   } catch (...) {
     // fallback to an alternative
+  } finally {
+    // ensure something is executed in all cases
   }
-  
+
   // continue your flow
-  
+
 } catch (...) {
   // something goes really wrong, inform the user as you can
 }
@@ -53,6 +99,8 @@ class Main < Sinatra::Base
   use Rack::Robustness do
     # fallback to an alternative
     # 3xx, 4xx errors maybe
+
+    # ensure something is executed in all cases
   end
 
   # try to achieve your goal through standard routes
@@ -60,7 +108,7 @@ class Main < Sinatra::Base
 end
 ```
 
-## Examples
+## Additional examples
 
 ```ruby
 class App < Sinatra::Base
@@ -102,6 +150,9 @@ class App < Sinatra::Base
     # we use SecurityError for handling forbidden accesses.
     # The default status is 403 here
     g.on(SecurityError){|ex| 403 }
+
+    # ensure logging in all exceptional cases
+    g.ensure(true){|ex| env['rack.errors'].write(ex.message) }
   end
 
   get '/some/route/:id' do |id|
@@ -202,6 +253,27 @@ use Rack::Robustness do |g|
 end
 ```
 
+## Ensure common block in happy/exceptional/all cases
+
+```ruby
+##
+# Ensure in all cases (no arg) or exceptional cases only (true)
+#
+use Rack::Robustness do |g|
+
+  # Ensure in all cases
+  g.ensure{|ex|
+    # ex might be nil here
+  }
+
+  # Ensure in exceptional cases only (for logging purposes for instance)
+  g.ensure(true){|ex|
+    # an exception occured, ex is never nil
+    env['rack.errors'].write("#{ex.message}\n")
+  }
+end
+```
+
 ## Don't catch all!
 
 ```ruby

data/Rakefile

@@ -1,6 +1,3 @@
-# We run tests by default
-task :default => :test
-
 #
 # Install all tasks found in tasks folder
 #
@@ -9,3 +6,4 @@ task :default => :test
 Dir["tasks/*.rake"].each do |taskfile|
   load taskfile
 end
+task :default => :test

data/lib/rack/robustness.rb

@@ -1,95 +1,210 @@
 module Rack
   class Robustness
 
-    VERSION = "1.0.0".freeze
+    VERSION = "1.2.0".freeze
 
-    NIL_HANDLER = lambda{|ex| nil }
-
-    def initialize(app)
-      @app       = app
-      @handlers  = {}
-      @status    = 500
-      @headers   = {'Content-Type' => "text/plain"}
-      @body      = ["Sorry, a fatal error occured."]
-      @catch_all = true
-      yield self if block_given?
-      on(Object){|ex| [@status, {}, @body]} if @catch_all
-      @headers.freeze
-      @body.freeze
-      @handlers.freeze
+    def self.new(app, &bl)
+      return super(app) if bl.nil? and not(Robustness==self)
+      Class.new(self).install(&bl).new(app)
     end
 
     ##
     # Configuration
+    module DSL
 
-    def no_catch_all
-      @catch_all = false
-    end
+      NIL_HANDLER = lambda{|ex| nil }
 
-    def on(ex_class, &bl)
-      @handlers[ex_class] = bl || NIL_HANDLER
-    end
+      def inherited(x)
+        x.reset
+      end
 
-    def status(s=nil, &bl)
-      @status = s || bl
-    end
+      def reset
+        @rescue_clauses   = {}
+        @ensure_clauses   = []
+        @status_clause    = 500
+        @headers_clause   = {'Content-Type' => "text/plain"}
+        @body_clause      = ["Sorry, a fatal error occured."]
+        @response_builder = lambda{|ex| ::Rack::Response.new }
+        @catch_all        = true
+      end
+      attr_reader :rescue_clauses, :ensure_clauses, :status_clause,
+                  :headers_clause, :body_clause, :catch_all, :response_builder
+
+      def install
+        yield self if block_given?
+        on(Object){|ex|
+          [status_clause, {}, body_clause]
+        } if @catch_all
+        @headers_clause.freeze
+        @body_clause.freeze
+        @rescue_clauses.freeze
+        @ensure_clauses.freeze
+        self
+      end
 
-    def headers(h=nil, &bl)
-      if h.nil?
-        @headers = bl
-      else
-        @headers.merge!(h)
+      def no_catch_all
+        @catch_all = false
       end
-    end
 
-    def content_type(ct=nil, &bl)
-      headers('Content-Type' => ct || bl)
-    end
+      def response(&bl)
+        @response_builder = bl
+      end
+
+      def rescue(ex_class, handler = nil, &bl)
+        @rescue_clauses[ex_class] = handler || bl || NIL_HANDLER
+      end
+      alias :on :rescue
+
+      def ensure(bypass_on_success = false, &bl)
+        @ensure_clauses << [bypass_on_success, bl]
+      end
+
+      def status(s=nil, &bl)
+        @status_clause = s || bl
+      end
+
+      def headers(h=nil, &bl)
+        if h.nil?
+          @headers_clause = bl
+        else
+          @headers_clause.merge!(h)
+        end
+      end
+
+      def content_type(ct=nil, &bl)
+        headers('Content-Type' => ct || bl)
+      end
+
+      def body(b=nil, &bl)
+        @body_clause = b.nil? ? bl : (String===b ? [ b ] : b)
+      end
+
+    end # module DSL
+    extend DSL
+
+  public
 
-    def body(b=nil, &bl)
-      @body = b.nil? ? bl : (String===b ? [ b ] : b)
+    def initialize(app)
+      @app = app
     end
 
     ##
     # Rack's call
 
     def call(env)
-      @app.call(env)
+      dup.call!(env)
     rescue => ex
-      handler = error_handler(ex.class)
-      raise unless handler
-      handle_response(handler, ex)
+       catch_all ? last_resort(ex) : raise(ex)
+    end
+
+  protected
+
+    def call!(env)
+      @env, @request = env, Rack::Request.new(env)
+      triple = @app.call(env)
+      handle_happy(triple)
+    rescue Exception => ex
+      handle_rescue(ex)
+    ensure
+      handle_ensure(ex)
     end
 
   private
 
-    def handle_response(response, ex)
-      case response
-      when NilClass then handle_response([@status,  {},       @body], ex)
-      when Fixnum   then handle_response([response, {},       @body], ex)
-      when String   then handle_response([@status,  {},       response], ex)
-      when Hash     then handle_response([@status,  response, @body], ex)
-      when Proc     then handle_response(response.call(ex), ex)
-      else
-        status, headers, body = response.map{|x| handle_value(x, ex) }
-        [ status,
-          handle_value(@headers, ex).merge(headers),
-          body ]
+    attr_reader :env, :request, :response
+
+    [ :response_builder,
+      :rescue_clauses,
+      :ensure_clauses,
+      :status_clause,
+      :headers_clause,
+      :body_clause,
+      :catch_all ].each do |m|
+      define_method(m){|*args, &bl|
+        self.class.send(m, *args, &bl)
+      }
+    end
+
+    def handle_happy(triple)
+      s, h, b = triple
+      @response = Response.new(b, s, h)
+      @response.finish
+    end
+
+    def handle_rescue(ex)
+      begin
+        # build a response instance
+        @response = instance_exec(ex, &response_builder)
+
+        # populate it if a rescue clause can be found
+        if rescue_clause = find_rescue_clause(ex.class)
+          handle_error(ex, rescue_clause)
+          return @response.finish
+        end
+
+        # no_catch_all mode, let reraise it later
+      rescue Exception => ex2
+        return catch_all ? last_resort(ex2) : raise(ex2)
+      end
+
+      # we are in no_catch_all mode, reraise
+      raise(ex)
+    end
+
+    def handle_ensure(ex)
+      @response ||= begin
+        status, headers, body = last_resort(ex)
+        ::Rack::Response.new(body, status, headers)
       end
+      ensure_clauses.each{|(bypass,ensurer)|
+        instance_exec(ex, &ensurer) if ex or not(bypass)
+      }
     end
 
-    def handle_value(value, ex)
-      case value
-      when Proc then value.call(ex)
-      when Hash then value.each_with_object({}){|(k,v),h| h[k] = handle_value(v, ex)}
+    def handle_error(ex, rescue_clause)
+      case rescue_clause
+      when NilClass then handle_error(ex, [status_clause,  {},           body_clause])
+      when Integer  then handle_error(ex, [rescue_clause,  {},           body_clause])
+      when String   then handle_error(ex, [status_clause,  {},           rescue_clause])
+      when Hash     then handle_error(ex, [status_clause, rescue_clause, body_clause])
+      when Proc     then handle_error(ex, handle_value(ex, rescue_clause))
       else
-        value
+        status, headers, body = rescue_clause
+        handle_status(ex, status)
+        handle_headers(ex, headers)
+        handle_headers(ex, headers_clause)
+        handle_body(ex, body)
+      end
+    end
+
+    def handle_status(ex, status)
+      @response.status = handle_value(ex, status)
+    end
+
+    def handle_headers(ex, headers)
+      handle_value(ex, headers).each_pair do |key,value|
+        @response[key] ||= handle_value(ex, value)
       end
     end
 
-    def error_handler(ex_class)
+    def handle_body(ex, body)
+      body = handle_value(ex, body)
+      @response.body = body.is_a?(String) ? [ body ] : body
+    end
+
+    def handle_value(ex, value)
+      value.is_a?(Proc) ? instance_exec(ex, &value) : value
+    end
+
+    def find_rescue_clause(ex_class)
       return nil if ex_class.nil?
-      @handlers.fetch(ex_class){ error_handler(ex_class.superclass) }
+      rescue_clauses.fetch(ex_class){ find_rescue_clause(ex_class.superclass) }
+    end
+
+    def last_resort(ex)
+      [ 500,
+        {'Content-Type' => 'text/plain'},
+        [ 'An internal error occured, sorry for the disagreement.' ] ]
     end
 
  end # class Robustness

data/spec/spec_helper.rb

@@ -4,6 +4,29 @@ require 'rack/robustness'
 require 'rack/test'
 
 module SpecHelpers
+
+  def mock_app(clazz = Rack::Robustness, &bl)
+    Rack::Builder.new do
+      use clazz, &bl
+      map '/happy' do
+        run lambda{|env| [200, {'Content-Type' => 'text/plain'}, ['happy']]}
+      end
+      map "/argument-error" do
+        run lambda{|env| raise ArgumentError, "an argument error" }
+      end
+      map "/type-error" do
+        run lambda{|env| raise TypeError, "a type error" }
+      end
+      map "/security-error" do
+        run lambda{|env| raise SecurityError, "a security error" }
+      end
+    end
+  end
+
+  def app
+    mock_app{}
+  end
+
 end
 
 RSpec.configure do |c|

data/spec/test_context.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+describe Rack::Robustness, 'the context in which blocks execute' do
+  include Rack::Test::Methods
+
+  let(:app){
+    mock_app do |g|
+      g.response{|ex|
+        raise "Invalid context" unless env && request
+        Rack::Response.new
+      }
+      g.body{|ex|
+        raise "Invalid context" unless env && request && response
+        if response.status == 400
+          "argument-error"
+        else
+          "security-error"
+        end
+      }
+      g.rescue(ArgumentError){|ex|
+        raise "Invalid context" unless env && request && response
+        400
+      }
+      g.rescue(SecurityError){|ex|
+        raise "Invalid context" unless env && request && response
+        403
+      }
+      g.ensure{|ex|
+        raise "Invalid context" unless env && request && response
+        $seen_ex = ex
+      }
+    end
+  }
+
+  it 'should let `env`, `request` and `response` be available in all blocks' do
+    get '/argument-error'
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq('argument-error')
+  end
+
+  it 'executes the ensure block as well' do
+    get '/argument-error'
+    expect($seen_ex).to be_a(ArgumentError)
+  end
+
+end

data/spec/test_ensure.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+describe Rack::Robustness, 'ensure' do
+  include Rack::Test::Methods
+
+  let(:app){
+    mock_app do |g|
+      g.ensure(true) {|ex| $seen_true  = [ex.class] }
+      g.ensure(false){|ex| $seen_false = [ex.class] }
+      g.ensure       {|ex| $seen_none  = [ex.class] }
+      g.status 400
+      g.on(ArgumentError){|ex| "error" }
+    end
+  }
+
+  before do
+    $seen_true = $seen_false = $seen_none = nil
+  end
+
+  it 'should be called in all cases when an error occurs' do
+    get '/argument-error'
+    expect(last_response.status).to eq(400)
+    expect(last_response.body).to eq("error")
+    expect($seen_true).to eq([ArgumentError])
+    expect($seen_false).to eq([ArgumentError])
+    expect($seen_none).to eq([ArgumentError])
+  end
+
+  it 'should not be called when explicit bypass on happy paths' do
+    get '/happy'
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).to eq("happy")
+    expect($seen_true).to be_nil
+    expect($seen_false).to eq([NilClass])
+    expect($seen_none).to eq([NilClass])
+  end
+
+end