optify-config 1.4.2

data/lib/optify_ruby/provider_module.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module Optify
+  # @!visibility private
+  module ProviderModule
+    extend T::Sig
+
+    #: (Array[String] feature_names) -> Array[String]
+    def get_canonical_feature_names(feature_names)
+      # Try to optimize a typical case where there are just a few features.
+      # Ideally in production, a single feature that imports many other features is used for the most common scenarios.
+      # Benchmarks show that it is faster to use a loop than to call the Rust implementation which involves making a `Vec<String>` and returning a `Vec<String>`.
+      if feature_names.length < 4
+        feature_names.map { |feature_name| get_canonical_feature_name(feature_name) }
+      else
+        _get_canonical_feature_names(feature_names)
+      end
+    end
+
+    #: (String canonical_feature_name) -> Optify::OptionsMetadata?
+    def get_feature_metadata(canonical_feature_name)
+      metadata_json = get_feature_metadata_json(canonical_feature_name)
+      return nil if metadata_json.nil?
+
+      OptionsMetadata.from_hash(JSON.parse(metadata_json))
+    end
+
+    private
+
+    #: -> Hash[String, OptionsMetadata]
+    def _features_with_metadata
+      return @features_with_metadata if @features_with_metadata
+
+      result = JSON.parse(features_with_metadata_json)
+      result.each do |key, value|
+        result[key] = OptionsMetadata.from_hash(value)
+      end
+      result.freeze
+
+      @features_with_metadata = T.let(result, T.nilable(T::Hash[String, OptionsMetadata]))
+      result
+    end
+
+    # Fetches options based on the provided key and feature names.
+    #
+    # @param key The key to fetch options for.
+    # @param feature_names The enabled feature names to use to build the options.
+    # @param config_class The class of the configuration to return.
+    # The class must implement `from_hash` as a class method to convert a hash to an instance of the class.
+    # It is recommended to use a class that extends `Optify::BaseConfig` because it implements `from_hash`.
+    # @param cache_options Set this if caching is desired. Only very simple caching is supported for now.
+    # @param preferences The preferences to use when getting options.
+    # @return The options.
+    #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+    def _get_options(key, feature_names, config_class, cache_options = nil, preferences = nil)
+      return get_options_with_cache(key, feature_names, config_class, cache_options, preferences) if cache_options
+
+      unless config_class.respond_to?(:from_hash)
+        Kernel.raise NotImplementedError,
+                     "The provided config class must implement `from_hash` as a class method
+              in order to be converted.
+              Recommended: extend `Optify::BaseConfig`."
+      end
+
+      options_json = if preferences
+                       get_options_json_with_preferences(key, feature_names, preferences)
+                     else
+                       get_options_json(key, feature_names)
+                     end
+      hash = JSON.parse(options_json)
+      T.unsafe(config_class).from_hash(hash)
+    end
+
+    #: -> void
+    def _init
+      @cache = T.let({}, T.nilable(T::Hash[T.untyped, T.untyped]))
+      @features_with_metadata = T.let(nil, T.nilable(T::Hash[String, OptionsMetadata]))
+    end
+
+    NOT_FOUND_IN_CACHE_SENTINEL = Object.new
+
+    #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, Optify::CacheOptions _cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+    def get_options_with_cache(key, feature_names, config_class, _cache_options, preferences = nil)
+      # Cache directly in Ruby instead of Rust because:
+      # * Avoid any possible conversion overhead.
+      # * Memory management: probably better to do it in Ruby for a Ruby app and avoid memory in Rust.
+      if preferences&.overrides?
+        Kernel.raise ArgumentError,
+                     'Caching when overrides are given is not supported. Do not pass cache options when using overrides in preferences.'
+      end
+
+      init unless @cache
+      feature_names = get_canonical_feature_names(feature_names) unless preferences&.skip_feature_name_conversion
+
+      cache_key = [key, feature_names, config_class]
+      result = @cache&.fetch(cache_key, NOT_FOUND_IN_CACHE_SENTINEL)
+      return result unless result.equal?(NOT_FOUND_IN_CACHE_SENTINEL)
+
+      # Handle a cache miss.
+
+      # We can avoid converting the features names because they're already converted, if that was desired.
+      if preferences.nil?
+        preferences = GetOptionsPreferences.new
+        preferences.skip_feature_name_conversion = true
+      else
+        # Indeed the copying of preferences could be wasteful, but this only happens on a cache miss
+        # and when no custom preferences are provided.
+        preferences = preferences.dup
+        preferences.skip_feature_name_conversion = true
+      end
+
+      result = get_options(key, feature_names, config_class, nil, preferences)
+
+      T.must(@cache)[cache_key] = result
+    end
+  end
+end

data/lib/optify_ruby/watcher_implementation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'json'
+
+require 'sorbet-runtime'
+
+require_relative './base_config'
+require_relative './implementation'
+require_relative './options_metadata'
+require_relative './provider_module'
+
+module Optify
+  # @!visibility private
+  class OptionsWatcher
+    include ProviderModule
+
+    # TODO: Find a better way to proxy the methods with copying the parameters.
+
+    #: -> Hash[String, OptionsMetadata]
+    def features_with_metadata
+      _check_cache
+      _features_with_metadata
+    end
+
+    #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+    def get_options(key, feature_names, config_class, cache_options = nil, preferences = nil)
+      _check_cache if cache_options
+
+      _get_options(key, feature_names, config_class, cache_options, preferences)
+    end
+
+    # (Optional) Eagerly initializes the cache.
+    # @return [OptionsWatcher] `self`.
+    #: -> OptionsWatcher
+    def init
+      _init
+      @cache_creation_time = T.let(Time.now, T.nilable(Time))
+      self
+    end
+
+    private
+
+    #: -> void
+    def _check_cache
+      return if @cache_creation_time && @cache_creation_time > last_modified
+
+      # The cache is not setup or it is out of date.
+      init
+    end
+  end
+end

data/rbi/optify.rbi

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+# typed: strong
+
+# Tools for working with configurations declared in files.
+module Optify
+  # A base class for classes from configuration files.
+  # Classes that derive from this can easily be used with `Optify::OptionsProvider.get_options`
+  # because they will have an implementation of `from_hash` that works recursively.
+  # This class is a work in progress with minimal error handling
+  # and doesn't handle certain cases such as nilable types yet.
+  # It may be moved to another gem in the future.
+  class BaseConfig
+    abstract!
+
+    # Create a new instance of the class from a hash.
+    #
+    # This is a class method that so that it can set members with private setters.
+    # @param hash The hash to create the instance from.
+    # @return The new instance.
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.attached_class) }
+    def self.from_hash(hash); end
+  end
+
+  # Options for caching.
+  # Only enabling or disabling caching is supported for now.
+  class CacheOptions < BaseConfig
+  end
+
+  # Information about a feature.
+  class OptionsMetadata < BaseConfig
+    sig { returns(T.nilable(T::Array[String])) }
+    def aliases; end
+
+    sig { returns(T.untyped) }
+    def details; end
+
+    sig { returns(String) }
+    def name; end
+
+    sig { returns(T.nilable(String)) }
+    def owners; end
+  end
+
+  # Preferences when getting options.
+  class GetOptionsPreferences
+    # Indicates if overrides are set.
+    sig { returns(T::Boolean) }
+    def overrides?; end
+
+    # Set overrides to apply after building the options based on the feature names.
+    # Do not provide overrides when requesting cached options.
+    # @param value The overrides to apply.
+    sig { params(value: T.nilable(T::Hash[T.untyped, T.untyped])).void }
+    def overrides=(value); end
+
+    # Set overrides to apply after building the options based on the feature names.
+    # Do not provide overrides when requesting cached options.
+    # @param value The overrides to apply as serialized JSON.
+    sig { params(value: T.nilable(String)).void }
+    def overrides_json=(value); end
+
+    sig { params(value: T::Boolean).void }
+    def skip_feature_name_conversion=(value); end
+
+    sig { returns(T::Boolean) }
+    def skip_feature_name_conversion; end
+  end
+
+  # A registry of features that provides configurations.
+  class OptionsRegistry
+    abstract!
+
+    # @return All of the canonical feature names.
+    sig { returns(T::Array[String]) }
+    def features; end
+
+    # @return All of the keys and values for the the features.
+    sig { returns(T::Hash[String, OptionsMetadata]) }
+    def features_with_metadata; end
+
+    # @return All of the keys and values for the the features.
+    sig do
+      params(feature_names: T::Array[String], preferences: GetOptionsPreferences)
+        .returns(String)
+    end
+    def get_all_options_json(feature_names, preferences); end
+  end
+
+  # A module only for internal use that provides the methods to help implement providers.
+  # Some of the methods shown within this module are implemented in Rust
+  # and are declared in this common module to avoid duplicate declarations in different classes.
+  module ProviderModule
+    # Map an alias or canonical feature name (perhaps derived from a file name) to a canonical feature name.
+    # Canonical feature names map to themselves.
+    #
+    # @param feature_name The name of an alias or a feature.
+    # @return The canonical feature name.
+    sig { params(feature_name: String).returns(String) }
+    def get_canonical_feature_name(feature_name); end
+
+    # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
+    # Canonical feature names map to themselves.
+    # This implementation may do an optimization for small arrays.
+    #
+    # @param feature_names The names of aliases or features.
+    # @return The canonical feature names.
+    sig { params(feature_names: T::Array[String]).returns(T::Array[String]) }
+    def get_canonical_feature_names(feature_names); end
+
+    # @return The metadata for the feature.
+    sig { params(canonical_feature_name: String).returns(T.nilable(OptionsMetadata)) }
+    def get_feature_metadata(canonical_feature_name); end
+
+    # Fetches options based on the provided key and feature names.
+    #
+    # @param key The key to fetch options for.
+    # @param feature_names The enabled feature names to use to build the options.
+    # @param config_class The class of the configuration to return.
+    # The class must implement `from_hash` as a class method to convert a hash to an instance of the class.
+    # It is recommended to use a class that extends `Optify::BaseConfig` because it implements `from_hash`.
+    # @param cache_options Set this if caching is desired. Only very simple caching is supported for now.
+    # @param preferences The preferences to use when getting options.
+    # @return The options.
+    sig do
+      type_parameters(:Config)
+        .params(
+          key: String,
+          feature_names: T::Array[String],
+          config_class: T::Class[T.type_parameter(:Config)],
+          cache_options: T.nilable(CacheOptions),
+          preferences: T.nilable(Optify::GetOptionsPreferences)
+        )
+        .returns(T.type_parameter(:Config))
+    end
+    def get_options(key, feature_names, config_class, cache_options = nil, preferences = nil); end
+
+    # Fetches options in JSON format based on the provided key and feature names.
+    #
+    # @param key [String] the key to fetch options for.
+    # @param feature_names [Array<String>] The enabled feature names to use to build the options.
+    # @return [String] the options in JSON.
+    sig { params(key: String, feature_names: T::Array[String]).returns(String) }
+    def get_options_json(key, feature_names); end
+
+    # Fetches options in JSON format based on the provided key and feature names.
+    #
+    # @param key [String] the key to fetch options for.
+    # @param feature_names [Array<String>] The enabled feature names to use to build the options.
+    # @param preferences [GetOptionsPreferences] The preferences to use when getting options.
+    # @return [String] the options in JSON.
+    sig do
+      params(key: String, feature_names: T::Array[String], preferences: GetOptionsPreferences)
+        .returns(String)
+    end
+    def get_options_json_with_preferences(key, feature_names, preferences); end
+
+    # (Optional) Eagerly initializes the cache.
+    # @return `self`.
+    sig { returns(T.self_type) }
+    def init; end
+
+    private
+
+    # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
+    # Canonical feature names map to themselves.
+    # This implementation calls the Rust implementation directly.
+    #
+    # @param feature_names The names of aliases or features.
+    # @return The canonical feature names.
+    sig { params(feature_names: T::Array[String]).returns(T::Array[String]) }
+    def _get_canonical_feature_names(feature_names); end
+
+    # @return The metadata for the feature.
+    sig { params(canonical_feature_name: String).returns(T.nilable(String)) }
+    def get_feature_metadata_json(canonical_feature_name); end
+
+    # @return All of the keys and values for the the features.
+    sig { returns(String) }
+    def features_with_metadata_json; end
+  end
+
+  # Provides configurations based on keys and enabled feature names.
+  class OptionsProvider < OptionsRegistry
+    include ProviderModule
+  end
+
+  # A builder for creating an `OptionsProvider` instance.
+  class OptionsProviderBuilder
+    # Adds a directory to the builder.
+    #
+    # @param path [String] The path of the directory to add.
+    # @return [OptionsProviderBuilder] `self`.
+    sig { params(path: String).returns(OptionsProviderBuilder) }
+    def add_directory(path); end
+
+    # @return [OptionsProvider] A newly built `OptionsProvider`.
+    sig { returns(OptionsProvider) }
+    def build; end
+  end
+
+  # Like `OptionsProvider` but also watches for changes to the files and reloads the options.
+  class OptionsWatcher < OptionsRegistry
+    include ProviderModule
+
+    # @return [Time] Returns the time when the provider was finished building.
+    sig { returns(Time) }
+    def last_modified; end
+  end
+
+  # A builder for creating an `OptionsWatcher` instance.
+  #
+  # This builder is kept separate from the `OptionsProviderBuilder`
+  # in order to keep `OptionsProviderBuilder` and `OptionsProvider` as simple and efficient as possible for production use.
+  class OptionsWatcherBuilder
+    # Adds a directory to watch for changes.
+    #
+    # @param path [String] The path of the directory to add.
+    # @return [OptionsWatcherBuilder] `self`.
+    sig { params(path: String).returns(OptionsWatcherBuilder) }
+    def add_directory(path); end
+
+    # @return [OptionsWatcher] A newly built `OptionsWatcher`.
+    sig { returns(OptionsWatcher) }
+    def build; end
+  end
+end

data/sig/optify.rbs

@@ -0,0 +1,157 @@
+# Tools for working with configurations declared in files.
+module Optify
+end
+
+# A base class for classes from configuration files.
+# Classes that derive from this can easily be used with `Optify::OptionsProvider.get_options`
+# because they will have an implementation of `from_hash` that works recursively.
+# This class is a work in progress with minimal error handling
+# and doesn't handle certain cases such as nilable types yet.
+# It may be moved to another gem in the future.
+class Optify::BaseConfig
+  # Create a new instance of the class from a hash.
+  #
+  # This is a class method that so that it can set members with private setters.
+  # @param hash The hash to create the instance from.
+  # @return The new instance.
+  def self.from_hash: (::Hash[untyped, untyped] hash) -> instance
+end
+
+# Options for caching.
+# Only enabling or disabling caching is supported for now.
+class Optify::CacheOptions < BaseConfig
+end
+
+# Information about a feature.
+class Optify::OptionsMetadata < BaseConfig
+  def aliases: () -> ::Array[String]?
+
+  def details: () -> untyped
+
+  def name: () -> String
+
+  def owners: () -> String?
+end
+
+# Preferences when getting options.
+class Optify::GetOptionsPreferences
+  # Indicates if overrides are set.
+  def overrides?: () -> bool
+
+  # Set overrides to apply after building the options based on the feature names.
+  # Do not provide overrides when requesting cached options.
+  # @param value The overrides to apply.
+  def overrides=: (::Hash[untyped, untyped]? value) -> void
+
+  # Set overrides to apply after building the options based on the feature names.
+  # Do not provide overrides when requesting cached options.
+  # @param value The overrides to apply as serialized JSON.
+  def overrides_json=: (String? value) -> void
+
+  def skip_feature_name_conversion=: (bool value) -> void
+
+  def skip_feature_name_conversion: () -> bool
+end
+
+# A registry of features that provides configurations.
+class Optify::OptionsRegistry
+  # @return All of the canonical feature names.
+  def features: () -> ::Array[String]
+
+  # @return All of the keys and values for the the features.
+  def features_with_metadata: () -> ::Hash[String, OptionsMetadata]
+
+  def get_all_options_json: (::Array[String] feature_names, GetOptionsPreferences preferences) -> String
+end
+
+# A module only for internal use that provides the methods to help implement providers.
+# Some of the methods shown within this module are implemented in Rust
+# and are declared in this common module to avoid duplicate declarations in different classes.
+module Optify::ProviderModule
+  # Map an alias or canonical feature name (perhaps derived from a file name) to a canonical feature name.
+  # Canonical feature names map to themselves.
+  #
+  # @param feature_name The name of an alias or a feature.
+  # @return The canonical feature name.
+  def get_canonical_feature_name: (String feature_name) -> String
+
+  # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
+  # Canonical feature names map to themselves.
+  # This implementation may do an optimization for small arrays.
+  #
+  # @param feature_names The names of aliases or features.
+  # @return The canonical feature names.
+  def get_canonical_feature_names: (::Array[String] feature_names) -> ::Array[String]
+
+  # @return The metadata for the feature.
+  def get_feature_metadata: (String canonical_feature_name) -> OptionsMetadata?
+
+  def get_options: [Config] (String key, ::Array[String] feature_names, T::Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+
+  # Fetches options in JSON format based on the provided key and feature names.
+  #
+  # @param key [String] the key to fetch options for.
+  # @param feature_names [Array<String>] The enabled feature names to use to build the options.
+  # @return [String] the options in JSON.
+  def get_options_json: (String key, ::Array[String] feature_names) -> String
+
+  def get_options_json_with_preferences: (String key, ::Array[String] feature_names, GetOptionsPreferences preferences) -> String
+
+  # (Optional) Eagerly initializes the cache.
+  # @return `self`.
+  def init: () -> self
+
+  # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
+  # Canonical feature names map to themselves.
+  # This implementation calls the Rust implementation directly.
+  #
+  # @param feature_names The names of aliases or features.
+  # @return The canonical feature names.
+  def _get_canonical_feature_names: (::Array[String] feature_names) -> ::Array[String]
+
+  # @return The metadata for the feature.
+  def get_feature_metadata_json: (String canonical_feature_name) -> String?
+
+  # @return All of the keys and values for the the features.
+  def features_with_metadata_json: () -> String
+end
+
+# Provides configurations based on keys and enabled feature names.
+class Optify::OptionsProvider < OptionsRegistry
+  include ProviderModule
+end
+
+# A builder for creating an `OptionsProvider` instance.
+class Optify::OptionsProviderBuilder
+  # Adds a directory to the builder.
+  #
+  # @param path [String] The path of the directory to add.
+  # @return [OptionsProviderBuilder] `self`.
+  def add_directory: (String path) -> OptionsProviderBuilder
+
+  # @return [OptionsProvider] A newly built `OptionsProvider`.
+  def build: () -> OptionsProvider
+end
+
+# Like `OptionsProvider` but also watches for changes to the files and reloads the options.
+class Optify::OptionsWatcher < OptionsRegistry
+  include ProviderModule
+
+  # @return [Time] Returns the time when the provider was finished building.
+  def last_modified: () -> Time
+end
+
+# A builder for creating an `OptionsWatcher` instance.
+#
+# This builder is kept separate from the `OptionsProviderBuilder`
+# in order to keep `OptionsProviderBuilder` and `OptionsProvider` as simple and efficient as possible for production use.
+class Optify::OptionsWatcherBuilder
+  # Adds a directory to watch for changes.
+  #
+  # @param path [String] The path of the directory to add.
+  # @return [OptionsWatcherBuilder] `self`.
+  def add_directory: (String path) -> OptionsWatcherBuilder
+
+  # @return [OptionsWatcher] A newly built `OptionsWatcher`.
+  def build: () -> OptionsWatcher
+end