brut 0.0.1 → 0.0.2

data/lib/sequel/plugins/external_id.rb

@@ -1,19 +1,51 @@
 module Sequel
   module Plugins
+    # Configures models with an external id that can be safely shared publicly and safely rotated. The external
+    # id is random, however it is prefixed with configurable strings that can indicate what type of model it represents.
+    # This disambiguates ids when shared pubnlically or in internal tooling.
+    #
+    # This extension accepts a configuration option `global_prefix:` that is a string prepended to all external IDs.  This ensures
+    # that your app's IDs clearly come from your app and not some other app that may be using external ids.
+    #
+    # To use external ids you must then call {ClassMethods#has_external_id} in your model. This method accepts a string which is
+    # appended to the global prefix.  This is then *prepended* to a unique identifier.  The per-model external id prefix should
+    # indicate the type of the model.  Note that it's not intended to be used programmatically—it's only for humans to quickly see
+    # what type of thing an identifier represents.
+    #
+    # When {ClassMethods#has_external_id} is called on your model, the column `external_id` will be set on save if it has no value.
+    #
+    # @example
+    #    class DB::Widget < AppDataModel
+    #      has_external_id "wg"
+    #    end
+    #
+    #    Sequel::Model.plugin :external_id, global_prefix: "my"
+    #
+    #    widget = DB::Widget.new(name: "flux capacitor")
+    #    widget.external_id # => mywg_43792834f9c3a7
     module ExternalId
+      # @!visibility private
       def self.apply(model,*args,&block)
         @global_prefix = (args.first || {})[:global_prefix]
       end
+      def self.global_prefix = @global_prefix
 
       module ClassMethods
-        attr_reader :global_prefix
+        # @!visibility private
+        def global_prefix = Sequel::Plugins::ExternalId.global_prefix
+        # Called inside a model's body to indicate that this model has an `external_id` that this plugin should manage and what
+        # prefix should be used.  Calling this will also alter {InstanceMethods#to_s} to include this id in the string representation.
+        #
+        # @param prefix [String] a short string identfying the type of this model. It will be prepended to your external_id.
         def has_external_id(prefix)
           global_prefix = find_global_prefix
           @external_id_prefix = RichString.new("#{global_prefix}#{prefix}").to_s_or_nil
         end
 
+        # @!visibility private
         def external_id_prefix = @external_id_prefix
 
+        # @!visibility private
         def find_global_prefix(receiver=self)
           if receiver.respond_to?(:global_prefix)
             if receiver.global_prefix.nil?
@@ -30,6 +62,7 @@ module Sequel
       end
 
       module InstanceMethods
+        # @!visibility private
         def before_save
           if self.class.external_id_prefix
             if self.external_id.nil?
@@ -39,6 +72,11 @@ module Sequel
           end
           super
         end
+        # Includes the external id in the super class' representation. This means you can include
+        # models in Log messages without having to explicitly fetch the id.
+        def to_s
+          super.to_s + "[external_id:#{self.external_id}]"
+        end
       end
     end
   end

data/lib/sequel/plugins/find_bang.rb

@@ -1,11 +1,14 @@
 module Sequel
   module Plugins
+    # Adds {ClassMethods#find!} to all models, which behaves as it does in Rails.
     module FindBang
       module ClassMethods
+        # Calls `first!`, but provides a more helpful error message when no records are found.
+        # @raise [Brut::Framework::Errors::NotFound]
         def find!(**args)
           self.first!(**args)
         rescue Sequel::NoMatchingRow => ex
-          raise Sequel::NoMatchingRow.new(ex.message + "; #{args.inspect}")
+          raise Brut::Framework::Errors::NotFound.new(resource_name: self.name,search_terms: args.inspect,context: ex.message)
         end
       end
     end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: brut
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - David Bryant Copeland
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-14 00:00:00.000000000 Z
+date: 2025-02-18 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faker
   requirement: !ruby/object:Gem::Requirement
@@ -262,6 +289,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -318,6 +373,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdiscount
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: NOT YET RELEASED - An opinionated web framework build on web standards
 email:
 - davec@thirdtank.com
@@ -337,7 +434,16 @@ 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
 - dx/docker-compose.env
 - dx/dx.sh.lib
@@ -348,8 +454,6 @@ files:
 - dx/start
 - dx/stop
 - lib/brut.rb
-- lib/brut/back_end/action.rb
-- lib/brut/back_end/result.rb
 - lib/brut/back_end/seed_data.rb
 - lib/brut/back_end/validator.rb
 - lib/brut/back_end/validators/form_validator.rb
@@ -374,38 +478,57 @@ files:
 - lib/brut/framework/errors.rb
 - lib/brut/framework/errors/abstract_method.rb
 - lib/brut/framework/errors/bug.rb
+- lib/brut/framework/errors/missing_parameter.rb
+- lib/brut/framework/errors/no_class_for_path.rb
 - lib/brut/framework/errors/not_found.rb
+- lib/brut/framework/errors/not_implemented.rb
 - lib/brut/framework/fussy_type_enforcement.rb
 - lib/brut/framework/mcp.rb
 - lib/brut/framework/project_environment.rb
 - lib/brut/front_end/asset_metadata.rb
 - lib/brut/front_end/component.rb
+- lib/brut/front_end/components/constraint_violations.rb
 - lib/brut/front_end/components/form_tag.rb
 - lib/brut/front_end/components/i18n_translations.rb
 - lib/brut/front_end/components/input.rb
 - lib/brut/front_end/components/inputs/csrf_token.rb
+- lib/brut/front_end/components/inputs/radio_button.rb
 - lib/brut/front_end/components/inputs/select.rb
 - lib/brut/front_end/components/inputs/text_field.rb
 - lib/brut/front_end/components/inputs/textarea.rb
 - lib/brut/front_end/components/locale_detection.rb
 - lib/brut/front_end/components/page_identifier.rb
-- lib/brut/front_end/components/timestamp.rb
+- lib/brut/front_end/components/time.rb
+- lib/brut/front_end/components/traceparent.rb
 - lib/brut/front_end/download.rb
 - lib/brut/front_end/flash.rb
 - lib/brut/front_end/form.rb
 - lib/brut/front_end/forms/constraint_violation.rb
 - lib/brut/front_end/forms/input.rb
+- lib/brut/front_end/forms/input_declarations.rb
 - lib/brut/front_end/forms/input_definition.rb
+- lib/brut/front_end/forms/radio_button_group_input.rb
+- lib/brut/front_end/forms/radio_button_group_input_definition.rb
+- lib/brut/front_end/forms/select_input.rb
+- lib/brut/front_end/forms/select_input_definition.rb
 - lib/brut/front_end/forms/validity_state.rb
 - lib/brut/front_end/handler.rb
 - lib/brut/front_end/handlers/csp_reporting_handler.rb
+- lib/brut/front_end/handlers/instrumentation_handler.rb
 - lib/brut/front_end/handlers/locale_detection_handler.rb
+- lib/brut/front_end/handlers/missing_handler.rb
 - lib/brut/front_end/handling_results.rb
 - lib/brut/front_end/http_method.rb
 - lib/brut/front_end/http_status.rb
+- lib/brut/front_end/layouts/_internal.html.erb
 - lib/brut/front_end/middleware.rb
+- lib/brut/front_end/middlewares/annotate_brut_owned_paths.rb
+- lib/brut/front_end/middlewares/favicon.rb
+- lib/brut/front_end/middlewares/open_telemetry_span.rb
 - lib/brut/front_end/middlewares/reload_app.rb
 - lib/brut/front_end/page.rb
+- lib/brut/front_end/pages/_missing_page.html.erb
+- lib/brut/front_end/pages/missing_page.rb
 - lib/brut/front_end/request_context.rb
 - lib/brut/front_end/route_hook.rb
 - lib/brut/front_end/route_hooks/age_flash.rb
@@ -421,20 +544,22 @@ files:
 - lib/brut/front_end/templates/erb_parser.rb
 - lib/brut/front_end/templates/escapable_filter.rb
 - lib/brut/front_end/templates/html_safe_string.rb
+- lib/brut/front_end/templates/locator.rb
 - lib/brut/i18n.rb
 - lib/brut/i18n/base_methods.rb
 - lib/brut/i18n/for_cli.rb
 - lib/brut/i18n/for_html.rb
 - lib/brut/i18n/http_accept_language.rb
 - lib/brut/instrumentation.rb
-- lib/brut/instrumentation/basic.rb
-- lib/brut/instrumentation/event.rb
-- lib/brut/instrumentation/http_event.rb
-- lib/brut/instrumentation/subscriber.rb
+- lib/brut/instrumentation/logger_span_exporter.rb
+- lib/brut/instrumentation/open_telemetry.rb
 - lib/brut/junk_drawer.rb
 - lib/brut/sinatra_helpers.rb
 - lib/brut/spec_support.rb
+- lib/brut/spec_support/clock_support.rb
 - lib/brut/spec_support/component_support.rb
+- lib/brut/spec_support/e2e_test_server.rb
+- lib/brut/spec_support/enhanced_node.rb
 - lib/brut/spec_support/flash_support.rb
 - lib/brut/spec_support/general_support.rb
 - lib/brut/spec_support/handler_support.rb
@@ -444,8 +569,12 @@ files:
 - lib/brut/spec_support/matchers/be_routing_for.rb
 - lib/brut/spec_support/matchers/have_constraint_violation.rb
 - lib/brut/spec_support/matchers/have_html_attribute.rb
+- lib/brut/spec_support/matchers/have_i18n_string.rb
+- lib/brut/spec_support/matchers/have_link_to.rb
+- 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/rspec_setup.rb
 - lib/brut/spec_support/session_support.rb
 - lib/brut/version.rb
 - lib/sequel/extensions/brut_instrumentation.rb
@@ -461,7 +590,6 @@ metadata:
   homepage_uri: https://naildrivin5.com
   source_code_uri: https://naildrivin5.com
   changelog_uri: https://naildrivin5.com
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -476,8 +604,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.4
 specification_version: 4
 summary: NOT YET RELEASED - Web Framework Built around Ruby, Web Standards, Simplicity,
   and Object-Orientation

data/lib/brut/back_end/action.rb

@@ -1,3 +0,0 @@
-class Brut::BackEnd::Action
-  include SemanticLogger::Loggable
-end

data/lib/brut/back_end/result.rb

@@ -1,46 +0,0 @@
-# The result of back-end processing, which is essentially
-# a container for constraint violations and arbitrary context.
-class Brut::BackEnd::Result
-  attr_reader :constraint_violations, :context
-
-  def initialize
-    @constraint_violations = {}
-    @context = {}
-  end
-
-  def constraint_violation!(object:,
-                            field:,
-                            key:,
-                            context: {})
-    @constraint_violations[object] ||= {}
-    @constraint_violations[object][field] ||= {}
-    @constraint_violations[object][field][key] = context
-  end
-
-  def each_violation(&block)
-    @constraint_violations.each do |object,fields|
-      fields.each do |field,keys|
-        keys.each do |key,context|
-          block.(object,field,key,context)
-        end
-      end
-    end
-  end
-
-  def []=(key_in_context,object)
-    @context[key_in_context] = object
-  end
-
-  def [](key_in_context)
-    @context.fetch(key_in_context)
-  rescue KeyError => ex
-    raise KeyError.new(
-      "Context did not contain '#{key_in_context}' (#{key_in_context.class}). Context has these keys: #{@context.keys.join(',')}",
-      receiver: ex.receiver,
-      key: ex.key)
-  end
-
-
-  def constraint_violations? = self.constraint_violations.any?
-
-end

data/lib/brut/front_end/components/timestamp.rb

@@ -1,33 +0,0 @@
-require "rexml"
-class Brut::FrontEnd::Components::Timestamp < Brut::FrontEnd::Component
-  include Brut::I18n::ForHTML
-  def initialize(timestamp:, format: :full, skip_year_if_same: true, attribute_format: :iso_8601, **only_contains_class)
-    @timestamp = timestamp
-    formats = [ format ]
-    if @timestamp.year == Time.now.year && skip_year_if_same
-      formats.unshift("#{format}_no_year")
-    end
-    format_keys = formats.map { |f| "time.formats.#{f}" }
-    found_format = formats.zip(::I18n.t(format_keys)).detect { |(key,value)|
-      value !~ /^Translation missing/
-    }.first
-    if found_format.nil?
-      raise ArgumentError,"format #{format} is not a known time format"
-    end
-    @format = found_format.to_sym
-
-    if ::I18n.t("time.formats.#{attribute_format}") =~ /^Translation missing/
-      raise ArgumentError,"attribute_format #{attribute_format} is not a known time format"
-    end
-    @attribute_format = attribute_format.to_sym
-    @class_attribute = only_contains_class[:class] || ""
-  end
-
-
-  def render(clock:)
-    timestamp_in_time_zone = clock.in_time_zone(@timestamp)
-    html_tag(:time, class: @class_attribute, datetime: ::I18n.l(timestamp_in_time_zone,format: @attribute_format)) do
-      ::I18n.l(timestamp_in_time_zone,format: @format)
-    end
-  end
-end

data/lib/brut/instrumentation/basic.rb

@@ -1,66 +0,0 @@
-class Brut::Instrumentation::Basic
-  def initialize
-    @subscribers = Concurrent::Set.new
-  end
-
-  class TypeChecking < Brut::Instrumentation::Basic
-    def instrument(event,&block)
-      if !event.kind_of?(Brut::Instrumentation::Event)
-        raise "You cannot instrument a #{event.class} - it must be a Brut::Instrumentation::Event or subclass"
-      end
-      super
-    end
-  end
-
-  def instrument(event,&block)
-    block ||= ->() {}
-
-    start     = Time.now
-    result    = nil
-    exception = nil
-
-    begin
-      result = block.(event)
-    rescue => ex
-      exception = ex
-    end
-    stop = Time.now
-    notify(event:,start:,stop:,exception:)
-    if exception
-      raise exception
-    else
-      result
-    end
-  end
-
-  def subscribe(subscriber=:use_block,&block)
-    if block.nil? && subscriber == :use_block
-      raise ArgumentError,"subscriber requires a Brut::Instrumentation::Subscriber or a block"
-    end
-    if !block.nil? && subscriber != :use_block
-      raise ArgumentError,"subscriber requires a Brut::Instrumentation::Subscriber or a block, not both"
-    end
-    if block.nil?
-      if subscriber.kind_of?(Proc)
-        subscriber = Brut::Instrumentation::Subscriber.from_proc(subscriber)
-      elsif !subscriber.kind_of?(Brut::Instrumentation::Subscriber)
-        raise ArgumentError, "subscriber must be a Proc or Brut::Instrumentation::Subscriber, not a #{subscriber.class}"
-      end
-    else
-      subscriber = Brut::Instrumentation::Subscriber.from_proc(block)
-    end
-    @subscribers << subscriber
-  end
-
-  def notify(event:,start:,stop:,exception:)
-    Thread.new do
-      @subscribers.each do |subscriber|
-        begin
-          subscriber.(event:,start:,stop:,exception:)
-        rescue => ex
-          warn "#{subscriber} raised #{ex}"
-        end
-      end
-    end
-  end
-end

data/lib/brut/instrumentation/event.rb

@@ -1,19 +0,0 @@
-class Brut::Instrumentation::Event
-  include Brut::Framework::FussyTypeEnforcement
-
-  attr_reader :category,
-              :subcategory,
-              :name,
-              :details
-
-  def initialize(category:,
-                 subcategory:nil,
-                 name:,
-                 details:{})
-    @category    = type!(category,String,"category",required: true, coerce: :to_s)
-    @subcategory = type!(subcategory,String,"subcategory",required: false, coerce: :to_s)
-    @name        = type!(name,String,"name",required:true,coerce: :to_s)
-    @details     = type!(details,Hash,"details",required:false) || {}
-  end
-
-end

data/lib/brut/instrumentation/http_event.rb

@@ -1,5 +0,0 @@
-class Brut::Instrumentation::HTTPEvent < Brut::Instrumentation::Event
-  def initialize(http_method:,name:,path:,details:{})
-    super(category: "http", subcategory: http_method, name: name, details: details.merge(path:path))
-  end
-end

data/lib/brut/instrumentation/subscriber.rb

@@ -1,41 +0,0 @@
-class Brut::Instrumentation::Subscriber
-  def self.from_proc(block)
-    required_parameter_names_found   = self.instance_method(:call).parameters.map { |(type,name)| [ name, false ] }.to_h
-    unexpected_parameter_names_error = {}
-
-    block.parameters.each do |(type,name)|
-      if required_parameter_names_found.key?(name)
-        if type == :key || type == :keyreq
-          required_parameter_names_found[name] = true
-        else
-          unexpected_parameter_names[name] = "Not a keyword arg"
-        end
-      elsif type != :key
-        if type == :keyreq
-          unexpected_parameter_names[name] = "keyword arg without a default value"
-        else
-          unexpected_parameter_names[name] = "Not a keyword arg"
-        end
-      end
-    end
-    errors = []
-    if unexpected_parameter_names_error.any?
-      messages = unexpected_parameter_names_error.map { |name,problem|
-        "#{name} - #{problem}"
-      }.join(", ")
-      errors << "Unexpected parameters were required, so this cannot be used as a subscriber: #{messages}"
-    end
-    if required_parameter_names_found.any? { |_name,found| !found }
-      messages = required_parameter_names_found.select { |_name,found| !found }.map { |name,_found| "#{name} must be a keyword argument" }.join(",")
-      errors << "Required parameters were missing, so this cannot be used as a subscriber: #{messages}"
-    end
-    if errors.any?
-      raise ArgumentError,errors.join(", ")
-    end
-    block
-  end
-
-  def call(event:,start:,stop:,exception:)
-  end
-
-end