convert_sdk 1.0.0

data/lib/convert_sdk/config.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # The SDK's configuration surface and wire-translation boundary #1.
+  #
+  # +Config+ is the ONE place in the gem where the inbound public naming world
+  # (idiomatic snake_case keyword arguments) is translated into the internal /
+  # wire naming world (string-keyed camelCase). The only other naming-world
+  # conversion site in the entire gem is the outbound payload builder in
+  # ApiManager (Story 4.1); any other file converting option names is an
+  # architecture violation (the two-worlds rule).
+  #
+  # == JS-parity defaults
+  #
+  # {DEFAULTS} carries the frozen JS-parity values — batch 10, flush interval
+  # 1s, data-refresh 300s, bucketing seed 9999 / max-traffic 10000 / max-hash
+  # 2**32. These exact numbers are restated across the PRD, architecture, and
+  # research; they are NOT tuning knobs and must not drift. Endpoint URLs are
+  # copied verbatim from the reference SDKs' default config.
+  #
+  # == Fail-fast validation (the SDK's only raising surface)
+  #
+  # Construction delegates to {ConfigValidator}, which raises a stdlib
+  # +ArgumentError+ — naming the offending option and the expected type — for any
+  # presence/type violation. This is the SDK's ONLY raising surface (Decision 3):
+  # there is no custom exception hierarchy, because the SDK degrades gracefully
+  # (cached config / sentinels) for every runtime/infra failure, leaving nothing
+  # for a hierarchy to hold. Misconfiguration therefore surfaces immediately at
+  # boot rather than as silent misbehavior in production. Unknown option keys are
+  # rejected for the same reason — a typo fails fast instead of being ignored.
+  #
+  # == Nil-able timer intervals (Lambda / CLI mode)
+  #
+  # +flush_interval+ and +data_refresh_interval+ accept +nil+, meaning
+  # timer-off: the background flush / refresh threads are never started. This is
+  # the AWS Lambda and plain-CLI recipe (synchronous flush before exit; no
+  # background threads). +flush_interval+ is the canonical flush-timer key
+  # throughout the gem (the older +event_release_interval+ alias is retired).
+  #
+  # == Secret registration (NFR5)
+  #
+  # When an +sdk_key+ / +sdk_key_secret+ is present and a {LogManager} is
+  # injected, +Config+ registers those values with the manager's {Redactor}
+  # immediately at construction — so secrets are armed before any log line can
+  # carry them. +Config+ is constructible standalone (no +log_manager+) for unit
+  # tests; +ConvertSdk.create+ / Client (Story 2.5) injects the real manager.
+  class Config
+    # Number of milliseconds per second — the +flush_interval+ second→ms wire
+    # translation factor.
+    MILLISECONDS_PER_SECOND = 1000
+
+    # The fixed bucketing hash space (2**32). A JS-parity constant, not a
+    # configurable option — exposed as a reader for the bucketing engine.
+    MAX_HASH = 4_294_967_296
+
+    # The frozen JS-parity defaults for every public option. Verified against
+    # javascript-sdk +config/default.ts+ and php-sdk +DefaultConfig.php+.
+    DEFAULTS = {
+      # Auth / data — at least one of sdk_key / data is required (validated).
+      sdk_key: nil,
+      sdk_key_secret: nil,
+      data: nil,
+      # Platform environment selector; nil leaves it to the platform default.
+      environment: nil,
+      # Live Convert endpoints (verbatim from the reference default config).
+      config_endpoint: "https://cdn-4.convertexperiments.com/api/v1",
+      track_endpoint: "https://[project_id].metrics.convertexperiments.com/v1",
+      # Bucketing constants — frozen JS-parity numbers, do not tune.
+      max_traffic: 10_000,
+      hash_seed: 9999,
+      # Config-refresh cadence in seconds (JS 300000 ms); nil = timer-off.
+      data_refresh_interval: 300,
+      # Event delivery — batch size and flush cadence (seconds); nil = timer-off.
+      event_batch_size: 10,
+      flush_interval: 1,
+      # Rule evaluation options.
+      keys_case_sensitive: true,
+      negation: "!",
+      # Logging verbosity (JS default.ts:29 logLevel: LogLevel.DEBUG).
+      log_level: LogLevel::DEBUG,
+      # Network tracking enable/disable.
+      tracking: true,
+      # HTTP client timeouts in seconds (consumed by HttpClient, Story 1.5).
+      open_timeout: 5,
+      read_timeout: 10
+    }.freeze
+
+    # @!attribute [r] sdk_key
+    #   @return [String, nil] account/project SDK key (JS +sdkKey+). Path auth.
+    # @!attribute [r] sdk_key_secret
+    #   @return [String, nil] bearer secret (JS +sdkKeySecret+). Redacted.
+    # @!attribute [r] data
+    #   @return [Hash, nil] inline config payload (JS +data+); skips fetch.
+    # @!attribute [r] environment
+    #   @return [String, nil] platform environment (JS +environment+).
+    # @!attribute [r] config_endpoint
+    #   @return [String] config-fetch base URL (JS +api.endpoint.config+).
+    # @!attribute [r] track_endpoint
+    #   @return [String] tracking base URL (JS +api.endpoint.track+).
+    # @!attribute [r] max_traffic
+    #   @return [Integer] bucketing max traffic (JS +bucketing.max_traffic+).
+    # @!attribute [r] hash_seed
+    #   @return [Integer] bucketing hash seed (JS +bucketing.hash_seed+).
+    # @!attribute [r] data_refresh_interval
+    #   @return [Numeric, nil] config-refresh seconds; nil = timer-off
+    #     (JS +dataRefreshInterval+, ms).
+    # @!attribute [r] event_batch_size
+    #   @return [Integer] event flush batch size (JS +events.batch_size+).
+    # @!attribute [r] flush_interval
+    #   @return [Numeric, nil] flush cadence seconds; nil = timer-off
+    #     (JS +events.release_interval+, ms). Canonical flush-timer key.
+    # @!attribute [r] keys_case_sensitive
+    #   @return [Boolean] rule key case sensitivity (JS +rules.keys_case_sensitive+).
+    # @!attribute [r] negation
+    #   @return [String] rule negation token (JS +rules.negation+, default "!").
+    # @!attribute [r] log_level
+    #   @return [Integer] a {LogLevel} threshold (JS +logger.logLevel+).
+    # @!attribute [r] tracking
+    #   @return [Boolean] network tracking enabled (JS +network.tracking+).
+    # @!attribute [r] open_timeout
+    #   @return [Numeric] HTTP connect timeout seconds (HttpClient, NFR3).
+    # @!attribute [r] read_timeout
+    #   @return [Numeric] HTTP read timeout seconds (HttpClient, NFR3).
+    attr_reader :sdk_key, :sdk_key_secret, :data, :environment,
+                :config_endpoint, :track_endpoint, :max_traffic, :hash_seed,
+                :data_refresh_interval, :event_batch_size, :flush_interval,
+                :keys_case_sensitive, :negation, :log_level, :tracking,
+                :open_timeout, :read_timeout
+
+    # Build a validated configuration from snake_case keyword options merged over
+    # {DEFAULTS}. Raises +ArgumentError+ (the SDK's only raising surface) on any
+    # presence/type violation or unknown option key.
+    #
+    # @param log_manager [LogManager, nil] when provided, present secrets
+    #   (sdk_key / sdk_key_secret) are registered with its {Redactor} so they
+    #   are armed before any log line. Optional for standalone construction.
+    # @param options [Hash{Symbol=>Object}] any subset of the {DEFAULTS} keys.
+    # @raise [ArgumentError] on unknown keys, missing sdk_key+data, or bad types.
+    def initialize(log_manager: nil, **options)
+      reject_unknown_keys(options)
+      merged = DEFAULTS.merge(options)
+      assign(merged)
+      ConfigValidator.new(merged).validate!
+      register_secrets(log_manager)
+    end
+
+    # @return [Integer] the fixed bucketing hash space (2**32).
+    def max_hash
+      MAX_HASH
+    end
+
+    # The wire-translation boundary: the internal, string-keyed camelCase
+    # representation downstream managers (DataManager / ApiManager) consume. This
+    # is the single inbound conversion site. +flush_interval+ seconds are
+    # translated to the millisecond wire value here; nil passes through (timer-off).
+    #
+    # @return [Hash{String=>Object}] a frozen internal config snapshot.
+    def to_internal
+      {
+        "sdkKey" => @sdk_key,
+        "sdkKeySecret" => @sdk_key_secret,
+        "data" => @data,
+        "environment" => @environment,
+        "configEndpoint" => @config_endpoint,
+        "trackEndpoint" => @track_endpoint,
+        "maxTraffic" => @max_traffic,
+        "hashSeed" => @hash_seed,
+        "maxHash" => MAX_HASH,
+        "dataRefreshInterval" => @data_refresh_interval,
+        "batchSize" => @event_batch_size,
+        "releaseInterval" => to_milliseconds(@flush_interval),
+        "keysCaseSensitive" => @keys_case_sensitive,
+        "negation" => @negation,
+        "logLevel" => @log_level,
+        "tracking" => @tracking
+      }.freeze
+    end
+
+    # The canonical set of accepted option keys (the {DEFAULTS} keys).
+    KNOWN_KEYS = DEFAULTS.keys.freeze
+
+    private
+
+    # Copy every merged option into its like-named instance variable.
+    def assign(merged)
+      merged.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    # Reject any option key not in {KNOWN_KEYS} — a typo fails fast at boot.
+    def reject_unknown_keys(options)
+      unknown = options.keys - KNOWN_KEYS
+      return if unknown.empty?
+
+      raise ArgumentError, "unknown configuration option(s): #{unknown.join(", ")}"
+    end
+
+    # Translate a seconds interval to the millisecond wire value; nil passes
+    # through unchanged (timer-off).
+    def to_milliseconds(seconds)
+      return nil if seconds.nil?
+
+      seconds * MILLISECONDS_PER_SECOND
+    end
+
+    # Arm the Redactor with present secrets so no log line can leak them. A nil
+    # log_manager (standalone construction) is a no-op.
+    def register_secrets(log_manager)
+      return if log_manager.nil?
+
+      log_manager.register_secret(@sdk_key) unless @sdk_key.nil?
+      log_manager.register_secret(@sdk_key_secret) unless @sdk_key_secret.nil?
+    end
+  end
+end

data/lib/convert_sdk/config_validator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module ConvertSdk
+  # The fail-fast validation rules for {Config} — the SDK's only raising surface.
+  #
+  # +ConfigValidator+ holds every presence/type rule for the configuration
+  # surface, extracted from {Config} so the surface class stays focused on
+  # naming-world translation and typed readers while the (uniform, table-like)
+  # validation rules live in one cohesive place. Every violation raises a stdlib
+  # +ArgumentError+ naming the offending option and the expected type; there is
+  # no custom exception hierarchy anywhere in the SDK (Decision 3).
+  #
+  # Rules:
+  #
+  # * presence — at least one of +sdk_key+ / +data+ must be present (FR6);
+  # * strings — +sdk_key+ / +sdk_key_secret+ / +environment+ / +config_endpoint+
+  #   / +track_endpoint+ / +negation+ must be String (nil accepted for the
+  #   optional ones); +data+ must be a Hash when present;
+  # * integers — +max_traffic+ / +hash_seed+ / +event_batch_size+;
+  # * intervals — +data_refresh_interval+ / +flush_interval+ are Numeric or nil
+  #   (nil = timer-off); +open_timeout+ / +read_timeout+ are Numeric;
+  # * booleans — +keys_case_sensitive+ / +tracking+ (strict true/false);
+  # * log level — must be one of the {LogLevel} values.
+  class ConfigValidator
+    # The accepted {LogLevel} integer values (TRACE..SILENT).
+    LOG_LEVEL_VALUES = [
+      LogLevel::TRACE, LogLevel::DEBUG, LogLevel::INFO,
+      LogLevel::WARN, LogLevel::ERROR, LogLevel::SILENT
+    ].freeze
+
+    # @param values [Hash{Symbol=>Object}] the merged option values, keyed by the
+    #   public snake_case option names (the {Config::DEFAULTS} keys).
+    def initialize(values)
+      @values = values
+    end
+
+    # Run every rule. The first violation raises; presence is checked first so a
+    # wholly-empty config reports the most useful fault.
+    #
+    # @raise [ArgumentError] on any presence/type violation.
+    # @return [void]
+    def validate!
+      validate_presence!
+      validate_strings!
+      validate_integers!
+      validate_intervals!
+      validate_booleans!
+      validate_log_level!
+    end
+
+    private
+
+    # At least one of sdk_key / data must be present (FR6).
+    def validate_presence!
+      return unless @values[:sdk_key].nil? && @values[:data].nil?
+
+      raise ArgumentError, "configuration requires sdk_key or data (at least one)"
+    end
+
+    # String-or-nil options, plus the Hash-or-nil data option.
+    def validate_strings!
+      %i[sdk_key sdk_key_secret environment config_endpoint track_endpoint negation].each do |name|
+        require_string(name, @values[name])
+      end
+      require_type(:data, @values[:data], Hash) unless @values[:data].nil?
+    end
+
+    # Integer options (bucketing constants and batch size).
+    def validate_integers!
+      %i[max_traffic hash_seed event_batch_size].each do |name|
+        require_type(name, @values[name], Integer)
+      end
+    end
+
+    # Timer intervals (Numeric or nil = timer-off) and HTTP timeouts (Numeric).
+    def validate_intervals!
+      require_interval(:data_refresh_interval, @values[:data_refresh_interval])
+      require_interval(:flush_interval, @values[:flush_interval])
+      require_type(:open_timeout, @values[:open_timeout], Numeric)
+      require_type(:read_timeout, @values[:read_timeout], Numeric)
+    end
+
+    # Strict boolean flags.
+    def validate_booleans!
+      %i[keys_case_sensitive tracking].each do |name|
+        require_boolean(name, @values[name])
+      end
+    end
+
+    # log_level must be one of the {LogLevel} values.
+    def validate_log_level!
+      level = @values[:log_level]
+      return if LOG_LEVEL_VALUES.include?(level)
+
+      raise ArgumentError,
+            "log_level must be a LogLevel value (#{LOG_LEVEL_VALUES.join(", ")}), got #{level.inspect}"
+    end
+
+    # Require String-or-nil (nil acceptable for optional strings).
+    def require_string(name, value)
+      return if value.nil? || value.is_a?(String)
+
+      raise ArgumentError, "#{name} must be a String, got #{value.class}"
+    end
+
+    # Require a Numeric-or-nil timer interval; nil means timer-off.
+    def require_interval(name, value)
+      return if value.nil? || value.is_a?(Numeric)
+
+      raise ArgumentError, "#{name} must be a Numeric (seconds) or nil (timer-off), got #{value.class}"
+    end
+
+    # Require +value+ to be an instance of +type+.
+    def require_type(name, value, type)
+      return if value.is_a?(type)
+
+      raise ArgumentError, "#{name} must be a #{type}, got #{value.class}"
+    end
+
+    # Require a strict boolean (true / false), never truthy coercion.
+    def require_boolean(name, value)
+      return if [true, false].include?(value)
+
+      raise ArgumentError, "#{name} must be a boolean (true/false), got #{value.class}"
+    end
+  end
+end