brut 0.0.1 → 0.0.2

data/lib/brut/front_end/forms/radio_button_group_input.rb

@@ -0,0 +1,46 @@
+class Brut::FrontEnd::Forms::RadioButtonGroupInput
+
+  extend Forwardable
+
+  # (see Brut::FrontEnd::Forms::Input#value)
+  attr_reader :value
+  # (see Brut::FrontEnd::Forms::Input#validity_state)
+  attr_reader :validity_state
+
+  # (see Brut::FrontEnd::Forms::Input#initialize)
+  def initialize(input_definition:, value:)
+    @input_definition = input_definition
+    @validity_state = Brut::FrontEnd::Forms::ValidityState.new
+    if input_definition.array?
+      value ||= []
+    end
+    self.value=(value)
+  end
+
+  def_delegators :"@input_definition", :name,
+                                       :required,
+                                       :array?
+
+  # (see Brut::FrontEnd::Forms::Input#value=)
+  def value=(new_value)
+    value_missing = new_value.nil? || (new_value.kind_of?(String) && new_value.strip == "")
+    missing = if self.required
+                value_missing
+              else
+                false
+              end
+
+    @validity_state = Brut::FrontEnd::Forms::ValidityState.new(
+      value_missing: missing,
+    )
+    @value = new_value
+  end
+
+  # (see Brut::FrontEnd::Forms::Input#server_side_constraint_violation)
+  def server_side_constraint_violation(key,context=true)
+    @validity_state.server_side_constraint_violation(key: key, context: context)
+  end
+
+  # (see Brut::FrontEnd::Forms::Input#valid?)
+  def valid? = @validity_state.valid?
+end

data/lib/brut/front_end/forms/radio_button_group_input_definition.rb

@@ -0,0 +1,29 @@
+# Defines a radio button group for a form, but not it's runtime state (which includes how many radio buttons would need to be
+# rendered).  See {Brut::FrontEnd::Forms::RadioButtonInput}.
+#
+# Note that this ultimately defines the contents for a `<input type="radio">` tag, so the constraints you can place are only those
+# supported by the browser.  Also note that arrays of radio button groups are not currently supported.
+class Brut::FrontEnd::Forms::RadioButtonGroupInputDefinition
+  include Brut::Framework::FussyTypeEnforcement
+  attr_reader :required, :name
+  # Create the input definition
+  # @param [String] name Name of the input (required)
+  # @param [true|false] required true if this field is required, false otherwise. Default is `true`.
+  # @param [true|false] array If true, an error is raised as this is not yet supported
+  def initialize(name:, required: true, array: false)
+    name = name.to_s
+    @name     = type!( name      , String        , "name",     required: true)
+    @required = type!( required  , [true, false] , "required", required: true)
+    @array    = type!( array     , [true, false] , "array", required: true)
+    if @array
+      raise Brut::Framework::Errors::NotImplemented, "Arrays of radio button groups are not yet supported"
+    end
+  end
+
+  def array? = @array
+
+  # Create an Input based on this defitition, initializing it with the given value.
+  def make_input(value:)
+    Brut::FrontEnd::Forms::RadioButtonGroupInput.new(input_definition: self, value: value)
+  end
+end

data/lib/brut/front_end/forms/select_input.rb

@@ -0,0 +1,47 @@
+# Like {Brut::FrontEnd::Forms::Input}, this models a `<SELECT>`'s current state and validity.
+class Brut::FrontEnd::Forms::SelectInput
+
+  extend Forwardable
+
+  # (see Brut::FrontEnd::Forms::Input#value)
+  attr_reader :value
+  # (see Brut::FrontEnd::Forms::Input#validity_state)
+  attr_reader :validity_state
+
+  # (see Brut::FrontEnd::Forms::Input#initialize)
+  def initialize(input_definition:, value:)
+    @input_definition = input_definition
+    @validity_state = Brut::FrontEnd::Forms::ValidityState.new
+    if input_definition.array?
+      value ||= []
+    end
+    self.value=(value)
+  end
+
+  def_delegators :"@input_definition", :name,
+                                       :required,
+                                       :array?
+
+  # (see Brut::FrontEnd::Forms::Input#value=)
+  def value=(new_value)
+    value_missing = new_value.nil? || (new_value.kind_of?(String) && new_value.strip == "")
+    missing = if self.required
+                value_missing
+              else
+                false
+              end
+
+    @validity_state = Brut::FrontEnd::Forms::ValidityState.new(
+      value_missing: missing,
+    )
+    @value = new_value
+  end
+
+  # (see Brut::FrontEnd::Forms::Input#server_side_constraint_violation)
+  def server_side_constraint_violation(key,context=true)
+    @validity_state.server_side_constraint_violation(key: key, context: context)
+  end
+
+  # (see Brut::FrontEnd::Forms::Input#valid?)
+  def valid? = @validity_state.valid?
+end

data/lib/brut/front_end/forms/select_input_definition.rb

@@ -0,0 +1,27 @@
+# Defines a `<select>` for a form, but not it's current runtime state.  {Brut::FrontEnd::Forms::SelectInput} is used to understand the current state or value of a select.
+#
+# Note that a select input definition is defining an HTML `<select>`, not a generic attribute.  Thus, the only constraints you can place on
+# an input are those that the browser supports.  If your form needs server side validation, you can accomplish that in a lot of ways,
+# such as implementing a {Brut::BackEnd::Validators::FormValidator}, or calling
+# {Brut::FrontEnd::Form#server_side_constraint_violation} directly.
+class Brut::FrontEnd::Forms::SelectInputDefinition
+  include Brut::Framework::FussyTypeEnforcement
+  attr_reader :required, :name
+  # Create the input definition
+  # @param [String] name Name of the input (required)
+  # @param [true|false] required true if this field is required, false otherwise. Default is `true`.
+  # @param [true|false] array If true, the form will expect multiple values for this input.  The values will be available as an array. Any values omitted by the user will be present as empty strings.
+  def initialize(name:, required: true, array: false)
+    name = name.to_s
+    @name     = type!( name      , String        , "name",     required: true)
+    @required = type!( required  , [true, false] , "required", required: true)
+    @array    = type!( array     , [true, false] , "array", required: true)
+  end
+
+  def array? = @array
+
+  # Create an Input based on this defitition, initializing it with the given value.
+  def make_input(value:)
+    Brut::FrontEnd::Forms::SelectInput.new(input_definition: self, value: value)
+  end
+end

data/lib/brut/front_end/forms/validity_state.rb

@@ -1,15 +1,19 @@
-# Mirrors a web browser's ValidityState API. Captures the overall state
-# of validity of an input.  This can accomodate server-side constraint violations
-# that are essentially arbitrary.  This means that an instance of this class should
-# fully capture all constraint violations for a given field.  You can 
-# iterate over all the violations with #each, which will yield one `ConstraintViolation` for
-# each failure.  You can query the constraint to determine if it is a client side constraint or not.
+# Mirrors a web browser's ValidityState API, but can also capture additional arbitrary server-side
+# constraint violations to create an entire picture of all constraints violated by a given form input.
+# In a sense, this is a wrapper for one or more {Brut::FrontEnd::Forms::ConstraintViolation} instances in the
+# context of an input.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
 class Brut::FrontEnd::Forms::ValidityState
   include Enumerable
 
+  # Create a validity state initialized with the given violations
+  #
+  # @param [Hash<String,true|false>] constraint_violations map of keys to booleans, where if the boolean is true, there is a
+  # constraint violation described by the key.  The keys are i18n fragments used to construct error messages.
   def initialize(constraint_violations={})
-    @constraint_violations = constraint_violations.map { |key,value|
-      if value
+    @constraint_violations = constraint_violations.map { |key,is_violation|
+      if is_violation
         Brut::FrontEnd::Forms::ConstraintViolation.new(key: key, context: {})
       else
         nil
@@ -17,15 +21,25 @@ class Brut::FrontEnd::Forms::ValidityState
     }.compact
   end
 
-  # Returns true if there are no validation errors
+  # Returns true if there are no constraint violations
   def valid? = @constraint_violations.empty?
 
+  # Returns true if there are constraint violations
+  def constraint_violations? = !self.valid?
+
   # Set a server-side constraint violation. This is essentially arbitrary and dependent
   # on your use-case.
+  #
+  # @param [String|Symbol] key an I18n key fragment used to create a message about the violation
+  # @param [Hash] context interpolated values used to create the message
   def server_side_constraint_violation(key:,context:)
     @constraint_violations << Brut::FrontEnd::Forms::ConstraintViolation.new(key: key, context: context, server_side: true)
   end
 
+  # Iterate over each constraint violation
+  #
+  # @yield [constraint] called once for each constraint violation
+  # @yieldparam constraint [Brut::FrontEnd::Forms::ConstraintViolation]
   def each(&block)
     @constraint_violations.each do |constraint|
       block.call(constraint)

data/lib/brut/front_end/handler.rb

@@ -1,18 +1,34 @@
-# A handler responds to all HTTP requests other than those that render a page. It will be given any data it needs
-# to handle the request to its handle method.  You define this method to accept the parameters you expect.
-#
-# You may also define before_handle which will be given any subset of those parameters and can perform logic before
-# handle is called.  This is most useful in a base class to check for permissions or other cross-cutting concerns.
-#
-# Tests should call handle!
 module Brut::FrontEnd
+  # A handler responds to all HTTP requests other than those that render a page. It will be given any data it needs
+  # to handle the request to its {#handle} method, which you must implement. 
+  # You define this method to accept the parameters you expect. See {Brut::FrontEnd::RequestContext} for how that works.
+  #
+  # You may also define `before_handle` which will be given any subset of those parameters and can perform logic before
+  # handle is called.  This is most useful in a base class to check for permissions or other cross-cutting concerns.
+  #
+  # The primary method of this class is {#handle!} which you should not override, but *should* call in a test.
   class Handler
     include Brut::FrontEnd::HandlingResults
+    include Brut::Framework::Errors
 
+    # You must implement this to accept whatever parameters you need. See {Brut::FrontEnd::RequestContext} for how that works.
+    # The type of the return value determines what will happen:
+    #
+    # * Instance of `URI` - browser will redirect to this URI. Typically, you would do this by calling {Brut::FrontEnd::HandlingResults#redirect_to}.
+    # * Instance of {Brut::FrontEnd::Component} (which notably includes {Brut::FrontEnd::Page}) - renders that component or page
+    # * Array of two items, with the first being an Instance of {Brut::FrontEnd::Component} and the second being an {Brut::FrontEnd::HttpStatus} -  renders that component or page, but responds with the given HTTP status. Useful for Ajax requests that don't return 200, but do return useful content.
+    # * Instance of {Brut::FrontEnd::HttpStatus} - returns just that status code. Typically you would do this by calling {Brut::FrontEnd::HandlingResults#http_status}
+    # * Instance of {Brut::FrontEnd::Download} - sends a file download to the browser.
+    #
+    # @return [URI|Brut::FrontEnd::Component,Array,Brut::FrontEnd::HttpStatus,Brut::FrontEnd::Download]
     def handle(**)
-      raise Brut::Framework::Errors::AbstractMethod
+      abstract_method!
     end
 
+    # Called by Brut to handle the request. Do not override this. If your handler responds to `before_handle` that is called with the
+    # same args as you have defined for {#handle}. If `before_handle` returns anything other than `nil`, that value is returned and
+    # should be one of the values documented in {#handle}.  If `before_handle` returns `nil`, {#handle} is called and whatever it
+    # returns is returned here.
     def handle!(**args)
       result = nil
       if self.respond_to?(:before_handle)
@@ -41,8 +57,11 @@ module Brut::FrontEnd
       result
     end
   end
+  # Namespace for handlers provided by Brut
   module Handlers
     autoload(:CspReportingHandler,"brut/front_end/handlers/csp_reporting_handler")
     autoload(:LocaleDetectionHandler,"brut/front_end/handlers/locale_detection_handler")
+    autoload(:MissingHandler,"brut/front_end/handlers/missing_handler")
+    autoload(:InstrumentationHandler,"brut/front_end/handlers/instrumentation_handler")
   end
 end

data/lib/brut/front_end/handlers/csp_reporting_handler.rb

@@ -1,10 +1,12 @@
+# Receives content security policy violations and logs them. This is set up in {Brut::Framework::MCP}, however CSP reporting is
+# configured in {Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts::ReportOnly}.
 class Brut::FrontEnd::Handlers::CspReportingHandler < Brut::FrontEnd::Handler
   def handle(body:)
     begin
       parsed = JSON.parse(body.read)
-      SemanticLogger["brut:__brut/csp-reporting"].info(parsed)
+      Brut.container.instrumentation.add_attributes(parsed)
     rescue => ex
-      SemanticLogger["brut:__brut/locale"].warn("Got #{ex} from /__brut/locale instead of a parseable JSON object")
+      Brut.container.instrumentation.record_exception(ex)
     end
     http_status(200)
   end

data/lib/brut/front_end/handlers/instrumentation_handler.rb

@@ -0,0 +1,99 @@
+require "base64"
+class Brut::FrontEnd::Handlers::InstrumentationHandler < Brut::FrontEnd::Handler
+  Event = Data.define(:name, :timestamp, :attributes) do
+    def self.from_json(json)
+      name       = json["name"]
+      timestamp  = Time.at(json["timestamp"].to_i / 1000.0)
+      attributes = json["attributes"] || {}
+      self.new(name:,timestamp:,attributes:)
+    end
+  end
+
+  Span = Data.define(:name,:start_timestamp,:end_timestamp,:attributes,:events,:spans) do
+    def self.from_json(json)
+      name            = json["name"]
+      start_timestamp = Time.at(json["start_timestamp"].to_i / 1000.0)
+      end_timestamp   = Time.at(json["end_timestamp"].to_i / 1000.0)
+      attributes      = json["attributes"] || {}
+      events          = (json["events"] || []).map { Event.from_json(it) }
+      spans           = (json["spans"] || []).map { Span.from_json(it) }
+      self.new(name:,start_timestamp:,end_timestamp:,attributes:,events:,spans:)
+    end
+
+    def self.from_header(header_value)
+      if header_value.nil?
+        return nil
+      end
+      if header_value.kind_of?(self)
+        return header_value
+      end
+
+      # This header can have info for several vendors, delimited by commas. We pick
+      # out ours, which has a vendor name 'brut'
+      brut_state = header_value.split(/\s*,\s*/).map { it.split(/\s*=\s*/) }.detect { |vendor,_|
+        vendor == "brut"
+      }[1]
+
+      # Our state is a base-64 encoded JSON blob
+      # each key/value separated by a colon.
+      json = Base64.decode64(brut_state)
+
+      hash = JSON.parse(json)
+      if !hash.kind_of?(Hash)
+        SemanticLogger[self.class].info "Got a #{hash.class} and not a Hash"
+        return nil
+      end
+      self.from_json(hash)
+    end
+  end
+
+  class TraceParent
+    def self.from_header(header_value)
+      if header_value.nil?
+        return nil
+      elsif header_value.kind_of?(self)
+        return header_value
+      else
+        return TraceParent.new(header_value)
+      end
+    end
+
+    def initialize(value)
+      @value = value
+    end
+
+    def as_carrier = { "traceparent" => @value }
+  end
+
+  def handle(http_tracestate:, http_traceparent:)
+    traceparent = TraceParent.from_header(http_traceparent)
+    span        = Span.from_header(http_tracestate)
+
+    if span.nil? || traceparent.nil?
+      SemanticLogger[self.class].info "Missing traceparent or span: #{http_tracestate}, #{http_traceparent}"
+      return http_status(400)
+    end
+
+    carrier = traceparent.as_carrier
+    propagator = OpenTelemetry::Trace::Propagation::TraceContext::TextMapPropagator.new
+    extracted_context = propagator.extract(carrier)
+    OpenTelemetry::Context.with_current(extracted_context) do
+      record_span(span)
+    end
+    http_status(200)
+  end
+
+private
+
+  def record_span(span)
+    otel_span = Brut.container.tracer.start_span(span.name, start_timestamp: span.start_timestamp, attributes: span.attributes)
+    span.events.each do |event|
+      otel_span.add_event(event.name,timestamp: event.timestamp, attributes: event.attributes)
+    end
+    span.spans.each do |inner_span|
+      record_span(inner_span)
+    end
+    otel_span.finish(end_timestamp: span.end_timestamp)
+  end
+
+end

data/lib/brut/front_end/handlers/locale_detection_handler.rb

@@ -1,8 +1,15 @@
+# Receives the Ajax request containing the browser's JavaScript engine's understanding of the user's locale.
+# This is configured in {Brut::Framework::MCP}, however the requests are initiated from the HTML custom element generated by
+# {Brut::FrontEnd::Components::LocaleDetection}.  This will set the timezone on the session via
+# {Brut::FrontEnd::Session#timezone_from_browser=}, and set the 
+# {Brut::FrontEnd::Session#http_accept_language=} *only* if the `Accept-Language` header did not provide a value that is supported by
+# the app.
 class Brut::FrontEnd::Handlers::LocaleDetectionHandler < Brut::FrontEnd::Handler
   def handle(body:,session:)
     begin
       parsed = JSON.parse(body.read)
-      SemanticLogger["brut:__brut/locale"].info("Got #{parsed.class}/#{parsed}")
+      Brut.container.instrumentation.add_attributes(parsed_body: parsed)
+      Brut.container.instrumentation.add_attributes(parsed_class: parsed.class)
       if parsed.kind_of?(Hash)
         locale   = parsed["locale"]
         timezone = parsed["timeZone"]
@@ -11,11 +18,9 @@ class Brut::FrontEnd::Handlers::LocaleDetectionHandler < Brut::FrontEnd::Handler
         if !session.http_accept_language.known?
           session.http_accept_language = Brut::I18n::HTTPAcceptLanguage.from_browser(locale)
         end
-      else
-        SemanticLogger["brut:__brut/locale"].warn("Got a #{parsed.class} from /__brut/locale instead of a hash")
       end
     rescue => ex
-      SemanticLogger["brut:__brut/locale"].warn("Got #{ex} from /__brut/locale instead of a parseable JSON object")
+      Brut.container.instrumentation.record_exception(ex)
     end
     http_status(200)
   end

data/lib/brut/front_end/handlers/missing_handler.rb

@@ -0,0 +1,9 @@
+# Used in development to handle a defined route but a missing page. This arranges to render a nicer error page than the default.
+class Brut::FrontEnd::Handlers::MissingHandler < Brut::FrontEnd::Handler
+  def handle(route:)
+    Brut::FrontEnd::Pages::MissingPage.new(route:)
+  end
+
+  class Form < Brut::FrontEnd::Form
+  end
+end

data/lib/brut/front_end/handling_results.rb

@@ -1,7 +1,17 @@
+# Convienience methods to use inside handlers to make it easier to return richly typed results.
+#
+# @see Brut::FrontEnd::Handler
 module Brut::FrontEnd::HandlingResults
-  # For use inside handle! or process! to indicate the user should be redirected to 
-  # the route for the given class and query string parameters. If the route
-  # does not support GET, an exception is raised
+  # Return this to cause your handler to redirect to `klass`' route with the given query string parameters.
+  #
+  # @param [Class] klass A page or handler class whose route should be redirected-to. Note that if parameters are required, they must
+  # be provided in `query_string_params` or this will raise an error. Note that the class must be for a GET route, since you cannot
+  # redirect to a non-GET.
+  # @param [Hash] query_string_params arguments and parameters for the route.  Any values that correspond to route parameters will be
+  # used to build the route. Remaining will be used as query parameters.
+  #
+  # @raise [ArgumentError] if `klass` is not a `Class` or if `klass` is not for a `GET`
+  # @raise [Brut::Framework::Errors::MissingParameter] if any required route parameters were not provided
   def redirect_to(klass, **query_string_params)
     if !klass.kind_of?(Class)
       raise ArgumentError,"redirect_to should be given a Class, not a #{klass.class}"
@@ -9,6 +19,6 @@ module Brut::FrontEnd::HandlingResults
     Brut.container.routing.uri(klass,with_method: :get,**query_string_params)
   end
 
-  # For use when an HTTP status code must be returned.
+  # Return this to return an HTTP status code from a number or string containing the code.
   def http_status(number) = Brut::FrontEnd::HttpStatus.new(number)
 end

data/lib/brut/front_end/http_method.rb

@@ -1,4 +1,10 @@
+# Wrapper around an HTTP Method, ensuring it contains only a valid value.
 class Brut::FrontEnd::HttpMethod
+  # Create an HTTP method from a string.
+  #
+  # @param [String|Symbol] string a string containing an HTTP method name. Case insensitive, and can be a symbol.
+  #
+  # @raise [ArgumentError] if the passed `string` is not a valid HTTP method
   def initialize(string)
     normalized = string.to_s.downcase.to_sym
     if !self.class.method_names.include?(normalized)
@@ -7,15 +13,21 @@ class Brut::FrontEnd::HttpMethod
     @method = normalized
   end
 
+  # @return [String] the method name, normalized to all lower case, as a string
   def to_s = @method.to_s
+  # @return [Symbol] the method name, normalized to all lower case, as a symbol
   def to_sym = @method.to_sym
   alias to_str to_s
 
+  # @return [true|false] True if the other object is the same class as this and has the same string representation
   def ==(other)
     self.class.name == other.class.name && self.to_s == other.to_s
   end
 
-  def get? = self.to_sym == :get
+  # @return [true|false] true if this is a GET
+  def get?  = self.to_sym == :get
+  # @return [true|false] true if this is a POST
+  def post? = self.to_sym == :post
 
 private
 

data/lib/brut/front_end/http_status.rb

@@ -1,4 +1,11 @@
+# Wrapper around an HTTP status, that can also normalize strings that contain status codes.
 class Brut::FrontEnd::HttpStatus
+  # Create an http status
+  #
+  # @param [Integer|String] number the status code. `to_i` is used to coerce this into a number.
+  #
+  # @raise [ArgumentError] if the value is lower than 100 or greater than 599. Note that the spec allows any value in that range to be
+  #                        considered a valid HTTP status code
   def initialize(number)
     number = number.to_i
     if ((number < 100) || (number > 599))
@@ -7,9 +14,12 @@ class Brut::FrontEnd::HttpStatus
     @number = number
   end
 
+  # @return [Number] the value as a number
   def to_i = @number
+  # @return [String] the value as a string
   def to_s = to_i.to_s
 
+  # @return [true|false] true if the other object has the same class as this and has the same numeric representation
   def ==(other)
     self.class == other.class && self.to_i == other.to_i
   end

data/lib/brut/front_end/layouts/_internal.html.erb

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta content="width=device-width,initial-scale=1" name="viewport">
+    <title>BRUT INTERNAL</title>
+    <meta content="website" property="og:type">
+    <%= component(Brut::FrontEnd::Components::PageIdentifier.new(self.page_name)) %>
+  <style>
+html {
+  font-family: system-ui, serif;
+  background: #fefefe;
+  color: #333;
+}
+code {
+  font-family: courier, monospace;
+}
+pre:has(code) {
+  display: inline-block;
+  background: black;
+  color: #88FF88;
+    padding: 0.5rem;
+      border-radius: 0.5rem;
+}
+pre code {
+  border:none;
+  background-color: transparent;
+  padding: 0;
+}
+h1, h2, h3, h4, h5, h6 {
+  line-height: 1.2;
+}
+p {
+  line-height: 1.4;
+  max-width: 60ch;
+}
+.missing-page {
+  padding: 2rem;
+  width: 60ch;
+  margin-left: auto;
+  margin-right: auto;
+  border-radius: 1rem;
+  box-shadow: rgb(106, 106, 106) 2px 3px 6px 0px;
+  background: color-mix(in srgb, red, white 95%);
+  text-align: center;
+}
+.missing-page p { 
+  text-align: left;
+}
+.missing-page h1 {
+  padding: 1rem;
+  border-radius: 1rem;
+  color: red;
+  display: inline-block;
+  background-color: white;
+  margin:0;
+  box-shadow: rgb(180, 180, 180) -1px -1px 5px 1px inset;
+  border: solid thin #ddd;
+}
+.missing-page pre {
+  box-shadow: rgb(106, 106, 106) 2px 3px 6px 0px;
+}
+  </style>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/lib/brut/front_end/middleware.rb

@@ -1,7 +1,12 @@
 module Brut::FrontEnd
+  # Base class of middlewares you can use in your app. This is currently a marker interface and provides no features
   class Middleware
   end
+  # Holds middlewares that are included with Brut and set up with all Brut apps by default
   module Middlewares
+    autoload(:Favicon,"brut/front_end/middlewares/favicon")
     autoload(:ReloadApp,"brut/front_end/middlewares/reload_app")
+    autoload(:AnnotateBrutOwnedPaths,"brut/front_end/middlewares/annotate_brut_owned_paths")
+    autoload(:OpenTelemetrySpan,"brut/front_end/middlewares/open_telemetry_span")
   end
 end

data/lib/brut/front_end/middlewares/annotate_brut_owned_paths.rb

@@ -0,0 +1,15 @@
+# Annotates any path that is owned by Brut as such. Alleviates downstream code from having to include the actual
+# path determination Brut uses.  After this middleware has run, `env["brut.owned_path"]` will return `true` if the path
+# represents one that Brut is managing.
+class Brut::FrontEnd::Middlewares::AnnotateBrutOwnedPaths < Brut::FrontEnd::Middleware
+  def initialize(app)
+    @app = app
+  end
+  def call(env)
+    if env["PATH_INFO"] =~ /^\/__brut\//
+      Brut.container.instrumentation.add_attributes("brut.owned_path" => true)
+      env["brut.owned_path"] = true
+    end
+    @app.call(env)
+  end
+end

data/lib/brut/front_end/middlewares/favicon.rb

@@ -0,0 +1,16 @@
+# Handles requests for `/favicon.ico` by redirecting the browser to `/static/images/favicon.ico`.
+class Brut::FrontEnd::Middlewares::Favicon < Brut::FrontEnd::Middleware
+  def initialize(app)
+    @app = app
+  end
+  def call(env)
+    if env["PATH_INFO"] =~ /^\/favicon.ico/
+      return [
+        301,
+        { "location" => "/static/images/favicon.ico" },
+        [],
+      ]
+    end
+    @app.call(env)
+  end
+end

data/lib/brut/front_end/middlewares/open_telemetry_span.rb

@@ -0,0 +1,12 @@
+class Brut::FrontEnd::Middlewares::OpenTelemetrySpan < Brut::FrontEnd::Middleware
+  def initialize(app)
+    @app = app
+  end
+  def call(env)
+    path = env["REQUEST_PATH"]
+    method = env["REQUEST_METHOD"]
+    Brut.container.instrumentation.span("HTTP.#{method}.#{path}") do |span|
+      @app.call(env)
+    end
+  end
+end