determinator 2.5.0 → 2.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b505247b6902fb3768389da7b5a20e625f95e5ccaec778ae7fb52e1808286b73
-  data.tar.gz: 659b93e86df258535f904bd90d91768767c5c1644cd578d3efe3f45a9c2aba6f
+  metadata.gz: 4466edc3643125ca6b84591b4db51083d215c5c6ea8201694e99d16e403eab24
+  data.tar.gz: 326d45e3f0ac249e5a358ee3911c1da4da01db81c14ab1b3c827a8fd5d0f4ef9
 SHA512:
-  metadata.gz: 753968e66ac00b3f0606eed33b5d1873ad23a89cce901b69e261f38263ff14f18b975a0f03e55146e8ea78dc397b1a48878f10c3b1fc6eadd4f278a78f2a7703
-  data.tar.gz: 46d183bc1e87d5031b43115bb63573503725f441a44603577274fef9817cd20722471bcba1b46d018beab4828bbcbf738c4de742aff0de26578178330edd2885
+  metadata.gz: c83ad23860f0d5565618e3cfbf1f9975763f3f64c0db49668fa2259aae06c972689e000538a734571906edbf766c8d1d46e58ad2d7c657461c76759768f37bfa
+  data.tar.gz: 777556d4606d6a10514b5f7c6311e498117845f9bf5bc3bd1be7f8c47cee837fb17243348d11ee0f2fff3931493e97e65cb06608dcbc9b435916aabad07e69f1

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 2.5.1
+
+Feature:
+- Add explain functionality for determinations
+
 # 2.5.0
 
 Feature:

data/lib/determinator.rb

@@ -3,6 +3,7 @@ require 'determinator/control'
 require 'determinator/feature'
 require 'determinator/target_group'
 require 'determinator/fixed_determination'
+require 'determinator/explainer'
 require 'determinator/cache/fetch_wrapper'
 require 'determinator/serializers/json'
 require 'determinator/missing_response'

data/lib/determinator/control.rb

@@ -5,10 +5,11 @@ require 'securerandom'
 
 module Determinator
   class Control
-    attr_reader :retrieval
+    attr_reader :retrieval, :explainer
 
     def initialize(retrieval:)
       @retrieval = retrieval
+      @explainer = Determinator::Explainer.new
     end
 
     # Creates a new determinator instance which assumes the actor id, guid and properties given
@@ -51,6 +52,12 @@ module Determinator
       end
     end
 
+    def explain_determination(name, id: nil, guid: nil, properties: {})
+      explainer.explain do
+        determinate_and_notice(name, id: id, guid: guid, properties: properties)
+      end
+    end
+
     def inspect
       '#<Determinator::Control>'
     end
@@ -76,17 +83,19 @@ module Determinator
       # Calling method can place constraints on the feature, eg. experiment only
       return false if block_given? && !yield(feature)
 
+      explainer.log(:start, { feature: feature } )
+
       # Inactive features are always, always off
-      return false unless feature.active?
+      return false unless feature_active?(feature)
 
-      return feature.override_value_for(id) if feature.overridden_for?(id)
+      return override_value(feature, id) if feature_overridden?(feature, id)
 
       fixed_determination = choose_fixed_determination(feature, properties)
       # Given constraints have specified that this actor's determination should be fixed
       if fixed_determination
-        return false unless fixed_determination.feature_on
-        return true unless feature.experiment?
-        return fixed_determination.variant
+        return explainer.log(:chosen_fixed_determination, { fixed_determination: fixed_determination }) {
+          fixed_determination_value(feature, fixed_determination)
+        }
       end
 
       target_group = choose_target_group(feature, properties)
@@ -98,14 +107,18 @@ module Determinator
       return false unless indicators
 
       # Actor's indicator has excluded them from the feature
-      return false if indicators.rollout >= target_group.rollout
+      return false if excluded_from_rollout?(indicators, target_group)
 
       # Features don't need variant determination and, at this stage,
       # they have been rolled out to.
-      return true unless feature.experiment?
+      # require_variant_determination?
+      return true unless require_variant_determination?(feature)
 
-      variant_for(feature, indicators.variant)
 
+
+      explainer.log(:chosen_variant) {
+        variant_for(feature, indicators.variant)
+      }
     rescue ArgumentError
       raise
 
@@ -114,25 +127,83 @@ module Determinator
       false
     end
 
+    def feature_active?(feature)
+      explainer.log(:feature_active) {
+        feature.active?
+      }
+    end
+
+    def feature_overridden?(feature, id)
+      explainer.log(:feature_overridden_for) {
+        feature.overridden_for?(id)
+      }
+    end
+
+    def override_value(feature, id)
+      explainer.log(:override_value, { id: id }) {
+        feature.override_value_for(id)
+      }
+    end
+
+    def excluded_from_rollout?(indicators, target_group)
+      explainer.log(:excluded_from_rollout, { target_group: target_group } ) {
+        indicators.rollout >= target_group.rollout
+      }
+    end
+
+    def require_variant_determination?(feature)
+      explainer.log(:require_variant_determination) {
+        feature.experiment?
+      }
+    end
+
+    def fixed_determination_value(feature, fixed_determination)
+      return false unless fixed_determination.feature_on
+      return true unless feature.experiment?
+      return fixed_determination.variant
+    end
+
     def choose_fixed_determination(feature, properties)
       # Keys and values must be strings
       normalised_properties = normalise_properties(properties)
 
-      feature.fixed_determinations.find { |fd|
-        matches_constraints(normalised_properties, fd.constraints)
-      }
+      feature.fixed_determinations.find do |fd|
+        explainer.log(:possible_match_fixed_determination, { fixed_determination: fd }) {
+          check_fixed_determination(fd, normalised_properties)
+        }
+      end
+    end
+
+    def check_fixed_determination(fixed_determination, properties)
+      explainer.log(:check_fixed_determination, { fixed_determination: fixed_determination })
+
+      matches_constraints(properties, fixed_determination.constraints)
     end
 
     def choose_target_group(feature, properties)
       # Keys and values must be strings
       normalised_properties = normalise_properties(properties)
 
-      feature.target_groups.select { |tg|
-        next false unless tg.rollout.between?(1, 65_536)
+      # Must choose target group deterministically, if more than one match
+      explainer.log(:chosen_target_group) {
+        filtered_target_groups(feature, normalised_properties).sort_by { |tg| tg.rollout }.last
+      }
+    end
+
+    def filtered_target_groups(feature, properties)
+      feature.target_groups.select do |tg|
+        explainer.log(:possible_match_target_group, { target_group: tg }) {
+          check_target_group(tg, properties)
+        }
+      end
+    end
+
+    def check_target_group(target_group, properties)
+      explainer.log(:check_target_group, { target_group: target_group })
+
+      return false unless target_group.rollout.between?(1, 65_536)
 
-        matches_constraints(normalised_properties, tg.constraints)
-        # Must choose target group deterministically, if more than one match
-      }.sort_by { |tg| tg.rollout }.last
+      matches_constraints(properties, target_group.constraints)
     end
 
     def matches_constraints(normalised_properties, constraints)
@@ -174,10 +245,12 @@ module Determinator
     def actor_identifier(feature, id, guid)
       case feature.bucket_type
       when :id
+        explainer.log(:missing_identifier, { identifier_type: 'ID' }) unless id
         id
       when :guid
         return guid if guid.to_s != ''
 
+        explainer.log(:missing_identifier, { identifier_type: 'GUID' })
         raise ArgumentError, 'A GUID must always be given for GUID bucketed features'
       when :fallback
         identifier = (id || guid).to_s
@@ -187,6 +260,7 @@ module Determinator
       when :single
         SecureRandom.hex(64)
       else
+        explainer.log(:unknown_bucket, { feature: feature } )
         Determinator.notice_error "Cannot process the '#{feature.bucket_type}' bucket type found in #{feature.name}"
       end
     end

data/lib/determinator/explainer.rb

@@ -0,0 +1,61 @@
+require 'determinator/explainer/messages'
+
+module Determinator
+  class Explainer
+    attr_accessor :enabled
+    attr_reader :logs
+
+    def initialize
+      @logs  = []
+      @enabled = false
+    end
+
+    def explain
+      @enabled = true
+      { outcome: yield, explanation: @logs }
+    ensure
+      @logs = []
+      @enabled = false
+    end
+
+    def log(type, args = {})
+      result = block_given? ? yield : nil
+
+      return result unless @enabled
+
+      result.tap do |r|
+        add(type, r, args)
+      end
+    end
+
+    private
+
+    def add(type, result, args = {})
+      template = MESSAGES[type].fetch(result.to_s) { MESSAGES[type][:default] }
+      return unless template
+
+      args = convert_hash(
+        args.merge(result: result)
+          .transform_values { |v| v.respond_to?(:to_explain_params) ? v.to_explain_params : v }
+      )
+
+      @logs << template.dup.tap do |m|
+        m[:title] = format(m[:title], args)
+        m[:subtitle] = format(m[:subtitle], args) if m[:subtitle]
+      end
+      true
+    end
+
+    def convert_hash(hsh, path = "")
+      hsh.each_with_object({}) do |(k, v), ret|
+        key = "#{path}#{k}"
+
+        if v.is_a?(Hash)
+          ret.merge! convert_hash(v, "#{key}.")
+        else
+          ret[key.to_sym] = v
+        end
+      end
+    end
+  end
+end

data/lib/determinator/explainer/messages.rb

@@ -0,0 +1,119 @@
+module Determinator
+  class Explainer
+    MESSAGES = {
+      start: {
+        default: {
+          type: :start,
+          title: 'Determinating %<feature.name>s',
+          subtitle: 'The given ID, GUID and properties will be used to determine which target groups this actor is in, and will deterministically return an outcome for the visibility of this feature for them.'
+        }
+      },
+      feature_active: {
+        'true' => { type: :continue, title: 'Feature is active' },
+        'false' => { type: :fail, title: 'Feature is inactive', subtitle: 'Every actor is excluded' }
+      },
+      feature_overridden_for: {
+        'false' => { type: :pass, title: 'No matching override found'  }
+      },
+      override_value: {
+        default: {
+          type: :success,
+          title: 'Matching override found for this actor with id: %<id>s',
+          subtitle: 'Determinator will return "%<result>s" for this actor and this feature in any system that is correctly set up.'
+        }
+      },
+      excluded_from_rollout: {
+        'true' => {
+          type: :fail,
+          title: 'Determinated to be outside the %<target_group.rollout_percent>s',
+          subtitle: 'This actor is excluded'
+        },
+        'false' => {
+          type: :continue,
+          title: 'Determinated to be inside the %<target_group.rollout_percent>s',
+          subtitle: 'This actor is included'
+        }
+      },
+      require_variant_determination: {
+        'false' => {
+          type: :success,
+          title: 'Feature flag on for this actor',
+          subtitle: 'Determinator will return true for this actor and this feature in any system that is correctly set up.'
+        }
+      },
+      missing_identifier: {
+        default: {
+          type: :fail,
+          title: 'No %<identifier_type>s given, cannot determinate',
+          subtitle: 'For %<identifier_type>s bucketed features an %<identifier_type>s must be given to have the possibility of being included.'
+        }
+      },
+      chosen_variant: {
+        default: {
+          type: :success,
+          title: 'In the "%<result>s" variant',
+          subtitle: 'Determinator will return "%<result>s" for this actor and this feature in any system that is correctly set up.'
+        }
+      },
+      unknown_bucket: {
+        default: {
+          type: :fail,
+          title: 'Unknown bucket type',
+          subtitle: 'The bucket type "%<feature.bucket_type>s" is not understood by Determinator. All actors will be excluded.'
+        }
+      },
+      check_target_group: {
+        default: {
+          type: :target_group,
+          title: 'Checking "%<target_group.name>s" target group',
+          subtitle: 'An actor must match at least one non-zero target group in order to be included.'
+        }
+      },
+      possible_match_target_group: {
+        'true' => {
+          type: :continue,
+          title: 'Matches the "%<target_group.name>s" target group',
+          subtitle: 'Matching this target group allows this actor a %<target_group.rollout_percent>s percent chance of being included.'
+        },
+        'false' => {
+          type: :pass,
+          title: 'Didn\'t match the "%<target_group.name>s" target group',
+          subtitle: 'Actor can\'t be included as part of this target group.'
+        }
+      },
+      chosen_target_group: {
+        '' => {
+          type: :fail,
+          title: 'No matching target groups',
+          subtitle: 'No matching target groups have a rollout larger than 0 percent. This actor is excluded.'
+        },
+        default: {
+          type: :info,
+          title: '%<result.rollout_percent>s percent chance of being included',
+          subtitle: 'The largest matching rollout percentage is %<result.rollout_percent>s, giving this actor a percent chance of being included.'
+        }
+      },
+      check_fixed_determination: {
+        default: {
+          type: :target_group,
+          title: 'Checking "%<fixed_determination.name>s" fixed determination',
+          subtitle: 'Matching an actor based on the constraints provided.'
+        }
+      },
+      possible_match_fixed_determination: {
+        'false' => {
+          type: :pass,
+          title: 'Didn\'t match the "%<fixed_determination.name>s" fixed determination',
+          subtitle: 'Actor can\'t be included as part of this fixed determination.'
+        }
+      },
+      chosen_fixed_determination: {
+        default: {
+          type: :success,
+          title: 'Matching fixed determination found for this actor with name: "%<fixed_determination.name>s"',
+          subtitle: 'Determinator will return "%<result>s" for this actor and this feature in any system that is correctly set up.'
+        },
+      }
+    }.freeze
+  end
+end

data/lib/determinator/feature.rb

@@ -58,6 +58,10 @@ module Determinator
       Marshal.dump(self) == Marshal.dump(other)
     end
 
+    def to_explain_params
+      { name: name, identifier: identifier, bucket_type: bucket_type }
+    end
+
     private
 
     attr_reader :overrides
@@ -72,6 +76,7 @@ module Determinator
       constraints = target_group['constraints'].to_h
 
       TargetGroup.new(
+        name: target_group['name'],
         rollout: target_group['rollout'].to_i,
         constraints: parse_constraints(constraints)
       )
@@ -97,6 +102,7 @@ module Determinator
       constraints = fixed_determination['constraints'].to_h
 
       FixedDetermination.new(
+        name: fixed_determination['name'],
         feature_on: fixed_determination['feature_on'],
         variant: variant,
         constraints: parse_constraints(constraints)

data/lib/determinator/fixed_determination.rb

@@ -1,8 +1,9 @@
 module Determinator
   class FixedDetermination
-    attr_reader :feature_on, :variant, :constraints
+    attr_reader :name, :feature_on, :variant, :constraints
 
-    def initialize(feature_on:, variant:, constraints: {})
+    def initialize(feature_on:, variant:, name: '', constraints: {})
+      @name = name
       @feature_on = feature_on
       @variant = variant
       @constraints = constraints
@@ -12,6 +13,10 @@ module Determinator
       "<feature_on: #{feature_on}, variant: #{variant}, constraints: #{constraints}"
     end
 
+    def to_explain_params
+      { name: name }
+    end
+
     def ==(other)
       return false unless other.is_a?(self.class)
       other.feature_on == feature_on && other.variant == variant && other.constraints == constraints

data/lib/determinator/target_group.rb

@@ -1,8 +1,9 @@
 module Determinator
   class TargetGroup
-    attr_reader :rollout, :constraints
+    attr_reader :name, :rollout, :constraints
 
-    def initialize(rollout:, constraints: {})
+    def initialize(rollout:, name: '', constraints: {})
+      @name = name
       @rollout = rollout
       @constraints = constraints
     end
@@ -15,9 +16,16 @@ module Determinator
       Rational(rollout, 65_536)
     end
 
+    def humanize_percentage
+      (rollout_percent * 100).to_f.round(1)
+    end
+
     def inspect
-      pc = (rollout_percent * 100).to_f.round(1)
-      "<#{pc}% of those matching: #{constraints}>"
+      "<TG name:'#{name}': #{humanize_percentage}% of those matching: #{constraints}>"
+    end
+
+    def to_explain_params
+      { name: name, rollout_percent: humanize_percentage }
     end
 
     def ==(other)

data/lib/determinator/version.rb

@@ -1,3 +1,3 @@
 module Determinator
-  VERSION = '2.5.0'
+  VERSION = '2.5.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: determinator
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.5.1
 platform: ruby
 authors:
 - JP Hastings-Spital
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-08 00:00:00.000000000 Z
+date: 2020-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -209,6 +209,8 @@ files:
 - lib/determinator/cache/fetch_wrapper.rb
 - lib/determinator/control.rb
 - lib/determinator/error_response.rb
+- lib/determinator/explainer.rb
+- lib/determinator/explainer/messages.rb
 - lib/determinator/feature.rb
 - lib/determinator/fixed_determination.rb
 - lib/determinator/missing_response.rb