scorched 1.1.0.pre → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5df1a902354207de82c8dcb0a6f00c68d9455d20edc05b3e70a5ef2c806a229a
-  data.tar.gz: 2bd5dac53da50545d9d6f0d832e7928aeefb07ebfcbbd1749c300b0fd71355e4
+  metadata.gz: 9e9063c14895226f457fcb9255e206f5915a8aaefde84be0114dabbf4723a677
+  data.tar.gz: e773ac700d17abe3b3ce00f94be2665e4753bacffee9ce07fc4e86a00f35afec
 SHA512:
-  metadata.gz: 3becda9a8c64fd085500003132cd5bd982d3ba6b67c33c5cabe9d4011377df4072f76e79baedd34a2544ee1546c105305e506dd1b2c5347844fd3742abf396a4
-  data.tar.gz: 51988a63c584113976d5a99080174d0d008e08f91f1f1aac17d74b25d353e514e54a7a1a1ea95385a96fdba187846a543be82b933721936387fd9b439ceef849
+  metadata.gz: 2444d1752e6296881377c74c21a6219b19b9ef415165e89382d4b9f3d80b8e7030c5997cf8fcffeb6377c5f58cd96431019f170ee75577210564798b61514764
+  data.tar.gz: 61dae3a5d9f0d4d35d53be9db55c157d0e0cbdeee1bcf504a0d9069fa674ad993e95c865ddcf8165d78ed5c2dd1f567184baecc1be90f69017d329f79642e75c

data/CHANGES.md

@@ -1,6 +1,21 @@
 Changelog
 =========
 
+### v1.1.1
+* Fixed frozen string mutation in `absolute` method.
+### v1.1.0
+* Added `around` filters to allow wrapping application logic around a request. `around` filters wrap around `before/after` filters. Ideal for `begin...ensure...end` where you need to ensure something happens before the request processing ends. For example:
+    ```
+    around do |cont|
+        begin
+            cont.call
+        ensure
+            # Ensure something important happens here
+        end
+    end
+    ```
+* Compatible with Ruby 4.0
+
 ### v1.1.0.pre
 * Updated dependancies
 * Now compatible with (and requires) Rack 3.x

data/docs/02_fundamentals/03_routing.md

@@ -117,7 +117,7 @@ Conditions are essentially just pre-requisites that must be met before a mapping
 * `:host` - The host name (i.e. domain name) used in the request.
 * `:language` - Languages accepted by the client.
 * `:media_type` - Media types (i.e. content types) accepted by the client.
-* `:handled` - Whether a mapping in the controller instance was invoked as the target for the request. A mapping that _passes_ a request is not considered a match.
+* `:dispatched` - Whether a mapping in the controller instance was invoked as the target for the request. A mapping that _passes_ a request is not considered dispatched.
 * `:method` - The request method used, e.g. GET, POST, PUT, ... .
 * `:proc` - An on-the-fly condition to be evaluated in the context of the controller instance. Should return true if the condition was satisfied, or false otherwise.
 * `:user_agent` - The user agent string provided with the request. Takes a Regexp or String.

data/docs/02_fundamentals/05_filters.md

@@ -42,6 +42,25 @@ end
 How you use filters is up to your own imagination and creative problem solving.
 
 
+Around Filters
+--------------
+Around filters wrap the entire before/dispatch/after cycle. The block is passed a single argument - a proc representing the rest of the filter chain - which it must call (e.g. `cont.call`) for request handling to proceed. If the block doesn't call it, the wrapped request chain never runs.
+
+Around filters defined earlier (including those defined in superclasses) wrap those defined later. Around filters are ideal for `begin...ensure...end`-style wrapping, where you need to guarantee something happens once the request has finished processing.
+
+```ruby
+around do |cont|
+  begin
+    cont.call
+  ensure
+    # Ensure something important happens here
+  end
+end
+```
+
+Like before and after filters, around filters can have conditions defined on them.
+
+
 Error Filters
 -------------
 Error filters are processed like regular filters, except they're called whenever an exception occurs. If an error filter returns false, it's assumed to be unhandled, and the next error filter is called. This continues until one of the following is true, 1) an error filter returns true, in which case the exception is assumed to be handled, 2) an error filter raises an exception itself, or 3) there are no more error handlers defined on the current controller, in which case the exception is re-raised.

data/lib/scorched/controller.rb

@@ -10,6 +10,7 @@ module Scorched
     include Scorched::Options('symbol_matchers')
     include Scorched::Collection('middleware')
     include Scorched::Collection('before_filters')
+    include Scorched::Collection('around_filters')
     include Scorched::Collection('after_filters', true)
     include Scorched::Collection('error_filters')
 
@@ -108,7 +109,7 @@ module Scorched
       end
 
       def filters
-        @filters ||= {before: before_filters, after: after_filters, error: error_filters}
+        @filters ||= {before: before_filters, around: around_filters, after: after_filters, error: error_filters}
       end
 
       def call(env)
@@ -213,6 +214,16 @@ module Scorched
         filter(:after, force: force, conditions: conditions, &block)
       end
 
+      # Syntactic sugar for defining an around filter.
+      # The block is passed a single argument - a proc representing the rest of the filter chain (including the
+      # eventual dispatch to before/matching/after processing). The block must call it (e.g. `cont.call`) for
+      # request handling to proceed; if it doesn't, the wrapped chain simply never runs.
+      # Around filters defined earlier (including those defined in superclasses) wrap those defined later, with the
+      # innermost proc being the actual before/dispatch/after cycle.
+      def around(**conditions, &block)
+        filter(:around, conditions: conditions, &block)
+      end
+
       # Syntactic sugar for defining an error filter.
       # Takes one or more optional exception classes for which this error filter should handle. Handles all exceptions
       # by default.
@@ -286,26 +297,29 @@ module Scorched
         end
       end
 
-      begin
-        if config[:strip_trailing_slash] == :redirect && request.path =~ %r{[^/]/+$}
-          query_string = request.query_string.empty? ? '' : '?' << request.query_string
-          redirect(request.path.chomp('/') + query_string, status: 307, halt: false)
-          return response.finish
-        end
-        pass if config[:auto_pass] && eligable_matches.empty?
-
-        if run_filters(:before)
-          catch(:halt) {
-            begin
-              try_matches
-            rescue => inner_error
-              rescue_block.call(inner_error)
-            end
-          }
+      if config[:strip_trailing_slash] == :redirect && request.path =~ %r{[^/]/+$}
+        query_string = request.query_string.empty? ? '' : '?' << request.query_string
+        redirect(request.path.chomp('/') + query_string, status: 307, halt: false)
+        return response.finish
+      end
+
+      run_around_filters do
+        begin
+          pass if config[:auto_pass] && eligable_matches.empty?
+
+          if run_ba_filters(:before)
+            catch(:halt) {
+              begin
+                try_matches
+              rescue => inner_error
+                rescue_block.call(inner_error)
+              end
+            }
+          end
+          run_ba_filters(:after)
+        rescue => outer_error
+          outer_error == inner_error ? raise : catch(:halt) { rescue_block.call(outer_error) }
         end
-        run_filters(:after)
-      rescue => outer_error
-        outer_error == inner_error ? raise : catch(:halt) { rescue_block.call(outer_error) }
       end
       response.finish
     end
@@ -328,6 +342,9 @@ module Scorched
     # Overriding this method provides the opportunity for one to have more control over how mapping targets are invoked.
     def dispatch(match)
       @_dispatched = true
+      if String === match.mapping[:target] || Symbol === match.mapping[:target]
+        match.mapping[:target] = Object.const_get(match.mapping[:target]) # Resolve symbol to constant, and replace target to avoid future lookups
+      end
       target = match.mapping[:target]
       response.merge! begin
         if Proc === target
@@ -556,9 +573,10 @@ module Scorched
       else
         env['scorched.root_path']
       end
-      abs.insert(0, '/') unless abs[0] == '/'
+      abs = "/#{abs}" unless abs[0] == '/'
       abs
     end
+    
 
     # We always want this filter to run at the end-point controller, hence we include the conditions within the body of
     # the filter.
@@ -595,21 +613,48 @@ module Scorched
 
   private
 
-    # Returns false if any of the filters halted the request. True otherwise.
-    def run_filters(type)
+    # Wraps the given block with the chain of around filters, outermost first, and calls it. Each filter is passed
+    # a proc representing the rest of the chain (the next around filter, or the wrapped block if there are no more),
+    # and is responsible for calling it to continue processing the request.
+    # As with before/after filters, a filter inherited by both an outer and inner controller (e.g. via `controller`
+    # sub-mapping) only runs once per request, tracked via the shared `env`.
+    def run_around_filters(&core)
+      tracker = filter_tracker(:around)
+      chain = filters[:around].to_a.reverse.reduce(core) do |inner, f|
+        proc do
+          if tracker.include?(f) || check_for_failed_condition(f[:conditions])
+            inner.call
+          else
+            tracker << f
+            instance_exec(inner, &f[:proc])
+          end
+        end
+      end
+      catch(:halt) { chain.call }
+    end
+
+    # Returns false if any of the before/after filters halted the request. True otherwise.
+    def run_ba_filters(type)
       halted = false
-      tracker = env['scorched.executed_filters'] ||= {before: Set.new, after: Set.new}
-      filters[type].reject { |f| tracker[type].include?(f) }.each do |f|
+      tracker = filter_tracker(type)
+      filters[type].reject { |f| tracker.include?(f) }.each do |f|
         unless check_for_failed_condition(f[:conditions]) || (halted && !f[:force])
-          tracker[type] << f
-          halted = true unless run_filter(f)
+          tracker << f
+          halted = true unless run_ba_filter(f)
         end
       end
       !halted
     end
 
-    # Returns false if the filter halted. True otherwise.
-    def run_filter(f)
+    # Returns the set of filters of the given type that have already executed for this request, tracked in `env` so
+    # an inherited filter isn't run twice across nested controller dispatches.
+    def filter_tracker(type)
+      tracker = env['scorched.executed_filters'] ||= {}
+      tracker[type] ||= Set.new
+    end
+
+    # Returns false if the before/after filter halted. True otherwise.
+    def run_ba_filter(f)
       catch(:halt) do
         instance_exec(&f[:proc])
         return true

data/lib/scorched/version.rb

@@ -1,3 +1,3 @@
 module Scorched
-  VERSION = '1.1.0.pre'
+  VERSION = '1.1.1'
 end

data/scorched.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new 'scorched', Scorched::VERSION do |s|
   s.add_dependency 'rack-accept', '~> 0.4' # Used for Accept-Charset, Accept-Encoding and Accept-Language headers.
   s.add_dependency 'scorched-accept', '~> 0.1' # Used for Accept header.
   s.add_dependency 'tilt', '~> 2.0'
+  s.add_dependency 'logger', '~> 1.7'
   s.add_development_dependency 'rack-test', '>= 1.0'
   s.add_development_dependency 'rspec', '>= 3.4'
   s.add_development_dependency 'rake', '>= 10.4'

data/spec/controller_spec.rb

@@ -421,7 +421,7 @@ module Scorched
       end
     end
 
-    describe "before/after filters" do
+    describe "before/after/around filters" do
       they "run directly before and after the target action" do
         order = []
         app.get('/') { order << :action }
@@ -540,6 +540,101 @@ module Scorched
       end
     end
 
+    describe "after filters" do
+      they "wrap around the before/action/after cycle, outermost first" do
+        order = []
+        app.around { |cont| order << :first_before; cont.call; order << :first_after }
+        app.around { |cont| order << :second_before; cont.call; order << :second_after }
+        app.before { order << :before }
+        app.after { order << :after }
+        app.get('/') { order << :action }
+        rt.get('/')
+        order.should == %i{first_before second_before before action after second_after first_after}
+      end
+
+      they "run in the context of the controller (same as the route)" do
+        route_instance = nil
+        around_instance = nil
+        app.get('/') { route_instance = self }
+        app.around { |cont| around_instance = self; cont.call }
+        rt.get('/')
+        route_instance.should == around_instance
+      end
+
+      they "run even if no route matches" do
+        counter = 0
+        app.around { |cont| counter += 1; cont.call }
+        rt.delete('/').status.should == 404
+        counter.should == 1
+      end
+
+      they "can take an optional set of conditions" do
+        counter = 0
+        app.around(method: ['GET', 'PUT']) { |cont| counter += 1; cont.call }
+        app.get('/') { }
+        app.put('/') { }
+        rt.post('/')
+        rt.get('/')
+        rt.put('/')
+        counter.should == 2
+      end
+
+      they "skip the target action, and everything else in the chain, if the continuation is never called" do
+        action_called = false
+        app.before { }
+        app.around { |cont| }
+        app.get('/') { action_called = true }
+        rt.get('/').status.should == 200
+        action_called.should == false
+      end
+
+      they "still unwind (run code after the continuation) even if the action halts" do
+        order = []
+        app.around { |cont| order << :before; cont.call; order << :after }
+        app.get('/') { order << :action; halt 200, 'stopped' }
+        response = rt.get('/')
+        response.body.should == 'stopped'
+        order.should == %i{before action after}
+      end
+
+      they "still unwind even if the action raises, once the error is handled" do
+        order = []
+        app.around { |cont| order << :before; cont.call; order << :after }
+        app.get('/') { raise 'boom' }
+        app.error { |e| order << :error; halt 500 }
+        rt.get('/').status.should == 500
+        order.should == %i{before error after}
+      end
+      
+      describe "nesting" do
+        example "around filters inherit but only run once" do
+          around_counter = 0
+          app.around { |cont| around_counter += 1; cont.call }
+          subcontroller = app.controller { get('/') { 'wow' } }
+          subcontroller.filters[:around].should == app.filters[:around]
+
+          rt.get('/')
+          around_counter.should == 1
+
+          # Hitting the subcontroller directly should yield the same results.
+          around_counter = 0
+          Rack::Test::Session.new(subcontroller).get('/')
+          around_counter.should == 1
+        end
+
+        example "around filters wrap from outermost to innermost" do
+          order = []
+          app.around { |cont| order << :outer_before; cont.call; order << :outer_after }
+          app.controller do
+            around { |cont| order << :inner_before; cont.call; order << :inner_after }
+            get('/') { order << :action }
+          end
+          rt.get('/')
+          order.should == %i{outer_before inner_before action inner_after outer_after}
+        end
+      end
+    end
+
     describe "error filters" do
       let(:app) do
         Class.new(Scorched::Controller) do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: scorched
 version: !ruby/object:Gem::Version
-  version: 1.1.0.pre
+  version: 1.1.1
 platform: ruby
 authors:
 - Tom Wardrop
 bindir: bin
 cert_chain: []
-date: 2025-02-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -79,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
@@ -202,7 +216,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 4.0.13
 specification_version: 4
 summary: Light-weight, DRY as a desert, web framework for Ruby
 test_files: