lucerna 0.1.0

data/lib/lucerna/gates/evaluate.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require_relative "hashing"
+
+module Lucerna
+  module Gates
+    # The Gates evaluation engine — pure functions over a compiled runtime,
+    # no I/O. Ported line-for-line from @lucerna/gates-core
+    # (sdks/core/src/evaluate.ts) onto the frozen bucketing contract in
+    # Hashing; the golden vectors in sdks/core/src/vectors.json pin parity.
+    #
+    # The runtime document keeps its wire shape (string keys, camelCase);
+    # decisions come out symbol-keyed with reason strings identical to the
+    # wire codes.
+    #
+    # Fail-safe rule: a gate carrying any rule element this engine version
+    # doesn't recognize (unknown condition operator, unknown override kind)
+    # is answered whole with "unsupported_rule" — flag off, experiment
+    # unassigned. An engine never half-evaluates a document it doesn't
+    # fully understand.
+    module Evaluate
+      OPERATORS = %w[is is_not contains gt lt is_set].freeze
+      OVERRIDE_BY = %w[user_id domain].freeze
+      OVERRIDE_SERVE = %w[on off].freeze
+
+      module_function
+
+      # Flag precedence, first hit wins:
+      #   1. environment master switch off -> off
+      #   2. overrides, in stored order (by user id or email domain)
+      #   3. conditions — all must match (a flag's rule is a conjunction)
+      #   4. percentage rollout, sticky by user id via the stored salt
+      # A rollout between 0 and 100 with no user id serves off — there is
+      # nothing to be sticky by.
+      def flag(flag, user_id: nil, traits: nil, trace: nil)
+        unless flag["enabled"]
+          note(trace, "enabled", "flag is off in this environment")
+          return { on: false, reason: "flag_off" }
+        end
+        note(trace, "enabled", "flag is on in this environment")
+
+        bad_override = flag["overrides"].find do |override|
+          !OVERRIDE_BY.include?(override["by"]) || !OVERRIDE_SERVE.include?(override["serve"])
+        end
+        bad_operator = unsupported_operator(flag["conditions"])
+        if bad_override || bad_operator
+          note(
+            trace,
+            "unsupported",
+            if bad_operator
+              %(condition operator "#{bad_operator}" is not supported by this engine)
+            else
+              %(override kind "#{bad_override["by"]}/#{bad_override["serve"]}" is not supported by this engine)
+            end,
+          )
+          return { on: false, reason: "unsupported_rule" }
+        end
+
+        traits ||= {}
+        domain = identity_domain(traits)&.downcase
+        flag["overrides"].each do |override|
+          matched =
+            if override["by"] == "user_id"
+              !user_id.nil? && override["who"] == user_id
+            else
+              !domain.nil? && override["who"].downcase == domain
+            end
+          note(
+            trace,
+            "override",
+            %(#{override["by"]} "#{override["who"]}" serves #{override["serve"]}: #{matched ? "matched" : "no match"}),
+          )
+          return { on: override["serve"] == "on", reason: "override" } if matched
+        end
+
+        unless flag["conditions"].empty?
+          all = true
+          flag["conditions"].each do |condition|
+            matched = matches_condition?(traits, condition)
+            note(
+              trace,
+              "condition",
+              %(#{condition["trait"]} #{condition["operator"]} "#{condition["value"]}": #{matched ? "matched" : "no match"}),
+            )
+            unless matched
+              all = false
+              break
+            end
+          end
+          return { on: true, reason: "conditions" } if all
+        end
+
+        percentage = flag["rollout"]["percentage"]
+        if percentage >= 100
+          note(trace, "rollout", "rollout at 100% — everyone is in")
+          return { on: true, reason: "rollout" }
+        end
+        if percentage <= 0
+          note(trace, "rollout", "rollout at 0% — no one is in")
+          return { on: false, reason: "rollout" }
+        end
+        if user_id.nil? || user_id.empty?
+          note(trace, "rollout", "partial rollout with no userId — nothing to be sticky by")
+          return { on: false, reason: "missing_user_id" }
+        end
+        roll = Hashing.bucket(flag["rollout"]["salt"], user_id)
+        on = roll < percentage * 100
+        note(
+          trace,
+          "rollout",
+          "bucket #{roll} #{on ? "<" : ">="} threshold #{percentage * 100} (basis points of 10000)",
+        )
+        { on: on, reason: "rollout" }
+      end
+
+      # Experiment assignment, sticky per (salt, user): eligibility gates
+      # first (running, environment, audience), then the holdout and traffic
+      # dice, then an allocation-weighted walk over the variants. The salt is
+      # per iteration, so restarting an iteration reshuffles every bucket by
+      # design.
+      def experiment(experiment, audiences, user_id: nil, traits: nil, trace: nil)
+        iteration = experiment["iteration"]
+
+        unless experiment["running"]
+          note(trace, "status", "experiment is not running")
+          return no_variant(iteration, "not_running")
+        end
+        note(trace, "status", "experiment is running")
+        unless experiment["enabled"]
+          note(trace, "environment", "experiment is off in this environment")
+          return no_variant(iteration, "environment_off")
+        end
+        note(trace, "environment", "experiment is on in this environment")
+
+        traits ||= {}
+        audience_id = experiment["audienceId"]
+        if audience_id.nil?
+          note(trace, "audience", "targets everyone")
+        else
+          audience = audiences[audience_id]
+          unless audience
+            note(trace, "audience", %(audience "#{audience_id}" is not in the runtime))
+            return no_variant(iteration, "audience_not_found")
+          end
+          bad_operator = unsupported_operator(audience["conditions"])
+          if bad_operator
+            note(
+              trace,
+              "unsupported",
+              %(audience condition operator "#{bad_operator}" is not supported by this engine),
+            )
+            return no_variant(iteration, "unsupported_rule")
+          end
+          in_audience = matches_audience?(traits, audience)
+          note(
+            trace,
+            "audience",
+            %(audience "#{audience_id}" (#{audience["match"]}): #{in_audience ? "matched" : "no match"}),
+          )
+          return no_variant(iteration, "not_in_audience") unless in_audience
+        end
+
+        if user_id.nil? || user_id.empty?
+          note(trace, "identity", "no userId — assignments have nothing to be sticky by")
+          return no_variant(iteration, "missing_user_id")
+        end
+
+        holdout = experiment["holdout"]
+        if holdout.positive?
+          roll = Hashing.bucket("#{experiment["salt"]}:holdout", user_id)
+          held = roll < holdout * 100
+          note(trace, "holdout", "bucket #{roll} vs holdout #{holdout * 100}: #{held ? "held out" : "in"}")
+          return no_variant(iteration, "holdout") if held
+        end
+        traffic = experiment["traffic"]
+        if traffic < 100
+          roll = Hashing.bucket("#{experiment["salt"]}:traffic", user_id)
+          out = roll >= traffic * 100
+          note(trace, "traffic", "bucket #{roll} vs traffic #{traffic * 100}: #{out ? "out" : "in"}")
+          return no_variant(iteration, "not_in_traffic") if out
+        end
+
+        # Allocations sum to 100 (enforced on write); the last variant
+        # absorbs any rounding gap so the walk always lands.
+        roll = Hashing.bucket("#{experiment["salt"]}:variant", user_id)
+        cumulative = 0
+        experiment["variants"].each do |variant|
+          cumulative += variant["allocation"] * 100
+          if roll < cumulative
+            note(trace, "variant", %(bucket #{roll} lands in "#{variant["name"]}"))
+            return assigned(variant, iteration)
+          end
+        end
+        last = experiment["variants"].last
+        unless last
+          note(trace, "variant", "experiment has no variants")
+          return no_variant(iteration, "not_running")
+        end
+        note(trace, "variant", %(bucket #{roll} absorbed by last variant "#{last["name"]}"))
+        assigned(last, iteration)
+      end
+
+      # One identity's decisions over the entire runtime.
+      def all(runtime, user_id: nil, traits: nil)
+        {
+          kills: runtime["kills"].dup,
+          flags: runtime["flags"].to_h do |key, value|
+            [key, flag(value, user_id: user_id, traits: traits)]
+          end,
+          experiments: runtime["experiments"].to_h do |key, value|
+            [key, experiment(value, runtime["audiences"], user_id: user_id, traits: traits)]
+          end,
+        }
+      end
+
+      # -- internals ------------------------------------------------------
+
+      def no_variant(iteration, reason)
+        { variant: nil, iteration: iteration, reason: reason }
+      end
+
+      def assigned(variant, iteration)
+        {
+          variant: { id: variant["id"], name: variant["name"], is_control: variant["isControl"] },
+          iteration: iteration,
+          reason: "assigned",
+        }
+      end
+
+      # Ordering for gt/lt: numeric when both sides parse as numbers,
+      # otherwise lexicographic by UTF-16 code units (ISO dates sort
+      # correctly). Code-unit comparison — not locale collation — is part
+      # of the frozen contract.
+      def compare_values(a, b)
+        numeric_a = js_number(a)
+        numeric_b = js_number(b)
+        return numeric_a <=> numeric_b if numeric_a && numeric_b
+
+        a.encode(Encoding::UTF_16BE).b <=> b.encode(Encoding::UTF_16BE).b
+      end
+
+      # Mirrors JavaScript Number(string) for the realistic trait space:
+      # whitespace-trimmed, empty string is 0, otherwise Float parsing.
+      def js_number(value)
+        stripped = value.strip
+        return 0.0 if stripped.empty?
+
+        Float(stripped)
+      rescue ArgumentError
+        nil
+      end
+
+      def matches_condition?(traits, condition)
+        raw = traits[condition["trait"]]
+        value = condition["value"]
+        case condition["operator"]
+        when "is_set"
+          !raw.nil? && raw != ""
+        when "is"
+          raw == value
+        when "is_not"
+          raw != value
+        when "contains"
+          (raw || "").downcase.include?(value.downcase)
+        when "gt"
+          !raw.nil? && compare_values(raw, value).positive?
+        when "lt"
+          !raw.nil? && compare_values(raw, value).negative?
+        else
+          false # unreachable — callers gate on unsupported_operator
+        end
+      end
+
+      # The first operator in the list this engine doesn't know, if any.
+      def unsupported_operator(conditions)
+        conditions.find { |condition| !OPERATORS.include?(condition["operator"]) }&.fetch("operator")
+      end
+
+      # The domain an override's by: "domain" matches: an explicit `domain`
+      # trait, falling back to the part of the `email` trait after the
+      # last "@".
+      def identity_domain(traits)
+        domain = traits["domain"]
+        return domain if domain && !domain.empty?
+
+        email = traits["email"]
+        return nil if email.nil? || email.empty?
+
+        at = email.rindex("@")
+        at ? email[(at + 1)..] : nil
+      end
+
+      def matches_audience?(traits, audience)
+        conditions = audience["conditions"]
+        return true if conditions.empty?
+
+        if audience["match"] == "all"
+          conditions.all? { |condition| matches_condition?(traits, condition) }
+        else
+          conditions.any? { |condition| matches_condition?(traits, condition) }
+        end
+      end
+
+      def note(trace, step, detail)
+        trace << { step: step, detail: detail } if trace
+      end
+    end
+  end
+end

data/lib/lucerna/gates/exposures.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../http"
+
+module Lucerna
+  module Gates
+    # Exposure delivery: recorded when the app reads a variant
+    # (Client#experiment), deduped, batched, and posted fire-and-forget to
+    # POST /sdk/v1/events. Nothing here may ever raise into a read or do
+    # network on one — record is a pure queue operation; delivery happens
+    # on the poller tick (or close). Failures report through on_error and
+    # the batch drops on the floor; the server dedupes idempotently per
+    # experiment+iteration+user, so anything we resend is harmless.
+    class Exposures
+      # Local dedupe window (seconds) — the server dedupes forever; this
+      # just saves traffic.
+      DEDUPE_TTL = 600.0
+      # Queue length at which record hints the caller to wake the poller.
+      FLUSH_AT = 20
+      # The endpoint accepts at most 100 events per request.
+      MAX_REQUEST_BATCH = 100
+      # Dedupe-map bound: past this, expired entries are pruned on record.
+      MAX_SEEN = 10_000
+
+      def initialize(url:, headers:, transport:, timeout:, on_error:, dedupe_ttl: DEDUPE_TTL, clock: nil)
+        @url = url
+        @headers = headers.merge("Content-Type" => "application/json")
+        @transport = transport
+        @timeout = timeout
+        @on_error = on_error
+        @dedupe_ttl = dedupe_ttl
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @mutex = Mutex.new
+        @seen = {} # dedupe key -> monotonic time the entry expires
+        @pending = []
+      end
+
+      # Called from app threads on the read path: sync, never raises, no
+      # network. Returns true when the queue has reached FLUSH_AT and the
+      # caller should wake the delivery tick.
+      def record(event)
+        now = @clock.call
+        key = "#{event["experimentKey"]}\n#{event["iteration"]}\n#{event["userId"]}\n#{event["variantId"]}"
+        @mutex.synchronize do
+          expiry = @seen[key]
+          return false if expiry && expiry > now
+
+          prune(now) if @seen.size >= MAX_SEEN
+          @seen[key] = now + @dedupe_ttl
+          @pending << event
+          @pending.size >= FLUSH_AT
+        end
+      end
+
+      def pending_count
+        @mutex.synchronize { @pending.size }
+      end
+
+      # Forked children inherit the parent's queue; they must not replay it.
+      def clear
+        @mutex.synchronize { @pending.clear }
+      end
+
+      # Poller/close threads only. Sends everything queued in ≤100-event
+      # requests; a failed request reports and its batch drops.
+      def flush
+        loop do
+          batch = @mutex.synchronize { @pending.shift(MAX_REQUEST_BATCH) }
+          break if batch.empty?
+
+          deliver(batch)
+        end
+      end
+
+      private
+
+      def deliver(batch)
+        request = HTTP::Request.new(:post, @url, @headers, JSON.generate({ "events" => batch }))
+        response = @transport.call(request, timeout: @timeout)
+        if response.status >= 400
+          @on_error.call(
+            RequestError.new("exposure flush failed with status #{response.status}", status: response.status),
+          )
+        end
+      rescue StandardError => error
+        @on_error.call(error)
+      end
+
+      def prune(now)
+        @seen.delete_if { |_, expiry| expiry <= now }
+        return if @seen.size < MAX_SEEN
+
+        # Every entry still live: the map is genuinely at capacity, so shed
+        # the oldest entries (Hash preserves insertion order) rather than
+        # letting one hot process grow without bound.
+        @seen.keys.each do |key|
+          @seen.delete(key)
+          break if @seen.size < MAX_SEEN / 2
+        end
+      end
+    end
+  end
+end

data/lib/lucerna/gates/hashing.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Lucerna
+  module Gates
+    # The frozen bucketing contract (never change this):
+    #
+    #   bucket = murmur3_x86_32(utf8("#{salt}:#{unit_id}"), seed 0) % 10000
+    #
+    # Buckets are basis points in [0, 10000). Salts are stored in the
+    # runtime, never derived from keys. Every SDK in every language must
+    # reproduce these values bit-for-bit — the golden vectors in
+    # sdks/core/src/vectors.json enforce it.
+    module Hashing
+      MASK = 0xFFFFFFFF
+      C1 = 0xcc9e2d51
+      C2 = 0x1b873593
+
+      module_function
+
+      # MurmurHash3 x86 32-bit over the UTF-8 bytes of +input+, as uint32.
+      # 32-bit wraparound is emulated by masking after every multiply/add;
+      # Ruby's right shift on the masked non-negative value matches the
+      # reference implementation's unsigned shift.
+      def murmur3(input, seed = 0)
+        data = input.encode(Encoding::UTF_8).bytes
+        length = data.length
+        h1 = seed & MASK
+
+        block_end = length - (length % 4)
+        index = 0
+        while index < block_end
+          k1 = data[index] |
+            (data[index + 1] << 8) |
+            (data[index + 2] << 16) |
+            (data[index + 3] << 24)
+          k1 = (k1 * C1) & MASK
+          k1 = ((k1 << 15) | (k1 >> 17)) & MASK
+          k1 = (k1 * C2) & MASK
+          h1 ^= k1
+          h1 = ((h1 << 13) | (h1 >> 19)) & MASK
+          h1 = ((h1 * 5) + 0xe6546b64) & MASK
+          index += 4
+        end
+
+        k1 = 0
+        remaining = length % 4
+        k1 ^= data[index + 2] << 16 if remaining == 3
+        k1 ^= data[index + 1] << 8 if remaining >= 2
+        if remaining >= 1
+          k1 ^= data[index]
+          k1 = (k1 * C1) & MASK
+          k1 = ((k1 << 15) | (k1 >> 17)) & MASK
+          k1 = (k1 * C2) & MASK
+          h1 ^= k1
+        end
+
+        h1 ^= length
+        h1 ^= h1 >> 16
+        h1 = (h1 * 0x85ebca6b) & MASK
+        h1 ^= h1 >> 13
+        h1 = (h1 * 0xc2b2ae35) & MASK
+        h1 ^ (h1 >> 16)
+      end
+
+      # The unit's bucket for a salt, in basis points [0, 10000).
+      def bucket(salt, unit_id)
+        murmur3("#{salt}:#{unit_id}") % 10_000
+      end
+    end
+  end
+end

data/lib/lucerna/gates/runtime.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lucerna
+  module Gates
+    module Runtime
+      # The newest runtime document shape this engine understands. A
+      # document with a higher schemaVersion means the SDK needs an
+      # upgrade — keep the current runtime instead of half-reading it.
+      SCHEMA_VERSION = 1
+
+      module_function
+
+      def acceptable?(document)
+        return false unless document.is_a?(Hash)
+
+        version = document["schemaVersion"]
+        return false unless version.is_a?(Numeric) && version <= SCHEMA_VERSION
+
+        %w[kills flags experiments audiences].all? { |key| document[key].is_a?(Hash) }
+      end
+    end
+  end
+end

data/lib/lucerna/http.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+require_relative "errors"
+
+module Lucerna
+  module HTTP
+    Request = Struct.new(:method, :url, :headers, :body)
+    Response = Struct.new(:status, :headers, :body)
+
+    RETRY_BASE = 0.25
+    DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+
+    # Transport failures worth retrying — the request may never have
+    # reached the server.
+    RETRYABLE_EXCEPTIONS = [
+      SystemCallError,
+      SocketError,
+      IOError,
+      EOFError,
+      Timeout::Error, # covers Net::OpenTimeout / Net::ReadTimeout / Net::WriteTimeout
+      OpenSSL::SSL::SSLError,
+    ].freeze
+
+    # Default transport: one fresh Net::HTTP connection per call. Fine at
+    # a 10s poll cadence; connection reuse is a future optimization. Any
+    # object responding to call(request, timeout:) and returning a
+    # Response can replace it (the test seam).
+    class NetHttpTransport
+      def call(request, timeout:)
+        uri = URI.parse(request.url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+
+        klass = request.method == :post ? Net::HTTP::Post : Net::HTTP::Get
+        net_request = klass.new(uri, request.headers)
+        net_request.body = request.body if request.body
+
+        net_response = http.request(net_request)
+        headers = {}
+        net_response.each_header { |key, value| headers[key.downcase] = value }
+        Response.new(net_response.code.to_i, headers, net_response.body)
+      end
+    end
+
+    module_function
+
+    # Runs the block (which must return a Response) up to +attempts+ times
+    # with jittered exponential backoff. Only network failures and 5xx are
+    # retried; any 4xx is a stable answer and raises immediately —
+    # AuthError for 401/403. Exhausted attempts raise the last error.
+    def with_retry(attempts: 3, sleeper: DEFAULT_SLEEPER)
+      attempt = 0
+      loop do
+        attempt += 1
+        begin
+          response = yield
+          status = response.status
+          return response if status < 400
+
+          error_class = status == 401 || status == 403 ? AuthError : RequestError
+          error = error_class.new("request failed with status #{status}", status: status)
+          raise error if status < 500 || attempt >= attempts
+        rescue *RETRYABLE_EXCEPTIONS => exception
+          raise RequestError, "#{exception.class}: #{exception.message}" if attempt >= attempts
+        end
+        sleeper.call((RETRY_BASE * (2**(attempt - 1))) + (rand * 0.1))
+      end
+    end
+  end
+end