brut 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fcc1f1288e34fb2c9a4c5a5e7fbc879ab9a4d56abbbaf1e8e3f3f5456cf38ad
-  data.tar.gz: c8a659fdb48e8a36f74d34daa60a1e96d0a799828372c28fa5888e2e135ab3ac
+  metadata.gz: b455ac9d87f61b5baa45cc6f4cc11c3b940b015aaf7792ba5ed8229dfd23d2fc
+  data.tar.gz: 5e6216b69db294da81ed31041a4b65a4a2b04de229e3d8695e5c9e1ad1625a84
 SHA512:
-  metadata.gz: f1297609ba764ce576b69d1d493466e005ff1e759464cb4e1025856311508f34dbb7abbb474a097de87a1c65ea4ddeab022c36221a41b0c763e88832512ba1d2
-  data.tar.gz: d30fde661e26d6f0df839b5609264eb71cb34339e5609c610f590d6c82ebd25890daf22cfaf140349b1dea8d0862e8ce1a4a319b2bad5e35a9ba9abe7f87ddc7
+  metadata.gz: 688aba783c6b979976ddf40417a6220a10295effef357aa9ebc0b1cd772fac759cae4ddaa2ce09c5bb4b1559d65ee04261d57a3c4253559b7f22a4c9dfffa42b
+  data.tar.gz: 67dbc5b31bf1c6e02f4f5b505d3f69e1eb084f862ccb78372377a3b49052e71711af4868eec6c5fd3bc68a4994bc10bbecb5ce42a260677c6a42c765f8a21e0a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.0.8)
+    brut (0.0.9)
       concurrent-ruby
       i18n
       irb

data/lib/brut/back_end/sidekiq/middlewares/server/flush_spans.rb

@@ -0,0 +1,17 @@
+# Designed to flush all OTel spans after each job is processed. You likely only
+# want this to be configured in development so you can see the results of individual
+# job executions.  Do not enable in production.
+#
+# When using, you want this to be inserted before OTel's sidekiq middleware:
+#
+#    config.server_middleware do |chain|
+#      chain.insert_before OpenTelemetry::Instrumentation::Sidekiq::Middlewares::Server::TracerMiddleware,
+#                          Brut::BackEnd::Sidekiq::Middlewares::Server::FlushSpans
+#    end
+class Brut::BackEnd::Sidekiq::Middlewares::Server::FlushSpans
+  def call(worker, job, queue)
+    yield
+  ensure
+    OpenTelemetry.tracer_provider.force_flush
+  end
+end

data/lib/brut/back_end/sidekiq/middlewares/server.rb

@@ -0,0 +1,3 @@
+class Brut::BackEnd::Sidekiq::Middlewares::Server
+  autoload(:FlushSpans, "brut/back_end/sidekiq/middlewares/server/flush_spans")
+end

data/lib/brut/back_end/sidekiq/middlewares.rb

@@ -0,0 +1,3 @@
+class Brut::BackEnd::Sidekiq::Middlewares
+  autoload(:Server, "brut/back_end/sidekiq/middlewares/server")
+end

data/lib/brut/back_end/sidekiq.rb

@@ -0,0 +1,3 @@
+class Brut::BackEnd::Sidekiq
+  autoload(:Middlewares, "brut/back_end/sidekiq/middlewares")
+end

data/lib/brut/cli/app.rb

@@ -208,7 +208,14 @@ class Brut::CLI::App
       return bootstrap_result
     end
     after_bootstrap
-    as_execution_result(command.execute)
+    if self.class.configure_only?
+      as_execution_result(command.execute)
+    else
+      result = Brut.container.instrumentation.span("CLI.#{$0}", class: self.class.name) do |span|
+        as_execution_result(command.execute)
+      end
+      result
+    end
   rescue Brut::CLI::Error => ex
     abort_execution(ex.message)
   end

data/lib/brut/cli/apps/db.rb

@@ -189,7 +189,9 @@ class Brut::CLI::Apps::DB < Brut::CLI::App
         formatted
       }
       Brut.container.sequel_db_handle.logger = logger
-      Sequel::Migrator.run(Brut.container.sequel_db_handle,migrations_dir)
+      Brut.container.instrumentation.span("migrations.run") do
+        Sequel::Migrator.run(Brut.container.sequel_db_handle,migrations_dir)
+      end
       out.puts "Migrations applied"
     end
   end

data/lib/brut/cli/apps/test.rb

@@ -40,21 +40,29 @@ class Brut::CLI::Apps::Test < Brut::CLI::App
     def execute
       Brut.container.sequel_db_handle.disconnect
       if options.rebuild?(default: rebuild_by_default?)
-        out.puts "Rebuilding test database schema"
-        system! "bin/db rebuild --env=test"
+        Brut.container.instrumentation.span("schema.rebuild.before") do
+          out.puts "Rebuilding test database schema"
+          system! "bin/db rebuild --env=test"
+        end
       end
-      if args.empty?
-        out.puts "Running all tests"
-        system! "#{rspec_command} #{Brut.container.app_specs_dir}/"
-      else
-        test_args = args.map { |_|
-          '"' + Shellwords.escape(_) + '"'
-        }.join(" ")
-        system! "#{rspec_command} #{test_args}"
+      Brut.container.instrumentation.span("tests.run") do |span|
+        if args.empty?
+          span.add_attributes(tests: :all)
+          out.puts "Running all tests"
+          system! "#{rspec_command} #{Brut.container.app_specs_dir}/"
+        else
+          span.add_attributes(tests: args.length)
+          test_args = args.map { |_|
+            '"' + Shellwords.escape(_) + '"'
+          }.join(" ")
+          system! "#{rspec_command} #{test_args}"
+        end
       end
       if options.rebuild_after?(default: rebuild_after_by_default?)
-        out.puts "Re-Rebuilding test database schema"
-        system! "bin/db rebuild --env=test"
+        Brut.container.instrumentation.span("schema.rebuild.after") do
+          out.puts "Re-Rebuilding test database schema"
+          system! "bin/db rebuild --env=test"
+        end
       end
       0
     end

data/lib/brut/cli.rb

@@ -26,7 +26,12 @@ module Brut
     # @param project_root [Pathname] the path to the root of your project. This is needed before the Brut framework is initialized so
     # it must be specified explicitly.
     def self.app(app_klass, project_root:)
-      Brut::CLI::AppRunner.new(app_klass:,project_root:).run!
+      Brut::CLI::AppRunner.new(app_klass:,project_root:).run!.tap {
+        otel_configured = OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+        if otel_configured
+          OpenTelemetry.tracer_provider.shutdown
+        end
+      }
     end
     autoload(:App, "brut/cli/app")
     autoload(:Command, "brut/cli/command")

data/lib/brut/framework/config.rb

@@ -424,6 +424,15 @@ class Brut::Framework::Config
         allow_nil: true,
       )
 
+      Brut.container.store(
+        "fallback_host",
+        URI,
+        "Hostname to use in situations where the request is not available",
+        nil,
+        allow_app_override: true,
+        allow_nil: true
+      )
+
       c.store(
         "local_hostname",
         String,

data/lib/brut/framework/errors/missing_configuration.rb

@@ -0,0 +1,11 @@
+# Raised when Brut configuration is missing an expected value.  This is mostly raised when values that must be set per app
+# have not been set.
+class Brut::Framework::Errors::MissingConfiguration < Brut::Framework::Error
+  # Create the exception
+  #
+  # @param [String|Symbol] config_name the name of the missing configuration parameter
+  # @param [String] context Any additional context to understand the error
+  def initialize(config_name, context)
+    super("Configuration parameter '#{config_name}' did not have a value, but was expected to. #{context}")
+  end
+end

data/lib/brut/framework/errors.rb

@@ -7,6 +7,7 @@ module Brut
       autoload(:NotImplemented,"brut/framework/errors/not_implemented")
       autoload(:NotFound,"brut/framework/errors/not_found")
       autoload(:MissingParameter,"brut/framework/errors/missing_parameter")
+      autoload(:MissingConfiguration,"brut/framework/errors/missing_configuration")
       autoload(:AbstractMethod,"brut/framework/errors/abstract_method")
       autoload(:NoClassForPath,"brut/framework/errors/no_class_for_path")
       # Raises {Brut::Framework::Errors::Bug}

data/lib/brut/framework/mcp.rb

@@ -33,7 +33,7 @@ class Brut::Framework::MCP
   #
   # * Create the instance and *do not* call `boot!`.  This is what you'd do if you can't or don't want to connect to external services
   # like the database.  For example, when Brut builds assets, it does not call `boot!`.
-  # * Create the intance and immediately call `boot!`.  This is what happens most of the time, in particular when the app is started
+  # * Create the instance and immediately call `boot!`.  This is what happens most of the time, in particular when the app is started
   # up by Puma to start serving requests.
   #
   # What you should avoid doing is creating an instance of this class and performing logic before later calling `boot!`.
@@ -70,6 +70,7 @@ class Brut::Framework::MCP
       end
     end
     Sequel::Database.extension :pg_array
+    Sequel::Database.extension :pg_json
 
     sequel_db = Brut.container.sequel_db_handle
 
@@ -100,6 +101,14 @@ class Brut::Framework::MCP
           )
         )
       end
+
+      if defined?(OpenTelemetry::Instrumentation::Sidekiq)
+        c.use 'OpenTelemetry::Instrumentation::Sidekiq', {
+          span_naming: :job_class,
+        }
+      else
+        SemanticLogger[self.class].info "OpenTelemetry::Instrumentation::Sidekiq is not loaded, so Sidekiq traces will not be captured"
+      end
     end
 
     Brut.container.store(

data/lib/brut/front_end/handling_results.rb

@@ -15,7 +15,7 @@ module Brut::FrontEnd::HandlingResults
     if !klass.kind_of?(Class)
       raise ArgumentError,"redirect_to should be given a Class, not a #{klass.class}"
     end
-    Brut.container.routing.uri(klass,with_method: :get,**query_string_params)
+    Brut.container.routing.path(klass,with_method: :get,**query_string_params)
   end
 
   # Return this to return an HTTP status code from a number or string containing the code.

data/lib/brut/front_end/request_context.rb

@@ -15,13 +15,15 @@ class Brut::FrontEnd::RequestContext
   # @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:)
+  # @param [URI] host URI the `request.host` and `request.scheme`, and `request.port` as provided by Rack
+  def initialize(env:,session:,flash:,xhr:,body:,host:)
     @hash = {
       env:,
       session:,
       flash:,
       xhr:,
       body:,
+      host:,
       csrf_token: Rack::Protection::AuthenticityToken.token(env["rack.session"]),
       clock: Clock.new(session.timezone),
     }

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

@@ -5,9 +5,10 @@ class Brut::FrontEnd::RouteHooks::SetupRequestContext < Brut::FrontEnd::RouteHoo
   def before(session:,request:,env:)
     flash = session.flash
     session[:_flash] ||= flash
+    host_uri = URI.parse("#{request.scheme}://#{request.host}:#{request.port}")
     Thread.current.thread_variable_set(
       :request_context,
-      Brut::FrontEnd::RequestContext.new(env:,session:session,flash:,xhr: request.xhr?,body: request.body)
+      Brut::FrontEnd::RequestContext.new(env:,session:session,flash:,xhr: request.xhr?,body: request.body, host: host_uri)
     )
     continue
   end

data/lib/brut/front_end/routing.rb

@@ -116,7 +116,25 @@ class Brut::FrontEnd::Routing
     route
   end
 
-  def uri(handler_class, with_method: :any, **rest)
+  def path(handler_class, with_method: :any, **rest)
+    route = self.route_for(handler_class, with_method:)
+    route.path(**rest)
+  end
+
+  def url(handler_class, with_method: :any, **rest)
+    route = self.route_for(handler_class, with_method:)
+    route.url(**rest)
+  end
+
+  def inspect
+    @routes.map { |route|
+      "#{route.http_method}:#{route.path_template} - #{route.handler_class.name}"
+    }.join("\n")
+  end
+
+private
+
+  def route_for(handler_class, with_method: :any)
     route = self.route(handler_class)
     route_allowed_for_method = if with_method == :any
                                  true
@@ -128,14 +146,9 @@ class Brut::FrontEnd::Routing
     if !route_allowed_for_method
       raise ArgumentError,"The route for '#{handler_class}' (#{route.path}) is not supported by HTTP method '#{with_method}'"
     end
-    route.path(**rest)
+    route
   end
 
-  def inspect
-    @routes.map { |route|
-      "#{route.http_method}:#{route.path_template} - #{route.handler_class.name}"
-    }.join("\n")
-  end
 
   def add_routing_method(route)
     handler_class = route.handler_class
@@ -143,7 +156,10 @@ class Brut::FrontEnd::Routing
     [ handler_class, form_class ].compact.each do |klass|
       klass.class_eval do
         def self.routing(**args)
-          Brut.container.routing.uri(self,**args)
+          Brut.container.routing.path(self,**args)
+        end
+        def self.full_routing(**args)
+          Brut.container.routing.url(self,**args)
         end
       end
     end
@@ -205,11 +221,31 @@ class Brut::FrontEnd::Routing
       uri
     end
 
+    def url(**query_string_params)
+      request_context = Thread.current.thread_variable_get(:request_context)
+      path = self.path(**query_string_params)
+      host = if request_context
+               request_context[:host]
+             end
+      host ||= Brut.container.fallback_host
+      host.merge(path)
+    rescue ArgumentError => ex
+      request_context_note = if request_context
+                               "the RequestContext did not contain request.host, which is unusual"
+                             else
+                               "the RequestContext was not available (likely due to calling `full_routing` outside an HTTP request)"
+                             end
+      raise Brut::Framework::Errors::MissingConfiguration(
+        :fallback_host,
+        "Attempting to get the full URL for route #{self.path_template}, #{request_context_note}, and Brut.container.fallback_host was not set.  You must set this value if you expect to generate complete URLs outside of an HTTP request")
+    end
+
     def ==(other)
       self.method == other.method && self.path == other.path
     end
 
   private
+
     def locate_handler_class(suffix,preposition, on_missing: :raise)
       if @path_template == "/"
         return Module.const_get("HomePage") # XXX Needs error handling

data/lib/brut/spec_support/clock_support.rb

@@ -2,10 +2,23 @@
 module Brut::SpecSupport::ClockSupport
   # Return a real lock in UTC
   def real_clock = Clock.new(TZInfo::Timezone.get("UTC"))
-  # Return a clock whose value for now is `now`
+
+  # Return a clock whose value for now is `now`, in UTC
   #
   # @param [String] now a string containing the value you want for {Clock#now} to return.
   def clock_at(now:)
-    Clock.new(TZInfo::Timezone.get("UTC"), now: Time.parse(now))
+    self.clock_in_timezone_at(timezone_name: "UTC", now: now)
+  end
+
+  # Return a clock whose value for now is `now` in the given timezone
+  #
+  # @param [String] timezone_name a string that is the name of the timezone to use.
+  # @param [String] now a string containing the value you want for {Clock#now} to return.
+  def clock_in_timezone_at(timezone_name:, now:)
+    time = Time.parse(now)
+    timezone = TZInfo::Timezone.get(timezone_name)
+    same_time_in_timezone = timezone.local_time(time.year, time.month, time.day, time.hour, time.min, time.sec)
+
+    Clock.new(TZInfo::Timezone.get(timezone_name), now: same_time_in_timezone)
   end
 end

data/lib/brut/spec_support/component_support.rb

@@ -78,7 +78,7 @@ module Brut::SpecSupport::ComponentSupport
 
   # @!visibility private
   def routing_for(klass,**args)
-    Brut.container.routing.uri(klass,**args)
+    Brut.container.routing.path(klass,**args)
   end
 
   # Escape HTML using the same code Brut uses for rendering templates.

data/lib/brut/spec_support/general_support.rb

@@ -5,6 +5,16 @@ module Brut::SpecSupport::GeneralSupport
   end
 
   module ClassMethods
+    def implementation_is_needed(check_again_at:)
+      check_again_at = if check_again_at.kind_of?(Time)
+                         check_again_at
+                       else
+                         check_again_at = Date.parse(check_again_at).to_time
+                       end
+      it "has no tests for now, but they are needed eventually" do
+        expect(Time.now < check_again_at).to eq(true),"It's after #{check_again_at}. Implementation is needed"
+      end
+    end
     # To pass bin/test audit with a class whose implementation is trivial, call this inside the RSpec `describe` block. This is better
     # than an empty test as it makes it more explicit that you believe the implementation is trivial enough to not require a test. You
     # can also set an expiration for this thinking.
@@ -23,7 +33,7 @@ module Brut::SpecSupport::GeneralSupport
         if check_again_at.nil?
           expect(true).to eq(true)
         else
-          expect(Time.now < check_again_at).to eq(true),"I'ts after #{check_again_at}. Check that the implementation of the class under test is still trivial. If it is, update or remove check_again_at:"
+          expect(Time.now < check_again_at).to eq(true),"It's after #{check_again_at}. Check that the implementation of the class under test is still trivial. If it is, update or remove check_again_at:"
         end
       end
     end

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

@@ -1,10 +1,10 @@
 RSpec::Matchers.define :be_routing_for do |klass,**args|
   match do |uri|
-    uri == Brut.container.routing.uri(klass,**args)
+    uri == Brut.container.routing.path(klass,**args)
   end
 
   failure_message do |uri|
-    expected = Brut.container.routing.uri(klass,**args)
+    expected = Brut.container.routing.path(klass,**args)
     "Expected route for #{klass}: #{expected}, but got #{uri}"
   end
 

data/lib/brut/spec_support/rspec_setup.rb

@@ -103,6 +103,7 @@ class Brut::SpecSupport::RSpecSetup
           flash: empty_flash,
           body: nil,
           xhr: false,
+          host: URI("https://example.com")
         )
         Thread.current.thread_variable_set(:request_context, request_context)
         example.example_group.let(:request_context) { request_context }

data/lib/brut/version.rb

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

data/lib/brut.rb

@@ -50,6 +50,7 @@ module Brut
   # will be in the back end, Brut is far less prescriptive about how to manage that than it is the front end.
   module BackEnd
     autoload(:Validators, "brut/back_end/validator")
+    autoload(:Sidekiq, "brut/back_end/sidekiq")
     # Do not put SeedData here - it must be loaded only when needed
   end
   # I18n is where internationalization and localization support lives.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: brut
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - David Bryant Copeland
 bindir: exe
 cert_chain: []
-date: 2025-03-15 00:00:00.000000000 Z
+date: 2025-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: irb
@@ -455,6 +455,10 @@ files:
 - dx/stop
 - lib/brut.rb
 - lib/brut/back_end/seed_data.rb
+- lib/brut/back_end/sidekiq.rb
+- lib/brut/back_end/sidekiq/middlewares.rb
+- lib/brut/back_end/sidekiq/middlewares/server.rb
+- lib/brut/back_end/sidekiq/middlewares/server/flush_spans.rb
 - lib/brut/back_end/validator.rb
 - lib/brut/back_end/validators/form_validator.rb
 - lib/brut/cli.rb
@@ -478,6 +482,7 @@ files:
 - lib/brut/framework/errors.rb
 - lib/brut/framework/errors/abstract_method.rb
 - lib/brut/framework/errors/bug.rb
+- lib/brut/framework/errors/missing_configuration.rb
 - lib/brut/framework/errors/missing_parameter.rb
 - lib/brut/framework/errors/no_class_for_path.rb
 - lib/brut/framework/errors/not_found.rb