brut 0.0.20 → 0.0.22

data/lib/brut/front_end.rb

@@ -1,16 +1,7 @@
-# In Brut, the _front end_ is considered anything that interacts directly with a web browser or HTTP.  This includes rendering HTML,
-# managing JavaScript and CSS, and processing form submissions.  It contrasts to {Brut::BackEnd}, which handles the business logic
-# and database.
-#
-# You {Brut::App} defines pages, forms, and actions. A page is backed by a subclass of {Brut::FrontEnd::Page}, which provides
-# dynamic data for rendering. A page can reference {Brut::FrontEnd::Component} subclasses to allow functional decomposition of front
-# end logic and markup, as well as re-use.  Both pages and components have ERB files that describe the HTML to be rendered.
-#
-# A {Brut::FrontEnd::Form} subclass defines a form that a browser will submit to your app. That
-# submission is processed by a {Brut::FrontEnd::Handler} subclass.  Handlers can also respond to other HTTP requests.
-#
-# In addition to responding to requests, you can subclass {Brut::FrontEnd::RouteHook} or {Brut::FrontEnd::Middleware} to perform
-# further manipulation of the request.
+# In Brut, the _front end_ is considered anything that interacts directly 
+# with a web browser or HTTP.  This includes rendering HTML, managing 
+# JavaScript and CSS, and processing form submissions.  It contrasts to 
+# {Brut::BackEnd}, which handles the business logic and database.
 #
 # The entire front-end is based on Rack, so you should be able to achieve anything you need to.
 module Brut::FrontEnd

data/lib/brut/i18n/base_methods.rb

@@ -6,39 +6,72 @@
 # * {Brut::I18n::ForCLI} for CLI apps
 # * {Brut::I18n::ForBackEnd} for back-end classes that aren't generating HTML
 #
+# This module assumes the existence of a three-method protocol that's used for HTML escaping in an
+# HTML-generating web context:
+#
+# * `capture` accepts the block yieled to {#t} and returns whatever it generates.  This needs to exist
+#   because Phlex's API renders to an internal buffer by default.  This module needs to allow Phlex
+#   API methods to render to a different buffer.
+# * `safe` accepts a string and returns a string that is presumed to be HTML safe.
+# * `html_escape` accepts a string and returns a string that is HTML escaped.
+#
+# This module does not implement these methods and assumes that either the class using this module will
+# implement them or that a submodule being used does.  All submodules provided by Brut provide implementations,
+# so this information is only relevant if you are using this module directly.
 module Brut::I18n::BaseMethods
 
   # Access a translation and insert interpolated elemens as needed. This will use the provided key to determine
-  # the actual full key to the translation, as described below.  The value returned is not HTML escaped,
-  # assuming that you have not placed HTML injections in your own translation files.  Interpolated
-  # values *are* HTML escaped, so external input is safe to provide.
-  #
-  # This method also may take a block, and the results of the block are inserted into the `%{block}`
-  # interpolation value in the i18n string, if it's present.
+  # the actual full key to the translation, as described below. See {Brut::I18n::ForHTML#t} for details
+  # on how this works in the context of a {Brut::FrontEnd::Component} or {Brut::FrontEnd::Page}.
   #
   # Any missing interpolation will result in an exception, *except* for the value `field`. When
   # a string has `%{field}` in it, but `field:` is omitted in this call, the value for 
-  # `"general.cv.this_field"` is used. This value, in English, is "this field", so a call
+  # `"cv.this_field"` is used. This value, in English, is "this field", so a call
   # to `t("email.required")` would generate `"This field is required"`, while a call
   # to `t("email.required", field: "E-mail address")` would generate `"E-mail address is required"`.
   #
   # @param [String,Symbol,Array<String>,Array<Symbol>] key used to create one or more keys to be translated.
-  #        This value's behavior is designed to a balance predictabilitiy in what actual key is chosen
-  #        but without needless repetition on a page.  If this value is provided, and is an array, the values
-  #        are joined with "." to form a key.  If the value is not an array, that value is used directly.
-  #        Given this key, two values are checked for a translation: the key itself and 
-  #        the key inside "general.".  If this value is *not* provided, it is expected
-  #        taht the `**rest` hash includes page: or component:.  See that parameter and the example.
-  #
-  # @param [Hash] rest values to use for interpolation of the key's translation. If `key` is omitted,
-  #               this hash should have a value for either `page:` or `component:` (not both).  If
-  #               `page:` is present, it is assumed that the class that has included this module
-  #               is a `Brut::FrontEnd::Page` or is a page component.  It's `page_name` will be used to create
-  #               a key based on the value of `page:`: `pages.«page_name».«page: value»`.
-  #               if `component:` is included, the behavior is the same but for `component` instead of `page`.
-  #               Note that if the page– or component–specific key is not found, this will check
-  #               `general.«page: value»`.
+  #        This value's behavior balances predictabilitiy with what key is used and some flexibilty
+  #        to allow page– or component–specific translations when needed, and fallbacks when not.
+  #
+  #        When an array if given, the values are turned into strings and joined with a "." to
+  #        form a full key.
+  #
+  #        Depending on what class this module is mixed into, additional keys will be tried:
+  #
+  #        * If this is a page, `pages.«page_name».` will be prepended and tried before the key passed in.
+  #          If the `pages.«page_name»` version is not found, the exact key passed in is checked.
+  #        * If this is a page private component, `pages.«page_name».` will be prepended and tried before
+  #          the key passed in. The value for `«page_name»` is determined by the outer class that this
+  #          component is a part of.
+  #        * If this is a component (include if it is a page private component),
+  #          `components.«component_name».` will be prepended and tried before the key passed in.
+  #          If the `components.«component_name»` version is not found, the exact key passed in is checked.
+  #
+  #        The priority of the keys are as follows:
+  #
+  #        1. Component key is checked (unless this is a page)
+  #        2. Page key is checked (unless this is a non-page private component)
+  #        3. The literal key passed-in is checked
+  #
+  #        If no value is found for any key an exception is raised.
+  #
+  # @param [Hash] interpolated_values values to use for interpolation of the key's translation. Note that if
+  #        `:block` is part of this has, you may not pass a block to this method.  Note also
+  #        that `:count` can be used if the key is expected to be pluralized.  This value
+  #        is required for keys that are designed for pluralization. See examples below.
   # @option interpolated_values [Numeric] count Special interpolation to control pluralization.
+  # @option interpolated_values [String] block Value to use for `%{block}`. If this is used, a block may not be
+  #                             yielded.
+  # @yield If a block is passed, it is used for the value of `%{block}`. No parameters are yielded to the block.
+  # @yieldreturn [String] The value to use for the `%{block}` interpolation value.  There is some nuance to
+  #                       how this works.  The value returned is given to `capture`, and *that* value
+  #                       is given to `safe`.  Outside of an HTML-rendering context, these methods
+  #                       simply pass through the contents of the block.  In an HTML-rendering
+  #                       context, however, these methods are assumed to be from
+  #                       [`Phlex::HTML`](https://phlex.fun).  `capture` will create a new Phlex
+  #                       context and capture any HTML built inside the block.  That HTML is assumed
+  #                       to be safe, thus `safe` is called to communicate this to Phlex.
   #
   # @raise [I18n::MissingTranslation] if no translation is found
   # @raise [I18n::MissingInterpolationArgument] if interpolation arguments are missing, or if the key
@@ -47,25 +80,17 @@ module Brut::I18n::BaseMethods
   # @example Simplest usage
   #   # in your translations file
   #   en: {
-  #     general: {
-  #       hello: "Hi!"
-  #     },
-  #     formalized: {
-  #       hello: "Greetings!"
-  #     }
+  #     hello: "Hi!"
   #   }
   #   # in your code
   #   t(:hello) # => Hi!
-  #   t("formalized.hello") # => Greetings!
   #
   # @example Using an array for the key
   #   # in your translations file
   #   en: {
-  #     general: {
-  #       actions: {
-  #         edit: "Make an edit"
-  #       }
-  #     },
+  #     actions: {
+  #       edit: "Make an edit"
+  #     }
   #   }
   #   # in your code
   #   t([:actions, :edit]) # => Make an edit
@@ -73,9 +98,7 @@ module Brut::I18n::BaseMethods
   # @example Using page:
   #   # in your translations file
   #   en: {
-  #     general: {
-  #       new_widget: "Make a New Widget",
-  #     },
+  #     new_widget: "Make a New Widget",
   #     pages: {
   #       HomePage: {
   #         new_widget: "Create new Widget"
@@ -86,62 +109,112 @@ module Brut::I18n::BaseMethods
   #     },
   #   }
   #   # in your code for HomePage
-  #   t(page: :new_widget) # => Create new Widget
+  #   t(:new_widget) # => Create new Widget
   #   # in your code for WidgetsPage
-  #   t(page: :new_widget) # => Create New
-  #   # in your code for SomeOtherEPage
-  #   t(page: :new_widget) # => Make a New Widget
+  #   t(:new_widget) # => Create New
+  #   # in your code for SomeOtherPage
+  #   t(:new_widget) # => Make a New Widget
   #
-  # @example Using page: with an array
+  # @example Using in a component
   #   # in your translations file
   #   en: {
+  #     status: {
+  #       ready: "Available",
+  #       stalled: "Stalled",
+  #       completed: "Done",
+  #     },
+  #     components: {
+  #       TagComponent: {
+  #         status: {
+  #           ready: "Ready",
+  #           stalled: "Waiting",
+  #         }
+  #       },
+  #     },
+  #   }
+  #   # in your code for TagComponent
+  #   t(page: [ :status, :ready ]) # => Ready
+  #   t(page: [ :status, :completed ]) # => Done
+  #   # in your code for StatusComponent
+  #   t(page: [ :status, :ready ]) # => Available
+  #   t(page: [ :status, :completed ]) # => Done
+  #
+  # @example Using in a page-private component
+  #   # in your translations file
+  #   en: {
+  #     status: {
+  #       ready: "Available",
+  #       stalled: "Stalled",
+  #       completed: "Done",
+  #     },
   #     pages: {
   #       WidgetsPage: {
-  #         new_widget: "Create New"
-  #         captions: {
-  #           new: "New Widgets"
-  #         }
+  #         new_widget: "Create New",
+  #         nevermind: "Don't Create One",
+  #       },
+  #     }
+  #     components: {
+  #       "WidgetsPage::WidgetComponent": {
+  #         new_widget: "Make New Widget",
   #       },
   #     },
   #   }
-  #   # in your code for HomePage
-  #   t(page: [ :captions, :new ]) # => New Widgets
-  def t(key=:look_in_rest,**rest,&block)
-    if key == :look_in_rest
-
-      page      = rest.delete(:page)
-      component = rest.delete(:component)
-
-      if !page.nil? && !component.nil?
-        raise ArgumentError, "You may only specify page or component, not both"
-      end
+  #   # in your code for WidgetsPage::WidgetComponent
+  #   t(page: :new_widget) # => Make New Widget
+  #   t(page: :nevermind) # => Don't Create One
+  #
+  # @example Using a block in a page or component
+  #   # in your translations file
+  #   en: {
+  #     greeting: "Hello there %{name}, you may %{block}",
+  #   }
+  #   # Inside a component where
+  #   # Brut::I18n::ForHTML has been included
+  #   def view_template
+  #     h1 do
+  #       raw(t(:greeting), name: user.name) do
+  #         a(href: "https://support.example.com") do
+  #           "contact support"
+  #         end
+  #       end
+  #     end
+  #   end
+  #   # This will produce this HTML, assuming user.name is "Pat":
+  #   <h1>
+  #     Hell there Pat, you may
+  #     <a href="https://support.example.com">
+  #       contact support
+  #     </a>
+  #   </h1>
+  def t(key,**interpolated_values,&block)
+    keys_to_check = []
+    key = Array(key).join('.')
+    is_page_private_component = self.kind_of?(Brut::FrontEnd::Component) &&
+                                self.page_private?
+    is_page                   = self.kind_of?(Brut::FrontEnd::Page)
+    is_component              = self.kind_of?(Brut::FrontEnd::Component) && !is_page
 
-      subkey = nil
-      if page
-        subkey = Array(page).join(".")
-        key = ["pages.#{self.page_name}.#{subkey}"]
-      elsif component
-        subkey = Array(component).join(".")
-        key = ["components.#{self.component_name}.#{subkey}"]
-      else
-        raise ArgumentError, "If you omit an explicit key, you must specify page or component"
-      end
-      key << "general.#{subkey}"
-    else
-      key = Array(key).join('.')
-      key = [key,"general.#{key}"]
+    if is_component
+      keys_to_check << "components.#{self.component_name}.#{key}"
+    end
+    if is_page
+      keys_to_check << "pages.#{self.page_name}.#{key}"
+    elsif is_page_private_component
+      keys_to_check << "pages.#{self.containing_page_name}.#{key}"
     end
+    keys_to_check << key
+
     if !block.nil?
-      if rest[:block]
+      if interpolated_values[:block]
         raise ArgumentError,"t was given a block and a block: param. You can't do both "
       end
       block_contents = safe(capture(&block))
-      rest[:block] = block_contents
+      interpolated_values[:block] = block_contents
     end
-    t_direct(key,**rest)
+    t_direct(keys_to_check,**interpolated_values.merge(key_given: key))
   rescue I18n::MissingInterpolationArgument => ex
     if ex.key.to_s == "block"
-      raise ArgumentError,"One of the keys #{key.join(", ")} contained a %{block} interpolation value: '#{ex.string}'. This means you must use t_html *and* yield a block to it"
+      raise ArgumentError,"One of the keys #{key.join(", ")} contained a %{block} interpolation value: '#{ex.string}'. This means you must yield a block to `t`"
     else
       raise
     end
@@ -152,7 +225,7 @@ module Brut::I18n::BaseMethods
   end
 
   def this_field_value
-    @__this_field_value ||= ::I18n.t("general.cv.this_field", raise: true)
+    @__this_field_value ||= ::I18n.t("cv.this_field", raise: true)
   end
 
   # Directly access translations without trying to be smart about deriving the key.  This is useful
@@ -160,28 +233,43 @@ module Brut::I18n::BaseMethods
   #
   # @param [Array<String>,Array<Symbol>] keys list of keys representing what is to be translated. The
   #                                           first key found will be used. If no key in the list is found
-  #                                           will raise a I18n::MissingTranslation
+  #                                           will raise a I18n::MissingTranslation. 
   # @param [Hash] interpolated_values value to use for interpolation of the key's translation
   # @option interpolated_values [Numeric] count Special interpolation to control pluralization.
+  # @option interpolated_values [String|Symbol] key_given If included, this is not used for interpolation, but
+  #                                             will be used in error messages to represent the key
+  #                                             given to `t`.
   #
   # @raise [I18n::MissingTranslation] if no translation is found
   # @raise [I18n::MissingInterpolationArgument] if interpolation arguments are missing, or if the key
   #                                             has pluralizations and no count: was given
   def t_direct(keys,interpolated_values={})
     keys = Array(keys).map(&:to_sym)
+    key_given = interpolated_values.delete(:key_given)
     default_interpolated_values = {
       field: this_field_value,
     }
     escaped_interpolated_values = interpolated_values.map { |key,value|
       if value.kind_of?(String)
-        [ key, CGI.escapeHTML(value) ]
+        [ key, html_escape(value) ]
       else
         [ key, value ]
       end
     }.to_h
     result = ::I18n.t(keys.first, default: keys[1..-1],raise: true, **default_interpolated_values.merge(escaped_interpolated_values))
     if result.kind_of?(Hash)
-      raise I18n::MissingInterpolationArgument.new(:count,interpolated_values,keys.join(","))
+      incorrect_pluralization = result.keys.none? { |key| key == :one }
+      if incorrect_pluralization
+        key_message = if key_given
+                        "Key '#{key_given}'"
+                      else
+                        "One of the keys"
+                      end
+        raise Brut::Framework::Errors::Bug,
+          "#{key_message} resulted in a Hash that doesn't appear to be created for pluralizations. This means that you may have given a key expecting it to map to a translation but it is actually a namespace for other keys.  Please adjust your translations file to avoid this situation. Keys checked:\n#{keys.join(", ")}\nSub keys found:\n#{result.keys.join(', ')}"
+      else
+        raise I18n::MissingInterpolationArgument.new(:count,interpolated_values,keys.join(","))
+      end
     end
     result
   end

data/lib/brut/i18n/for_back_end.rb

@@ -1,5 +1,9 @@
+# Use this to access translations in any back-end code.
+# This implementation does support blocks yielded to {#t}, however
+# their values are not necessarily HTML-escaped.
 module Brut::I18n::ForBackEnd
   include Brut::I18n::BaseMethods
   def safe(string) = string
   def capture(&block) = block.()
+  def html_escape(value) = value
 end

data/lib/brut/i18n/for_cli.rb

@@ -1,5 +1,9 @@
+# Use this to access translations in any CLI.
+# This implementation does support blocks yielded to {#t}, however
+# their values are not necessarily HTML-escaped.
 module Brut::I18n::ForCLI
   include Brut::I18n::BaseMethods
   def safe(string) = string
   def capture(&block) = block.()
+  def html_escape(value) = value
 end

data/lib/brut/i18n/for_html.rb

@@ -1,12 +1,40 @@
 # I18n for components or pages, which are assumed to be Phlex components.
-# To use this outside of a Phlex context, you must define these two
-# methods to ensure proper HTML escaping happens:
+# This will do HTML escaping as follows:
+#
+# * Interpolated values are always HTML-escaped
+# * When a block is used, that value is assumed to be safe HTML,
+#   and generated outside the current Phlex context. It's value is
+#   captured (via `#capture`) and then declared HTML safe by being
+#   passed to `#safe`.
+#
+# Unless you put HTML injections into your translations file, this should result
+# in safe HTML in any translation.
+#
+# This module provides two features that aren't part of {#Brut::I18n::BaseMethods}:
+#
+# * {#t} calls `#safe` on its return value, indicating that the string is safe. To use
+#   this string in a Phlex view, you *must* call `#raw` and pass it the string.
+# * {#html_escape} is implemented to escape values it's given.
+#
+#
+# @example
+#   class StatusComponent < AppComponent
+#     def initialize(status:)
+#       @status = status
+#     end
+#     def view_template
+#       div do
+#         raw(
+#           t( [ :status, @status ] )
+#         )
+#       end
+#     end
+#   end
 #
-# * `safe` to accept a string and return a string.
-# * `capture` to accept a block and return its contents as a string.
 module Brut::I18n::ForHTML
   include Brut::I18n::BaseMethods
   def t(...)
     safe(super)
   end
+  def html_escape(value) = CGI.escapeHTML(value)
 end

data/lib/brut/i18n/http_accept_language.rb

@@ -1,8 +1,19 @@
+# Manages the value for the HTTP
+# [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept-Language)
+# header. Generally, you would not interact with this class directly, however it is used
+# by Brut to make a guess as to which Locale a browser is reporting.
 class Brut::I18n::HTTPAcceptLanguage
+  # A locale with the weight (value for q=) it was given in the Accept-Language header
   WeightedLocale = Data.define(:locale, :q) do
+    # Returns the primary locale for whatever locale
+    # this is holding.  For example, the primary locale 
+    # of "en-US" is "en".
     def primary_locale = self.locale.gsub(/\-.*$/,"")
+
+    # True if this locale is a primary locale
     def primary? = self.primary_locale == self.locale
 
+    # Return a new WeightedLocale that is the primary locale.
     def primary_only
       self.class.new(locale: self.primary_locale, q: self.q)
     end
@@ -12,6 +23,11 @@ class Brut::I18n::HTTPAcceptLanguage
     end
   end
 
+  # Parse the value stored in the session.
+  #
+  # @param [String] session_value the value stored in the session.
+  # @return [Brut::I18n::HTTPAcceptLanguage] a usable object. If the provided value
+  #         is blank, #{Brut::I18n::HTTPAcceptLanguage::AlwaysEnglish} is returned.
   def self.from_session(session_value)
     values = session_value.to_s.split(/,/).map { |value|
       locale,q = value.split(/;/)
@@ -24,6 +40,19 @@ class Brut::I18n::HTTPAcceptLanguage
     end
   end
 
+  # Parse the value provided by the browser via 
+  # {Brut::FrontEnd::Handlers::LocaleDetectionHandler} via
+  # the `brut-locale-detection` custom element (which
+  # uses `Intl.DateTimeFormat().resolvedOptions()` to determine
+  # the locale).
+  #
+  # Because this value is not in the same format as the Accept-Language
+  # header, it's `q` is assumed to be 1.
+  #
+  # @param [String] value the value provided by the brower.
+  #
+  # @return [Brut::I18n::HTTPAcceptLanguage] a usable object. If the provided value
+  #         is blank, #{Brut::I18n::HTTPAcceptLanguage::AlwaysEnglish} is returned.
   def self.from_browser(value)
     value = value.to_s.strip
     if value == ""
@@ -33,6 +62,10 @@ class Brut::I18n::HTTPAcceptLanguage
     end
   end
 
+  # Parse from the HTTP Accept-Language header.
+  #
+  # @return [Brut::I18n::HTTPAcceptLanguage] a usable object. If the provided value
+  #         is blank, #{Brut::I18n::HTTPAcceptLanguage::AlwaysEnglish} is returned.
   def self.from_header(header_value)
     header_value = header_value.to_s.strip
     if header_value == "*" || header_value == ""
@@ -50,14 +83,28 @@ class Brut::I18n::HTTPAcceptLanguage
     end
   end
 
+  # Ordered list of locales, from highest-weighted to lowest.
   attr_reader :weighted_locales
+  # @param [Array<Brut::I18n::HTTPAcceptLanguage::WeightedLocale>] weighted_locales locales to use. They do not
+  #        need to be ordered
   def initialize(weighted_locales)
     @weighted_locales = weighted_locales.sort_by(&:q).reverse
   end
+
+  # True if the values inside this object represent known locales, and not a guess based on missing information.
+  # In general, this returns true if the values came from the Accept-Language header, or from the browser.
   def known? = true
+
+  # Serialize for storage in the session
+  #
+  # @return [String] a string that can be stored in the session and later deserialized via {.from_session}.
   def for_session = @weighted_locales.map { |weighted_locale| "#{weighted_locale.locale};#{weighted_locale.q}" }.join(",")
   def to_s = self.for_session
 
+  # A subclass that represents the use of English and only English.  This is
+  # used when attempts to determine the locale fail.  Instances of this class
+  # are considered "unknown" ({#known?} returns false), which allows Brut
+  # to replace this with a known value later on.
   class AlwaysEnglish < Brut::I18n::HTTPAcceptLanguage
     def initialize
       super([ WeightedLocale.new(locale: "en", q: 1) ])

data/lib/brut/instrumentation/open_telemetry.rb

@@ -1,3 +1,7 @@
+# Class to interact with the OpenTelemetry standard in a simpler way than
+# the provided Ruby gem does.  In general, you should use this class
+# via `Brut.container.instrumentation`, and you should *not* use the 
+# OpenTelemetry ruby library directly.  You probably wouldn't want to, anyway.
 class Brut::Instrumentation::OpenTelemetry
   # Create a span around the given block of code.
   #
@@ -39,20 +43,51 @@ class Brut::Instrumentation::OpenTelemetry
                            timestamp:)
   end
 
+  # Record an exception.  In general, use this only if:
+  #
+  # * You need to have the parent span record this particular exception
+  # * You are not going to re-raise the exception.
+  #
+  # Otherwise, look at {#record_and_reraise_exception!}.
+  #
+  # @param [Exception] ex the exception to record.
+  # @param [Hash] attributes any attributes to attach that will show up in your OTel provider
   def record_exception(ex,attributes=nil)
     current_span = OpenTelemetry::Trace.current_span
     current_span.record_exception(ex,attributes: NormalizedAttributes.new(nil,attributes).to_h)
   end
 
+  # Record an exception and re-raise it. This is useful if you want
+  # the exception recorded as part of the parent span, but still plan
+  # to let it raise.  Don't do this for every exception you intend to raise.
+  # @param [Exception] ex the exception to record.
+  # @param [Hash] attributes any attributes to attach that will show up in your OTel provider
+  # @raise [Exception] the exception passed in.
+  def record_and_reraise_exception!(ex,attributes=nil)
+    reecord_exception(ex,attributes)
+    raise ex
+  end
+
+
   # Adds attributes to the span, converting the hash or keyword arguments to strings. This will use
   # the app's Otel prefix for all attributes, so you do not have to prefix them.
-  # If you need to set standard attributes, you should use {Brut::Instrumentation::OpenTelemetry::Span#add_prefixed_attributes} instead.
+  # If you need to set standard attributes, you should use {#add_prefixed_attributes} instead.
   # @param [Hash] attributes any attributes to attach to the event.
   def add_attributes(attributes)
     current_span = OpenTelemetry::Trace.current_span
     current_span.add_attributes(NormalizedAttributes.new(:detect,attributes).to_h)
   end
 
+  # Adds attributes to the span, prefixing each key with the given prefix, then converting the hash or keyword arguments to strings.  For example, if the prefix is 'my_app' and you add the attributes 'type' and 'reason', the actual attribute names will be 'my_app.type' and 'my_app.reason'.
+  #
+  # @see #add_attributes
+  def add_prefixed_attributes(prefix,attributes)
+    current_span = OpenTelemetry::Trace.current_span
+    current_span.add_attributes(
+      NormalizedAttributes.new(prefix,attributes).to_h
+    )
+  end
+
 private
 
   class NormalizedAttributes

data/lib/brut/instrumentation.rb

@@ -1,10 +1,8 @@
+# Namespace for instrumentation setup and support.  Brut strives to provide useful
+# instrumentation by default.
+#
 module Brut::Instrumentation
   autoload(:OpenTelemetry,"brut/instrumentation/open_telemetry")
   autoload(:LoggerSpanExporter,"brut/instrumentation/logger_span_exporter")
-
-  # Convenience method to add attributes to create a span without accessing the instrumentation instance directly.
-  def span(name,**attributes,&block)
-    Brut.container.instrumentation.span(name,**attributes,&block)
-  end
 end
 

data/lib/brut/sinatra_helpers.rb

@@ -9,6 +9,7 @@ module Brut::SinatraHelpers
     sinatra_app.path("/__brut/locale_detection",method: :post)
     sinatra_app.path("/__brut/instrumentation",method: :get)
     sinatra_app.set :host_authorization, permitted_hosts: Brut.container.permitted_hosts
+    sinatra_app.set :show_exceptions, false
   end
 
   # @private
@@ -178,16 +179,23 @@ module Brut::SinatraHelpers
             form_class: form_class,
           )
 
-          handler = handler_class.new
           form = if form_class.nil?
                    nil
                  else
                    form_class.new(params: params)
                  end
 
-          process_args = Brut::FrontEnd::RequestContext.current.as_method_args(handler,:handle,request_params: params,form: form,route:brut_route)
+          constructor_args = Brut::FrontEnd::RequestContext.current.as_constructor_args(
+            handler_class,
+            request_params: params,
+            route: brut_route,
+            form: form,
+          )
+
+          handler = handler_class.new(**constructor_args)
 
-          result = handler.handle!(**process_args)
+          result = handler.handle!
+          span.add_prefixed_attributes("brut", result_class: result.class)
 
           case result
           in URI => uri