flagbearer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e2bc8382cbedca12c994ca288f3f2ba43f4a0210bfb311fe6a0382e073f8e36
+  data.tar.gz: 375896df1ebe6ba4bb33a5e991510672d01aa8bdba3915619a0d02df6376a655
+SHA512:
+  metadata.gz: d020d5f29ac73a5d37a58ed04692c2afde7b2f899626a58d8b7572f2c115de446af6466bc4722984ebdc408691f9225cf1d0917a1ba0395ca9dcfb51e00af117
+  data.tar.gz: fd7a0f62af25ba695a687d878b7fb3f3a8947f9463356aa573cce0b93b0b7143bad8859afe17b137148a3cf4131a4bebdf4081ac64f6a3d2d6cc5d3a63d420ba

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flagbearer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,45 @@
+# flagbearer for Ruby
+
+Ruby SDK for Flagbearer. Downloads an environment's ruleset and evaluates flags
+locally for each user, without making a network request for every flag check.
+Requires Ruby 3.2 or later and has no runtime dependencies.
+
+```sh
+bundle add flagbearer
+```
+
+## Docs
+
+Keys, syncing at startup, per-request checks, forking servers, shutdown and
+exposures are covered at
+[docs.flagbearer.dev/sdks/ruby](https://docs.flagbearer.dev/sdks/ruby).
+
+## Development
+
+From this directory, with Ruby 3.2 or later first on `PATH`:
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+`bun run test:sdk` does the same, and finds Homebrew's `ruby@3.4` even when the
+macOS system Ruby comes first on `PATH`; set `RUBY_BIN` to use another Ruby.
+The tests include the shared evaluation fixtures in
+[`fixtures/evaluation.json`](../fixtures/evaluation.json),
+which the other SDKs also run, and fork tests that use a real `Process.fork`.
+Flagbearer's integration tests run this SDK against the real backend through
+[`testing/servers/ruby-server.rb`](../testing/servers/ruby-server.rb).
+
+## Releasing
+
+Bump `VERSION` in `lib/flagbearer/version.rb`, merge, then build and push the
+gem from this directory with a RubyGems account that owns `flagbearer` (MFA is
+required):
+
+```sh
+gem build flagbearer.gemspec
+gem push flagbearer-0.1.0.gem
+```
+
+RubyGems versions can't be reused, so bump the version for every release.

data/lib/flagbearer/client.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Flagbearer
+  # Checks flags against the rules in memory. Create one per process with
+  # Flagbearer.init and keep it for the life of the process. Thread-safe.
+  class Client
+    def initialize(key, url: DEFAULT_URL, debug: false, app_version: nil, timings: Timings.default)
+      raise ArgumentError, "A nonempty server SDK key is required" unless
+        key.is_a?(String) && !key.empty? && !key.match?(/[[:space:]]/)
+
+      @endpoint = HTTP::Endpoint.new(url)
+      @key = key
+      @headers = { "Authorization" => "Bearer #{key}" }.freeze
+      @app_version = app_version
+      @timings = timings
+      @debug = DebugLog.new(debug)
+      @ruleset = nil
+      @active = nil
+      @closed = false
+      @lock = Mutex.new
+      start
+    end
+
+    # Waits for the latest rules. Raises Flagbearer::Error when the request fails
+    # or the timeout passes; the client keeps retrying in the background either way.
+    def sync(timeout: nil)
+      check_fork
+      @coordinator.sync(timeout: timeout)
+    end
+
+    # Checks a flag using only the rules in memory. Never raises or blocks on the
+    # network. +user+ is a Hash with :key and :email, as symbols or strings.
+    def enabled?(flag, user = {}, default: false)
+      check_fork
+      fields = user_fields(user)
+      ruleset = @ruleset
+      version = ruleset&.version
+      details = begin
+        Evaluate.evaluate(ruleset&.flags&.[](flag), fields, version, default)
+      rescue StandardError
+        Evaluate::Evaluation.new(default, "fallback", version)
+      end
+      @reporter.record(flag, fields, details)
+      details.value
+    end
+
+    # Uploads pending exposure reports. Raises Flagbearer::Error when an upload fails.
+    def flush
+      check_fork
+      @reporter.flush
+    end
+
+    # Stops streaming and background threads, then uploads pending exposures.
+    # Safe to call more than once. Rules in memory stay usable.
+    def close
+      @lock.synchronize do
+        return if @closed
+
+        @closed = true
+        if Process.pid != @pid
+          # A forked child that never restarted: its parent owns these checks.
+          @reporter.abandon
+          return
+        end
+      end
+      @coordinator.close
+      @stream.close
+      abort(@active)
+      begin
+        @reporter.close
+      rescue StandardError
+        nil # shutdown continues if the last upload fails
+      end
+      nil
+    end
+
+    # Restarts background work in a forked child. The client also does this on
+    # its own the first time it's used after a fork; call it from a hook like
+    # Puma's on_worker_boot to start streaming before the first request.
+    def postfork
+      @lock.synchronize do
+        return if @closed || Process.pid == @pid
+
+        @debug.call("Restarting after fork")
+        # The parent's threads don't exist here, and its sockets are still the
+        # parent's, so its objects are dropped rather than closed. The child
+        # keeps the rules and starts with no pending checks: the parent reports
+        # its own.
+        @active = nil
+        start
+      end
+      nil
+    end
+
+    private
+
+    def start
+      @pid = Process.pid
+      connected = false
+      @reporter = ExposureReporter.new(
+        endpoint: @endpoint, key: @key, app_version: @app_version, timings: @timings
+      )
+      stream = nil
+      coordinator = Coordinator.new(
+        fetch: -> { fetch },
+        apply: ->(ruleset) { @ruleset = ruleset },
+        on_permanent_failure: -> { stream&.close },
+        timings: @timings, debug: @debug, version: @ruleset&.version
+      )
+      stream = VersionStream.new(
+        endpoint: @endpoint, headers: @headers, timings: @timings, debug: @debug,
+        on_version: ->(version) { coordinator.on_version(version) },
+        on_open: lambda {
+          # After a reconnect, refetch in case an announcement was missed.
+          coordinator.streaming(true, refresh: connected)
+          connected = true
+        },
+        on_disconnect: -> { coordinator.streaming(false) }
+      )
+      @coordinator = coordinator
+      @stream = stream
+      coordinator.refresh_in_background
+    end
+
+    def check_fork
+      postfork if Process.pid != @pid
+    end
+
+    def user_fields(user)
+      return { key: nil, email: nil } if user.nil?
+      # Anything else gets the default, and its check is counted as lost.
+      return { key: user, email: nil } unless user.is_a?(Hash)
+
+      { key: user.fetch(:key) { user["key"] }, email: user.fetch(:email) { user["email"] } }
+    end
+
+    def abort(http)
+      http&.finish if http&.started?
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def fetch
+      current = @ruleset
+      headers = @headers.dup
+      headers["If-None-Match"] = %("#{current.version}") if current
+      request = Net::HTTP::Get.new(@endpoint.path("/v1/ruleset"), headers)
+      response = begin
+        HTTP.request(@endpoint, request, timeout: @timings.request_timeout,
+                                         on_connection: ->(http) { @active = http })
+      ensure
+        @active = nil
+      end
+      return nil if response.code.to_i == 304
+
+      HTTP.check_status(response)
+      ruleset = Evaluate.parse_ruleset(response.body.to_s)
+      raise Error.new("Invalid ruleset response") unless ruleset
+      if current && ruleset.environment_id != current.environment_id
+        raise Error.new("Ruleset environment changed unexpectedly")
+      end
+
+      ruleset
+    end
+  end
+end

data/lib/flagbearer/evaluate.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Flagbearer
+  # Pure evaluation: the same rules every Flagbearer SDK follows.
+  module Evaluate
+    MAX_SAFE_INTEGER = (2**53) - 1
+    # Like JavaScript's trim(): Unicode whitespace and the BOM.
+    TRIM = /\A[[:space:]\uFEFF]+|[[:space:]\uFEFF]+\z/
+
+    FlagRule = Struct.new(:key, :enabled, :rollout_bps, :override_emails)
+    Ruleset = Struct.new(:environment_id, :version, :flags)
+    Evaluation = Struct.new(:value, :reason, :version)
+
+    module_function
+
+    # A user's place in a flag's rollout, 0-9999. Below rollout_bps means on.
+    def bucket(flag_key, user_key)
+      Digest::SHA256.hexdigest(utf8(flag_key) + ":".b + utf8(user_key)).to_i(16) % 10_000
+    end
+
+    # The UTF-8 bytes of a string. Binary strings, like HTTP bodies, are taken
+    # to be UTF-8 already; other encodings are converted.
+    def utf8(text)
+      text.encoding == Encoding::BINARY ? text.b : text.encode(Encoding::UTF_8).b
+    end
+
+    def text(body) = utf8(body.to_s).force_encoding(Encoding::UTF_8)
+
+    def normalize_email(email)
+      text(email).scrub("\uFFFD").gsub(TRIM, "").downcase
+    end
+
+    def evaluate(flag, user, version, default)
+      return Evaluation.new(default, "fallback", version) if flag.nil?
+      return Evaluation.new(false, "off", version) unless flag.enabled
+
+      email = user[:email]
+      raise TypeError, "email must be a String" unless email.nil? || email.is_a?(String)
+
+      email = email.nil? ? "" : normalize_email(email)
+      if !email.empty? && flag.override_emails.any? { |item| normalize_email(item) == email }
+        return Evaluation.new(true, "tester", version)
+      end
+
+      key = user[:key]
+      raise TypeError, "key must be a String" unless key.nil? || key.is_a?(String)
+
+      if key.nil? || key.empty?
+        return Evaluation.new(default, "fallback", version) unless [0, 10_000].include?(flag.rollout_bps)
+
+        return Evaluation.new(flag.rollout_bps == 10_000, "rollout", version)
+      end
+
+      Evaluation.new(bucket(flag.key, key) < flag.rollout_bps, "rollout", version)
+    end
+
+    # JSON numbers are doubles, so 42.0 is the same version as 42.
+    def integer(value)
+      return value if value.is_a?(Integer)
+      return value.to_i if value.is_a?(Float) && value.finite? && value == value.floor
+
+      nil
+    end
+
+    def version(value)
+      number = integer(value)
+      number if number && number >= 0 && number <= MAX_SAFE_INTEGER
+    end
+
+    # The ruleset in a GET /v1/ruleset body, or nil if any of it is invalid.
+    def parse_ruleset(body)
+      value = JSON.parse(text(body))
+      return nil unless value.is_a?(Hash)
+
+      environment_id = value["environmentId"]
+      number = version(value["version"])
+      flags = value["flags"]
+      return nil unless environment_id.is_a?(String) && number && flags.is_a?(Array)
+
+      rules = {}
+      flags.each do |item|
+        rule = parse_rule(item)
+        return nil unless rule
+
+        rules[rule.key] = rule
+      end
+      Ruleset.new(environment_id, number, rules.freeze).freeze
+    rescue JSON::ParserError
+      nil
+    end
+
+    def parse_rule(item)
+      return nil unless item.is_a?(Hash)
+
+      key = item["key"]
+      enabled = item["enabled"]
+      rollout = integer(item["rolloutBps"])
+      emails = item["overrideEmails"]
+      return nil unless key.is_a?(String) && [true, false].include?(enabled)
+      return nil unless rollout && rollout.between?(0, 10_000)
+      return nil unless emails.is_a?(Array) && emails.all?(String)
+
+      FlagRule.new(key, enabled, rollout, emails.freeze).freeze
+    end
+  end
+end

data/lib/flagbearer/exposures.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Flagbearer
+  # Counts flag checks and uploads them in the background.
+  class ExposureReporter
+    WINDOW_MS = 30_000
+    MAX_RECORDS = 1000
+    BATCH_SIZE = 100
+    MAX_CHECK_COUNT = 1_000_000_000
+
+    # One upload, fixed when sealed, so a retry sends exactly the same body and
+    # the server can recognize it by its batch ID.
+    Batch = Struct.new(:id, :user, :events)
+
+    def initialize(endpoint:, key:, app_version:, timings:)
+      @endpoint = endpoint
+      @key = key
+      @app_version = app_version && !app_version.empty? ? app_version[0, 100] : nil
+      @timeout = timings.exposure_timeout
+      @reporter_id = SecureRandom.uuid
+      @lock = Mutex.new
+      @send_lock = Mutex.new # one upload at a time; flush waits for the one in progress
+      @wake = ConditionVariable.new
+      @active = {}
+      @sealed = []
+      @sealed_events = 0
+      @dropped = 0
+      @reported_dropped = 0
+      @retry_at = 0.0
+      @failures = 0
+      @closed = false
+      @thread = Thread.new { run(timings.exposure_flush_interval) }
+      @thread.name = "flagbearer-exposures"
+      @thread.report_on_exception = false
+    end
+
+    def record(flag, user, details)
+      @lock.synchronize do
+        return if @closed
+
+        key = user[:key]
+        if !flag.is_a?(String) || flag.empty? || HTTP.js_length(flag) > 256 ||
+           !(key.nil? || key.is_a?(String)) || (key && HTTP.js_length(key) > 256)
+          @dropped += 1
+          return
+        end
+        now = (Time.now.to_r * 1000).floor
+        bucket = iso(now / WINDOW_MS * WINDOW_MS)
+        raw_email = user[:email]
+        email = if raw_email.is_a?(String) && !raw_email.empty? && HTTP.js_length(raw_email) <= 254
+                  normalized = Evaluate.normalize_email(raw_email)
+                  normalized.empty? ? nil : normalized
+                end
+        user_key = key.nil? || key.empty? ? nil : key
+        identity = [flag, user_key, email, details.value, details.reason, details.version, bucket]
+        existing = @active[identity]
+        if existing
+          if existing[:event]["checkCount"] < MAX_CHECK_COUNT
+            existing[:event]["checkCount"] += 1
+            existing[:event]["lastCheckedAt"] = iso(now)
+          else
+            @dropped += 1
+          end
+          return
+        end
+        if @active.size + @sealed_events >= MAX_RECORDS
+          @dropped += 1
+          return
+        end
+        who = {}
+        who["key"] = user_key if user_key
+        who["email"] = email if email
+        @active[identity] = {
+          user: who,
+          event: {
+            "flagKey" => flag, "result" => details.value, "reason" => details.reason,
+            "configurationVersion" => details.version, "bucket" => bucket, "checkCount" => 1,
+            "firstCheckedAt" => iso(now), "lastCheckedAt" => iso(now)
+          }
+        }
+      end
+    rescue StandardError
+      @lock.synchronize { @dropped += 1 }
+    end
+
+    # Uploads every pending check. Raises when an upload fails.
+    def flush
+      @send_lock.synchronize do
+        send_all
+      rescue StandardError
+        @lock.synchronize do
+          @failures += 1
+          delay = [60.0, 2.0**[@failures, 6].min].min
+          @retry_at = [@retry_at, monotonic + delay].max
+        end
+        raise
+      end
+    end
+
+    def close
+      @lock.synchronize do
+        return if @closed
+
+        @closed = true
+        @wake.broadcast
+      end
+      flush
+    end
+
+    # Stops the timer without uploading: for a forked child, whose parent still
+    # owns these checks.
+    def abandon
+      @lock.synchronize do
+        @closed = true
+        @wake.broadcast
+      end
+    end
+
+    private
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def iso(milliseconds)
+      Time.at(Rational(milliseconds, 1000)).utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    def run(interval)
+      loop do
+        @lock.synchronize do
+          return if @closed
+
+          @wake.wait(@lock, HTTP.jitter(interval, 0.1))
+          return if @closed
+        end
+        due = @lock.synchronize { monotonic >= @retry_at }
+        next unless due
+
+        begin
+          flush
+        rescue StandardError
+          nil # background uploads retry later
+        end
+      end
+    end
+
+    # Expects @lock held. A batch never mixes users.
+    def seal
+      open = {}
+      @active.each_value do |item|
+        batch = open[item[:user]]
+        if batch.nil? || batch.events.size >= BATCH_SIZE
+          batch = Batch.new(SecureRandom.uuid, item[:user], [])
+          open[item[:user]] = batch
+          @sealed << batch
+        end
+        batch.events << item[:event]
+        @sealed_events += 1
+      end
+      @active = {}
+    end
+
+    def settle(batch)
+      @lock.synchronize do
+        if @sealed.first.equal?(batch)
+          @sealed.shift
+          @sealed_events -= batch.events.size
+        end
+      end
+    end
+
+    def send_all
+      @lock.synchronize { seal }
+      loop do
+        batch, dropped = @lock.synchronize do
+          next nil if @sealed.empty? && @dropped <= @reported_dropped
+
+          # Only lost checks to report: an empty batch carries the count.
+          [@sealed.first || Batch.new(SecureRandom.uuid, {}, []), @dropped]
+        end
+        break if batch.nil?
+
+        checks = batch.events.sum { |event| event["checkCount"] }
+        body = {
+          "batchId" => batch.id, "reporterId" => @reporter_id, "user" => batch.user,
+          "events" => batch.events, "droppedChecks" => dropped,
+          "sdk" => "ruby", "sdkVersion" => VERSION
+        }
+        body["appVersion"] = @app_version if @app_version
+        request = Net::HTTP::Post.new(@endpoint.path("/v1/exposures"), {
+          "Authorization" => "Bearer #{@key}", "Content-Type" => "application/json"
+        })
+        request.body = JSON.generate(body)
+        response = HTTP.request(@endpoint, request, timeout: @timeout)
+        status = response.code.to_i
+        unless status.between?(200, 299)
+          refused = status.between?(400, 499) && status != 429
+          @lock.synchronize do
+            wait = HTTP.retry_after(response["Retry-After"])
+            @retry_at = [@retry_at, monotonic + [wait, 3600].min].max if wait.positive?
+            if refused
+              # The server won't take this batch, so retrying can't help.
+              @dropped += checks
+              @retry_at = monotonic + 60
+            end
+          end
+          settle(batch) if refused
+          raise Error.new("Exposure upload failed (#{status})", retryable: !refused)
+        end
+        rejected = receipt(response.body, checks, batch.events.size)
+        @lock.synchronize do
+          @dropped += rejected
+          @reported_dropped = [@reported_dropped, dropped].max
+        end
+        settle(batch)
+      end
+      @lock.synchronize { @failures = 0 }
+    end
+
+    def receipt(body, checks, events)
+      parsed = JSON.parse(Evaluate.text(body))
+      accepted = parsed.is_a?(Hash) ? parsed["accepted"] : nil
+      rejected = parsed.is_a?(Hash) ? parsed["rejectedChecks"] : nil
+      if accepted.is_a?(Integer) && accepted.between?(0, events) &&
+         rejected.is_a?(Integer) && rejected.between?(0, checks)
+        return rejected
+      end
+
+      raise Error.new("Invalid exposure upload receipt", retryable: true)
+    rescue JSON::ParserError
+      raise Error.new("Invalid exposure upload receipt", retryable: true)
+    end
+  end
+end

data/lib/flagbearer/http.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module Flagbearer
+  # A failed request or an unusable response. Retryable failures back off and
+  # try again; permanent ones stop automatic refreshes until sync is called.
+  class Error < StandardError
+    attr_reader :retry_after
+
+    def initialize(message, retryable: false, retry_after: 0.0)
+      super(message)
+      @retryable = retryable
+      @retry_after = retry_after
+    end
+
+    def retryable? = @retryable
+    def permanent? = !@retryable
+  end
+
+  # Raised by sync after close.
+  class ClosedError < StandardError
+    def initialize(message = "Flagbearer client is closed") = super
+  end
+
+  # Network plumbing shared by the ruleset, stream and exposure requests.
+  module HTTP
+    MAX_RETRY = 30.0
+
+    module_function
+
+    # Seconds to wait from a Retry-After header, given in seconds or as an HTTP date.
+    def retry_after(header, now = Time.now)
+      return 0.0 if header.nil? || header.empty?
+
+      seconds = Float(header, exception: false)
+      return seconds.finite? && seconds.positive? ? seconds : 0.0 if seconds
+
+      [Time.httpdate(header) - now, 0.0].max
+    rescue ArgumentError
+      0.0
+    end
+
+    def check_status(response)
+      status = response.code.to_i
+      return if status.between?(200, 299)
+
+      # A 3xx lands here too: Net::HTTP never follows redirects.
+      raise Error.new(
+        "Flagbearer request failed: #{status}",
+        retryable: [408, 429].include?(status) || status >= 500,
+        retry_after: retry_after(response["Retry-After"])
+      )
+    end
+
+    def backoff(attempt, base: 1.0, cap: MAX_RETRY)
+      delay = [cap, base * (2**[attempt, 5].min)].min
+      [cap, delay * (0.8 + (rand * 0.4))].min
+    end
+
+    def jitter(interval, spread)
+      interval * (1 - spread + (rand * 2 * spread))
+    end
+
+    # UTF-16 code units, as JavaScript and the server's limits count them.
+    def js_length(text)
+      Evaluate.text(text).encode("UTF-16LE").bytesize / 2
+    end
+
+    # One SDK server address.
+    class Endpoint
+      attr_reader :uri
+
+      def initialize(url)
+        @uri = URI.parse(url.to_s)
+        raise ArgumentError, "Flagbearer url must use HTTP or HTTPS" unless
+          %w[http https].include?(@uri.scheme) && @uri.host && !@uri.host.empty?
+
+        @prefix = @uri.path.to_s.chomp("/")
+      rescue URI::InvalidURIError
+        raise ArgumentError, "Flagbearer url must use HTTP or HTTPS"
+      end
+
+      def path(route) = "#{@prefix}#{route}"
+
+      def connection(open_timeout:, read_timeout:)
+        http = Net::HTTP.new(@uri.host, @uri.port)
+        http.use_ssl = @uri.scheme == "https"
+        http.open_timeout = open_timeout
+        http.read_timeout = read_timeout
+        http.write_timeout = read_timeout
+        http.keep_alive_timeout = 0
+        http
+      end
+    end
+
+    NETWORK_ERRORS = [
+      IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse, Net::ProtocolError, EOFError
+    ].freeze
+
+    # Sends one request and reads the whole response. Network errors are retryable.
+    # on_connection receives the started connection, so close can abort it.
+    def request(endpoint, request, timeout:, on_connection: nil)
+      http = endpoint.connection(open_timeout: timeout, read_timeout: timeout)
+      http.start
+      on_connection&.call(http)
+      response = http.request(request)
+      response.body
+      response
+    rescue *NETWORK_ERRORS => e
+      raise Error.new("Flagbearer request failed: #{e.message}", retryable: true)
+    ensure
+      begin
+        http&.finish if http&.started?
+      rescue IOError
+        nil
+      end
+    end
+  end
+end

data/lib/flagbearer/log.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Flagbearer
+  # Diagnostics for debug: true. Never logs keys, user data, flag names or rules.
+  class DebugLog
+    def initialize(enabled, io: $stderr)
+      @enabled = enabled
+      @io = io
+    end
+
+    def call(message, **details)
+      return unless @enabled
+
+      if details.empty?
+        @io.puts("[Flagbearer] #{message}")
+      else
+        # Same shape as the Node SDK's console.debug output: { version: 42 }.
+        fields = details.map { |name, value| "#{name}: #{value.nil? ? 'undefined' : value}" }
+        @io.puts("[Flagbearer] #{message} { #{fields.join(', ')} }")
+      end
+    rescue StandardError
+      nil
+    end
+  end
+
+  def self.warn_log(message)
+    $stderr.puts("Flagbearer: #{message}")
+  rescue StandardError
+    nil
+  end
+end

data/lib/flagbearer/refresh.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Flagbearer
+  # Every delay the client uses, in seconds. Tests shorten them.
+  Timings = Struct.new(
+    :request_timeout, :poll_interval, :retry_base, :max_retry,
+    :max_version_refresh_delay, :stream_connect_timeout, :stream_idle_timeout,
+    :exposure_flush_interval, :exposure_timeout,
+    keyword_init: true
+  ) do
+    def self.default
+      new(
+        request_timeout: 5.0, poll_interval: 30.0, retry_base: 1.0, max_retry: 30.0,
+        max_version_refresh_delay: 2.0, stream_connect_timeout: 5.0, stream_idle_timeout: 45.0,
+        exposure_flush_interval: 30.0, exposure_timeout: 10.0
+      )
+    end
+  end
+
+  # Decides when to fetch the ruleset. One worker thread makes every fetch, so
+  # there is never more than one in flight.
+  class Coordinator
+    def initialize(fetch:, apply:, on_permanent_failure:, timings:, debug:, version: nil)
+      @fetch = fetch
+      @apply = apply
+      @on_permanent_failure = on_permanent_failure
+      @timings = timings
+      @debug = debug
+      @lock = Mutex.new
+      @wake = ConditionVariable.new
+
+      @stopped = false
+      @blocked = false
+      @streaming = false
+      @version = version
+      @wanted = nil
+      @attempt = 0
+      @not_before = 0.0 # nothing is fetched before this: backoff or a server's Retry-After
+      @retry_at = nil
+      @poll_at = nil
+      @version_at = nil
+      @requested = false
+      @in_flight = false
+      @waiters = []
+
+      @lock.synchronize { ensure_polling }
+      @thread = Thread.new { run }
+      @thread.name = "flagbearer-refresh"
+      @thread.report_on_exception = false
+    end
+
+    # Waits for a fetch. Joins one already in flight.
+    def sync(timeout: nil)
+      waiter = Thread::Queue.new
+      @lock.synchronize do
+        raise ClosedError if @stopped
+
+        @blocked = false
+        ensure_polling
+        @waiters << waiter
+        if @in_flight
+          @debug.call("Joining active refresh")
+        else
+          @retry_at = nil
+          @requested = true
+        end
+        @wake.broadcast
+      end
+      result = waiter.pop(timeout: timeout)
+      raise Error.new("Flagbearer sync timed out", retryable: true) if result.nil?
+      raise result unless result == :ok
+
+      nil
+    end
+
+    def refresh_in_background
+      @lock.synchronize { background }
+    end
+
+    def on_version(version)
+      @lock.synchronize do
+        next if @stopped
+
+        @debug.call("Stream version received", version: version, currentVersion: @version)
+        @wanted = [@wanted || 0, version].max
+        if behind? && @version_at.nil? && !@in_flight
+          @version_at = now + (rand * @timings.max_version_refresh_delay)
+          @wake.broadcast
+        end
+      end
+    end
+
+    def streaming(connected, refresh: true)
+      @lock.synchronize do
+        next if @stopped
+
+        if @streaming != connected
+          @debug.call(connected ? "Stream connected" : "Stream disconnected; using polling")
+        end
+        @streaming = connected
+        if connected
+          clear_polling
+          background if refresh
+        else
+          ensure_polling
+        end
+        @wake.broadcast
+      end
+    end
+
+    def close
+      waiters = @lock.synchronize do
+        return if @stopped
+
+        @stopped = true
+        @debug.call("Coordinator closed")
+        @wake.broadcast
+        taken = @waiters
+        @waiters = []
+        taken
+      end
+      waiters.each { |waiter| waiter << ClosedError.new }
+    end
+
+    private
+
+    # The helpers below expect @lock to be held.
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def behind? = !@wanted.nil? && (@version.nil? || @version < @wanted)
+
+    def background
+      return if @stopped || @blocked || @retry_at || @in_flight
+
+      @requested = true
+      @wake.broadcast
+    end
+
+    def ensure_polling
+      return if @stopped || @blocked || @streaming || @poll_at
+
+      interval = HTTP.jitter(@timings.poll_interval, 0.1)
+      @debug.call("Polling scheduled", intervalMs: (interval * 1000).round)
+      @poll_at = now + interval
+    end
+
+    def clear_polling
+      @debug.call("Polling disabled") if @poll_at
+      @poll_at = nil
+    end
+
+    def schedule_retry(error)
+      delay = HTTP.backoff(@attempt, base: @timings.retry_base, cap: @timings.max_retry)
+      @attempt += 1
+      delay = [delay, error.retry_after].max if error.is_a?(Error)
+      @not_before = now + delay
+      @retry_at = @not_before
+      @debug.call("Refresh retry scheduled", delayMs: (delay * 1000).round, attempt: @attempt)
+    end
+
+    # Seconds until the worker has something to do, or nil if never.
+    def next_due(at)
+      return [@not_before - at, 0].max if @requested
+
+      times = [@retry_at, @poll_at, @version_at].compact
+      times.empty? ? nil : [times.min - at, 0].max
+    end
+
+    # Turns any timer that has fired into a fetch request.
+    def take_due(at)
+      if @version_at && @version_at <= at
+        @version_at = nil
+        background if behind?
+      end
+      if @retry_at && @retry_at <= at
+        @retry_at = nil
+        background
+      end
+      if @poll_at && @poll_at <= at
+        @poll_at = nil
+        background
+        ensure_polling
+      end
+      @requested && at >= @not_before
+    end
+
+    def run
+      loop do
+        waiters = @lock.synchronize do
+          until @stopped
+            at = now
+            break if take_due(at)
+
+            @wake.wait(@lock, next_due(at))
+          end
+          return if @stopped
+
+          @requested = false
+          @in_flight = true
+          @version_at = nil
+          taken = @waiters
+          @waiters = []
+          taken
+        end
+
+        error = nil
+        begin
+          refresh
+        rescue StandardError => e
+          error = e
+        end
+
+        stopped = @lock.synchronize do
+          @in_flight = false
+          # Sync calls that arrived during this fetch join it.
+          waiters.concat(@waiters)
+          @waiters = []
+          @stopped
+        end
+        waiters.each { |waiter| waiter << (error || :ok) }
+        Flagbearer.warn_log("sync failed: #{error.message}") if error && !stopped && waiters.empty?
+      end
+    end
+
+    # One refresh, repeated while a stream announcement is still ahead of us.
+    def refresh
+      loop do
+        @debug.call("Refresh started")
+        begin
+          result = @fetch.call
+        rescue StandardError => e
+          permanent = @lock.synchronize do
+            raise if @stopped
+
+            if e.is_a?(Error) && e.permanent?
+              @debug.call("Automatic refresh stopped after permanent failure")
+              @blocked = true
+              @streaming = false
+              @retry_at = nil
+              clear_polling
+              true
+            else
+              schedule_retry(e)
+              false
+            end
+          end
+          @on_permanent_failure.call if permanent
+          raise
+        end
+
+        again = @lock.synchronize do
+          next false if @stopped
+
+          if result.nil?
+            @debug.call("Snapshot unchanged", version: @version)
+            if behind?
+              # The backend is still behind: retry later rather than spin.
+              schedule_retry(nil)
+            else
+              @attempt = 0
+              @not_before = 0.0
+            end
+            next false
+          end
+
+          previous = @version
+          if previous.nil? || result.version >= previous
+            @version = result.version
+            @apply.call(result)
+            @debug.call("Snapshot applied", version: result.version, previousVersion: previous)
+          else
+            @debug.call("Older snapshot ignored", version: result.version, currentVersion: previous)
+          end
+
+          if !behind?
+            @attempt = 0
+            @not_before = 0.0
+            false
+          elsif previous && result.version <= previous
+            schedule_retry(nil)
+            false
+          else
+            true # An announcement arrived during the request: fetch again now.
+          end
+        end
+        return unless again
+      end
+    end
+  end
+end

data/lib/flagbearer/stream.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flagbearer
+  # Server-Sent Events, fed text in arbitrary pieces. Calls on_version for each
+  # well-formed version event and ignores everything else.
+  class EventParser
+    MAX_EVENT_LENGTH = 65_536
+
+    def initialize(&on_version)
+      @on_version = on_version
+      @buffer = "".b
+      @event = "message"
+      @data = +""
+    end
+
+    # Works on bytes: CR and LF never occur inside a multi-byte UTF-8 character,
+    # so a character split across reads is whole again by the time its line ends.
+    def feed(chunk)
+      @buffer << chunk.b
+      start = 0
+      while (index = @buffer.index(/[\r\n]/n, start))
+        # A CR at the end might be the first half of a CRLF in the next piece.
+        break if @buffer.getbyte(index) == 13 && index == @buffer.bytesize - 1
+
+        line(@buffer.byteslice(start, index - start).force_encoding(Encoding::UTF_8).scrub("\uFFFD"))
+        index += 1 if @buffer.getbyte(index) == 13 && @buffer.getbyte(index + 1) == 10
+        start = index + 1
+      end
+      @buffer = @buffer.byteslice(start..)
+      raise ArgumentError, "Flagbearer stream line too large" if @buffer.bytesize > MAX_EVENT_LENGTH
+    end
+
+    private
+
+    def line(text)
+      if text.empty?
+        dispatch
+        return
+      end
+      return if text.start_with?(":")
+
+      field, separator, content = text.partition(":")
+      content = "" if separator.empty?
+      content = content[1..] if content.start_with?(" ")
+      case field
+      when "event" then @event = content
+      when "data"
+        @data << content << "\n"
+        raise ArgumentError, "Flagbearer stream event too large" if @data.length > MAX_EVENT_LENGTH
+      end
+    end
+
+    def dispatch
+      if @event == "version" && !@data.empty?
+        parsed = begin
+          JSON.parse(@data.chomp("\n"))
+        rescue JSON::ParserError
+          nil
+        end
+        version = parsed.is_a?(Hash) ? Evaluate.version(parsed["version"]) : nil
+        @on_version.call(version) if version
+      end
+      @event = "message"
+      @data = +""
+    end
+  end
+
+  # Holds GET /v1/stream open on its own thread and reconnects with backoff.
+  class VersionStream
+    def initialize(endpoint:, headers:, timings:, debug:, on_version:, on_open:, on_disconnect:)
+      @endpoint = endpoint
+      @headers = headers.merge("Accept" => "text/event-stream")
+      @timings = timings
+      @debug = debug
+      @on_version = on_version
+      @on_open = on_open
+      @on_disconnect = on_disconnect
+      @lock = Mutex.new
+      @wake = ConditionVariable.new
+      @closed = false
+      @http = nil
+      @attempts = 0
+      @thread = Thread.new { run }
+      @thread.name = "flagbearer-stream"
+      @thread.report_on_exception = false
+    end
+
+    attr_reader :thread
+
+    def close
+      http = @lock.synchronize do
+        return if @closed
+
+        @closed = true
+        @wake.broadcast
+        @http
+      end
+      @debug.call("Stream closed")
+      abort(http)
+    end
+
+    private
+
+    def closed? = @lock.synchronize { @closed }
+
+    # Closing the socket from another thread wakes a read blocked on it.
+    def abort(http)
+      http&.finish if http&.started?
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def run
+      until closed?
+        failure = connect
+        return if closed?
+
+        @on_disconnect.call
+        if failure.is_a?(Error) && failure.permanent?
+          # Polling remains available; the next ruleset request also checks the key.
+          Flagbearer.warn_log("stream stopped; using polling: #{failure.message}")
+          return
+        end
+        delay = HTTP.backoff(@attempts, base: @timings.retry_base, cap: @timings.max_retry)
+        @attempts += 1
+        delay = [delay, failure.retry_after].max if failure.is_a?(Error)
+        @debug.call("Stream reconnect scheduled", delayMs: (delay * 1000).round)
+        @lock.synchronize { @wake.wait(@lock, delay) unless @closed }
+      end
+    end
+
+    def connect
+      @debug.call("Stream connecting")
+      http = @endpoint.connection(
+        open_timeout: @timings.stream_connect_timeout,
+        read_timeout: @timings.stream_connect_timeout
+      )
+      http.start
+      @lock.synchronize do
+        return nil if @closed
+
+        @http = http
+      end
+      request = Net::HTTP::Get.new(@endpoint.path("/v1/stream"), @headers)
+      failure = nil
+      http.request(request) do |response|
+        HTTP.check_status(response)
+        type = response["Content-Type"].to_s.split(";").first.to_s.strip.downcase
+        raise Error.new("Invalid Flagbearer stream response") unless type == "text/event-stream"
+        return nil if closed?
+
+        # From here the timeout is the idle limit: heartbeats arrive every 15 seconds.
+        http.read_timeout = @timings.stream_idle_timeout
+        @on_open.call
+
+        parser = EventParser.new { |version| @on_version.call(version) }
+        response.read_body do |chunk|
+          @attempts = 0
+          parser.feed(chunk)
+        end
+      end
+      failure
+    rescue StandardError => e
+      e
+    ensure
+      @lock.synchronize { @http = nil }
+      abort(http)
+    end
+  end
+end

data/lib/flagbearer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Flagbearer
+  VERSION = "0.1.0"
+end

data/lib/flagbearer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "flagbearer/version"
+require_relative "flagbearer/log"
+require_relative "flagbearer/http"
+require_relative "flagbearer/evaluate"
+require_relative "flagbearer/refresh"
+require_relative "flagbearer/stream"
+require_relative "flagbearer/exposures"
+require_relative "flagbearer/client"
+
+# The Flagbearer server SDK: download an environment's rules once, check flags locally.
+module Flagbearer
+  DEFAULT_URL = "https://sdk.flagbearer.dev"
+
+  # Starts a client: fetches the rules and opens the stream in the background.
+  def self.init(key, url: DEFAULT_URL, debug: false, app_version: nil)
+    Client.new(key, url: url, debug: debug, app_version: app_version)
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: flagbearer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Flagbearer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Check Flagbearer feature flags locally on the server: rules stream in,
+  checks never wait on the network.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/flagbearer.rb
+- lib/flagbearer/client.rb
+- lib/flagbearer/evaluate.rb
+- lib/flagbearer/exposures.rb
+- lib/flagbearer/http.rb
+- lib/flagbearer/log.rb
+- lib/flagbearer/refresh.rb
+- lib/flagbearer/stream.rb
+- lib/flagbearer/version.rb
+homepage: https://flagbearer.dev
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://docs.flagbearer.dev/sdks/ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Flagbearer Ruby SDK
+test_files: []