blueprint_config 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e1b4cd0cf2aeb8bb83afa7545fd6aca21c103f7902edf56567d0d1bab7fc596
-  data.tar.gz: a8dcc907c8c5ee3a5cb3073d41accb0b40bf2fa21006af15fceef3ab2e0bb065
+  metadata.gz: c1f80d9fbe572d7bbbef333547cb8423732f6ec75765be47e31bcefe3a0a3c0e
+  data.tar.gz: 179b6bed1dbc51c9521ec5c6d1ff0951f0d6f5bc1b1436216e0436c1b3b2e86b
 SHA512:
-  metadata.gz: 65a35dc0a72caf730aca234e27a24b3f532571fb70480ae12b6ff39d541325d7ab246c43341ead9716a0c5629fafb8695aebbabaae4ce953e8cc4313118d2a6b
-  data.tar.gz: 6eadf4f45fcb8a9aa1e2dd88f868314469e28d360e4f8014de4fb23f83af3208f20f739a23bde87ab8d6f18bf4437e39e5bb53957d3075cf4949bbf091a4e148
+  metadata.gz: bcbe5013a6e6217df4c358a4abbb9ec26fc1f476ffdcff23acad47d06733a99096f3b1bcf6cb114eee06384428a16406a8b188e2c9b2c5992cccfa4e13a55a34
+  data.tar.gz: 30bf9fd227b7f6137adc0b66d92d81ed2cec697754995515b96cea57230072f9c00b72074cbfc1b10e72adc5514446824b25068addab9d1da51923228292fff7

data/.idea/blue_config.iml

@@ -69,4 +69,37 @@
       </RakeTaskImpl>
     </option>
   </component>
+  <component name="RakeTasksCache-v2">
+    <option name="myRootTask">
+      <RakeTaskImpl id="rake">
+        <subtasks>
+          <RakeTaskImpl description="Build blueprint_config-1.4.0.gem into the pkg directory" fullCommand="build" id="build" />
+          <RakeTaskImpl id="build">
+            <subtasks>
+              <RakeTaskImpl description="Generate SHA512 checksum if blueprint_config-1.4.0.gem into the checksums directory" fullCommand="build:checksum" id="checksum" />
+            </subtasks>
+          </RakeTaskImpl>
+          <RakeTaskImpl description="Remove any temporary products" fullCommand="clean" id="clean" />
+          <RakeTaskImpl description="Remove any generated files" fullCommand="clobber" id="clobber" />
+          <RakeTaskImpl description="Build and install blueprint_config-1.4.0.gem into system gems" fullCommand="install" id="install" />
+          <RakeTaskImpl id="install">
+            <subtasks>
+              <RakeTaskImpl description="Build and install blueprint_config-1.4.0.gem into system gems without network access" fullCommand="install:local" id="local" />
+            </subtasks>
+          </RakeTaskImpl>
+          <RakeTaskImpl description="Create tag v1.4.0 and build and push blueprint_config-1.4.0.gem to rubygems.org" fullCommand="release[remote]" id="release[remote]" />
+          <RakeTaskImpl description="Run RSpec code examples" fullCommand="spec" id="spec" />
+          <RakeTaskImpl description="" fullCommand="default" id="default" />
+          <RakeTaskImpl description="" fullCommand="release" id="release" />
+          <RakeTaskImpl id="release">
+            <subtasks>
+              <RakeTaskImpl description="" fullCommand="release:guard_clean" id="guard_clean" />
+              <RakeTaskImpl description="" fullCommand="release:rubygem_push" id="rubygem_push" />
+              <RakeTaskImpl description="" fullCommand="release:source_control_push" id="source_control_push" />
+            </subtasks>
+          </RakeTaskImpl>
+        </subtasks>
+      </RakeTaskImpl>
+    </option>
+  </component>
 </module>

data/README.md

@@ -33,12 +33,135 @@ and load configuration in following order:
 - settings in database
 - config/app.local.yml
 
-Settings form database will be available only after rails app initialization.
+Settings from database will be available only after rails app initialization.
 Everything else can be used in initializers.
 
-## Accessing configuration variables.
+## Rails Credentials Handling
 
-You can access configuration variables in any of followining ways:
+BlueprintConfig integrates with Rails credentials system. When Rails is available, it uses `Rails.application.credentials` which automatically handles both global and environment-specific credentials.
+
+### Environment-Specific Credentials (Rails 6+)
+
+Rails 6+ supports environment-specific credentials that are automatically merged:
+- Global: `config/credentials.yml.enc` (with `config/master.key`)
+- Environment-specific: `config/credentials/[environment].yml.enc` (with `config/credentials/[environment].key`)
+
+Example structure:
+```
+config/
+├── credentials.yml.enc              # Global credentials
+├── master.key                       # Global key (not committed)
+└── credentials/
+    ├── development.yml.enc          # Development-only credentials
+    ├── development.key              # Development key (not committed)
+    ├── production.yml.enc           # Production-only credentials
+    └── production.key               # Production key (not committed)
+```
+
+When both exist, Rails merges them with environment-specific values taking precedence. BlueprintConfig automatically receives the merged result through `Rails.application.credentials`.
+
+Example:
+```ruby
+# In config/credentials.yml.enc (global):
+aws:
+  region: us-east-1
+  bucket: myapp
+
+# In config/credentials/production.yml.enc:
+aws:
+  access_key_id: PROD_KEY_123
+  secret_access_key: PROD_SECRET_456
+
+# Result in production:
+AppConfig.aws.region              # => "us-east-1" (from global)
+AppConfig.aws.bucket              # => "myapp" (from global)
+AppConfig.aws.access_key_id       # => "PROD_KEY_123" (from production)
+AppConfig.aws.secret_access_key   # => "PROD_SECRET_456" (from production)
+```
+
+## Configuration Recommendations
+
+### Where to Put Your Settings
+
+Different types of configuration should be stored in different places based on their nature:
+
+#### 1. **Credentials** → Use Rails Credentials
+Sensitive data like API keys, passwords, and tokens:
+```yaml
+# config/credentials.yml.enc
+stripe:
+  secret_key: sk_live_xxxxx
+  webhook_secret: whsec_xxxxx
+database:
+  password: super_secret_password
+external_api:
+  token: bearer_token_xxxxx
+```
+
+#### 2. **Application Configuration** → Use `config/app.yml`
+Rarely changed settings that configure application behavior:
+```yaml
+# config/app.yml
+smtp:
+  server: smtp.example.com
+  port: 587
+  domain: example.com
+app:
+  host: app.example.com
+  name: My Application
+  support_email: support@example.com
+features:
+  signup_enabled: true
+  maintenance_mode: false
+```
+
+#### 3. **Dynamic Settings** → Use Database
+Settings that need to change without redeployment:
+```ruby
+# Stored in settings table, managed via admin interface
+BlueprintConfig::Setting.create(key: 'feature_flags.new_ui', value: 'true')
+BlueprintConfig::Setting.create(key: 'rate_limits.api_calls', value: '1000')
+BlueprintConfig::Setting.create(key: 'maintenance.message', value: 'Back at 3pm')
+```
+
+> **Automatic Reloading**: Database settings are automatically reloaded when changed. The system checks for updates every second and refreshes configuration if database records are newer than the cached values. This means changes take effect immediately without restarting the application.
+
+#### 4. **Local Overrides** → Use `config/app.local.yml`
+Development-specific overrides (never commit this file):
+```yaml
+# config/app.local.yml
+smtp:
+  server: localhost
+  port: 1025  # Local MailCatcher
+app:
+  host: localhost:3000
+debug:
+  verbose_logging: true
+```
+
+### Configuration Precedence
+
+Settings are loaded in this order (later sources override earlier ones):
+1. `config/app.yml` - Base configuration
+2. Rails credentials - Secure/sensitive data
+3. ENV variables - Deployment-specific overrides
+4. Database settings - Runtime-configurable values
+5. `config/app.local.yml` - Local development overrides
+
+## Accessing Configuration Variables
+
+The recommended access style is using dot notation (member access syntax):
+
+```ruby
+# Recommended approach
+AppConfig.action_mailer.smtp_settings.address
+AppConfig.stripe.secret_key
+AppConfig.features.signup_enabled
+
+# This provides clean, readable code that mirrors your configuration structure
+```
+
+You can access configuration variables in any of following ways:
 
 ### Member access syntax:
 
@@ -58,7 +181,7 @@ AppConfig.some.var
               ^^^^
 ```
 
-If nil is suitable as a default value tyou can use safe navigation operator
+If nil is suitable as a default value you can use safe navigation operator
 
 ```ruby
 irb(main):001> AppConfig.some&.var
@@ -68,7 +191,7 @@ irb(main):001> AppConfig.some&.var
 
 
 
-Optionaly you use bang methods to allways raise exception when variable is not defined
+Optionally you can use bang methods to always raise exception when variable is not defined
 
 ```ruby
 irb(main):001> AppConfig.some
@@ -88,7 +211,7 @@ irb(main):002> AppConfig.host?
 => true
 ```
 
-Note: Because question mark methods return Boolean you cannot chain em.
+Note: Because question mark methods return Boolean you cannot chain them.
 
 ### Hash access syntax
 You can use both symbols or strings as keys
@@ -128,7 +251,7 @@ irb(main):004> AppConfig.fetch(:var){123}
 
 ### Dig
 
-Dig permits to sefely get value in nested structures (including arrays)
+Dig permits to safely get value in nested structures (including arrays)
 
 ```ruby
 irb(main):001> AppConfig.dig(:action_mailer, :smtp_settings, :address)
@@ -146,6 +269,279 @@ irb(main):002> AppConfig.dig!(:action, :smtp_settings, :address)
 
 Whenever possible exception message specifies which key is missing.
 
+## Testing with Memory Backend
+
+In test environments, BlueprintConfig automatically includes a memory backend that allows you to temporarily set configuration values for testing purposes. The memory backend has the highest priority and will override all other configuration sources.
+
+### Setting Values in Tests
+
+You can use `AppConfig.set` to temporarily override configuration values:
+
+```ruby
+# Set a single value
+AppConfig.set('smtp.server', 'test.localhost')
+
+# Set multiple values with a hash
+AppConfig.set(
+  smtp: {
+    server: 'localhost',
+    port: 1025
+  },
+  features: {
+    new_ui: true
+  }
+)
+
+# Set deeply nested values
+AppConfig.set('app.mail.settings', { 
+  from: 'test@example.com',
+  reply_to: 'noreply@example.com'
+})
+```
+
+### RSpec Usage Pattern
+
+```ruby
+RSpec.describe 'MyFeature' do
+  context 'with feature enabled' do
+    before do
+      AppConfig.set('features.new_ui', true)
+    end
+
+    after do
+      AppConfig.clear_memory!
+    end
+
+    it 'behaves differently' do
+      expect(AppConfig.features.new_ui).to be true
+      # test your feature
+    end
+  end
+end
+```
+
+### Shared Examples and Contexts
+
+```ruby
+RSpec.shared_context 'with premium features' do
+  before do
+    AppConfig.set(
+      features: {
+        premium: true,
+        advanced_analytics: true,
+        api_limit: 10000
+      }
+    )
+  end
+
+  after do
+    AppConfig.clear_memory!
+  end
+end
+
+# Use in your specs
+RSpec.describe PremiumService do
+  include_context 'with premium features'
+  
+  it 'allows advanced operations' do
+    expect(AppConfig.features.premium).to be true
+    # test premium functionality
+  end
+end
+```
+
+### Clearing Memory
+
+Use `AppConfig.clear_memory!` to clear all memory-stored values:
+
+```ruby
+# In RSpec configuration
+RSpec.configure do |config|
+  config.after(:each) do
+    AppConfig.clear_memory! if defined?(AppConfig)
+  end
+end
+
+# Or manually in specific tests
+AppConfig.clear_memory!
+```
+
+### Important Notes
+
+1. The memory backend is only available in test environment (`Rails.env.test?`)
+2. Memory values have the highest priority and override all other sources
+3. Values are stored in memory only and are not persisted
+4. Remember to clear memory between tests to avoid test pollution
+5. The `set` method will raise an error if used outside test environment
+
+## Debugging and Inspection
+
+### Viewing Configuration Sources
+
+BlueprintConfig tracks where each configuration value comes from. You can use the `source` method to see which backend provided a specific value:
+
+```ruby
+# Get the source of a specific configuration value
+AppConfig.config.source(:smtp, :server)
+# => "BlueprintConfig::Backend::YAML(config/app.yml) smtp.server"
+
+AppConfig.config.source(:database, :password)
+# => "BlueprintConfig::Backend::Credentials(global + production) database.password"
+
+# In test environment with memory backend
+AppConfig.set('feature.enabled', true)
+AppConfig.config.source(:feature, :enabled)
+# => "BlueprintConfig::Backend::Memory feature.enabled"
+
+# For environment variables with specific configuration
+AppConfig.config.source(:api, :key)
+# => "BlueprintConfig::Backend::ENV(whitelist_prefixes: API_, APP_) api.key"
+
+# For local overrides
+AppConfig.config.source(:debug, :verbose)
+# => "BlueprintConfig::Backend::YAML(config/app.local.yml) debug.verbose"
+
+# For database settings
+AppConfig.config.source(:rate_limit, :max_requests)
+# => "BlueprintConfig::Backend::ActiveRecord(settings table) rate_limit.max_requests"
+```
+
+### Inspecting All Configuration
+
+To view all configuration values as a hash:
+
+```ruby
+# Get all configuration as a Ruby hash
+AppConfig.to_h
+# or
+AppConfig.config.to_h
+# => {
+#   smtp: {
+#     server: "smtp.gmail.com",
+#     port: 587,
+#     domain: "example.com"
+#   },
+#   database: {
+#     pool: 5,
+#     timeout: 5000
+#   },
+#   features: {
+#     signup_enabled: true,
+#     beta_features: false
+#   }
+# }
+
+# Pretty print configuration in console
+require 'pp'
+pp AppConfig.to_h
+
+# Convert to YAML for easier reading
+require 'yaml'
+puts AppConfig.to_h.to_yaml
+# ---
+# :smtp:
+#   :server: smtp.gmail.com
+#   :port: 587
+#   :domain: example.com
+# :database:
+#   :pool: 5
+#   :timeout: 5000
+# :features:
+#   :signup_enabled: true
+#   :beta_features: false
+```
+
+### Viewing Configuration with Sources
+
+To see both values and their sources:
+
+```ruby
+# Get configuration with source information
+AppConfig.with_sources
+# or
+AppConfig.config.with_sources
+# => {
+#   smtp: {
+#     server: {
+#       value: "smtp.gmail.com",
+#       source: "BlueprintConfig::Backend::YAML(config/app.yml)"
+#     },
+#     port: {
+#       value: 587,
+#       source: "BlueprintConfig::Backend::YAML(config/app.yml)"
+#     },
+#     username: {
+#       value: "user@example.com",
+#       source: "BlueprintConfig::Backend::Credentials(production)"
+#     }
+#   },
+#   features: {
+#     beta_enabled: {
+#       value: true,
+#       source: "BlueprintConfig::Backend::Memory"
+#     }
+#   },
+#   debug: {
+#     verbose: {
+#       value: true,
+#       source: "BlueprintConfig::Backend::YAML(config/app.local.yml)"
+#     }
+#   }
+# }
+
+# Pretty print with sources
+require 'pp'
+pp AppConfig.config.with_sources
+
+# Convert to YAML for easier reading
+require 'yaml'
+puts AppConfig.config.with_sources.to_yaml
+```
+
+### Checking Available Backends
+
+To see which backends are currently loaded:
+
+```ruby
+# List all backends with their configuration
+AppConfig.backends.each do |backend|
+  puts backend.source
+end
+# Output:
+# BlueprintConfig::Backend::YAML(config/app.yml)
+# BlueprintConfig::Backend::Credentials(global + production)
+# BlueprintConfig::Backend::ENV(whitelist_prefixes: API_, APP_)
+# BlueprintConfig::Backend::ActiveRecord(settings table)
+# BlueprintConfig::Backend::YAML(config/app.local.yml)
+# BlueprintConfig::Backend::Memory
+
+# Check specific backend
+AppConfig.backends[:memory]  # => BlueprintConfig::Backend::Memory instance or nil
+AppConfig.backends[:app]     # => BlueprintConfig::Backend::YAML instance
+```
+
+### Configuration Load Order
+
+The default configuration load order (later sources override earlier ones):
+
+1. `app` - YAML file (config/app.yml)
+2. `credentials` - Rails credentials
+3. `env` - Environment variables
+4. `db` - Database settings (after Rails initialization)
+5. `app_local` - Local YAML overrides (config/app.local.yml)
+6. `memory` - Test-only memory backend (highest priority in test environment)
+
+### Source Tracking Details
+
+BlueprintConfig provides detailed source information for debugging:
+
+- **YAML files**: Shows the file path (e.g., `config/app.yml`)
+- **Credentials**: Shows whether using global only or merged with environment-specific (e.g., `global + production`)
+- **Environment variables**: Shows any whitelist configuration
+- **Database**: Indicates if connected to settings table
+- **Memory**: Simple indicator for test values
+
+Note: While YAML line numbers are not currently tracked, the file path information helps identify which YAML file contains specific values. For credentials, Rails automatically merges global and environment-specific files, and the source indicates which files are in use.
 
 ## License
 

data/lib/blueprint_config/backend/active_record.rb

@@ -114,6 +114,14 @@ module BlueprintConfig
 
         @updated_at.present? && @updated_at >= max_updated_at
       end
+
+      def source
+        if @configured && table_exist?
+          "#{self.class.name}(settings table)"
+        else
+          "#{self.class.name}(not available)"
+        end
+      end
     end
   end
 end

data/lib/blueprint_config/backend/credentials.rb

@@ -6,21 +6,40 @@ module BlueprintConfig
   module Backend
     class Credentials < Base
       def load_keys
-        credentials.to_h
+        if defined?(Rails)
+          # When Rails is available, use Rails.application.credentials
+          # Rails already handles merging global and environment-specific credentials
+          Rails.application.credentials.to_h
+        else
+          # Standalone mode - just load global credentials
+          standalone_credentials.to_h
+        end
       end
 
-      def credentials
-        if defined?(Rails)
-          Rails.application.credentials
+      def source
+        if defined?(Rails) && Rails.env
+          # Check if environment-specific credentials exist
+          env_path = "config/credentials/#{Rails.env}.yml.enc"
+          if File.exist?(env_path)
+            "#{self.class.name}(global + #{Rails.env})"
+          else
+            "#{self.class.name}(global)"
+          end
         else
-          ActiveSupport::EncryptedConfiguration.new(
-            config_path: 'config/credentials.yml.enc',
-            key_path: 'config/master.key',
-            env_key: 'RAILS_MASTER_KEY',
-            raise_if_missing_key: false
-          )
+          "#{self.class.name}"
         end
       end
+
+      private
+
+      def standalone_credentials
+        ActiveSupport::EncryptedConfiguration.new(
+          config_path: 'config/credentials.yml.enc',
+          key_path: 'config/master.key',
+          env_key: 'RAILS_MASTER_KEY',
+          raise_if_missing_key: false
+        )
+      end
     end
   end
 end

data/lib/blueprint_config/backend/env.rb

@@ -42,6 +42,18 @@ module BlueprintConfig
 
         nest_hash(filtered_env, @options[:nest_separator] || '_')
       end
+
+      def source
+        details = []
+        details << "whitelist_keys: #{@options[:whitelist_keys].join(', ')}" if @options[:whitelist_keys]
+        details << "whitelist_prefixes: #{@options[:whitelist_prefixes].join(', ')}" if @options[:whitelist_prefixes]
+        
+        if details.any?
+          "#{self.class.name}(#{details.join(', ')})"
+        else
+          self.class.name
+        end
+      end
     end
   end
 end

data/lib/blueprint_config/backend/memory.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module BlueprintConfig
+  module Backend
+    class Memory < Base
+      def initialize
+        super
+        @store = {}
+      end
+
+      def load_keys
+        # Return the flattened store which will be nested by BlueprintConfig
+        nest_hash(@store, '.')
+      end
+
+      def set(key, value)
+        if value.is_a?(Hash)
+          # Handle nested hashes - store them properly for nested access
+          nested_hash = flatten_hash(value, key.to_s)
+          @store.merge!(nested_hash)
+        else
+          @store[key.to_s] = value
+        end
+      end
+
+      def clear
+        @store.clear
+      end
+
+      def fresh?
+        true
+      end
+
+      private
+
+      def flatten_hash(hash, parent_key = '')
+        result = {}
+        hash.each do |k, v|
+          new_key = parent_key.empty? ? k.to_s : "#{parent_key}.#{k}"
+          if v.is_a?(Hash)
+            result.merge!(flatten_hash(v, new_key))
+          else
+            result[new_key] = v
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/blueprint_config/backend/yaml.rb

@@ -20,6 +20,10 @@ module BlueprintConfig
         end
       end
 
+      def source
+        "#{self.class.name}(#{@path})"
+      end
+
       private
 
       def path

data/lib/blueprint_config/configuration.rb

@@ -60,5 +60,38 @@ module BlueprintConfig
         object
       end
     end
+
+    def set(key, value = nil)
+      memory_backend = @backends[:memory]
+      raise "Memory backend not configured. Only available in test environment." unless memory_backend
+
+      if key.is_a?(Hash)
+        # Handle hash argument: AppConfig.set(foo: { bar: 'baz' })
+        key.each do |k, v|
+          set(k.to_s, v)
+        end
+      else
+        memory_backend.set(key.to_s, value)
+      end
+      reload!
+    end
+
+    def clear_memory!
+      memory_backend = @backends[:memory]
+      return unless memory_backend
+
+      memory_backend.clear
+      reload!
+    end
+
+    def to_h
+      reload! unless backends&.fresh?
+      config.to_h
+    end
+
+    def with_sources
+      reload! unless backends&.fresh?
+      config.with_sources
+    end
   end
 end