brut 0.0.20 → 0.0.22

data/lib/brut/framework/app.rb

@@ -1,9 +1,10 @@
 # An "App" in Brut paralance is the collection of source code and configuration that is needed to operate
 # a website. This includes everything needed to serve HTTP requests, but also includes ancillary
-# tasks and any related files required for the app to exist and function.  Your app will have an `App` class that subclasses this
-# class.
+# tasks and any related files required for the app to exist and function.
+# Your app will have an `App` class that subclasses this class.
 #
-# When your app is initialized, Brut will have been configured, but access to internal resources may not be available.  It is here
+# When your app is initialized, Brut will have been configured,
+# but access to internal resources may not be available.  It is here
 # that you can override configuration values or do any other setup before everything boots.
 class Brut::Framework::App
   include Brut::Framework::Errors
@@ -18,7 +19,8 @@ class Brut::Framework::App
   # actions where an app needs to exist inside some organizational context.
   def organization = id
 
-  # Call this in your app's definition to define your app's routes. The contents of the block will be evaluated in the context of
+  # Call this in your app's definition to define your app's routes.
+  # The contents of the block will be evaluated in the context of
   # {Brut::SinatraHelpers::ClassMethods}, and the methods there are generally the ones you should be calling.
   #
   # You can call this multiple times and the routes will be concatenated together.
@@ -31,6 +33,69 @@ class Brut::Framework::App
     end
   end
 
+  # Call this to specify what happens when an unhandled exception occurs.  You may call this mulitple times,
+  # however note that if an error is caught that matches more than one block's condition, the one that is called
+  # will be the first one declared.
+  #
+  # The only deviation from this rule is when you call this
+  # without any condition.  Doing that establishes the behavior for a "catch all" handler, which is
+  # only called when no other configured block can handle the exception. You can declare
+  # this at any time. **Do note** the "catch all" handler is more of a best effort. Brut is currently
+  # based on Sinatra which provides no way to arbitrarily catch all exceptions.  What Brut does here is to 
+  # explicitly catch the range of http status codes from 400 to 999.
+  #
+  # Note that Brut will record the exception via OpenTelemetry so you should not do this in your handlers.  It
+  # would be preferable to instead record an event if you want to have observability from your error handlers.
+  #
+  # @param [Class|Integer|Range<Integer>] condition if given this specifies the conditions under which the given
+  #        block will handle the error.  If omitted, this block will handle any error that doesn't have a more
+  #        specific handler configured.  Meaning of values:
+  #        * A class - this is an exception class that, if caught, triggers the handler
+  #        * An integer - this is an HTTP status code that, if returned, triggers the handler
+  #        * A range of integers - this is a range of HTTP status codes that, if returned, triggers the handler
+  # @yield [Exception] the block is given two named parameters: `exception:` and `http_status_code:`. Your block
+  #        can declare both, either, or none.  Any that are declared will be given values.  At least one
+  #        will be non-`nil`, however are encouraged to code defensively inside this block.
+  # @yieldparam [Exception] exception: the exception that was raised. This will be `nil`
+  #             if the error was caused by an HTTP status code.
+  # @yieldparam [Integer] http_status_code: the HTTP status code that was returned. If `exception:` is
+  #             not `nil`, this value is highly likely to be 500.
+  # @yieldreturn The block should return a valid Rack response. For now.
+  def self.error(condition=:catch_all, &block)
+    @error_blocks ||= {}
+    if block.nil?
+      raise ArgumentError, "You must provide a block to error"
+    end
+    parameters = block.parameters.reject { |type,name|
+      type == :keyreq && [ :http_status_code, :exception ].include?(name)
+    }
+    if parameters.any?
+      messages = parameters.map { |type,name|
+        case type
+        when :keyreq
+          "required keyword parameter '#{name}:'"
+        when :key
+          "optional keyword parameter '#{name}:'"
+        when :rest
+          "rest parameter '#{name}'"
+        when :opt
+          "optional parameter '#{name}'"
+        when :req
+          "required parameter '#{name}'"
+        else
+          "unknown parameter '#{name}'"
+        end
+      }
+      raise ArgumentError, "Your error handler block may only accept exception: and http_status_code: as required keyword parameters.  The following parameters were found:\n  #{messages.join("\n  ")}"
+    end
+    if @error_blocks[condition]
+      raise ArgumentError, "You have already configured error handling for condition '#{condition.to_s}'"
+    end
+    @error_blocks[condition] = block
+  end
+
+  def self.error_blocks = @error_blocks || {}
+
   # Add a Rack middleware to your app. Middlewares are configured in the order in which you call this method.
   #
   # @param [Class] middleware a class that implements [Rack Middleware](https://github.com/rack/rack/blob/main/SPEC.rdoc).
@@ -81,7 +146,7 @@ class Brut::Framework::App
   # code required *after* Brut has been set up and started.  You can rely on the
   # database being available. Any attempts to override configuration values
   # may not succeed.  This is called after the framework has booted, but before
-  # your apps' routes are set up.
+  # your app's routes are set up.
   def boot!
   end
 

data/lib/brut/framework/config.rb

@@ -1,11 +1,13 @@
 require_relative "project_environment"
 require "pathname"
 
-# Holds configuration for the framework and your app.  In general, you should not interact with this class, however it's source code
-# is a good reference for what is configured by default by Brut.
+# Holds configuration for the framework and your app.  In general, you 
+# should not interact with this class, however it's source code is a good 
+# reference for what is configured by default by Brut.
 class Brut::Framework::Config
 
-  # Configures all defaults.  In general, this attempts to be lazy in setting things up, so calling this should not attempt to make a
+  # Configures all defaults.  In general, this attempts to be lazy in
+  # setting things up, so calling this should not attempt to make a
   # connection to your database.
   def configure!
     Brut.container do |c|

data/lib/brut/framework/container.rb

@@ -21,7 +21,8 @@ end
 #
 # There is no namespacing/hierarchy.
 #
-# In general, you should not create instances of this class, but you may need to access it via {Brut.container} in order to obtain
+# In general, you should not create instances of this class, but you may
+# need to access it via {Brut.container} in order to obtain
 # configuration values or set your own.
 class Brut::Framework::Container
   def initialize
@@ -92,7 +93,7 @@ class Brut::Framework::Container
   end
 
   # Called by your app to override an existing value.  The value must be overridable (see {#store}).  Generally, you should call this
-  # in the initializer of your {Brut::Framework::App} subclass.  Calling this after the fact may not have the affect you want.
+  # in the initializer of your {Brut::Framework::App} subclass.  Calling this after the fact may not have the effect you want.
   #
   # @param [String|Symbol] name name of the value to override. Will be coerced to a String. This name must have been previously
   #                             configured.

data/lib/brut/framework/errors.rb

@@ -1,7 +1,7 @@
 module Brut
   module Framework
-    # Include this in your class to access some helpful methods that throw commonly-needed
-    # errors
+    # Namespace for Brut-specific error classes, and a holder of several error-related convienience 
+    # methods.  Include this module to gain access to those methods.
     module Errors
       autoload(:Bug,"brut/framework/errors/bug")
       autoload(:NotImplemented,"brut/framework/errors/not_implemented")
@@ -10,7 +10,12 @@ module Brut
       autoload(:MissingConfiguration,"brut/framework/errors/missing_configuration")
       autoload(:AbstractMethod,"brut/framework/errors/abstract_method")
       autoload(:NoClassForPath,"brut/framework/errors/no_class_for_path")
-      # Raises {Brut::Framework::Errors::Bug}
+      # Raises {Brut::Framework::Errors::Bug}, used to indicate a codepath is a bug.  "But, why write a
+      # bug in the first place?" you may be asking.  Sometimes, a code path exists, but external factors
+      # mean that it should never be executed.  Or, sometimes an API can be mis-used, but the current
+      # state of the system is such that it would never be misused.
+      #
+      # This method allows you to indicate such situations and provide a meaningful explanation.
       #
       # @param message Message to include in the error
       # @raise [Brut::Framework::Errors::Bug]
@@ -18,7 +23,10 @@ module Brut
         raise Brut::Framework::Errors::Bug,message
       end
 
-      # Raises {Brut::Framework::Errors::AbstractMethod}
+      # Raises {Brut::Framework::Errors::AbstractMethod}, which is useful if you need to document
+      # a method that a subclass must implement, but for which there is no useful default
+      # implementation.
+      #
       # @raise [Brut::Framework::Errors::AbstractMethod]
       def abstract_method!
         raise Brut::Framework::Errors::AbstractMethod

data/lib/brut/framework/mcp.rb

@@ -116,8 +116,65 @@ class Brut::Framework::MCP
     @sinatra_app = Class.new(Sinatra::Base)
     @sinatra_app.include(Brut::SinatraHelpers)
 
+    safely_record_exception = ->(exception,http_status_code) {
+      begin
+      if exception.nil?
+        Brut.container.instrumentation.add_event("error triggered without exception", http_status_code:)
+      else
+        Brut.container.instrumentation.record_exception(exception, http_status_code:)
+      end
+      rescue => ex
+        begin
+          SemanticLogger[self.class].error(
+            "Error recording exception",
+            original_excerption: exception, 
+            exception: ex)
+        rescue => ex2
+          $stderr.puts "While handling an error recording an exception, we get another error from SemanticLogger." + [
+            [ :original_exception,  exception,  ].join(": "),
+            [ :exception_from_recording_exception,  ex, ].join(": "),
+            [ :exception_from_semantic_logger,  ex2 ].join(": "),
+
+          ].join(", ")
+        end
+      end
+    }
+
+    @app.class.error_blocks.each do |condition,block|
+      if condition != :catch_all
+        @sinatra_app.error(condition) do
+          exception = request.env["sinatra.error"]
+          safely_record_exception.(exception, response.status)
+          block_args = if exception
+                         { exception: }
+                       else
+                         { http_status_code: response.status }
+                       end
+          block.(**block_args)
+        end
+      end
+    end
+    if @app.class.error_blocks[:catch_all]
+      block = @app.class.error_blocks[:catch_all]
+      block_args = block.parameters.map { |(type,name)|
+        [ name, nil ]
+      }.to_h
+      @sinatra_app.error(400..999) do
+        exception = request.env["sinatra.error"]
+        safely_record_exception.(exception, response.status)
+        if block_args.key?(:exception)
+          block_args[:exception] = exception
+        end
+        if block_args.key?(:http_status_code)
+          block_args[:http_status_code] = response.status
+        end
+        block.(**block_args)
+      end
+    else
+    end
+
     message = if Brut.container.project_env.development?
-                "Form submission did not include an authenticity token. All forms must include one. To add one, use the `form_tag` helper, or include <%= component(Brut::FrontEnd::Components::Inputs::CsrfToken) %> somewhere inside your <form> tag"
+                "Form submission did not include an authenticity token. All forms must include one. To add one, use the `form_tag` helper, or include Brut::FrontEnd::Components::Inputs::CsrfToken somewhere inside your <form> tag"
               else
                 "Forbidden"
               end

data/lib/brut/framework/project_environment.rb

@@ -1,5 +1,7 @@
-# Manages the interpretation of dev/test/prod. The canonical instance is available via `Brut.container.project_env`.  Generally, you
-# should avoid basing logic on this, or at least contain the conditional behavior to the configuration values. But, you do you.
+# Manages the interpretation of dev/test/prod. The canonical instance is available 
+# via `Brut.container.project_env`.  Generally, you
+# should avoid basing logic on this, or at least contain the conditional behavior
+# to the configuration values. But, you do you.
 class Brut::Framework::ProjectEnvironment
   # Create the project environment based on the string
   # @param [String] string_value value from e.g. `ENV["RACK_ENV"]` to use to set the environment
@@ -21,6 +23,8 @@ class Brut::Framework::ProjectEnvironment
   # @return [true|false] true is this is production
   def production?  = @value == "production"
 
+  def staging? = raise "Staging is a lie, please consider feature flags or literally any other way to manage in-development features of your app. I promise you, you will regret ever having to do anything with a staging server"
+
   # @return [String] the string value (which should be suitable for the constructor)
   def to_s = @value
 end

data/lib/brut/framework.rb

@@ -1,5 +1,5 @@
 module Brut
-  # The Framework module holds a lot of Brut's internals, or classes that cut across the back end and front end.
+  # Namespace for Brut's internals as well as classes that aren't strictly front or back end.
   module Framework
     autoload(:App,"brut/framework/app")
     autoload(:Config,"brut/framework/config")

data/lib/brut/front_end/component.rb

@@ -16,21 +16,18 @@ module Brut::FrontEnd::Components
 end
 
 # A Component is the top level class for managing the rendering of 
-# content.  A component is essentially an ERB template and a class whose
-# instance servces as it's binding. It is very similar to a View Component, though
-# not quite as fancy.
+# content.  It is a Phlex component with additional features.
+# Components are the primary mechanism for managing view complexity and managing
+# markup re-use in Brut.
 #
-# When subclassing this to create a component, your initializer's signature will determine what data
-# is required for your component to work.  It can be anything, just keep in mind that any page or component
-# that uses your component must be able to provide those values.
+# To create a component, subclass this class (or, more likely, your app's `AppComponent`) and
+# provide an initializer that accepts keyword arguments.  The names of these arguments will be used to locate the
+# values that Brut will pass in when creating your component object.
 #
-# If your component does not override {#render} (which, generally, it won't), an ERB file is expected to exist alongside it in the
-# app.  For example, if you have a component named `Auth::LoginButtonComponent`, it would expected to be in
-# `app/src/front_end/components/auth/login_button_component.rb`.  Thus, Brut will also expect
-# `app/src/front_end/components/auth/login_button_component.html.erb` to exist as well. That ERB file is used with an instance of your
-# component's class to render the component's HTML.
+# Consult Brut's documentation on keyword injection to know what values you may use and how values are located.
 #
-# @see Brut::FrontEnd::Component::Helpers
+# Becuase this is a Phlex component, you must implement `view_template` and make calls to Phlex's API to create
+# the markup for your component.
 class Brut::FrontEnd::Component < Phlex::HTML
 
   include Brut::Framework::Errors
@@ -53,71 +50,72 @@ class Brut::FrontEnd::Component < Phlex::HTML
   register_element :brut_tabs
   register_element :brut_tracing
 
-  def inline_svg(svg)
-    Brut.container.svg_locator.locate(svg).then { |svg_file|
-      File.read(svg_file)
-    }.then { |svg_content|
-      raw(safe(svg_content))
-    }
-  end
+  # Module for the various "free methods" available to all components.
+  # Generally, we don't want to build up mega-classes with lots of modules, but
+  # this provides a nice, singular namespace to document the helpers as apart
+  # from the various methods of the component.
+  module Helpers
+    # Render an inline an SVG that is part of your app. **Note** this does not
+    # return the SVG's contents, but it renders it into the current Phlex
+    # context.
+    #
+    # @param [String] svg path to the SVG file, relative to where SVGs are
+    #        stored, which is `app/src/front_end/svgs` or where `Brut.container.svg_locator` is
+    #        looking
+    #
+    # @see Brut::FrontEnd::InlineSvgLocator
+    def inline_svg(svg)
+      Brut.container.svg_locator.locate(svg).then { |svg_file|
+        File.read(svg_file)
+      }.then { |svg_content|
+        raw(safe(svg_content))
+      }
+    end
 
-  def time_tag(timestamp:nil,**component_options, &contents)
-    args = component_options.merge(timestamp:)
-    render Brut::FrontEnd::Components::TimeTag.new(**args,&contents)
+    # Return a component that you would like Brut to instantiate.
+    # This will use keyword injection to create the component, which means that if the component
+    # doesn't require any data from this component, you do not need to pass through those values.
+    # For example, you may have a component that renders the flash message.  To avoid requiring your component to
+    # be passed the flash, a global component can be injected with it from Brut.
+    #
+    # @return [Object] instance of `component_klass`, as created by Brut. This will
+    #         not render the component.
+    def global_component(component_klass)
+      Brut::FrontEnd::RequestContext.inject(component_klass)
+    end
   end
+  include Helpers
 
-  def form_tag(**args, &block)
-    render Brut::FrontEnd::Components::FormTag.new(**args,&block)
-  end
+  # The name of this component, used for debugging and other purposes. Do not
+  # override this.
+  def self.component_name = self.name
+  # Convenience method to get the component name. This just calls the class
+  # method {.component_name}.
+  def component_name = self.class.component_name
 
-  def global_component(component_klass)
-    render Brut::FrontEnd::RequestContext.inject(component_klass)
-  end
+  # True if this component is page private.
+  # @!visibility private
+  def page_private? = !!self.containing_page_class
 
-  def constraint_violations(form:, input_name:, index: nil, message_html_attributes: {}, **html_attributes)
-    render(
-      Brut::FrontEnd::Components::ConstraintViolations.new(
-        form:,
-        input_name:,
-        index:,
-        message_html_attributes:,
-        **html_attributes
-      )
-    )
-  end
+  # Returns the {Brut::FrontEnd::Page.page_name} of the page containing this component, 
+  # if it is {#page_private?}. Do not call if it's not.
+  # @!visibility private
+  def containing_page_name = self.containing_page_class.page_name
 
-  # Create an HTML input tag for the given input of a form.  This is a convieniece method
-  # that calls {Brut::FrontEnd::Components::Inputs::TextField.for_form_input}.
-  def input_tag(form:, input_name:, index: nil, **html_attributes)
-    render(
-      Brut::FrontEnd::Components::Inputs::TextField.for_form_input(
-        form:,
-        input_name:,
-        index:,
-        html_attributes:)
-    )
-  end
-
-  def self.component_name = self.name
-  def component_name = self.class.component_name
+private
 
-  def page_name
-    @page_name ||= begin
-                     page = self.class.name.split(/::/).reduce(Module) { |accumulator,class_path_part|
-                       if accumulator.ancestors.include?(Brut::FrontEnd::Page)
-                         accumulator
-                       else
-                         accumulator.const_get(class_path_part)
-                       end
-                     }
-                     if page.ancestors.include?(Brut::FrontEnd::Page)
-                       page.name
-                     elsif page.respond_to?(:page_name)
-                       page.page_name
-                     else
-                       raise "#{self.class} is not nested inside a page, so #page_name should not have been called"
-                     end
-                   end
+  def containing_page_class
+    page_class = self.class.name.split(/::/).reduce(Module) { |accumulator,class_path_part|
+      if accumulator.ancestors.include?(Brut::FrontEnd::Page)
+        accumulator
+      else
+        accumulator.const_get(class_path_part)
+      end
+    }
+    if page_class.ancestors.include?(Brut::FrontEnd::Page)
+      page_class
+    else
+      nil
+    end
   end
-
 end

data/lib/brut/front_end/components/constraint_violations.rb

@@ -14,10 +14,7 @@
 # </brut-cv-messages>
 # ```
 #
-# Note that if you are using `<brut-form>` then `<brut-cv>` elements will be inserted into the `<brut-cv-messages>` element, however
-# they will not have the `server-side` attribute.
-#
-# You will most commonly use this component via {Brut::FrontEnd::Component::Helpers#constraint_violations}.
+# Note that if you are using `<brut-form>` then `<brut-cv>` elements will be inserted into the `<brut-cv-messages>` element, however they will not have the `server-side` attribute.
 class Brut::FrontEnd::Components::ConstraintViolations < Brut::FrontEnd::Component
   # Create a new ConstraintViolations component
   #

data/lib/brut/front_end/components/form_tag.rb

@@ -1,4 +1,4 @@
-# Represents a `<form>` HTML element that includes a CSRF token as needed. You likely want to use this class via the {Brut::FrontEnd::Component::Helpers#form_tag} method.
+# Represents a `<form>` HTML element that includes a CSRF token as needed.
 class Brut::FrontEnd::Components::FormTag < Brut::FrontEnd::Component
   # Creates the form surrounding the contents of the block yielded to it. If the form's action is a POST, it will include a CSRF token.
   # If the form's action is GET, it will not.

data/lib/brut/front_end/components/input.rb

@@ -2,10 +2,10 @@ module Brut::FrontEnd::Components
 
   # Holds components designed to render HTML `<input>` and other form components.
   module Inputs
-    autoload(:TextField,"brut/front_end/components/inputs/text_field")
+    autoload(:InputTag,"brut/front_end/components/inputs/input_tag")
     autoload(:RadioButton,"brut/front_end/components/inputs/radio_button")
-    autoload(:Select,"brut/front_end/components/inputs/select")
-    autoload(:Textarea,"brut/front_end/components/inputs/textarea")
+    autoload(:SelectTagWithOptions,"brut/front_end/components/inputs/select_tag_with_options")
+    autoload(:TextareaTag,"brut/front_end/components/inputs/textarea_tag")
     autoload(:CsrfToken,"brut/front_end/components/inputs/csrf_token")
   end
 

data/lib/brut/front_end/components/inputs/csrf_token.rb

@@ -1,5 +1,5 @@
 # Renders a hidden field for a form that contains the current CSRF token. You only need
-# to use this directly if you are building a form without {Brut::FrontEnd::Component::Helpers#form_tag}.
+# to use this directly if you are building a form without {Brut::FrontEnd::Components::FormTag}
 class Brut::FrontEnd::Components::Inputs::CsrfToken < Brut::FrontEnd::Components::Input
   def initialize(csrf_token:)
     @csrf_token = csrf_token

data/lib/brut/front_end/components/inputs/{text_field.rb → input_tag.rb}

@@ -1,5 +1,5 @@
 # Generates an HTML `<input>` field.
-class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components::Input
+class Brut::FrontEnd::Components::Inputs::InputTag < Brut::FrontEnd::Components::Input
   # Creates the appropriate input for the given {Brut::FrontEnd::Form} and input name.
   # Generally, you want to use this method over the initializer.
   #
@@ -7,10 +7,10 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
   # @param [String] input_name the name of the input, which should be a member of `form`
   # @param [Integer] index if this input is part of an array, this is the index into that array. This is used to get the input's value.
   # @param [Hash] html_attributes any additional HTML attributes to include on the `<input>` element.
-  def self.for_form_input(form:, input_name:, index: nil, html_attributes: {})
+  def self.for_form_input(form:, input_name:, index: nil, **html_attributes)
+    input = form.input(input_name, index:)
     default_html_attributes = {}
     html_attributes = html_attributes.map { |key,value| [ key.to_sym, value ] }.to_h
-    input = form.input(input_name, index:)
 
     default_html_attributes[:required] = input.required
     default_html_attributes[:pattern]  = input.pattern
@@ -41,17 +41,15 @@ class Brut::FrontEnd::Components::Inputs::TextField < Brut::FrontEnd::Components
       default_html_attributes[:value] = (index || true).to_s
       default_html_attributes[:checked] = value == "true"
     else
-      default_html_attributes[:value] = value.to_s
+      default_html_attributes[:value] = value.nil? ? nil : value.to_s
     end
     if !form.new? && !input.valid?
       default_html_attributes["data-invalid"] = true
-      input.validity_state.each do |constraint,violated|
-        if violated
-          default_html_attributes["data-#{constraint}"] = true
-        end
+      input.validity_state.each do |constraint|
+        default_html_attributes["data-#{constraint}"] = true
       end
     end
-    Brut::FrontEnd::Components::Inputs::TextField.new(default_html_attributes.merge(html_attributes))
+    Brut::FrontEnd::Components::Inputs::InputTag.new(default_html_attributes.merge(html_attributes))
   end
 
   def invalid? = @attributes["data-invalid"] == true

data/lib/brut/front_end/components/inputs/radio_button.rb

@@ -3,7 +3,7 @@
 # internal to the {Brut::FrontEnd::Form} treat the radio button group as a single input with
 # a single name and value.  When it comes time to generate HTML, this class is used
 # to generate a single radio button from a group.
-class Brut::FrontEnd::Components::Inputs::RadioButton < Brut::FrontEnd::Components::Inputs::TextField
+class Brut::FrontEnd::Components::Inputs::RadioButton < Brut::FrontEnd::Components::Inputs::InputTag
   # Creates a radio button that is part of a radio button group.  You should call this
   # method once for each radio button in the group.
   #