e-volv-logs 0.1.0

data/lib/evolve_logs/flags/delivery.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require "evolve_logs/flags/kernel"
+require "evolve_logs/flags/sse"
+
+module EvolveLogs
+  module Flags
+    # A flag condition is logged once, not once per evaluation: the first
+    # occurrence writes one line to stderr, later ones are silent until the
+    # condition resets (a confirmation resets outage/stale/auth).
+    class LogOnce
+      def initialize
+        @seen = {}
+        @mutex = Mutex.new
+      end
+
+      def once(log_id, message)
+        @mutex.synchronize do
+          return if @seen[log_id]
+
+          @seen[log_id] = true
+        end
+        $stderr.puts(message)
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def reset(log_id)
+        @mutex.synchronize { @seen.delete(log_id) }
+        nil
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Server ruleset delivery: bootstrap + SSE stream with polling fallback.
+    # One daemon thread owns the state machine; evaluation threads never
+    # touch it except to read confirmed_at (docs/LAUNCH-SDK.md §4, §5;
+    # PORTING.md "Delivery behaviour"). Fork safety lives in ensure_running.
+    class ServerDelivery
+      STREAM_IDLE_S = 60.0          # no bytes for this long → abort the stream
+      STREAM_RETRY_WHILE_POLLING_S = 300.0
+      AUTH_RETRY_S = 300.0
+
+      attr_reader :mode
+      attr_accessor :confirmed_at
+
+      def initialize(base_url:, key:, user_agent:, mode:, poll_interval_seconds:, stale_after_seconds:,
+                     on_ruleset:, log:, rng: nil)
+        @base_url = base_url
+        @key = key
+        @user_agent = user_agent
+        @mode = mode
+        @poll_interval = [15.0, poll_interval_seconds.to_f].max
+        @stale_after = stale_after_seconds.to_f
+        @on_ruleset = on_ruleset
+        @log = log
+        @rng = rng || Random
+        @confirmed_at = nil
+        @disabled = false
+        @etag = nil
+        @stop = false
+        @closed = false
+        @thread = nil
+        @stale_thread = nil
+        @pid = nil
+        @launch_mutex = Mutex.new
+        @wake_mutex = Mutex.new
+        @wake = ConditionVariable.new
+        @next_poll = 0.0
+        @next_stream = 0.0
+        @stream_failures = 0
+        @stream_http = nil
+      end
+
+      def disabled?
+        @disabled
+      end
+
+      # -- lifecycle -------------------------------------------------------
+
+      def start(held_etag)
+        @etag = held_etag
+        return if @mode == "offline"
+
+        launch
+        nil
+      end
+
+      def close
+        @closed = true
+        @stop = true
+        finish_stream
+        @wake_mutex.synchronize { @wake.broadcast }
+        join_thread(@thread)
+        join_thread(@stale_thread)
+        nil
+      end
+
+      # ensure_running relaunches the threads after fork — Puma, Unicorn,
+      # Resque and Sidekiq Enterprise fork after boot, and Ruby threads do
+      # not survive fork. Called from Flags#detail on the evaluation path;
+      # in the common case it is one integer comparison, no I/O.
+      def ensure_running
+        return if @closed || @disabled || @mode == "offline"
+        return if @pid == Process.pid && alive?(@thread)
+
+        @launch_mutex.synchronize do
+          next if @closed || @disabled
+          next if @pid == Process.pid && alive?(@thread)
+
+          launch
+        end
+        nil
+      end
+
+      def ping
+        response = http_get("/ping")
+        return nil unless response.code.to_i == 200
+
+        JSON.parse(response.body.to_s)
+      rescue StandardError
+        nil
+      end
+
+      # -- state machine -----------------------------------------------------
+
+      def launch
+        @pid = Process.pid
+        @stop = false
+        @thread = Thread.new { run }
+        @thread.name = "e-volv-flags"
+        @stale_thread = Thread.new { watch_stale }
+        @stale_thread.name = "e-volv-flags-stale"
+      end
+
+      def run
+        bootstrap
+        @next_poll = monotonic + @poll_interval if @next_poll <= monotonic
+        until @stop || @disabled
+          now = monotonic
+          if @mode == "stream" || (@next_stream.positive? && now >= @next_stream)
+            @next_stream = 0.0
+            begin
+              stream_once
+            rescue StandardError
+              return if @stop || @disabled
+
+              if @mode == "poll"
+                @next_stream = monotonic + STREAM_RETRY_WHILE_POLLING_S
+              else
+                @stream_failures += 1
+                if @stream_failures >= 2
+                  fall_back_to_polling(0.0)
+                else
+                  wait(Flags.full_jitter_seconds(@stream_failures, @rng))
+                end
+              end
+            end
+            next
+          end
+          if now >= @next_poll
+            bootstrap
+            # A 429 Retry-After or 401/404 five-minute deadline the bootstrap
+            # just scheduled stays untouched.
+            @next_poll = monotonic + @poll_interval if @next_poll <= now
+          end
+          wait(0.25)
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def watch_stale
+        until @stop
+          wait(1.0)
+          break if @stop
+
+          next if @confirmed_at.nil?
+
+          age = Time.now.to_f - @confirmed_at
+          next unless age > @stale_after
+
+          @log.once("stale", "e-volv flags: ruleset is stale (no confirmation for #{age.to_i}s)")
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def bootstrap
+        return if @stop || @disabled
+
+        headers = @etag ? { "if-none-match" => %("#{@etag}") } : {}
+        response = http_get("/bootstrap?v=#{Kernel::RULESET_VERSION}", headers)
+        status = response.code.to_i
+        if status == 304
+          confirmed
+          return
+        end
+        if status == 200
+          body = parse_json(response.body)
+          return unless body.is_a?(Hash)
+
+          version = body["rulesetVersion"]
+          if !version.is_a?(Numeric) || version > Kernel::RULESET_VERSION
+            shown = version.is_a?(Numeric) ? version : "unknown"
+            @log.once("version", "e-volv flags: ignoring a ruleset newer than this SDK reads (v#{shown}); upgrade e-volv-logs")
+            return
+          end
+          @etag = body["etag"]
+          confirmed
+          @on_ruleset.call(body)
+          return
+        end
+        on_status(status, response.body.to_s, response)
+      rescue StandardError
+        @log.once("outage", "e-volv flags: control plane unreachable, serving last known values")
+        nil
+      end
+
+      # on_status handles a non-2xx bootstrap/stream-connect response per the
+      # delivery table.
+      def on_status(status, text, response)
+        if status == 403 && text.include?("lacks the scope")
+          @disabled = true
+          @log.once("scope", "e-volv flags: this key lacks flags:read — flags are off, telemetry is unaffected")
+          close
+          return
+        end
+        if [401, 403, 404].include?(status)
+          @log.once("auth", "e-volv flags: the control plane refused this key (#{status}); serving last known values and retrying every 5 minutes")
+          @next_poll = monotonic + AUTH_RETRY_S
+          return
+        end
+        if status == 429
+          retry_after = parse_retry_after(response["retry-after"]) || 30.0
+          @next_poll = monotonic + [retry_after, 1.0].max
+          return
+        end
+        @log.once("outage", "e-volv flags: control plane returned #{status}, serving last known values")
+      end
+
+      # stream_once blocks while the stream is healthy; it returns on a 429
+      # (poll fallback) and raises on any other failure — the run loop counts
+      # consecutive failures and backs off or falls back.
+      def stream_once
+        ended_cleanly = false
+        http = build_http(STREAM_IDLE_S)
+        request = Net::HTTP::Get.new(stream_path)
+        headers("accept" => "text/event-stream").each { |k, v| request[k] = v }
+        @stream_http = http
+        http.request(request) do |response|
+          status = response.code.to_i
+          if status == 429
+            fall_back_to_polling(parse_retry_after(response["retry-after"]) || 0.0)
+            ended_cleanly = true
+            next
+          end
+          unless status == 200
+            on_status(status, response.body.to_s, response) if [401, 403, 404].include?(status)
+            raise "stream #{status}"
+          end
+          @stream_failures = 0
+          @mode = "stream"
+
+          parser = SseParser.new { |event, data| on_stream_event(event, data) }
+          response.read_body do |chunk|
+            return if @stop
+
+            parser.push(chunk.to_s.force_encoding(Encoding::UTF_8))
+          end
+        end
+        raise "stream ended" unless ended_cleanly || @stop
+      ensure
+        @stream_http = nil
+      end
+
+      def on_stream_event(event, data)
+        confirmed
+        return unless event == "ruleset"
+
+        message = parse_json(data)
+        return unless message.is_a?(Hash)
+
+        bootstrap if message.key?("changedAt") || message["etag"] != @etag
+      end
+
+      def fall_back_to_polling(retry_stream_after)
+        @mode = "poll"
+        @next_poll = 0.0
+        @next_stream = monotonic + [STREAM_RETRY_WHILE_POLLING_S, retry_stream_after].max
+      end
+
+      def confirmed
+        @confirmed_at = Time.now.to_f
+        @log.reset("outage")
+        @log.reset("stale")
+        @log.reset("auth")
+      end
+
+      # -- HTTP plumbing -----------------------------------------------------
+
+      def build_http(read_timeout)
+        uri = URI.parse(@base_url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 10
+        http.read_timeout = read_timeout
+        http
+      end
+
+      def stream_path
+        uri = URI.parse(@base_url)
+        path = uri.request_uri
+        path = "/" if path.nil? || path.empty?
+        "#{path}/stream"
+      end
+
+      def http_get(path, extra = {})
+        uri = URI.parse("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 10
+        http.read_timeout = 10
+        request = Net::HTTP::Get.new(uri.request_uri.empty? ? "/" : uri.request_uri)
+        headers(extra).each { |k, v| request[k] = v }
+        http.start { |conn| conn.request(request) }
+      end
+
+      def headers(extra = {})
+        base = { "authorization" => "Bearer #{@key}", "user-agent" => @user_agent }
+        extra.each { |k, v| base[k] = v }
+        base
+      end
+
+      # -- small helpers -------------------------------------------------------
+
+      def wait(seconds)
+        @wake_mutex.synchronize do
+          @wake.wait(@wake_mutex, seconds) unless @stop
+        end
+        nil
+      end
+
+      def join_thread(thread)
+        thread&.join(1) unless thread.nil? || thread == Thread.current
+        nil
+      end
+
+      def finish_stream
+        http = @stream_http
+        http&.finish
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def alive?(thread)
+        !thread.nil? && thread.alive?
+      end
+
+      def parse_json(text)
+        JSON.parse(text.to_s)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+
+      def parse_retry_after(value)
+        return nil if value.nil?
+
+        text = value.to_s.strip
+        return nil if text.empty?
+
+        Float(text)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/evolve_logs/flags/exposures.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module EvolveLogs
+  module Flags
+    # Exposure recording: sampling first, then de-dupe by flag/variant/kind/
+    # subject inside a window — suppressed repeats ride as `count` on the
+    # first exposure after the window (docs/LAUNCH-SDK.md §7). Rows carry
+    # camelCase wire keys. Everything is best-effort: never raises.
+    class ExposureRecorder
+      BUFFER_CAP = 10_000
+      SEEN_CAP = 50_000
+      RESERVED = %w[kind key targetingKey name anonymous].freeze
+
+      def initialize(enabled: true, sample_rate: 1.0, dedupe_window_seconds: 60,
+                     send_attributes: false, private_attributes: [],
+                     now: nil, rnd: nil, uuid: nil)
+        @enabled = enabled
+        @sample_rate = sample_rate
+        @window = dedupe_window_seconds
+        @send_attributes = send_attributes
+        @private = (private_attributes || []).map(&:to_s)
+        @now = now || -> { Time.now.to_f }
+        @rnd = rnd || -> { Random.rand }
+        @uuid = uuid || -> { SecureRandom.uuid }
+        @queue = []
+        @seen = {}
+        @mutex = Mutex.new
+      end
+
+      def record(flag_key, variant, reason, context)
+        @mutex.synchronize do
+          return unless @enabled
+
+          rate = @sample_rate
+          return if rate < 1 && @rnd.call >= rate
+
+          subject = subject_of(context)
+          dedupe_key = "#{flag_key}\0#{variant || ''}\0#{subject['kind']}\0#{subject['key'] || ''}"
+          at = @now.call
+          entry = @seen[dedupe_key]
+          if entry && at - entry[:at] < @window
+            entry[:suppressed] += 1
+            return
+          end
+          count = 1 + (entry ? entry[:suppressed] : 0)
+          @seen[dedupe_key] = { at: at, suppressed: 0 }
+          prune_seen(at) if @seen.size > SEEN_CAP
+
+          row = {
+            "id" => @uuid.call.to_s,
+            "ts" => Time.at(at).utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
+            "flagKey" => flag_key.to_s[0, 64],
+            "reason" => reason.to_s[0, 40],
+            "contextKind" => subject["kind"].to_s[0, 64],
+          }
+          row["variant"] = variant.to_s[0, 60] if variant
+          row["subject"] = subject["key"] if subject["key"]
+          row["contextName"] = subject["name"] if subject["name"]
+          row["anonymous"] = true if subject["anonymous"]
+          row["count"] = [count, 1_000_000].min if count > 1
+          row["sampleRate"] = rate if rate < 1
+          if @send_attributes
+            row["attributes"] = subject["attributes"].reject { |k, _| @private.include?(k) }
+          end
+          @queue << row
+          @queue.shift(@queue.length - BUFFER_CAP) if @queue.length > BUFFER_CAP
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def pending
+        @mutex.synchronize { @queue.length }
+      end
+
+      def drain(limit = 1000)
+        @mutex.synchronize { @queue.shift([limit, @queue.length].min) }
+      end
+
+      # requeue puts a batch that could not be sent back at the front, still
+      # capped — the oldest overflow is dropped.
+      def requeue(batch)
+        @mutex.synchronize { @queue = (batch + @queue).last(BUFFER_CAP) }
+        nil
+      end
+
+      # subject_of extracts the subject fields of one evaluation context in
+      # camelCase wire shape. A multi-context contributes its first kind.
+      def subject_of(context)
+        raw = context.is_a?(Hash) ? context : {}
+        kind = raw["kind"]
+        kind = "user" unless kind.is_a?(String)
+        single = raw
+        if kind == "multi"
+          single = {}
+          raw.each do |k, v|
+            next if k == "kind" || !v.is_a?(Hash)
+
+            kind = k
+            single = v
+            break
+          end
+        end
+        key = single["key"]
+        key = single["targetingKey"] if key.nil?
+        name = single["name"]
+        attributes = {}
+        single.each { |k, v| attributes[k] = v unless RESERVED.include?(k) }
+        {
+          "kind" => kind,
+          "key" => key.nil? ? nil : key.to_s[0, 200],
+          "name" => name.is_a?(String) ? name[0, 200] : nil,
+          "anonymous" => single["anonymous"].equal?(true) ? true : nil,
+          "attributes" => attributes,
+        }
+      end
+
+      private
+
+      def prune_seen(at)
+        @seen.delete_if { |_, v| at - v[:at] >= @window && v[:suppressed].zero? }
+      end
+    end
+  end
+end