brut 0.0.1 → 0.0.2

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

@@ -1,23 +1,38 @@
+# Reloads the app without requiring a restart. This should only be used in development.  Every single request will trigger this.
 class Brut::FrontEnd::Middlewares::ReloadApp < Brut::FrontEnd::Middleware
   LOCK = Concurrent::ReadWriteLock.new
   def initialize(app)
     @app = app
   end
   def call(env)
-    Brut.container.instrumentation.instrument(Brut::Instrumentation::Event.new(category: "middleware", subcategory: self.class.name, name: "call")) do
+    path = env["PATH_INFO"].to_s
+    dir = if path[0] == "/"
+            path.split(/\//)[1]
+          else
+            path.split(/\//)[0]
+          end
+    reload = !["static","js","css","__brut"].include?(dir)
+    if reload
       # We can only have one thread reloading stuff at a time, per process.
       # The ReadWriteLock achieves this.
       #
       # Here, if any thread is serving a request, THIS thread will wait here.
       # Once no other thread is serving a request, the write lock is acquired and a reload happens.
-      LOCK.with_write_lock do
-        begin
-          Brut.container.zeitwerk_loader.reload
-          Brut.container.routing.reload
-          Brut.container.asset_path_resolver.reload
-          ::I18n.reload!
-        rescue => ex
-          SemanticLogger[self.class].warn("Reload failed - your browser may not show you the latest code: #{ex.message}")
+      Brut.container.instrumentation.span(self.class.name) do |span|
+        LOCK.with_write_lock do
+          span.add_event("lock acquired")
+          begin
+            Brut.container.zeitwerk_loader.reload
+            span.add_event("Zeitwerk reloaded")
+            Brut.container.routing.reload
+            span.add_event("Routing reloaded")
+            Brut.container.asset_path_resolver.reload
+            span.add_event("Asset Path Resolver reloaded")
+            ::I18n.reload!
+            span.add_event("I18n reloaded")
+          rescue => ex
+            SemanticLogger[self.class].warn("Reload failed - your browser may not show you the latest code: #{ex.message}\n#{ex.backtrace}")
+          end
         end
       end
       # If another thread has a write lock, we wait here so that the reload can complete before serving
@@ -26,6 +41,9 @@ class Brut::FrontEnd::Middlewares::ReloadApp < Brut::FrontEnd::Middleware
       LOCK.with_read_lock do
         @app.call(env)
       end
+    else
+      Brut.container.instrumentation.add_event("Not reloading")
+      @app.call(env)
     end
   end
 end

data/lib/brut/front_end/page.rb

@@ -1,42 +1,77 @@
-# A page is a component that has a layout and thus is intended to be
-# an entire web page, not just a fragment.
+# A page backs a web page.  A page renders everything in the browser window.  Technically, it is exactly like a component except that
+# it can have a layout.
+#
+# When subclassing this to create a page, your initializer's signature will determine what data
+# is required for your page to work.  It can be anything, just keep in mind that any component your page uses may
+# require additional data.
+#
+# If your page 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 page named `Auth::LoginPage`, it would expected to be in
+# `app/src/front_end/pages/auth/login_page.rb`.  Thus, Brut will also expect
+# `app/src/front_end/pages/auth/login_page.html.erb` to exist as well. That ERB file is used with an instance of your
+# pages's class to render the page's HTML.
+#
+# @see Brut::FrontEnd::Component
 class Brut::FrontEnd::Page < Brut::FrontEnd::Component
   include Brut::FrontEnd::HandlingResults
   using Brut::FrontEnd::Templates::HTMLSafeString::Refinement
 
+  # Returns the name of the layout for this page.  This string is used to find an ERB file in `app/src/front_end/layouts`. Every page
+  # must have a layout. If you wish to render a page with no layout, create an empty layout in your app and use that.
+  #
+  # @return [String] The name of the layout. May not be `nil`.
   def layout = "default"
 
+  # Called after the page is created, but before {#render} is called.  This allows you to do any pre-flight checks and potentially
+  # redirect the user or produce an error.
+  #
+  # @return [URI|Brut::FrontEnd::HttpStatus|Object] If you return a `URI` (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#redirect_to}), the user is redirected and {#render} is never called. If you return a {Brut::FrontEnd::HttpStatus} (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#http_status}), {#render} is skipped and that status is returned with no content.  If anything else is returned, {#render} is called as normal.
   def before_render = nil
 
+  # @!visibility private
   def handle!
     case before_render
     in URI => uri
+      Brut.container.instrumentation.add_event("before_render got a URI", uri: uri)
       uri
     in Brut::FrontEnd::HttpStatus => http_status
+      Brut.container.instrumentation.add_event("before_render got status", http_status: http_status)
       http_status
     else
       render
     end
   end
 
-  # Overrides component's render to add the concept of a layout.
-  # A layout is an HTML/ERB file that will contain this page's contents.
+  # The core method of a page, which overrides {Brut::FrontEnd::Component#render}. This is expected to return
+  # a string to be sent as a response to an HTTP request. Generally, you should not call this method as it is
+  # called by Brut when your page is requested.
+  #
+  # Also, generally don't override this unles you need to do something unusual.  Overriding this will completely bypass the layout
+  # system and skip all ERB processing. Unlike {Brut::FrontEnd::Component#render}, overriding this method does not provide access to injected data from the request context.
+  #
+  # @return [Brut::FrontEnd::Templates::HTMLSafeString] string containing the page's full HTML.
   def render
-    Brut.container.layout_locator.locate(self.layout).
-      then { |layout_erb_file| Brut::FrontEnd::Template.new(layout_erb_file)
-      } => layout_template
+    layout_template = Brut.container.layout_locator.locate(self.layout).
+      then { |layout_erb_file| Brut::FrontEnd::Template.new(layout_erb_file) }
 
-    Brut.container.page_locator.locate(self.template_name).
-      then { |erb_file| Brut::FrontEnd::Template.new(erb_file)
-      } => template
+    template = Brut.container.page_locator.locate(self.template_name).
+      then { |erb_file| Brut::FrontEnd::Template.new(erb_file) }
 
+    Brut.container.instrumentation.add_event("templates found", layout: layout_template.template_file_path, page: template.template_file_path)
+
+    page = template.render_template(self).html_safe!
     layout_template.render_template(self) do
-      template.render_template(self).html_safe!
+      page
     end
   end
 
+  # @return [String] name of this page for use in debugging or for whatever reason you may want to dynamically refer to the page's name.  The default value is the class name.
   def self.page_name = self.name
+
+  # Convienience method for {.page_name}.
   def page_name = self.class.page_name
+
+  # @!visibility private
   def component_name = raise Brut::Framework::Errors::Bug,"#{self.class} is not a component"
 
 private
@@ -45,3 +80,7 @@ private
 
 end
 
+# Holds pages included with the Brut framework
+module Brut::FrontEnd::Pages
+  autoload(:MissingPage,"brut/front_end/pages/missing_page.rb")
+end

data/lib/brut/front_end/pages/_missing_page.html.erb

@@ -0,0 +1,17 @@
+<main class="missing-page">
+  <h1>Route Not Implemented</h1>
+  <h2>Cannot Find <code><%= class_name %></code></h2>
+  <p>
+    You defined <code><%= path_template %></code> in your app, however the class(es) that impelment it could not be found.
+  </p>
+  <% if scaffold_command %>
+    <p>
+      To create the expected <%= types_of_files_created %>, run this command:
+    </p>
+    <pre><code>bin/scaffold <%= scaffold_command %> <%= class_name %></code></pre>
+  <% else %>
+    <p>
+      Something is wrong - Brut cannot figure out what sort of route you are trying to create. This is probably a bug!
+    </p>
+  <% end %>
+</main>

data/lib/brut/front_end/pages/missing_page.rb

@@ -0,0 +1,36 @@
+# Used in development when a route has been mapped, but no class exists for the page. This
+# renders a hopefully helpful message in the browser to allow the developer to know what 
+# next steps to take.
+class Brut::FrontEnd::Pages::MissingPage < Brut::FrontEnd::Page
+
+  attr_reader :class_name,
+              :path_template,
+              :class_file,
+              :scaffold_command,
+              :types_of_files_created
+
+  def initialize(route:)
+    @class_name = route.exception.class_name_path.join("::")
+    @path_template = route.path_template
+    parts = route.exception.class_name_path.map { |part|
+      RichString.new(part).underscorized.to_s
+    }
+    last_part = parts[-1]
+    parts[-1] = last_part + ".rb"
+    if route.class == Brut::FrontEnd::Routing::MissingForm
+      @scaffold_command       = "form"
+      @types_of_files_created = "form class, handler class, and test"
+    elsif route.class == Brut::FrontEnd::Routing::MissingPage
+      @scaffold_command       = "page"
+      @types_of_files_created = "page class, HTML template, and test"
+    elsif route.class == Brut::FrontEnd::Routing::MissingPath
+      @scaffold_command       = "handler"
+      @types_of_files_created = "handler class, and test"
+    else
+      nil
+    end
+  end
+
+  def layout = "_internal"
+  def template_name = "_missing_page"
+end

data/lib/brut/front_end/request_context.rb

@@ -1,4 +1,20 @@
+# Container for request-specific information that serves as the source of what can be automaticall passed to various methods by Brut.
+#
+# The intention for this class is to provide access to the 80% of stuff needed by most requests, to alleviate the need to have to dig
+# into `env` or the Rack request.  This also allows arbitrary information to be inserted and made available later.
+#
+# Several methods of Brut objects take keyword arguments in their initializer or a particular method.  The names of those keyword
+# arguments correspond to values that are contained by this class.  Thus, if you are creating, say, a {Brut::FrontEnd::Page} subclass,
+# and create an initializer for it that accepts the `clock:` keyword argument, the managed instance of {Clock} will be passed into it
+# when Brut creates an instance of the class.
 class Brut::FrontEnd::RequestContext
+  # Create a new RequestContext based on some of the information provided by Rack
+  #
+  # @param [Hash] env the Rack `env` object, as available to any middleware
+  # @param [Brut::FrontEnd::Session] session the current session, noting that this is the Brut (or your app) session class and not the Rack session.
+  # @param [Brut::FrontEnd::Flash] flash the current flash
+  # @param [true|false] xhr true if this is an XHR request.
+  # @param [Object] body the `request.body` as provided by Rack
   def initialize(env:,session:,flash:,xhr:,body:)
     @hash = {
       env:,
@@ -7,16 +23,25 @@ class Brut::FrontEnd::RequestContext
       xhr:,
       body:,
       csrf_token: Rack::Protection::AuthenticityToken.token(env["rack.session"]),
-      clock: Clock.new(session.timezone_from_browser),
+      clock: Clock.new(session.timezone),
     }
   end
 
 
+  # Set an arbitrary value that can be injected later
+  # @param [String|Symbol] key the name of the value. This is converted to a symbol.
+  # @param [Object] value the value to map. Should not be nil.
   def []=(key,value)
     key = key.to_sym
     @hash[key] = value
   end
 
+  # Access the given value, raising an exception if it has not been set or if it's nil. 
+  # @param [String|Symbol] key the value to fetch.
+  #
+  # @return [Object] the mapped value
+  #
+  # @raise [ArgumentError] if `key` was never mapped or maps to `nil`.
   def fetch(key)
     if self.key?(key)
       value = self[key]
@@ -30,26 +55,101 @@ class Brut::FrontEnd::RequestContext
     end
   end
 
+  # Access a given value, returning `nil` if it's not mapped or is `nil`
+  # @param [String|Symbol] key the value to get
+  # @return [Object] the mapped value
   def [](key)
     @hash[key.to_sym]
   end
 
+  # Check if a given value has been mapped.
+  # @param [String|Symbol] key the value to check
+  # @return [true|false] if the value is mapped. Note that if `nil` was injected, this method returns `true`.
   def key?(key)
     @hash.key?(key.to_sym)
   end
 
-  # Returns a hash suitable to passing into this class' constructor.
-  def as_constructor_args(klass, request_params:)
-    args_for_method(method: klass.instance_method(:initialize), request_params:, form: nil)
+  # Based on `klass`' constructor, returns a Hash that maps all keywords it requires to the values stored in this
+  # `RequestContext`. It is assumed that `request_params:` contains the query parameters so they can be injected.
+  # The {Brut::FrontEnd::Routing::Route} can also be injected to pass in.
+  #
+  # @example
+  #     class SomeClass
+  #       def initialize(flash:,clock:,date:)
+  #         # ...
+  #       end
+  #     end
+  #    
+  #     hash = request_context.as_constructor_args(
+  #       SomeClass,
+  #       request_params: { date: "2024-11-11" }
+  #     )
+  #    
+  #     # hash contains:
+  #     # {
+  #     #   flash: «Flash used to create the RequestContext»,
+  #     #   clock: «Clock used to create the RequestContext»,
+  #     #   date: "2024-11-11",
+  #     # }
+  #    
+  #     object = SomeClass.new(**hash)
+  #
+  # @param [Class] klass a class that is to be instantiated entirely by the contents of this `RequestContext`.
+  # @param [Hash] request_params Query string parameters provided by Rack.
+  # @param [Brut::FrontEnd::Routing::Route] route the route that triggered the request.
+  # @return [Hash] can be splatted to keyword arguments and passed to the constructor of `klass`
+  #
+  # @raise [ArgumentError] if the constructor has any non-keyword arguments, or if any required keyword argument is
+  #                        not present in this `RequestContext`.
+  def as_constructor_args(klass, request_params:, route:nil)
+    args_for_method(method: klass.instance_method(:initialize), request_params:, form: nil, route:)
   end
 
-  def as_method_args(object, method_name, request_params:,form:)
-    args_for_method(method: object.method(method_name), request_params:, form:)
+  # Based on `object`' method, returns a Hash that maps all keywords it requires to the values stored in this
+  # `RequestContext`. It is assumed that `request_params:` contains the query parameters so they can be injected.
+  # It is also assumed that `form:` is the {Brut::FrontEnd::Form} that is provided as part of the request.
+  # The {Brut::FrontEnd::Routing::Route} can also be injected to pass in.
+  #
+  # @example
+  #     class SomeClass
+  #       def doit(flash:,clock:,date:)
+  #         # ...
+  #       end
+  #     end
+  #    
+  #     object = SomeClass.new
+  #    
+  #     hash = request_context.as_method_args(
+  #       object,
+  #       :doit,
+  #       request_params: { date: "2024-11-11" }
+  #     )
+  #    
+  #     # hash contains:
+  #     # {
+  #     #   flash: «Flash used to create the RequestContext»,
+  #     #   clock: «Clock used to create the RequestContext»,
+  #     #   date: "2024-11-11",
+  #     # }
+  #    
+  #     result = object.doit(**hash)
+  #
+  # @param [Class] object an object whose method is to be called that requires some of the contents of this `RequestContext`.
+  # @param [Symbol] method_name name of the method that will be called.
+  # @param [Hash] request_params Query string parameters provided by Rack. Note that any parameter whose value is the empty string will be coerced to `nil`.
+  # @param [Brut::FrontEnd::Routing::Route] route the route that triggered the request.
+  # @param [Brut::FrontEnd::Form] form the form that was submitted with this request. May be `nil`.
+  # @return [Hash] can be splatted to keyword arguments and passed to the constructor of `klass`
+  #
+  # @raise [ArgumentError] if the method has any non-keyword arguments, or if any required keyword argument is
+  #                        not present in this `RequestContext`.
+  def as_method_args(object, method_name, request_params:,form:,route:nil)
+    args_for_method(method: object.method(method_name), request_params:, form:,route:)
   end
 
 private
 
-  def args_for_method(method:, request_params:, form: )
+  def args_for_method(method:, request_params:, form:,route:)
     args = {}
     method.parameters.each do |(type,name)|
 
@@ -62,10 +162,19 @@ private
 
       if self.key?(name)
         args[name] = self[name]
+      elsif name.to_s =~ /^http_[^_]+/
+        header_value = self[:env][name.to_s.upcase]
+        if header_value
+          args[name] = header_value
+        elsif type == :keyreq
+          args[name] = nil
+        end
       elsif !form.nil? && name == :form
         args[name] = form
+      elsif !route.nil? && name == :route
+        args[name] = route
       elsif !request_params.nil? && (request_params[name.to_s] || request_params[name.to_sym])
-        args[name] = request_params[name.to_s] || request_params[name.to_sym]
+        args[name] = RichString.new(request_params[name.to_s] || request_params[name.to_sym]).to_s_or_nil
       elsif type == :keyreq
         request_params_message = if request_params.nil?
                                    "no request params provied"

data/lib/brut/front_end/route_hook.rb

@@ -1,7 +1,49 @@
 module Brut::FrontEnd
+  # Base class for all route hooks. A route hook must implement either `before` or `after` and can be used via
+  # {Brut::Framework::App.before} or {Brut::Framework::App.after}.
+  #
+  # A route hook differs from Middleware in to ways:
+  #
+  # * A route hook has a rich structured return type that is more expressive that Rack's array, however less powerful.
+  # * A route hook can be injected with session and request information via {Brut::FrontEnd::RequestContext}.  This allows your route
+  # hooks to easily access information like the currently-logged-in user, session, flash, or query string parameters.
+  #
+  # Note that while a route hook can be used as both a before and an after, state will not be shared.
   class RouteHook
     include Brut::FrontEnd::HandlingResults
-    # Return this to continue the hook
+    include Brut::Framework::Errors
+
+    # Subclasses should implement this if they intend to be used as before hooks. The method parameters that the subclass uses will
+    # determine what information is avaiable.
+    #
+    # The return type determines what happens:
+    #
+    # * `URI` - the browser will be redirected to this URI
+    # * `Brut::FrontEnd::HttpStatus` - the request will be terminated with this status
+    # * `false` - the request is terminated with a 500
+    # * `true` or `nil` - the request will continue to the next hook or to the route handler. Use {#continue} if this is what you want to happen
+    #
+    # @return [URI|Brut::FrontEnd::HttpStatus|false|true|nil]
+    def before
+      abstract_method!
+    end
+
+    # Subclasses should implement this if they intend to be used as after hooks. The method parameters that the subclass uses will
+    # determine what information is avaiable.
+    #
+    # The return type determines what happens:
+    #
+    # * `URI` - the browser will be redirected to this URI
+    # * `Brut::FrontEnd::HttpStatus` - the request will be terminated with this status
+    # * `false` - the request is terminated with a 500
+    # * `true` or `nil` - the request will continue to the next hook or to the browser. Use {#continue} if this is what you want to happen
+    #
+    # @return [URI|Brut::FrontEnd::HttpStatus|false|true|nil]
+    def after
+      abstract_method!
+    end
+
+    # Return this to continue the hook. This is preferred over `true` or `nil` as it communicates the intent of what should happen
     def continue = true
   end
 

data/lib/brut/front_end/route_hooks/age_flash.rb

@@ -1,8 +1,9 @@
+# Ages the flash every time there is a request
 class Brut::FrontEnd::RouteHooks::AgeFlash < Brut::FrontEnd::RouteHook
-  def after(app_session:,request_context:)
+  def after(session:,request_context:)
     flash = request_context[:flash]
     flash.age!
-    app_session.flash = flash
+    session.flash = flash
     continue
   end
 end

data/lib/brut/front_end/route_hooks/csp_no_inline_scripts.rb

@@ -1,9 +1,17 @@
+# Sets content security policy headers that forbid inline scripts, but allow inline styles.
+# This is intended to be used in development to allow easier UI design work to happen in the browser
+# by the temporary use of inline styles.
+#
+# @see Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts
+# @see https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
 class Brut::FrontEnd::RouteHooks::CSPNoInlineScripts < Brut::FrontEnd::RouteHook
   def after(response:)
     response.headers["Content-Security-Policy"] = header_value
     continue
   end
 
+private
+
   def header_value
     [
       "default-src 'self'",

data/lib/brut/front_end/route_hooks/csp_no_inline_styles_or_scripts.rb

@@ -1,19 +1,16 @@
+# Sets content security policy headers that forbid inline scripts and inline styles.
+#
+# @see Brut::FrontEnd::RouteHooks::CSPNoInlineScripts
+# @see https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
 class Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts < Brut::FrontEnd::RouteHook
   def after(response:)
     response.headers["Content-Security-Policy"] = header_value
     continue
   end
 
-  def header_value
-    [
-      "default-src 'self'",
-      "script-src-elem 'self'",
-      "script-src-attr 'none'",
-      "style-src-elem 'self'",
-      "style-src-attr 'none'",
-    ].join("; ")
-  end
-
+  # Sets content security policy headers that only report the use inline scripts and inline styles, but do allow them.
+  # This is useful for existing apps where you want to migrate to a more secure policy, but cannot.
+  # @see Brut::FrontEnd::Handlers::CspReportingHandler
   class ReportOnly < Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts
     def after(response:,request:)
       csp_reporting_path   = uri(Brut::FrontEnd::Handlers::CspReportingHandler.routing,request:)
@@ -28,6 +25,17 @@ class Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts < Brut::FrontEnd::R
 
 private
 
+  def header_value
+    [
+      "default-src 'self'",
+      "script-src-elem 'self'",
+      "script-src-attr 'none'",
+      "style-src-elem 'self'",
+      "style-src-attr 'none'",
+    ].join("; ")
+  end
+
+
   def uri(path,request:)
     # Adapted from Sinatra's innards
     host = "http#{'s' if request.secure?}://"

data/lib/brut/front_end/route_hooks/locale_detection.rb

@@ -1,11 +1,16 @@
+# Detects the user's locale from the `Accept-Language` header and, if one of the locales has been set up in this app, configured
+# Ruby's `I18n` to use it.  This will also store the value in the session via {Brut::FrontEnd::Session#http_accept_language=}.
+#
+# @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language
 class Brut::FrontEnd::RouteHooks::LocaleDetection < Brut::FrontEnd::RouteHook
-  def before(app_session:,env:)
+  def before(session:,env:)
     http_accept_language = Brut::I18n::HTTPAcceptLanguage.from_header(env["HTTP_ACCEPT_LANGUAGE"])
-    if !app_session.http_accept_language.known?
-      app_session.http_accept_language = http_accept_language
+    Brut.container.instrumentation.add_attributes(http_accept_language:)
+    if !session.http_accept_language.known?
+      session.http_accept_language = http_accept_language
     end
     best_locale = nil
-    app_session.http_accept_language.weighted_locales.each do |weighted_locale|
+    session.http_accept_language.weighted_locales.each do |weighted_locale|
       if ::I18n.available_locales.include?(weighted_locale.locale.to_sym)
         best_locale = weighted_locale.locale.to_sym
         break
@@ -15,9 +20,10 @@ class Brut::FrontEnd::RouteHooks::LocaleDetection < Brut::FrontEnd::RouteHook
       end
     end
     if best_locale
+      Brut.container.instrumentation.add_attributes(best_locale:)
       ::I18n.locale = best_locale
     else
-      SemanticLogger["Brut"].warn("None of the user's locales are available: #{app_session.http_accept_language}")
+      Brut.container.instrumentation.add_attributes(best_locale: false)
     end
     continue
   end

data/lib/brut/front_end/route_hooks/setup_request_context.rb

@@ -1,10 +1,13 @@
+# Sets up the {Brut::FrontEnd::RequestContext} based on the contents of the session.
+# This is so that downstream handlers and hooks can have access to richer data than the hashes
+# and strings provided by Rack.
 class Brut::FrontEnd::RouteHooks::SetupRequestContext < Brut::FrontEnd::RouteHook
-  def before(app_session:,request:,env:)
-    flash = app_session.flash
-    app_session[:_flash] ||= flash
+  def before(session:,request:,env:)
+    flash = session.flash
+    session[:_flash] ||= flash
     Thread.current.thread_variable_set(
       :request_context,
-      Brut::FrontEnd::RequestContext.new(env:,session:app_session,flash:,xhr: request.xhr?,body: request.body)
+      Brut::FrontEnd::RequestContext.new(env:,session:session,flash:,xhr: request.xhr?,body: request.body)
     )
     continue
   end