HatiConfig

A Ruby approach to configuration management, inspired by real-world challenges in distributed systems. This gem explores practical solutions for teams dealing with configuration complexity at scale.

• Simple Configuration Management: Easily define, set, and retrieve configuration options.
• Type Validation: Ensure configurations are correct with built-in type validation.
• Multiple Formats: Import and export configurations in JSON, YAML, and Hash formats.
• Nested Configurations: Support for infinite nested configurations for complex applications.
• Classy Access: Access configurations in a 'classy' manner for better organization and readability.
• Built-in Types: Utilize various built-in types including basic types, data structures, numeric types, and time types.
• Extensible: Easily extendable to accommodate custom configuration needs.

• Overview & Configuration Patterns
• Installation
• Basic Usage
• Configuration Container Usage
• Define with DSL Syntax
• Distributed Features
  • Remote Configuration
  • Environment Management
  • Team Isolation
  • Schema Versioning
  • Caching and Refresh
  • Encryption
• Typing
  • Configure Type Validation
  • Define Configuration Type Validation
  • Type Schema
  • Built-in Types
• Import/Export:
  • Loading Configurations
  • Loading from Remote Sources
  • Loading from a JSON String
  • Loading from a YAML File
  • Exporting Configurations
  • to_h
  • to_json
  • to_yaml
• Security
  • Encryption
  • Encryption Key Providers
  • Security Features
• OSS
  • Development
  • Contributing
  • License
  • Code of Conduct

• Fixed: Encryption functionality now works correctly with the config(key, value: "secret", encrypted: true) syntax
• Enhanced: Improved encryption handling for both inline and hash-based configuration syntax
• Improved: Better error handling and type validation for encrypted values
• Updated: Comprehensive encryption documentation with practical examples

Install the gem and add to the application's Gemfile by executing:

bundle add hati-config

If bundler is not being used to manage dependencies, install the gem by executing:

gem install hati-config

Use Case: You're building a Ruby application that needs clean, type-safe configuration management. You want to avoid scattered constants, magic strings, and configuration bugs that crash production. You need nested configs, type validation, and the ability to export configs for debugging.

Why existing tools fall short:

• Plain Ruby constants are global and can't be nested cleanly
• YAML files lack type safety and runtime validation
• Environment variables become unwieldy with complex nested configs
• No built-in export/import capabilities for debugging and testing

HatiConfig solution: Clean DSL for defining configs with automatic type validation, nested namespaces, and built-in serialization.

require 'hati_config'

module MyApp
  extend HatiConfig
end

MyApp.configure :settings do
  config option: 42
  config.int typed_opt_one: 42
  config typed_opt_two: 4.2, type: :float
end

MyApp.settings.option                 # => 42
MyApp.settings.typed_opt_one          # => 42
MyApp.settings.typed_opt_two          # => 4.2

require 'hati_config'

# Set up encryption key
ENV['HATI_CONFIG_ENCRYPTION_KEY'] = '0' * 32  # 256-bit key

# Create a setting instance with encryption
settings = HatiConfig::Setting.new

# Configure encryption
settings.class.encryption do
  key_provider :env
end

# Configure encrypted and plain values
settings.config :api_key, value: "secret-key", encrypted: true
settings.config :public_url, value: "https://api.example.com"

settings[:api_key]     # => "secret-key" (automatically decrypted)
settings[:public_url]  # => "https://api.example.com" (plain text)

MyApp.configure :settings do
  config option: 42
end

MyApp.configure :app do
  configure :lvl_one do
    config opt: 100
    configure :lvl_two do
      config opt: 200
      configure :lvl_three do
        config opt: 300
        configure :lvl_four do
          config opt: 400
          configure :lvl_five do
            config opt: 500
            # NOTE: as deep as you want
          end
        end
      end
    end
  end
end

MyApp.app.lvl_one.opt                                     # => 100
MyApp.app.lvl_one.lvl_two.opt                             # => 200
MyApp.app.lvl_one.lvl_two.lvl_three.opt                   # => 300
MyApp.app.lvl_one.lvl_two.lvl_three.lvl_four.opt          # => 400
MyApp.app.lvl_one.lvl_two.lvl_three.lvl_four.lvl_five.opt # => 500

MyApp.configure :settings do
  config custom_typed_opt_one: '42', type: :float
end
# => HatiConfig::SettingTypeError

Use Case: You're running a microservices architecture with 50+ services across multiple regions. Each service needs to know database endpoints, API keys, and feature flags that change frequently. Traditional config files mean redeploying every service when anything changes, causing downtime and deployment bottlenecks.

Why existing tools fall short:

• Environment variables become unmanageable with hundreds of configs
• Config files require application restarts and deployments
• Tools like Consul require additional infrastructure and learning curve
• Most solutions don't handle automatic refresh or fallback gracefully

HatiConfig solution: Load configurations from HTTP endpoints, S3, or Redis with automatic refresh, caching, and fallback. Update configs without touching code or deployments.

HatiConfig supports loading configurations from various remote sources:

require 'hati_config'

module MyApp
  extend HatiConfig

  # Load from HTTP endpoint
  configure :api_settings, http: {
    url: 'https://config-server/api-config.json',
    headers: { 'Authorization' => 'Bearer token' },
    refresh_interval: 300  # refresh every 5 minutes
  }

  # Load from S3
  configure :database_settings, s3: {
    bucket: 'my-configs',
    key: 'database.yml',
    region: 'us-west-2',
    refresh_interval: 600
  }

  # Load from Redis
  configure :feature_flags, redis: {
    host: 'redis.example.com',
    key: 'feature_flags',
    refresh_interval: 60
  }
end

Use Case: Your application runs across development, staging, production, and multiple regional production environments. Each environment needs different database URLs, API endpoints, timeout values, and feature flags. Developers accidentally use production configs in development, or staging configs leak into production, causing outages.

Why existing tools fall short:

• Rails environments are limited and don't handle complex multi-region setups
• Multiple config files lead to duplication and inconsistency
• No validation that the right configs are loaded in the right environment
• Switching between environments requires manual file changes or complex deployment scripts

HatiConfig solution: Define base configurations with environment-specific overrides. Built-in environment detection with validation ensures the right configs are always loaded.

Easily manage configurations across different environments:

module MyApp
  extend HatiConfig

  configure :settings do
    # Base configuration
    config :timeout, default: 30
    config :retries, default: 3

    # Environment-specific overrides
    environment :development do
      config :api_url, value: 'http://localhost:3000'
      config :debug, value: true
    end

    environment :staging do
      config :api_url, value: 'https://staging-api.example.com'
      config :timeout, value: 60
    end

    environment :production do
      config :api_url, value: 'https://api.example.com'
      config :timeout, value: 15
      config :retries, value: 5
    end
  end
end

Use Case: You work at a large tech company with 10+ engineering teams (Frontend, Backend, Mobile, DevOps, ML, etc.). Each team has their own configurations, but they all deploy to shared infrastructure. Teams accidentally override each other's configs, causing mysterious production issues that take hours to debug.

Why existing tools fall short:

• Shared config files create merge conflicts and accidental overwrites
• Namespace collisions are common (multiple teams using "database_url")
• No clear ownership or boundaries for configuration sections
• Changes by one team can break another team's services

HatiConfig solution: Create isolated namespaces for each team. Teams can safely manage their own configs without affecting others, while still sharing common infrastructure settings.

Prevent configuration conflicts between teams:

module MyApp
  extend HatiConfig

  # Team-specific configuration namespace
  team :frontend do
    configure :settings do
      config :api_endpoint, value: '/api/v1'
      config :cache_ttl, value: 300
    end
  end

  team :backend do
    configure :settings do
      config :database_pool, value: 5
      config :worker_threads, value: 10
    end
  end

  team :mobile do
    configure :settings do
      config :push_notifications, value: true
      config :offline_mode, value: true
    end
  end
end

# Access team configurations
MyApp.frontend.settings.api_endpoint  # => '/api/v1'
MyApp.backend.settings.database_pool  # => 5
MyApp.mobile.settings.offline_mode    # => true

Use Case: Your application has evolved over 2 years. The original config had simple database settings, but now includes complex microservice endpoints, ML model parameters, and feature flags. Old configs are incompatible with new code, but you need to support gradual rollouts and rollbacks without breaking existing deployments.

Why existing tools fall short:

• No versioning means breaking changes crash old application versions
• Manual migration scripts are error-prone and forgotten
• No way to validate that configs match the expected schema
• Rolling back code requires manually reverting config changes

HatiConfig solution: Version your configuration schemas with automatic migrations. Validate configs against expected schemas and handle version mismatches gracefully.

Track and validate configuration schema changes:

module MyApp
  extend HatiConfig

  configure :settings, version: '2.0' do
    # Schema definition with version constraints
    schema do
      required :database_url, type: :string, since: '1.0'
      required :pool_size, type: :integer, since: '1.0'
      optional :replica_urls, type: [:string], since: '2.0'
      deprecated :old_setting, since: '2.0', remove_in: '3.0'
    end

    # Migrations for automatic updates
    migration '1.0' => '2.0' do |config|
      config.replica_urls = [config.delete(:backup_url)].compact
    end
  end
end

Use Case: Your application makes 1000+ requests per second and needs to check feature flags and rate limits on each request. Fetching configs from remote sources every time would crush your config server and add 50ms latency to every request. But configs can change and you need updates within 1 minute for critical flags.

Why existing tools fall short:

• No caching means every request hits the config server
• Simple TTL caching means stale data during config server outages
• No intelligent refresh strategies lead to thundering herd problems
• Manual cache invalidation is complex and error-prone

HatiConfig solution: Intelligent caching with stale-while-revalidate, background refresh, exponential backoff, and jitter to prevent thundering herds.

Configure caching behavior and automatic refresh:

module MyApp
  extend HatiConfig

  configure :settings do
    # Cache configuration
    cache do
      adapter :redis, url: 'redis://cache.example.com:6379/0'
      ttl 300  # 5 minutes
      stale_while_revalidate true
    end

    # Refresh strategy
    refresh do
      interval 60  # check every minute
      jitter 10    # add random delay (0-10 seconds)
      backoff do
        initial 1
        multiplier 2
        max 300
      end
    end
  end
end

Use Case: Your application handles API keys, database passwords, OAuth secrets, and encryption keys that are worth millions if compromised. These secrets are scattered across config files, environment variables, and deployment scripts. A single leaked config file or compromised CI/CD pipeline exposes everything. Compliance requires encryption at rest and audit trails.

Why existing tools fall short:

• Environment variables are visible in process lists and logs
• Config files with secrets get committed to Git accidentally
• Kubernetes secrets are base64 encoded, not encrypted
• External secret managers add complexity and network dependencies
• No transparent encryption/decryption in application code

HatiConfig solution: Automatic encryption of sensitive values with multiple key providers (env, files, AWS KMS). Values are encrypted at rest and decrypted transparently when accessed.

Secure sensitive configuration values with built-in encryption support:

require 'hati_config'

# Set the encryption key via environment variable
ENV['HATI_CONFIG_ENCRYPTION_KEY'] = '0123456789abcdef' * 2  # 32-character key

# Create a settings instance
settings = HatiConfig::Setting.new

# Configure encryption with environment variable key provider
settings.class.encryption do
  key_provider :env  # Uses HATI_CONFIG_ENCRYPTION_KEY environment variable
  algorithm 'aes'    # AES encryption (default)
  key_size 256       # 256-bit keys (default)
  mode 'gcm'         # GCM mode (default)
end

# Configure settings with encrypted and plain values
settings.config :api_key, value: 'secret-api-key', encrypted: true
settings.config :database_password, value: 'super-secret-password', encrypted: true

# Regular unencrypted values
settings.config :api_url, value: 'https://api.example.com'

# Nested configurations with encryption
settings.configure :database do
  config :host, value: 'db.example.com'
  config :password, value: 'db-secret', encrypted: true
  config :username, value: 'app_user'
end

# Access values - encrypted values are automatically decrypted
settings[:api_key]              # => 'secret-api-key' (decrypted)
settings.database[:password]    # => 'db-secret' (decrypted)
settings[:api_url]              # => 'https://api.example.com' (plain)

The gem supports multiple key providers for encryption keys:

# Environment variable (default)
settings.class.encryption do
  key_provider :env, env_var: 'MY_ENCRYPTION_KEY'  # Custom env var name
end

# File-based key
settings.class.encryption do
  key_provider :file, file_path: '/secure/path/to/key.txt'
end

# AWS KMS (requires aws-sdk-kms gem)
settings.class.encryption do
  key_provider :aws_kms, key_id: 'alias/config-key', region: 'us-west-2'
end

• AES-256-GCM encryption: Industry-standard encryption with authentication
• Automatic encryption/decryption: Values are encrypted when stored and decrypted when accessed
• Type safety: Only string values can be encrypted (enforced at runtime)
• Multiple key providers: Support for environment variables, files, and AWS KMS
• Secure storage: Encrypted values are stored as Base64-encoded strings

require 'hati_config'

module MyGem
  extend HatiConfig
end

MyGem.configure :settings do
  config :option
  config.int :typed_opt_one
  config :typed_opt_two, type: Integer
  # NOTE: declare nested namespace with configure <symbol arg>
  configure :nested do
    config :option
  end
end

MyGem.settings do
  config option: 1
  config typed_opt_one: 2
  config typed_opt_two: 3
  # NOTE: access namespace via <.dot_access>
  config.nested do
    config option: 4
  end
end

MyGem.settings do
  option 'one'
  typed_opt_one 1
  typed_opt_two 2
  # NOTE: access namespace via <block>
  nested do
    option 'nested'
  end
end

MyGem.settings.option        # => 'one'
MyGem.settings.typed_opt_one # => 1
MyGem.settings.typed_opt_two # => 2
MyGem.settings.nested.option # => 'nested'

MyGem.settings do
  config.typed_opt_two: '1'
end
# => HatiConfig::SettingTypeError

MyGem.settings do
  typed_opt_two '1'
end
# => HatiConfig::SettingTypeError

# List one of entries as built-in :symbols or classes

MyApp.configure :settings do
  config transaction_fee: 42, type: [Integer, :float, BigDecimal]
  config vendor_code: 42, type: [String, :int]
end

MyApp.configure :settings do
  config option: CustomClass.new, type: CustomClass
end

acc_proc = Proc.new { |val| val.respond_to?(:accounts) }
holder_lam = ->(name) { name.length > 5 }

MyApp.configure :settings do
  config acc_data: User.new, type: acc_proc
  config holder_name: 'John Doe', type: holder_lam
end

Use Case: Your application needs to load configuration from existing YAML files, JSON APIs, or hash data from databases. You want to validate the loaded data against expected schemas and handle format errors gracefully. Different environments might use different config sources (files in development, APIs in production).

Why existing tools fall short:

• Manual YAML/JSON parsing is error-prone and lacks validation
• No schema validation means runtime errors from bad config data
• Mixing different config sources requires complex custom code
• No unified interface for different data formats

HatiConfig solution: Unified interface for loading from YAML, JSON, and Hash sources with optional schema validation and clear error handling.

The HatiConfig module allows you to load configuration data from various sources, including YAML and JSON. Below are the details for each option.

• json (String)
• yaml (String)
• hash (Hash)
• schema (Hash) (Optional) See: Type Schema and Built-in Types

You can load configuration data from a JSON string by passing the json option to the configure method.

• json (String): A JSON string containing the configuration data.
• schema (Hash) (Optional): A hash representing the type schema for the configuration data.

• If the JSON format is invalid, a LoadDataError will be raised with the message "Invalid JSON format".

MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}').settings
# => #<MyGem::Setting:0x00007f8c1c0b2a80 @options={:opt_one=>1, :opt_two=>2}>

MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}', schema: { opt_one: :int, opt_two: :str })
# => HatiConfig::SettingTypeError: Expected: <str>. Given: 2 which is <Integer> class.

MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}', schema: { opt_one: :int, opt_two: :int })

MyGem.settings do
  opt_one 1
  opt_two "2"
end
# => HatiConfig::SettingTypeError: Expected: <intstr>. Given: \"2\" which is <String> class.

You can also load configuration data from a YAML file by passing the yaml option to the configure method.

• yaml (String): A file path to a YAML file containing the configuration data.
• schema (Hash) (Optional): A hash representing the type schema for the configuration data.

• If the specified YAML file is not found, a LoadDataError will be raised with the message "YAML file not found".

# settings.yml

opt_one: 1
opt_two: 2

MyGem.configure :settings, yaml: 'settings.yml'
# => #<MyGem::Setting:0x00006f8c1c0b2a80 @options={:opt_one=>1, :opt_two=>2}>

MyGem.configure :settings, yaml: 'settings.yml', schema: { opt_one: :int, opt_two: :str }
# => HatiConfig::SettingTypeError: Expected: <str>. Given: 2 which is <Integer> class.

MyGem.configure :settings, yaml: 'settings.yml', schema: { opt_one: :int, opt_two: :int }

MyGem.settings do
  opt_one 1
  opt_two "2"
end
# => HatiConfig::SettingTypeError: Expected: <intstr>. Given: \"2\" which is <String> class.

You can dump the configuration data in various formats using the following methods:

MyGem.configure :settings do
  config opt_one: 1
  config opt_two: 2
end

MyGem.settings.to_json # => '{"opt_one":1,"opt_two":2}'

MyGem.configure :settings do
  config opt_one: 1
  config opt_two: 2
end

MyGem.settings.to_json # => '{"opt_one":1,"opt_two":2}'

MyGem.configure :settings do
  config opt_one: 1
  config opt_two: 2
end

MyGem.settings.to_yaml # => "---\nopt_one: 1\nopt_two: 2\n"

MyGem.configure :settings do
  config.int opt_one: 1
  config.str opt_two: "2"
end

MyGem.settings.type_schema # => {:opt_one=>:int, :opt_two=>:str}

Use Case: Your application crashes in production because someone set a timeout to "30 seconds" instead of 30, or a database pool size to "many" instead of 10. You need runtime type validation that catches these errors early and provides clear error messages. Different config values need different types (strings, integers, arrays, custom objects).

Why existing tools fall short:

• No runtime type checking means silent failures or crashes
• Custom validation code is scattered throughout the application
• Error messages are unclear ("expected Integer, got String")
• No support for complex types like arrays of specific types or custom classes

HatiConfig solution: Comprehensive type system with built-in types, composite types, custom validators, and clear error messages.

:int  => Integer
:str  => String
:sym  => Symbol
:null => NilClass
:any  => Object
:true_class  => TrueClass
:false_class => FalseClass

:hash  => Hash
:array => Array

:big_decimal => BigDecimal,
:float       => Float,
:complex     => Complex,
:rational    => Rational,

:date      => Date,
:date_time => DateTime,
:time      => Time,

:bool       => [TrueClass, FalseClass],
:numeric    => [Integer, Float, BigDecimal],
:kernel_num => [Integer, Float, BigDecimal, Complex, Rational],
:chrono     => [Date, DateTime, Time]

• Mariya Giy (@MarieGiy)

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.

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 to publish the .gem file to rubygems.org.

Bug reports and feature requests are welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the HatiConfig project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.