flagnetic 0.1.0

data/lib/flagnetic/controller_helpers.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "version"
+
+module Flagnetic
+  # ControllerHelpers builds the context of the current request; the
+  # railtie includes it in every controller and makes flagnetic_context a
+  # view helper.
+  #
+  #   Flagnetic.client.bool("new_checkout", default: false, context: flagnetic_context)
+  #
+  # The context holds the configured unit types:
+  #
+  # - config.flagnetic.user_unit_type: the unit type of the signed-in user,
+  #   whose ID config.flagnetic.user_id reads (a callable receiving the
+  #   controller; by default current_user&.id where the controller has
+  #   current_user, else session[:user_id]). Absent while signed out.
+  # - config.flagnetic.anonymous_unit_type: the unit type of a random ID
+  #   generated on the first request and kept in the cookie named by
+  #   config.flagnetic.anonymous_cookie. Signing in keeps it, so the context
+  #   of a signed-in user carries both IDs and an experiment spanning
+  #   sign-up keeps its variation; call Flagnetic.client.alias
+  #   with flagnetic_anonymous_id at sign-up to link them for analysis.
+  #
+  # Neither is set by default: the SDK never invents a unit type. The
+  # attributes are the predeclared sdk and sdk_version, platform and
+  # app_version when configured, and whatever config.flagnetic.attributes
+  # (a callable receiving the controller) returns, which wins over them.
+  module ControllerHelpers
+    # SIGNED_IN_USER_ID is the default config.flagnetic.user_id.
+    SIGNED_IN_USER_ID = lambda { |controller|
+      if controller.respond_to?(:current_user, true)
+        controller.__send__(:current_user)&.id
+      else
+        controller.session[:user_id]
+      end
+    }
+
+    # ANONYMOUS_ID_FORMAT is what a kept anonymous ID may look like; anything else
+    # in the cookie is replaced by a new one.
+    ANONYMOUS_ID_FORMAT = /\A[A-Za-z0-9_-]{1,64}\z/
+
+    def self.included(base)
+      base.helper_method(:flagnetic_context, :flagnetic_anonymous_id) if base.respond_to?(:helper_method)
+    end
+
+    # flagnetic_context returns the context of the current request, built
+    # once per request.
+    def flagnetic_context
+      @flagnetic_context ||= { units: flagnetic_units(flagnetic_config),
+                               attributes: flagnetic_attributes(flagnetic_config) }.freeze
+    end
+
+    # flagnetic_anonymous_id returns the anonymous ID of the current
+    # visitor, generating it and setting its cookie on the first request,
+    # or nil when no anonymous unit type is configured.
+    def flagnetic_anonymous_id
+      return @flagnetic_anonymous_id if defined?(@flagnetic_anonymous_id)
+
+      config = flagnetic_config
+      @flagnetic_anonymous_id = (flagnetic_cookie_id(config.anonymous_cookie) if config.anonymous_unit_type)
+    end
+
+    private
+
+    def flagnetic_config = ::Rails.application.config.flagnetic
+
+    def flagnetic_units(config)
+      units = {}
+      units[config.anonymous_unit_type.to_s] = flagnetic_anonymous_id if config.anonymous_unit_type
+      if config.user_unit_type
+        id = config.user_id.call(self)
+        units[config.user_unit_type.to_s] = id.to_s if id.present?
+      end
+      units
+    end
+
+    def flagnetic_attributes(config)
+      attributes = { "sdk" => "flagnetic-ruby", "sdk_version" => VERSION }
+      attributes["platform"] = config.platform if config.platform
+      attributes["app_version"] = config.app_version if config.app_version
+      own = config.attributes&.call(self) || {}
+      attributes.merge(own.to_h.transform_keys(&:to_s))
+    end
+
+    def flagnetic_cookie_id(name)
+      jar = request.cookie_jar
+      id = jar[name]
+      return id if id.is_a?(String) && id.match?(ANONYMOUS_ID_FORMAT)
+
+      id = SecureRandom.uuid
+      jar.permanent[name] = { value: id, httponly: true, same_site: :lax, secure: request.ssl? }
+      id
+    end
+  end
+end

data/lib/flagnetic/detail.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Flagnetic
+  # REASONS are the evaluation reasons a Detail carries. The evaluator
+  # produces the first eight; the SDK produces local_override and
+  # fallback. A getter never serves error: an evaluator error serves the
+  # built-in default with reason fallback.
+  REASONS = %i[rule rollout experiment override prerequisite_failed error off fallthrough local_override
+               fallback].freeze
+
+  # STAGES are the steps of the fallback chain. built_in: no ruleset was
+  # ever received, getters serve built-in defaults. last_good: the held
+  # ruleset came from an earlier success, or from the store, and the most
+  # recent attempt failed. fresh: the most recent attempt succeeded, a 304
+  # included. An offline client is always fresh once its document loads.
+  STAGES = %i[built_in last_good fresh].freeze
+
+  # ERROR_CODES say why a Detail has reason fallback: the evaluator's four,
+  # then type_mismatch (the flag's type differs from the getter's),
+  # no_ruleset (stage built_in) and general (an internal failure caught at
+  # the API boundary).
+  ERROR_CODES = %i[flag_not_found server_only prerequisite_cycle inconsistent_ruleset type_mismatch no_ruleset
+                   general].freeze
+
+  # Detail is a served value and why it was served.
+  #
+  # - value: the served value (true or false, a String, a Numeric, or for a
+  #   JSON flag the parsed, frozen value), or the built-in default as passed
+  #   with reason fallback.
+  # - reason: one of REASONS. variation and rule_id as the evaluator sets
+  #   them; error_code with reason fallback.
+  # - ruleset_version, received_at: the ruleset evaluated against, nil at
+  #   stage built_in. The age of a last good ruleset is observable through
+  #   received_at.
+  # - stage: one of STAGES, at the moment of the evaluation.
+  # - overridden: a platform override decided the value, directly or
+  #   through a prerequisite. A local override is reason local_override
+  #   instead.
+  # - experiment: an Eval::ExperimentDetail when the value came from a
+  #   running experiment, an override landing in one included.
+  Detail = Struct.new(:value, :reason, :variation, :rule_id, :error_code, :ruleset_version, :received_at, :stage,
+                      :overridden, :experiment, keyword_init: true) do
+    def initialize(overridden: false, **fields)
+      super
+      freeze
+    end
+  end
+
+  # Status is the state of the fallback chain: the stage, and since when
+  # the held ruleset is stale (the time of the first failed attempt since
+  # the last success), nil while the most recent attempt succeeded.
+  Status = Struct.new(:stage, :stale_since, keyword_init: true) do
+    def initialize(**fields)
+      super
+      freeze
+    end
+  end
+
+  # Error is the base of every error the SDK raises. Getters never raise.
+  class Error < StandardError; end
+
+  # LocalOverridesNotAllowed is raised by LocalOverrides#set on a client
+  # constructed without allow_overrides: true.
+  class LocalOverridesNotAllowed < Error; end
+
+  # LocalOverrideRefused is raised by LocalOverrides#set when the held
+  # ruleset belongs to a protected environment.
+  class LocalOverrideRefused < Error; end
+
+  # OfflineError is raised by Client#reload when the offline document
+  # cannot be read or decoded; the held ruleset stays.
+  class OfflineError < Error; end
+end

data/lib/flagnetic/eval/evaluation.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+module Flagnetic
+  # Eval is the evaluator; see flagnetic/eval.rb.
+  module Eval
+    # Index holds the flag and segment maps and the conditions of a decoded
+    # ruleset, compiled once, and what the ruleset holds that this evaluator
+    # does not know.
+    class Index
+      # invalid_serves marks, by rule index, the experiment serves that
+      # break the invariants every experiment serve holds (see
+      # Compiler#valid_experiment?), so evaluation reaching one answers
+      # inconsistent_ruleset without checking them again.
+      CompiledFlag = Struct.new(:flag, :variations, :rules, :invalid_serves)
+      # CompiledCondition is a condition prepared once at decode time. error
+      # is set when it cannot be evaluated against this document; evaluating
+      # it then yields inconsistent_ruleset. unsupported is the construct of
+      # an error that comes from an operator or condition kind this
+      # evaluator does not know.
+      CompiledCondition = Struct.new(:kind, :error, :attribute, :names_unit, :match, :segment, :flag, :variation,
+                                     :unsupported)
+      # CompiledSegment is a segment's conditions and the unsupported
+      # constructs it holds.
+      CompiledSegment = Struct.new(:conditions, :unsupported)
+
+      attr_reader :flags, :segments, :unsupported
+
+      def initialize(ruleset)
+        # A unit type named as an attribute is a string attribute holding
+        # that unit's ID.
+        units = ruleset.unit_types.to_h { |u| [u, true] }
+        types = ruleset.attributes.to_h { |a| [a.key, a.type] }.merge(units.transform_values { "string" })
+        compiler = Compiler.new(types, units)
+        @segments = ruleset.segments.to_h { |s| [s.key, compiler.segment(s)] }.freeze
+        @flags = {}
+        @unsupported = {}
+        ruleset.flags.each do |f|
+          @flags[f.key] = compiler.flag(f)
+          found = compiler.unsupported_in(f, @flags[f.key], @segments)
+          @unsupported[f.key] = found.freeze unless found.empty?
+        end
+        @flags.freeze
+        @unsupported.freeze
+        freeze
+      end
+    end
+
+    # The condition kinds and serve kinds this evaluator knows.
+    CONDITION_KINDS = %w[attribute in_segment not_in_segment prerequisite].freeze
+    SERVE_KINDS = %w[variation rollout experiment].freeze
+    private_constant :CONDITION_KINDS, :SERVE_KINDS
+
+    # Compiler compiles the conditions of one ruleset against its declared
+    # attribute types and unit types.
+    Compiler = Struct.new(:types, :units) do
+      def segment(segment)
+        found = []
+        conditions = segment.conditions.map do |c|
+          next add_unsupported(found, compile(c)) if c.kind == "attribute"
+
+          error = "segment #{segment.key.inspect} has a #{c.kind.inspect} condition"
+          unknown = construct(:condition_kind, c.kind) unless CONDITION_KINDS.include?(c.kind)
+          add_unsupported(found, invalid(c, error, unknown))
+        end
+        Index::CompiledSegment.new(conditions.freeze, found.freeze).freeze
+      end
+
+      def flag(flag)
+        variations = flag.variations.to_h { |v| [v.key, v.value] }.freeze
+        rules = flag.rules.map { |r| r.conditions.map { |c| compile(c) }.freeze }.freeze
+        invalid_serves = flag.rules.map { |r| r.serve.kind == "experiment" && !valid_experiment?(r.serve, variations) }
+        Index::CompiledFlag.new(flag, variations, rules, invalid_serves.freeze).freeze
+      end
+
+      # unsupported_in lists the constructs a compiled flag holds that this
+      # evaluator does not know, in document order, each once: those of its
+      # rules, and of the segments its rules name.
+      def unsupported_in(flag, compiled, segments)
+        found = []
+        flag.rules.each_with_index do |rule, i|
+          compiled.rules[i].each do |c|
+            add_unsupported(found, c)
+            next if c.segment.to_s.empty?
+
+            segments[c.segment]&.unsupported&.each { |u| found << u unless found.include?(u) }
+          end
+          kind = rule.serve.kind
+          add_construct(found, construct(:serve_kind, kind)) unless SERVE_KINDS.include?(kind)
+        end
+        found
+      end
+
+      private
+
+      # valid_experiment? reports whether an experiment serve holds what
+      # assigning a unit to a variation relies on: an experiment key, a unit
+      # type and both salts; a traffic allocation within 0 to 10000; and at
+      # least two weights, none negative, each naming a distinct variation
+      # of the flag, summing to exactly 10000. Any other serve would assign
+      # units to variations the experiment does not compare, or to none, so
+      # every evaluator refuses it the same way instead of each assigning
+      # its own way.
+      def valid_experiment?(serve, variations)
+        return false if [serve.experiment, serve.unit_type, serve.inclusion_salt, serve.variation_salt].any?(&:empty?)
+        return false unless (0..BUCKETS).cover?(serve.traffic_allocation) && serve.weights.size >= 2
+
+        named = serve.weights.map(&:variation)
+        named.uniq.size == named.size && named.all? { |v| variations.key?(v) } &&
+          serve.weights.none? { |w| w.weight.negative? } && serve.weights.sum(&:weight) == BUCKETS
+      end
+
+      def add_unsupported(found, compiled)
+        add_construct(found, compiled.unsupported)
+        compiled
+      end
+
+      def add_construct(found, construct)
+        found << construct if construct && !found.include?(construct)
+      end
+
+      # construct is the unsupported construct of a kind with a name; none
+      # for a missing name: no server sends that, so it is a defect of the
+      # ruleset rather than a reason to upgrade.
+      def construct(kind, name)
+        Construct.new(kind, name).freeze unless name.empty?
+      end
+
+      def invalid(cond, error, unsupported = nil)
+        Index::CompiledCondition.new(cond.kind, error, nil, nil, nil, nil, nil, nil, unsupported).freeze
+      end
+
+      def compile(cond)
+        case cond.kind
+        when "attribute" then compile_attribute(cond)
+        when "in_segment", "not_in_segment"
+          Index::CompiledCondition.new(cond.kind, nil, nil, false, nil, cond.segment).freeze
+        when "prerequisite"
+          Index::CompiledCondition.new(cond.kind, nil, nil, false, nil, nil, cond.flag, cond.variation).freeze
+        else
+          invalid(cond, "unknown condition kind #{cond.kind.inspect}", construct(:condition_kind, cond.kind))
+        end
+      end
+
+      def compile_attribute(cond)
+        unless Operators::KNOWN.include?(cond.op)
+          return invalid(cond, "unknown operator #{cond.op.inspect}", construct(:operator, cond.op))
+        end
+
+        type = types[cond.attribute]
+        return invalid(cond, "attribute #{cond.attribute.inspect} is not declared") unless type
+
+        match = Operators.compile(type, cond.op, cond.value)
+        Index::CompiledCondition.new(cond.kind, nil, cond.attribute, units.key?(cond.attribute), match).freeze
+      rescue Operators::Error => e
+        invalid(cond, "attribute #{cond.attribute.inspect}: #{e.message}")
+      end
+    end
+    private_constant :Index, :Compiler
+
+    # Evaluation is the state of one evaluate or evaluate_all call: the
+    # flags on the current prerequisite path, and every flag result
+    # computed so far.
+    #
+    # For one flag and one context:
+    #
+    # 1. An absent flag is error flag_not_found.
+    # 2. A flag that is off serves its off variation, reason off.
+    # 3. The first override whose unit type is in the context with an equal
+    #    unit ID serves its variation, reason override, override_influenced
+    #    true. Steps 4 and 5 then run in shadow, ignoring the override; when
+    #    they end in an experiment that includes the unit, the result
+    #    carries that experiment's detail with override true and the served
+    #    variation.
+    # 4. Flag-level prerequisites in order: each evaluates the prerequisite
+    #    flag with the same context and holds when its reason is neither off
+    #    nor error and it serves the required variation. The first failure
+    #    serves the off variation, reason prerequisite_failed, naming that
+    #    prerequisite. A flag met again on the current prerequisite path is
+    #    error prerequisite_cycle. An error in a prerequisite becomes the
+    #    dependent flag's error.
+    # 5. Rules in order, first match wins; a rule's conditions in order,
+    #    stopping at the first false one. A rollout or experiment whose unit
+    #    type is absent, or whose unit falls outside it, lets evaluation
+    #    continue with the next rule.
+    # 6. No rule matched: the fallthrough variation, reason fallthrough.
+    # 7. A variation, segment, flag or attribute referenced but missing from
+    #    the document, or a condition that cannot be evaluated, is error
+    #    inconsistent_ruleset, only when evaluation reaches it.
+    class Evaluation
+      # Failure carries an error code out of nested condition evaluation.
+      Failure = Struct.new(:code)
+      private_constant :Failure
+
+      def initialize(index, context)
+        @index = index
+        @context = context
+        @visiting = {}
+        @memo = {}
+      end
+
+      # flag evaluates a flag by key. A flag reached again while it is on
+      # the current prerequisite path is a cycle.
+      def flag(key)
+        return @memo[key] if @memo.key?(key)
+
+        f = @index.flags[key]
+        return error(:flag_not_found) unless f
+        return error(:prerequisite_cycle).__send__(:of_flag, f.flag) if @visiting.key?(key)
+
+        @visiting[key] = true
+        result = compute(f).__send__(:of_flag, f.flag)
+        @visiting.delete(key)
+        @memo[key] = result
+      end
+
+      private
+
+      def error(code, influenced = false) # rubocop:disable Style/OptionalBooleanParameter
+        Result.new(reason: :error, error_code: code, override_influenced: influenced)
+      end
+
+      def compute(cf)
+        f = cf.flag
+        return serve(cf, f.off_variation, reason: :off) unless f.on
+
+        f.overrides.each do |o|
+          next unless @context.unit(o.unit_type) == o.unit_id
+
+          r = serve(cf, o.variation, reason: :override, override_influenced: true)
+          return r if r.reason == :error
+
+          shadow = body(cf)
+          return r unless shadow.reason == :experiment
+
+          x = shadow.experiment.to_h.merge(variation: r.variation, override: true)
+          return Result.new(**r.to_h, experiment: ExperimentDetail.new(**x))
+        end
+        body(cf)
+      end
+
+      # body runs steps 4 to 6: prerequisites, rules and the fallthrough.
+      def body(cf)
+        f = cf.flag
+        influenced = [false]
+
+        f.prerequisites.each do |p|
+          held = prerequisite(p.flag, p.variation, influenced)
+          return error(held.code, influenced[0]) if held.is_a?(Failure)
+          next if held
+
+          return serve(cf, f.off_variation, reason: :prerequisite_failed, prerequisite: p.flag,
+                                            override_influenced: influenced[0])
+        end
+
+        f.rules.each_with_index do |rule, i|
+          matched = conditions(cf.rules[i], influenced)
+          return error(matched.code, influenced[0]) if matched.is_a?(Failure)
+          next unless matched
+          return error(:inconsistent_ruleset, influenced[0]) if cf.invalid_serves[i]
+
+          r = serve_rule(cf, rule, influenced[0])
+          return r if r
+        end
+
+        serve(cf, f.fallthrough, reason: :fallthrough, override_influenced: influenced[0])
+      end
+
+      # serve_rule serves a matching rule, or returns nil when a rollout or
+      # experiment leaves the unit out and evaluation continues.
+      def serve_rule(cf, rule, influenced)
+        s = rule.serve
+        case s.kind
+        when "variation"
+          serve(cf, s.variation, reason: :rule, rule_id: rule.id, override_influenced: influenced)
+        when "rollout"
+          id = @context.unit(s.unit_type)
+          bucket = id && Murmur3.bucket(s.salt, id)
+          return nil unless bucket && bucket < s.percentage
+
+          serve(cf, s.variation, reason: :rollout, rule_id: rule.id, bucket: bucket, override_influenced: influenced)
+        when "experiment"
+          experiment(cf, rule, influenced)
+        else
+          error(:inconsistent_ruleset, influenced)
+        end
+      end
+
+      def experiment(cf, rule, influenced)
+        s = rule.serve
+        id = @context.unit(s.unit_type)
+        return nil unless id
+
+        inclusion = Murmur3.bucket(s.inclusion_salt, id)
+        return nil unless inclusion < s.traffic_allocation
+
+        variation_bucket = Murmur3.bucket(s.variation_salt, id)
+        assigned = assign(s.weights, variation_bucket)
+        return error(:inconsistent_ruleset, influenced) unless assigned
+
+        r = serve(cf, assigned, reason: :experiment, rule_id: rule.id, override_influenced: influenced)
+        return r if r.reason == :error
+
+        Result.new(**r.to_h, experiment: ExperimentDetail.new(
+          key: s.experiment, variation: assigned, unit_type: s.unit_type, unit_id: id,
+          inclusion_salt: s.inclusion_salt, variation_salt: s.variation_salt,
+          inclusion_bucket: inclusion, variation_bucket: variation_bucket, override: influenced
+        ))
+      end
+
+      # assign walks weights in list order; variation i covers
+      # [sum(w_0..w_{i-1}), sum(w_0..w_i)).
+      def assign(weights, bucket)
+        upper = 0
+        weights.each do |w|
+          upper += w.weight
+          return w.variation if bucket < upper
+        end
+        nil
+      end
+
+      # serve builds a result serving a variation of the flag, or
+      # inconsistent_ruleset when the variation is missing (step 7).
+      def serve(cf, variation, **fields)
+        unless cf.variations.key?(variation)
+          return error(:inconsistent_ruleset,
+                       fields.fetch(:override_influenced, false))
+        end
+
+        Result.new(value: cf.variations[variation], variation: variation, **fields)
+      end
+
+      # prerequisite evaluates another flag for the same context. It holds
+      # when that flag's reason is neither off nor error and it serves the
+      # required variation. An error in the prerequisite is a defect of the
+      # ruleset and is returned as a Failure, so it surfaces on the
+      # dependent flag instead of silently serving its off variation.
+      # Influence accumulates into influenced[0].
+      def prerequisite(key, variation, influenced)
+        f = @index.flags[key]
+        return Failure.new(:inconsistent_ruleset) if f.nil? || !f.variations.key?(variation)
+
+        r = flag(key)
+        influenced[0] ||= r.override_influenced
+        return Failure.new(r.error_code) if r.reason == :error
+
+        r.reason != :off && r.variation == variation
+      end
+
+      # conditions evaluates an AND-set in order and stops at the first false
+      # condition; later conditions are not evaluated and cannot influence
+      # the result.
+      def conditions(conds, influenced)
+        conds.each do |c|
+          held = condition(c, influenced)
+          return held if held.is_a?(Failure) || !held
+        end
+        true
+      end
+
+      def condition(cond, influenced)
+        return Failure.new(:inconsistent_ruleset) if cond.error
+
+        case cond.kind
+        when "attribute"
+          value = cond.names_unit ? @context.unit(cond.attribute) : @context.attributes[cond.attribute]
+          cond.match.call(value)
+        when "in_segment", "not_in_segment"
+          segment = @index.segments[cond.segment]
+          return Failure.new(:inconsistent_ruleset) unless segment
+
+          inside = conditions(segment.conditions, influenced)
+          return inside if inside.is_a?(Failure)
+
+          inside == (cond.kind == "in_segment")
+        else
+          prerequisite(cond.flag, cond.variation, influenced)
+        end
+      end
+    end
+    private_constant :Evaluation
+  end
+end

data/lib/flagnetic/eval/instant.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Flagnetic
+  module Eval
+    # Instant reads dates as integer nanoseconds since the Unix epoch, the
+    # way the reference evaluator's time.Parse(time.RFC3339Nano) and
+    # time.UnixMilli read them.
+    module Instant
+      RFC3339 = /\A(\d{4})-(\d{2})-(\d{2})T(\d{1,2}):(\d{2}):(\d{2})(?:[.,](\d+))?(?:(Z)|([+-])(\d{2}):(\d{2}))\z/
+      MAX_EPOCH_MILLIS = 2**53
+      private_constant :RFC3339, :MAX_EPOCH_MILLIS
+
+      module_function
+
+      # from_context reads a context value: an RFC 3339 string with an
+      # offset, an integral number of Unix epoch milliseconds or a Time.
+      def from_context(value)
+        case value
+        when String then parse_rfc3339(value)
+        when Time then (value.to_r * 1_000_000_000).floor
+        when true, false, nil then nil
+        else
+          ms = Values.number(value)
+          return nil unless ms && ms == ms.truncate && ms.abs <= MAX_EPOCH_MILLIS
+
+          ms.to_i * 1_000_000
+        end
+      end
+
+      # parse_rfc3339 accepts what Go's time.Parse with RFC3339Nano accepts:
+      # an upper-case T and Z, a one- or two-digit hour, a fraction after .
+      # or , truncated to nanoseconds, and an offset of at most 24:60.
+      def parse_rfc3339(str)
+        m = str.valid_encoding? && RFC3339.match(str)
+        return nil unless m
+
+        year, month, day, hour, min, sec = m.captures[0, 6].map(&:to_i)
+        return nil unless valid_date?(year, month, day) && hour < 24 && min < 60 && sec < 60
+
+        offset = offset_seconds(m)
+        return nil unless offset
+
+        seconds = Time.utc(year, month, day, hour, min, sec).to_i - offset
+        (seconds * 1_000_000_000) + m[7].to_s[0, 9].ljust(9, "0").to_i
+      end
+
+      def offset_seconds(match)
+        return 0 if match[8]
+
+        hours = match[10].to_i
+        minutes = match[11].to_i
+        return nil if hours > 24 || minutes > 60
+
+        seconds = (hours * 3600) + (minutes * 60)
+        match[9] == "-" ? -seconds : seconds
+      end
+
+      def valid_date?(year, month, day)
+        return false unless month.between?(1, 12) && day >= 1
+
+        days = [31, leap?(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1]
+        day <= days
+      end
+
+      def leap?(year)
+        (year % 4).zero? && (!(year % 100).zero? || (year % 400).zero?)
+      end
+    end
+    private_constant :Instant
+  end
+end

data/lib/flagnetic/eval/murmur3.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Flagnetic
+  # Eval is the evaluator; see flagnetic/eval.rb.
+  module Eval
+    # BUCKETS is the number of buckets a unit is hashed into. A percentage in
+    # basis points (0 to 10000) is compared against a bucket directly.
+    BUCKETS = 10_000
+
+    # Murmur3 is MurmurHash3 x86 32-bit with seed 0 over the bytes of a
+    # string, read as an unsigned integer. Hashing UTF-16 or reading the
+    # result as signed gives different buckets and fails the murmur3 vectors.
+    module Murmur3
+      C1 = 0xcc9e2d51
+      C2 = 0x1b873593
+      MASK = 0xffffffff
+
+      module_function
+
+      # bucket computes the bucket of a unit for a salt:
+      #
+      #   murmur3_32(utf8("{salt}.{unit_id}"), seed 0) mod 10000
+      #
+      # on the unsigned hash, giving 0 to 9999. A unit is inside
+      # percentage p when its bucket is below p. It equals ClickHouse
+      # murmurHash3_32(concat(salt, '.', unit_id)) % 10000.
+      def bucket(salt, unit_id)
+        hash32("#{salt.b}.#{unit_id.b}") % BUCKETS
+      end
+
+      def hash32(data)
+        bytes = data.b
+        h = 0
+        blocks = bytes.bytesize / 4
+        bytes.unpack("V#{blocks}").each do |k|
+          h ^= mix(k)
+          h = rotl(h, 13)
+          h = ((h * 5) + 0xe6546b64) & MASK
+        end
+        tail = bytes.byteslice(blocks * 4, 3).bytes
+        unless tail.empty?
+          k = tail.each_with_index.sum { |b, i| b << (8 * i) }
+          h ^= mix(k)
+        end
+        fmix(h ^ (bytes.bytesize & MASK))
+      end
+
+      def mix(key)
+        k = (key * C1) & MASK
+        k = rotl(k, 15)
+        (k * C2) & MASK
+      end
+
+      def fmix(hash)
+        h = hash
+        h ^= h >> 16
+        h = (h * 0x85ebca6b) & MASK
+        h ^= h >> 13
+        h = (h * 0xc2b2ae35) & MASK
+        h ^ (h >> 16)
+      end
+
+      def rotl(value, bits)
+        ((value << bits) | (value >> (32 - bits))) & MASK
+      end
+      private_class_method :mix, :fmix, :rotl
+    end
+    private_constant :Murmur3
+  end
+end