flagnetic 0.1.0

data/lib/flagnetic/eval/ruleset.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flagnetic
+  module Eval
+    # SCHEMA_VERSION is the ruleset schema version this evaluator reads.
+    SCHEMA_VERSION = 1
+
+    # SCOPE is the only scope of a ruleset this evaluator reads: the
+    # document an SDK evaluates locally holds everything the environment
+    # decides, private segments included. Another scope is a document made
+    # for another reader.
+    SCOPE = "server"
+
+    # DecodeError is a document that is not a ruleset this evaluator can
+    # read.
+    class DecodeError < StandardError; end
+
+    # Ruleset is the complete evaluable configuration of one environment at
+    # one moment. Build it with Ruleset.decode. It is frozen and safe to
+    # share between threads.
+    class Ruleset
+      attr_reader :schema_version, :version, :scope, :environment, :unit_types, :attributes, :segments, :flags
+
+      # decode reads a ruleset document from JSON text. It raises
+      # DecodeError only when the document is not a ruleset this evaluator
+      # can read: malformed JSON, a field of the wrong JSON type, an
+      # unsupported schema_version or a scope other than server. Unknown
+      # fields are ignored and null reads as absent. Dangling references,
+      # invalid conditions, invalid experiment serves and constructs this
+      # evaluator does not know do not fail decoding; evaluating a flag that
+      # reaches one returns reason error with inconsistent_ruleset, so one
+      # defective flag never takes the others down.
+      def self.decode(json)
+        raise DecodeError, "decode ruleset: want JSON text, got #{json.class}" unless json.is_a?(String)
+
+        doc = JSON.parse(Values.utf8(json), freeze: true, max_nesting: 10_000)
+        new(**Document.ruleset(doc))
+      rescue JSON::ParserError, EncodingError => e
+        raise DecodeError, "decode ruleset: #{e.message}"
+      end
+
+      private_class_method :new
+
+      def initialize(schema_version:, version:, scope:, environment:, unit_types:, attributes:, segments:, flags:)
+        if schema_version != SCHEMA_VERSION
+          raise DecodeError, "decode ruleset: unsupported schema_version #{schema_version}, " \
+                             "this evaluator reads #{SCHEMA_VERSION}"
+        end
+        unless scope == SCOPE
+          raise DecodeError, "decode ruleset: scope #{scope.inspect}, this evaluator reads #{SCOPE.inspect} only"
+        end
+
+        @schema_version = schema_version
+        @version = version
+        @scope = scope
+        @environment = environment
+        @unit_types = unit_types
+        @attributes = attributes
+        @segments = segments
+        @flags = flags
+        @index = Index.new(self)
+        freeze
+      end
+
+      # protected? reports whether the ruleset belongs to a protected
+      # environment. SDKs refuse local overrides there. A document without
+      # an environment (a hand-written offline file) is unprotected.
+      def protected?
+        environment&.protected == true
+      end
+
+      # flag returns the flag with key as the document has it, or nil. SDKs
+      # check a flag's type against the one requested.
+      def flag(key)
+        @index.flags[key]&.flag
+      end
+
+      # unsupported_rules reports, by flag key, the constructs each flag
+      # holds that this evaluator does not know: an operator, a condition
+      # kind or a serve kind, typically sent by a server newer than the SDK.
+      # The constructs come in document order, each once; a flag holds what
+      # its rules hold and what the segments its rules name hold. A flag
+      # holding none is absent, so the report is empty for a ruleset this
+      # evaluator fully supports.
+      def unsupported_rules
+        @index.unsupported
+      end
+
+      # evaluate computes one flag for a context. It never reads a clock,
+      # never records an exposure and never fails: problems are results with
+      # reason error.
+      def evaluate(flag_key, context = nil)
+        Evaluation.new(@index, Context.__send__(:coerce, context)).flag(flag_key)
+      end
+
+      # evaluate_all evaluates every flag of the ruleset for a context, keyed
+      # by flag key. Prerequisite results are memoized within the call.
+      def evaluate_all(context = nil)
+        e = Evaluation.new(@index, Context.__send__(:coerce, context))
+        flags.to_h { |f| [f.key, e.flag(f.key)] }.freeze
+      end
+    end
+
+    # Document reads the decoded JSON into frozen structs, refusing a field
+    # of the wrong JSON type the way the reference evaluator's typed
+    # decoding does. A missing or null field is its zero value.
+    module Document
+      INT64 = (-(2**63))..((2**63) - 1)
+      private_constant :INT64
+
+      module_function
+
+      def ruleset(doc)
+        d = object(doc, "ruleset")
+        {
+          schema_version: int(d["schema_version"], "schema_version"),
+          version: int(d["version"], "version"),
+          scope: string(d["scope"], "scope"),
+          environment: d["environment"].nil? ? nil : environment(d["environment"]),
+          unit_types: list(d["unit_types"], "unit_types") { |u, p| string(u, p) },
+          attributes: list(d["attributes"], "attributes") { |a, p| attribute(a, p) },
+          segments: list(d["segments"], "segments") { |s, p| segment(s, p) },
+          flags: list(d["flags"], "flags") { |f, p| flag(f, p) }
+        }
+      end
+
+      def environment(value)
+        e = object(value, "environment")
+        Environment.new(key: string(e["key"], "environment.key"),
+                        protected: bool(e["protected"], "environment.protected")).freeze
+      end
+
+      def attribute(value, path)
+        a = object(value, path)
+        Attribute.new(key: string(a["key"], "#{path}.key"), type: string(a["type"], "#{path}.type")).freeze
+      end
+
+      def segment(value, path)
+        s = object(value, path)
+        Segment.new(key: string(s["key"], "#{path}.key"), private: bool(s["private"], "#{path}.private"),
+                    conditions: list(s["conditions"], "#{path}.conditions") { |c, p| condition(c, p) }).freeze
+      end
+
+      def condition(value, path)
+        c = object(value, path)
+        fields = %w[kind attribute op segment flag variation].to_h do |k|
+          [k.to_sym, string(c[k], "#{path}.#{k}")]
+        end
+        Condition.new(value: condition_value(c["value"], "#{path}.value"), **fields).freeze
+      end
+
+      # condition_value refuses a number beyond the range of a double, which
+      # the reference evaluator cannot decode into a condition value.
+      # Variation values stay raw JSON there and are not checked.
+      def condition_value(value, path)
+        case value
+        when Array then value.each_with_index { |e, i| condition_value(e, "#{path}[#{i}]") }
+        when Hash then value.each { |k, v| condition_value(v, "#{path}.#{k}") }
+        when Numeric then wrong(path, "a number within the range of a double", value) if value.to_f.infinite?
+        end
+        value
+      end
+
+      def flag(value, path)
+        f = object(value, path)
+        Flag.new(
+          key: string(f["key"], "#{path}.key"),
+          type: string(f["type"], "#{path}.type"),
+          automatic_exposure: bool(f["automatic_exposure"], "#{path}.automatic_exposure"),
+          variations: list(f["variations"], "#{path}.variations") { |v, p| variation(v, p) },
+          on: bool(f["on"], "#{path}.on"),
+          off_variation: string(f["off_variation"], "#{path}.off_variation"),
+          fallthrough: string(f["fallthrough"], "#{path}.fallthrough"),
+          prerequisites: list(f["prerequisites"], "#{path}.prerequisites") { |r, p| prerequisite(r, p) },
+          overrides: list(f["overrides"], "#{path}.overrides") { |o, p| override(o, p) },
+          rules: list(f["rules"], "#{path}.rules") { |r, p| rule(r, p) }
+        ).freeze
+      end
+
+      def variation(value, path)
+        v = object(value, path)
+        Variation.new(key: string(v["key"], "#{path}.key"), value: v["value"]).freeze
+      end
+
+      def prerequisite(value, path)
+        r = object(value, path)
+        Prerequisite.new(flag: string(r["flag"], "#{path}.flag"),
+                         variation: string(r["variation"], "#{path}.variation")).freeze
+      end
+
+      def override(value, path)
+        o = object(value, path)
+        Override.new(unit_type: string(o["unit_type"], "#{path}.unit_type"),
+                     unit_id: string(o["unit_id"], "#{path}.unit_id"),
+                     variation: string(o["variation"], "#{path}.variation")).freeze
+      end
+
+      def rule(value, path)
+        r = object(value, path)
+        Rule.new(id: string(r["id"], "#{path}.id"),
+                 conditions: list(r["conditions"], "#{path}.conditions") { |c, p| condition(c, p) },
+                 serve: serve(r["serve"], "#{path}.serve")).freeze
+      end
+
+      def serve(value, path)
+        s = object(value, path)
+        strings = %w[kind variation unit_type salt experiment inclusion_salt variation_salt].to_h do |k|
+          [k.to_sym, string(s[k], "#{path}.#{k}")]
+        end
+        Serve.new(
+          percentage: int(s["percentage"], "#{path}.percentage"),
+          traffic_allocation: int(s["traffic_allocation"], "#{path}.traffic_allocation"),
+          weights: list(s["weights"], "#{path}.weights") { |w, p| weight(w, p) },
+          **strings
+        ).freeze
+      end
+
+      def weight(value, path)
+        w = object(value, path)
+        Weight.new(variation: string(w["variation"], "#{path}.variation"),
+                   weight: int(w["weight"], "#{path}.weight")).freeze
+      end
+
+      def object(value, path)
+        return {} if value.nil?
+        return value if value.is_a?(Hash)
+
+        wrong(path, "an object", value)
+      end
+
+      def list(value, path)
+        return [].freeze if value.nil?
+
+        wrong(path, "a list", value) unless value.is_a?(Array)
+        value.each_with_index.map { |e, i| yield e, "#{path}[#{i}]" }.freeze
+      end
+
+      def string(value, path)
+        return "" if value.nil?
+        return value if value.is_a?(String)
+
+        wrong(path, "a string", value)
+      end
+
+      def bool(value, path)
+        return false if value.nil?
+        return value if [true, false].include?(value)
+
+        wrong(path, "a boolean", value)
+      end
+
+      def int(value, path)
+        return 0 if value.nil?
+        return value if value.is_a?(Integer) && INT64.cover?(value)
+
+        wrong(path, "an integer", value)
+      end
+
+      def wrong(path, want, value)
+        raise DecodeError, "decode ruleset: #{path} must be #{want}, got #{JSON.generate(value, allow_nan: true)}"
+      end
+    end
+    private_constant :Document
+  end
+end

data/lib/flagnetic/eval/semver.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Flagnetic
+  module Eval
+    # Semver is a parsed semantic version. Build metadata is dropped because
+    # it never affects precedence.
+    class Semver
+      include Comparable
+
+      CORE = /\A[0-9]+(?:\.[0-9]+){0,2}\z/
+      IDENTIFIERS = /\A[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*\z/
+      NUMERIC = /\A[0-9]+\z/
+      private_constant :CORE, :IDENTIFIERS, :NUMERIC
+
+      # parse reads an optional lower-case "v", one to three dot-separated
+      # non-negative integers (missing components are 0, so "1.41" equals
+      # "1.41.0"), an optional "-" pre-release and an optional "+" build.
+      # Numeric components are unbounded and leading zeros are ignored.
+      # Pre-release and build identifiers are non-empty runs of
+      # [0-9A-Za-z-]. It returns nil for anything else.
+      def self.parse(str)
+        return nil unless str.is_a?(String) && str.valid_encoding?
+
+        s = str.delete_prefix("v")
+        s, build = s.split("+", 2)
+        return nil if build && !build.match?(IDENTIFIERS)
+
+        s, prerelease = s.to_s.split("-", 2)
+        return nil if prerelease && !prerelease.match?(IDENTIFIERS)
+        return nil unless s.to_s.match?(CORE)
+
+        core = s.split(".").map(&:to_i)
+        new(core.fill(0, core.size...3), prerelease ? prerelease.split(".") : [])
+      end
+
+      attr_reader :core, :prerelease
+
+      def initialize(core, prerelease)
+        @core = core.freeze
+        @prerelease = prerelease.freeze
+        freeze
+      end
+
+      # <=> orders versions by SemVer 2.0.0 section 11 precedence.
+      def <=>(other)
+        return nil unless other.is_a?(Semver)
+
+        c = core <=> other.core
+        return c unless c.zero?
+        return 0 if prerelease.empty? && other.prerelease.empty?
+        return 1 if prerelease.empty?
+        return -1 if other.prerelease.empty?
+
+        prerelease.zip(other.prerelease).each do |a, b|
+          break if b.nil?
+
+          c = compare_identifiers(a, b)
+          return c unless c.zero?
+        end
+        prerelease.size <=> other.prerelease.size
+      end
+
+      private
+
+      # compare_identifiers orders pre-release identifiers: numeric ones
+      # numerically and below alphanumeric ones, alphanumeric ones in ASCII
+      # order.
+      def compare_identifiers(left, right)
+        ln = left.match?(NUMERIC)
+        rn = right.match?(NUMERIC)
+        return left.to_i <=> right.to_i if ln && rn
+        return -1 if ln
+        return 1 if rn
+
+        left.b <=> right.b
+      end
+    end
+    private_constant :Semver
+  end
+end

data/lib/flagnetic/eval/types.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Flagnetic
+  module Eval
+    # Context is the subject of an evaluation: unit IDs by unit type, and
+    # attributes. A context with no units is valid: attribute rules apply;
+    # rollouts, experiments and overrides are skipped. An empty unit ID
+    # counts as absent. Keys may be strings or symbols.
+    #
+    # Attribute values: String, true or false, a real Numeric, an Array of
+    # strings, and for dates an RFC 3339 string, integral Unix epoch
+    # milliseconds or a Time.
+    Context = Struct.new(:units, :attributes, keyword_init: true) do
+      def initialize(units: nil, attributes: nil)
+        super(units: (units || {}).transform_keys(&:to_s).freeze,
+              attributes: (attributes || {}).transform_keys(&:to_s).freeze)
+        freeze
+      end
+
+      # unit returns the unit ID of a unit type, or nil when absent.
+      def unit(unit_type)
+        id = units[unit_type]
+        id.is_a?(String) && !id.empty? ? Values.utf8(id) : nil
+      end
+
+      # coerce accepts a Context, a Hash with units and attributes, or nil.
+      def self.coerce(context)
+        case context
+        when Context then context
+        when nil then self::EMPTY
+        when Hash
+          c = context.transform_keys(&:to_s)
+          new(units: c["units"], attributes: c["attributes"])
+        else raise ArgumentError, "context must be a Flagnetic::Eval::Context or a Hash, got #{context.class}"
+        end
+      end
+      private_class_method :coerce
+    end
+    Context::EMPTY = Context.new
+
+    # REASONS are the evaluation reasons the evaluator produces. fallback
+    # and local_override are produced by SDKs, never by the evaluator.
+    REASONS = %i[off override rule rollout experiment fallthrough prerequisite_failed error].freeze
+
+    # ERROR_CODES say why a result has reason error.
+    ERROR_CODES = %i[flag_not_found prerequisite_cycle inconsistent_ruleset].freeze
+
+    # Construct is an operator, a condition kind or a serve kind of a
+    # ruleset that this evaluator does not know. kind is :operator,
+    # :condition_kind or :serve_kind.
+    Construct = Struct.new(:kind, :name) do
+      def as_json
+        { "kind" => kind.to_s, "name" => name }
+      end
+    end
+
+    # Result is the outcome of evaluating one flag for one context. Its
+    # as_json form is what the conformance fixtures compare, key for key.
+    #
+    # - type: the flag's type, and automatic_exposure its setting: with it
+    #   an SDK emits an exposure after every evaluation whose result carries
+    #   an experiment, with no second call. Both are the flag's rather than
+    #   the evaluation's and are nil only when there is no flag to read them
+    #   from, an error with flag_not_found.
+    # - value, variation: the served variation; nil for errors.
+    # - reason: one of REASONS.
+    # - rule_id: the rule that served, for reasons rule, rollout and
+    #   experiment.
+    # - experiment: an ExperimentDetail with reason experiment, and with
+    #   reason override when the override's shadow evaluation lands in a
+    #   running experiment that includes the unit.
+    # - prerequisite: the flag-level prerequisite that failed, for reason
+    #   prerequisite_failed.
+    # - bucket: the unit's bucket for reason rollout.
+    # - error_code: one of ERROR_CODES, for reason error.
+    # - override_influenced: an override decided the result, or any
+    #   prerequisite sub-evaluation consulted on the way was
+    #   override-influenced, whatever the final reason. Every exposure and
+    #   event derived from the result carries it.
+    Result = Struct.new(:type, :automatic_exposure, :value, :variation, :reason, :rule_id, :experiment,
+                        :prerequisite, :bucket, :error_code, :override_influenced, keyword_init: true) do
+      def initialize(override_influenced: false, **fields)
+        super
+        freeze
+      end
+
+      # of_flag is the result stamped with the flag it is about: every step
+      # leaves type and automatic_exposure alone, so one place fills them in
+      # for every reason a known flag can carry.
+      def of_flag(flag)
+        Result.new(**to_h, type: flag.type, automatic_exposure: flag.automatic_exposure)
+      end
+      private :of_flag
+
+      # as_json is the result's JSON form, keyed as the reference
+      # evaluator encodes it: the flag's type and automatic exposure unless
+      # there is no flag, the served value unless the reason is error, and
+      # every other field unless it is unset or an empty string.
+      def as_json
+        out = type.nil? ? {} : { "type" => type }
+        out["value"] = value unless reason == :error
+        {
+          "variation" => variation, "reason" => reason.to_s, "rule_id" => rule_id
+        }.each { |k, v| out[k] = v unless v.nil? || v == "" }
+        out["automatic_exposure"] = automatic_exposure unless type.nil?
+        {
+          "experiment" => experiment&.as_json, "prerequisite" => prerequisite,
+          "bucket" => bucket, "error_code" => error_code&.to_s
+        }.each { |k, v| out[k] = v unless v.nil? || v == "" }
+        out["override_influenced"] = override_influenced
+        out
+      end
+    end
+
+    # ExperimentDetail is everything an SDK needs to report an exposure: the
+    # one shape of experiment detail shared by local and remote evaluation.
+    # variation is the served variation: the assignment, or the override's
+    # variation when an override decided the result. override equals the
+    # result's override_influenced; exposures carrying it are excluded from
+    # analysis.
+    ExperimentDetail = Struct.new(:key, :variation, :unit_type, :unit_id, :inclusion_salt, :variation_salt,
+                                  :inclusion_bucket, :variation_bucket, :override, keyword_init: true) do
+      def initialize(**fields)
+        super
+        freeze
+      end
+
+      def as_json
+        to_h.transform_keys(&:to_s)
+      end
+    end
+
+    # The ruleset document, as decoded. Every struct is frozen.
+    Environment = Struct.new(:key, :protected, keyword_init: true)
+    Attribute = Struct.new(:key, :type, keyword_init: true)
+    Segment = Struct.new(:key, :private, :conditions, keyword_init: true)
+    Condition = Struct.new(:kind, :attribute, :op, :value, :segment, :flag, :variation, keyword_init: true)
+    Flag = Struct.new(:key, :type, :automatic_exposure, :variations, :on, :off_variation,
+                      :fallthrough, :prerequisites, :overrides, :rules, keyword_init: true)
+    Variation = Struct.new(:key, :value, keyword_init: true)
+    Prerequisite = Struct.new(:flag, :variation, keyword_init: true)
+    Override = Struct.new(:unit_type, :unit_id, :variation, keyword_init: true)
+    Rule = Struct.new(:id, :conditions, :serve, keyword_init: true)
+    Serve = Struct.new(:kind, :variation, :unit_type, :percentage, :salt, :experiment, :inclusion_salt,
+                       :variation_salt, :traffic_allocation, :weights, keyword_init: true)
+    Weight = Struct.new(:variation, :weight, keyword_init: true)
+  end
+end