brut 0.0.20 → 0.0.21

data/lib/brut/front_end/page.rb

@@ -1,46 +1,44 @@
-# 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.
+# A Page backs a web page, which handles rendering everything in a browser window when a URL is requested.
+# Technically, a page is identical to a {Brut::FrontEnd::Component}, except that a page has a layout.
+# A {Brut::FrontEnd::Layout} is common HTML that surrounds your page's HTML.
+# Your page is a Phlex component, but instead of implementing `view_template`, you
+# implement {#page_template} to ensure the layout is used.
 #
-# 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.
+# To create a page, after defining a route, subclass this class (or, more likely, your app's `AppPage`) 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 page object.
 #
-# 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.
+# Consult Brut's documentation on keyword injection to know what values you may use and how values are located.
 #
 # @see Brut::FrontEnd::Component
+# @see Brut::FrontEnd::Layout
 class Brut::FrontEnd::Page < Brut::FrontEnd::Component
   include Brut::FrontEnd::HandlingResults
 
-  # 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.
+  # Returns the name of the layout for this page.  This string is used to find a class named
+  # `«camelized-layout»Layout` in your app.  The default value is "default", meaning that the class
+  # `DefaultLayout` will be used.
   #
-  # Note that the layout can be dynamic. It is requested when {#render} is called, so you can override this
+  # Note that the layout can be dynamic. It is requested when {#page_template} is called, so you can override this
   # method and use any ivar set in your constructor to change what layout is used.
   #
+  # If your page does not need a layout, you have two options:
+  #
+  # * Create your own blank layout named, e.g. `BlankLayout` and have this method return `"blank"`.
+  # * Implement `view_template` instead of `page_template`, thus overriding this class' implementation that uses
+  #   layouts.
+  #
   # @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
+  # Called after the page is created, but before {#page_template} 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.
+  # @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 no HTML is generated. If you return a {Brut::FrontEnd::HttpStatus} (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#http_status}), HTML generation is skipped and that status is returned with no content.  If anything else is returned, HTML is generated normal.
   def before_render = nil
 
-  def with_layout(&block)
-    layout_class = Module.const_get(
-      layout_class = RichString.new([
-        self.layout,
-        "layout"
-      ].join("_")).camelize
-    )
-    render layout_class.new(page_name:,&block)
-  end
-
-
+  # Core method of this class. Do not override. This handles the use of {#before_render} and is what Brut
+  # calls to possibly render the page.
   def handle!
     case before_render
     in URI => uri
@@ -52,6 +50,15 @@ class Brut::FrontEnd::Page < Brut::FrontEnd::Component
     end
   end
 
+  # Override this method to produce your page's HTML. You are intended to call Phlex
+  # methods here. Anything you can do inside the Phlex-standard `view_template` method, you can 
+  # do here. The only difference is that this will all be rendered in the context of your configured
+  # {#layout}.
+  def page_template = abstract_method!
+
+  # Phlex's API to produce markup. Do not override this or you will lose your layout.
+  # This implementation locates the configured layout, renders it, and renders {#page_template}
+  # inside.
   def view_template
     with_layout do
       page_template
@@ -68,6 +75,24 @@ class Brut::FrontEnd::Page < Brut::FrontEnd::Component
   # @!visibility private
   def component_name = raise Brut::Framework::Errors::Bug,"#{self.class} is not a component"
 
+private
+
+  # Locates the layout class and uses it to render itself, along
+  # with the block given.
+  #
+  # @!visibility private
+  def with_layout(&block)
+    layout_class = Module.const_get(
+      layout_class = RichString.new([
+        self.layout,
+        "layout"
+      ].join("_")).camelize
+    )
+    render layout_class.new(page_name:,&block)
+  end
+
+
+
 end
 
 # Holds pages included with the Brut framework

data/lib/brut/front_end/routing.rb

@@ -218,7 +218,11 @@ private
         joined_path = joined_path + "#" + URI.encode_uri_component(anchor)
       end
       uri = URI(joined_path)
-      uri.query = URI.encode_www_form(query_string_params)
+      query_string = URI.encode_www_form(query_string_params)
+      if query_string.to_s.strip != ""
+        uri.query = query_string
+      end
+
       uri.extend(Phlex::SGML::SafeObject)
     end
 

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

@@ -23,12 +23,12 @@ module Brut::I18n::BaseMethods
   # 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
+  #        This value's behavior is designed to 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.
+  #        that 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
@@ -39,6 +39,16 @@ module Brut::I18n::BaseMethods
   #               Note that if the page– or component–specific key is not found, this will check
   #               `general.«page: value»`.
   # @option interpolated_values [Numeric] count Special interpolation to control pluralization.
+  # @yield Nothing is yielded if a block is given, however the value returned is used for the `%{block}`
+  #        interpolation value.
+  # @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
@@ -89,7 +99,7 @@ module Brut::I18n::BaseMethods
   #   t(page: :new_widget) # => Create new Widget
   #   # in your code for WidgetsPage
   #   t(page: :new_widget) # => Create New
-  #   # in your code for SomeOtherEPage
+  #   # in your code for SomeOtherPage
   #   t(page: :new_widget) # => Make a New Widget
   #
   # @example Using page: with an array
@@ -106,6 +116,30 @@ module Brut::I18n::BaseMethods
   #   }
   #   # in your code for HomePage
   #   t(page: [ :captions, :new ]) # => New Widgets
+  #
+  # @example Using a block with Phlex
+  #   # 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=:look_in_rest,**rest,&block)
     if key == :look_in_rest
 

data/lib/brut/i18n/for_back_end.rb

@@ -1,3 +1,6 @@
+# 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

data/lib/brut/i18n/for_cli.rb

@@ -1,3 +1,6 @@
+# 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

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,11 +43,32 @@ 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.

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

data/lib/brut/spec_support/component_support.rb

@@ -10,9 +10,17 @@ module Brut::SpecSupport::ComponentSupport
   include Brut::SpecSupport::ClockSupport
   include Brut::I18n::BaseMethods
 
-  # Render a component into its text representation.  This mimics what happens when a component is used
-  # inside a template.  You typically don't want this, but should use {#render_and_parse}, since that will
-  # parse the HTML.
+  # Render a component or page into its text representation.  This mimics what happens when Brut renders
+  # the page or component.  Note that pages don't always return Strings, for example if `before_render`
+  # returns a redirect.
+  #
+  # When testing a component, call {#render_and_parse} instead of this. When testing a page that will
+  # always render HTML, again call {#render_and_parse}.
+  #
+  # When using this, there are some matchers that can help assert what the page has done:
+  #
+  # * `have_redirected_to` to check that the page redirected elsewhere, instead of rendering.
+  # * `have_returned_http_status` to check that the page returned an HTTP status instead of rendering.
   def render(component,&block)
     if component.kind_of?(Brut::FrontEnd::Page)
       if !block.nil?
@@ -30,7 +38,13 @@ module Brut::SpecSupport::ComponentSupport
     end
   end
 
-  # Render a component and parse it into a Nokogiri Node for examination.
+  # Render a component or page and parse it into a Nokogiri Node for examination.  There are several matchers
+  # you can use with the return value of this method:
+  #
+  # * `have_html_attribute` to check if a node has a value for an HTML attribute.
+  # * `have_i18n_string` to check if the text of a node is exactly an i18n string you have set up.
+  # * `have_link_to` to check that a node contains a link to a page or page routing
+  #
   #
   # @example
   #

data/lib/brut/spec_support/e2e_support.rb

@@ -1,4 +1,4 @@
 # Convienience methods for writing E2E tests
 module Brut::SpecSupport::E2eSupport
-  include Brut::I18n::BaseMethods
+  include Brut::I18n::ForBackEnd
 end

data/lib/brut/spec_support/general_support.rb

@@ -5,6 +5,9 @@ module Brut::SpecSupport::GeneralSupport
   end
 
   module ClassMethods
+    # Used to indicate that a test does need to be written, but that
+    # its implementation can wait until a given date before causing
+    # `bin/ci` to fail the test suite.
     def implementation_is_needed(check_again_at:)
       check_again_at = if check_again_at.kind_of?(Time)
                          check_again_at

data/lib/brut/spec_support/handler_support.rb

@@ -2,7 +2,12 @@ require_relative "flash_support"
 require_relative "clock_support"
 require_relative "session_support"
 
-# Convienience methods for testing handlers.
+# Convienience methods for testing handlers.  When testing handlers, the following matchers may be useful:
+#
+#
+# * `have_redirected_to` to check that the handler redirected to a give URI
+# * `have_rendered` to check that the handler rendered a specific page
+# * `have_returned_http_status` to check that the handler returned an HTTP status
 module Brut::SpecSupport::HandlerSupport
   include Brut::SpecSupport::FlashSupport
   include Brut::SpecSupport::ClockSupport

data/lib/brut/spec_support/matcher.rb

@@ -10,4 +10,5 @@ require_relative "matchers/have_i18n_string"
 require_relative "matchers/have_redirected_to"
 require_relative "matchers/have_rendered"
 require_relative "matchers/have_returned_http_status"
+require_relative "matchers/have_returned_rack_response"
 require_relative "matchers/have_link_to"

data/lib/brut/spec_support/matchers/be_page_for.rb

@@ -1,3 +1,4 @@
+# E2E
 RSpec::Matchers.define :be_page_for do |klass|
   match do |page|
     meta = page.locator("meta[name='class']")

data/lib/brut/spec_support/matchers/have_html_attribute.rb

@@ -1,3 +1,4 @@
+# Component/Page
 RSpec::Matchers.define :have_html_attribute do |attribute|
   if attribute.kind_of?(Hash)
     if attribute.keys.length != 1

data/lib/brut/spec_support/matchers/have_i18n_string.rb

@@ -1,9 +1,6 @@
+# Component/Page
 RSpec::Matchers.define :have_i18n_string do |key,**args|
-  include Brut::I18n::ForHTML
-
-  # XXX: Figure out how to not have to do this
-  def safe(x) = x
-  def capture(&block) = block.()
+  include Brut::I18n::ForBackEnd
 
   match do |nokogiri_node|
 

data/lib/brut/spec_support/matchers/have_link_to.rb

@@ -1,3 +1,4 @@
+# Component/Page
 RSpec::Matchers.define :have_link_to do |page_klass,**args|
   match do |node|
     node.css("a[href='#{page_klass.routing(**args)}']").any?

data/lib/brut/spec_support/matchers/have_redirected_to.rb

@@ -1,3 +1,4 @@
+# Page
 RSpec::Matchers.define :have_redirected_to do |page_or_uri,**page_params|
   match do |result|
     if page_or_uri.kind_of?(URI)

data/lib/brut/spec_support/matchers/have_rendered.rb

@@ -1,3 +1,4 @@
+# Handler
 RSpec::Matchers.define :have_rendered do |component_or_page|
   match do |result|
     result.class.ancestors.include?(component_or_page)

data/lib/brut/spec_support/matchers/have_returned_rack_response.rb

@@ -0,0 +1,44 @@
+# Handler
+RSpec::Matchers.define :have_returned_rack_response do |http_status: :any, headers: :any, body: :any|
+  match do |result|
+    case result
+    in [ response_status, response_headers, response_body ]
+      http_status_match = http_status == :any || response_status == http_status
+      headers_match     = headers == :any || response_headers == headers
+      body_match        = body == :any || response_body == body
+
+      http_status_match && headers_match && body_match
+    else
+      false
+    end
+  end
+
+  failure_message do |result|
+    case result
+    in [ response_status, response_headers, response_body ]
+      http_status_match = http_status == :any || response_status == http_status
+      headers_match     = headers == :any || response_headers == headers
+      body_match        = body == :any || response_body == body
+      errors = [
+        http_status_match ? nil : "HTTP status #{response_status} did not match #{http_status}",
+        headers_match     ? nil : "Headers #{response_headers} did not match #{headers}",
+        body_match        ? nil : "Body #{response_body} did not match #{body}",
+      ].compact.join(", ")
+    else
+      if result.kind_of?(Array)
+        "Response was a #{result.class} of length #{result.length}, which could not be interpreted as a Rack response."
+      else
+        "Response was a #{result.class}, which could not be interpreted as a Rack response."
+      end
+    end
+  end
+  failure_message_when_negated do |result|
+    case result
+    in [ response_status, response_headers, response_body ]
+      "Response was a Rack response and/or array of size 3"
+    else
+      "failure_message_when_negated encounterd a code-path for a non-Rack response, which should not have happened when have_returned_rack_response was negated"
+    end
+  end
+
+end

data/lib/brut/spec_support.rb

@@ -1,7 +1,7 @@
 module Brut
   # Spec Support holds various matchers and helpers useful when writing tests with RSpec.
   # Note that this module and it's contents aren't loaded by default when you `require "brut"`.
-  # Your app's `spec_helper.rb` should require these properly.
+  # Your app's `spec_helper.rb` should require these explicitly.
   module SpecSupport
   end
 end

data/lib/brut/version.rb

@@ -1,4 +1,4 @@
 module Brut
   # @!visibility private
-  VERSION = "0.0.20"
+  VERSION = "0.0.21"
 end

data/lib/brut.rb

@@ -1,10 +1,11 @@
 require_relative "brut/framework"
 
-# Brut is a way to make web apps with Ruby. It focuses on web standards, object-orientation, and other fundamentals. Brut seeks to
-# minimize abstractions where possible.
+# Brut is a way to make web apps with Ruby. It focuses on web standards, object-orientation, and other
+# fundamentals. Brut seeks to minimize abstractions where possible.
 #
-# Brut encourages the use of the browser's technology and encourages you to build a web app based on good practices that are set up by
-# default.  Brut may not look easy, but it aims to be simple.  It attempts to minimize dependencies and complexity, while leveraging
+# Brut encourages the use of the browser's technology and encourages you to build a web app based
+# on good practices that are set up by default.  Brut may not look easy, but it aims to be simple.
+# It attempts to minimize dependencies and complexity, while leveraging
 # common tested Ruby libraries related to web development.
 #
 # Have fun!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brut
 version: !ruby/object:Gem::Version
-  version: 0.0.20
+  version: 0.0.21
 platform: ruby
 authors:
 - David Bryant Copeland
@@ -406,14 +406,6 @@ files:
 - bin/rake
 - bin/setup
 - brut.gemspec
-- doc-src/architecture.md
-- doc-src/assets.md
-- doc-src/forms.md
-- doc-src/handlers.md
-- doc-src/javascript.md
-- doc-src/keyword-injection.md
-- doc-src/pages.md
-- doc-src/route-hooks.md
 - docker-compose.dx.yml
 - docs-todo.md
 - dx/build
@@ -553,6 +545,7 @@ files:
 - lib/brut/spec_support/matchers/have_redirected_to.rb
 - lib/brut/spec_support/matchers/have_rendered.rb
 - lib/brut/spec_support/matchers/have_returned_http_status.rb
+- lib/brut/spec_support/matchers/have_returned_rack_response.rb
 - lib/brut/spec_support/rspec_setup.rb
 - lib/brut/spec_support/session_support.rb
 - lib/brut/version.rb