magick-feature-flags 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 958764166d59a55b2243c5ce0f009164c26c75ae07740b200808866f3d6ad543
-  data.tar.gz: a96a1b187259c225a0b55ec243dbdfc9d9771621b420a4519c2fc7c4e9ee6a5c
+  metadata.gz: be6153e50823e724cefb980f60d0272c878ed9fd3619cfa98eaaa8917ab621d1
+  data.tar.gz: a6e50cabc9eb5730f819ff038ce23b9869e56140244d2b6b48a4c6efa46c1667
 SHA512:
-  metadata.gz: 1affc66448028865d889535959d7970e8b54d1b3e3367d0bd4fb19ec8b18451c9bbc4714735e5f98f26da4a124e52b56a00c345d161660bfb944a9adb2bcbb12
-  data.tar.gz: 3ef2b6d8341517ef3bc8099a582e550877242d50f3fb67eab645b7d13f7adbdcf999f9f7a1d39e86ed3f5d1c13a98e8a69200dc5ab3b8c666cd14e924c462d0f
+  metadata.gz: d392122de52073465642db7d78302e4bd7aecb9d9507b9d2189f02c3bc9332b47c9facc02a5c1f7771d8bc355e25fe7607bd0c56a655536031bac6257b9a6cd0
+  data.tar.gz: 5feae702d0c3f67142b70ea65b1b396ea34c352430db81749eecdcb636481cbb87aff026dad4012c89e8875f4a6395edca61ca0669859039e6d7912ebd65375e

data/README.md

@@ -195,6 +195,40 @@ feature.enable_for_ip_addresses('192.168.1.0/24', '10.0.0.1')
 feature.enable_for_custom_attribute(:subscription_tier, ['premium', 'enterprise'])
 ```
 
+### Wire Targeting Payload (control-plane APIs)
+
+For building flag-management endpoints on top of the gem (an internal panel,
+a sync job, any JSON API), two primitives implement the wire contract — the
+gem ships no routes, your app owns paths and auth:
+
+```ruby
+# GET side — full flag payload, string keys. The "targeting" key is ALWAYS
+# present ({} = no targeting); list rules are arrays of strings, percentages
+# floats. Rails-idiomatic: works with render json: directly.
+render json: Magick.features.values          # [{... "targeting" => {"user" => ["3"], "percentage_users" => 50.0}}, ...]
+
+# PATCH side — wholesale, declarative write: the payload IS the new targeting
+# state. Keys absent from the payload are removed; {} clears everything.
+feature.replace_targeting(payload['targeting'])
+```
+
+`replace_targeting` is lenient about input spellings (string or symbol keys,
+plural aliases like `users:`, scalars for lists, numeric strings) but strict
+about content: unknown keys or invalid values (percentage outside `(0, 100]`,
+malformed date ranges, junk IPs) raise `Magick::InvalidTargetingError`
+*before anything is applied* — map it to a 422:
+
+```ruby
+rescue Magick::InvalidTargetingError => e
+  render json: { error: e.message }, status: :unprocessable_entity
+```
+
+Each call records one audit entry and one version snapshot
+(`replace_targeting`). A/B variants are not part of the targeting payload —
+they never appear inside the wire `targeting` object and survive a replace
+untouched (manage them via `set_variants`). `enable`/`disable` still clear
+all targeting wholesale, so their wire representation is `"targeting": {}`.
+
 ### Feature Exclusions
 
 Exclusions let you block specific users, groups, roles, tags, or IP addresses from a feature — even if they match an inclusion rule. **Exclusions always take priority over inclusions.**

data/app/controllers/magick/adminui/features_controller.rb

@@ -42,8 +42,7 @@ module Magick
       end
 
       def partially_enabled?(feature)
-        targeting = feature.instance_variable_get(:@targeting) || {}
-        targeting.any? && !targeting.empty?
+        (feature.targeting || {}).any?
       end
 
       def index
@@ -132,7 +131,6 @@ module Magick
       end
 
       def update_targeting
-        # Handle targeting updates from form
         targeting_params = params[:targeting] || {}
         unless hash_like?(targeting_params)
           redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Invalid targeting payload.'
@@ -143,146 +141,13 @@ module Magick
         feature_name = @feature.name.to_s
         @feature = Magick.features[feature_name] if Magick.features.key?(feature_name)
 
-        current_targeting = @feature.instance_variable_get(:@targeting) || {}
-
-        # Handle roles - always clear existing and set new ones
-        # Rails checkboxes don't send unchecked values, so we need to check what was sent
-        current_roles = current_targeting[:role].is_a?(Array) ? current_targeting[:role] : (current_targeting[:role] ? [current_targeting[:role]] : [])
-        selected_roles = Array(targeting_params[:roles]).reject(&:blank?)
-
-        # Disable roles that are no longer selected
-        (current_roles - selected_roles).each do |role|
-          @feature.disable_for_role(role) if role.present?
-        end
-
-        # Enable newly selected roles
-        (selected_roles - current_roles).each do |role|
-          @feature.enable_for_role(role) if role.present?
-        end
-
-        # Handle tags - always clear existing and set new ones
-        # Rails checkboxes don't send unchecked values, so we need to check what was sent
-        current_tags = current_targeting[:tag].is_a?(Array) ? current_targeting[:tag] : (current_targeting[:tag] ? [current_targeting[:tag]] : [])
-        selected_tags = Array(targeting_params[:tags]).reject(&:blank?)
-
-        # Disable tags that are no longer selected
-        (current_tags - selected_tags).each do |tag|
-          @feature.disable_for_tag(tag) if tag.present?
-        end
-
-        # Enable newly selected tags
-        (selected_tags - current_tags).each do |tag|
-          @feature.enable_for_tag(tag) if tag.present?
-        end
-
-        # Handle user IDs - replace existing user targeting
-        if targeting_params[:user_ids].present?
-          user_ids = targeting_params[:user_ids].split(',').map(&:strip).reject(&:blank?)
-          current_user_ids = current_targeting[:user].is_a?(Array) ? current_targeting[:user] : (current_targeting[:user] ? [current_targeting[:user]] : [])
-
-          # Disable users that are no longer in the list
-          (current_user_ids - user_ids).each do |user_id|
-            @feature.disable_for_user(user_id) if user_id.present?
-          end
-
-          # Enable new users
-          (user_ids - current_user_ids).each do |user_id|
-            @feature.enable_for_user(user_id) if user_id.present?
-          end
-        elsif targeting_params.key?(:user_ids) && targeting_params[:user_ids].blank?
-          # Clear all user targeting if field was cleared
-          current_user_ids = current_targeting[:user].is_a?(Array) ? current_targeting[:user] : (current_targeting[:user] ? [current_targeting[:user]] : [])
-          current_user_ids.each do |user_id|
-            @feature.disable_for_user(user_id) if user_id.present?
-          end
-        end
-
-        # Handle percentage of users
-        percentage_users_value = targeting_params[:percentage_users]
-        if percentage_users_value.present? && percentage_users_value.to_s.strip != ''
-          percentage = percentage_users_value.to_f
-          if percentage > 0 && percentage <= 100
-            result = @feature.enable_percentage_of_users(percentage)
-            Rails.logger.debug "Magick: Enabled percentage_users #{percentage} for #{@feature.name}: #{result}" if defined?(Rails)
-          else
-            # Value is 0 or invalid - disable
-            @feature.disable_percentage_of_users
-          end
-        else
-          # Field is empty - disable if it was previously set
-          @feature.disable_percentage_of_users if current_targeting[:percentage_users]
-        end
-
-        # Handle percentage of requests
-        percentage_requests_value = targeting_params[:percentage_requests]
-        if percentage_requests_value.present? && percentage_requests_value.to_s.strip != ''
-          percentage = percentage_requests_value.to_f
-          if percentage > 0 && percentage <= 100
-            result = @feature.enable_percentage_of_requests(percentage)
-            Rails.logger.debug "Magick: Enabled percentage_requests #{percentage} for #{@feature.name}: #{result}" if defined?(Rails)
-          else
-            # Value is 0 or invalid - disable
-            @feature.disable_percentage_of_requests
-          end
-        else
-          # Field is empty - disable if it was previously set
-          @feature.disable_percentage_of_requests if current_targeting[:percentage_requests]
-        end
-
-        # Handle excluded user IDs
-        if targeting_params[:excluded_user_ids].present?
-          excluded_user_ids = targeting_params[:excluded_user_ids].split(',').map(&:strip).reject(&:blank?)
-          current_excluded_users = current_targeting[:excluded_users].is_a?(Array) ? current_targeting[:excluded_users] : (current_targeting[:excluded_users] ? [current_targeting[:excluded_users]] : [])
-
-          (current_excluded_users - excluded_user_ids).each do |user_id|
-            @feature.remove_user_exclusion(user_id) if user_id.present?
-          end
-
-          (excluded_user_ids - current_excluded_users).each do |user_id|
-            @feature.exclude_user(user_id) if user_id.present?
-          end
-        elsif targeting_params.key?(:excluded_user_ids) && targeting_params[:excluded_user_ids].blank?
-          current_excluded_users = current_targeting[:excluded_users].is_a?(Array) ? current_targeting[:excluded_users] : (current_targeting[:excluded_users] ? [current_targeting[:excluded_users]] : [])
-          current_excluded_users.each do |user_id|
-            @feature.remove_user_exclusion(user_id) if user_id.present?
-          end
-        end
-
-        # Handle excluded roles
-        current_excluded_roles = current_targeting[:excluded_roles].is_a?(Array) ? current_targeting[:excluded_roles] : (current_targeting[:excluded_roles] ? [current_targeting[:excluded_roles]] : [])
-        selected_excluded_roles = Array(targeting_params[:excluded_roles]).reject(&:blank?)
-
-        (current_excluded_roles - selected_excluded_roles).each do |role|
-          @feature.remove_role_exclusion(role) if role.present?
-        end
-
-        (selected_excluded_roles - current_excluded_roles).each do |role|
-          @feature.exclude_role(role) if role.present?
-        end
-
-        # Handle excluded tags
-        current_excluded_tags = current_targeting[:excluded_tags].is_a?(Array) ? current_targeting[:excluded_tags] : (current_targeting[:excluded_tags] ? [current_targeting[:excluded_tags]] : [])
-        selected_excluded_tags = Array(targeting_params[:excluded_tags]).reject(&:blank?)
-
-        (current_excluded_tags - selected_excluded_tags).each do |tag|
-          @feature.remove_tag_exclusion(tag) if tag.present?
-        end
-
-        (selected_excluded_tags - current_excluded_tags).each do |tag|
-          @feature.exclude_tag(tag) if tag.present?
-        end
-
-        # After all targeting updates, ensure we're using the registered feature instance
-        # and reload it to get the latest state from adapter
-        feature_name = @feature.name.to_s
-        if Magick.features.key?(feature_name)
-          @feature = Magick.features[feature_name]
-          @feature.reload
-        else
-          @feature.reload
-        end
+        # One declarative write: one audit entry + one version per submit.
+        @feature.replace_targeting(desired_targeting_from_form(targeting_params))
+        @feature.reload
 
         redirect_to magick_admin_ui.feature_path(@feature.name), notice: 'Targeting updated successfully'
+      rescue Magick::InvalidTargetingError => e
+        redirect_to magick_admin_ui.feature_path(@feature.name), alert: "Invalid targeting: #{e.message}"
       rescue StandardError => e
         Rails.logger.error "Magick: Error updating targeting for #{@feature.name}: #{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}" if defined?(Rails)
         redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Could not update targeting — see server logs for details.'
@@ -322,8 +187,56 @@ module Magick
         redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Could not update variants — see server logs for details.'
       end
 
+      # Targeting rules the edit form has no fields for. They are carried over
+      # from the current state on every submit so a form save can never
+      # silently destroy them. (:variants is preserved by replace_targeting
+      # itself.)
+      FORM_UNMANAGED_TARGETING_KEYS = %i[
+        group excluded_groups ip_address excluded_ip_addresses
+        date_range custom_attributes complex_conditions
+      ].freeze
+
       private
 
+      # Build the full desired targeting state from the edit form. Checkbox
+      # groups (roles/tags and their exclusions) and the percentage fields are
+      # authoritative on every submit — unchecked/blank means "remove the
+      # rule". The comma-separated user lists are only authoritative when
+      # their field was actually sent. Percentages stay lenient here (blank
+      # or out-of-range clears the rule, as the form always behaved) —
+      # strict validation is for API callers of replace_targeting.
+      def desired_targeting_from_form(targeting_params)
+        current = @feature.targeting || {}
+        desired = {}
+        FORM_UNMANAGED_TARGETING_KEYS.each { |key| desired[key] = current[key] if current.key?(key) }
+
+        desired[:role] = Array(targeting_params[:roles]).reject(&:blank?)
+        desired[:tag] = Array(targeting_params[:tags]).reject(&:blank?)
+        desired[:excluded_roles] = Array(targeting_params[:excluded_roles]).reject(&:blank?)
+        desired[:excluded_tags] = Array(targeting_params[:excluded_tags]).reject(&:blank?)
+
+        desired[:user] = csv_ids(targeting_params, :user_ids, current[:user])
+        desired[:excluded_users] = csv_ids(targeting_params, :excluded_user_ids, current[:excluded_users])
+
+        desired[:percentage_users] = form_percentage(targeting_params[:percentage_users])
+        desired[:percentage_requests] = form_percentage(targeting_params[:percentage_requests])
+
+        desired.compact
+      end
+
+      def csv_ids(targeting_params, field, current_value)
+        return Array(current_value) unless targeting_params.key?(field)
+
+        targeting_params[field].to_s.split(',').map(&:strip).reject(&:blank?)
+      end
+
+      def form_percentage(raw)
+        return nil if raw.blank?
+
+        percentage = raw.to_f
+        percentage.positive? && percentage <= 100 ? percentage : nil
+      end
+
       # Resolve the acting admin via the configurable AdminUI hook and run the
       # action inside Magick.with_actor. A failing resolver only costs
       # attribution — it must never 500 the admin UI, and it is rescued

data/lib/magick/errors.rb

@@ -5,5 +5,9 @@ module Magick
   class FeatureNotFoundError < Error; end
   class InvalidFeatureTypeError < Error; end
   class InvalidFeatureValueError < Error; end
+  # Raised by Feature#replace_targeting when a wire targeting payload
+  # contains unknown keys or invalid values. Nothing is applied on failure,
+  # so API callers can map it straight to a 422.
+  class InvalidTargetingError < Error; end
   class AdapterError < Error; end
 end

data/lib/magick/export_import.rb

@@ -103,55 +103,18 @@ module Magick
       feature.set_value(value) if !value.nil? && !(value.is_a?(String) && value.empty?)
     end
 
-    # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/CyclomaticComplexity
     def self.apply_targeting(feature, targeting)
-      targeting.each do |type, values|
-        case type.to_sym
-        when :user, :users
-          Array(values).each { |v| feature.enable_for_user(v) }
-        when :excluded_users
-          Array(values).each { |v| feature.exclude_user(v) }
-        when :group, :groups
-          Array(values).each { |v| feature.enable_for_group(v) }
-        when :excluded_groups
-          Array(values).each { |v| feature.exclude_group(v) }
-        when :role, :roles
-          Array(values).each { |v| feature.enable_for_role(v) }
-        when :excluded_roles
-          Array(values).each { |v| feature.exclude_role(v) }
-        when :tag, :tags
-          Array(values).each { |v| feature.enable_for_tag(v) }
-        when :excluded_tags
-          Array(values).each { |v| feature.exclude_tag(v) }
-        when :ip_address, :ip_addresses
-          feature.enable_for_ip_addresses(Array(values))
-        when :excluded_ip_addresses
-          feature.exclude_ip_addresses(Array(values))
-        when :percentage_users
-          feature.enable_percentage_of_users(values)
-        when :percentage_requests
-          feature.enable_percentage_of_requests(values)
-        when :date_range
-          range = values.is_a?(Hash) ? values.transform_keys(&:to_sym) : values
-          feature.enable_for_date_range(range[:start], range[:end]) if range.is_a?(Hash) && range[:start] && range[:end]
-        when :custom_attributes
-          apply_custom_attributes(feature, values)
-        end
-      end
-    end
-    # rubocop:enable Metrics/MethodLength
-    # rubocop:enable Metrics/CyclomaticComplexity
+      return unless targeting.is_a?(Hash)
 
-    def self.apply_custom_attributes(feature, values)
-      return unless values.is_a?(Hash)
+      # Exports from gem versions where variants leaked into the targeting
+      # hash must stay importable; variants are applied separately from the
+      # top-level key.
+      payload = targeting.reject { |key, _| key.to_s == 'variants' }
+      return if payload.empty?
 
-      values.each do |attr, rule|
-        rule_h = rule.is_a?(Hash) ? rule.transform_keys(&:to_sym) : {}
-        next unless rule_h[:values]
-
-        feature.enable_for_custom_attribute(attr, rule_h[:values], operator: (rule_h[:operator] || :equals).to_sym)
-      end
+      feature.replace_targeting(payload)
+    rescue Magick::InvalidTargetingError => e
+      raise ImportError, "Magick.import: invalid targeting for '#{feature.name}': #{e.message}"
     end
 
     def self.apply_variants(feature, variants)

data/lib/magick/feature.rb

@@ -9,7 +9,8 @@ module Magick
     VALID_TYPES = %i[boolean string number].freeze
     VALID_STATUSES = %i[active inactive deprecated].freeze
 
-    attr_reader :name, :type, :status, :default_value, :description, :display_name, :group, :adapter_registry
+    attr_reader :name, :type, :status, :default_value, :description, :display_name, :group, :adapter_registry,
+                :targeting
 
     def initialize(name, adapter_registry, **options)
       @name = name.to_s
@@ -749,6 +750,64 @@ module Magick
       }
     end
 
+    # Wire-format serializer for control-plane APIs (e.g. the platform's
+    # /internal/panel/flags endpoints). The "targeting" key is ALWAYS present
+    # ({} = no targeting), array rules are arrays of strings, percentages are
+    # floats, and the internal :variants entry never appears inside targeting.
+    # Rails-idiomatic: `render json: feature` (or a collection) emits this.
+    def as_json(_options = nil)
+      {
+        'name' => name,
+        'display_name' => display_name,
+        'group' => group,
+        'type' => type.to_s,
+        'status' => status.to_s,
+        'value' => stored_value,
+        'default_value' => default_value,
+        'description' => description,
+        'targeting' => TargetingPayload.serialize(targeting),
+        'dependencies' => (@dependencies || []).map(&:to_s),
+        # Variants live inside @targeting under the internal :variants key
+        # (variants_for_export reads a never-assigned ivar and is always
+        # empty), so the wire payload reads the authoritative source.
+        'variants' => TargetingPayload.deep_stringify(targeting[:variants] || [])
+      }
+    end
+
+    # Wholesale, declarative targeting write: the payload IS the new
+    # targeting state. Keys absent from it are removed; {} clears all
+    # targeting. Accepts wire input leniently (string/symbol keys, plural
+    # aliases, scalars for lists, numeric strings) but validates strictly —
+    # unknown keys or invalid values raise InvalidTargetingError before any
+    # state is touched. The internal :variants entry is not part of the wire
+    # payload and survives the replace untouched.
+    # Accepts the payload as a positional hash or inline keywords
+    # (replace_targeting(user: [3])) — Ruby routes a braceless hash to
+    # keywords, so both spellings must land in the same place. Passing
+    # nothing raises (via normalize): clearing requires an explicit {}.
+    def replace_targeting(payload = nil, user_id: nil, **inline_rules)
+      raise ArgumentError, 'pass targeting either as a hash or inline, not both' if payload && inline_rules.any?
+
+      normalized = TargetingPayload.normalize(payload || (inline_rules unless inline_rules.empty?))
+      normalized[:variants] = targeting[:variants] if targeting[:variants]
+
+      changes = {
+        targeting: {
+          from: TargetingPayload.serialize(targeting),
+          to: TargetingPayload.serialize(normalized)
+        }
+      }
+      record_change('replace_targeting', changes, user_id: user_id) do
+        @targeting = normalized
+        persist_targeting
+
+        if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
+          Magick::Rails::Events.feature_changed(name, changes: changes, user_id: user_id)
+        end
+      end
+      true
+    end
+
     def variants_for_export
       return [] unless defined?(Magick::FeatureVariant)
 
@@ -790,8 +849,6 @@ module Magick
 
     private
 
-    attr_reader :targeting
-
     # Single choke point for change tracking: wraps a public mutator's body,
     # then writes one audit entry and one version snapshot for the operation.
     # A thread-local guard makes nested mutator calls (enable -> set_value)

data/lib/magick/targeting_payload.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'time'
+
+module Magick
+  # Translates between the internal targeting hash and the wire-format
+  # targeting payload exchanged with control planes (panel contract):
+  #
+  #   GET  -> Feature#as_json emits `serialize(targeting)` — string keys,
+  #           arrays of strings, floats; the "targeting" key is always
+  #           present ({} = no targeting).
+  #   PATCH -> Feature#replace_targeting runs the inbound payload through
+  #           `normalize` — lenient about aliases/scalars/key types, strict
+  #           about vocabulary and values (all-or-nothing).
+  #
+  # The internal-only :variants key never crosses the wire in either
+  # direction: `serialize` drops it, `normalize` rejects it.
+  module TargetingPayload
+    # Inclusion keys are singular, exclusion keys plural — mirrors the
+    # internal @targeting layout, which is also the persisted layout.
+    ARRAY_KEYS = %i[
+      user group role tag ip_address
+      excluded_users excluded_groups excluded_roles excluded_tags excluded_ip_addresses
+    ].freeze
+    PERCENTAGE_KEYS = %i[percentage_users percentage_requests].freeze
+    STRUCTURED_KEYS = %i[date_range custom_attributes complex_conditions].freeze
+    CANONICAL_KEYS = (ARRAY_KEYS + PERCENTAGE_KEYS + STRUCTURED_KEYS).freeze
+
+    # Plural spellings accepted on input for parity with Magick.import.
+    ALIASES = {
+      users: :user,
+      groups: :group,
+      roles: :role,
+      tags: :tag,
+      ip_addresses: :ip_address
+    }.freeze
+
+    IP_KEYS = %i[ip_address excluded_ip_addresses].freeze
+
+    CUSTOM_ATTRIBUTE_OPERATORS = %i[equals eq not_equals ne in not_in greater_than gt less_than lt].freeze
+    COMPLEX_OPERATORS = %i[and or].freeze
+    COMPLEX_CONDITION_TYPES = %i[user group role custom_attribute].freeze
+
+    module_function
+
+    # Wire payload -> canonical internal targeting hash. Raises
+    # InvalidTargetingError on the first problem, before any state is
+    # touched, so callers get all-or-nothing semantics for free.
+    def normalize(payload)
+      raise InvalidTargetingError, "targeting must be a Hash, got #{payload.class}" unless payload.is_a?(Hash)
+
+      normalized = {}
+      payload.each do |raw_key, raw_value|
+        key = canonical_key(raw_key)
+        raise InvalidTargetingError, "conflicting targeting keys resolve to '#{key}'" if normalized.key?(key)
+        next if raw_value.nil? # nil = remove the rule, same as omitting the key
+
+        value = normalize_value(key, raw_value)
+        normalized[key] = value unless value.nil?
+      end
+      normalized
+    end
+
+    # Internal targeting hash -> wire payload. Never raises: the read path
+    # must serialize whatever historical state an adapter hands back.
+    def serialize(targeting)
+      return {} unless targeting.is_a?(Hash)
+
+      targeting.each_with_object({}) do |(key, value), wire|
+        key = key.to_sym
+        next if key == :variants # internal-only, managed via set_variants
+
+        wire[key.to_s] =
+          if ARRAY_KEYS.include?(key)
+            Array(value).map(&:to_s)
+          elsif PERCENTAGE_KEYS.include?(key)
+            value.to_f
+          elsif key == :date_range
+            serialize_date_range(value)
+          else
+            deep_stringify(value)
+          end
+      end
+    end
+
+    def canonical_key(raw_key)
+      key = raw_key.to_sym
+      key = ALIASES.fetch(key, key)
+      if key == :variants
+        raise InvalidTargetingError, 'variants are not part of the targeting payload (use set_variants)'
+      end
+      raise InvalidTargetingError, "unknown targeting key: '#{raw_key}'" unless CANONICAL_KEYS.include?(key)
+
+      key
+    end
+
+    def normalize_value(key, value)
+      if ARRAY_KEYS.include?(key)
+        normalize_array(key, value)
+      elsif PERCENTAGE_KEYS.include?(key)
+        normalize_percentage(key, value)
+      elsif key == :date_range
+        normalize_date_range(value)
+      elsif key == :custom_attributes
+        normalize_custom_attributes(value)
+      else # :complex_conditions
+        normalize_complex_conditions(value)
+      end
+    end
+
+    # Scalars are accepted as one-element lists; empty lists mean "no rule"
+    # and collapse to key removal, keeping {} the only spelling of
+    # "no targeting".
+    def normalize_array(key, value)
+      values = (value.is_a?(Array) ? value : [value]).compact.map { |v| v.to_s.strip }.reject(&:empty?).uniq
+      return nil if values.empty?
+
+      validate_ip_list!(key, values) if IP_KEYS.include?(key)
+      values
+    end
+
+    def validate_ip_list!(key, values)
+      values.each do |ip|
+        IPAddr.new(ip)
+      rescue ArgumentError # includes IPAddr::Error
+        raise InvalidTargetingError, "invalid IP address or CIDR range in '#{key}': '#{ip}'"
+      end
+    end
+
+    def normalize_percentage(key, value)
+      percentage = begin
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise InvalidTargetingError, "'#{key}' must be a number, got #{value.inspect}"
+      end
+      unless percentage.positive? && percentage <= 100
+        raise InvalidTargetingError, "'#{key}' must be within (0, 100], got #{percentage}"
+      end
+
+      percentage
+    end
+
+    def normalize_date_range(value)
+      raise InvalidTargetingError, "'date_range' must be a Hash with start and end" unless value.is_a?(Hash)
+
+      start_value = value[:start] || value['start']
+      end_value = value[:end] || value['end']
+      raise InvalidTargetingError, "'date_range' requires both start and end" unless start_value && end_value
+
+      { start: parse_date_bound(start_value), end: parse_date_bound(end_value) }
+    end
+
+    def parse_date_bound(value)
+      return value unless value.is_a?(String)
+
+      Time.parse(value)
+      value
+    rescue ArgumentError
+      raise InvalidTargetingError, "'date_range' bound is not a parseable time: '#{value}'"
+    end
+
+    def normalize_custom_attributes(value)
+      raise InvalidTargetingError, "'custom_attributes' must be a Hash" unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(attribute, rule), result|
+        raise InvalidTargetingError, "rule for custom attribute '#{attribute}' must be a Hash" unless rule.is_a?(Hash)
+
+        values = Array(rule[:values] || rule['values']).compact.map(&:to_s).reject(&:empty?)
+        raise InvalidTargetingError, "custom attribute '#{attribute}' requires values" if values.empty?
+
+        operator = (rule[:operator] || rule['operator'] || :equals).to_sym
+        unless CUSTOM_ATTRIBUTE_OPERATORS.include?(operator)
+          raise InvalidTargetingError, "unknown operator '#{operator}' for custom attribute '#{attribute}'"
+        end
+
+        result[attribute.to_sym] = { values: values, operator: operator }
+      end
+    end
+
+    def normalize_complex_conditions(value)
+      raise InvalidTargetingError, "'complex_conditions' must be a Hash" unless value.is_a?(Hash)
+
+      operator = (value[:operator] || value['operator'] || :and).to_sym
+      unless COMPLEX_OPERATORS.include?(operator)
+        raise InvalidTargetingError, "'complex_conditions' operator must be and/or, got '#{operator}'"
+      end
+
+      conditions = value[:conditions] || value['conditions']
+      raise InvalidTargetingError, "'complex_conditions' requires a conditions Array" unless conditions.is_a?(Array)
+
+      { operator: operator, conditions: conditions.map { |c| normalize_complex_condition(c) } }
+    end
+
+    def normalize_complex_condition(condition)
+      raise InvalidTargetingError, 'each complex condition must be a Hash' unless condition.is_a?(Hash)
+
+      type = (condition[:type] || condition['type']).to_s.to_sym
+      unless COMPLEX_CONDITION_TYPES.include?(type)
+        raise InvalidTargetingError, "unknown complex condition type: '#{type}'"
+      end
+
+      params = condition[:params] || condition['params'] || {}
+      raise InvalidTargetingError, "params for complex condition '#{type}' must be a Hash" unless params.is_a?(Hash)
+
+      { type: type, params: params.transform_keys(&:to_sym) }
+    end
+
+    def serialize_date_range(value)
+      return deep_stringify(value) unless value.is_a?(Hash)
+
+      start_value = value[:start] || value['start']
+      end_value = value[:end] || value['end']
+      { 'start' => serialize_time(start_value), 'end' => serialize_time(end_value) }
+    end
+
+    def serialize_time(value)
+      return value if value.nil? || value.is_a?(String)
+      return value.iso8601 if value.respond_to?(:iso8601)
+
+      value.to_s
+    end
+
+    def deep_stringify(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
+      when Array
+        value.map { |v| deep_stringify(v) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+  end
+end

data/lib/magick/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Magick
-  VERSION = '1.5.0'
+  VERSION = '1.6.0'
 end

data/lib/magick.rb

@@ -23,6 +23,7 @@ require_relative 'magick/targeting/ip_address'
 require_relative 'magick/targeting/custom_attribute'
 require_relative 'magick/targeting/complex'
 require_relative 'magick/errors'
+require_relative 'magick/targeting_payload'
 
 require_relative 'magick/log_safe'
 require_relative 'magick/audit_log'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: magick-feature-flags
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Andrew Lobanov
@@ -145,6 +145,7 @@ files:
 - lib/magick/targeting/request_percentage.rb
 - lib/magick/targeting/role.rb
 - lib/magick/targeting/user.rb
+- lib/magick/targeting_payload.rb
 - lib/magick/testing_helpers.rb
 - lib/magick/version.rb
 - lib/magick/versioning.rb