rackal 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ead58575158b4ee56a407d2dc1efc3b9ca7dbe00fef20cfd2f6151fbc1a6585
+  data.tar.gz: 2b325e4277a93d86795c280acd6e3d83b4ec8090322e2f198889379d5e6e9244
+SHA512:
+  metadata.gz: b407bd38f1d6e5dac470a165c8111b022150b501acd0f1b59b40c9a71216a7650888295aed80a8969e2206fec9e76b6f33fbf439c76e626eda430cd8caffcdba
+  data.tar.gz: 53a49cea9ac29e8bd342867ae1714f72acdf5a3cf457b6d7d63a9962bbad9a5944bb186e9f9b627ae2c34e7c9950f3c7871aca2511d3df724f81bb34468defd4

data/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2021 Richard Newman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,71 @@
+# Rackal
+
+The `rackal` gem provides helpers in configuring directly configuring Rack.
+
+The main intent is abstract away some common boilerplate and reduce hardcoded details in
+application configuration, especially in `config.ru`, in a way that still allows some
+direct control of how it is applied.
+
+Rackal was originally developed to simplify set up of Roda apps but is intended to not
+assume or depend on Roda. As of this writing, no testing with Sinatra or bare Rack apps has
+been performed, so milage may vary. This gem is still considered experimental.
+
+## Features
+* Environment aware: "production", "staging", "test", and "development" are recognized (based on ENV['RACK_ENV'])
+* Database configuration: easy access to database configuration (based on YAML)
+* Application metadata: easy access to application details (trivial YAML configuration)
+* Application protection: easy use of Refrigerator gem if used
+
+## Example `config.ru`
+```
+require 'rackal'
+
+# support logging
+if Rackal.environment.unprotected? # by default: "development" or "test" is unprotected
+  require 'logger'
+  logger = Logger.new($stdout)
+end
+
+require 'roda'
+
+Gem.ruby
+
+# these output lines demonstrate some use
+puts "Starting #{Rackal.application.name} in #{Rackal.environment.env} environment."
+#=> Starting MyApp in production environment.
+puts "(root directory is #{Rackal.application.root})"
+#=> (root directory is /home/someuser/src/my_app)
+
+run(Rackal.application.main_class.freeze.app) # main_class is the driving class of the application
+
+Rackal.protect!  # applies Refrigerator if gem is present in production settings
+```
+
+## Performance
+Given that one key feature of Roda is its performance and memory footprint, care was taken
+to avoid interferring with that. Any cost is constrained as much as possible to only
+application startup:
+* Rackal is expected to add minimal time to application startup.
+* Rackal is expected to consume marginally additional memory in the application for holding its
+state once the application has started.
+
+Rigorous performance testing has not yet been done to ensure those claims.
+
+## Contributing
+Since a Gemfile is used for testing and development conveniences without polluting the
+gem itself, be sure to `bundle install`.  RSpec, simplecov, and rubocop are assumed, but
+only RSpec itself is required.
+
+The provided RSpec tests have strong coverage. Presently focus on mutation testing is
+ongoing.
+
+Further development is invited to better support Roda applications, extensions and
+generalization for non-Roda Rack applications, and performance improvements.
+
+## Acknowledgements
+Jeremy Evans's `roda-sequel-stack` [repository](https://github.com/jeremyevans/roda-sequel-stack) was used as the original reference for boilerplate.
+
+Some application metadata concepts were inspired by Rails, with a much lighter approach taken.
+
+## License
+Rackal is released under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rackal.rb

@@ -0,0 +1,46 @@
+require 'rackal/internal/application'
+require 'rackal/internal/database_configuration'
+require 'rackal/internal/rack_environment'
+require 'rackal/internal/protection'
+
+module Rackal
+  # Retrieves current Rack environment with convenience methods
+  #
+  # @param [Hash] options
+  # @option options [true, false] :reset If true, resets cache and ensure fresh retrieval (defaults to: false)
+  # @return [Object] an object
+  def self.environment(options = {})
+    reload = options.delete(:reload) || false
+    @environment = nil if reload
+
+    @environment = Internal::RackEnvironment.new(options)
+  end
+
+  def self.database_parameters(options = {})
+    reload = options.delete(:reload) || false
+    @database_parameters = nil if reload
+
+    @database_parameters ||= Internal::DatabaseConfiguration.parameters
+  end
+
+  def self.env(key, options = {})
+    reload = options.delete(:reload) || false
+    @env = nil if reload
+
+    @env ||= {}
+
+    @env[key] || (@env[key] = ENV.fetch(key.to_s, nil))
+  end
+
+  def self.application
+    @application ||= Internal::Application.new
+  end
+
+  def self.protect!
+    Internal::Protection.apply
+  end
+
+  def self.root
+    @root ||= application.root
+  end
+end

data/lib/rackal/internal/application.rb

@@ -0,0 +1,99 @@
+require_relative 'configuration_file'
+
+module Rackal
+  module Internal
+    class Application
+      include ConfigurationFile
+
+      # TODO: -- drop this?!
+      def self.root
+        new.root
+      end
+
+      def initialize
+        @config = parse
+      end
+
+      def name
+        @config[:app_main]
+      end
+
+      # only supports bare class names (not under a namespace)
+      def main_class
+        raise NameError unless name
+
+        @main_class ||= Object.const_get(name)
+      end
+
+      # lightly inspired by Rails implementation in
+      # railties/lib/rails/engine.rb#find_root_with_flag
+      def root
+        return @root if defined?(@root) && @root
+
+        paths = potential_root_paths
+
+        # 1) preference is to find "config.ru" if possible
+        # 2) if not (1), try to find main app
+        # 3) if not (1) or (2) look for nearest lib/ directory
+        [:configru, :app, :lib].each do |key|
+          info = paths.detect { |path| path[key] }
+          @root = info&.fetch(:dirname, nil)
+          return @root if @root
+        end
+
+        # give up if we can't find it
+        @root = Dir.pwd
+      end
+
+    private
+
+      def parse
+        @parse = read_configuration('rackal') { |content| content.fetch('rackal') }
+      end
+
+      # only works in linux style OS (assumes path delimiter "/")
+      def potential_root_paths
+        appname = main_class_rb_filename
+
+        caller_locations.lazy.map { |location| assess_location(location, appname) }
+        #   assess_location
+        #   path = location.absolute_path || location.path
+        #   dirname = File.dirname(path)
+
+        #   {
+        #     dirname: dirname,
+        #     configru: File.directory?(dirname) && File.exist?("#{dirname}/config.ru"),
+        #     app: appname && (File.directory?(dirname) && File.exist?("#{dirname}/#{appname}")),
+        #     # configru: File.directory?(path) && File.exist?("#{path}/config.ru"),
+        #     # app: appname && (File.directory?(path) && File.exist?("#{path}/#{appname}")),
+        #     lib: dirname.match?(/.*\/lib\/\z/)
+        #   }
+        # end
+      end
+
+      def assess_location(location, appname)
+        path = location.absolute_path || location.path
+        dirname = File.dirname(path)
+
+        {
+          dirname: dirname,
+          configru: File.directory?(dirname) && File.exist?("#{dirname}/config.ru"),
+          app: appname && (File.directory?(dirname) && File.exist?("#{dirname}/#{appname}")),
+          # configru: File.directory?(path) && File.exist?("#{path}/config.ru"),
+          # app: appname && (File.directory?(path) && File.exist?("#{path}/#{appname}")),
+          lib: dirname.match?(/.*\/lib\/\z/)
+        }
+      end
+
+      def main_class_rb_filename
+        return nil unless name
+
+        # stolen from Rails ActiveSupport (but simpler)
+        word = name.gsub(/([A-Z\d]+)(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) do
+          (Regexp.last_match(1) || Regexp.last_match(2)) << '_'
+        end
+        "#{word.tr('-', '_').downcase}.rb"
+      end
+    end
+  end
+end

data/lib/rackal/internal/configuration_file.rb

@@ -0,0 +1,24 @@
+require_relative 'yaml_file'
+
+module Rackal
+  module Internal
+    module ConfigurationFile
+      include YamlFile
+
+      def configuration_directory
+        'config'
+      end
+
+      def read_configuration(yaml_filename)
+        filename = yaml_filename&.strip || ''
+        if filename.empty?
+          raise ArgumentError, "must apply a YAML filename within #{configuration_directory}"
+        end
+
+        filepath = "#{configuration_directory}/#{yaml_filename}.yml"
+        content = yaml_content(filepath)
+        (block_given? ? yield(content) : content)&.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/rackal/internal/database_configuration.rb

@@ -0,0 +1,39 @@
+require_relative 'configuration_file'
+
+module Rackal
+  module Internal
+    class DatabaseConfiguration
+      include ConfigurationFile
+
+      attr_reader :parameters
+
+      class << self
+        def parameters
+          new.parameters
+        end
+      end
+
+      def initialize
+        @parameters = parse
+      end
+
+    private
+
+      def parse
+        requested_key = Rackal.environment.env.to_s
+        used_key = requested_key
+
+        result = read_configuration('database') do |content|
+          content.fetch(requested_key) { |_| content.fetch(used_key = 'default') }
+        end
+
+        result[:configuration_key] = {
+          requested: requested_key,
+          used: used_key
+        }
+
+        result
+      end
+    end
+  end
+end

data/lib/rackal/internal/protection.rb

@@ -0,0 +1,18 @@
+module Rackal
+  module Internal
+    module Protection
+      def self.apply
+        return false if Rackal.environment.unprotected?
+
+        begin
+          require 'refrigerator'
+        rescue LoadError
+          false
+        else
+          Refrigerator.freeze_core
+          true
+        end
+      end
+    end
+  end
+end

data/lib/rackal/internal/rack_environment.rb

@@ -0,0 +1,53 @@
+module Rackal
+  module Internal
+    class RackEnvironment
+      attr_reader :env
+
+      # @api private
+      def initialize(options = {})
+        @env = (ENV['RACK_ENV'] || 'development').to_sym
+
+        protect_test = options&.fetch(:protect_test, false) || false
+        @protect_test = protect_test ? true : false # force boolean
+      end
+
+      # @return Array list of environments recognized as supported by RackEnvironment
+      def self.supported
+        [:production, :staging, :test, :development]
+      end
+
+      supported.each do |supported_name|
+        # @!macro [attach] supported_name
+        #   @method $1?()
+        #   @return Boolean true if current environment is $1
+        define_method("#{supported_name}?") { env == supported_name }
+      end
+
+      # @return Boolean true if current environment is supported
+      def supported?
+        @supported ||= self.class.supported.include? env
+      end
+
+      # @return Boolean true if current environment is not supported
+      def unsupported?
+        !supported?
+      end
+
+      # return Array list environments treated as protected (e.g., :production)
+      def protected
+        @protected ||= self.class.supported -
+                       (@protect_test ? [:development] : [:development, :test])
+      end
+
+      # @return Boolean true if current environment is to be treated as protected
+      def protected?
+        @is_protected ||= protected.include? env
+      end
+
+      # @return Boolean true if current environment is not to be treated as protected
+      def unprotected?
+        @is_unprotected ||= !protected?
+      end
+    end
+  end
+end

data/lib/rackal/internal/yaml_file.rb

@@ -0,0 +1,17 @@
+require 'erb'
+require 'yaml'
+
+module Rackal
+  module Internal
+    module YamlFile
+      def yaml_content(filepath)
+        raise ArgumentError unless filepath.is_a?(String)
+
+        YAML.safe_load(
+          ERB.new(File.read(filepath)).result,
+          aliases: true
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: rackal
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Richard Newman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-07-10 00:00:00.000000000 Z
+dependencies: []
+description: 'Rack application helpers
+
+  '
+email:
+- richard@newmanworks.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rackal.rb
+- lib/rackal/internal/application.rb
+- lib/rackal/internal/configuration_file.rb
+- lib/rackal/internal/database_configuration.rb
+- lib/rackal/internal/protection.rb
+- lib/rackal/internal/rack_environment.rb
+- lib/rackal/internal/yaml_file.rb
+homepage: https://rubygems.org/gems/rackal
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key: 
+specification_version: 4
+summary: Rackal
+test_files: []