bbk-utils 1.1.6.376358 → 1.1.6.409139

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 102c2729e460c60af51ef53ba1e1d1dea7ff96cf4430092eda0c386921dfe8b1
-  data.tar.gz: 561cf4cd85c5cc82d03b411f40b0ca4c47e3438953cbb8cf86ebfbdea550939e
+  metadata.gz: 40fafd60b7a8a9c337c28b002831b29f57da91633306857f5a9fff5c73c3d4a1
+  data.tar.gz: 5a67d746083afb0e0ed01b606ae8c1fe1f2ccb2f5d8184f5a584aaef82ea834f
 SHA512:
-  metadata.gz: 62ded80cc3b747b281eb11d736243c06cd7306cb8d6f8a73ec2bb4d80255fc94f75c266ff351acfd800665df78caf3b6807a7ac1d560f94f76b61f4d5b8810c9
-  data.tar.gz: 3b9968c1647b914fea6992d6d35aefd30d43a5733d388ead4fab0e94fb3e82b07c16a851cc70095cc4493a2a32486d98105a103d6233a32961df1b552c283884
+  metadata.gz: c4a4c724e029d7492dd2dcaeda86dc667deef657fb668ae518cd54d9fa1d8d1e1ae6f5bc896cb27cc20e063346fc12280a3ccb4aed6330e7ee67cd804b808b5c
+  data.tar.gz: 5f2b6c7980b27a9e1aa6e05e47adf0b1af6b6ddb9f62f06d25c4e2153ce05791527af20438e07c09647b2d9bad9ae6ee1fce8ff7b77cf7889e835a5fc856ec24

data/README.md

@@ -13,7 +13,10 @@
 
 </div>
 
-Common classes and helpers for BBK library stack.
+Набор общих классов и вспомогательных модулей для стека библиотек BBK. / Common classes and helpers for BBK library stack.
+
+
+## Установка / Installation
 
 ## Installation
 
@@ -37,9 +40,81 @@ Or adding to your project:
 gem "bbk-utils", "~> 1.0.0"
 ```
 
-## Features
+## Возможности / Features
+
+### EnvHelper — сборка URL подключений / URL Building Helper
+
+Нормализует переменные окружения: собирает URL из отдельных компонентов и раскладывает обратно. Три уровня приоритетов: ENV-переменная > компонент из базового URL > значение по умолчанию.
+
+Normalizes environment variables: builds URLs from individual components and decomposes back. Three-level priorities: env var > component from base URL > default.
+
+```ruby
+# Базы данных / Databases — prepare_database_envs
+env = { 'DATABASE_URL' => 'postgres://user:pass@host:5432/db', 'DATABASE_HOST' => 'newhost' }
+BBK::Utils::EnvHelper.prepare_database_envs(env)
+# => env['DATABASE_URL'] = 'postgres://user:pass@newhost:5432/db'
+
+# Очереди сообщений / Message Queues — prepare_mq_envs
+env = { 'MQ_HOST' => 'mq1;mq2;mq3', 'MQ_USER' => 'guest' }
+BBK::Utils::EnvHelper.prepare_mq_envs(env)
+# => env['MQ_URL'] = 'amqps://guest@mq1:5671/;amqps://guest@mq2:5671/;amqps://guest@mq3:5671/'
+
+# Jaeger Tracing — prepare_jaeger_envs
+BBK::Utils::EnvHelper.prepare_jaeger_envs(ENV)
+```
+
+### Config — декларативная работа с переменными окружения / Declarative ENV Management
+
+Декларативное описание, валидация и чтение переменных окружения с поддержкой типов, значений по умолчанию, подконфигураций и маскирования секретов.
+
+Declarative description, validation, and reading of environment variables with type casting, defaults, subconfigurations, and secret masking.
+
+```ruby
+require 'bbk/utils'
+
+BBK::Utils::Config.instance.tap do |cfg|
+  cfg.require('API_KEY', desc: 'API key', secure: true)
+  cfg.optional('LOG_LEVEL', default: 'info', desc: 'Logging level')
+  cfg.optional('TIMEOUT', default: 30, type: method(:Integer), desc: 'Timeout in seconds')
+  cfg.optional('DEBUG_MODE', default: false, bool: true, desc: 'Enable debug mode')
+  cfg.optional('CLEAN_INTERVAL', default: '3month', type: method(:duration_parser))
+
+  cfg.map('SSL_CERT', '/etc/ssl/cert.pem', desc: 'SSL certificate')
+
+  cfg.subconfig(prefix: 'REDIS') do |redis|
+    redis.optional('URL', default: 'redis://redis:6379/0', desc: 'Redis URL')
+    redis.optional('POOL_SIZE', default: 5, type: method(:Integer), desc: 'Pool size')
+  end
+end
+
+# Важно: сначала EnvHelper, потом Config
+# Important: EnvHelper first, then Config
+BBK::Utils::EnvHelper.prepare_database_envs(ENV)
+BBK::Utils::EnvHelper.prepare_mq_envs(ENV)
+BBK::Utils::Config.run!(ENV)
+
+# Доступ к значениям / Accessing values
+BBK::Utils::Config['LOG_LEVEL']   # => "info"
+BBK::Utils::Config['REDIS_URL']   # => "redis://redis:6379/0"
+puts BBK::Utils::Config.to_s
+```
+
+#### Префиксы и альтернативные имена / Prefixes & Alternative Names
+
+```ruby
+config = BBK::Utils::Config.instance(prefix: 'MYAPP')
+config.optional('PORT', default: 3000)  # читает MYAPP_PORT
+
+cfg.require('DB_URL', key: 'DATABASE_URL', desc: 'Database URL')  # ищет DATABASE_URL, доступен как DB_URL
+```
+
+#### Приведение булевых значений / Boolean Casting
+
+`false, 0, '0', 'f', 'false', 'off'` (и их вариации) → `false`. Всё остальное → `true`. Пустая строка и `nil` → `nil`.
+
+`false, 0, '0', 'f', 'false', 'off'` (and variations) → `false`. Everything else → `true`. Empty string and `nil` → `nil`.
 
-### bbkdocs
+### bbkdocs — генерация документации / Documentation Generator
 
 Создать `bin/bbkdocs`:
 

data/lib/bbk/utils/config.rb

@@ -2,18 +2,82 @@
 
 module BBK
   module Utils
+    # Класс управления конфигурацией приложения через переменные окружения.
+    #
+    # Предоставляет декларативный способ описания конфигурационных параметров
+    # с поддержкой префиксов, подконфигураций, приведения типов, безопасных значений
+    # и файловых конфигураций. Реализует паттерн Singleton.
+    #
+    # @example Базовое использование
+    #   BBK::Utils::Config.instance.tap do |cfg|
+    #     cfg.optional('LOG_LEVEL', default: 'info', desc: 'Уровень логирования')
+    #     cfg.require('DATABASE_URL', desc: 'Строка подключения к БД')
+    #     cfg.optional('REDIS_URL', default: 'redis://localhost:6379/0')
+    #   end
+    #   BBK::Utils::Config.run!(ENV)
+    #
+    #   # Доступ к значениям
+    #   BBK::Utils::Config['LOG_LEVEL']    # => "info"
+    #   BBK::Utils::Config['DATABASE_URL'] # => значение из ENV
+    #
+    # @example Использование с префиксами
+    #   config = BBK::Utils::Config.instance(prefix: 'MYAPP')
+    #   config.optional('PORT', default: 3000)
+    #   config.run!(ENV)
+    #   # Читает переменную MYAPP_PORT из ENV
+    #
+    # @example Подконфигурации
+    #   config = BBK::Utils::Config.instance
+    #   config.subconfig(prefix: 'DB') do |db|
+    #     db.require('HOST', desc: 'Хост базы данных')
+    #     db.optional('PORT', default: '5432')
+    #   end
+    #   config.run!(ENV)
+    #   # Читает переменные DB_HOST и DB_PORT из ENV
+    #
+    # @note Все методы класса делегируются единственному экземпляру (Singleton)
+    # @see Config::BooleanCaster Класс для приведения булевых значений
     class Config
 
+      # @return [String] Разделитель между частями префикса
       PREFIX_SEP = '_'
+
+      # @return [String] Заглушка для отображения безопасных значений в выводе
       FILTERED_VALUE = '[FILTERED]'
 
-      attr_accessor :store, :name
-      attr_reader :prefix, :env_prefix, :parent
+      # @return [Hash] Хранилище конфигурационных элементов
+      attr_accessor :store
+
+      # @return [String, nil] Имя конфигурации (для отображения)
+      attr_accessor :name
+
+      # @return [String, nil] Префикс данной конфигурации
+      attr_reader :prefix
+
+      # @return [String] Полный префикс с учётом родительских (для ENV)
+      attr_reader :env_prefix
 
+      # @return [Config, nil] Родительская конфигурация
+      attr_reader :parent
+
+      # Ошибка при обращении к несуществующему ключу конфигурации
       class KeyError < StandardError; end
 
+      # Класс для приведения значений к булевому типу.
+      #
+      # Распознаёт широкий набор "ложных" значений: 0, 'f', 'false', 'off' и их варианты.
+      # Всё остальное считается истиной. Пустые значения возвращают +nil+.
+      #
+      # @example
+      #   BooleanCaster.cast('true')  # => true
+      #   BooleanCaster.cast('0')     # => false
+      #   BooleanCaster.cast('off')   # => false
+      #   BooleanCaster.cast(nil)     # => nil
+      #   BooleanCaster.cast('')      # => nil
+      #   BooleanCaster.cast('yes')   # => true
       class BooleanCaster
 
+        # Множество значений, интерпретируемых как +false+
         FALSE_VALUES = [
           false, 0,
           '0', :"0",
@@ -25,6 +89,10 @@ module BBK
           'OFF', :OFF
         ].to_set.freeze
 
+        # Приводит значение к булевому типу.
+        #
+        # @param value [Object] Значение для приведения
+        # @return [Boolean, nil] +true+, +false+ или +nil+ (для пустых значений)
         def self.cast(value)
           if value.nil? || value == ''
             nil
@@ -35,14 +103,55 @@ module BBK
 
       end
 
+      # Возвращает единственный экземпляр конфигурации (Singleton).
+      #
+      # @param prefix [String, nil] Префикс для переменных окружения (только при первом вызове)
+      # @return [Config] Единственный экземпляр
+      #
+      # @example
+      #   config = BBK::Utils::Config.instance
+      #   config = BBK::Utils::Config.instance(prefix: 'MYAPP')
       def self.instance(prefix: nil)
         @instance ||= new(prefix: prefix)
       end
 
+      # Приводит значение к булевому типу.
+      #
+      # @param value [Object] Значение для приведения
+      # @return [Boolean, nil] Результат приведения
+      # @see BooleanCaster.cast
       def self.parse_bool_value(value)
         BooleanCaster.cast(value)
       end
 
+      # Делегирование методов экземпляра на уровень класса
+      # 
+      # @!method self.map(env, file, required: true, desc: nil, bool: false, key: nil, rewrite: true, category: nil, warning: nil)
+      #   @see #map
+      # @!method self.require(env, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false, category: nil, warning: nil)
+      #   @see #require
+      # @!method self.optional(env, default: nil, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false, category: nil, warning: nil)
+      #   @see #optional
+      # @!method self.run!(source = ENV)
+      #   @see #run!
+      # @!method self.[](key)
+      #   @see #[]
+      # @!method self.[]=(key, value)
+      #   @see #[]=
+      # @!method self.content(key)
+      #   @see #content
+      # @!method self.to_s
+      #   @see #to_s
+      # @!method self.as_json(*args)
+      #   @see #as_json
+      # @!method self.to_json(*args)
+      #   @see #to_json
+      # @!method self.to_yaml(*args)
+      #   @see #to_yaml
+      # @!method self.fetch(key, default = nil)
+      #   @see #fetch
+      # @!method self.root?
+      #   @see #root?
       class << self
 
         delegate :map, :require, :optional, :run!, :[], :[]=, :content, :to_s,
@@ -51,6 +160,16 @@ module BBK
 
       end
 
+      # Инициализирует новый экземпляр конфигурации.
+      #
+      # Обычно не вызывается напрямую — используйте {.instance}.
+      #
+      # @param name [String, nil] Имя конфигурации (для отображения в логах)
+      # @param prefix [String, nil] Префикс для переменных окружения
+      # @param parent [Config, nil] Родительская конфигурация (для подконфигураций)
+      #
+      # @example
+      #   config = BBK::Utils::Config.new(name: 'myapp', prefix: 'MYAPP')
       def initialize(name: nil, prefix: nil, parent: nil)
         @name = name
         @store = {}
@@ -65,6 +184,27 @@ module BBK
         @env_prefix = normalize_key(@prefixes.join(PREFIX_SEP))
       end
 
+      # Регистрирует файловый конфигурационный параметр.
+      #
+      # Значение переменной окружения записывается в указанный файл.
+      # Используется для сертификатов, ключей и других файловых данных.
+      #
+      # @param env [String] Имя переменной окружения (без префикса)
+      # @param file [String] Путь к файлу, куда будет записано значение
+      # @param required [Boolean] Обязательность параметра (по умолчанию: true)
+      # @param desc [String, nil] Описание параметра
+      # @param bool [Boolean] (устарел) Не используется для файловых параметров, оставлен для совместимости
+      # @param key [String, nil] Альтернативное имя переменной окружения
+      # @param rewrite [Boolean] Перезаписывать при повторной регистрации (по умолчанию: true)
+      # @param category [String, nil] Имя категории, к которой относится параметр.
+      #   Используется генератором документации `BBK::Utils::Cli::Docs::Builder`
+      # @param warning [String, nil] Предупреждение для отображения
+      # @return [void]
+      #
+      # @example
+      #   config.map('SSL_CERT', '/etc/ssl/cert.pem', desc: 'SSL-сертификат')
+      #   config.run!(ENV)
+      #   # Значение ENV['SSL_CERT'] будет записано в /etc/ssl/cert.pem
       def map(env, file, required: true, desc: nil, bool: false, key: nil, rewrite: true, category: nil, warning: nil)
         conf_key = full_prefixed_key(env)
         return if @store.key?(conf_key) && !rewrite
@@ -81,10 +221,34 @@ module BBK
         }
       end
 
+      # Регистрирует обязательный конфигурационный параметр.
+      #
+      # При отсутствии переменной в источнике во время {#run!} будет выброшено исключение.
+      #
+      # @param env [String] Имя переменной окружения (без префикса)
+      # @param desc [String, nil] Описание параметра
+      # @param bool [Boolean] Интерпретировать как булево значение (по умолчанию: false)
+      # @param type [#call, Class, nil] Кастер типа: объект с методом +call+ или класс с методом +new+
+      #   *Примечание:* для встроенных классов (например, `Integer`, `Float`) передавайте `method(:Integer)`, так как они не имеют публичного метода `new`.
+      # @param key [String, nil] Альтернативное имя переменной окружения (используется для чтения из ENV).
+      #   Например: `config.require('MY_DB', key: 'DATABASE_URL')` прочитает `DATABASE_URL`,
+      #   но в коде вы будете обращаться к нему как `config['MY_DB']`.
+      # @param rewrite [Boolean] Перезаписывать при повторной регистрации (по умолчанию: true)
+      # @param secure [Boolean] Скрывать значение в выводе (по умолчанию: false)
+      # @param category [String, nil] Имя категории, к которой относится параметр.
+      #   Используется генератором документации `BBK::Utils::Cli::Docs::Builder`
+      # @param warning [String, nil] Предупреждение для отображения
+      # @return [void]
+      # @raise [ArgumentError] Если одновременно указаны +bool+ и +type+
+      #
+      # @example
+      #   config.require('DATABASE_URL', desc: 'Строка подключения к БД')
+      #   config.require('API_KEY', secure: true, desc: 'Секретный ключ')
+      #   config.require('WORKERS_COUNT', type: method(:Integer), desc: 'Число воркеров')
       def require(env, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false, category: nil, warning: nil)
         raise ArgumentError.new('Specified type and bool') if bool && type.present?
 
-        type = BBK::Config::BooleanCaster.singleton_method(:cast) if bool
+        type = BBK::Utils::Config::BooleanCaster.singleton_method(:cast) if bool
         conf_key = full_prefixed_key(env)
         return if @store.key?(conf_key) && !rewrite
 
@@ -101,6 +265,30 @@ module BBK
         }
       end
 
+      # Регистрирует опциональный конфигурационный параметр со значением по умолчанию.
+      #
+      # @param env [String] Имя переменной окружения (без префикса)
+      # @param default [Object] Значение по умолчанию (по умолчанию: nil)
+      # @param desc [String, nil] Описание параметра
+      # @param bool [Boolean] Интерпретировать как булево значение (по умолчанию: false)
+      # @param type [#call, Class, nil] Кастер типа: объект с методом +call+ или класс с методом +new+
+      #   *Примечание:* для встроенных классов (например, `Integer`, `Float`) передавайте `method(:Integer)`, так как они не имеют публичного метода `new`.
+      # @param key [String, nil] Альтернативное имя переменной окружения (используется для чтения из ENV).
+      #   Например: `config.optional('REDIS_URL', key: 'REDIS_CACHE_URL', default: 'redis://localhost:6379/0')` прочитает `REDIS_CACHE_URL`,
+      #   но в коде вы будете обращаться к нему как `config['REDIS_URL']`.
+      # @param rewrite [Boolean] Перезаписывать при повторной регистрации (по умолчанию: true)
+      # @param secure [Boolean] Скрывать значение в выводе (по умолчанию: false)
+      # @param category [String, nil] Имя категории, к которой относится параметр.
+      #   Используется генератором документации `BBK::Utils::Cli::Docs::Builder`
+      # @param warning [String, nil] Предупреждение для отображения
+      # @return [void]
+      # @raise [ArgumentError] Если одновременно указаны +bool+ и +type+
+      #
+      # @example
+      #   config.optional('LOG_LEVEL', default: 'info', desc: 'Уровень логирования')
+      #   config.optional('PORT', default: '3000', type: method(:Integer))
+      #   config.optional('DEBUG', default: false, bool: true)
+      #   config.optional('PASSWORD', default: '', secure: true)
       def optional(env, default: nil, desc: nil, bool: false, type: nil, key: nil, rewrite: true, secure: false, category: nil, warning: nil)
         raise ArgumentError.new('Specified type and bool') if bool && type.present?
 
@@ -122,6 +310,20 @@ module BBK
         }
       end
 
+      # Запускает обработку всех зарегистрированных параметров.
+      #
+      # Проходит по всем элементам хранилища и читает значения из источника.
+      # Рекурсивно обрабатывает все подконфигурации.
+      #
+      # @param source [Hash{String=>String}, #fetch] Источник значений (объект с методом #fetch, например ENV)
+      # @return [nil]
+      # @raise [RuntimeError] Если обязательный параметр отсутствует в источнике
+      #
+      # @example Чтение из ENV
+      #   config.run!
+      #
+      # @example Чтение из хэша
+      #   config.run!({ 'DATABASE_URL' => 'postgres://...' })
       def run!(source = ENV)
         @store.each_value do |item|
           process(source, item)
@@ -130,6 +332,26 @@ module BBK
         nil
       end
 
+      # Создаёт подконфигурацию с собственным префиксом.
+      #
+      # Переменные окружения подконфигурации получают дополнительный префикс.
+      # Например, при префиксе родителя 'APP' и префиксе подконфигурации 'DB',
+      # переменная 'HOST' будет читаться как 'APP_DB_HOST'.
+      #
+      # @param prefix [String, Symbol] Префикс подконфигурации
+      # @param name [String, nil] Имя подконфигурации
+      # @yield [sub] Блок для регистрации параметров подконфигурации
+      # @yieldparam sub [Config] Экземпляр подконфигурации
+      # @return [Config] Созданная подконфигурация
+      # @raise [ArgumentError] Если подконфигурация с таким префиксом уже существует
+      #
+      # @example
+      #   config = BBK::Utils::Config.instance(prefix: 'APP')
+      #   config.subconfig(prefix: 'DB', name: 'database') do |db|
+      #     db.require('HOST')
+      #     db.optional('PORT', default: '5432')
+      #   end
+      #   # Будут читаться переменные APP_DB_HOST и APP_DB_PORT
       def subconfig(prefix:, name: nil)
         raise ArgumentError.new("Subconfig with prefix #{prefix} already exists") if @subconfigs.any? {|sub| sub.prefix == prefix.to_s }
 
@@ -139,14 +361,43 @@ module BBK
         sub
       end
 
+      # Возвращает значение конфигурационного параметра.
+      #
+      # Поиск происходит с учётом префиксов, вверх по иерархии (к родителю)
+      # и вниз (в подконфигурации).
+      #
+      # @param key [String] Имя параметра
+      # @return [Object] Значение параметра
+      # @raise [Config::KeyError] Если параметр не найден
+      #
+      # @example
+      #   BBK::Utils::Config['LOG_LEVEL'] # => "info"
       def [](key)
         self.get(key, search_up: true, search_down: true)[:value]
       end
 
+      # Устанавливает значение конфигурационного параметра.
+      #
+      # @param key [String] Имя параметра
+      # @param value [Object] Новое значение
+      # @return [Object] Установленное значение
+      #
+      # @example
+      #   BBK::Utils::Config['LOG_LEVEL'] = 'debug'
       def []=(key, value)
         @store[normalize_key(key)][:value] = value
       end
 
+      # Возвращает содержимое параметра.
+      #
+      # Для файловых параметров читает содержимое файла.
+      # Для остальных возвращает значение.
+      #
+      # @param key [String] Имя параметра
+      # @return [String, Object] Содержимое файла или значение параметра
+      #
+      # @example
+      #   config.content('SSL_CERT') # => содержимое файла сертификата
       def content(key)
         item = @store[normalize_key(key)]
         if (file = item[:file])
@@ -156,6 +407,17 @@ module BBK
         end
       end
 
+      # Возвращает значение параметра или значение по умолчанию.
+      #
+      # В отличие от {#[]}, не выбрасывает исключение при отсутствии параметра.
+      #
+      # @param key [String] Имя параметра
+      # @param default [Object] Значение по умолчанию (по умолчанию: nil)
+      # @return [Object] Значение параметра или +default+
+      #
+      # @example
+      #   BBK::Utils::Config.fetch('LOG_LEVEL', 'warn') # => "info" (если значение установлено) или "warn" (если не установлено)
+      #   BBK::Utils::Config.fetch('NONEXISTENT', 'fallback') # => "fallback"
       def fetch(key, default = nil)
         if (rec = self.get(key, search_up: true, search_down: true)) && rec.key?(:value)
           rec[:value]
@@ -166,6 +428,19 @@ module BBK
         default
       end
 
+      # Возвращает человекочитаемое представление конфигурации.
+      #
+      # Выводит все параметры с их значениями, описаниями и статусом обязательности.
+      # Безопасные параметры отображаются как +[FILTERED]+.
+      #
+      # @return [String] Форматированный вывод конфигурации
+      #
+      # @example Вывод
+      #   # Environment variables:
+      #   #    <DATABASE_URL>                                     Строка подключения к БД
+      #   #       -> "postgres://localhost/mydb"
+      #   #    [LOG_LEVEL] (=info)                                Уровень логирования
+      #   #       -> "info"
       def to_s
         result = StringIO.new
         result.puts "Environment variables#{@name ? " for #{@name}" : ''}:"
@@ -184,6 +459,12 @@ module BBK
         result.string
       end
 
+      # Возвращает конфигурацию как хэш.
+      #
+      # @param _args [Array] Игнорируется (для совместимости с ActiveSupport)
+      # @return [Hash] Хэш вида { "ИМЯ_ПЕРЕМЕННОЙ" => { параметры } }
+      # @note Если в конфигурации используются кастомные type-кастеры (Method, Proc, Class),
+      #   поле `type` будет сериализовано как строковое представление объекта (например, "#<Method: Object(Kernel)#Integer(*)>").
       def as_json(*_args)
         values = store_with_subconfigs.values.sort_by do |item|
           [item[:file].present? ? 0 : 1, item[:required] ? 0 : 1]
@@ -194,22 +475,46 @@ module BBK
         @name ? { @name => values } : values
       end
 
+      # Возвращает конфигурацию в формате JSON.
+      #
+      # @param _args [Array] Игнорируется (для совместимости с ActiveSupport)
+      # @return [String] JSON-представление конфигурации
+      # @note Если в конфигурации используются кастомные type-кастеры (Method, Proc, Class),
+      #   поле `type` будет сериализовано как строковое представление объекта (например, "#<Method: Object(Kernel)#Integer(*)>").
       def to_json(*_args)
         JSON.pretty_generate(as_json)
       end
 
+      # Возвращает конфигурацию в формате YAML.
+      #
+      # @param _args [Array] Игнорируется (для совместимости с ActiveSupport)
+      # @return [String] YAML-представление конфигурации
+      # @note Если в конфигурации используются кастомные type-кастеры (Method, Proc, Class),
+      #   поле `type` будет сериализовано как строковое представление объекта (например, "#<Method: Object(Kernel)#Integer(*)>").
       def to_yaml(*_args)
         JSON.parse(to_json).to_yaml
       end
 
+      # Проверяет, является ли конфигурация корневой (не имеет родителя).
+      #
+      # @return [Boolean] +true+ если конфигурация корневая
       def root?
         @parent.nil?
       end
 
       protected
 
+        # @return [Array<String>] Массив префиксов от корня до текущего уровня
         attr_reader :prefixes
 
+        # Ищет конфигурационный элемент по ключу.
+        #
+        # @param key [String] Имя параметра
+        # @param search_up [Boolean] Искать в родительских конфигурациях
+        # @param search_down [Boolean] Искать в подконфигурациях
+        # @return [Hash] Конфигурационный элемент
+        # @raise [KeyError] Если параметр не найден
+        # @api private
         def get(key, search_up: false, search_down: false)
           normalized_key = normalize_key(key)
           return @store[normalized_key] if @store.key?(normalized_key)
@@ -232,6 +537,10 @@ module BBK
           raise KeyError.new("There is no such key: #{key} in config!")
         end
 
+        # Возвращает все элементы хранилища включая подконфигурации.
+        #
+        # @return [Hash] Объединённое хранилище всех уровней
+        # @api private
         def store_with_subconfigs
           res = @store.dup
           @subconfigs.each do |sub|
@@ -242,12 +551,22 @@ module BBK
 
       private
 
+        # Нормализует ключ: переводит в верхний регистр, заменяет дефисы на подчёркивания.
+        #
+        # @param key [String, nil] Ключ для нормализации
+        # @return [String, nil] Нормализованный ключ
+        # @api private
         def normalize_key(key)
           return nil if key.nil?
 
           key.to_s.upcase.gsub('-', '_')
         end
 
+        # Формирует полный ключ с учётом префикса.
+        #
+        # @param key [String] Базовый ключ
+        # @return [String] Ключ с префиксом (например, "APP_DB_HOST")
+        # @api private
         def full_prefixed_key(key)
           p_key = if env_prefix.empty?
             [key.to_s]
@@ -257,6 +576,11 @@ module BBK
           normalize_key(p_key)
         end
 
+        # Генерирует варианты ключей с разными комбинациями префиксов.
+        #
+        # @param key [String] Базовый ключ
+        # @return [Enumerator] Перечислитель вариантов ключей
+        # @api private
         def sub_prefixed_keys(key)
           Enumerator.new do |yielder|
             @prefixes.size.downto(0).each do |last_index|
@@ -265,6 +589,20 @@ module BBK
           end
         end
 
+        # Обрабатывает один конфигурационный элемент: читает значение из источника.
+        #
+        # Логика обработки:
+        # - Если значение присутствует или указан тип — обрабатывает значение
+        # - Для файловых параметров — записывает значение в файл
+        # - Для типизированных — применяет кастер типа
+        # - Если значение отсутствует и параметр обязательный — выбрасывает ошибку
+        # - Если значение отсутствует и параметр опциональный — использует дефолт
+        #
+        # @param source [Hash{String=>String}, #fetch] Источник значений (объект с методом #fetch, например ENV)
+        # @param item [Hash] Конфигурационный элемент из хранилища
+        # @return [void]
+        # @raise [RuntimeError] Если обязательный параметр отсутствует
+        # @api private
         def process(source, item)
           content = source.fetch(item[:env], item[:default])
 
@@ -305,10 +643,21 @@ module BBK
           raise
         end
 
+        # Выбрасывает ошибку об отсутствии обязательного параметра.
+        #
+        # @param item [Hash] Конфигурационный элемент
+        # @raise [RuntimeError] Всегда выбрасывает ошибку
+        # @api private
         def required!(item)
           raise "ENV [#{item[:env]}] is required!"
         end
 
+        # Формирует строку вывода для файлового параметра.
+        #
+        # @param item [Hash] Конфигурационный элемент
+        # @param padding [String] Отступ для форматирования
+        # @return [String] Форматированная строка
+        # @api private
         def print_file_item(item, padding)
           line = "#{padding}File #{wrap_required(item)}"
           line = if item[:desc].present?
@@ -320,11 +669,19 @@ module BBK
           "#{line}\n#{padding * 2}-> #{item[:file].inspect}"
         end
 
+        # Формирует строку вывода для обычного параметра.
+        #
+        # @param item [Hash] Конфигурационный элемент
+        # @param padding [String] Отступ для форматирования
+        # @return [String] Форматированная строка
+        # @api private
         def print_item(item, padding)
           line = padding + wrap_required(item)
           if item[:default].present?
             def_value = if item[:secure]
               FILTERED_VALUE
+            elsif item[:default].respond_to?(:secure_inspect)
+              item[:default].secure_inspect
             else
               item[:default]
             end
@@ -338,12 +695,22 @@ module BBK
           end
           value = if item[:secure]
             FILTERED_VALUE
+          elsif item[:value].respond_to?(:secure_inspect)
+            item[:value].secure_inspect
           else
             item[:value].inspect
           end
           "#{line}\n#{padding * 2}-> #{value}"
         end
 
+        # Оборачивает имя переменной в скобки в зависимости от обязательности.
+        #
+        # Обязательные параметры выводятся в угловых скобках: <ИМЯ>
+        # Опциональные параметры выводятся в квадратных скобках: [ИМЯ]
+        #
+        # @param item [Hash] Конфигурационный элемент
+        # @return [String] Имя переменной в скобках
+        # @api private
         def wrap_required(item)
           if item[:required]
             "<#{item[:env]}>"
@@ -354,5 +721,4 @@ module BBK
 
     end
   end
-end
-
+end

data/lib/bbk/utils/env_helper.rb

@@ -4,21 +4,119 @@ require 'uri'
 
 module BBK
   module Utils
+    # Вспомогательный модуль для сборки и нормализации переменных окружения
+    # при подключении к внешним сервисам.
+    #
+    # Предоставляет методы для конструирования URL-подключений из переменных окружения
+    # с интеллектуальными значениями по умолчанию и механизмом переопределения.
+    # Поддерживает базы данных, очереди сообщений и сервисы трейсинга.
+    #
+    # @example Базовое использование для конфигурации базы данных
+    #   env = {
+    #     'DATABASE_URL' => 'postgres://old:pass@oldhost:5432/olddb',
+    #     'DATABASE_HOST' => 'newhost',
+    #     'DATABASE_NAME' => 'newdb'
+    #   }
+    #   BBK::Utils::EnvHelper.prepare_database_envs(env)
+    #   # => env['DATABASE_URL'] = 'postgres://old:pass@newhost:5432/newdb'
+    #   # => env['DATABASE_HOST'] = 'newhost'
+    #   # => env['DATABASE_NAME'] = 'newdb'
+    #
+    # @note Все методы изменяют переданный хэш env in-place и возвращают его
     module EnvHelper
 
+      # @return [String] Префикс по умолчанию для переменных окружения, связанных с базой данных
       DEFAULT_DATABASE_PREFIX = 'DATABASE'
 
+      # Подготавливает переменные окружения для подключения к базе данных.
+      #
+      # Собирает URL подключения к БД из отдельных переменных окружения или
+      # переопределяет компоненты существующего URL. После сборки URL раскладывает
+      # его обратно в индивидуальные переменные окружения.
+      #
+      # Поддерживаемые переменные окружения (с префиксом):
+      # - {prefix}_URL - базовый URL (опционально, используется как шаблон)
+      # - {prefix}_ADAPTER - адаптер/схема БД (по умолчанию: 'postgresql')
+      # - {prefix}_HOST - хост БД (по умолчанию: 'db')
+      # - {prefix}_PORT - порт БД (по умолчанию: 5432)
+      # - {prefix}_USER - пользователь БД (по умолчанию: 'postgres')
+      # - {prefix}_PASS - пароль БД (по умолчанию: nil)
+      # - {prefix}_NAME - имя БД/путь
+      # - {prefix}_POOL - размер пула соединений. Используется **только если в {prefix}_URL присутствует query-строка** (не обязательно содержащая параметр `pool`). Если query-строки нет, значение игнорируется.
+      #
+      # @param env [Hash{String=>String}, ENV] Хэш переменных окружения или объект ENV (изменяется in-place)
+      # @param prefix [String] Префикс для имен переменных окружения
+      # @return [Hash{String=>String}, ENV] Тот же объект env (изменён in-place)
+      #
+      # @example Только с URL
+      #   env = { 'DATABASE_URL' => 'postgres://user:pass@host:5432/mydb' }
+      #   prepare_database_envs(env)
+      #   # => env['DATABASE_HOST'] = 'host', env['DATABASE_PORT'] = '5432', и т.д.
+      #
+      # @example С URL и переопределениями
+      #   env = { 'DATABASE_URL' => 'postgres://user:pass@host:5432/mydb', 'DATABASE_HOST' => 'newhost' }
+      #   prepare_database_envs(env)
+      #   # => env['DATABASE_URL'] = 'postgres://user:pass@newhost:5432/mydb'
+      #
+      # @example Только с индивидуальными переменными
+      #   env = { 'DATABASE_HOST' => 'myhost', 'DATABASE_NAME' => 'mydb' }
+      #   prepare_database_envs(env)
+      #   # => env['DATABASE_URL'] = 'postgresql://postgres@myhost:5432/mydb'
       def self.prepare_database_envs(env, prefix: DEFAULT_DATABASE_PREFIX)
         uri = build_uri_with_defaults(env, prefix: prefix)
         apply_env_from_uri(env, uri, prefix: prefix)
         env
       end
 
+      # Подготавливает переменные окружения для подключения к очереди сообщений.
+      #
+      # Собирает URL для MQ из переменных окружения с поддержкой нескольких хостов (кластер).
+      # Хосты могут быть указаны в виде списка, разделенного точкой с запятой или вертикальной чертой,
+      # в переменной MQ_HOST.
+      #
+      # Поддерживаемые переменные окружения:
+      # - MQ_URL - базовый URL-шаблон (опционально, используется первый, если несколько)
+      # - MQ_HOST - хост(ы), могут быть разделены ';' или '|' (по умолчанию: 'mq')
+      # - MQ_PORT - порт (по умолчанию: 5671)
+      # - MQ_USER - имя пользователя
+      # - MQ_PASS - пароль
+      # - MQ_VHOST - виртуальный хост (по умолчанию: '/')
+      #
+      # @param env [Hash{String=>String}, ENV] Хэш переменных окружения или объект ENV (изменяется in-place)
+      # @return [Hash{String=>String}, ENV] Тот же объект env (изменён in-place)
+      #
+      # @example Один хост
+      #   env = { 'MQ_HOST' => 'rabbitmq', 'MQ_USER' => 'guest' }
+      #   prepare_mq_envs(env)
+      #   # => env['MQ_URL'] = 'amqps://guest@rabbitmq:5671/'
+      #
+      # @example Несколько хостов (кластер)
+      #   env = { 'MQ_HOST' => 'mq1;mq2;mq3', 'MQ_USER' => 'guest' }
+      #   prepare_mq_envs(env)
+      #   # => env['MQ_URL'] = 'amqps://guest@mq1:5671/;amqps://guest@mq2:5671/;amqps://guest@mq3:5671/'
+      #   # => env['MQ_HOST'] = 'mq1;mq2;mq3'
       def self.prepare_mq_envs(env)
         apply_mq_env_from_uri(env, build_mq_uri_with_defaults(env))
         env
       end
 
+      # Подготавливает переменные окружения для Jaeger трейсинга.
+      #
+      # Собирает URL подключения к Jaeger из переменных окружения.
+      #
+      # Поддерживаемые переменные окружения:
+      # - JAEGER_URL - базовый URL (опционально)
+      # - JAEGER_SENDER - протокол/схема отправки (по умолчанию: 'udp')
+      # - JAEGER_HOST - хост Jaeger агента (по умолчанию: 'jaeger')
+      # - JAEGER_PORT - порт Jaeger агента (по умолчанию: 6831)
+      #
+      # @param env [Hash{String=>String}, ENV] Хэш переменных окружения или объект ENV (изменяется in-place)
+      # @return [Hash{String=>String}, ENV] Тот же объект env (изменён in-place)
+      #
+      # @example
+      #   env = { 'JAEGER_HOST' => 'jaeger-agent' }
+      #   prepare_jaeger_envs(env)
+      #   # => env['JAEGER_URL'] = 'udp://jaeger-agent:6831'
       def self.prepare_jaeger_envs(env)
         jaeger_uri = ::URI.parse(env['JAEGER_URL'] || '').tap do |uri|
           uri.scheme = env.fetch('JAEGER_SENDER', uri.scheme) || 'udp'
@@ -32,6 +130,18 @@ module BBK
         env
       end
 
+      # Собирает объект URI из переменных окружения со значениями по умолчанию.
+      # При отсутствии {prefix}_URL используется пустой URI (URI.parse('')).
+      #
+      # @note Приоритет для каждого компонента:
+      #   1. Индивидуальная переменная окружения (например, DATABASE_HOST)
+      #   2. Компонент из базового URL (например, host из DATABASE_URL)
+      #   3. Значение по умолчанию (например, 'db')
+      #
+      # @param env [Hash{String=>String}, ENV] Хэш переменных окружения или объект ENV
+      # @param prefix [String] Префикс для имен переменных окружения
+      # @return [URI::Generic] Сконструированный объект URI
+      # @api private
       def self.build_uri_with_defaults(env, prefix: DEFAULT_DATABASE_PREFIX)
         ::URI.parse(env[prefixed_key(prefix, 'URL')] || '').then do |uri|
           result = uri.clone
@@ -54,6 +164,13 @@ module BBK
         end
       end
 
+      # Раскладывает URI в индивидуальные переменные окружения.
+      #
+      # @param env [Hash{String=>String}, ENV] Хэш переменных окружения или объект ENV (изменяется in-place)
+      # @param uri [URI::Generic] Объект URI для декомпозиции
+      # @param prefix [String] Префикс для имен переменных окружения
+      # @return [void]
+      # @api private
       def self.apply_env_from_uri(env, uri, prefix: DEFAULT_DATABASE_PREFIX)
         env[prefixed_key(prefix, 'URL')] = uri.to_s
         env[prefixed_key(prefix, 'ADAPTER')] = uri.scheme
@@ -69,11 +186,16 @@ module BBK
         end
       end
 
+      # Собирает объекты URI для MQ из переменных окружения с поддержкой нескольких хостов.
+      #
+      # @param env [Hash{String=>String}, ENV] Хэш переменных окружения или объект ENV
+      # @return [Array<URI>] Массив объектов URI (по одному на каждый хост)
+      # @api private
       def self.build_mq_uri_with_defaults(env)
-        # Only first MQ_URL selected as template if any
+        # Только первый MQ_URL выбирается как шаблон, если их несколько
         url = [env.fetch('MQ_URL', '').split(/[;|]/)].flatten.select(&:present?).first || ''
 
-        # all hosts if form of list fills url template
+        # Все хосты в виде списка заполняют шаблон URL
         hosts = [env.fetch('MQ_HOST',
                            URI.parse(url).hostname || 'mq').split(/[;|]/)].flatten.select(&:present?).uniq
 
@@ -95,6 +217,12 @@ module BBK
         end
       end
 
+      # Раскладывает URI для MQ в переменные окружения.
+      #
+      # @param env [Hash{String=>String}, ENV] Хэш переменных окружения или объект ENV (изменяется in-place)
+      # @param uris [Array<URI>] Массив объектов URI
+      # @return [void]
+      # @api private
       def self.apply_mq_env_from_uri(env, uris)
         uri = uris.first
 
@@ -111,11 +239,16 @@ module BBK
         env['MQ_VHOST'] = vhost
       end
 
+      # Конструирует имя переменной окружения с префиксом.
+      #
+      # @param prefix [String] Префикс (например, 'DATABASE')
+      # @param name [String] Имя переменной (например, 'HOST')
+      # @return [String] Объединенное имя (например, 'DATABASE_HOST')
+      # @api private
       def self.prefixed_key(prefix, name)
         [prefix, name].select(&:present?).join('_')
       end
 
     end
   end
-end
-
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bbk-utils
 version: !ruby/object:Gem::Version
-  version: 1.1.6.376358
+  version: 1.1.6.409139
 platform: ruby
 authors:
 - Samoilenko Yuri
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport