quonfig 0.0.15 → 0.0.17

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