rackal 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ead58575158b4ee56a407d2dc1efc3b9ca7dbe00fef20cfd2f6151fbc1a6585
-  data.tar.gz: 2b325e4277a93d86795c280acd6e3d83b4ec8090322e2f198889379d5e6e9244
+  metadata.gz: 9b8aeffe0440b8e7bc48ffa1cfb8cb4192896da0230e46fc2d900ff002a32889
+  data.tar.gz: 2384ea484c8f6a50460efefa32f11630a336c88b77b31c7f5591f987783049e3
 SHA512:
-  metadata.gz: b407bd38f1d6e5dac470a165c8111b022150b501acd0f1b59b40c9a71216a7650888295aed80a8969e2206fec9e76b6f33fbf439c76e626eda430cd8caffcdba
-  data.tar.gz: 53a49cea9ac29e8bd342867ae1714f72acdf5a3cf457b6d7d63a9962bbad9a5944bb186e9f9b627ae2c34e7c9950f3c7871aca2511d3df724f81bb34468defd4
+  metadata.gz: 3c7c8ad588cb2a63806cf3117e93d88a1e2924937bf7e850618b370b8ef554faba7cf86818eeac6d93ad21a8eb1a300d8de4d685c9e8cfd1d5ae48cf03eee0bf
+  data.tar.gz: 23e739d63c605079ba3a977294fb857835f87b5df42313822450ed5d84762943263c442410fb0101eb15d3b3c712ff91a2a83034a6f6cf8205f67e2d0a422d79

data/LICENSE

@@ -1,17 +1,21 @@
+MIT License
+
 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:
+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 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.
+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

@@ -1,6 +1,8 @@
 # Rackal
 
-The `rackal` gem provides helpers in configuring directly configuring Rack.
+[![Gem Version](https://badge.fury.io/rb/rackal.svg)](https://badge.fury.io/rb/rackal)
+
+The `rackal` gem provides convenience helpers when configuring Rack applications.
 
 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
@@ -8,13 +10,16 @@ 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.
+been performed, so milage may vary. This gem is still considered experimental (at least
+until version number is updated to at least 0.1.0).
 
 ## 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
+* Database configuration: easy access to database configuration (based on YAML configuration file)
+* Application metadata: easy access to application details (trivial YAML configuration file)
+* Application protection: easy use of [Refrigerator](https://github.com/jeremyevans/ruby-refrigerator) gem (when available)
+
+Easy setup for application logging is being considered for inclusion in Rackal.
 
 ## Example `config.ru`
 ```
@@ -32,15 +37,110 @@ 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)
+# => Starting MyApp in production environment.
+puts "(root directory is \"#{Rackal.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
 ```
 
+An demonstration application using Rackal will be provided in a later version.
+
+## Main interface
+Available as namespaced methods:
+
+* `Rackal.application` returns an object allowing access to various application metadata
+* `Rackal.root` returns the inferred root directory of the application (same as `Rackal.appliation.root`)
+* `Rackal.database_parameters` returns Hash of database connection attributes (see below)
+* `Rackal.environment` returns an object allowing access to various runtime environment (e.g., "production") metadata
+* `Rackal.env` convenience use of `ENV` array (with caching) (e.g., `Rackal.env("RACK_ENV")` == `ENV["RACK_ENV"]`)
+* `Rackal.protect!` applies [Refrigerator](https://github.com/jeremyevans/ruby-refrigerator) gem (if available) to lock/freeze the application during run time. Merely returns `false` if gem is not available.
+
+If `ENV["RACK_ENV"]` is `nil` for whatever reason, Rackal will assume a development environment.
+
+## Configuration
+Two configuration files, written in YAML, will be assumed to be under `/config` directory for
+the application: `database.yml` and `rackal.yml`
+
+### Twelve-factor app
+If adhering to the [twelve-factor app](https://12factor.net/config) standard, recall that
+deploy-level configuration should not included in code, but application configuration can
+be.
+
+Rackal does not interfere with use of tools like [dotenv](https://github.com/bkeepers/dotenv)
+or [figaro](https://github.com/laserlemon/figaro) to support deploy-level environment variable.
+Merely add that to the application startup (e.g., `config.ru`) in the usual way before
+calling any Rackal methods.
+
+Since the YAML files used for Rackal's configuration support ERB, those files can then
+follow the environment variables supplied dynamically when wanted, while leaving
+application-level directly supplied.  The `database.yml` example below shows such a use
+for credentials.
+
+### `database.yml`
+
+The `database.yml` file is just to collect, by runtime environment, the parameters for
+connecting to the database.
+
+If `Rackal.database_parameters` is never called, this YAML file need not be present.
+
+Example (for Sequel using Postgres):
+```
+default: &default
+  adapter: 'postgres'
+  # host: 'some_db_url'
+  # port: '5432'
+  database: 'myapp'
+  max_connections: 10
+  username: <%= Rackal.env('MYAPP_DATABASE_USERNAME') %>
+  password: <%= Rackal.env('MYAPP_DATABASE_PASSWORD') %>
+
+development:
+  <<: *default
+  host: 'localhost'
+  database: 'myapp_dev'
+
+test:
+  <<: *default
+  host: 'localhost'
+  database: 'myapp_test'
+
+staging:
+  <<: *default
+
+production:
+  <<: *default
+```
+
+For the given runtime environment, the configured parameters are available in code via
+`Rackal.database_parameters` which provides a Hash (using symbols as keys):
+```
+Rackal.database_parameters[:database]
+# => "myapp_test" if ENV['RACK_ENV'] == "test"
+```
+
+### `rackal.yml`
+
+The `rackal.yml` file is for any specifics to inform Rackal of assumptions it can make.
+
+Presently, only the name of the application is configured to support inference of how
+to refer to it in the boilerplate it abstracts away (e.g., class name, source file name).
+
+If neither `Rackal.root` nor `Rackal.application` are ever called (unlikely), this YAML file
+need not be present.
+
+Example:
+```
+rackal:
+  app_main: 'SomeApp' # note that this is the class name, provided as a string
+```
+
+* `app_main`: class name of the main class used to drive the application.
+  * The string, as given, is available in code as `Rackal.application.name`
+  * The class, as a constant, is available in case as `Rackal.application.main_class`
+
 ## 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
@@ -56,16 +156,29 @@ Since a Gemfile is used for testing and development conveniences without polluti
 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.
+The provided RSpec tests have strong coverage for regression testing. Mutation testing
+will be attempted soon.
 
 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.
+Jeremy Evans's `roda-sequel-stack` [repository](https://github.com/jeremyevans/roda-sequel-stack)
+was used as an original reference for boilerplate (though the "up"/"down" mechanics for
+database migrations are not considered in Rackal).
+
+Some application metadata concepts were inspired by Rails (for instance, `Rackal.root`),
+though with a much lighter (and so less robust) approach taken in Rackal.
+
+## Limitations
+* Rackal (primarily `Rackal.root`) assumes use in a Linux style OS and so use of `/` as a
+path delimiter.
+* Right now, `Rackal.database_parameters` has only been tested with Sequel ORM for database
+connections, though the use of YAML to produce the Hash should be universally capable.
+* (As stated in the introduction to this notes,) Rackal has not been tested with a bare
+Rack application or with a Sinatra application.
+
+Please [report issues or bugs](https://github.com/rdnewman/rackal/issues).
 
 ## License
 Rackal is released under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rackal.rb

@@ -16,6 +16,12 @@ module Rackal
     @environment = Internal::RackEnvironment.new(options)
   end
 
+  # Retrieves database connection parameters from configuration file
+  # Requires `config/database.yml`.
+  #
+  # @param [Hash] options
+  # @option options [true, false] :reset If true, resets cache and ensure fresh retrieval (defaults to: false)
+  # @return [Hash]
   def self.database_parameters(options = {})
     reload = options.delete(:reload) || false
     @database_parameters = nil if reload
@@ -23,6 +29,11 @@ module Rackal
     @database_parameters ||= Internal::DatabaseConfiguration.parameters
   end
 
+  # Retrieves OS environment values (`ENV`)
+  #
+  # @param [Hash] options
+  # @option options [true, false] :reset If true, resets cache and ensure fresh retrieval (defaults to: false)
+  # @return [String]
   def self.env(key, options = {})
     reload = options.delete(:reload) || false
     @env = nil if reload
@@ -32,14 +43,23 @@ module Rackal
     @env[key] || (@env[key] = ENV.fetch(key.to_s, nil))
   end
 
+  # Retrieves application details. Requires `config/rackal.yml`.
+  #
+  # @return [Object] an object
   def self.application
     @application ||= Internal::Application.new
   end
 
+  # Applies Refrigerator gem (if available) in protected Rack environments
+  #
+  # @return [true, false] true if gem available and in protected environment; otherwise, false
   def self.protect!
     Internal::Protection.apply
   end
 
+  # Returns root directory (inferred) for the application. Requires `config/rackal.yml`.
+  #
+  # @return [String] top (root) directory for the application
   def self.root
     @root ||= application.root
   end

data/lib/rackal/internal/application.rb

@@ -5,11 +5,7 @@ module Rackal
     class Application
       include ConfigurationFile
 
-      # TODO: -- drop this?!
-      def self.root
-        new.root
-      end
-
+      # @api private
       def initialize
         @config = parse
       end
@@ -18,16 +14,17 @@ module Rackal
         @config[:app_main]
       end
 
-      # only supports bare class names (not under a namespace)
       def main_class
+        # only supports bare class names (not under a namespace)
         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
+        # lightly inspired by Rails implementation in
+        # railties/lib/rails/engine.rb#find_root_with_flag
+
         return @root if defined?(@root) && @root
 
         paths = potential_root_paths
@@ -51,24 +48,12 @@ module Rackal
         @parse = read_configuration('rackal') { |content| content.fetch('rackal') }
       end
 
-      # only works in linux style OS (assumes path delimiter "/")
       def potential_root_paths
+        # only works in linux style OS (assumes path delimiter "/")
+
         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)
@@ -79,8 +64,6 @@ module Rackal
           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
@@ -88,7 +71,7 @@ module Rackal
       def main_class_rb_filename
         return nil unless name
 
-        # stolen from Rails ActiveSupport (but simpler)
+        # based on 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

data/lib/rackal/internal/database_configuration.rb

@@ -13,6 +13,7 @@ module Rackal
         end
       end
 
+      # @api private
       def initialize
         @parameters = parse
       end

data/lib/rackal/internal/rack_environment.rb

@@ -33,7 +33,7 @@ module Rackal
         !supported?
       end
 
-      # return Array list environments treated as protected (e.g., :production)
+      # @return Array list environments treated as protected (e.g., :production)
       def protected
         @protected ||= self.class.supported -
                        (@protect_test ? [:development] : [:development, :test])

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rackal
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Richard Newman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-10 00:00:00.000000000 Z
+date: 2021-07-11 00:00:00.000000000 Z
 dependencies: []
 description: 'Rack application helpers
 
@@ -31,7 +31,9 @@ files:
 homepage: https://rubygems.org/gems/rackal
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/rdnewman/rackal
+  bug_tracker_uri: https://github.com/rdnewman/rackal/issues
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -47,7 +49,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.23
 signing_key: 
 specification_version: 4
 summary: Rackal