roda 3.66.0 → 3.68.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52a6bb08790a0a3414771a5d772a27d98089a96a306812ddb781ce31724289f0
-  data.tar.gz: 8679931319b2abf3b8aba64151664cf2d154517fbfd5020ded910e5ba32452a0
+  metadata.gz: faad040bd1e251d705afbfe6ced40794aa2f135658168c85603a6c8a83a497be
+  data.tar.gz: 6e1d78ffdf0442835a754e54fc6216d8f668f3d0cb8e9c5635c1a582b17d5746
 SHA512:
-  metadata.gz: 4ace69f14606887e7243a5ec00598d8a3ded4230e8fbdf849c801579f38c9242ca87c5ab48887aeba65911cbcf49e675e768c077d20680e9693c5989180218b7
-  data.tar.gz: 7986400736b3631524c3427f135a8d3cb9da04da0d1413f59d764fd8c5b7c4ee6f81be9a3b92d848c5546229b7bd7f236278cfe41cb12410c34def542762d1f9
+  metadata.gz: a663960b5f5c5391a44102b1b255fbb5546f241c2386b6fdbe8a5050f434407332f239eb0c862ab877de239ec1b4ea39c4f9202c488672a846c5f8eabaef6379
+  data.tar.gz: 508fa08ad66e1b11b5abc552345067fc2517aeb10ea060c6298a337b44db453c5daf35a0bbafe399dd9167286fd9ea35c07d75c340f640a6198beb52367352d5

data/CHANGELOG

@@ -1,3 +1,11 @@
+= 3.68.0 (2023-05-11)
+
+* Make Roda.run in multi_run plugin accept blocks to allow autoloading the apps to dispatch to (jeremyevans)
+
+= 3.67.0 (2023-04-12)
+
+* Add custom_block_results plugin for registering custom block result handlers (jeremyevans)
+
 = 3.66.0 (2023-03-13)
 
 * Support overriding exception page assets via exception_page_{css,js} instance methods (jeremyevans) (#306)

data/doc/release_notes/3.67.0.txt

@@ -0,0 +1,25 @@
+= New Feature
+
+* A custom_block_results plugin has been added for custom handling
+  of block results.  This allows routing blocks to return
+  arbitrary objects instead of just String, nil, and false, and
+  to have custom handling for them. For example, if you want to
+  be able to have your routing blocks return the status code to use,
+  you could do:
+
+    plugin :custom_block_results
+
+    handle_block_result Integer do |result|
+      response.status_code = result
+    end
+
+    route do |r|
+      200
+    end
+
+  While the expected use of the handle_block_result method is with
+  class arguments, you can use any argument that implements an
+  appropriate === method.
+
+  The symbol_views and json plugins, which support additional block
+  results, now use the custom_block_results plugin internally.

data/doc/release_notes/3.68.0.txt

@@ -0,0 +1,21 @@
+= New Feature
+
+* Roda.run in the multi_run plugin now accepts blocks, to allow
+  autoloading of apps to dispatch to:
+
+    class App < Roda
+      plugin :multi_run
+
+      run("other_app"){OtherApp}
+
+      route do |r|
+        r.multi_run
+      end
+    end
+
+  With the above example, the block is not evaluated until a
+  request for the /other_app branch is received.  If OtherApp is
+  autoloaded, this can speed up application startup and partial
+  testing. When freezing the application (for production use),
+  the block is eagerly loaded, so that requests to the
+  /other_app branch do not call the block on every request.

data/lib/roda/plugins/custom_block_results.rb

@@ -0,0 +1,68 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The custom_block_results plugin allows you to specify handling
+    # for different block results.  By default, Roda only supports
+    # nil, false, and string block results, but using this plugin,
+    # you can support other block results.
+    #
+    # For example, if you wanted to support returning Integer
+    # block results, and have them set the response status code,
+    # you could do:
+    #
+    #   plugin :custom_block_results
+    #
+    #   handle_block_result Integer do |result|
+    #     response.status_code = result
+    #   end
+    #
+    #   route do |r|
+    #     200
+    #   end
+    #
+    # The expected use case for this is to customize behavior by
+    # class, but matching uses ===, so it is possible to use non-class
+    # objects that respond to === appropriately.
+    #
+    # Note that custom block result handling only occurs if the types
+    # are not handled by Roda itself.  You cannot use this to modify
+    # the handling of nil, false, or string results.
+    module CustomBlockResults
+      def self.configure(app)
+        app.opts[:custom_block_results] ||= {}
+      end
+
+      module ClassMethods
+        # Freeze the configured custom block results when freezing the app.
+        def freeze
+          opts[:custom_block_results].freeze
+          super
+        end
+
+        # Specify a block that will be called when an instance of klass
+        # is returned as a block result.  The block defines a method.
+        def handle_block_result(klass, &block)
+          opts[:custom_block_results][klass] = define_roda_method(opts[:custom_block_results][klass] || "custom_block_result_#{klass}", 1, &block)
+        end
+      end
+
+      module RequestMethods
+        private
+
+        # Try each configured custom block result, and call the related method
+        # to get the block result.
+        def unsupported_block_result(result)
+          roda_class.opts[:custom_block_results].each do |klass, meth|
+            return scope.send(meth, result) if klass === result
+          end
+
+          super
+        end
+      end
+    end
+
+    register_plugin(:custom_block_results, CustomBlockResults)
+  end
+end

data/lib/roda/plugins/json.rb

@@ -55,11 +55,17 @@ class Roda
     module Json
       # Set the classes to automatically convert to JSON, and the serializer to use.
       def self.configure(app, opts=OPTS)
+        app.plugin :custom_block_results
+
         classes = opts[:classes] || [Array, Hash]
         app.opts[:json_result_classes] ||= []
         app.opts[:json_result_classes] += classes
-        app.opts[:json_result_classes].uniq!
-        app.opts[:json_result_classes].freeze
+        classes = app.opts[:json_result_classes]
+        classes.uniq!
+        classes.freeze
+        classes.each do |klass|
+          app.opts[:custom_block_results][klass] = :handle_json_block_result
+        end
 
         app.opts[:json_result_serializer] = opts[:serializer] || app.opts[:json_result_serializer] || app.opts[:json_serializer] || :to_json.to_proc
 
@@ -71,32 +77,34 @@ class Roda
       module ClassMethods
         # The classes that should be automatically converted to json
         def json_result_classes
+          # RODA4: remove, only used by previous implementation.
           opts[:json_result_classes]
         end
       end
 
+      module InstanceMethods
+        # Handle a result for one of the registered JSON result classes
+        # by converting the result to JSON.
+        def handle_json_block_result(result)
+          @_response['Content-Type'] ||= opts[:json_result_content_type]
+          @_request.send(:convert_to_json, result)
+        end
+      end
+
       module RequestMethods
         private
 
-        # If the result is an instance of one of the json_result_classes,
-        # convert the result to json and return it as the body, using the
-        # application/json content-type.
-        def block_result_body(result)
-          case result
-          when *roda_class.json_result_classes
-            response['Content-Type'] ||= roda_class.opts[:json_result_content_type]
-            convert_to_json(result)
-          else
-            super
-          end
-        end
-
         # Convert the given object to JSON.  Uses to_json by default,
         # but can use a custom serializer passed to the plugin.
-        def convert_to_json(obj)
-          args = [obj]
-          args << self if roda_class.opts[:json_result_include_request]
-          roda_class.opts[:json_result_serializer].call(*args)
+        def convert_to_json(result)
+          opts = roda_class.opts
+          serializer = opts[:json_result_serializer]
+
+          if opts[:json_result_include_request]
+            serializer.call(result, self)
+          else
+            serializer.call(result)
+          end
         end
       end
     end

data/lib/roda/plugins/multi_run.rb

@@ -17,7 +17,7 @@ class Roda
     #   App.run "ro", OtherRodaApp
     #   App.run "si", SinatraApp
     #
-    # Inside your route block, you can call r.multi_run to dispatch to all
+    # Inside your route block, you can call +r.multi_run+ to dispatch to all
     # three rack applications based on the prefix:
     #
     #   App.route do |r|
@@ -28,7 +28,7 @@ class Roda
     # starting with +/ro+ to +OtherRodaApp+, and routes starting with +/si+ to
     # SinatraApp.
     #
-    # You can pass a block to +multi_run+ that will be called with the prefix,
+    # You can pass a block to +r.multi_run+ that will be called with the prefix,
     # before dispatching to the rack app:
     #
     #   App.route do |r|
@@ -39,12 +39,26 @@ class Roda
     #
     # This is useful for modifying the environment before passing it to the rack app.
     #
-    # The multi_run plugin is similar to the multi_route plugin, with the difference
-    # being the multi_route plugin keeps all routing subtrees in the same Roda app/class,
-    # while multi_run dispatches to other rack apps.  If you want to isolate your routing
-    # subtrees, multi_run is a better approach, but it does not let you set instance
-    # variables in the main Roda app and have those instance variables usable in
-    # the routing subtrees.
+    # You can also call +Roda.run+ with a block:
+    #
+    #   App.run("ra"){PlainRackApp}
+    #   App.run("ro"){OtherRodaApp}
+    #   App.run("si"){SinatraApp}
+    #
+    # When called with a block, Roda will call the block to get the app to dispatch to
+    # every time the block is called.  The expected usage is with autoloaded classes,
+    # so that the related classes are not loaded until there is a request for the
+    # related route.  This can sigficantly speedup startup or testing a subset of the
+    # application.  When freezing an application, the blocks are called once to get the
+    # app to dispatch to, and that is cached, to ensure the any autoloads are completed
+    # before the application is frozen.
+    #
+    # The multi_run plugin is similar to the hash_branches and multi_route plugins, with
+    # the difference being the hash_branches and multi_route plugins keep all routing
+    # subtrees in the same Roda app/class, while multi_run dispatches to other rack apps.
+    # If you want to isolate your routing subtrees, multi_run is a better approach, but
+    # it does not let you set instance variables in the main Roda app and have those
+    # instance variables usable in the routing subtrees.
     #
     # To handle development environments that reload code, you can call the
     # +run+ class method without an app to remove dispatching for the prefix.
@@ -52,12 +66,21 @@ class Roda
       # Initialize the storage for the dispatched applications
       def self.configure(app)
         app.opts[:multi_run_apps] ||= {}
+        app.opts[:multi_run_app_blocks] ||= {}
       end
 
       module ClassMethods
+        # Convert app blocks into apps by calling them, in order to force autoloads
+        # and to speed up subsequent calls.
         # Freeze the multi_run apps so that there can be no thread safety issues at runtime.
         def freeze
-          opts[:multi_run_apps].freeze
+          app_blocks = opts[:multi_run_app_blocks]
+          apps = opts[:multi_run_apps]
+          app_blocks.each do |prefix, block|
+            apps[prefix] = block.call
+          end
+          app_blocks.clear.freeze
+          apps.freeze
           self::RodaRequest.refresh_multi_run_regexp!
           super
         end
@@ -69,12 +92,22 @@ class Roda
         end
 
         # Add a rack application to dispatch to for the given prefix when
-        # r.multi_run is called.
-        def run(prefix, app=nil)
-          if app
-            multi_run_apps[prefix.to_s] = app
+        # r.multi_run is called. If a block is given, it is called every time
+        # there is a request for the route to get the app to call. If neither
+        # a block or an app is provided, any stored route for the prefix is
+        # removed.  It is an error to provide both an app and block in the same call.
+        def run(prefix, app=nil, &block)
+          prefix = prefix.to_s
+          if app 
+            raise Roda::RodaError, "cannot provide both app and block to Roda.run" if block
+            opts[:multi_run_apps][prefix] = app
+            opts[:multi_run_app_blocks].delete(prefix)
+          elsif block
+            opts[:multi_run_apps].delete(prefix)
+            opts[:multi_run_app_blocks][prefix] = block
           else
-            multi_run_apps.delete(prefix.to_s)
+            opts[:multi_run_apps].delete(prefix)
+            opts[:multi_run_app_blocks].delete(prefix)
           end
           self::RodaRequest.refresh_multi_run_regexp!
         end
@@ -84,7 +117,7 @@ class Roda
         # Refresh the multi_run_regexp, using the stored route prefixes,
         # preferring longer routes before shorter routes.
         def refresh_multi_run_regexp!
-          @multi_run_regexp = /(#{Regexp.union(roda_class.multi_run_apps.keys.sort.reverse)})/
+          @multi_run_regexp = /(#{Regexp.union((roda_class.opts[:multi_run_apps].keys + roda_class.opts[:multi_run_app_blocks].keys).sort.reverse)})/
         end
 
         # Refresh the multi_run_regexp if it hasn't been loaded yet.
@@ -95,11 +128,12 @@ class Roda
 
       module RequestMethods
         # If one of the stored route prefixes match the current request,
-        # dispatch the request to the stored rack application.
+        # dispatch the request to the appropriate rack application.
         def multi_run
           on self.class.multi_run_regexp do |prefix|
             yield prefix if defined?(yield)
-            run scope.class.multi_run_apps[prefix]
+            opts = scope.opts
+            run(opts[:multi_run_apps][prefix] || opts[:multi_run_app_blocks][prefix].call)
           end
         end
       end

data/lib/roda/plugins/symbol_views.rb

@@ -23,18 +23,9 @@ class Roda
     #     :foo
     #   end
     module SymbolViews
-      module RequestMethods
-        private
-
-        # If the block result is a symbol, consider the symbol a
-        # template name and use the template view as the body.
-        def block_result_body(result)
-          if result.is_a?(Symbol)
-            scope.view(result)
-          else
-            super
-          end
-        end
+      def self.configure(app)
+        app.plugin :custom_block_results
+        app.opts[:custom_block_results][Symbol] = :view
       end
     end
 

data/lib/roda/request.rb

@@ -547,7 +547,7 @@ class Roda
           when nil, false
             # nothing
           else
-            raise RodaError, "unsupported block result: #{result.inspect}"
+            unsupported_block_result(result)
           end
         end
 
@@ -652,6 +652,12 @@ class Roda
           end
         end
 
+        # How to handle block results that are not nil, false, or a String.
+        # By default raises an exception.
+        def unsupported_block_result(result)
+          raise RodaError, "unsupported block result: #{result.inspect}"
+        end
+
         # Handle an unsupported matcher.
         def unsupported_matcher(matcher)
           raise RodaError, "unsupported matcher: #{matcher.inspect}"

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 = 66
+  RodaMinorVersion = 68
 
   # The patch version of Roda, updated only for bug fixes from the last
   # feature release.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roda
 version: !ruby/object:Gem::Version
-  version: 3.66.0
+  version: 3.68.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-13 00:00:00.000000000 Z
+date: 2023-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -239,6 +239,8 @@ extra_rdoc_files:
 - doc/release_notes/3.64.0.txt
 - doc/release_notes/3.65.0.txt
 - doc/release_notes/3.66.0.txt
+- doc/release_notes/3.67.0.txt
+- doc/release_notes/3.68.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
@@ -312,6 +314,8 @@ files:
 - doc/release_notes/3.64.0.txt
 - doc/release_notes/3.65.0.txt
 - doc/release_notes/3.66.0.txt
+- doc/release_notes/3.67.0.txt
+- doc/release_notes/3.68.0.txt
 - doc/release_notes/3.7.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
@@ -342,6 +346,7 @@ files:
 - lib/roda/plugins/content_security_policy.rb
 - lib/roda/plugins/cookies.rb
 - lib/roda/plugins/csrf.rb
+- lib/roda/plugins/custom_block_results.rb
 - lib/roda/plugins/custom_matchers.rb
 - lib/roda/plugins/default_headers.rb
 - lib/roda/plugins/default_status.rb
@@ -469,7 +474,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Routing tree web toolkit