togglefleet 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 608c0c99556263faeb1c847374977afa7173f249b83062523d80078891b187ca
-  data.tar.gz: 5a498caa5253020f3b096d495801701fba336126cc8e66f5c10e60f7628c5dd1
+  metadata.gz: add053306fe4d2d5cabba8a3777222eb7434804f2d248d6c2570de4904b63b55
+  data.tar.gz: e6e7c6a0dd21a431998a47b121dd8eada0c5fae401cb910af6f6874f50b74e14
 SHA512:
-  metadata.gz: 7fc721286453dbda46fae8f0bcebb8a4a8adf22a8aaefd1beefeeddffda82b350ecad4ae39fdc1a26abced744116778a2ff31f8b3deae93b1c18a7a1c3b52bdf
-  data.tar.gz: 28d5b041acb5538a9681bada4c0f1c7b636784bc5b875b7415a64aa2bfebedd4bad876d6eab447760615780b6cc4657ed6e948a0f763a52be3d03f3edc9c90e3
+  metadata.gz: a14afc7241970e98e1f4faa754045bd9b21bbfa6c027c01b6600060f1770e0dd5ba72ec8f83aa7e9a073547a75acd9753ae55f0410f9de38d6324fe8f4c3c938
+  data.tar.gz: dfa555c326077d674e3ef8157d5a72fca16000c39be3e4ad707ebe1edf7b10aa306f6d44516972e8020823f28aface6a7c22ed2798b6e0d795942b3ce1f35d49

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# 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.1] — 2026-07-26
+
+Documentation only. No code changes; upgrading is optional.
+
+### Changed
+
+- Expanded the gem description. rubygems.org does not render `README.md` — the
+  gem page shows only the description — so the things a developer needs in order
+  to evaluate the library (hot-path cost, failure behaviour under an outage,
+  zero-dependency footprint, fork safety, and the fact that group membership is
+  resolved in your own process so no user data leaves it) are now stated there
+  rather than being visible only on GitHub.
+
+## [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.1"
 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.1
 platform: ruby
 authors:
 - ToggleFleet
@@ -9,16 +9,30 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: ToggleFleet is a cloud feature-flag service. This gem fetches your environment's
-  flags, caches them, and evaluates all five gates (boolean, actor, group, % of actors,
-  % of time) locally — so checking a flag is a hash lookup, not a network call. Background
-  refresh uses conditional ETag requests; evaluation is byte-identical to the server.
+description: |
+  ToggleFleet is a hosted feature-flag service for Ruby. This gem fetches your environment's
+  flags once, refreshes them in the background with conditional ETag requests, and evaluates
+  all five gates — boolean, actor, group, percentage-of-actors (sticky), and percentage-of-time
+  — entirely in-process. Checking a flag is a hash lookup, not a network call, so flags cost
+  nothing on the hot path and keep working at their last known values if ToggleFleet is
+  unreachable.
+
+  Zero runtime dependencies — only the Ruby standard library. Thread-safe, fork-safe under
+  Puma/Unicorn/Passenger, and fail-safe by design: any error returns your configured default
+  rather than raising into a request.
+
+  Evaluation is byte-identical to server-side evaluation, including MD5 bucketing, so a sticky
+  rollout targets exactly the same actors whether it is resolved locally or through the API.
+  Group membership is decided by predicates in your own code, so no user data leaves your process.
+
+  Requires a ToggleFleet account for an SDK key. Full documentation at https://togglefleet.com/docs.
 email:
 - support@togglefleet.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/togglefleet.rb
@@ -30,6 +44,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: