mimi-config 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cca2e6a1670a7c4f5721347e52617840139f84c3
-  data.tar.gz: 744fb11b98ed3ddbb7524a73a0a58b8156b0ddb7
+  metadata.gz: c11b17f051b8f15e08c1a3fbcfe0ba385949ff4a
+  data.tar.gz: 1c9eea0c84229415e795cfe45d107500f249250d
 SHA512:
-  metadata.gz: 8c7b0f8d48b89bfa92f24aea94ab620a692d8b67bc170bc89f1f75f0b2264cf2cdcfd82d06732681cff6c9f4527373f1be51448de19164d5eb9977848bca2a97
-  data.tar.gz: 4181ee303e70a2751fe026d89b639afc28ba6384e795f9f0f6c231dc855f4152b1ff63ea9cc023823bc855f51679fcabcfae35db82e4d29605acb229038fa5e9
+  metadata.gz: f6774639e0cd68abc8d81b44ede677827f42c933063bd93af2a811bce0dd17596fce9923c42bb235059ec24aaa022cd0f406edb5d98be27da98cc25797243fa2
+  data.tar.gz: 77b66fe00e50c047ed8314cf9c05cf713114368769b57d252ccd7f928bd243524359700ed2e607159f257b7b1f94083b5d34564c3a388b4399376980f5645a3d

data/Gemfile

@@ -3,4 +3,5 @@ source 'https://rubygems.org'
 gemspec
 
 # Comment out the following gem instructions, if you not using gem sources
-# gem 'mimi-core', path: '/mimi-core'
+gem 'mimi-core', path: '../mimi-core'
+

data/README.md

@@ -1,6 +1,6 @@
 # mimi-config
 
-A simple ENV based configuration for microservice applications.
+A simple ENV and manifest based configuration for microservice applications.
 
 
 ## Installation
@@ -23,64 +23,196 @@ Or install it yourself as:
 
 `Mimi::Config` allows you to define a set of configurable parameters and constants in a *manifest* file with a simple YAML format.
 
+When instantiated, a `Mimi::Config` object reads and parses the manifest found in the specified file,
+loads parameter values from ENV variables and processes them according to the manifest.
+
+On success, `Mimi::Config` object makes configurable parameters available as Hash keys
+or as methods:
+
+```yaml
+# manifest.yml
+param1:
+  default: "foobar"
+```
+
+```ruby
+require 'mimi/config'
+
+config = Mimi::Config.new('manifest.yml')
+config.param1 # => "foobar", if ENV['param1'] is not set
+```
+
+
+## Manifest
+
+A *manifest* is a formal declaration of accepted configurable parameters.
+Only the parameters defined in the manifest may be set.
+
+For each configurable parameter there may be declared:
+
+ * configurable parameter name
+ * human readable description of the parameter
+ * type of accepted values
+ * default value
+ * whether this parameter is constant or not
+
 ### Example manifest.yml
 ```yaml,name=manifest.yml
+# This is a minimal definition of a configurable parameter.
+# Its type is 'string', there is no human readable description and no default value:
+min1:
+
+# This parameter is optional as it has a default value.
 opt1:
   desc: This is an optional configurable parameter
-  default: 123
+  default: "opt1.default"
 
+# Having no defined default value makes the configurable parameter required
+req1:
+  desc: This is a required configurable parameter
+
+# An optional configurable parameter with a default value of 'nil':
 opt2:
-  desc: This is an optional configurable parameter with the default value of nil
   default:
 
+# A constant parameter of type 'string'.
+# It must have a default value and it cannot be changed via ENV variable.
 const1:
-  desc: This is a constant parameter, that cannot be changed via an ENV variable
-  const: 456
+  desc: This is a constant parameter
+  default: "const1.default"
+  const: true
+```
+
+### Configurable parameter types
 
+The type of configurable parameter defines which values/format it accepts from ENV,
+and the type it converts the processed value to.
 
-req1: This is a required configurable parameter
+```yaml
+# manifest_with_types.yml
 
-req2:
-  desc: And so is this one
+# 'string' accepts any value and converts to String
+str1:
+  type: string
 
-# And so is this one with no description
-req3:
+# 'integer' accepts any positive integer and converts to Integer
+int1:
+  type: integer
+
+# 'decimal' accepts a decimal number representation (integer or fractional) and converts to BigDecimal
+dec1:
+  type: decimal
+
+# 'boolean' accepts only String values 'true' and 'false',
+# and converts to Ruby literals 'true' or 'false'.
+bool1:
+  type: boolean
+
+# 'json' accepts a valid JSON and converts to a decoded object (of any type)
+json1:
+  type: json
+
+# 'enum' is a special type that accepts only values from a provided set of string literals.
+# Converts the value to String.
+enum1:
+  type:
+    - debug
+    - info
+    - warn
+    - error
 ```
 
+**Example:**
+
+```ruby
+require 'mimi/config'
+
+# Provided the ENV values are set as:
+ENV['str1'] # => "foobar"
+ENV['int1'] # => "123"
+ENV['dec1'] # => "1.23"
+ENV['bool1'] # => "true"
+ENV['json1'] # => "[{\"a\":1},{\"b\":2}]"
+ENV['enum1'] # => "info"
+
+config = Mimi::Config.new('manifest_with_types.yml')
+
+config.str1 # => "foobar" (String)
+config.int1 # => 123 (Integer)
+config.dec1 # => 1.23 (BigDecimal)
+config.bool1 # => true (TrueClass)
+config.json1 # => [{"a"=>1}, {"b"=>2}] (Array)
+config.enum1 # => "info" (String)
+```
+
+
 ### How to load configuration from your app
 
 Providing you have placed your manifest into `config/manifest.yml`:
 
+```yaml
+const1:
+  default: 456
+  const: true
+
+req1:
+
+opt1:
+  default: foobar
+
+opt2:
+  type: integer
+  default: 0
+```
+
 ```ruby
 config = Mimi::Config.new('config/manifest.yml')
 
 config.const1 # => 456, from manifest.yml
-config.opt1 # value from ENV['opt1'] or default from manifest.yml
+config.opt1 # value from ENV['opt1'] or default "foobar" from manifest.yml
 config.req2 # value from ENV['req2']
 
 # alternatively use [] syntax:
 config.opt2    #
-config[:opt2]  # all three refer to the same configurable parameter
-config['opt2'] #
+config[:opt2]  # refers to the same configurable parameter
 
 # you cannot access parameters not defined in the manifest:
-config.req5 # => NoMethodError
-config['req5'] # => ArgumentError
+config.foobar # => NoMethodError
+config[:foobar] # => ArgumentError
+
+# when using [] syntax, use Symbol as parameter name:
+config.opt2     # => 0, if ENV['opt2'] is not set
+config[:opt2]   # => 0, if ENV['opt2'] is not set
+config['opt2']  # => ArgumentError
 
 # check, if parameter is defined:
-config.include?('req5') # => false
+config.include?(:foobar) # => false
 ```
 
-## Development
+### Using with Dotenv
+
+When a `Mimi::Config` object is instantiated, the `.env` file is loaded and processed,
+the functionality provided by the `dotenv` gem.
+
+You can choose to disable `dotenv` and `.env` file loading:
+
+```ruby
+require 'mimi/config'
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+config = Mimi::Config.new('manifest.yml', config_use_dotenv: false)
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Using as Mimi component
 
-## Contributing
+It is possible to configure `Mimi::Config` as a Mimi module:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mimi-config. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+```ruby
+require 'mimi/config'
+
+Mimi.use Mimi::Config, config_use_dotenv: false
+```
 
+After that, any `Mimi::Config` object you instantiate will use provided options as default.
 
 ## License
 

data/lib/mimi/config/version.rb

@@ -1,5 +1,5 @@
 module Mimi
   class Config
-    VERSION = '0.1.1'.freeze
+    VERSION = '1.0.0'.freeze
   end # class Config
 end # module Mimi

data/lib/mimi/config.rb

@@ -22,10 +22,30 @@ module Mimi
     # Current set of values for configurable and const parameters
     attr_reader :params
 
-    default_options(
-      raise_on_missing_params: true,
-      use_dotenv: true
-    )
+    # Mimi::Config module manifest
+    #
+    def self.manifest
+      {
+        config_raise_on_missing_params: {
+          desc: 'Raise error on missing params',
+          default: true,
+          hidden: true
+        },
+        config_use_dotenv: {
+          desc: 'Use Dotenv and load .env file',
+          default: true,
+          hidden: true
+        }
+      }
+    end
+
+    # Returns the module path, for exported rake files
+    #
+    # @return [Pathname]
+    #
+    def self.module_path
+      Pathname.new(__dir__).join('..', '..').expand_path
+    end
 
     # Creates a Config object.
     #
@@ -37,7 +57,7 @@ module Mimi
     # @param manifest_filename [String,nil] path to the manifest.yml or nil to skip loading manifest
     #
     def initialize(manifest_filename = nil, opts = {})
-      @manifest = Mimi::Config::Manifest.new
+      @manifest = Mimi::Core::Manifest.new({})
       @params = {}
       load(manifest_filename, opts) if manifest_filename
     end
@@ -46,11 +66,11 @@ module Mimi
     # from ENV.
     #
     def load(manifest_filename, opts = {})
-      opts = self.class.module_options.deep_merge(opts)
+      opts = self.class.options.deep_merge(opts)
       manifest_filename = Pathname.new(manifest_filename).expand_path
-      load_manifest(manifest_filename, opts)
+      @manifest.merge!(self.class.load_manifest(manifest_filename, opts))
       load_params(opts)
-      if opts[:raise_on_missing_params] && !missing_params.empty?
+      if opts[:config_raise_on_missing_params] && !missing_params.empty?
         raise "Missing required configurable parameters: #{missing_params.join(', ')}"
       end
       self
@@ -63,23 +83,11 @@ module Mimi
       required_params - @params.keys
     end
 
-    # Returns annotated manifest
+    # Returns the underlying manifest
     #
-    def manifest
-      @manifest.map do |k, v|
-        {
-          name: k,
-          desc: v[:desc],
-          required: !v.key?(:default),
-          const: v[:const],
-          default: v[:default]
-        }
-      end
-    end
-
-    # Returns raw manifest
+    # @return [Mimi::Core::Manifest]
     #
-    def manifest_raw
+    def manifest
       @manifest
     end
 
@@ -89,26 +97,29 @@ module Mimi
     # via #[] and #<name> methods.
     #
     def include?(name)
-      @manifest.key?(name.to_sym)
+      @manifest.to_h.key?(name.to_sym)
     end
 
     # Returns the parameter value
     #
-    # @param key [String,Symbol] parameter name
+    # @param key [Symbol] parameter name
     #
     def [](key)
+      unless key.is_a?(Symbol)
+        raise ArgumentError, "Invalid key to #[], Symbol expected: '#{key.inspect}'"
+      end
       raise ArgumentError, "Undefined parameter '#{key}'" unless include?(key)
-      @params[key.to_sym]
+      @params[key]
     end
 
     # Provides access to parameters as methods.
     #
     # Example:
-    #   config['foo'] # => 'bar'
+    #   config[:foo] # => 'bar'
     #   config.foo # => 'bar'
     #
     #   # missing parameter
-    #   config['bar'] # => ArgumentError
+    #   config[:bar] # => ArgumentError
     #   config.bar # => NoMethodError
     #
     def method_missing(name, *)
@@ -126,46 +137,40 @@ module Mimi
     # @return [Hash]
     #
     def to_h
-      @manifest.keys.map do |k|
+      @manifest.to_h.keys.map do |k|
         [k, self[k]]
       end.to_h
     end
 
     # Returns to_h.to_s
     #
+    # @return [String]
+    #
     def to_s
       to_h.to_s
     end
 
-    private
-
-    # Reads manifest file and merges it with the current manifest.
+    # Reads and parses the manifest file and constructs the Mimi::Core::Manifest object
+    #
+    # @param filename [Pathname]
+    # @param _opts
+    # @return [Mimi::Core::Manifest]
     #
-    def load_manifest(filename, _opts = {})
-      @manifest.load(filename)
+    def self.load_manifest(filename, _opts = {})
+      Mimi::Core::Manifest.from_yaml(File.read(filename))
+    rescue StandardError => e
+      raise "Failed to load config manifest from '#{filename}': #{e}"
     end
 
+    private
+
     # Reads parameters from the ENV according to the current manifest
     #
     def load_params(opts = {})
-      Dotenv.load if opts[:use_dotenv]
-      manifest.each do |p|
-        env_name = p[:name].to_s
-        if p[:const]
-          # const
-          @params[p[:name]] = p[:default]
-        elsif p[:required]
-          # required configurable
-          @params[p[:name]] = ENV[env_name] if ENV.key?(env_name)
-        else
-          # optional configurable
-          @params[p[:name]] = ENV.key?(env_name) ? ENV[env_name] : p[:default]
-        end
-      end
-      @params
+      Dotenv.load if opts[:config_use_dotenv]
+      @params = @manifest.apply(ENV.to_h.symbolize_keys)
     end
   end # class Config
 end # module Mimi
 
 require_relative 'config/version'
-require_relative 'config/manifest'

data/lib/tasks/config.rake

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Returns the path to the manifest file
+#
+# @return [Pathname]
+#
+def rake_task_config_manifest_filename
+  Mimi.app_path_to('config', 'manifest.yml')
+end
+
+# Displays current manifest and configured values in .env format
+#
+# @param include_consts [true,false] include non-configurable parameters (consts)
+#
+def rake_task_config(include_consts = false)
+  manifest = Mimi::Config.load_manifest(rake_task_config_manifest_filename)
+  missing_params = manifest.keys.select { |k| manifest.required?(k) }.reject { |k| ENV.key?(k.to_s) }
+
+  manifest.to_h.each do |name, props|
+    next if props[:const] && !include_consts
+    annotation = []
+    if props[:const]
+      annotation << '[CONST]'
+      annotation << "(value: #{props[:default].inspect})"
+    elsif missing_params.include?(name)
+      annotation << "[MISSING] (#{props[:type]})"
+    else
+      annotation << "(#{props[:type]}, default: #{props[:default].inspect})"
+    end
+    annotation << props[:desc] if props.key?(:desc)
+    annotation.unshift('  #') unless annotation.empty?
+    puts "#{name}=#{ENV[name.to_s]}#{annotation.join(' ')}"
+  end
+  abort('# FIXME: configure missing parameters') unless missing_params.empty?
+end
+
+# Generates a new/updated config manifest
+#
+# @return [String] a config manifest in the YAML format
+#
+def rake_task_config_manifest_generate
+  manifest = Mimi::Core::Manifest.new({})
+
+  # merge loaded modules manifests
+  Mimi.loaded_modules.map(&:manifest).each do |manifest_hash|
+    manifest.merge!(manifest_hash)
+  end
+
+  # merge app's explicit manifest
+  app_manifest = Mimi::Config.load_manifest(rake_task_config_manifest_filename)
+  manifest.merge!(app_manifest)
+
+  manifest.to_yaml
+end
+
+desc 'Display config manifest and current config'
+task :config do
+  rake_task_config(false)
+end
+
+namespace :config do
+  desc 'Display config manifest and current config, including consts'
+  task :all do
+    rake_task_config(true)
+  end
+
+  desc 'Generate and display a combined manifest for all loaded modules'
+  task :manifest do
+    puts rake_task_config_manifest_generate
+  end
+
+  namespace :manifest do
+    manifest_filename = Pathname.pwd.join('config', 'manifest.yml')
+    desc "Generate and write a combined manifest to: #{manifest_filename}"
+    task :create do
+      if File.exist?(manifest_filename)
+        puts "* Found an existing application manifest, loading: #{manifest_filename}"
+      end
+      puts '* Generating a combined manifest'
+      manifest_contents = rake_task_config_manifest_generate
+      config_path = Mimi.app_path_to('config')
+      puts "* Writing the combined manifest to: #{manifest_filename}"
+      sh "install -d #{config_path}" unless File.directory?(config_path)
+      File.open(rake_task_config_manifest_filename, 'w') do |f|
+        f.puts manifest_contents
+      end
+    end
+  end
+end

data/mimi-config.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'mimi-core', '~> 0.1'
+  spec.add_dependency 'mimi-core', '~> 1.0'
   spec.add_dependency 'dotenv', '~> 2.1'
 
   spec.add_development_dependency 'bundler', '~> 1.11'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mimi-config
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Alex Kukushkin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-09 00:00:00.000000000 Z
+date: 2019-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mimi-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -112,8 +112,8 @@ files:
 - bin/console
 - bin/setup
 - lib/mimi/config.rb
-- lib/mimi/config/manifest.rb
 - lib/mimi/config/version.rb
+- lib/tasks/config.rake
 - mimi-config.gemspec
 homepage: https://github.com/kukushkin/mimi-config
 licenses:
@@ -136,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.6.14.4
 signing_key: 
 specification_version: 4
 summary: Simple ENV based configuration for microservice apps

data/lib/mimi/config/manifest.rb

@@ -1,86 +0,0 @@
-module Mimi
-  class Config
-    class Manifest < Hash
-      # Reads manifest file and merges it with the current manifest.
-      #
-      # @return [Mimi::Config::Manifest] current manifest merged with the new one
-      #
-      def load(filename_or_hash, _opts = {})
-        new_manifest = nil
-        if filename_or_hash.is_a?(String) || filename_or_hash.is_a?(Pathname)
-          new_manifest = YAML.load(File.read(filename_or_hash))
-        end
-        new_manifest = filename_or_hash.dup if filename_or_hash.is_a?(Hash)
-        return self unless new_manifest
-        raise 'Invalid manifest file format' unless new_manifest.is_a?(Hash)
-        new_manifest.each do |k, v|
-          merge_key(k, v)
-        end
-        self
-      rescue StandardError => e
-        raise "Failed to load manifest file: #{e}"
-      end
-
-      # Returns YAML representation of the manifest
-      #
-      # @return [String]
-      #
-      def to_yaml
-        out = []
-        self.each do |k, v|
-          if v.key?(:const)
-            out << "#{k}:"
-            out << "  desc: #{value_to_yaml(v[:desc])}" if v.key?(:desc)
-            if v[:const]
-              out << "  const: #{value_to_yaml(v[:default])}"
-            elsif v.key?(:default)
-              out << "  default: #{value_to_yaml(v[:default])}"
-            end
-          elsif v.key?(:desc)
-            out << "#{k}: #{value_to_yaml(v[:desc])}"
-          else
-            out << "#{k}:"
-          end
-          out << ''
-        end
-        out.join("\n")
-      end
-
-      private
-
-      def value_to_yaml(v)
-        v.nil? ? '# nil' : v.inspect
-      end
-
-      def merge_key(k, v)
-        k = k.to_sym
-        self[k] ||= {}
-        if v.nil?
-          # var:
-        elsif v.is_a?(String)
-          # var: A description
-          self[k][:desc] = v
-        elsif v.is_a?(Hash)
-          merge_key_hash(k, v)
-        end
-      end
-
-      def merge_key_hash(k, v)
-        v = v.dup.stringify_keys
-        self[k][:desc] = v['desc'] if v.key?('desc')
-
-        if v.key?('const') && v.key?('default')
-          raise "Invalid mix of 'const' and 'default' in parameter definition '#{k}'"
-        end
-
-        if v.key?('default')
-          self[k][:const] = false
-          self[k][:default] = v['default']
-        elsif v.key?('const')
-          self[k][:const] = true
-          self[k][:default] = v['const']
-        end
-      end
-    end # class Manifest
-  end # class Config
-end # module Mimi