brut 0.0.1

data/lib/brut/framework/config.rb

@@ -0,0 +1,415 @@
+require_relative "project_environment"
+require "pathname"
+
+# Exists to hold configuration for the Brut framework.
+# This is a wrapper around a series of calls to Brut.container.store
+# but is a class and thus invokable, so that the configuration can
+# be controlled.
+class Brut::Framework::Config
+
+  class DockerPathComponent
+    PATH_REGEXP = /\A[a-z0-9]+(-|_)?[a-z0-9]+\z/
+    def initialize(string)
+      if string.to_s.match?(PATH_REGEXP)
+        @string = string
+      else
+        raise ArgumentError.new("Value must be only lower case letters, digits, and may have at most one underscore: '#{string}'")
+      end
+    end
+
+    def to_str = @string
+    def to_s = self.to_str
+  end
+
+  class AppId < DockerPathComponent
+  end
+
+  class AppOrganizationName < DockerPathComponent
+  end
+
+  def configure!
+    Brut.container do |c|
+      # Brut Stuff that should not be changed
+
+      c.store_ensured_path(
+        "tmp_dir",
+        "Temporary directory where ephemeral files can do"
+      ) do |project_root|
+        project_root / "tmp"
+      end
+
+      c.store(
+        "project_env",
+        Brut::Framework::ProjectEnvironment,
+        "The environment of the running app, e.g. dev/test/prod",
+        Brut::Framework::ProjectEnvironment.new(ENV["RACK_ENV"])
+      )
+
+      c.store_ensured_path(
+        "log_dir",
+        "Path where log files may be written"
+      ) do |project_root|
+        project_root / "logs"
+      end
+
+      c.store_ensured_path(
+        "public_root_dir",
+        "Path to the root of all public files"
+      ) do |project_root|
+        project_root / "app" / "public"
+      end
+
+      c.store_ensured_path(
+        "images_root_dir",
+        "Path to the root of all images"
+      ) do |public_root_dir|
+        public_root_dir / "static" / "images"
+      end
+
+      c.store_ensured_path(
+        "css_bundle_output_dir",
+        "Path where bundled CSS is written for use in web pages"
+      ) do |public_root_dir|
+        public_root_dir / "css"
+      end
+
+      c.store_ensured_path(
+        "js_bundle_output_dir",
+        "Path where bundled JS is written for use in web pages"
+      ) do |public_root_dir|
+        public_root_dir / "js"
+      end
+
+      c.store(
+        "database_url",
+        String,
+        "URL to the primary database - generally avoid this and use sequel_db_handle"
+      ) do
+        ENV.fetch("DATABASE_URL")
+      end
+
+      c.store(
+        "sequel_db_handle",
+        Object,
+        "Handle to the database",
+      ) do |database_url|
+        Sequel.connect(database_url)
+      end
+
+      c.store_ensured_path(
+        "app_src_dir",
+        "Path to root of where all the app's source files are"
+      ) do |project_root|
+        project_root / "app" / "src"
+      end
+
+      c.store_ensured_path(
+        "app_specs_dir",
+        "Path to root of where all the app's specs/tests are"
+      ) do |project_root|
+        project_root / "specs"
+      end
+
+      c.store_ensured_path(
+        "js_specs_dir",
+        "Path to root of where all JS-based specs/tests are",
+      ) do |app_specs_dir|
+        app_specs_dir / "front_end" / "js"
+      end
+
+      c.store_required_path(
+        "front_end_src_dir",
+        "Path to the root of the front end layer for the app"
+      ) do |app_src_dir|
+        app_src_dir / "front_end"
+      end
+
+      c.store_required_path(
+        "components_src_dir",
+        "Path to where components classes and templates are stored"
+      ) do |front_end_src_dir|
+        front_end_src_dir / "components"
+      end
+
+      c.store_required_path(
+        "components_specs_dir",
+        "Path to where tests of components classes are stored",
+      ) do |app_specs_dir|
+        app_specs_dir / "front_end" / "components"
+      end
+
+      c.store_required_path(
+        "forms_src_dir",
+        "Path to where form classes are stored"
+      ) do |front_end_src_dir|
+        front_end_src_dir / "forms"
+      end
+
+      c.store_required_path(
+        "handlers_src_dir",
+        "Path to where handlers are stored"
+      ) do |front_end_src_dir|
+        front_end_src_dir / "handlers"
+      end
+
+      c.store_required_path(
+        "svgs_src_dir",
+        "Path to where svgs are stored"
+      ) do |front_end_src_dir|
+        front_end_src_dir / "svgs"
+      end
+
+      c.store_required_path(
+        "images_src_dir",
+        "Path to where images are stored"
+      ) do |front_end_src_dir|
+        front_end_src_dir / "images"
+      end
+
+      c.store_required_path(
+        "pages_src_dir",
+        "Path to where page classes and templates are stored"
+      ) do |front_end_src_dir|
+        front_end_src_dir / "pages"
+      end
+
+      c.store_required_path(
+        "pages_specs_dir",
+        "Path to where tests of page classes are stored",
+      ) do |app_specs_dir|
+        app_specs_dir / "front_end" / "pages"
+      end
+
+      c.store_required_path(
+        "layouts_src_dir",
+        "Path to where layout classes and templates are stored"
+      ) do |front_end_src_dir|
+        front_end_src_dir / "layouts"
+      end
+
+      c.store_required_path(
+        "js_src_dir",
+        "Path to where JS files are",
+      ) do |front_end_src_dir|
+        front_end_src_dir / "js"
+      end
+
+      c.store_required_path(
+        "back_end_src_dir",
+        "Path to the root of the back end layer for the app"
+      ) do |app_src_dir|
+        app_src_dir / "back_end"
+      end
+
+      c.store_ensured_path(
+        "data_models_src_dir",
+        "Path to the root of all data modeling",
+      ) do |back_end_src_dir|
+        back_end_src_dir / "data_models"
+      end
+
+      c.store_ensured_path(
+        "migrations_dir",
+        "Path to the DB migrations",
+      ) do |data_models_src_dir|
+        data_models_src_dir / "migrations"
+      end
+
+      c.store_ensured_path(
+        "db_seeds_dir",
+        "Path to the seed data for the DB",
+      ) do |data_models_src_dir|
+        data_models_src_dir / "seed"
+      end
+
+      c.store_ensured_path(
+        "config_dir",
+        "Path to where configuration files are stores"
+      ) do |project_root|
+        project_root / "app" / "config"
+      end
+
+      c.store(
+        "asset_metadata_file",
+        Pathname,
+        "Path to the asset metadata file, used to manage hashed asset names"
+      ) do |config_dir|
+        config_dir / "asset_metadata.json"
+      end
+
+
+      c.store(
+        "layout_locator",
+        "Brut::FrontEnd::Component::TemplateLocator",
+        "Object to use to locate templates for layouts"
+      ) do |layouts_src_dir|
+        Brut::FrontEnd::Component::TemplateLocator.new(paths: layouts_src_dir,
+                                                       extension: "html.erb")
+      end
+
+      c.store(
+        "page_locator",
+        "Brut::FrontEnd::Component::TemplateLocator",
+        "Object to use to locate templates for pages"
+      ) do |pages_src_dir|
+        Brut::FrontEnd::Component::TemplateLocator.new(paths: pages_src_dir,
+                                                       extension: "html.erb")
+      end
+
+      c.store(
+        "component_locator",
+        "Brut::FrontEnd::Component::TemplateLocator",
+        "Object to use to locate templates for components"
+      ) do |components_src_dir, pages_src_dir|
+        Brut::FrontEnd::Component::TemplateLocator.new(paths: [ components_src_dir, pages_src_dir ],
+                                                       extension: "html.erb")
+      end
+
+      c.store(
+        "svg_locator",
+        "Brut::FrontEnd::Component::TemplateLocator",
+        "Object to use to locate SVGs"
+      ) do |svgs_src_dir|
+        Brut::FrontEnd::Component::TemplateLocator.new(paths: svgs_src_dir,
+                                                       extension: "svg")
+      end
+
+      c.store(
+        "asset_path_resolver",
+        "Brut::FrontEnd::Component::AssetPathResolver",
+        "Object to use to resolve logical asset paths to actual asset paths"
+      ) do |asset_metadata_file|
+        Brut::FrontEnd::Component::AssetPathResolver.new(metadata_file: asset_metadata_file)
+      end
+
+      c.store(
+        "routing",
+        "Brut::FrontEnd::Routing",
+        "Routing for all registered routes of this app",
+        Brut::FrontEnd::Routing.new
+      )
+
+      c.store(
+        "instrumentation",
+        Brut::Instrumentation::Basic,
+        "Interface for recording instrumentable events and subscribing to them",
+      ) do |project_env|
+        if project_env.production?
+          Brut::Instrumentation::Basic.new
+        else
+          Brut::Instrumentation::Basic::TypeChecking.new
+        end
+      end
+
+      # App can override
+
+      c.store(
+        "external_id_prefix",
+        String,
+        "String to use as a prefix for external ids in tables using the external_id feature. Nil means the feature is disabled",
+        nil,
+        allow_app_override: true,
+        allow_nil: true,
+      )
+
+      c.store(
+        "debug_zeitwerk?",
+        :boolean,
+        "If true, Zeitwerk's loading will be logged for debugging purposes. Do not enable this in production",
+        false,
+        allow_app_override: true,
+      )
+
+      c.store(
+        "session_class",
+        Class,
+        "Class to use when wrapping the Rack session",
+        Brut::FrontEnd::Session,
+        allow_app_override: true,
+      )
+
+      c.store(
+        "flash_class",
+        Class,
+        "Class to use to represent the Flash",
+        Brut::FrontEnd::Flash,
+        allow_app_override: true,
+      )
+
+      c.store(
+        "semantic_logger_appenders",
+        { Hash => "if only one appender is needed", Array => "to configure multiple appenders" },
+        "List of appenders to be configured for SemanticLogger",
+        allow_app_override: true
+      ) do |project_env,log_dir|
+        appenders = if project_env.development?
+                      [
+                        { formatter: :color, io: $stdout },
+                        { file_name: (log_dir / "development.log").to_s },
+                      ]
+                    end
+        if appenders.nil?
+          appenders = { file_name: (log_dir / "#{project_env}.log").to_s }
+        end
+        if appenders.nil?
+          appenders = { io: $stdout }
+        end
+        appenders
+      end
+
+      c.store(
+        "eager_load_classes?",
+        :boolean,
+        "If true, classes are eagerly loaded upon startup",
+        true,
+        allow_app_override: true
+      )
+
+      c.store(
+        "auto_reload_classes?",
+        :boolean,
+        "If true, classes are reloaded with each request. Useful only really for development",
+        allow_app_override: true
+      ) do |project_env|
+        no_reload_in_dev = ENV["BRUT_NO_RELOAD_IN_DEV"] == "true"
+        if project_env.development?
+          !no_reload_in_dev
+        else
+          false
+        end
+      end
+
+      c.store(
+        "log_level",
+        String,
+        "Log level to control how much logging is happening",
+        allow_app_override: true,
+      ) do
+        ENV["LOG_LEVEL"] || "debug"
+      end
+
+      c.store(
+        "csp_class",
+        Class,
+        "Route Hook to use for setting the Content-Security-Policy header",
+        allow_app_override: true,
+        allow_nil: true,
+      ) do |project_env|
+        if project_env.development?
+          Brut::FrontEnd::RouteHooks::CSPNoInlineScripts
+        else
+          Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts
+        end
+      end
+
+      c.store(
+        "csp_reporting_class",
+        Class,
+        "Route Hook to use for setting the Content-Security-Policy-Report-Only header",
+        Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts::ReportOnly,
+        allow_app_override: true,
+        allow_nil: true,
+      )
+    end
+  end
+end

data/lib/brut/framework/container.rb

@@ -0,0 +1,190 @@
+require "fileutils"
+
+module Brut
+  def self.container(&block)
+    @container ||= Brut::Framework::Container.new
+    if !block.nil?
+      block.(@container)
+    end
+    @container
+  end
+end
+
+# This is a basic container for shared context, configuration,
+# and objects. This allows easily sharing cross-cutting information
+# such as project root, environment, and other objects.
+#
+# This can be used to store configuration values, re-usable objects,
+# or anything else that is needed in the app.  Values are fetched lazily
+# and can depend on other values in this container.
+#
+# There is no namespacing/hierarchy.
+class Brut::Framework::Container
+  def initialize
+    @container = {}
+  end
+
+  # Store a named value for later.
+  #
+  # name:: The name of the value. This should be a string that is a valid Ruby identifier.
+  # type:: Description of the type that the value should conform to. if this value is "boolean" or :boolean, then
+  #        the value will be coerced into `true` or `false`. Otherwise, this serves as documentation for now.
+  # description:: Documentation as to what this value is for.
+  # value:: if given, this is the value to use.
+  # block:: If value is omitted, block will be evaluated the first time the value is
+  #         fetched and is expected to return the value to use for all subsequent
+  #         requests.
+  #
+  #         The block can receive parameters and those parameters names must
+  #         match other values stored in this container.  Those values are passed in.
+  #
+  #         For example, if you have the value `project_root`, you can then set another
+  #         value called `tmp_dir` that uses `project_root` like so:
+  #
+  #         ```
+  #         container.store("tmp_dir") { |project_root| project_root / "tmp" }
+  #         ```
+  def store(name,type,description,value=:use_block,allow_app_override: false,allow_nil: false,&block)
+    # TODO: Check that value / block is used properly
+    name = name.to_s
+    if type == "boolean"
+      type = :boolean
+    end
+    if type == :boolean
+      if name !~ /\?$/
+        raise ArgumentError, "#{name} is a boolean so must end with a question mark"
+      end
+    end
+    self.validate_name!(name:,type:,allow_app_override:)
+    if value == :use_block
+      derive_with = block
+      @container[name] = { value: nil, derive_with: derive_with }
+    else
+      if type == :boolean
+        value = !!value
+      end
+      @container[name] = { value: value }
+    end
+    @container[name][:description]        = description
+    @container[name][:type]               = type
+    @container[name][:allow_app_override] = allow_app_override
+    @container[name][:allow_nil]          = allow_nil
+    self
+  end
+
+  def override(name,value=:use_block,&block)
+    name = name.to_s
+    if !@container[name]
+      raise ArgumentError,"#{name} has not been specified so you cannot override it"
+    end
+    if !@container[name][:allow_app_override]
+      raise ArgumentError,"#{name} does not allow the app to override it"
+    end
+    if value == :use_block
+      @container[name] = { value: nil, derive_with: block }
+    else
+      @container[name] = { value: value }
+    end
+  end
+
+  # Store a value that represents a path that must exist. The value will
+  # be assumed to be of type Pathname
+  def store_required_path(name,description,value=:use_block,&block)
+    self.store(name,Pathname,description,value,&block)
+    @container[name][:required_path] = true
+    self
+  end
+
+  # Store a value that represents a path that can be created if
+  # it does not exist. The path won't be created until the value is 
+  # accessed the first time. The value will
+  # be assumed to be of type Pathname
+  def store_ensured_path(name,description,value=:use_block,&block)
+    self.store(name,Pathname,description,value,&block)
+    @container[name][:ensured_path] = true
+    self
+  end
+
+  # Fetch a value by using its name as a method to instances of this class.
+  def method_missing(sym,*args,&block)
+    if args.length == 0 && block.nil? && self.respond_to_missing?(sym)
+      fetch_value(sym.to_s)
+    else
+      super.method_missing(sym,*args,&block)
+    end
+  end
+
+  # Implemented to go along with method_missing
+  def respond_to_missing?(name,include_private=false)
+    @container.key?(name.to_s)
+  end
+
+
+  # Fetch a value given a name.
+  def fetch(name)
+    fetch_value(name.to_s)
+  end
+
+private
+
+  def fetch_value(name)
+    # TODO: Provide a cleanr impl and better error checking if things go wrong
+    x = @container.fetch(name)
+
+    value = x[:value]
+
+    if !value.nil? || (x[:allow_nil] && value.nil?)
+      handle_path_values(name,x)
+      return value
+    end
+
+    deriver = x[:derive_with]
+    if deriver.nil?
+      raise "Something is seriously wrong. '#{name}' was stored in container without a derive_with value"
+    end
+
+    parameters = deriver.parameters(lambda: true)
+    args = parameters.map { |param_description| param_description[1] }.map { |name_of_dependent_object| self.send(name_of_dependent_object) }
+    value = deriver.(*args)
+    if x[:type] == :boolean
+      value = !!value
+    end
+    x[:value] = value
+    if x[:value].nil?
+      if !x[:allow_nil]
+        raise "Something is wrong: #{name} had no value"
+      end
+    end
+    handle_path_values(name,x)
+    x[:value]
+  end
+
+  def handle_path_values(name,contained_value)
+    value = contained_value[:value]
+    if contained_value[:required_path] && !Dir.exist?(value)
+      raise "For value '#{name}', the directory is represents must exist, but does not: '#{value}'"
+    end
+    if contained_value[:ensured_path]
+      FileUtils.mkdir_p value
+    end
+  end
+
+  PATHNAME_NAME_REGEXP = /_(dir|file)$/
+
+  def validate_name!(name:,type:,allow_app_override:)
+    if @container.key?(name)
+      if allow_app_override
+        raise ArgumentError.new("Name '#{name}' has already been specified - to override it, use Brut.container.override")
+      else
+        raise ArgumentError.new("Name '#{name}' has already been specified - you cannot override it")
+      end
+    end
+    if type.to_s == "Pathname"
+      if name != "project_root"
+        if !name.match(PATHNAME_NAME_REGEXP)
+          raise ArgumentError.new("Name '#{name}' is a Pathname, and must end in '_dir' or '_file'")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+class Brut::Framework::Errors::AbstractMethod < Brut::Framework::Error
+  def initialize(message=nil)
+    if message.nil?
+      super
+    else
+      super("Subclass must implement: #{message}")
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# Thrown when a codepath should never have been allowed
+# to occur.  This is useful is signaling that the system
+# has some sort of bug in its integration. For example,
+# attempting to perform an action that the UI should've
+# prevented
+class Brut::Framework::Errors::Bug < Brut::Framework::Error
+  def initialize(message=nil)
+    if message.nil?
+      super
+    else
+      super("BUG: #{message}")
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# Indicates that a resource or database row does not exist.
+class Brut::Framework::Errors::NotFound < Brut::Framework::Error
+  def initialize(resource_name:,id:,context:nil)
+    if !context.nil?
+      context = ": #{context}"
+    end
+    super("Could not find a #{resource_name} using ID #{id}#{context}")
+  end
+end
+

data/lib/brut/framework/errors.rb

@@ -0,0 +1,14 @@
+module Brut
+  module Framework
+    module Errors
+      autoload(:Bug,"brut/framework/errors/bug")
+      autoload(:NotFound,"brut/framework/errors/not_found")
+      autoload(:AbstractMethod,"brut/framework/errors/abstract_method")
+      def bug!(message=nil)
+        raise Brut::Framework::Errors::Bug,message
+      end
+    end
+    class Error < StandardError
+    end
+  end
+end

data/lib/brut/framework/fussy_type_enforcement.rb

@@ -0,0 +1,50 @@
+# Include this to enable methods to help with type checking.  Generally, you should not use this
+# unless there is a real concern that someone will pass the wrong type in and it would not be obvious
+# that they made this mistake.  Of note, this is preferred for widely used classes instead of trying
+# to convert arguments to whatever type the class needs.
+module Brut::Framework::FussyTypeEnforcement
+  # Perform basic type checking, ideally inside a constructor when assigning ivars
+  #
+  # value:: the value that was given
+  # type_descriptor:: a class or an array of allowed values. If a class, value must be kind_of? that class. If an array,
+  #                   value must be one of the values in the array.
+  # variable_name_for_error_message:: the name of the variable so that error messages make sense
+  # required:: if true, the value may not be nil. If false, nil values are allowed and no real type checking is done. Note that a
+  #            string that is blank counts as nil, so a require string must not be blank.
+  # coerce:: if given, this is the symbol that will be used to coerce the value before type checking
+  def type!(value,type_descriptor,variable_name_for_error_message, required: false, coerce: false)
+
+    value_blank = value.nil? || ( value.kind_of?(String) && value.strip == "" )
+
+    if !required && value_blank
+      return value
+    end
+
+    if required && value_blank
+      raise ArgumentError.new("'#{variable_name_for_error_message}' must have a value")
+    end
+
+    if type_descriptor.kind_of?(Class)
+      coerced_value = coerce ? value.send(coerce) : value
+      if !coerced_value.kind_of?(type_descriptor)
+        class_description = if coerce
+                              "but was a #{value.class}, coerced to a #{coerced_value.class} via #{coerce}"
+                            else
+                              "but was a #{value.class}"
+                            end
+        raise ArgumentError.new("'#{variable_name_for_error_message}' must be a #{type_descriptor}, #{class_description} (value as a string is #{value})")
+      end
+      value = coerced_value
+    elsif type_descriptor.kind_of?(Array)
+      if !type_descriptor.include?(value)
+        description_of_values = type_descriptor.map { |value|
+          "#{value} (a #{value.class})"
+        }.join(", ")
+        raise ArgumentError.new("'#{variable_name_for_error_message}' must be one of #{description_of_values}, but was a #{value.class} (value as a string is #{value})")
+      end
+    else
+      raise ArgumentError.new("Use of type! with a #{type_descriptor.class} (#{type_descriptor}) is not supported")
+    end
+    value
+  end
+end