togglefleet 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 608c0c99556263faeb1c847374977afa7173f249b83062523d80078891b187ca
-  data.tar.gz: 5a498caa5253020f3b096d495801701fba336126cc8e66f5c10e60f7628c5dd1
+  metadata.gz: 0f09f92537778aa772a14ed6250748d881500c9e84d35154f776fffecdecedc1
+  data.tar.gz: deb6b017894d8fb1373c23fae52acda0a0b602a6c066c5ebde5e31b97fca6682
 SHA512:
-  metadata.gz: 7fc721286453dbda46fae8f0bcebb8a4a8adf22a8aaefd1beefeeddffda82b350ecad4ae39fdc1a26abced744116778a2ff31f8b3deae93b1c18a7a1c3b52bdf
-  data.tar.gz: 28d5b041acb5538a9681bada4c0f1c7b636784bc5b875b7415a64aa2bfebedd4bad876d6eab447760615780b6cc4657ed6e948a0f763a52be3d03f3edc9c90e3
+  metadata.gz: 8e92f5e26d72e1b324fe2ce6d9f60144c46fa8a50f10fa7b124cdda3c2bf160ca07b7b94a82df0f29822eccc7b0d6e1251b5565f81e239128bce90529e47b6ec
+  data.tar.gz: f526fe055723c08c9f9dcc26e749d10e7a434ddecc59870372e4660aeb452fcd6fdfd1804943927c33d09f006753414455717b133bf04e216833e6cfa097bebd

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to the ToggleFleet Ruby SDK are documented here.
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-07-26
+
+Reliability release. Every change here is about the SDK staying out of your
+request path when something goes wrong.
+
+### Fixed
+
+- **A failed config fetch no longer blocks every flag check.** Previously, if the
+  first fetch failed, `enabled?` retried the HTTP request on *every* call — so an
+  unreachable config endpoint added up to `open_timeout + read_timeout` (8s by
+  default) to each flag check, turning a background problem into a foreground
+  outage. A failed attempt is now not retried until `refresh_interval` has
+  elapsed; in between, evaluation returns `config.default` immediately with no
+  network access at all.
+
+- **Forked web servers now refresh their config.** Threads do not survive `fork`,
+  so under Puma, Unicorn or Passenger in clustered mode every worker inherited a
+  dead poller and served the boot-time configuration forever. The client now
+  detects that it is running in a forked child and restarts the poller
+  automatically — no `on_worker_boot` wiring required.
+
+- **`ToggleFleet.configure` no longer leaks a thread.** Reconfiguring abandoned
+  the previous client's poller, which kept running against the old config. The
+  previous client is now stopped first. This mostly bit test suites, which
+  reconfigure repeatedly.
+
+### Added
+
+- `ToggleFleet.stop` / `Client#stop` — cleanly terminate the background refresh
+  thread. Safe to call more than once.
+- Refresh interval is now jittered by ±15% so a fleet of processes that booted
+  together does not poll the config endpoint in lockstep.
+
+### Notes
+
+- No API changes. Upgrading from 0.1.0 requires no code changes.
+- Flag evaluation semantics are unchanged and remain byte-identical to
+  server-side evaluation, including MD5 bucketing for sticky percentage rollouts.
+
+## [0.1.0] — 2026-06-27
+
+Initial release: local evaluation of all five gates (boolean, actor, group,
+percentage of actors, percentage of time), background refresh with conditional
+ETag requests, and fail-safe defaults.

data/README.md

@@ -81,7 +81,8 @@ ToggleFleet.all(actor: current_user)
 - **Background refresh** — a single daemon thread polls every `refresh_interval` seconds with an
   `If-None-Match` ETag, so unchanged configs cost one `304` and zero parsing.
 - **Fail-safe** — if the service is unreachable, the gem serves the last good config; if it never
-  loaded, every flag returns `config.default` (defaults to `false`).
+  loaded, `start` continues with the background poller and every flag returns `config.default`
+  (defaults to `false`). An instrumentation callback failure is logged without changing a flag result.
 - **Instrumentation** — hook every evaluation for metrics or logging:
 
 ```ruby

data/lib/togglefleet/version.rb

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

data/lib/togglefleet.rb

@@ -46,13 +46,15 @@ module ToggleFleet
     attr_reader :config
 
     def initialize(config)
-      @config  = config
-      @groups  = {}            # name => predicate proc
-      @flags   = {}            # flag key => state hash
-      @etag    = nil
-      @loaded  = false
-      @mutex   = Mutex.new
-      @poller  = nil
+      @config      = config
+      @groups      = {}        # name => predicate proc
+      @flags       = {}        # flag key => state hash
+      @etag        = nil
+      @loaded      = false
+      @mutex       = Mutex.new
+      @poller      = nil
+      @poller_pid  = nil       # pid that owns @poller; threads do not survive fork
+      @last_attempt = nil      # monotonic time of the last fetch attempt (success or failure)
     end
 
     # Register a group predicate. Group membership is decided in YOUR code, so a flag enabled
@@ -65,25 +67,58 @@ module ToggleFleet
 
     # Pull the config once and start the background refresh thread. Idempotent.
     def start
-      sync
+      attempt_sync
+      start_poller
+      self
+    end
+
+    # Stop the background refresh thread. Safe to call more than once.
+    def stop
+      thread = @mutex.synchronize do
+        current = @poller
+        @poller = nil
+        @poller_pid = nil
+        current
+      end
+      thread&.kill
+      self
+    end
+
+    private def start_poller
       @mutex.synchronize do
-        @poller ||= Thread.new do
+        return if @poller && @poller_pid == Process.pid
+        @poller = Thread.new do
           loop do
-            sleep(@config.refresh_interval)
+            # Jitter the interval so a fleet of processes that booted together
+            # does not stampede the config endpoint in lockstep.
+            sleep(@config.refresh_interval * (0.85 + Kernel.rand * 0.3))
             begin; sync; rescue StandardError => e; log("refresh failed: #{e.class}: #{e.message}"); end
           end
         end
         @poller.name = "togglefleet-refresh" if @poller.respond_to?(:name=)
+        @poller_pid = Process.pid
       end
-      self
+    end
+
+    # Threads do not survive fork. Under Puma/Unicorn/Passenger in clustered
+    # mode the workers inherit @loaded=true and a dead poller, so without this
+    # they would serve the boot-time config forever and never refresh again.
+    private def restart_poller_if_forked
+      return if @poller_pid.nil? || @poller_pid == Process.pid
+      @mutex.synchronize do
+        @poller = nil
+        @poller_pid = nil
+      end
+      start_poller
     end
 
     # The whole point: evaluate locally, no network call here.
     def enabled?(flag, actor: nil, groups: nil)
+      restart_poller_if_forked
       ensure_loaded
       state  = @mutex.synchronize { @flags[flag.to_s] }
       result = state ? evaluate(state, actor, groups) : @config.default
-      @config.on_evaluation&.call(flag.to_s, actor, result)
+      notify_evaluation(flag.to_s, actor, result)
       result
     rescue StandardError => e
       log("enabled?(#{flag}) error: #{e.class}: #{e.message}")
@@ -126,11 +161,38 @@ module ToggleFleet
 
     private
 
+    # Lazy first load, rate-limited.
+    #
+    # Previously this retried on EVERY enabled? call while unloaded, so if the
+    # config endpoint was unreachable each flag check blocked for open_timeout +
+    # read_timeout (up to 8s) — turning a background outage into a foreground
+    # one, which is the exact opposite of the gem's promise. Now a failed attempt
+    # is not repeated until refresh_interval has elapsed; until then evaluation
+    # returns config.default immediately with no network at all.
     def ensure_loaded
       return if @loaded
+      return unless claim_attempt
       begin; sync; rescue StandardError => e; log("initial load failed, using defaults: #{e.message}"); end
     end
 
+    # True at most once per refresh_interval. Deliberately records the attempt
+    # before it happens, so a hung request cannot let a second caller through.
+    def claim_attempt
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @mutex.synchronize do
+        return false if @last_attempt && (now - @last_attempt) < @config.refresh_interval
+        @last_attempt = now
+        true
+      end
+    end
+
+    def attempt_sync
+      return unless claim_attempt
+      sync
+    rescue StandardError => e
+      log("initial load failed, using defaults: #{e.class}: #{e.message}")
+    end
+
     # Mirrors the server's evaluation byte-for-byte (same MD5 bucketing) so a sticky rollout
     # is identical whether you evaluate here or call /v1/evaluate.
     def evaluate(state, actor, explicit_groups)
@@ -177,13 +239,25 @@ module ToggleFleet
       names.uniq
     end
 
+    def notify_evaluation(flag, actor, result)
+      @config.on_evaluation&.call(flag, actor, result)
+    rescue StandardError => e
+      log("on_evaluation callback raised: #{e.class}: #{e.message}")
+    end
+
     def log(msg)
       @config.logger&.warn("[togglefleet] #{msg}")
+    rescue StandardError
+      nil
     end
   end
 
   class << self
     def configure
+      # Stop the previous client first: reconfiguring used to abandon its poller
+      # thread, which kept running forever against the old config — a thread and
+      # socket leak every time configure was called (common in test suites).
+      @client&.stop
       @config = Configuration.new
       yield @config if block_given?
       @client = Client.new(@config)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: togglefleet
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - ToggleFleet
@@ -19,6 +19,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/togglefleet.rb
@@ -30,6 +31,8 @@ metadata:
   homepage_uri: https://togglefleet.com
   source_code_uri: https://github.com/takeaseatventure/togglefleet-ruby
   documentation_uri: https://togglefleet.com/docs
+  changelog_uri: https://github.com/takeaseatventure/togglefleet-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/takeaseatventure/togglefleet-ruby/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: