quonfig 0.0.16 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f167f3b60db07394dc7c49b85c3dbc196e0b5c82f3426b35695c0f212339b8b
-  data.tar.gz: 4b79e1196c4625359943255a348d907c28865a5cd85432ac464737406d7a6169
+  metadata.gz: 125753bc634b155cdae7cf4772705ee74c5ec37f4a612c9c52ea873a94d0c5ca
+  data.tar.gz: 2c6e09f01e7ed54cf7e6f0fbb33784ea62e0d2bd069a87e3d74dafe3ed97aeb1
 SHA512:
-  metadata.gz: 5aa3a23774245bf31752e4c9918de8bf37cc865e15b6ed160b222181d805a0fe477064cc5cf27dc6810b87cdd1c250f8558b650c98fd5e7a354c3e2e70090c53
-  data.tar.gz: 82c4561817b40e4dd0ecfd1b5267e6a5f41ea2e774c2d2537400aaf04886eb579807da457f6964915a065a32dc7beea043a2797d83ff04dba3c9fb4e46c39cb3
+  metadata.gz: 7e9474c7aa96611977db52658ba730efab5aafddb811e68dbd8ce90833d3c3017f6d5bc9b870db54be4b125844f43d46d96c067179a5cfd744880e4ca32cbd79
+  data.tar.gz: 26e638dbdeb223f06d9742cd155fd2b5b33073b20ee6e397a3322564979042c9c9dff8a3f893127c30ca70544202fc04ba2e3ce6c6c2f58332613dba884f9c33

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.0.18 - 2026-05-21
+
+- **Fix (SSE): give Net `read_timeout` headroom over the watchdog deadline (qfg-6y44).** `stream_once` armed two read deadlines at the identical `sse_read_timeout` value: `Net::HTTP#read_timeout` and the `ReadDeadlineWatchdog`. On the body read both were live, and the watchdog carries up to `POLL_INTERVAL` (0.25 s) of polling latency on top of its deadline — so when Net's (unreliable on the `read_body` path) stdlib timeout did fire, it could beat the watchdog and surface a `Net::ReadTimeout` instead of the `SSEReadDeadlineExceeded` the SDK is instrumented around. A new `READ_TIMEOUT_HEADROOM` (30 s) keeps Net's `read_timeout` as a redundant backstop while guaranteeing the watchdog fires first.
+- **Fix (datadir): coerce int/double config values to numbers at load time (qfg-38sf.8).** Config files store `int`/`double` Value fields as JSON strings (`{"type":"int","value":"123"}`). api-delivery normalizes these to real numbers at config-load time (`Value.UnmarshalJSON`), so every HTTP/SSE envelope already carries JSON numbers — but the datadir loader read the files directly and passed the strings through verbatim. `Quonfig::Datadir` now runs a generic recursive `coerce_numeric_values` walk over each parsed config document before projecting it to a `ConfigResponse`: any Value node (`type` of `"int"`/`"double"` with a String `value`) is coerced via `Integer(value, 10)` / `Float(value)`, covering `default.rules[].value`, environment rules, `criteria[].valueToMatch`, weighted-value arms, and variants. An unparseable numeric string is left untouched (passthrough — never raises). Brings the datadir loader in line with sdk-go and api-delivery so the loaded envelope always carries real numbers regardless of who consumes it.
+- **CI: pin `integration-test-data` to v2026.05.20 and guard against stale generated tests (#12).** The integration suite now resolves its YAML specs from a pinned tag, and a guard fails the build if the generated tests drift from the templates.
+- **CI: skip the Chaos workflow on Dependabot PRs and de-flake the datadir-reload test (8f60d9c).**
+- **Dependency bumps (CI actions):** `actions/setup-go` 5.6.0 → 6.4.0 (#7), `actions/checkout` 4.3.1 → 6.0.2 (#8), `actions/upload-artifact` 4.6.2 → 7.0.1 (#9), `ruby/setup-ruby` 1.306.0 → 1.310.0 (#10).
+
+## 0.0.17 - 2026-05-19
+
+- **Feat (datadir): opt-in `data_dir_auto_reload` (qfg-mol-2da).** Datadir mode previously loaded the workspace once at construction and served purely from memory. Set `data_dir_auto_reload: true` to have the SDK watch the configured `datadir`, re-read `Quonfig::Datadir.load_envelope`, and fire the existing `on_update` callback whenever files change. Adds `listen ~> 3.8` (FSEvents on macOS, inotify on Linux, polling fallback on Windows) as a runtime dep. Behavior: parse-then-swap (a failed parse keeps the previous envelope and skips the callback), debounced (`data_dir_auto_reload_debounce_ms`, default 200 ms — bursts coalesce to one reload), and gracefully downgrades when watch registration fails (read-only fs, immutable container, missing native backend). Symlinked datadirs are resolved to their real path before watching. Default is `false`; opt-in only.
+- **Feat (datadir + fork): auto-restart the watcher across `fork(2)` (qfg-mol-2da).** The watcher uses a background thread, which does not survive fork. The existing `Process._fork` hook (qfg-ryov, Ruby 3.1+) now also tears the datadir watcher down in the parent before fork and rebuilds a fresh one on the same `Client` in each child — no customer wiring required for Puma clustered mode, Unicorn, Sidekiq's parent-forks-workers model, Resque, or Spring. Ruby 3.0 customers continue to use the documented `Quonfig.fork` pattern in `on_worker_boot`, which rebuilds the watcher alongside the rest of the client.
+
 ## 0.0.16 - 2026-05-15
 
 - **Feat (SSE): replace `ld-eventsource` with an SDK-owned reconnect loop (qfg-35sm).** sdk-ruby was the outlier among the four backend SDKs — sdk-go, sdk-node, and sdk-python all own their reconnect loop, only sdk-ruby handed it off to a library and scraped its log output to observe reconnects. The wire format we actually consume (plain JSON envelopes in single-line `data:` frames, no named events, no retry directives) is trivial enough that an SDK-owned loop is clearer than the library wrapper. New `Quonfig::SSEConfigClient` (~520 LoC, `lib/quonfig/sse_config_client.rb`) handles connect/parse/reconnect end-to-end. `restart_total` is now incremented at exactly one site under a mutex — verifiable, not log-scraped. `ld-eventsource` and the transitive `http` gem are removed from the gemspec. `ReconnectCountingLogger` and the `sse_reconnect_reset_interval` option (both 0.0.15-era defensive scaffolding around upstream behavior) are deleted — the bugs they defended against don't exist when the SDK owns the loop. Chaos: 10/10 in a 36-min run (scenarios 02 silent-stall, 05 sse-down-fallback, 09 flapping kill-storm).

data/README.md

@@ -107,6 +107,107 @@ export QUONFIG_ENVIRONMENT=production
 client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
 ```
 
+## Datadir mode: auto-reload on file changes
+
+In datadir mode the SDK loads the workspace once at construction time and then
+serves config purely from memory. Opt in to `data_dir_auto_reload: true` to
+have the SDK watch the directory and re-read the envelope whenever files
+change — an editor save, a `git pull`, or a build step that rewrites the
+workspace.
+
+```ruby
+client = Quonfig::Client.new(
+  datadir:              '/path/to/workspace',
+  environment:          'development',
+  data_dir_auto_reload: true # off by default — must be opted in
+)
+
+client.on_update do
+  puts 'Quonfig configs reloaded from disk'
+end
+
+# Edit a file under /path/to/workspace and on_update fires within ~200ms.
+
+# On shutdown, stop stops the watcher and cancels any pending debounce.
+client.stop
+```
+
+### When to enable
+
+- Local development with the datadir checked out from git.
+- Self-hosted servers that `git pull` the datadir on a schedule.
+- CI jobs that mutate the datadir between assertions.
+
+### When NOT to enable
+
+- **Read-only / immutable filesystems** (some containers, scratch images,
+  AWS Lambda). Watch registration may fail; the SDK degrades gracefully
+  (logs the error and continues serving the envelope it loaded at init time)
+  but you're paying for nothing.
+- **Build-time-embedded workflows** where the datadir is bundled into the
+  artifact and never changes at runtime. Watching wastes a thread and a
+  native-backend handle.
+- **Production paths where reload timing matters** — e.g. you'd rather pin
+  the envelope you shipped with and roll forward through a redeploy than
+  have it shift under traffic.
+
+Default is `false`; datadir mode is silent until you opt in.
+
+### Behavior contract
+
+- **Parse-then-swap.** If the new envelope fails to parse (truncated write,
+  mid-`git pull` state, invalid JSON), the SDK logs the error and **keeps
+  serving the previous envelope**. `on_update` is _not_ fired on parse
+  failure — only on a successful swap.
+- **Debounced.** Bursts of filesystem events (atomic-rename editor saves,
+  `git pull` touching dozens of files) coalesce into a single re-read.
+  Default window: **200ms** — long enough to absorb the 3–5 events a typical
+  editor emits in <50ms, short enough that interactive edits feel immediate.
+  Tune via `data_dir_auto_reload_debounce_ms` if you need a different
+  window.
+- **Graceful degrade.** If watch registration fails (read-only fs, immutable
+  container, missing native backend), the SDK logs and continues without
+  watching — it does **not** raise from the constructor.
+- **Symlinks.** The watcher resolves `datadir` to its real path at start
+  time. Editing the file the symlink points at _is_ detected; atomic flips
+  that retarget the link itself are **not**.
+- **Shutdown.** `client.stop` stops the watcher and cancels any pending
+  debounce. There is no separate handle to manage — the watcher lifecycle
+  is tied to the client.
+
+### Fork safety (Puma cluster, Unicorn, Resque, Sidekiq)
+
+The auto-reload watcher uses a background thread, which — like any Ruby
+thread — does not survive `fork(2)`. **You do not need to wire this up
+manually on Ruby 3.1+.** The SDK's `Process._fork` hook (see [Rails
+integration](#rails-integration) below) stops the watcher in the parent
+before fork and restarts a fresh watcher in each child after fork. This
+covers Puma clustered mode, Unicorn, Sidekiq's parent-forks-workers model,
+Resque, Spring, and manual `fork { ... }` calls.
+
+On Ruby 3.0 (no `Process._fork`), follow the manual `before_fork` /
+`on_worker_boot` pattern in the [Rails integration](#rails-integration)
+section — `Quonfig.fork` rebuilds the full client, including the datadir
+watcher, in the child.
+
+### Tuning the debounce window
+
+```ruby
+Quonfig::Client.new(
+  datadir:                          '/path/to/workspace',
+  data_dir_auto_reload:             true,
+  data_dir_auto_reload_debounce_ms: 1000 # wait a full second after the last event
+)
+```
+
+The default (200 ms) is tuned for interactive editing. Raise it if you have
+a noisy producer (continuously regenerating files) and you'd rather see one
+reload per second than per save. Lower it only if you've measured that 200 ms
+is meaningfully too slow for your use case.
+
+See the [open-source / local how-to](https://docs.quonfig.com/docs/how-tos/open-source-local)
+for the cross-SDK story (sdk-node, sdk-go, sdk-ruby, sdk-python, sdk-java).
+
 ## Environment variables
 
 | Variable                    | Purpose                                                                                  |
@@ -130,7 +231,9 @@ Quonfig::Client.new(
   on_no_default:   :error,
   global_context:  {},
   datadir:         '/path/to/workspace',
-  environment:     'production'
+  environment:     'production',
+  data_dir_auto_reload:             false,
+  data_dir_auto_reload_debounce_ms: 200
 )
 ```
 
@@ -147,6 +250,8 @@ Quonfig::Client.new(
 | `global_context`  | `Hash`                     | `{}`                                                                | Context applied to every evaluation.                                                              |
 | `datadir`         | `String`                   | `ENV['QUONFIG_DIR']`                                                | Path to a local workspace. When set, the SDK runs offline from disk.                              |
 | `environment`     | `String`                   | `ENV['QUONFIG_ENVIRONMENT']`                                        | Environment to evaluate in datadir mode. Required when `datadir` is set.                          |
+| `data_dir_auto_reload`              | `Boolean`         | `false`                                                             | Datadir mode only. When `true`, the SDK watches the datadir and re-reads the envelope when files change. See [Datadir mode: auto-reload on file changes](#datadir-mode-auto-reload-on-file-changes). |
+| `data_dir_auto_reload_debounce_ms`  | `Integer` (ms)    | `200`                                                               | Debounce window for the auto-reload watcher — events arriving inside the window are coalesced into a single re-read. Ignored when `data_dir_auto_reload` is `false`. |
 | `logger`          | Logger-like object         | `nil`                                                               | Optional host-app logger (e.g. `Rails.logger`). Must respond to `debug`/`info`/`warn`/`error`. When set, all SDK warnings/errors flow through this logger instead of the default stderr / SemanticLogger backend. |
 
 ## Typed getters

data/lib/quonfig/client.rb

@@ -78,6 +78,7 @@ module Quonfig
 
       if @options.datadir
         load_datadir_into_store
+        start_datadir_watcher if @options.data_dir_auto_reload
       else
         initialize_network_mode
       end
@@ -316,7 +317,12 @@ module Quonfig
     # or if the client is in datadir mode (no threaded components to start).
     def after_fork_in_child
       return if @stopped
-      return if @options.datadir
+
+      if @options.datadir
+        start_datadir_watcher if @options.data_dir_auto_reload
+        return
+      end
+
       return if @config_loader.nil? # never finished network init (e.g. invalid key)
 
       # SSE state machine carries flags that no longer apply in the child
@@ -429,6 +435,13 @@ module Quonfig
         LOG.debug "Error stopping telemetry reporter: #{e.message}"
       end
       @telemetry_reporter = nil
+
+      begin
+        @datadir_watcher&.stop
+      rescue StandardError => e
+        LOG.debug "Error stopping datadir watcher: #{e.message}"
+      end
+      @datadir_watcher = nil
     end
 
     # Rebuild the telemetry reporter in the child after fork. Mirrors the
@@ -675,10 +688,60 @@ module Quonfig
 
     def load_datadir_into_store
       envelope = Quonfig::Datadir.load_envelope(@options.datadir, @options.environment)
+      apply_datadir_envelope(envelope)
+    end
+
+    # Apply a freshly loaded datadir envelope to the store. Keys that were
+    # present before but missing now are deleted, so a `rm configs/foo.json`
+    # propagates through the auto-reload path. Records a refresh timestamp.
+    # Caller is responsible for firing on_update.
+    def apply_datadir_envelope(envelope)
+      new_keys = envelope.configs.map { |cfg| cfg['key'] }.compact.to_set
+      old_keys = @store.keys.to_set
+      (old_keys - new_keys).each { |k| @store.delete(k) }
       envelope.configs.each { |cfg| @store.set(cfg['key'], cfg) }
       record_refresh!
     end
 
+    # qfg-mol-2da: start the filesystem watcher for datadir auto-reload.
+    # On listen-registration failure (read-only fs, missing native backend),
+    # log and continue without watching — the SDK keeps serving the envelope
+    # captured at init.
+    def start_datadir_watcher
+      return unless @options.datadir
+
+      watcher = Quonfig::DatadirWatcher.new(
+        datadir: @options.datadir,
+        debounce_ms: @options.data_dir_auto_reload_debounce_ms,
+        on_change: -> { reload_datadir! },
+        on_error: ->(err) { LOG.warn "[quonfig] datadir watcher error: #{err.class}: #{err.message}" }
+      )
+      unless watcher.start
+        LOG.warn '[quonfig] data_dir_auto_reload requested but watcher registration failed; continuing without auto-reload'
+        return
+      end
+      @datadir_watcher = watcher
+    end
+
+    # Re-read the datadir into a fresh envelope and atomically install it.
+    # Parse errors (mid-write JSON, garbage file) are logged and swallowed:
+    # the previous envelope stays in the store and on_update does NOT fire.
+    # qfg-mol-2da.
+    def reload_datadir!
+      return if @stopped
+      return unless @options.datadir
+
+      begin
+        envelope = Quonfig::Datadir.load_envelope(@options.datadir, @options.environment)
+      rescue StandardError => e
+        LOG.warn "[quonfig] datadir reload failed; keeping previous envelope: #{e.class}: #{e.message}"
+        return
+      end
+
+      apply_datadir_envelope(envelope)
+      notify_on_update_callback
+    end
+
     # Initialize network mode: sync HTTP fetch (bounded by
     # initialization_timeout_sec) then start SSE + polling as requested.
     def initialize_network_mode

data/lib/quonfig/datadir.rb

@@ -42,6 +42,7 @@ module Quonfig
           raw = JSON.parse(File.read(path))
           raise ArgumentError, "[quonfig] config has empty key — file is not a Quonfig Config: #{path}" if raw['key'].nil? || raw['key'].to_s.empty?
 
+          coerce_numeric_values(raw)
           configs << to_config_response(raw, env_id)
         end
       end
@@ -94,5 +95,42 @@ module Quonfig
 
       raw || false
     end
+
+    # Config files store int/double Value fields as JSON strings
+    # (`{"type":"int","value":"123"}`). api-delivery normalizes these to real
+    # numbers at config-load time (`Value.UnmarshalJSON`), so every envelope it
+    # emits over HTTP/SSE already carries JSON numbers. In datadir mode we read
+    # the files directly, so we must coerce here to match.
+    #
+    # Walks the parsed config document in place, coercing every Value node — any
+    # Hash with a `type` of `"int"`/`"double"` and a String `value` — to a real
+    # number. A generic recursive walk covers `default.rules[].value`,
+    # environment rules, `criteria[].valueToMatch`, weighted-value arms, and
+    # variants without enumerating each location. On parse failure the original
+    # string is left in place (passthrough — never raise).
+    def coerce_numeric_values(node)
+      case node
+      when Hash
+        coerce_numeric_value_field(node)
+        node.each_value { |child| coerce_numeric_values(child) }
+      when Array
+        node.each { |child| coerce_numeric_values(child) }
+      end
+      node
+    end
+
+    def coerce_numeric_value_field(hash)
+      value = hash['value']
+      return unless value.is_a?(String)
+
+      case hash['type']
+      when 'int'
+        hash['value'] = Integer(value, 10)
+      when 'double'
+        hash['value'] = Float(value)
+      end
+    rescue ArgumentError, TypeError
+      # Unparseable numeric string — leave the original value untouched.
+    end
   end
 end

data/lib/quonfig/datadir_watcher.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Quonfig
+  # Watches a datadir for changes and fires +on_change+ once per debounced
+  # burst. Wraps the `listen` gem (https://github.com/guard/listen), which
+  # uses platform-native backends (FSEvents on macOS, inotify on Linux,
+  # polling fallback on Windows).
+  #
+  # The caller owns parse-then-swap: this class only fires the trigger.
+  # Registration failures (read-only fs, immutable container, native backend
+  # missing) are surfaced via +on_error+; in that case +start+ returns
+  # +false+ and no listener is held.
+  #
+  # Mirrors sdk-node/src/datadirWatcher.ts (qfg-mol-0kr) modulo Ruby idioms:
+  # listen does not have an equivalent to Node's `fs.watch({recursive:true})`,
+  # but it watches recursively by default.
+  class DatadirWatcher
+    # Indirection seam for tests. Production code uses ::Listen; tests can
+    # swap in a class that raises from `.to` to exercise the registration-
+    # failure path without needing a read-only filesystem.
+    LISTEN_FACTORY = nil # resolved lazily so the gem can be required late
+
+    def initialize(datadir:, debounce_ms:, on_change:, on_error:)
+      @datadir = datadir
+      @debounce_seconds = debounce_ms.to_f / 1000.0
+      @on_change = on_change
+      @on_error = on_error
+      @mutex = Mutex.new
+      @scheduled_task = nil
+      @listener = nil
+      @closed = false
+    end
+
+    # Start the underlying file watcher. Returns true on success, false if
+    # registration failed (in which case +on_error+ has already been called
+    # and the caller should continue without auto-reload).
+    #
+    # Blocks until the listener is in its :processing_events state (or a
+    # short safety timeout elapses) so a customer writing to the datadir
+    # immediately after the Client constructor returns is detected, rather
+    # than racing the listen backend's async setup.
+    def start
+      resolved = File.realpath(@datadir)
+      factory = self.class::LISTEN_FACTORY || ::Listen
+      @listener = factory.to(resolved) do |_modified, _added, _removed|
+        schedule_reload
+      end
+      @listener.start
+      wait_for_listener_ready
+      true
+    rescue StandardError => e
+      @on_error.call(e)
+      false
+    end
+
+    # Stop the watcher and cancel any pending debounce. Idempotent.
+    def stop
+      task, listener = @mutex.synchronize do
+        @closed = true
+        t = @scheduled_task
+        l = @listener
+        @scheduled_task = nil
+        @listener = nil
+        [t, l]
+      end
+      begin
+        task&.cancel
+      rescue StandardError
+        # best-effort; caller already in shutdown
+      end
+      begin
+        listener&.stop
+      rescue StandardError
+        # best-effort
+      end
+    end
+
+    private
+
+    # Block briefly until the listener reports :processing_events. Listen's
+    # state machine supports wait_for_state; we cap at 500 ms so a broken
+    # backend cannot wedge the SDK boot. (The native FSEvents backend on
+    # macOS still has ~100ms latency *after* this returns — that is a
+    # property of the OS, not something we can synchronize away. Tests that
+    # need to observe the first post-init write should sleep accordingly.)
+    def wait_for_listener_ready
+      return unless @listener.respond_to?(:wait_for_state)
+
+      begin
+        @listener.wait_for_state(:processing_events, timeout: 0.5)
+      rescue StandardError
+        # If the FSM doesn't transition, keep going — events may still flow.
+      end
+    end
+
+    def schedule_reload
+      @mutex.synchronize do
+        return if @closed
+
+        @scheduled_task&.cancel
+        on_change = @on_change
+        @scheduled_task = Concurrent::ScheduledTask.execute(@debounce_seconds) do
+          # Re-check closed under the mutex so a stop() landing between cancel
+          # and execute cannot resurrect a fired callback.
+          should_fire = @mutex.synchronize { !@closed }
+          on_change.call if should_fire
+        end
+      end
+    end
+  end
+end

data/lib/quonfig/options.rb

@@ -6,7 +6,8 @@ module Quonfig
   # Options passed to Quonfig::Client at construction time.
   class Options
     attr_reader :sdk_key, :environment, :api_urls, :sse_api_urls, :telemetry_destination, :config_api_urls,
-                :on_no_default, :initialization_timeout_sec, :on_init_failure, :collect_sync_interval, :datadir, :enable_sse, :enable_polling, :poll_interval, :global_context, :logger_key, :logger, :enable_quonfig_user_context
+                :on_no_default, :initialization_timeout_sec, :on_init_failure, :collect_sync_interval, :datadir, :enable_sse, :enable_polling, :poll_interval, :global_context, :logger_key, :logger, :enable_quonfig_user_context,
+                :data_dir_auto_reload, :data_dir_auto_reload_debounce_ms
     attr_accessor :is_fork
 
     module ON_INITIALIZATION_FAILURE
@@ -119,6 +120,24 @@ module Quonfig
 
     private
 
+    # @!method initialize(options = {})
+    #   @option options [Boolean] :data_dir_auto_reload (false)
+    #     Datadir mode only. When +true+, the SDK watches the workspace
+    #     directory and re-reads the envelope whenever files inside it
+    #     change. Parse-then-swap: a failed parse keeps the previous
+    #     envelope. Default debounce window is 200 ms; tune via
+    #     +:data_dir_auto_reload_debounce_ms+. Listen-registration failure
+    #     (read-only fs, missing native backend) is logged and the SDK
+    #     continues serving the envelope captured at init.
+    #
+    #     On Ruby 3.1+ the SDK's +Process._fork+ hook tears the watcher
+    #     down in the parent before fork and rebuilds it in each child;
+    #     no customer wiring is required for Puma cluster / Unicorn /
+    #     Sidekiq / Resque. See README "Fork safety".
+    #   @option options [Integer] :data_dir_auto_reload_debounce_ms (200)
+    #     Debounce window in milliseconds. Filesystem events arriving
+    #     inside the window are coalesced into a single re-read. Ignored
+    #     when +:data_dir_auto_reload+ is +false+.
     def init(
       api_urls: nil,
       telemetry_url: nil,
@@ -141,7 +160,9 @@ module Quonfig
       global_context: {},
       logger_key: nil,
       logger: nil,
-      enable_quonfig_user_context: false
+      enable_quonfig_user_context: false,
+      data_dir_auto_reload: false,
+      data_dir_auto_reload_debounce_ms: 200
     )
       @sdk_key = sdk_key
       @environment = environment
@@ -163,6 +184,8 @@ module Quonfig
       @logger_key = logger_key
       @logger = logger
       @enable_quonfig_user_context = enable_quonfig_user_context
+      @data_dir_auto_reload = data_dir_auto_reload
+      @data_dir_auto_reload_debounce_ms = data_dir_auto_reload_debounce_ms
 
       # defaults that may be overridden by context_upload_mode
       @collect_shapes = false

data/lib/quonfig/sse_config_client.rb

@@ -56,6 +56,17 @@ module Quonfig
     # Anything else (5xx, 429, network errors) stays on the transient path.
     TERMINAL_HTTP_CODES = [401, 403, 404].freeze
 
+    # qfg-6y44: headroom added to +sse_read_timeout+ when configuring
+    # Net::HTTP#read_timeout. The ReadDeadlineWatchdog already covers both the
+    # header and body reads at exactly +sse_read_timeout+; Net's own
+    # read_timeout is only a redundant backstop. Arming it at the *same* value
+    # as the watchdog makes the two race — and on the body path Net's
+    # (unreliable) timeout can fire first, surfacing a Net::ReadTimeout instead
+    # of the SSEReadDeadlineExceeded the SDK is instrumented around. Giving
+    # Net's read_timeout this much headroom keeps it a backstop without ever
+    # letting it win the race.
+    READ_TIMEOUT_HEADROOM = 30
+
     # +on_error+: optional callable invoked on every SSE error edge. Parent
     # Quonfig::Client wires this to drive @sse_state -> :error so that
     # +connection_state+ reflects the disconnect (qfg-47c2.27).
@@ -254,8 +265,11 @@ module Quonfig
       http.use_ssl = (uri.scheme == 'https')
       http.open_timeout = @options.sse_connect_timeout
       # Keep Net::HTTP's read_timeout as a backstop for the header read
-      # (where it does apply reliably). The watchdog covers the body path.
-      http.read_timeout = @options.sse_read_timeout
+      # (where it does apply reliably). The watchdog covers the body path —
+      # so read_timeout gets READ_TIMEOUT_HEADROOM over the watchdog deadline
+      # to guarantee the watchdog fires first and we get a deterministic
+      # SSEReadDeadlineExceeded rather than a racy Net::ReadTimeout (qfg-6y44).
+      http.read_timeout = @options.sse_read_timeout + READ_TIMEOUT_HEADROOM
 
       req = Net::HTTP::Get.new(uri.request_uri, headers)
 

data/lib/quonfig/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quonfig
-  VERSION = '0.0.16'
+  VERSION = '0.0.18'
 end

data/lib/quonfig.rb

@@ -51,6 +51,8 @@ require 'quonfig/resolver'
 require 'quonfig/config_envelope'
 require 'quonfig/config_loader'
 require 'quonfig/datadir'
+require 'listen'
+require 'quonfig/datadir_watcher'
 require 'quonfig/sse_config_client'
 require 'quonfig/http_connection'
 require 'quonfig/caching_http_connection'

data/quonfig.gemspec

@@ -31,4 +31,8 @@ Gem::Specification.new do |s|
   s.add_dependency 'activesupport', '>= 4'
   s.add_dependency 'concurrent-ruby', '~> 1.0', '>= 1.0.5'
   s.add_dependency 'faraday', '>= 1.0'
+  # File watching for opt-in data_dir_auto_reload (qfg-mol-2da). 3.x supports
+  # Ruby 3.0+. Native backends (rb-fsevent on macOS, rb-inotify on Linux) are
+  # transitive deps of `listen`; the polling fallback is used elsewhere.
+  s.add_dependency 'listen', '~> 3.8'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 0.0.16
+  version: 0.0.18
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-15 00:00:00.000000000 Z
+date: 2026-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -58,6 +58,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
 description: Quonfig — feature flags and live config, stored as files in git.
 email: jeff@quonfig.com
 executables: []
@@ -79,6 +93,7 @@ files:
 - lib/quonfig/config_store.rb
 - lib/quonfig/context.rb
 - lib/quonfig/datadir.rb
+- lib/quonfig/datadir_watcher.rb
 - lib/quonfig/dev_context.rb
 - lib/quonfig/duration.rb
 - lib/quonfig/encryption.rb