roda 3.70.0 → 3.72.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d8ea04ca767f8be110f6ba14d1fd877a389a2e733e2925020f2ac589f6a9571
-  data.tar.gz: c9a2d26f41724c05ea1de5e8fb0058093e5fad34fb0c6479dd74badcfea67016
+  metadata.gz: d5c28e38d35f59176f159798f68d82bbd30df62a5907ace3a3750b1daf7b4fe6
+  data.tar.gz: cb5fd8d5a9d665bc820c55ccbf1fd6a068873ae3e265a1f877bbdf82b51c4d6e
 SHA512:
-  metadata.gz: 288a793976f389dfa2fe8fd55fb649590748cbe7ebb9da48f351117bb93da33ceee5848077f53c73430fd943b6be5b69a6d189e8b7424fe9ec60892dbaacff56
-  data.tar.gz: 3cad6d6823a2fbcd5534521b6e5fbcc7b85c04d1a80e9ca758cac6ab9b4b967a5f019b653de7d4de3c1d32069832f362fd2564ec219252b0f2dd8ccf1c0785c1
+  metadata.gz: d8710537511b8f332c443fd41bd279c99de53c0bc9618cd92f763ab7d354f70c4496ba9eafa076438087b5ab52f36e69f649aa00d2fb6f07d5315b7d61aef4a1
+  data.tar.gz: e0af216b465facc81e81ab8a495d472685c26aa6b2c1d56c0e48631586555f78f4d5922ac5ee92c6118a08b8162ee35866dc5708155bdbed70d5851b2ff8339b

data/CHANGELOG

@@ -1,3 +1,15 @@
+= 3.72.0 (2023-09-12)
+
+* Add invalid_request_body plugin for custom handling of invalid request bodies (jeremyevans)
+
+* Warn when defining method that expects 1 argument when block requires multiple arguments when :check_arity option is set to :warn (jeremyevans)
+
+* Implement the match_hooks plugin using the match_hook_args plugin (jeremyevans)
+
+= 3.71.0 (2023-08-14)
+
+* Add match_hook_args plugin, similar to match_hooks but support matchers and block args as hook arguments (jeremyevans)
+
 = 3.70.0 (2023-07-12)
 
 * Add plain_hash_response_headers plugin, using a plain hash for response headers on Rack 3 for much better performance (jeremyevans)

data/doc/release_notes/3.71.0.txt

@@ -0,0 +1,33 @@
+= New Feature
+
+* A match_hook_args plugin has been added.  This is similar to the
+  existing match_hook plugin, but passes through the matchers and
+  block arguments (values yielded to the match block). Example:
+
+    plugin :match_hook_args
+ 
+    add_match_hook do |matchers, block_args|
+      logger.debug("matchers: #{matchers.inspect}. #{block_args.inspect} yielded.")
+    end
+
+    # Term is an implicit matcher used for terminating matches, and
+    # will be included in the array of matchers yielded to the match hook
+    # if a terminating match is used.
+    term = self.class::RodaRequest::TERM
+
+    route do |r|
+      r.root do
+        # for a request for /
+        # matchers: nil, block_args: nil
+      end
+
+      r.on 'a', ['b', 'c'], Integer do |segment, id|
+        # for a request for /a/b/1
+        # matchers: ["a", ["b", "c"], Integer], block_args: ["b", 1]
+      end
+
+      r.get 'd' do
+        # for a request for /d
+        # matchers: ["d", term], block_args: []
+      end
+    end

data/doc/release_notes/3.72.0.txt

@@ -0,0 +1,48 @@
+= New Features
+
+* An invalid_request_body plugin has been added for allowing custom
+  handling of invalid request bodies.  Roda uses Rack's request body
+  parsing, and by default invalid request bodies can result in
+  different exceptions based on how the body is invalid and which
+  version of Rack is in use.
+
+  If you want to treat an invalid request body as the submission of
+  no parameters, you can use the :empty_hash argument when loading
+  the plugin:
+
+    plugin :invalid_request_body, :empty_hash
+
+  If you want to return a empty 400 (Bad Request) response if an
+  invalid request body is submitted, you can use the :empty_400
+  argument when loading the plugin:
+
+    plugin :invalid_request_body, :empty_400
+
+  If you want to raise a Roda::RodaPlugins::InvalidRequestBody::Error
+  exception if an invalid request body is submitted (which makes it
+  easier to handle these exceptions when using the error_handler
+  plugin), you can use the :raise argument when loading the plugin:
+
+    plugin :invalid_request_body, :raise
+
+  For custom behavior, you can pass a block when loading the plugin
+  The block is called with the exception Rack raised when parsing the
+  body. The block will be used to define a method in the application's
+  RodaRequest class.  It can either return a hash of parameters, or
+  you can raise a different exception, or you can halt processing and
+  return a response:
+
+    plugin :invalid_request_body do |exception|
+      # To treat the exception raised as a submitted parameter
+      {body_error: exception}
+    end
+
+= Other Improvements
+
+* When using the check_arity: :warn Roda option, Roda now correctly
+  warns when defining a method that expects a single argument when
+  the provided block requires multiple arguments.
+
+* The match_hooks plugin is now implemented using the match_hook_args
+  plugin, simplifying the implementation.  This change should be
+  transparent unless you were reaching into the internals.

data/lib/roda/plugins/invalid_request_body.rb

@@ -0,0 +1,107 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The invalid_request_body plugin allows for custom handling of invalid request
+    # bodies.  Roda uses Rack for parsing request bodies, so by default, any
+    # invalid request bodies would result in Rack raising an exception, and the
+    # exception could change for different reasons the request body is invalid.
+    # This plugin overrides RodaRequest#POST (which parses parameters from request
+    # bodies), and if parsing raises an exception, it allows for custom behavior.
+    # 
+    # If you want to treat an invalid request body as the submission of no parameters,
+    # you can use the :empty_hash argument when loading the plugin:
+    #
+    #   plugin :invalid_request_body, :empty_hash
+    #
+    # If you want to return a empty 400 (Bad Request) response if an invalid request
+    # body is submitted, you can use the :empty_400 argument when loading the plugin:
+    #
+    #   plugin :invalid_request_body, :empty_400
+    #
+    # If you want to raise a Roda::RodaPlugins::InvalidRequestBody::Error exception
+    # if an invalid request body is submitted (which makes it easier to handle these
+    # exceptions when using the error_handler plugin), you can use the :raise argument
+    # when loading the plugin:
+    #
+    #   plugin :invalid_request_body, :raise
+    #
+    # For custom behavior, you can pass a block when loading the plugin.  The block
+    # is called with the exception Rack raised when parsing the body. The block will
+    # be used to define a method in the application's RodaRequest class.  It can either
+    # return a hash of parameters, or you can raise a different exception, or you
+    # can halt processing and return a response:
+    #
+    #   plugin :invalid_request_body do |exception|
+    #     # To treat the exception raised as a submitted parameter
+    #     {body_error: exception}
+    #   end
+    module InvalidRequestBody
+      # Exception class raised for invalid request bodies.
+      Error = Class.new(RodaError)
+
+      # Set the action to use (:empty_400, :empty_hash, :raise) for invalid request bodies,
+      # or use a block for custom behavior.
+      def self.configure(app, action=nil, &block)
+        if action
+          if block
+            raise RodaError, "cannot provide both block and action when loading invalid_request_body plugin"
+          end
+
+          method = :"handle_invalid_request_body_#{action}"
+          unless RequestMethods.private_method_defined?(method)
+            raise RodaError, "invalid invalid_request_body action provided: #{action}"
+          end
+
+          app::RodaRequest.send(:alias_method, :handle_invalid_request_body, method)
+        elsif block
+          app::RodaRequest.class_eval do
+            define_method(:handle_invalid_request_body, &block)
+            alias handle_invalid_request_body handle_invalid_request_body
+          end
+        else
+          raise RodaError, "must provide block or action when loading invalid_request_body plugin"
+        end
+
+        app::RodaRequest.send(:private, :handle_invalid_request_body)
+      end
+
+      module RequestMethods
+        # Handle invalid request bodies as configured if the default behavior
+        # raises an exception.
+        def POST
+          super
+        rescue => e 
+          handle_invalid_request_body(e)
+        end
+
+        private
+
+        # Return an empty 400 HTTP response for invalid request bodies.
+        def handle_invalid_request_body_empty_400(e)
+          response.status = 400
+          headers = response.headers
+          headers.clear
+          headers[RodaResponseHeaders::CONTENT_TYPE] = 'text/html'
+          headers[RodaResponseHeaders::CONTENT_LENGTH] ='0'
+          throw :halt, response.finish_with_body([])
+        end
+
+        # Treat invalid request bodies by using an empty hash as the
+        # POST params.
+        def handle_invalid_request_body_empty_hash(e)
+          {}
+        end
+
+        # Raise a specific error for all invalid request bodies,
+        # to allow for easy rescuing using the error_handler plugin.
+        def handle_invalid_request_body_raise(e)
+          raise Error, e.message
+        end
+      end
+    end
+
+    register_plugin(:invalid_request_body, InvalidRequestBody)
+  end
+end

data/lib/roda/plugins/json.rb

@@ -52,6 +52,9 @@ class Roda
     # using the +:content_type+ option:
     #
     #   plugin :json, content_type: 'application/xml'
+    #
+    # This plugin depends on the custom_block_results plugin, and therefore does
+    # not support treating String, FalseClass, or NilClass values as JSON.
     module Json
       # Set the classes to automatically convert to JSON, and the serializer to use.
       def self.configure(app, opts=OPTS)

data/lib/roda/plugins/mail_processor.rb

@@ -379,7 +379,7 @@ class Roda
         end
 
         # Perform the processing of mail for this request, first considering
-        # routes defined via the the class-level +rcpt+ method, and then the
+        # routes defined via the class-level +rcpt+ method, and then the
         # normal routing tree passed in as the block.
         def process_mail(&block)
           if string_routes = opts[:mail_processor_string_routes]

data/lib/roda/plugins/match_hook.rb

@@ -4,7 +4,10 @@
 class Roda
   module RodaPlugins
     # The match_hook plugin adds hooks that are called upon a successful match
-    # by any of the matchers.
+    # by any of the matchers.  The hooks do not take any arguments.  If you would
+    # like hooks that pass the arguments/matchers and values yielded to the route block,
+    # use the match_hook_args plugin. This uses the match_hook_args plugin internally,
+    # but doesn't pass the matchers and values yielded.
     #
     #   plugin :match_hook
     #
@@ -12,56 +15,18 @@ class Roda
     #     logger.debug("#{request.matched_path} matched. #{request.remaining_path} remaining.")
     #   end
     module MatchHook
-      def self.configure(app)
-        app.opts[:match_hooks] ||= []
+      def self.load_dependencies(app)
+        app.plugin :match_hook_args
       end
 
       module ClassMethods
-        # Freeze the array of hook methods when freezing the app
-        def freeze
-          opts[:match_hooks].freeze
-          super
-        end
-
         # Add a match hook.
         def match_hook(&block)
-          opts[:match_hooks] << define_roda_method("match_hook", 0, &block)
-
-          if opts[:match_hooks].length == 1
-            class_eval("alias _match_hook #{opts[:match_hooks].first}", __FILE__, __LINE__)
-          else
-            class_eval("def _match_hook; #{opts[:match_hooks].join(';')} end", __FILE__, __LINE__)
-          end
-
-          public :_match_hook
-
+          meth = define_roda_method("match_hook", 0, &block)
+          add_match_hook{|_,_| send(meth)}
           nil
         end
       end
-
-      module InstanceMethods
-        # Default empty method if no match hooks are defined.
-        def _match_hook
-        end
-      end
-
-      module RequestMethods
-        private
-
-        # Call the match hook if yielding to the block before yielding to the block.
-        def if_match(_)
-          super do |*a|
-            scope._match_hook
-            yield(*a)
-          end
-        end
-
-        # Call the match hook before yielding to the block
-        def always
-          scope._match_hook
-          super
-        end
-      end
     end
 
     register_plugin :match_hook, MatchHook

data/lib/roda/plugins/match_hook_args.rb

@@ -0,0 +1,93 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The match_hook_args plugin adds hooks that are called upon a successful match
+    # by any of the matchers. It is similar to the match_hook plugin, but it allows
+    # for passing the matchers and block arguments for each match method.
+    #
+    #   plugin :match_hook_args
+    #
+    #   add_match_hook do |matchers, block_args|
+    #     logger.debug("matchers: #{matchers.inspect}. #{block_args.inspect} yielded.")
+    #   end
+    #
+    #   # Term is an implicit matcher used for terminating matches, and
+    #   # will be included in the array of matchers yielded to the match hook 
+    #   # if a terminating match is used.
+    #   term = self.class::RodaRequest::TERM
+    #
+    #   route do |r|
+    #     r.root do
+    #       # for a request for /
+    #       # matchers: nil, block_args: nil
+    #     end
+    #
+    #     r.on 'a', ['b', 'c'], Integer do |segment, id|
+    #       # for a request for /a/b/1
+    #       # matchers: ["a", ["b", "c"], Integer], block_args: ["b", 1]
+    #     end
+    #
+    #     r.get 'd' do
+    #       # for a request for /d
+    #       # matchers: ["d", term], block_args: []
+    #     end
+    #   end
+    module MatchHookArgs
+      def self.configure(app)
+        app.opts[:match_hook_args] ||= []
+      end
+
+      module ClassMethods
+        # Freeze the array of hook methods when freezing the app
+        def freeze
+          opts[:match_hook_args].freeze
+          super
+        end
+
+        # Add a match hook that will be called with matchers and block args.
+        def add_match_hook(&block)
+          opts[:match_hook_args] << define_roda_method("match_hook_args", :any, &block)
+
+          if opts[:match_hook_args].length == 1
+            class_eval("alias _match_hook_args #{opts[:match_hook_args].first}", __FILE__, __LINE__)
+          else
+            class_eval("def _match_hook_args(v, a); #{opts[:match_hook_args].map{|m| "#{m}(v, a)"}.join(';')} end", __FILE__, __LINE__)
+          end
+
+          public :_match_hook_args
+
+          nil
+        end
+      end
+
+      module InstanceMethods
+        # Default empty method if no match hooks are defined.
+        def _match_hook_args(matchers, block_args)
+        end
+      end
+
+      module RequestMethods
+        private
+
+        # Call the match hook with matchers and block args if yielding to the block before yielding to the block.
+        def if_match(v)
+          super do |*a|
+            scope._match_hook_args(v, a)
+            yield(*a)
+          end
+        end
+
+        # Call the match hook with nil matchers and blocks before yielding to the block
+        def always
+          scope._match_hook_args(nil, nil)
+          super
+        end
+      end
+    end
+
+    register_plugin :match_hook_args, MatchHookArgs
+  end
+end
+

data/lib/roda/plugins/typecast_params.rb

@@ -346,7 +346,7 @@ class Roda
         end
 
         # The reason behind this error.  If this error was caused by a conversion method,
-        # this will be the the conversion method symbol.  If this error was caused
+        # this will be the conversion method symbol.  If this error was caused
         # because a value was missing, then it will be +:missing+.  If this error was
         # caused because a value was not the correct type, then it will be +:invalid_type+.
         attr_accessor :reason

data/lib/roda/version.rb

@@ -4,7 +4,7 @@ class Roda
   RodaMajorVersion = 3
 
   # The minor version of Roda, updated for new feature releases of Roda.
-  RodaMinorVersion = 70
+  RodaMinorVersion = 72
 
   # The patch version of Roda, updated only for bug fixes from the last
   # feature release.

data/lib/roda.rb

@@ -88,6 +88,7 @@ class Roda
           end
           call_meth = meth
 
+          # RODA4: Switch to false # :warn in last Roda 3 version
           if (check_arity = opts.fetch(:check_arity, true)) && !block.lambda?
             required_args, optional_args, rest, keyword = _define_roda_method_arg_numbers(block)
 
@@ -117,6 +118,9 @@ class Roda
                 alias_method meth, meth
                 meth = :"#{meth}_arity"
               elsif required_args > 1
+                if check_arity == :warn
+                  RodaPlugins.warn "Arity mismatch in block passed to define_roda_method. Expected Arity 1, but multiple arguments required for #{block.inspect}"
+                end
                 b = block
                 block = lambda{|r| instance_exec(r, &b)} # Fallback
               end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roda
 version: !ruby/object:Gem::Version
-  version: 3.70.0
+  version: 3.72.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-12 00:00:00.000000000 Z
+date: 2023-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -244,6 +244,8 @@ extra_rdoc_files:
 - doc/release_notes/3.69.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.70.0.txt
+- doc/release_notes/3.71.0.txt
+- doc/release_notes/3.72.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
 files:
@@ -321,6 +323,8 @@ files:
 - doc/release_notes/3.69.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.70.0.txt
+- doc/release_notes/3.71.0.txt
+- doc/release_notes/3.72.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
 - lib/roda.rb
@@ -384,6 +388,7 @@ files:
 - lib/roda/plugins/host_authorization.rb
 - lib/roda/plugins/indifferent_params.rb
 - lib/roda/plugins/inject_erb.rb
+- lib/roda/plugins/invalid_request_body.rb
 - lib/roda/plugins/json.rb
 - lib/roda/plugins/json_parser.rb
 - lib/roda/plugins/link_to.rb
@@ -391,6 +396,7 @@ files:
 - lib/roda/plugins/mailer.rb
 - lib/roda/plugins/match_affix.rb
 - lib/roda/plugins/match_hook.rb
+- lib/roda/plugins/match_hook_args.rb
 - lib/roda/plugins/middleware.rb
 - lib/roda/plugins/middleware_stack.rb
 - lib/roda/plugins/module_include.rb