roda 3.65.0 → 3.67.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1c9c4301b4c90cb2f2c7a2d190986b4b6c68c4e1eb4b0be59bdba2aebdf6780
-  data.tar.gz: 576b15ba70cdab634638bce683ba8ee8ac93feb9fe5f3ae8982cf6ae07c6d686
+  metadata.gz: 0ea9212a800294ebf286d593e230ac925aced0d5e7c118fa7541b3fd6a5cc983
+  data.tar.gz: 9a591fdf0b2b481f71cbf871a70b3f83a8cac4bca4c3fe399348dfeee2447a13
 SHA512:
-  metadata.gz: 91b24c2bbcb2d2c27c14f242d620fab9d5e838f68bc102887018e41e4e05f5eb93718ab312c727a32ac4ab6df0dbcf4d0bb134499674dee71e991e953ecac85b
-  data.tar.gz: 9fe4592c67425c171926368d1121841dcafae686eb6822439536c24040788049041f34dffae22fde1ba2905f63c0e3abd13a5938ea263f4b143fdb94219e66f1
+  metadata.gz: 7f5887a701034ac935d6bb1f14a454f6dfe03751ec7842e383f401555f46d021d8bb502658959a5edae9d4199d8e8bfc785721d3386b76f0b6b280c7731fad3d
+  data.tar.gz: eb7de74ded26221a86664644ceddda6428e877bdf158acd988319c56bdc335955b506623cc9d8fb3c71376c877d4e00254c018c4341debd221a6439d9557e6ed

data/CHANGELOG

@@ -1,3 +1,15 @@
+= 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)
+
+* Avoid keeping reference to Roda instance that caches an inline template (jeremyevans)
+
+* Add render_coverage plugin, using tilt 2.1 features to allow for compiled templates in Ruby <3.2 (jeremyevans)
+
 = 3.65.0 (2023-02-13)
 
 * Make indifferent_params plugin work with changes in rack main branch (jeremyevans)

data/doc/release_notes/3.66.0.txt

@@ -0,0 +1,23 @@
+= New Features
+
+* A render_coverage plugin has been added, which will cause compiled
+  template code to be saved to a folder and loaded using load instead
+  of eval. This allows for coverage to work for the compiled template
+  code in Ruby versions before 3.2.  It can also allow for verbose
+  syntax warnings in compiled template code (ignored by eval), and
+  can also be useful for static analysis of compiled template code.
+  This plugin requires tilt 2.1+.
+
+* The exception_page plugin now supports exception_page_{css,js}
+  instance methods for overriding the CSS and JavaScript on the
+  generated exception page.
+
+= Other Improvements
+
+* Using inline templates (render/view :inline option) no longer keeps
+  a reference to the Roda instance that caches the template.
+
+= Backwards Compatibility
+
+* The Render::TemplateMtimeWrapper API has changed.  Any external
+  use of this class needs to be updated.

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/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/exception_page.rb

@@ -227,7 +227,7 @@ END
 
             css = case css_file
             when nil
-              "<style type=\"text/css\">#{ExceptionPage.css}</style>"
+              "<style type=\"text/css\">#{exception_page_css}</style>"
             when false
               # :nothing
             else
@@ -236,7 +236,7 @@ END
 
             js = case js_file
             when nil
-              "<script type=\"text/javascript\">\n//<!--\n#{ExceptionPage.js}\n//-->\n</script>"
+              "<script type=\"text/javascript\">\n//<!--\n#{exception_page_js}\n//-->\n</script>"
             when false
               # :nothing
             else
@@ -399,6 +399,16 @@ END
           end
         end
 
+        # The CSS to use on the exception page
+        def exception_page_css
+          ExceptionPage.css
+        end
+
+        # The JavaScript to use on the exception page
+        def exception_page_js
+          ExceptionPage.js
+        end
+
         private
 
         if RUBY_VERSION >= '3.2'
@@ -420,11 +430,11 @@ END
         def exception_page_assets
           get 'exception_page.css' do
             response['Content-Type'] = "text/css"
-            ExceptionPage.css
+            scope.exception_page_css
           end
           get 'exception_page.js' do
             response['Content-Type'] = "application/javascript"
-            ExceptionPage.js
+            scope.exception_page_js
           end
         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/render.rb

@@ -320,14 +320,16 @@ class Roda
       # template file has been modified.  This is an internal class and
       # the API is subject to change at any time.
       class TemplateMtimeWrapper
-        def initialize(template_class, path, dependencies, *template_args)
-          @template_class = template_class
-          @path = path
-          @template_args = template_args
-          @dependencies = ([path] + Array(dependencies)) if dependencies
+        def initialize(roda_class, opts, template_opts)
+          @roda_class = roda_class
+          @opts = opts
+          @template_opts = template_opts
+          reset_template
 
-          @mtime = template_last_modified if File.file?(path)
-          @template = template_class.new(path, *template_args)
+          @path = opts[:path]
+          deps = opts[:dependencies]
+          @dependencies = ([@path] + Array(deps)) if deps
+          @mtime = template_last_modified
         end
 
         # If the template file exists and the modification time has
@@ -358,7 +360,7 @@ class Roda
           else
             if mtime != @mtime
               @mtime = mtime
-              @template = @template_class.new(@path, *@template_args)
+              reset_template
               return true
             end
           end
@@ -407,6 +409,14 @@ class Roda
             end
           end
         end
+
+        private
+
+        # Reset the template, done every time the template or one of its
+        # dependencies is modified.
+        def reset_template
+          @template = @roda_class.create_template(@opts, @template_opts)
+        end
       end
 
       module ClassMethods
@@ -427,6 +437,17 @@ class Roda
           end
         end
 
+        # Return an Tilt::Template object based on the given opts and template_opts.
+        def create_template(opts, template_opts)
+          opts[:template_class].new(opts[:path], 1, template_opts, &opts[:template_block])
+        end
+
+        # A proc that returns content, used for inline templates, so that the template
+        # doesn't hold a reference to the instance of the class
+        def inline_template_block(content)
+          Proc.new{content}
+        end
+
         # Copy the rendering options into the subclass, duping
         # them as necessary to prevent changes in the subclass
         # affecting the parent class.
@@ -656,7 +677,7 @@ class Roda
           if content = opts[:inline]
             path = opts[:path] = content
             template_class = opts[:template_class] ||= ::Tilt[engine]
-            opts[:template_block] = Proc.new{content}
+            opts[:template_block] = self.class.inline_template_block(content)
           else
             opts[:views] ||= render_opts[:views]
             path = opts[:path] ||= template_path(opts)
@@ -730,14 +751,14 @@ class Roda
                !opts[:inline]
 
             if render_opts[:check_template_mtime] && !opts[:template_block] && !cache
-              template = TemplateMtimeWrapper.new(opts[:template_class], opts[:path], opts[:dependencies], 1, template_opts)
+              template = TemplateMtimeWrapper.new(self.class, opts, template_opts)
 
               if define_compiled_method
                 method_name = :"_roda_template_#{self.class.object_id}_#{method_cache_key}"
                 method_cache[method_cache_key] = template.define_compiled_method(self.class, method_name)
               end
             else
-              template = opts[:template_class].new(opts[:path], 1, template_opts, &opts[:template_block])
+              template = self.class.create_template(opts, template_opts)
 
               if define_compiled_method && cache != false
                 begin

data/lib/roda/plugins/render_coverage.rb

@@ -0,0 +1,86 @@
+# frozen-string-literal: true
+
+require 'tilt'
+# :nocov:
+raise 'Tilt version does not support coverable templates' unless Tilt::Template.method_defined?(:compiled_path=)
+# :nocov:
+
+#
+class Roda
+  module RodaPlugins
+    # The render_coverage plugin builds on top of the render plugin
+    # and sets compiled_path on created templates.  This allows
+    # Ruby's coverage library before Ruby 3.2 to consider code created
+    # by templates. You may not need this plugin on Ruby 3.2+, since
+    # on Ruby 3.2+, coverage can consider code loaded with +eval+.
+    # This plugin is only supported when using tilt 2.1+, since it
+    # requires the compiled_path supported added in tilt 2.1. 
+    #
+    # By default, the render_coverage plugin will use +coverage/views+
+    # as the directory containing the compiled template files.  You can
+    # change this by passing the :dir option when loading the plugin.
+    # By default, the plugin will set the compiled_path by taking the
+    # template file path, stripping off any of the allowed_paths used
+    # by the render plugin, and converting slashes to dashes. You can
+    # override the allowed_paths to strip by passing the :strip_paths
+    # option when loading the plugin.  Paths outside :strip_paths (or
+    # the render plugin allowed_paths if :strip_paths is not set) will
+    # not have a compiled_path set.
+    #
+    # Due to how Ruby's coverage library works in regards to loading
+    # a compiled template file with identical code more than once,
+    # it may be beneficial to run coverage testing with the
+    # +RODA_RENDER_COMPILED_METHOD_SUPPORT+ environment variable set
+    # to +no+ if using this plugin.
+    module RenderCoverage
+      def self.load_dependencies(app, opts=OPTS)
+        app.plugin :render
+      end
+
+      # Use the :dir option to set the directory to store the compiled
+      # template files, and the :strip_paths directory for paths to
+      # strip.
+      def self.configure(app, opts=OPTS)
+        app.opts[:render_coverage_strip_paths] = opts[:strip_paths].map{|f| File.expand_path(f)} if opts.has_key?(:strip_paths)
+        coverage_dir = app.opts[:render_coverage_dir] = opts[:dir] || app.opts[:render_coverage_dir] || 'coverage/views'
+        Dir.mkdir(coverage_dir) unless File.directory?(coverage_dir)
+      end
+
+      module ClassMethods
+        # Set a compiled path on the created template, if the path for
+        # the template is in one of the allowed_views.
+        def create_template(opts, template_opts)
+          template = super
+          return template if opts[:template_block]
+
+          path = File.expand_path(opts[:path])
+          (self.opts[:render_coverage_strip_paths] || render_opts[:allowed_paths]).each do |dir|
+            if path.start_with?(dir + '/')
+              template.compiled_path = File.join(self.opts[:render_coverage_dir], path[dir.length+1, 10000000].gsub('/', '-'))
+              break
+            end
+          end
+
+          template
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        # Convert template paths to real paths to try to ensure the same template is cached.
+        def template_path(opts)
+          path = super
+
+          if File.file?(path)
+            File.realpath(path)
+          else
+            path
+          end
+        end
+      end
+    end
+
+    register_plugin(:render_coverage, RenderCoverage)
+  end
+end

data/lib/roda/plugins/route_csrf.rb

@@ -90,7 +90,7 @@ class Roda
     #                      action attribute, and returns a path you can pass to csrf_token
     #                      that should be valid for the form submission.  The argument should
     #                      either be nil or a string representing a relative path, absolute
-    #                      path, or full URL.
+    #                      path, or full URL (using appropriate URL encoding).
     # csrf_tag(path=nil, method='POST') :: An HTML hidden input tag string containing the CSRF token, suitable
     #                                      for placing in an HTML form.  Takes the same arguments as csrf_token.
     # csrf_token(path=nil, method='POST') :: The value of the csrf token, in case it needs to be accessed

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 = 65
+  RodaMinorVersion = 67
 
   # 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.65.0
+  version: 3.67.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-13 00:00:00.000000000 Z
+date: 2023-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -238,6 +238,8 @@ extra_rdoc_files:
 - doc/release_notes/3.63.0.txt
 - 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.7.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
@@ -310,6 +312,8 @@ files:
 - doc/release_notes/3.63.0.txt
 - 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.7.0.txt
 - doc/release_notes/3.8.0.txt
 - doc/release_notes/3.9.0.txt
@@ -340,6 +344,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
@@ -409,6 +414,7 @@ files:
 - lib/roda/plugins/recheck_precompiled_assets.rb
 - lib/roda/plugins/relative_path.rb
 - lib/roda/plugins/render.rb
+- lib/roda/plugins/render_coverage.rb
 - lib/roda/plugins/render_each.rb
 - lib/roda/plugins/render_locals.rb
 - lib/roda/plugins/request_aref.rb
@@ -466,7 +472,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