hati-config 0.1.0

data/hati-config.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'hati_config/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'hati-config'
+  spec.version = '0.1.0'
+  spec.authors = ['Marie Giy']
+  spec.email   = %w[giy.mariya@gmail.com]
+  spec.license = 'MIT'
+
+  spec.summary = 'Ruby configuration management for distributed systems and multi-team environments.'
+  spec.description = 'A practical approach to configuration management with type safety, team isolation, ' \
+                     'environment inheritance, encryption, and remote sources. Designed for teams dealing ' \
+                     'with configuration complexity at scale.'
+  spec.homepage = "https://github.com/hackico-ai/#{spec.name}"
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.files         = Dir['CHANGELOG.md', 'LICENSE', 'README.md', 'hati-config.gemspec', 'lib/**/*']
+  spec.bindir        = 'bin'
+  spec.executables   = []
+  spec.require_paths = ['lib']
+
+  spec.metadata['repo_homepage']     = spec.homepage
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['changelog_uri']   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.add_dependency 'aws-sdk-s3', '~> 1.0'
+  spec.add_dependency 'bigdecimal', '~> 3.0'
+  spec.add_dependency 'connection_pool', '~> 2.4'
+  spec.add_dependency 'redis', '~> 5.0'
+end

data/lib/hati_config/cache.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require 'redis'
+require 'connection_pool'
+require 'json'
+
+module HatiConfig
+  # Cache module provides functionality for caching and refreshing configurations.
+  module Cache
+    # Module for handling numeric configuration attributes
+    module NumericConfigurable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def numeric_accessor(*names)
+          names.each do |name|
+            define_method(name) do |value = nil|
+              if value.nil?
+                instance_variable_get(:"@#{name}")
+              else
+                instance_variable_set(:"@#{name}", value)
+                self
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # Defines caching behavior for configurations.
+    #
+    # @param adapter [Symbol] The cache adapter to use (:memory, :redis)
+    # @param options [Hash] Options for the cache adapter
+    # @yield The cache configuration block
+    # @example
+    #   cache do
+    #     adapter :redis, url: "redis://cache.example.com:6379/0"
+    #     ttl 300  # 5 minutes
+    #     stale_while_revalidate true
+    #   end
+    def cache(&block)
+      @cache_config = CacheConfig.new
+      @cache_config.instance_eval(&block) if block_given?
+      @cache_config
+    end
+
+    # Gets the cache configuration.
+    #
+    # @return [CacheConfig] The cache configuration
+    def cache_config
+      @cache_config ||= CacheConfig.new
+    end
+
+    # CacheConfig class handles cache configuration and behavior.
+    class CacheConfig
+      include NumericConfigurable
+
+      attr_reader :adapter_type, :adapter_options
+
+      numeric_accessor :ttl
+
+      def refresh(&block)
+        @refresh_config.instance_eval(&block) if block_given?
+        @refresh_config
+      end
+
+      def stale_while_revalidate(enabled = nil)
+        if enabled.nil?
+          @stale_while_revalidate
+        else
+          @stale_while_revalidate = enabled
+          self
+        end
+      end
+
+      def initialize
+        @adapter_type = :memory
+        @adapter_options = {}
+        @ttl = 300
+        @stale_while_revalidate = false
+        @refresh_config = RefreshConfig.new
+        @adapter = nil
+      end
+
+      # Sets the cache adapter.
+      #
+      # @param type [Symbol] The adapter type (:memory, :redis)
+      # @param options [Hash] Options for the adapter
+      def adapter(*args, **kwargs)
+        if args.empty? && kwargs.empty?
+          @adapter ||= initialize_adapter
+        else
+          type = args[0]
+          options = args[1] || kwargs
+          @adapter_type = type
+          @adapter_options = options
+          @adapter = nil
+          self
+        end
+      end
+
+      attr_writer :adapter
+
+      private
+
+      def initialize_adapter
+        case adapter_type
+        when :memory
+          MemoryAdapter.new
+        when :redis
+          RedisAdapter.new(adapter_options)
+        else
+          raise ArgumentError, "Unknown cache adapter: #{adapter_type}"
+        end
+      end
+
+      # Gets a value from the cache.
+      #
+      # @param key [String] The cache key
+      # @return [Object, nil] The cached value or nil if not found
+      def get(key)
+        adapter.get(key)
+      end
+
+      # Sets a value in the cache.
+      #
+      # @param key [String] The cache key
+      # @param value [Object] The value to cache
+      # @param ttl [Integer, nil] Optional TTL override
+      def set(key, value, ttl = nil)
+        adapter.set(key, value, ttl || @ttl)
+      end
+
+      # Deletes a value from the cache.
+      #
+      # @param key [String] The cache key
+      def delete(key)
+        adapter.delete(key)
+      end
+    end
+
+    # RefreshConfig class handles refresh configuration and behavior.
+    class RefreshConfig
+      include NumericConfigurable
+
+      attr_reader :interval, :jitter, :backoff_config
+
+      numeric_accessor :interval, :jitter
+
+      def initialize
+        @interval = 60
+        @jitter = 0
+        @backoff_config = BackoffConfig.new
+      end
+
+      # Configures backoff behavior.
+      #
+      # @yield The backoff configuration block
+      def backoff(&block)
+        @backoff_config.instance_eval(&block) if block_given?
+        @backoff_config
+      end
+
+      # Gets the next refresh time.
+      #
+      # @return [Time] The next refresh time
+      def next_refresh_time
+        jitter_amount = jitter.positive? ? rand(0.0..jitter) : 0
+        Time.now + interval + jitter_amount
+      end
+    end
+
+    # BackoffConfig class handles backoff configuration and behavior.
+    class BackoffConfig
+      include NumericConfigurable
+
+      attr_reader :initial, :multiplier, :max
+
+      numeric_accessor :initial, :multiplier, :max
+
+      def initialize
+        @initial = 1
+        @multiplier = 2
+        @max = 300
+      end
+
+      # Gets the backoff time for a given attempt.
+      #
+      # @param attempt [Integer] The attempt number
+      # @return [Integer] The backoff time in seconds
+      def backoff_time(attempt)
+        time = initial * (multiplier**(attempt - 1))
+        [time, max].min
+      end
+    end
+
+    # MemoryAdapter class provides in-memory caching.
+    class MemoryAdapter
+      def initialize
+        @store = {}
+        @expiry = {}
+      end
+
+      # Gets a value from the cache.
+      #
+      # @param key [String] The cache key
+      # @return [Object, nil] The cached value or nil if not found/expired
+      def get(key)
+        return nil if expired?(key)
+
+        @store[key]
+      end
+
+      # Sets a value in the cache.
+      #
+      # @param key [String] The cache key
+      # @param value [Object] The value to cache
+      # @param ttl [Integer] The TTL in seconds
+      def set(key, value, ttl)
+        @store[key] = value
+        @expiry[key] = Time.now + ttl if ttl
+      end
+
+      # Deletes a value from the cache.
+      #
+      # @param key [String] The cache key
+      def delete(key)
+        @store.delete(key)
+        @expiry.delete(key)
+      end
+
+      private
+
+      def expired?(key)
+        expiry = @expiry[key]
+        expiry && Time.now >= expiry
+      end
+    end
+
+    # RedisAdapter class provides Redis-based caching.
+    class RedisAdapter
+      def initialize(options)
+        @pool = ConnectionPool.new(size: 5, timeout: 5) do
+          Redis.new(options)
+        end
+      end
+
+      # Gets a value from the cache.
+      #
+      # @param key [String] The cache key
+      # @return [Object, nil] The cached value or nil if not found
+      def get(key)
+        @pool.with do |redis|
+          value = redis.get(key)
+          value ? Marshal.load(value) : nil
+        end
+      rescue TypeError, ArgumentError
+        nil
+      end
+
+      # Sets a value in the cache.
+      #
+      # @param key [String] The cache key
+      # @param value [Object] The value to cache
+      # @param ttl [Integer] The TTL in seconds
+      def set(key, value, ttl)
+        @pool.with do |redis|
+          redis.setex(key, ttl, Marshal.dump(value))
+        end
+      end
+
+      # Deletes a value from the cache.
+      #
+      # @param key [String] The cache key
+      def delete(key)
+        @pool.with do |redis|
+          redis.del(key)
+        end
+      end
+    end
+  end
+end

data/lib/hati_config/configuration.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+# HatiConfig module provides functionality for managing HatiConfig features.
+module HatiConfig
+  # This module handles configuration trees and loading data from various sources.
+  module Configuration
+    # Isolated module provides methods for handling isolated configurations.
+    module Local
+      # Configures an isolated config tree and tracks it
+      #
+      # @param config_tree_name [Symbol] The name of the configuration tree
+      # @param opts [Hash] Options for configuration
+      # @yield The configuration block
+      # @return [self]
+      #
+      # @example
+      #   configure :isolated_settings do
+      #     config api_url: "https://api.example.com"
+      #   end
+      #
+      #   # Example of accessing the configuration
+      #   puts MyApp.isolated_settings.api_url # => "https://api.example.com"
+      def configure(config_tree_name, opts = {}, &block)
+        super
+
+        @isolated_configs ||= []
+        @isolated_configs << config_tree_name
+
+        self
+      end
+
+      # Inherits isolated configurations to the base class
+      #
+      # @param base [Class] The inheriting class
+      #
+      # @example
+      #   class ChildClass < ParentClass
+      #     # Automatically inherits isolated configurations
+      #   end
+      #
+      #   # Example of accessing inherited configurations
+      #   puts ChildClass.parent_settings.timeout # => 30
+      def inherited(base)
+        super
+
+        @isolated_configs.each do |parent_config|
+          hash = __send__(parent_config).to_h
+          schema = __send__(parent_config).type_schema
+          lock_schema = __send__(parent_config).lock_schema
+
+          base.configure parent_config, hash: hash, schema: schema, lock_schema: lock_schema
+        end
+      end
+    end
+
+    # Creates a class-level method for the configuration tree.
+    #
+    # This method allows you to define a configuration tree using a block
+    # or load configuration data from a hash, JSON, or YAML file.
+    #
+    # @param config_tree_name [Symbol, String] The name of the configuration method to be defined.
+    # @param opts [Hash] Optional options for loading configuration data.
+    # @option opts [Hash] :hash A hash containing configuration data.
+    # @option opts [String] :json A JSON string containing configuration data.
+    # @option opts [String] :yaml A file path to a YAML file containing configuration data.
+    # @option opts [Hash] :schema A hash representing the type schema for the configuration.
+    # @yield [Setting] A block that builds the configuration tree.
+    #
+    # @example Configuring with a block
+    #   configure :app_config do
+    #     config :username, value: "admin"
+    #     config :max_connections, type: :int, value: 10
+    #   end
+    #
+    # @example Loading from a hash
+    #   configure :app_config, hash: { username: "admin", max_connections: 10 }
+    #
+    # @example Loading from a JSON string
+    #   configure :app_config, json: '{"username": "admin", "max_connections": 10}'
+    #
+    # @example Loading from a YAML file
+    #   configure :app_config, yaml: 'config/settings.yml'
+    #
+    # @example Loading with a schema
+    #   configure :app_config, hash: { name: "admin", policy: "allow" }, schema: { name: :str, policy: :str }
+    def configure(config_tree_name, opts = {}, &block)
+      settings = block ? HatiConfig::Setting.new(&block) : HatiConfig::Setting.new
+
+      load_configs = load_data(opts) unless opts.empty?
+      settings.load_from_hash(load_configs, schema: opts[:schema], lock_schema: opts[:lock_schema]) if load_configs
+
+      define_singleton_method(config_tree_name) do |&tree_block|
+        tree_block ? settings.instance_eval(&tree_block) : settings
+      end
+    end
+
+    module_function
+
+    # Loads configuration data from various sources based on the provided options.
+    #
+    # @param opts [Hash] Optional options for loading configuration data.
+    # @option opts [Hash] :hash A hash containing configuration data.
+    # @option opts [String] :json A JSON string containing configuration data.
+    # @option opts [String] :yaml A file path to a YAML file containing configuration data.
+    # @return [Hash] The loaded configuration data.
+    # @raise [LoadDataError] If no valid data is found.
+    #
+    # @example Loading from a hash
+    #   load_data(hash: { key: "value" })
+    #
+    # @example Loading from a JSON string
+    #   load_data(json: '{"key": "value"}')
+    #
+    # @example Loading from a YAML file
+    #   load_data(yaml: 'config/settings.yml')
+    def load_data(opts = {})
+      data = if opts[:hash]
+               opts[:hash]
+             elsif opts[:json]
+               JSON.parse(opts[:json])
+             elsif opts[:yaml]
+               YAML.load_file(opts[:yaml])
+             elsif opts[:http]
+               RemoteLoader.from_http(**opts[:http])
+             elsif opts[:s3]
+               RemoteLoader.from_s3(**opts[:s3])
+             elsif opts[:redis]
+               RemoteLoader.from_redis(**opts[:redis])
+             end
+
+      raise HatiConfig::LoadDataError, 'Invalid load source type' unless data
+
+      data
+    rescue JSON::ParserError
+      raise HatiConfig::LoadDataError, 'Invalid JSON format'
+    rescue Errno::ENOENT
+      raise HatiConfig::LoadDataError, 'YAML file not found'
+    end
+  end
+end

data/lib/hati_config/encryption.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module HatiConfig
+  # Encryption module provides methods for encrypting and decrypting sensitive configuration values.
+  module Encryption
+    # Custom error class for encryption-related errors.
+    class EncryptionError < StandardError; end
+
+    # Defines encryption configuration for a class or module.
+    #
+    # @yield [encryption_config] A block to configure encryption settings.
+    # @return [EncryptionConfig] The encryption configuration instance.
+    def encryption(&block)
+      @encryption_config ||= EncryptionConfig.new
+      @encryption_config.instance_eval(&block) if block_given?
+      @encryption_config
+    end
+
+    # Gets the encryption configuration.
+    #
+    # @return [EncryptionConfig] The encryption configuration
+    def encryption_config
+      @encryption_config ||= EncryptionConfig.new
+    end
+
+    # EncryptionConfig class handles encryption configuration and behavior.
+    class EncryptionConfig
+      attr_reader :key_provider, :algorithm, :key_size, :mode, :key_provider_type, :key_provider_options
+
+      def initialize
+        @key_provider = nil
+        @key_provider_type = nil
+        @key_provider_options = {}
+        @algorithm = 'aes'
+        @key_size = 256
+        @mode = 'gcm'
+      end
+
+      # Sets the key provider.
+      #
+      # @param provider [Symbol] The key provider type (:env, :file, :aws_kms)
+      # @param options [Hash] Options for the key provider
+      def key_provider(provider = nil, options = {})
+        if provider.nil?
+          @key_provider
+        else
+          @key_provider_type = provider
+          @key_provider_options = options
+          @key_provider = KeyProvider.create(provider, options)
+          self
+        end
+      end
+
+      # Sets the encryption algorithm.
+      #
+      # @param value [String] The encryption algorithm (e.g., "aes")
+      def algorithm(value = nil)
+        if value.nil?
+          @algorithm
+        else
+          @algorithm = value
+          self
+        end
+      end
+
+      # Sets the key size.
+      #
+      # @param value [Integer] The key size in bits (e.g., 256)
+      def key_size(value = nil)
+        if value.nil?
+          @key_size
+        else
+          @key_size = value
+          self
+        end
+      end
+
+      # Sets the encryption mode.
+      #
+      # @param value [String] The encryption mode (e.g., "gcm")
+      def mode(value = nil)
+        if value.nil?
+          @mode
+        else
+          @mode = value
+          self
+        end
+      end
+
+      # Encrypts a value.
+      #
+      # @param value [String] The value to encrypt
+      # @return [String] The encrypted value in Base64 format
+      # @raise [EncryptionError] If encryption fails
+      def encrypt(value)
+        raise EncryptionError, 'No key provider configured' unless @key_provider
+
+        begin
+          cipher = OpenSSL::Cipher.new("#{@algorithm}-#{@key_size}-#{@mode}")
+          cipher.encrypt
+          cipher.key = @key_provider.key
+
+          if @mode == 'gcm'
+            cipher.auth_data = ''
+            iv = cipher.random_iv
+            cipher.iv = iv
+            ciphertext = cipher.update(value.to_s) + cipher.final
+            auth_tag = cipher.auth_tag
+
+            # Format: Base64(IV + Auth Tag + Ciphertext)
+            Base64.strict_encode64(iv + auth_tag + ciphertext)
+          else
+            iv = cipher.random_iv
+            cipher.iv = iv
+            ciphertext = cipher.update(value.to_s) + cipher.final
+
+            # Format: Base64(IV + Ciphertext)
+            Base64.strict_encode64(iv + ciphertext)
+          end
+        rescue OpenSSL::Cipher::CipherError => e
+          raise EncryptionError, "Encryption failed: #{e.message}"
+        end
+      end
+
+      # Decrypts a value.
+      #
+      # @param encrypted_value [String] The encrypted value in Base64 format
+      # @return [String] The decrypted value
+      # @raise [EncryptionError] If decryption fails
+      def decrypt(encrypted_value)
+        raise EncryptionError, 'No key provider configured' unless @key_provider
+        return nil if encrypted_value.nil?
+
+        begin
+          data = Base64.strict_decode64(encrypted_value)
+          cipher = OpenSSL::Cipher.new("#{@algorithm}-#{@key_size}-#{@mode}")
+          cipher.decrypt
+          cipher.key = @key_provider.key
+
+          if @mode == 'gcm'
+            iv = data[0, 12] # GCM uses 12-byte IV
+            auth_tag = data[12, 16] # GCM uses 16-byte auth tag
+            ciphertext = data[28..]
+
+            cipher.iv = iv
+            cipher.auth_tag = auth_tag
+            cipher.auth_data = ''
+
+          else
+            iv = data[0, 16] # Other modes typically use 16-byte IV
+            ciphertext = data[16..]
+
+            cipher.iv = iv
+          end
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError => e
+          raise EncryptionError, "Decryption failed: #{e.message}"
+        rescue ArgumentError => e
+          raise EncryptionError, "Invalid encrypted value: #{e.message}"
+        end
+      end
+    end
+
+    # KeyProvider class hierarchy for handling encryption keys.
+    class KeyProvider
+      def self.create(type, options = {})
+        case type
+        when :env
+          EnvKeyProvider.new(options)
+        when :file
+          FileKeyProvider.new(options)
+        when :aws_kms
+          AwsKmsKeyProvider.new(options)
+        else
+          raise EncryptionError, "Unknown key provider: #{type}"
+        end
+      end
+
+      def key
+        raise NotImplementedError, 'Subclasses must implement #key'
+      end
+    end
+
+    # EnvKeyProvider gets the encryption key from an environment variable.
+    class EnvKeyProvider < KeyProvider
+      def initialize(options = {})
+        super()
+        @env_var = options[:env_var] || 'HATI_CONFIG_ENCRYPTION_KEY'
+      end
+
+      def key
+        key = ENV.fetch(@env_var, nil)
+        raise EncryptionError, "Encryption key not found in environment variable #{@env_var}" unless key
+
+        key
+      end
+    end
+
+    # FileKeyProvider gets the encryption key from a file.
+    class FileKeyProvider < KeyProvider
+      def initialize(options = {})
+        super()
+        @file_path = options[:file_path]
+        raise EncryptionError, 'File path not provided' unless @file_path
+      end
+
+      def key
+        raise EncryptionError, "Key file not found: #{@file_path}" unless File.exist?(@file_path)
+
+        File.read(@file_path).strip
+      rescue SystemCallError => e
+        raise EncryptionError, "Failed to read key file: #{e.message}"
+      end
+    end
+
+    # AwsKmsKeyProvider gets the encryption key from AWS KMS.
+    class AwsKmsKeyProvider < KeyProvider
+      def initialize(options = {})
+        super()
+        require 'aws-sdk-kms'
+        @key_id = options[:key_id]
+        @region = options[:region]
+        @client = nil
+        raise EncryptionError, 'KMS key ID not provided' unless @key_id
+      end
+
+      def key
+        @key ||= begin
+          client = Aws::KMS::Client.new(region: @region)
+          response = client.generate_data_key(
+            key_id: @key_id,
+            key_spec: 'AES_256'
+          )
+          response.plaintext
+        rescue Aws::KMS::Errors::ServiceError => e
+          raise EncryptionError, "Failed to get key from KMS: #{e.message}"
+        end
+      end
+    end
+  end
+end