e-volv-logs 0.1.0

data/lib/evolve_logs/context.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  # TraceContext is one position in a trace. Ruby has no AsyncLocalStorage or
+  # contextvars; Thread.current[] is fiber-local, so the context flows into
+  # fibers spawned under the current thread and never leaks across threads.
+  TraceContext = Struct.new(:trace_id, :span_id, :parent_span_id) do
+    def root?
+      parent_span_id.nil? || parent_span_id.empty?
+    end
+  end
+
+  module Context
+    KEY = :__evolve_logs_trace_context__
+
+    TRACEPARENT_RE = /\A\s*00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})\s*\z/.freeze
+
+    module_function
+
+    def current
+      Thread.current[KEY]
+    end
+
+    # with installs ctx for the duration of the block and restores the
+    # previous context afterwards — including when the block raises.
+    def with(ctx)
+      previous = Thread.current[KEY]
+      Thread.current[KEY] = ctx
+      yield
+    ensure
+      Thread.current[KEY] = previous
+    end
+
+    def new_root
+      TraceContext.new(SecureRandom.hex(16), SecureRandom.hex(8), nil)
+    end
+
+    # child returns the next hop: the parent's trace id, a new span id and
+    # the parent's span id as parent. A nil parent starts a fresh root trace.
+    def child(parent)
+      return new_root if parent.nil?
+      TraceContext.new(parent.trace_id, SecureRandom.hex(8), parent.span_id)
+    end
+
+    # parse_traceparent parses a W3C traceparent header, returning nil when
+    # it is absent, malformed, or carries all-zero ids.
+    def parse_traceparent(header)
+      return nil if header.nil?
+      match = TRACEPARENT_RE.match(header.to_s.downcase)
+      return nil unless match
+      return nil if match[1].delete("0").empty? || match[2].delete("0").empty?
+      TraceContext.new(match[1], match[2], nil)
+    end
+
+    # hop returns the trace context for the next hop of the trace named by a
+    # traceparent header. A malformed or absent header starts a fresh root
+    # trace, so a producer that sends nothing still yields a trace of its own
+    # rather than an error.
+    def hop(header)
+      child(parse_traceparent(header))
+    end
+
+    def traceparent
+      tc = current
+      return nil if tc.nil?
+      "00-#{tc.trace_id}-#{tc.span_id}-01"
+    end
+  end
+end

data/lib/evolve_logs/flags/cache.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "tmpdir"
+
+require "evolve_logs/flags/kernel"
+
+module EvolveLogs
+  module Flags
+    # Ruleset cache: one envelope file per key, atomic writes (contract §6).
+    # The file name is a sha1 of the key — the key itself never appears on
+    # disk. Everything rescues to nil: caching is best-effort.
+    module Cache
+      MAX_CACHE_BYTES = 10 * 1024 * 1024
+
+      module_function
+
+      def cache_name(key)
+        "evolve-flags-#{Digest::SHA1.hexdigest(key.to_s.encode(Encoding::UTF_8))[0, 12]}.json"
+      end
+
+      def default_dir
+        File.join(Dir.tmpdir, "evolve-flags")
+      end
+
+      # parse_envelope applies the §6 reject rules to raw envelope JSON.
+      def parse_envelope(raw, kind = "ruleset")
+        return nil if raw.nil? || raw.empty? || raw.bytesize > MAX_CACHE_BYTES
+
+        env = JSON.parse(raw)
+        return nil unless env.is_a?(Hash)
+        return nil unless env["formatVersion"] == 1
+        return nil unless env["kind"] == kind
+        return nil unless env["environmentId"].is_a?(String)
+        return nil unless env["etag"].is_a?(String)
+
+        version = env["rulesetVersion"]
+        return nil unless version.is_a?(Numeric)
+        return nil if version > Kernel::RULESET_VERSION
+        return nil unless env["payload"].is_a?(Hash)
+
+        env
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+
+      def read(dir, key)
+        path = File.join(dir, cache_name(key))
+        return nil unless File.file?(path)
+        return nil if File.size(path) > MAX_CACHE_BYTES
+
+        parse_envelope(File.binread(path).force_encoding(Encoding::UTF_8))
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      # write persists the ruleset envelope atomically (temp file + rename,
+      # 0600); a payload over 10 MB is not cached. Never raises.
+      def write(dir, key, ruleset)
+        body = JSON.generate(
+          "formatVersion" => 1,
+          "kind" => "ruleset",
+          "environmentId" => ruleset["environmentId"],
+          "rulesetVersion" => ruleset["rulesetVersion"],
+          "etag" => ruleset["etag"],
+          "savedAt" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
+          "payload" => ruleset
+        )
+        return if body.bytesize > MAX_CACHE_BYTES
+
+        Dir.mkdir(dir) unless Dir.exist?(dir)
+        tmp = Tempfile.create(".evolve-flags-", dir)
+        begin
+          tmp.write(body)
+          tmp.close
+          File.chmod(0o600, tmp.path)
+          File.rename(tmp.path, File.join(dir, cache_name(key)))
+        ensure
+          tmp.close unless tmp.closed?
+        end
+        nil
+      rescue SystemCallError, IOError, TypeError, JSON::GeneratorError
+        nil
+      end
+    end
+  end
+end

data/lib/evolve_logs/flags/client.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "evolve_logs/version"
+
+require "evolve_logs/flags/kernel"
+require "evolve_logs/flags/options"
+require "evolve_logs/flags/cache"
+require "evolve_logs/flags/exposures"
+require "evolve_logs/flags/delivery"
+
+module EvolveLogs
+  module Flags
+    # The public flags handle bound to one key (docs/LAUNCH-SDK.md §3):
+    # synchronous evaluation over the held ruleset. Evaluation never blocks
+    # and never raises; the delivery thread owns the network; ready() is the
+    # only call that waits, and only because the caller chose to.
+    class Client
+      def initialize(key, options, observer_url: nil, post_json: nil)
+        @key = key
+        @options = options
+        @post_json = post_json
+        @base_url = Flags.base_url(observer_url, options.url)
+        @log = LogOnce.new
+        @ruleset = nil
+        @fetched_environment_id = nil
+        @received_from_network = false
+        @updated_at = nil
+        @ready_mutex = Mutex.new
+        @ready_cv = ConditionVariable.new
+        @listeners = []
+        @listeners_mutex = Mutex.new
+        @cache_dir = options.cache == false ? nil : (options.cache || Cache.default_dir)
+        exposures = options.exposures
+        @exposures = ExposureRecorder.new(
+          enabled: exposures[:enabled] != false,
+          sample_rate: clamp01(exposures[:sample_rate] || 1.0),
+          dedupe_window_seconds: exposures[:dedupe_window_seconds] || 60,
+          send_attributes: exposures[:send_attributes] == true,
+          private_attributes: options.private_attributes
+        )
+        @delivery = ServerDelivery.new(
+          base_url: @base_url,
+          key: key,
+          user_agent: "e-volv-logs-ruby/#{EvolveLogs::VERSION}",
+          mode: options.mode,
+          poll_interval_seconds: options.poll_interval_seconds,
+          stale_after_seconds: options.stale_after_seconds,
+          on_ruleset: ->(ruleset) { accept(ruleset, from_network: true) },
+          log: @log
+        )
+      end
+
+      def start
+        accept(@options.bootstrap, from_network: false) if @options.bootstrap.is_a?(Hash)
+        if @cache_dir
+          cached = Cache.read(@cache_dir, @key)
+          accept(cached["payload"], from_network: false) if cached && @ruleset.nil?
+        end
+        @delivery.start(@ruleset ? @ruleset["etag"] : nil)
+        nil
+      end
+
+      # -- reads -------------------------------------------------------------
+
+      # last_updated_at is the epoch seconds of the last confirmation, or of
+      # the last bootstrap/cache accept when the delivery thread has not
+      # confirmed yet.
+      def last_updated_at
+        @delivery.confirmed_at || @updated_at
+      end
+
+      def mode
+        @delivery.mode
+      end
+
+      def bool(key, default, context = nil)
+        run("boolean", key, default, context).value
+      end
+
+      def string(key, default, context = nil)
+        run("string", key, default, context).value
+      end
+
+      def number(key, default, context = nil)
+        run("number", key, default, context).value
+      end
+
+      def json(key, default, context = nil)
+        run(nil, key, default, context).value
+      end
+
+      def detail(key, default, context = nil)
+        run(nil, key, default, context)
+      end
+
+      # ready waits up to `timeout` seconds for the first ruleset from the
+      # network. Offline or bootstrap-fed clients answer immediately.
+      def ready(timeout: 5)
+        return !@ruleset.nil? if @received_from_network || @delivery.mode == "offline"
+
+        deadline = monotonic + timeout
+        @ready_mutex.synchronize do
+          until @received_from_network
+            remaining = deadline - monotonic
+            return false if remaining <= 0
+
+            @ready_cv.wait(@ready_mutex, remaining)
+          end
+        end
+        true
+      end
+
+      # on_change subscribes a listener for ruleset change notifications; the
+      # returned proc unsubscribes. Listener errors never propagate.
+      def on_change(&listener)
+        @listeners_mutex.synchronize { @listeners << listener }
+        -> { @listeners_mutex.synchronize { @listeners.delete(listener) } }
+      end
+
+      # verify pings the control plane; nil on any failure.
+      def verify
+        @delivery.ping
+      end
+
+      # -- writes ------------------------------------------------------------
+
+      def flush_exposures
+        loop do
+          batch = @exposures.drain(1000)
+          return if batch.empty?
+
+          status = 0
+          begin
+            status = @post_json ? @post_json.call("#{@base_url}/exposures", { "exposures" => batch }).to_i : 0
+          rescue StandardError
+            status = 0
+          end
+          # Sent, or an unrecoverable 4xx: drop and keep draining. 429 and
+          # transport errors requeue the batch and stop — the next flush
+          # retries.
+          next if (200..299).cover?(status) || (status != 429 && (400..499).cover?(status))
+
+          @exposures.requeue(batch)
+          return
+        end
+      rescue StandardError
+        nil
+      end
+
+      def close
+        @delivery.close
+        # An orderly shutdown persists what it can: the delivery threads are
+        # stopped (a cache write in flight finishes first), then exposures go.
+        flush_exposures
+        nil
+      end
+
+      # -- internals ---------------------------------------------------------
+
+      def run(kind, key, default, context)
+        @delivery.ensure_running
+        ruleset = @ruleset
+        if ruleset.nil?
+          @log.once("not-ready", "e-volv flags: flags not ready — serving defaults until the first ruleset arrives")
+          return Evaluation.new(default, nil, "FLAG_NOT_FOUND")
+        end
+        ctx = stringify_keys(context.nil? ? {} : context)
+        result = Kernel.evaluate(ruleset, key, default, ctx)
+        return result if %w[FLAG_NOT_FOUND ERROR].include?(result.reason)
+        return Evaluation.new(default, nil, "TYPE_MISMATCH") if kind && JsValues.js_type(result.value) != kind
+
+        @exposures.record(key, result.variant, result.reason, ctx)
+        result
+      rescue StandardError, SystemStackError
+        Evaluation.new(default, nil, "ERROR")
+      end
+
+      # accept swaps the held ruleset; from the network it also persists the
+      # cache, marks readiness and notifies listeners.
+      def accept(next_ruleset, from_network:)
+        return unless next_ruleset.is_a?(Hash)
+
+        if from_network && @fetched_environment_id &&
+           next_ruleset["environmentId"] != @fetched_environment_id
+          @log.once("environment", "e-volv flags: this key now serves a different environment")
+        end
+        previous = @ruleset
+        @ruleset = next_ruleset
+        @updated_at = Time.now.to_f
+        if from_network
+          @fetched_environment_id = next_ruleset["environmentId"]
+          Cache.write(@cache_dir, @key, next_ruleset) if @cache_dir
+          @received_from_network = true
+          @ready_mutex.synchronize { @ready_cv.broadcast }
+        end
+        changed = changed_keys(previous, next_ruleset)
+        return if changed.empty?
+
+        listeners = @listeners_mutex.synchronize { @listeners.dup }
+        listeners.each do |listener|
+          begin
+            listener.call(changed)
+          rescue StandardError
+            nil # listener errors are the caller's
+          end
+        end
+      rescue StandardError
+        nil # a bad payload never breaks availability
+      end
+
+      def changed_keys(previous, next_ruleset)
+        return [] unless previous.is_a?(Hash)
+
+        prev_flags = previous["flags"].is_a?(Hash) ? previous["flags"] : {}
+        next_flags = next_ruleset["flags"].is_a?(Hash) ? next_ruleset["flags"] : {}
+        (prev_flags.keys | next_flags.keys).select do |k|
+          JSON.generate(canonical(prev_flags[k])) != JSON.generate(canonical(next_flags[k]))
+        end.sort
+      end
+
+      # canonical renders a value with sorted hash keys so two structurally
+      # equal rulesets compare equal (notification dedupe).
+      def canonical(value)
+        case value
+        when Hash
+          out = {}
+          value.keys.map(&:to_s).sort.each do |k|
+            original = value.key?(k) ? k : value.keys.find { |x| x.to_s == k }
+            out[k] = canonical(value[original])
+          end
+          out
+        when Array
+          value.map { |v| canonical(v) }
+        else
+          value
+        end
+      end
+
+      # stringify_keys deep-converts caller contexts (which may use symbols)
+      # to the string keys the kernel and the wire speak.
+      def stringify_keys(value)
+        case value
+        when Hash
+          out = {}
+          value.each { |k, v| out[k.to_s] = stringify_keys(v) }
+          out
+        when Array
+          value.map { |v| stringify_keys(v) }
+        else
+          value
+        end
+      end
+
+      def clamp01(rate)
+        rate = rate.to_f
+        return 1.0 if rate.nan?
+
+        [[rate, 0.0].max, 1.0].min
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    # The flags handle when flags are disabled (no key, or enabled: false):
+    # defaults, FLAG_NOT_FOUND, no timers, no threads.
+    class Disabled
+      def last_updated_at
+        nil
+      end
+
+      def mode
+        "offline"
+      end
+
+      def bool(_key, default, _context = nil)
+        default
+      end
+
+      def string(_key, default, _context = nil)
+        default
+      end
+
+      def number(_key, default, _context = nil)
+        default
+      end
+
+      def json(_key, default, _context = nil)
+        default
+      end
+
+      def detail(_key, default, _context = nil)
+        Evaluation.new(default, nil, "FLAG_NOT_FOUND")
+      end
+
+      def ready(timeout: 5)
+        false
+      end
+
+      def on_change(&_listener)
+        -> {}
+      end
+
+      def verify
+        nil
+      end
+
+      def flush_exposures; end
+
+      def close; end
+
+      def start; end
+    end
+  end
+end

data/lib/evolve_logs/flags/context.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  module Flags
+    # Port of packages/flags-kernel/src/context.ts: reading a context,
+    # whatever shape it arrived in.
+    module Context
+      # The kind a context without one is taken to be.
+      DEFAULT_CONTEXT_KIND = "user"
+      # A canonical non-negative array index: "0", not "01".
+      INDEX = /\A(?:0|[1-9]\d*)\z/.freeze
+
+      module_function
+
+      # resolve splits a context into its kinds: a multi-context yields one
+      # entry per nested kind; anything else yields a single entry under its
+      # own kind, defaulting to "user".
+      def resolve(ctx)
+        resolved = {}
+        return resolved unless ctx.is_a?(Hash)
+
+        if ctx["kind"] == "multi"
+          ctx.each do |kind, nested|
+            next if kind == "kind" || !nested.is_a?(Hash)
+
+            resolved[kind] = nested.merge("kind" => kind)
+          end
+          return resolved
+        end
+
+        kind = ctx["kind"]
+        kind = DEFAULT_CONTEXT_KIND unless kind.is_a?(String) && !kind.empty?
+        resolved[kind] = ctx
+        resolved
+      end
+
+      # context_key: `key` if present and not null, else `targetingKey`; the
+      # chosen value must be a non-empty string.
+      def context_key(c)
+        return nil unless c.is_a?(Hash)
+
+        key = c["key"]
+        key = c["targetingKey"] if key.nil?
+        key.is_a?(String) && !key.empty? ? key : nil
+      end
+
+      # key_of_kind: the default kind applies only when kind is absent — an
+      # empty string is looked up as "" (PORTING.md).
+      def key_of_kind(contexts, kind = JsValues::MISSING)
+        return nil unless contexts.is_a?(Hash)
+
+        context_key(contexts[kind_or_default(kind)])
+      end
+
+      # kind_or_default: the kindOrDefault port. Absent and empty mean
+      # "user" — that is what every ruleset written before kinds meant.
+      # null is present, not absent: it names a kind no context carries, so
+      # the lookup misses. Collapsing null into "user" would make a rule the
+      # author misconfigured silently target everybody.
+      def kind_or_default(kind)
+        kind.equal?(JsValues::MISSING) || kind == "" ? DEFAULT_CONTEXT_KIND : kind
+      end
+
+      # attribute_path splits an attribute reference: `/address/city` is a
+      # JSON-pointer-style path (~1 → /, ~0 → ~), `address.city` the earlier
+      # e-volv spelling, anything else one literal key.
+      def attribute_path(a)
+        if a.start_with?("/")
+          return a[1..-1].split("/")
+                     .map { |part| part.gsub("~1", "/").gsub("~0", "~") }
+                     .reject { |part| part.empty? }
+        end
+        return a.split(".") if a.include?(".")
+
+        [a]
+      end
+
+      # attribute_of reads one attribute off one context. `key`, `kind`,
+      # `name` and `anonymous` are built in and always answer; the absent
+      # sentinel means "no value".
+      def attribute_of(c, a)
+        return JsValues::MISSING unless c.is_a?(Hash)
+
+        # The one alias: every ruleset and every OpenFeature caller written
+        # before contexts says `targetingKey` where it means the key.
+        if a == "targetingKey" || a == "key"
+          key = context_key(c)
+          return key.nil? ? JsValues::MISSING : key
+        end
+        if a == "kind"
+          kind = c["kind"]
+          return kind.nil? ? DEFAULT_CONTEXT_KIND : kind
+        end
+
+        cursor = c
+        attribute_path(a).each do |segment|
+          return JsValues::MISSING unless cursor.is_a?(Hash) || cursor.is_a?(Array)
+
+          cursor = step(cursor, segment)
+        end
+        cursor
+      end
+
+      # attribute_of_kind reads an attribute from the named kind; absent or
+      # empty kind means "user", null names a kind no context carries and
+      # misses (PORTING.md).
+      def attribute_of_kind(contexts, kind, a)
+        return JsValues::MISSING unless contexts.is_a?(Hash)
+
+        attribute_of(contexts[kind_or_default(kind)], a)
+      end
+
+      # step: a hash answers a key lookup; an array answers a canonical index
+      # or `length`; anything else is absent.
+      def step(cursor, segment)
+        if cursor.is_a?(Hash)
+          return cursor.key?(segment) ? cursor[segment] : JsValues::MISSING
+        end
+        if cursor.is_a?(Array)
+          return cursor.length if segment == "length"
+          return cursor[segment.to_i] if INDEX.match?(segment) && segment.to_i < cursor.length
+        end
+
+        JsValues::MISSING
+      end
+    end
+  end
+end