trevosdk 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a962376d1586309cd51a06b89ebc86bf1fd6e150c04e74aede22a6565685ec40
-  data.tar.gz: 30d9cc18e9c4b11a77230525f6402a6152dc3c21cb063ede29c3a7cc76fa4609
+  metadata.gz: c05a483b9ac99c124d83cf4eea80cedbac818112aea0a1187850355180bb7a0b
+  data.tar.gz: 9fefd4fd2d6670e124506c03304c1045934e62859b9aacfc6f1d57c5dc93458e
 SHA512:
-  metadata.gz: 82076d6c8de3bf5f47a40be0b6a75581a7e9a24e4f04e7cf09c8814e60c6e68244078a83c059fefea83ee4770694bf28938d9d97eef67bb86814f6ba24f85c8e
-  data.tar.gz: 18f482f337bb9d52d6c0bed6e505d4879fd8aacb5ccf96fdd5c652389a5c23cf4006935568c77eeec7bbc5b8a1efc0e2a25429f97e039549a0b7870792a4f72d
+  metadata.gz: 5fbad477a55bddba3bb530d2fc59a566f5723df1f858316ead1875c611fc389e9dad4bd25558fac373e1887fca35bcc5f9e8118255940795504f724f96686b9d
+  data.tar.gz: 68e0911e14e8df2274f20cf365049823d00444221a666564eb39c08d8a8dbd99992017cd74354deb422f2398906cdbe3ef011ca56763ce906c780ea5b99b8eb0

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to the Ruby **trevosdk** gem are documented here.
+
+## [Unreleased]
+
+## [0.1.2] - 2026-09-23
+
+### Fixed
+
+- Releases use the current official RubyGems trusted-publishing action.
+
+## [0.1.1] - 2026-09-22
+
+### Added
+
+- Public error classes for configuration, delivery, serialization,
+  bounded-queue, and rejected-event failures.
+
+### Fixed
+
+- Forked Puma and job-worker processes restart background delivery instead of
+  inheriting unusable parent threads.
+- Delivery backs off during sustained outages, reapplies queue bounds after
+  retries, and keeps shutdown bounded without losing concurrently queued
+  events.
+- Rails-style integer user IDs and symbol experiment keys are normalized;
+  queued strings are copied so caller mutation cannot rewrite an event.
+- Payload byte limits, whitespace validation, self-hosted alias URLs, exposure
+  deduplication, and config ETag handling now match the cross-SDK contract.
+
+## [0.1.0] - 2026-08-16
+
+### Added
+
+- Initial release with deterministic server assignment, configuration polling,
+  event batching, identity linking, and shared conformance vectors.

data/README.md

@@ -11,6 +11,8 @@ gem install trevosdk
 # config/initializers/trevosdk.rb (Rails) or anywhere at boot
 Trevosdk.init(ENV.fetch("TREVO_SECRET_KEY"))
 
+# Bound the first config wait; later background polls keep recovering.
+Trevosdk.client.ready(2)
 variant = Trevosdk.client.get_variant("checkout-cta", user_id: current_user.id)
 if variant == "treatment"
   # alternate experience

data/lib/trevosdk/batcher.rb

@@ -3,6 +3,7 @@
 require "json"
 require "time"
 
+require_relative "errors"
 require_relative "transport"
 
 module Trevosdk
@@ -22,8 +23,30 @@ module Trevosdk
       @wake_mutex = Mutex.new
       @wake_cv = ConditionVariable.new
       @wake_flag = false
+      @stop_mutex = Mutex.new
+      @stop_cv = ConditionVariable.new
       @stopped = false
+      @draining = false
       @dropped = 0
+      @rejected_after_close = 0
+      @consecutive_failures = 0
+      @worker = nil
+    end
+
+    # Rebuilds every lock and clears the dead worker handle inherited from the
+    # parent. Threads do not survive a fork, but the started flag did.
+    def reset_after_fork
+      @mutex = Mutex.new
+      @send_mutex = Mutex.new
+      @wake_mutex = Mutex.new
+      @wake_cv = ConditionVariable.new
+      @wake_flag = false
+      @stop_mutex = Mutex.new
+      @stop_cv = ConditionVariable.new
+      @stopped = false
+      @draining = false
+      @rejected_after_close = 0
+      @consecutive_failures = 0
       @worker = nil
     end
 
@@ -36,43 +59,117 @@ module Trevosdk
     def enqueue(event)
       first_drop = false
       over_batch = false
+      rejected = false
       @mutex.synchronize do
-        return if @stopped
-        if @queue.length >= MAX_QUEUE_SIZE
+        if @stopped
+          @rejected_after_close += 1
+          rejected = @rejected_after_close == 1
+        elsif @queue.length >= MAX_QUEUE_SIZE
           # Drop oldest: an outage should cost the stalest events, not the newest.
           @queue.shift
           @dropped += 1
           first_drop = @dropped == 1
         end
-        @queue.push(event)
-        over_batch = @queue.length >= @batch_size
+        unless @stopped
+          @queue.push(event)
+          over_batch = @queue.length >= @batch_size
+        end
+      end
+      if rejected
+        @on_error.call(QueueFullError.new("Trevo client is closed; events tracked after close are dropped"))
+        return
       end
       if first_drop
-        @on_error.call(RuntimeError.new("Trevo event queue full at #{MAX_QUEUE_SIZE}; dropping oldest events"))
+        @on_error.call(QueueFullError.new("Trevo event queue full at #{MAX_QUEUE_SIZE}; dropping oldest events"))
       end
       wake! if over_batch
     end
 
     # Sends everything queued; raises on delivery failure so callers get a real guarantee.
-    def flush
-      @send_mutex.synchronize { drain }
+    def flush(deadline = nil)
+      @send_mutex.synchronize { drain(deadline) }
     end
 
     # Stops the worker and flushes once; never raises — this runs from exit hooks.
     def shutdown
-      @mutex.synchronize { @stopped = true }
+      signal_stop
       wake!
       @worker&.join(@flush_interval_s + 1)
       @worker = nil
       begin
-        flush
+        # Bounded. An abandoned worker can hold the send mutex across a whole
+        # multi-request drain, and close runs on the process-exit path, where a
+        # container's SIGTERM grace period is seconds, not minutes.
+        flush_bounded(SHUTDOWN_FLUSH_TIMEOUT_S)
       rescue => error
         @on_error.call(error)
+      ensure
+        # Set after the flush, so an event tracked while a SIGTERM handler runs
+        # is still caught by the flush it races.
+        @mutex.synchronize { @stopped = true }
       end
     end
 
     private
 
+    def flush_bounded(timeout_s)
+      deadline = monotonic + timeout_s
+      unless try_lock_until(@send_mutex, deadline)
+        @on_error.call(
+          DeliveryError.new(
+            "Trevo shutdown timed out waiting for an in-flight flush; queued events were left undelivered"
+          )
+        )
+        return
+      end
+      begin
+        drain(deadline)
+      ensure
+        @send_mutex.unlock
+      end
+    end
+
+    def try_lock_until(mutex, deadline)
+      until mutex.try_lock
+        return false if monotonic >= deadline
+        sleep(0.01)
+      end
+      true
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def backoff_delay
+      base = [@flush_interval_s * (2**@consecutive_failures), MAX_FLUSH_BACKOFF_S].min
+      # ±20% jitter stops every process in a fleet retrying in lockstep.
+      base * (0.8 + (rand * 0.4))
+    end
+
+    def signal_stop
+      @stop_mutex.synchronize do
+        @draining = true
+        @stop_cv.broadcast
+      end
+    end
+
+    def draining?
+      @stop_mutex.synchronize { @draining }
+    end
+
+    # Sleeps up to timeout_s, returning early only when shutdown signals.
+    def wait_for_stop(timeout_s)
+      deadline = monotonic + timeout_s
+      @stop_mutex.synchronize do
+        until @draining
+          remaining = deadline - monotonic
+          break if remaining <= 0
+          @stop_cv.wait(@stop_mutex, remaining)
+        end
+      end
+    end
+
     def wake!
       @wake_mutex.synchronize do
         @wake_flag = true
@@ -82,61 +179,102 @@ module Trevosdk
 
     def run
       loop do
-        @wake_mutex.synchronize do
-          @wake_cv.wait(@wake_mutex, @flush_interval_s) unless @wake_flag
-          @wake_flag = false
+        if @consecutive_failures.positive?
+          # Backs off on a timer the enqueue signal cannot short-circuit, or a
+          # partial ingestion outage becomes a fleet-wide retry storm. Only
+          # shutdown breaks it, so close does not block for the whole delay.
+          wait_for_stop(backoff_delay)
+          @wake_mutex.synchronize { @wake_flag = false }
+        else
+          @wake_mutex.synchronize do
+            @wake_cv.wait(@wake_mutex, @flush_interval_s) unless @wake_flag
+            @wake_flag = false
+          end
         end
-        return if @mutex.synchronize { @stopped }
+        return if draining?
         begin
           flush
+          @consecutive_failures = 0
         rescue => error
+          @consecutive_failures += 1
           @on_error.call(error)
         end
       end
     end
 
-    def drain
-      pending = @mutex.synchronize do
-        drained = @queue
-        @queue = []
-        drained
-      end
+    def drain(deadline = nil)
+      loop do
+        return if !deadline.nil? && monotonic >= deadline
+
+        # One batch at a time: snapshotting the whole queue meant any exception
+        # outside the per-batch guard destroyed all of it.
+        batch = @mutex.synchronize { @queue.shift(@batch_size) }
+        return if batch.empty?
+
+        begin
+          body = serialize(batch)
+        rescue => error
+          # Deterministic: requeuing would block the queue forever.
+          @on_error.call(
+            SerializationError.new(
+              "Trevo dropped #{batch.length} event(s): could not serialize them (#{error.message})"
+            )
+          )
+          next
+        end
 
-      pending.each_slice(@batch_size).with_index do |batch, index|
         status = begin
-          send_batch(batch)
+          post(body)
         rescue
           nil
         end
         next if !status.nil? && (200..299).cover?(status)
 
-        start = index * @batch_size
-        requeued =
-          if retryable?(status)
-            pending[start..]
-          else
-            # A rejected batch will be rejected identically forever; drop it, keep the rest.
-            @on_error.call(
-              RuntimeError.new(
-                "Trevo dropped #{batch.length} event(s): ingestion rejected them with status #{status.inspect}"
-              )
+        if retryable?(status)
+          requeue(batch)
+        else
+          # A rejected batch will be rejected identically forever; drop it, keep the rest.
+          @on_error.call(
+            DeliveryError.new(
+              "Trevo dropped #{batch.length} event(s): ingestion rejected them with status #{status.inspect}",
+              status
             )
-            pending[(start + batch.length)..]
-          end
-        @mutex.synchronize { @queue.unshift(*requeued) }
-        raise "Trevo event delivery failed with status #{status.inspect}"
+          )
+        end
+        raise DeliveryError.new("Trevo event delivery failed with status #{status.inspect}", status)
       end
     end
 
+    def requeue(batch)
+      dropped = 0
+      @mutex.synchronize do
+        @queue.unshift(*batch)
+        if @queue.length > MAX_QUEUE_SIZE
+          # Re-apply the bound: enqueue admits another full MAX_QUEUE_SIZE
+          # while a flush is in flight.
+          dropped = @queue.length - MAX_QUEUE_SIZE
+          @queue = @queue[0, MAX_QUEUE_SIZE]
+          @dropped += dropped
+        end
+      end
+      return if dropped.zero?
+      @on_error.call(
+        QueueFullError.new("Trevo event queue full at #{MAX_QUEUE_SIZE}; dropped #{dropped} event(s)")
+      )
+    end
+
     def retryable?(status)
       return true if status.nil?
       return true if [408, 429].include?(status)
       status >= 500
     end
 
-    def send_batch(events)
-      # sentAt is stamped at send, so a batch re-queued through an outage stays correctable.
-      body = JSON.generate({events: events, sentAt: Time.now.utc.iso8601(3)})
+    # sentAt is stamped at send, so a batch re-queued through an outage stays correctable.
+    def serialize(events)
+      JSON.generate({events: events, sentAt: Time.now.utc.iso8601(3)})
+    end
+
+    def post(body)
       response = @transport.call(
         TransportRequest.new(
           method: "POST",

data/lib/trevosdk/client.rb

@@ -5,6 +5,7 @@ require "time"
 
 require_relative "batcher"
 require_relative "core"
+require_relative "errors"
 require_relative "poller"
 require_relative "transport"
 require_relative "version"
@@ -34,7 +35,7 @@ module Trevosdk
       @on_error = on_error || ->(error) { warn("[Trevo] #{error.message}") }
       @alias_url = alias_url || self.class.derive_alias_url(ingestion_url)
 
-      @experiments = (bootstrap_config || []).to_h { |config| [config["experimentKey"], config] }
+      @experiments = (bootstrap_config || []).to_h { |config| [config["experimentKey"].to_s, config] }
       @exposures = ExposureDeduper.new(SERVER_EXPOSURE_DEDUP_MAX_KEYS)
       @exposures_mutex = Mutex.new
       @forced = self.class.parse_force_variants(ENV[FORCE_VARIANTS_ENV])
@@ -60,14 +61,17 @@ module Trevosdk
       @start_mutex = Mutex.new
       @started = false
       @closed = false
+      @forked_pid = Process.pid
     end
 
     # Alias lives on the same service as events, so an ingestion override must move alias too.
+    #
+    # A substitution, never a fallback to the public endpoint: sending a
+    # self-hosted deployment's alias traffic to trevosdk.com would ship the
+    # customer's secret key and identity graph off their own host.
     def self.derive_alias_url(ingestion_url)
       return ALIAS_URL if ingestion_url == INGESTION_URL
-      trimmed = ingestion_url.sub(%r{/+\z}, "")
-      return "#{trimmed.delete_suffix("/events")}/alias" if trimmed.end_with?("/events")
-      ALIAS_URL
+      ingestion_url.sub(%r{/events/?\z}, "/alias")
     end
 
     def self.parse_force_variants(raw)
@@ -82,7 +86,10 @@ module Trevosdk
     end
 
     def get_variant(experiment_key, user_id: nil, anonymous_id: nil, track_exposure: true)
-      return Core::CONTROL_VARIANT if experiment_key.to_s.empty?
+      # Normalised once, then used for every lookup: guarding with .to_s while
+      # looking the key up raw put a Symbol key in control, silently.
+      experiment_key = experiment_key.to_s
+      return Core::CONTROL_VARIANT if experiment_key.empty?
       ensure_started
 
       config = @experiments[experiment_key]
@@ -136,9 +143,14 @@ module Trevosdk
         )
       )
       if response.status == 409
-        raise "Trevo alias rejected: anonymousId \"#{anonymous_id}\" is already linked to a different user"
+        raise DeliveryError.new(
+          "Trevo alias rejected: anonymousId \"#{anonymous_id}\" is already linked to a different user",
+          409
+        )
+      end
+      unless (200..299).cover?(response.status)
+        raise DeliveryError.new("Trevo alias failed with status #{response.status}", response.status)
       end
-      raise "Trevo alias failed with status #{response.status}" unless (200..299).cover?(response.status)
       nil
     end
 
@@ -161,10 +173,11 @@ module Trevosdk
     private
 
     def swap_config(configs)
-      @experiments = configs.to_h { |config| [config["experimentKey"], config] }
+      @experiments = configs.to_h { |config| [config["experimentKey"].to_s, config] }
     end
 
     def ensure_started
+      restart_after_fork if @forked_pid != Process.pid
       return if @started
       @start_mutex.synchronize do
         return if @started || @closed
@@ -175,6 +188,18 @@ module Trevosdk
       end
     end
 
+    # Puma clustered, Unicorn and Sidekiq fork after a Rails initializer builds
+    # the client. Threads do not survive a fork but @started did, so the child
+    # delivered nothing at all.
+    def restart_after_fork
+      @forked_pid = Process.pid
+      @start_mutex = Mutex.new
+      @exposures_mutex = Mutex.new
+      @batcher.reset_after_fork
+      @poller.reset_after_fork
+      @started = false
+    end
+
     def enqueue_event(event_name, user_id, anonymous_id, properties, insert_id)
       built = Core.build_event(
         event_name,
@@ -187,7 +212,7 @@ module Trevosdk
         insert_id: insert_id || SecureRandom.uuid
       )
       unless built.ok
-        @on_error.call(RuntimeError.new("Trevo track(\"#{event_name}\") ignored: #{built.reason}"))
+        @on_error.call(EventRejectedError.new("Trevo track(\"#{event_name}\") ignored: #{built.reason}"))
         return
       end
 

data/lib/trevosdk/core.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "errors"
+
 module Trevosdk
   # Pure evaluation core — no I/O, no clock reads; time is a parameter.
   # Frozen contract: must match packages/contracts/src/corpus/vectors.json exactly.
@@ -17,6 +19,14 @@ module Trevosdk
     EXPOSURE_DEDUP_WINDOW_MS = 600_000
     EXPOSURE_DEDUP_MAX_KEYS = 1_000
 
+    # The exact set JS String.prototype.trim() strips (ECMA-262 WhiteSpace +
+    # LineTerminator). Ruby's String#strip and Python's str.strip() each cover a
+    # different set, so the frozen contract returned a different rejection
+    # reason per language for the same input.
+    JS_WHITESPACE = "\u0009\u000A\u000B\u000C\u000D\u0020\u00A0\u1680" \
+      "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A" \
+      "\u2028\u2029\u202F\u205F\u3000\uFEFF"
+
     FNV_OFFSET_BASIS_32 = 0x811c9dc5
     FNV_PRIME_32 = 0x01000193
     MASK_32 = 0xffffffff
@@ -26,6 +36,11 @@ module Trevosdk
 
     module_function
 
+    # True when the string is empty after stripping exactly what JS trims.
+    def js_blank?(value)
+      value.delete(JS_WHITESPACE).empty?
+    end
+
     # FNV-1a over UTF-16 code units (not bytes) — matches the reference JS SDK.
     # Invalid bytes hash as U+FFFD instead of raising: such strings have no JS
     # equivalent, so deterministic assignment beats crashing the request.
@@ -61,8 +76,11 @@ module Trevosdk
       last_variant_name = nil
       variants.each do |variant|
         cumulative += variant["trafficSplit"] * 100
-        return variant["name"].to_s if bucket < cumulative
-        last_variant_name = variant["name"].to_s
+        # A copy: returning the config's own String let a caller who mutates the
+        # result rewrite the shared experiment snapshot for every later request
+        # on the process.
+        return variant["name"].to_s.dup if bucket < cumulative
+        last_variant_name = variant["name"].to_s.dup
       end
 
       last_variant_name || CONTROL_VARIANT
@@ -96,9 +114,21 @@ module Trevosdk
       ParseResult.new(true, experiments, nil)
     end
 
+    # Frozen copy of a caller-owned String, so later mutation cannot reach a
+    # queued event. Non-strings (an Integer user id) pass through untouched.
+    #
+    # Invalid bytes are folded to U+FFFD exactly as fnv1a32 does. Rack and
+    # ActiveRecord hand you such strings routinely, and tolerating them at the
+    # hashing layer only to choke on them at JSON serialization is what let one
+    # event wedge the whole delivery queue.
+    def snapshot_string(value)
+      return value unless value.is_a?(String)
+      value.valid_encoding? ? value.dup : value.scrub
+    end
+
     def build_event(event_name, timestamp:, user_id: nil, anonymous_id: nil,
       properties: nil, sdk_version: nil, insert_id: nil)
-      unless event_name.is_a?(String) && !event_name.strip.empty?
+      unless event_name.is_a?(String) && !js_blank?(event_name)
         return BuildEventResult.new(false, nil, "empty-name")
       end
       return BuildEventResult.new(false, nil, "name-too-long") if event_name.length > MAX_EVENT_NAME_LENGTH
@@ -111,22 +141,35 @@ module Trevosdk
         rescue JSON::NestingError, JSON::GeneratorError, SystemStackError
           return BuildEventResult.new(false, nil, "properties-unserializable")
         end
-        return BuildEventResult.new(false, nil, "properties-too-large") if serialized.length > MAX_PROPERTIES_BYTES
+        # Measured in UTF-8 BYTES, as the server does. #length counts
+        # characters, so an emoji or CJK payload was accepted at up to 4x the
+        # intended budget and ingestion then 400'd — dropping the whole batch.
+        if serialized.bytesize > MAX_PROPERTIES_BYTES
+          return BuildEventResult.new(false, nil, "properties-too-large")
+        end
         # Round trip both validates and deep-copies, isolating the caller from later mutation.
         snapshot = JSON.parse(serialized)
       end
 
-      if (user_id.nil? || user_id.empty?) && (anonymous_id.nil? || anonymous_id.empty?)
+      # `.to_s.empty?`, matching Client#get_variant and the JS reference's
+      # truthiness check: `current_user.id` is an Integer in every Rails app,
+      # and it is the idiom the README recommends.
+      if user_id.to_s.empty? && anonymous_id.to_s.empty?
         return BuildEventResult.new(false, nil, "no-identity")
       end
 
-      event = {"event" => event_name}
-      event["userId"] = user_id unless user_id.nil?
-      event["anonymousId"] = anonymous_id unless anonymous_id.nil?
+      # Every caller-supplied String is snapshotted, not just properties. A
+      # reused buffer (`buf.replace(id)`, the standard allocation-avoidance
+      # idiom) otherwise rewrote events already queued, putting one user's id on
+      # rows belonging to another — undetectable server-side, because the
+      # payload is internally inconsistent rather than malformed.
+      event = {"event" => snapshot_string(event_name)}
+      event["userId"] = snapshot_string(user_id) unless user_id.nil?
+      event["anonymousId"] = snapshot_string(anonymous_id) unless anonymous_id.nil?
       event["properties"] = snapshot unless snapshot.nil?
-      event["timestamp"] = timestamp
-      event["sdkVersion"] = sdk_version unless sdk_version.nil?
-      event["insertId"] = insert_id unless insert_id.nil?
+      event["timestamp"] = snapshot_string(timestamp)
+      event["sdkVersion"] = snapshot_string(sdk_version) unless sdk_version.nil?
+      event["insertId"] = snapshot_string(insert_id) unless insert_id.nil?
       BuildEventResult.new(true, event, nil)
     end
   end
@@ -139,16 +182,17 @@ module Trevosdk
     end
 
     def should_log?(identity, experiment_key, variant_name, now_ms)
-      if @seen.length >= @max_keys
-        @seen.delete_if { |_, ts| now_ms - ts >= Core::EXPOSURE_DEDUP_WINDOW_MS }
-        @seen.clear if @seen.length >= @max_keys
-      end
-
       key = "#{identity}:#{experiment_key}:#{variant_name}"
       last = @seen[key]
       return false if !last.nil? && now_ms - last < Core::EXPOSURE_DEDUP_WINDOW_MS
 
+      # Ruby hashes are insertion-ordered, so eviction is shifting the oldest
+      # entry rather than scanning every key. The previous delete_if ran on
+      # EVERY call once the map reached its cap, in a Ruby block that never
+      # releases the GVL — freezing every thread in the worker for ~4ms.
+      @seen.delete(key)
       @seen[key] = now_ms
+      @seen.shift while @seen.length > @max_keys
       true
     end
 

data/lib/trevosdk/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Trevosdk
+  # Every failure this SDK raises or reports through +on_error+ is one of these.
+  # A bare RuntimeError forces callers to string-match the message to tell
+  # "queue full" from "delivery failed" from "event rejected", so a caller who
+  # wires up +on_error+ correctly still cannot branch on what happened.
+  #
+  # Descends from RuntimeError so callers of already published versions, who can
+  # only rescue RuntimeError today, keep working.
+  class Error < RuntimeError; end
+
+  # Config could not be fetched, or did not match the contract.
+  class ConfigError < Error; end
+
+  # Ingestion rejected a batch or could not be reached.
+  class DeliveryError < Error
+    attr_reader :status
+
+    def initialize(message, status = nil)
+      super(message)
+      @status = status
+    end
+  end
+
+  # A batch could not be serialized. Deterministic — retrying cannot help.
+  class SerializationError < Error; end
+
+  # The bounded queue dropped events.
+  class QueueFullError < Error; end
+
+  # A single event failed validation and was not queued.
+  class EventRejectedError < Error; end
+end

data/lib/trevosdk/poller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "core"
+require_relative "errors"
 require_relative "transport"
 
 module Trevosdk
@@ -31,8 +32,20 @@ module Trevosdk
     end
 
     def wait_ready(timeout_s = nil)
+      deadline = timeout_s.nil? ? nil : Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_s
       @ready_mutex.synchronize do
-        @ready_cv.wait(@ready_mutex, timeout_s) unless @ready
+        # Loop, not a single wait: a spurious wakeup would otherwise return
+        # false while the first poll was still in flight.
+        until @ready
+          remaining =
+            if deadline.nil?
+              nil
+            else
+              deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            end
+          break if !remaining.nil? && remaining <= 0
+          @ready_cv.wait(@ready_mutex, remaining)
+        end
         @ready
       end
     end
@@ -42,7 +55,22 @@ module Trevosdk
         @stopped = true
         @stop_cv.signal
       end
-      @worker&.join(1)
+      worker = @worker
+      return if worker.nil?
+      # The request timeout plus a margin, matching the batcher's convention. A
+      # 1s join against a 10s request left the thread running: it then rewrote
+      # the config of a client the application considers dead.
+      @worker = nil if worker.join(REQUEST_TIMEOUT_S + 1)
+    end
+
+    # Clears the dead worker handle and sync primitives inherited from a fork.
+    def reset_after_fork
+      @stop_mutex = Mutex.new
+      @stop_cv = ConditionVariable.new
+      @stopped = false
+      @ready_mutex = Mutex.new
+      @ready_cv = ConditionVariable.new
+      @ready = false
       @worker = nil
     end
 
@@ -78,14 +106,18 @@ module Trevosdk
       )
       return if response.status == 304
       unless (200..299).cover?(response.status)
-        raise "Trevo config fetch failed with status #{response.status}"
+        raise ConfigError, "Trevo config fetch failed with status #{response.status}"
       end
 
       parsed = Core.parse_config_response(response.json)
-      raise "Trevo config response invalid: #{parsed.error}" unless parsed.success
+      raise ConfigError, "Trevo config response invalid: #{parsed.error}" unless parsed.success
 
+      # Assigned unconditionally, and only once the payload has validated: a
+      # server or CDN that stops sending ETags must clear the stored one, or the
+      # client keeps revalidating against a token it will never refresh past —
+      # so an experiment change silently never takes effect.
       etag = (response.headers || {}).transform_keys(&:downcase)["etag"]
-      @etag = etag unless etag.nil? || etag.empty?
+      @etag = (etag.nil? || etag.empty?) ? nil : etag
       @on_config.call(parsed.experiments)
     end
   end

data/lib/trevosdk/transport.rb

@@ -17,6 +17,11 @@ module Trevosdk
   SERVER_MAX_BATCH_SIZE = 500
   MAX_QUEUE_SIZE = 10_000
   REQUEST_TIMEOUT_S = 10.0
+  # Ceiling on retry backoff, matching the browser SDK's MAX_FLUSH_BACKOFF_MS.
+  MAX_FLUSH_BACKOFF_S = 30.0
+  # close runs on the process-exit path, where a container's SIGTERM grace
+  # period is measured in seconds — an unbounded final flush gets SIGKILLed.
+  SHUTDOWN_FLUSH_TIMEOUT_S = 5.0
   SERVER_EXPOSURE_DEDUP_MAX_KEYS = 100_000
   FORCE_VARIANTS_ENV = "TREVO_FORCE_VARIANTS"
 

data/lib/trevosdk/version.rb

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

data/lib/trevosdk.rb

@@ -2,6 +2,7 @@
 
 require_relative "trevosdk/client"
 require_relative "trevosdk/core"
+require_relative "trevosdk/errors"
 require_relative "trevosdk/version"
 
 module Trevosdk
@@ -9,8 +10,15 @@ module Trevosdk
     # Process-wide singleton for the common one-client-per-app setup
     # (e.g. a Rails config/initializers/trevosdk.rb).
     def init(secret_key, **options)
-      @client&.close
-      @client = Client.new(secret_key, **options)
+      # Build first, swap second, close last. Closing first meant a raising
+      # constructor — an unset TREVO_SECRET_KEY is one line of ENV away — left
+      # the singleton pointing at an already-closed client that `client` still
+      # returns, so every later call silently no-opped.
+      replacement = Client.new(secret_key, **options)
+      previous = @client
+      @client = replacement
+      previous&.close
+      replacement
     end
 
     def client

metadata

@@ -1,26 +1,25 @@
 --- !ruby/object:Gem::Specification
 name: trevosdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Trevo
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 
-email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - lib/trevosdk.rb
 - lib/trevosdk/batcher.rb
 - lib/trevosdk/client.rb
 - lib/trevosdk/core.rb
+- lib/trevosdk/errors.rb
 - lib/trevosdk/poller.rb
 - lib/trevosdk/transport.rb
 - lib/trevosdk/version.rb
@@ -31,7 +30,6 @@ metadata:
   homepage_uri: https://trevosdk.com
   documentation_uri: https://docs.trevosdk.com
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -46,8 +44,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Trevo server SDK for Ruby — deterministic variant assignment and event tracking
 test_files: []