brut 0.0.1 → 0.0.2

data/lib/brut/front_end/routing.rb

@@ -3,8 +3,6 @@ require "uri"
 # Holds the registered routes for this app.
 class Brut::FrontEnd::Routing
 
-  include SemanticLogger::Loggable
-
   def initialize
     @routes = Set.new
   end
@@ -21,6 +19,10 @@ class Brut::FrontEnd::Routing
     new_routes = @routes.map { |route|
       if route.class == Route
         route.class.new(route.http_method,route.path_template)
+      elsif route.class == MissingPage || route.class == MissingHandler || route.class == MissingForm
+        route.class.new(route.path_template,route.exception)
+      elsif route.class == MissingPath
+        route.class.new(route.method,route.path_template,route.exception)
       else
         route.class.new(route.path_template)
       end
@@ -35,28 +37,60 @@ class Brut::FrontEnd::Routing
   end
 
   def register_page(path)
-    route = PageRoute.new(path)
+    route = begin
+              PageRoute.new(path)
+            rescue Brut::Framework::Errors::NoClassForPath => ex
+              if Brut.container.project_env.development?
+                MissingPage.new(path,ex)
+              else
+                raise ex
+              end
+            end
     @routes << route
     add_routing_method(route)
     route
   end
 
   def register_form(path)
-    route = FormRoute.new(path)
+    route = begin
+              FormRoute.new(path)
+            rescue Brut::Framework::Errors::NoClassForPath => ex
+              if Brut.container.project_env.development?
+                MissingForm.new(path,ex)
+              else
+                raise ex
+              end
+            end
     @routes << route
     add_routing_method(route)
     route
   end
 
   def register_handler_only(path)
-    route = FormHandlerRoute.new(path)
+    route = begin
+              FormHandlerRoute.new(path)
+            rescue Brut::Framework::Errors::NoClassForPath => ex
+              if Brut.container.project_env.development?
+                MissingHandler.new(path,ex)
+              else
+                raise ex
+              end
+            end
     @routes << route
     add_routing_method(route)
     route
   end
 
   def register_path(path, method:)
-    route = Route.new(method, path)
+    route = begin
+              Route.new(method, path)
+            rescue Brut::Framework::Errors::NoClassForPath => ex
+              if Brut.container.project_env.development?
+                MissingPath.new(method,path,ex)
+              else
+                raise ex
+              end
+            end
     @routes << route
     add_routing_method(route)
     route
@@ -73,7 +107,11 @@ class Brut::FrontEnd::Routing
       handler_class_match || form_class_match
     }
     if !route
-      raise ArgumentError,"There is no configured route for #{handler_class}"
+      if handler_class.ancestors.include?(Brut::FrontEnd::Form)
+        raise ArgumentError,"There is no configured route for the form #{handler_class} and/or the handler class for this form doesn't exist"
+      else
+        raise ArgumentError,"There is no configured route for #{handler_class}"
+      end
     end
     route
   end
@@ -116,8 +154,6 @@ class Brut::FrontEnd::Routing
 
   class Route
 
-    include SemanticLogger::Loggable
-
     attr_reader :handler_class, :path_template, :http_method
 
     def initialize(method,path_template)
@@ -133,24 +169,37 @@ class Brut::FrontEnd::Routing
       @handler_class = self.locate_handler_class(self.suffix,self.preposition)
     end
 
+    def path_params
+      @path_template.split(/\//).map { |path_part|
+        if path_part =~ /^:(.+)$/
+          $1.to_sym
+        else
+          nil
+        end
+      }.compact
+    end
+
     def path(**query_string_params)
       path = @path_template.split(/\//).map { |path_part|
         if path_part =~ /^:(.+)$/
           param_name = $1.to_sym
           if !query_string_params.key?(param_name)
-            query_string_params_for_message = if query_string_params.keys.any?
-                                                query_string_params.keys.map(&:to_s).join(", ")
-                                              else
-                                                "no params"
-                                              end
-            raise ArgumentError,"path for #{@handler_class} requires '#{param_name}' as a path parameter, but it was not specified to #path. Got #{query_string_params_for_message}"
+            raise Brut::Framework::Errors::MissingParameter.new(
+              param_name,
+              params_received: query_string_params.keys,
+              context: ":#{param_name} was used as a path parameter for #{@handler_class} (path '#{@path_template}')"
+            )
           end
           query_string_params.delete(param_name)
         else
           path_part
         end
       }
-      uri = URI(path.join("/"))
+      joined_path = path.join("/")
+      if joined_path == ""
+        joined_path = "/"
+      end
+      uri = URI(joined_path)
       uri.query = URI.encode_www_form(query_string_params)
       uri
     end
@@ -162,7 +211,7 @@ class Brut::FrontEnd::Routing
   private
     def locate_handler_class(suffix,preposition, on_missing: :raise)
       if @path_template == "/"
-        return Module.const_get("HomePage")
+        return Module.const_get("HomePage") # XXX Needs error handling
       end
       path_parts = @path_template.split(/\//)[1..-1]
 
@@ -184,20 +233,20 @@ class Brut::FrontEnd::Routing
         array
       }
       part_names[-1] += suffix
-      part_names.inject(Module) { |mod,path_element|
-        mod.const_get(path_element,mod == Module)
-      }
-    rescue NameError => ex
-      if on_missing == :raise
-        module_message = if ex.receiver == Module
-                           "Could not find"
-                         else
-                           "Module '#{ex.receiver}' did not have"
-                         end
-        message = "Cannot find page class for route '#{@path_template}', which should be #{part_names.join("::")}. #{module_message} the class or module '#{ex.name}'"
-        raise message
-      else
-        nil
+      begin
+        part_names.inject(Module) { |mod,path_element|
+          mod.const_get(path_element,mod == Module)
+        }
+      rescue NameError => ex
+        if on_missing == :raise
+          raise Brut::Framework::Errors::NoClassForPath.new(
+            class_name_path: part_names,
+            path_template: @path_template,
+            name_error: ex,
+          )
+        else
+          nil
+        end
       end
     end
 
@@ -206,6 +255,64 @@ class Brut::FrontEnd::Routing
 
   end
 
+  class MissingPage < Route
+    attr_reader :exception
+    def initialize(path_template,ex)
+      @http_method   = Brut::FrontEnd::HttpMethod.new(:get)
+      @path_template = path_template
+      @handler_class = begin
+                         page_class = Class.new(Brut::FrontEnd::Pages::MissingPage)
+                         compressed_class_name = ex.class_name_path.join
+                         Module.const_set(:"BrutMissingPages#{compressed_class_name}",page_class)
+                         page_class
+                       end
+      @exception     = ex
+    end
+  end
+
+  class MissingHandler < Route
+    attr_reader :exception
+    def initialize(path_template,ex)
+      @http_method   = Brut::FrontEnd::HttpMethod.new(:post)
+      @path_template = path_template
+      @handler_class = begin
+                         handler_class = Class.new(Brut::FrontEnd::Handlers::MissingHandler)
+                         compressed_class_name = ex.class_name_path.join
+                         Module.const_set(:"BrutMissingHandlers#{compressed_class_name}",handler_class)
+                         handler_class
+                       end
+      @exception     = ex
+    end
+  end
+
+  class MissingPath < Route
+    attr_reader :exception
+    def initialize(method,path_template,ex)
+      @http_method   = Brut::FrontEnd::HttpMethod.new(method)
+      @path_template = path_template
+      @handler_class = begin
+                         handler_class = Class.new(Brut::FrontEnd::Handlers::MissingHandler)
+                         compressed_class_name = ex.class_name_path.join
+                         Module.const_set(:"BrutMissingHandlers#{compressed_class_name}",handler_class)
+                         handler_class
+                       end
+      @exception     = ex
+    end
+  end
+
+  class MissingForm < MissingHandler
+    attr_reader :form_class
+    def initialize(path_template,ex)
+      super
+      @form_class = begin
+                      form_class = Class.new(Brut::FrontEnd::Handlers::MissingHandler::Form)
+                      compressed_class_name = ex.class_name_path.join
+                      Module.const_set(:"BrutMissingForms#{compressed_class_name}",form_class)
+                      form_class
+                    end
+    end
+  end
+
   class PageRoute < Route
     def initialize(path_template)
       super(Brut::FrontEnd::HttpMethod.new(:get),path_template)

data/lib/brut/front_end/session.rb

@@ -2,20 +2,31 @@
 # Generally, this can act like a Hash for setting and accessing values stored in the session.
 # It provides a few useful additions:
 #
-# * Your app can extend this to provide an app-specific API around the session.
+# * Your app can extend this to provide an app-specific API around the session, using `Brut.container.override("session_class",«your class»)`.
 # * There is direct access to commonly-used data stored in the session, such as the flash.
 class Brut::FrontEnd::Session
+  # Create the session based on the session provided by Rack.
+  #
+  # @param [Rack session] rack_session the session as provided by Rack. This is treated as a Hash.
   def initialize(rack_session:)
     @rack_session = rack_session
   end
 
+  # Return the interpretation of the `Accept-Language` header that was set by (#http_accept_language=).
+  #
+  # @return [Brut::I18n::HTTPAcceptLanguage] Never returns `nil`. If the value is corrupted or invalid, an instance that uses English
+  # will be returned.
   def http_accept_language = Brut::I18n::HTTPAcceptLanguage.from_session(self[:__brut_http_accept_language])
+
+  # Set the `Accept-Language` for the session, as an {Brut::I18n::HTTPAcceptLanguage}
+  # @param [Brut::I18n::HTTPAcceptLanguage] http_accept_language
   def http_accept_language=(http_accept_language)
     self[:__brut_http_accept_language] = http_accept_language.for_session
   end
 
-  # Get the timezone as reported by the browser, as a TZInfo::Timezone.
-  # If none is available or the browser reported an invalid value, this returns nil.
+  # Get the timezone as reported by the browser, or nil if there isn't one or the browser sent and invalid value
+  #
+  # @return [TZInfo::Timezone|nil]
   def timezone_from_browser
     tz_name = self[:__brut_timezone_from_browser]
     if tz_name.nil?
@@ -24,13 +35,14 @@ class Brut::FrontEnd::Session
     begin
       TZInfo::Timezone.get(tz_name)
     rescue TZInfo::InvalidTimezoneIdentifier => ex
-      SemanticLogger[self.class.name].warn(ex)
+      Brut.container.instrumentation.record_exception(ex, class: self.class)
       nil
     end
   end
 
-  # Set the timezone as reported by the browser. This alleviates the need to keep
-  # asking the browser for this information.
+  # Set the timezone as reported by the browser.
+  #
+  # @param timezone [TZInfo::Timezone|String] The timezone, or name of a timezone suitable for use with `TZInfo::Timezone`.
   def timezone_from_browser=(timezone)
     if timezone.kind_of?(TZInfo::Timezone)
       timezone = timezone.name
@@ -38,18 +50,85 @@ class Brut::FrontEnd::Session
     self[:__brut_timezone_from_browser] = timezone
   end
 
+  # Set the session timezone, regardless of what the browser reports.
+  #
+  # @param timezone [TZInfo::Timezone|String|nil] The timezone, or name of a timezone suitable for use with `TZInfo::Timezone`. Use
+  # `nil` to clear this value and use the browser's time zone.
+  def timezone=(timezone)
+    if timezone.kind_of?(TZInfo::Timezone)
+      timezone = timezone.name
+    end
+    self[:__brut_timezone_override] = timezone
+  end
+
+  # Get the session timezone. This is the preferred way to get a timezone for the current session.  Always returns a value, based on
+  # the following logic:
+  #
+  # 1. If {#timezone=} has been called with a value, that time zone is returned.
+  # 2. If {#timezone=} has been given no value or `nil`, and {#timezone_from_browser} returns a value, that value is used.
+  # 3. If {#timezone_from_browser} returns `nil`, `ENV["TZ"]` is used, assuming it is a valid time zone.
+  # 4. If 'ENV["TZ"]` is blank or invalid, UTC is returned.
+  #
+  # It is in your best interest to ensure that each session has a valid time zone.
+  #
+  # @return [TZInfo::Timezone]
+  def timezone
+    tz_name = self[:__brut_timezone_override]
+    timezone = nil
+    if !tz_name.nil?
+      begin
+        timezone = TZInfo::Timezone.get(tz_name)
+      rescue TZInfo::InvalidTimezoneIdentifier => ex
+        Brut.container.instrumentation.record_exception(ex, class: self.class, invalid_tz_name: tz_name)
+      end
+    end
+    if timezone.nil?
+      timezone = self.timezone_from_browser
+    end
+    if timezone.nil?
+      begin
+        timezone = if ENV["TZ"]
+                     TZInfo::Timezone.get(ENV["TZ"])
+                   else
+                     nil
+                   end
+      rescue TZInfo::InvalidTimezoneIdentifier => ex
+        Brut.container.instrumentation.record_exception(ex, class: self.class, invalid_env_tz: ENV['TZ'])
+        nil
+      end
+    end
+    if timezone.nil?
+      timezone = TZInfo::Timezone.get("UTC")
+    end
+    timezone
+  end
+
+  # Access the underlying session directly
+  #
+  # @param [Symbol|String] key the key to use. Coerced into a string.
+  # @return [Object] whatever value, including `nil`, is in the session for this key.
   def[](key) = @rack_session[key.to_s]
 
+  # Set the session value for the key.
+  #
+  # @param [Symbol|String] key the key to use. Coerced into a string.
+  # @param [Object] value Value to use. Note that this value may be coerced into a string in a way that may not work for your use case.
+  # You are encouraged to send in a string. If you want to store rich data in the session, maybe don't? But if you must, add a
+  # method to do the marshalling in your app's subclass of this
   def[]=(key,value)
     @rack_session[key.to_s] = value
   end
 
+  # Delete a key from the session. This is preferred to setting the value to `nil`
   def delete(key) = @rack_session.delete(key.to_s)
 
-  # Access the flash, as an instance of whatever class has been configured.
+  # Access the flash, as an instance of whatever class has been configured. Note that this returns a copy of the flash, so any changes
+  # will not be stored in the session unless you call (#flash=) after changing it.  Generally, this isn't a big deal as Brut handles
+  # this for you.
   def flash
     Brut.container.flash_class.from_h(self[:__brut_flash])
   end
+  # Set the flash.
   def flash=(new_flash)
     self[:__brut_flash] = new_flash.to_h
   end

data/lib/brut/front_end/template.rb

@@ -1,31 +1,46 @@
 require "temple"
 
+# Holds code related to rendering ERB templates
 module Brut::FrontEnd::Templates
   autoload(:HTMLSafeString,"brut/front_end/templates/html_safe_string")
   autoload(:ERBParser,"brut/front_end/templates/erb_parser")
   autoload(:EscapableFilter,"brut/front_end/templates/escapable_filter")
   autoload(:BlockFilter,"brut/front_end/templates/block_filter")
   autoload(:ERBEngine,"brut/front_end/templates/erb_engine")
+  autoload(:Locator,"brut/front_end/templates/locator")
 end
 
-# Handles rendering HTML templates
+# Handles rendering HTML templates written in ERB.  This is a light wrapper around `Tilt`.
+# This also configured a few customizations to allow a Rails-like rendering of ERB:
+#
+# * HTML escaping by default
+# * Helpers that return {Brut::FrontEnd::Templates::HTMLSafeString}s won't be escaped
+#
+# @see https://github.com/rtomayko/tilt
 class Brut::FrontEnd::Template
 
+  # @!visibility private
+  # This sets up global state somewhere, even though we aren't using `TempleTemplate`
+  # anywhere.
   TempleTemplate = Temple::Templates::Tilt(Brut::FrontEnd::Templates::ERBEngine,
                                            register_as: "html.erb")
 
+  attr_reader :template_file_path
+
   # Wraps a string that is deemed safe to insert into
   # HTML without escaping it.  This allows stuff like
   # <%= component(SomeComponent) %> to work without
   # having to remember to <%== all the time.
   def initialize(template_file_path)
-    @tilt_template = Tilt.new(template_file_path)
+    @template_file_path = template_file_path
+    @tilt_template = Tilt.new(@template_file_path)
   end
 
   def render_template(...)
     @tilt_template.render(...)
   end
 
+  # Convienience method to escape HTML in the canonical way.
   def self.escape_html(string)
     Brut::FrontEnd::Templates::EscapableFilter.escape_html(string)
   end

data/lib/brut/front_end/templates/block_filter.rb

@@ -1,10 +1,11 @@
-# This is a slightly modified copy if Hanamis' Filters::Block:
-#
-# https://github.com/hanami/view/blob/main/lib/hanami/view/erb/filters/block.rb
+# Allows rendering blocks in ERB the way Rails' helpers like `form_with` do.
+# This is a slightly modified copy of Hanami's `Filters::Block`.
 #
+# @see https://github.com/hanami/view/blob/main/lib/hanami/view/erb/filters/block.rb
 class Brut::FrontEnd::Templates::BlockFilter < Temple::Filter
   END_LINE_RE = /\bend\b/
 
+  # @!visibility private
   def on_erb_block(escape, code, content)
     tmp = unique_name
 

data/lib/brut/front_end/templates/erb_parser.rb

@@ -2,7 +2,7 @@
 #
 # https://github.com/hanami/view/blob/main/lib/hanami/view/erb/parser.rb
 #
-# That is licensed MIT and thus so is this.
+# That is licensed MIT and thus so is this file.
 #
 # Avoid changes to this file so it can be kept updated with Hanami.
 class Brut::FrontEnd::Templates::ERBParser < Temple::Parser

data/lib/brut/front_end/templates/escapable_filter.rb

@@ -3,11 +3,13 @@
 class Brut::FrontEnd::Templates::EscapableFilter < Temple::Filters::Escapable
   using Brut::FrontEnd::Templates::HTMLSafeString::Refinement
 
+  # @!visibility private
   def initialize(opts = {})
     opts[:escape_code] ||= "::Brut::FrontEnd::Templates::EscapableFilter.escape_html((%s))"
     super(opts)
   end
 
+  # @!visibility private
   def self.escape_html(html)
     if html.kind_of?(Brut::FrontEnd::Templates::HTMLSafeString)
       html.string

data/lib/brut/front_end/templates/html_safe_string.rb

@@ -1,18 +1,33 @@
 # A wrapper around a string to indicate it is HTML-safe and
-# can be rendered directly without escaping.
+# can be rendered directly without escaping. This was done to avoid adding methods on `String` and the internal state
+# required to make something like `"foo".html_safe!` work.
 class Brut::FrontEnd::Templates::HTMLSafeString
+  # This can be used via `using` to add `html_safe!` and `html_safe?` method to `String` when they might be more convienient
+  # than using {Brut::FrontEnd::Templates::HTMLSafeString} directly.
   module Refinement
     refine String do
       def html_safe! = Brut::FrontEnd::Templates::HTMLSafeString.from_string(self)
       def html_safe? = false
     end
   end
+  using Refinement
+
+  # @return [String] the underlying string being wrapped
   attr_reader :string
+
+  # Create an HTML safe string based on the parameter. It's recommended to use {.from_string} instead.
+  #
+  # @param [String] string A string that is considered safe to put directly into a web page without escaping.
   def initialize(string)
     @string = string
   end
 
-  # Wrap a string in an HTMLSafeString if needed.
+  # Creates an HTML Safe string based on the parameter, properly handling if a HTML safe string is being passed.
+  #
+  # @param [String|Brut::FrontEnd::Templates::HTMLSafeString] string_or_html_safe_string the value to turn into an HTML safe string.
+  #
+  # @return [Brut::FrontEnd::Templates::HTMLSafeString] if `string_or_html_safe_string` is already HTML safe, returns it. Otherwise,
+  # wraps the string as HTML safe.
   def self.from_string(string_or_html_safe_string)
     if string_or_html_safe_string.kind_of?(self)
       string_or_html_safe_string
@@ -24,12 +39,25 @@ class Brut::FrontEnd::Templates::HTMLSafeString
   # This must be convertible to a string
   def to_s       = @string
   def to_str     = @string
+  # Matches the protocol in {Brut::FrontEnd::Templates::HTMLSafeString::Refinement}
+  # @return [Brut::FrontEnd::Templates::HTMLSafeString] self
   def html_safe! = self
+  # Matches the protocol in {Brut::FrontEnd::Templates::HTMLSafeString::Refinement}
+  # @return [true|false] true
   def html_safe? = true
+
+  # Return a new instance that has called `capitalize` on the underlying string
   def capitalize = self.class.new(@string.capitalize)
+  # Return a new instance that has called `downcase` on the underlying string
   def downcase   = self.class.new(@string.downcase)
+  # Return a new instance that has called `upcase` on the underlying string
   def upcase     = self.class.new(@string.upcase)
 
+  # Returns the concatenation of two strings. If the other is HTML safe, then this returns an HTML safe string.
+  # If the other is not, this returns a normal unsafe string.
+  #
+  # @param [String|Brut::FrontEnd::Templates::HTMLSafeString] other
+  # @return [String|Brut::FrontEnd::Templates::HTMLSafeString] A safe or unsafe string, depending on what was passed.
   def +(other)
     if other.html_safe?
       self.class.new(@string + other.to_s)

data/lib/brut/front_end/templates/locator.rb

@@ -0,0 +1,60 @@
+# Locates a template, based on a name, configured paths, and an extension.  This class forms both an API
+# for template location ({#locate}) as well as an implementation that is conventional with Brut apps.
+class Brut::FrontEnd::Templates::Locator
+  # Create a locator that will search the given paths and require that template
+  # files have the given extension
+  #
+  # @param [Pathname|String|Array<Pathname|String>] paths one or more paths that will be searched for templates
+  # @param [String] extension file extension, without the dot, of the name of files that are considered templates
+  def initialize(paths:, extension:)
+    @paths     = Array(paths).map { |path| Pathname(path) }
+    @extension = extension
+  end
+
+  # Given a base name, which may or may not be nested paths, returns the path to the template
+  # for this file.  There must be exactly one template that matches.
+  #
+  # @example
+  #
+  #    locator = Locator.new(
+  #      paths: [
+  #        Brut.container.app_src_dir / "front_end" / "components",
+  #        Brut.container.app_src_dir / "front_end" / "other_components",
+  #      ],
+  #      extension: "html.erb"
+  #    )
+  #
+  #    # Suppose app/src/front_end/components/foo.html.erb exists
+  #    path = locator.locate("foo")
+  #    # => "app/src/front_end/components/foo.html.erb"
+  #
+  #    # Suppose app/src/front_end/components/bar/blah.html.erb exists
+  #    path = locator.locate("bar/blah")
+  #    # => "app/src/front_end/components/bar/blah.html.erb"
+  #
+  #    # Suppose both app/src/front_end/components/bar/blah.html.erb and
+  #    #              app/src/front_end/other_components/bar/blah.html.erb
+  #    # both exist
+  #    path = locator.locate("bar/blah")
+  #    # => raises an error since there are two matches
+  #
+  # @param [String] base_name the base name of a file that is expected to have a template.  This is searched relative to the paths
+  # provided to the constructor, so it may have nested paths
+  # @return [String] path to the template for the given `base_name`
+  # @raises StandardError if zero or more than one templates are found
+  def locate(base_name)
+    paths_to_try = @paths.map { |path|
+      path / "#{base_name}.#{@extension}"
+    }
+    paths_found = paths_to_try.select { |path|
+      path.exist?
+    }
+    if paths_found.empty?
+      raise "Could not locate template for #{base_name}. Tried: #{paths_to_try.map(&:to_s).join(', ')}"
+    end
+    if paths_found.length > 1
+      raise "Found more than one valid pat for #{base_name}.  You must rename your files to disambiguate them. These paths were all found: #{paths_found.map(&:to_s).join(', ')}"
+    end
+    return paths_found[0]
+  end
+end

data/lib/brut/i18n/base_methods.rb

@@ -130,6 +130,10 @@ module Brut::I18n::BaseMethods
     end
   end
 
+  def l(date_like, format: :default)
+    ::I18n::l(date_like,format: format)
+  end
+
   def this_field_value
     @__this_field_value ||= ::I18n.t("general.cv.this_field", raise: true)
   end

data/lib/brut/i18n.rb

@@ -1,3 +1,4 @@
+# I18n holds all the code useful for translating and localizing information. It's based on Ruby's I18n.
 module Brut::I18n
   autoload(:BaseMethods, "brut/i18n/base_methods")
   autoload(:ForCLI, "brut/i18n/for_cli")