quonfig 0.0.18 → 0.0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125753bc634b155cdae7cf4772705ee74c5ec37f4a612c9c52ea873a94d0c5ca
-  data.tar.gz: 2c6e09f01e7ed54cf7e6f0fbb33784ea62e0d2bd069a87e3d74dafe3ed97aeb1
+  metadata.gz: f71f10c80365079815e7b7d7f2a9a8926ecfc358697505bb3c6bd3f2e6142976
+  data.tar.gz: 3d0988da2eb9a17457dc53c358e32a55aaa17f59e1c7c280db5db52b3eb991fc
 SHA512:
-  metadata.gz: 7e9474c7aa96611977db52658ba730efab5aafddb811e68dbd8ce90833d3c3017f6d5bc9b870db54be4b125844f43d46d96c067179a5cfd744880e4ca32cbd79
-  data.tar.gz: 26e638dbdeb223f06d9742cd155fd2b5b33073b20ee6e397a3322564979042c9c9dff8a3f893127c30ca70544202fc04ba2e3ce6c6c2f58332613dba884f9c33
+  metadata.gz: e019ac9393b2644208aaa79fbbed9bfe0a27e346413ffac2cd126d47fd9ffa114a1af4bfcd597b527577935a586ea6636aa6e8c96be8ee657889bc324d9ea38c
+  data.tar.gz: 89026759a78f4219766b14366630a5df3a3126884c5bfa721764cffdf6799c8f47df5be1245c86c8966aedbbb9a4508b65d53a400cd3c6e4308f872bc975f6ce

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.0.19 - 2026-05-28
+
+- **Deprecation (context): `in_context` is now a deprecated alias of `with_context` (qfg-e0kk).** The two methods have always been runtime-identical — both accept a properties hash and either yield a `Quonfig::BoundClient` to a given block or return the BoundClient directly. As part of the sdk-1.0 unification, every SDK in the family is converging on the `with_context` family; sdk-ruby keeps `in_context` as a YARD-`@deprecated` alias for the 1.0.0 cycle so existing customer code (especially Prefab-fork lineage call sites) keeps working without a runtime warning. Implementation collapses to a one-line forward (`in_context` now calls `with_context`), and the README example is updated to use `with_context`. Slated for removal in 2.0.0.
+- **Feat (options): rename `initialization_timeout_sec` → `init_timeout_ms` (qfg-39za).** Of the six SDKs, only sdk-ruby (and sdk-python, also being renamed) expressed this in seconds; sdk-node uses `initTimeout` (ms), sdk-javascript uses `timeout` (ms), sdk-java uses `Duration`. Picking `init_timeout_ms` as the canonical snake_case name lets sdk-ruby and sdk-python converge. The default is unchanged in wall-clock terms: `init_timeout_ms: 10_000` (previously expressed as `initialization_timeout_sec: 10`). The legacy `initialization_timeout_sec` kwarg and accessor are kept as deprecated aliases for one minor cycle; passing `initialization_timeout_sec:` (seconds) is forwarded transparently as `* 1000` into the ms-based storage, and reading `Options#initialization_timeout_sec` returns the configured timeout in seconds. Will be removed in a future minor release.
+- **Feat (options): rename `enable_polling` → `fallback_poll_enabled`, `poll_interval` → `fallback_poll_interval_ms` (qfg-thsn).** The old names predated the SSE+fallback architecture and read as "always poll", but the actual behavior since 0.0.4 has been "poll only when SSE is unavailable for >= 2x the interval". The new names match sdk-node / sdk-python / sdk-java. Defaults are unchanged: `fallback_poll_enabled: true`, `fallback_poll_interval_ms: 60_000` (previously expressed as 60 seconds). The legacy `enable_polling` and `poll_interval` kwargs and accessors are kept as deprecated aliases for one minor cycle; passing `poll_interval:` (seconds) is forwarded transparently as `poll_interval * 1000` into the new ms-based storage, and reading `Options#poll_interval` returns the configured interval in seconds. Will be removed in a future minor release.
+
 ## 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.

data/README.md

@@ -50,13 +50,13 @@ attach a context in three ways:
 client.get_bool('beta-feature', user: { key: 'user-123', plan: 'pro' })
 ```
 
-### 2. `in_context` block
+### 2. `with_context` block
 
 Everything evaluated inside the block sees the supplied context. The block's
-return value is returned from `in_context`.
+return value is returned from `with_context`.
 
 ```ruby
-result = client.in_context(user: { key: 'user-123', plan: 'pro' }) do |bound|
+result = client.with_context(user: { key: 'user-123', plan: 'pro' }) do |bound|
   {
     hero:   bound.get_string('homepage-hero'),
     limit:  bound.get_int('rate-limit'),
@@ -67,8 +67,9 @@ end
 
 ### 3. `with_context` — BoundClient for repeated lookups
 
-`with_context` returns an immutable `BoundClient` that carries the context on
-every call. Useful when you want to pass a context-bound handle down the stack.
+Called without a block, `with_context` returns an immutable `BoundClient` that
+carries the context on every call. Useful when you want to pass a
+context-bound handle down the stack.
 
 ```ruby
 bound = client.with_context(user: { key: 'user-123', plan: 'pro' })
@@ -78,6 +79,9 @@ bound.enabled?('beta-feature')
 bound.get_int('rate-limit')
 ```
 
+> `in_context` is a deprecated alias of `with_context` kept for backward
+> compatibility through 1.0.0. New code should use `with_context`.
+
 ## Datadir / offline mode
 
 For tests, CI, or air-gapped environments, point the client at a local workspace
@@ -221,17 +225,17 @@ for the cross-SDK story (sdk-node, sdk-go, sdk-ruby, sdk-python, sdk-java).
 
 ```ruby
 Quonfig::Client.new(
-  sdk_key:         '...',                          # required unless QUONFIG_BACKEND_SDK_KEY is set
-  api_urls:        ['https://primary.quonfig.com', 'https://secondary.quonfig.com'],
-  telemetry_url:   'https://telemetry.quonfig.com',
-  enable_sse:      true,
-  enable_polling:  false,
-  poll_interval:   60,
-  init_timeout:    10,
-  on_no_default:   :error,
-  global_context:  {},
-  datadir:         '/path/to/workspace',
-  environment:     'production',
+  sdk_key:                   '...',                          # required unless QUONFIG_BACKEND_SDK_KEY is set
+  api_urls:                  ['https://primary.quonfig.com', 'https://secondary.quonfig.com'],
+  telemetry_url:             'https://telemetry.quonfig.com',
+  enable_sse:                true,
+  fallback_poll_enabled:     true,
+  fallback_poll_interval_ms: 60_000,
+  init_timeout_ms:           10_000,
+  on_no_default:             :error,
+  global_context:            {},
+  datadir:                   '/path/to/workspace',
+  environment:               'production',
   data_dir_auto_reload:             false,
   data_dir_auto_reload_debounce_ms: 200
 )
@@ -242,10 +246,10 @@ Quonfig::Client.new(
 | `sdk_key`         | `String`                   | `ENV['QUONFIG_BACKEND_SDK_KEY']`                                    | SDK key for API authentication.                                                                   |
 | `api_urls`        | `Array<String>`            | `["https://primary.${QUONFIG_DOMAIN}", "https://secondary.${QUONFIG_DOMAIN}"]` | Ordered list of API base URLs to try. SSE stream URLs are derived by prepending `stream.` to each hostname. Defaults derive from `QUONFIG_DOMAIN` (default `quonfig.com`). |
 | `telemetry_url`   | `String`                   | `https://telemetry.${QUONFIG_DOMAIN}`                                          | Base URL for the telemetry service. Default derives from `QUONFIG_DOMAIN`.                        |
-| `enable_sse`      | `Boolean`                  | `true`                                                              | Receive real-time updates over Server-Sent Events.                                                |
-| `enable_polling`  | `Boolean`                  | `false`                                                             | Poll the API on an interval as a fallback.                                                        |
-| `poll_interval`   | `Integer` (seconds)        | `60`                                                                | Polling interval when `enable_polling` is `true`.                                                 |
-| `init_timeout`    | `Integer` (seconds)        | `10`                                                                | Maximum time to wait for the initial config load.                                                 |
+| `enable_sse`              | `Boolean`                  | `true`                                                              | Receive real-time updates over Server-Sent Events.                                                |
+| `fallback_poll_enabled`   | `Boolean`                  | `true`                                                              | Engage HTTP polling as a fallback when SSE is unavailable for >= 2x `fallback_poll_interval_ms`. Deprecated alias: `enable_polling`. |
+| `fallback_poll_interval_ms` | `Integer` (ms)           | `60_000`                                                            | Interval between fallback HTTP polls, in milliseconds. Deprecated alias: `poll_interval` (seconds, multiplied by 1000 internally). |
+| `init_timeout_ms` | `Integer` (ms)             | `10_000`                                                            | Maximum time to wait for the initial config load, in milliseconds. Deprecated alias: `initialization_timeout_sec` (seconds, multiplied by 1000 internally). |
 | `on_no_default`   | `Symbol`                   | `:error`                                                            | Behavior when a key has no value and no default: `:error`, `:warn`, or `:ignore`.                 |
 | `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.                              |

data/lib/quonfig/client.rb

@@ -185,17 +185,27 @@ module Quonfig
 
     # ---- Context binding ----------------------------------------------
 
-    def in_context(properties)
-      bound = Quonfig::BoundClient.new(self, properties)
-      block_given? ? yield(bound) : bound
+    # Bind +properties+ as a context. With a block, yields a
+    # {Quonfig::BoundClient} and returns the block's value. Without a block,
+    # returns the BoundClient directly.
+    #
+    # qfg-e0kk: kept as a deprecated alias of {#with_context}. The two methods
+    # have always been runtime-identical; sdk-1.0 unifies on +with_context+
+    # across all SDKs. No runtime warning is emitted (Prefab-fork lineage,
+    # heavy customer usage). Slated for removal in 2.0.0.
+    #
+    # @deprecated Use {#with_context} instead.
+    def in_context(properties, &block)
+      with_context(properties, &block)
     end
 
-    def with_context(properties, &block)
-      if block_given?
-        in_context(properties, &block)
-      else
-        Quonfig::BoundClient.new(self, properties)
-      end
+    # Bind +properties+ as a context. With a block, yields a
+    # {Quonfig::BoundClient} and returns the block's value. Without a block,
+    # returns the BoundClient directly — useful for passing a context-bound
+    # handle down the stack.
+    def with_context(properties)
+      bound = Quonfig::BoundClient.new(self, properties)
+      block_given? ? yield(bound) : bound
     end
 
     # ---- Filters & helpers --------------------------------------------
@@ -334,7 +344,7 @@ module Quonfig
       end
 
       sse_started = @options.enable_sse && start_sse
-      start_polling if @options.enable_polling && !sse_started
+      start_polling if @options.fallback_poll_enabled && !sse_started
 
       restart_telemetry_in_child
     end
@@ -515,7 +525,7 @@ module Quonfig
         [@sse_ever_connected, @sse_terminal_failure]
       end
 
-      return unless @options.respond_to?(:enable_polling) && @options.enable_polling
+      return unless @options.respond_to?(:fallback_poll_enabled) && @options.fallback_poll_enabled
       return if @stopped
       # qfg-i5xv: a terminal SSE classification suppresses polling engage in
       # every branch — the customer's key is bad and HTTP polling will fail
@@ -575,15 +585,19 @@ module Quonfig
       end
     end
 
-    # Schedule a 2*poll_interval grace timer after a connected->error edge.
-    # If SSE recovers before the timer fires, +cancel_fallback_engage_timer+
-    # tears it down. Idempotent — does nothing if a timer is already pending
-    # or the supervisor is already alive.
+    # Schedule a 2*fallback_poll_interval grace timer after a connected->error
+    # edge. If SSE recovers before the timer fires,
+    # +cancel_fallback_engage_timer+ tears it down. Idempotent — does nothing
+    # if a timer is already pending or the supervisor is already alive.
     def schedule_fallback_engage
-      poll_interval = @options.respond_to?(:poll_interval) && @options.poll_interval ? @options.poll_interval : 60
-      return if poll_interval <= 0
+      poll_ms = if @options.respond_to?(:fallback_poll_interval_ms) && @options.fallback_poll_interval_ms
+                  @options.fallback_poll_interval_ms
+                else
+                  60_000
+                end
+      return if poll_ms <= 0
 
-      grace_seconds = poll_interval * 2.0
+      grace_seconds = (poll_ms / 1000.0) * 2.0
 
       @state_mutex.synchronize do
         return if @fallback_engage_timer&.alive?
@@ -743,7 +757,7 @@ module Quonfig
     end
 
     # Initialize network mode: sync HTTP fetch (bounded by
-    # initialization_timeout_sec) then start SSE + polling as requested.
+    # init_timeout_ms) then start SSE + polling as requested.
     def initialize_network_mode
       raise Quonfig::Errors::InvalidSdkKeyError, @options.sdk_key if @options.sdk_key.nil? || @options.sdk_key.to_s.strip.empty?
 
@@ -760,7 +774,7 @@ module Quonfig
     end
 
     def perform_initial_fetch
-      timeout = @options.initialization_timeout_sec || 10
+      timeout = (@options.init_timeout_ms || 10_000) / 1000.0
       result = :failed
 
       begin
@@ -827,15 +841,20 @@ module Quonfig
       return if @stopped
       return if @poll_supervisor&.alive?
 
-      poll_interval = @options.respond_to?(:poll_interval) && @options.poll_interval ? @options.poll_interval : 60
-      return if poll_interval <= 0
+      poll_ms = if @options.respond_to?(:fallback_poll_interval_ms) && @options.fallback_poll_interval_ms
+                  @options.fallback_poll_interval_ms
+                else
+                  60_000
+                end
+      return if poll_ms <= 0
 
+      poll_seconds = poll_ms / 1000.0
       stopped_ref = -> { @stopped }
       worker = lambda do |notify_delivered|
         loop do
           break if stopped_ref.call
 
-          sleep poll_interval
+          sleep poll_seconds
           break if stopped_ref.call
 
           @config_loader.fetch!

data/lib/quonfig/config_loader.rb

@@ -12,7 +12,7 @@ module Quonfig
   #     -> 304 Not Modified (ETag honored via If-None-Match)
   #
   # The fetch is synchronous; Client is responsible for timing out the initial
-  # fetch per `initialization_timeout_sec`.
+  # fetch per `init_timeout_ms`.
   class ConfigLoader
     LOG = Quonfig::InternalLogger.new(self)
 

data/lib/quonfig/options.rb

@@ -6,10 +6,41 @@ 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, :init_timeout_ms, :on_init_failure, :collect_sync_interval, :datadir, :enable_sse, :fallback_poll_enabled, :fallback_poll_interval_ms, :global_context, :logger_key, :logger, :enable_quonfig_user_context,
                 :data_dir_auto_reload, :data_dir_auto_reload_debounce_ms
     attr_accessor :is_fork
 
+    # Default fallback poll interval, in milliseconds. The SDK polls api-delivery
+    # at this cadence only when SSE is unavailable for >= 2x this value.
+    DEFAULT_FALLBACK_POLL_INTERVAL_MS = 60_000
+
+    # Default initialization timeout, in milliseconds. The SDK waits up to this
+    # long for the initial config fetch before failing per :on_init_failure.
+    DEFAULT_INIT_TIMEOUT_MS = 10_000
+
+    # Deprecated alias for #fallback_poll_enabled. Will be removed in a future
+    # minor release.
+    def enable_polling
+      @fallback_poll_enabled
+    end
+
+    # Deprecated alias for #fallback_poll_interval_ms, in seconds. Reads back the
+    # interval in the legacy unit so existing callers (e.g. internal code that
+    # `sleep`s on this value) keep working. Will be removed in a future minor
+    # release.
+    def poll_interval
+      @fallback_poll_interval_ms / 1000.0
+    end
+
+    # Deprecated alias for #init_timeout_ms, in seconds. Reads back the timeout
+    # in the legacy unit so existing callers (e.g. internal code that passes
+    # this to Timeout.timeout) keep working. Will be removed in a future minor
+    # release.
+    def initialization_timeout_sec
+      ms = @init_timeout_ms.to_f / 1000.0
+      ms == ms.to_i ? ms.to_i : ms
+    end
+
     module ON_INITIALIZATION_FAILURE
       RAISE = :raise
       RETURN = :return
@@ -145,10 +176,13 @@ module Quonfig
       environment: ENV.fetch('QUONFIG_ENVIRONMENT', nil),
       datadir: ENV.fetch('QUONFIG_DIR', nil),
       enable_sse: true,
-      enable_polling: true,
-      poll_interval: 60,
+      fallback_poll_enabled: nil,
+      fallback_poll_interval_ms: nil,
+      enable_polling: nil,
+      poll_interval: nil,
       on_no_default: ON_NO_DEFAULT::RAISE,
-      initialization_timeout_sec: 10,
+      init_timeout_ms: nil,
+      initialization_timeout_sec: nil,
       on_init_failure: ON_INITIALIZATION_FAILURE::RAISE,
       collect_max_paths: DEFAULT_MAX_PATHS,
       collect_sync_interval: nil,
@@ -168,10 +202,39 @@ module Quonfig
       @environment = environment
       @datadir = datadir
       @enable_sse = enable_sse
-      @enable_polling = enable_polling
-      @poll_interval = poll_interval
+      # qfg-thsn: canonical names are fallback_poll_enabled and
+      # fallback_poll_interval_ms (matches sdk-node / sdk-python / sdk-java).
+      # The legacy enable_polling / poll_interval (seconds) kwargs are kept
+      # as deprecated aliases for one minor cycle. The canonical kwarg wins
+      # if both are passed; otherwise the legacy value is forwarded (and the
+      # seconds-based interval is multiplied *1000 transparently).
+      @fallback_poll_enabled = if !fallback_poll_enabled.nil?
+                                 fallback_poll_enabled
+                               elsif !enable_polling.nil?
+                                 enable_polling
+                               else
+                                 true
+                               end
+      @fallback_poll_interval_ms = if !fallback_poll_interval_ms.nil?
+                                     fallback_poll_interval_ms
+                                   elsif !poll_interval.nil?
+                                     poll_interval * 1000
+                                   else
+                                     DEFAULT_FALLBACK_POLL_INTERVAL_MS
+                                   end
       @on_no_default = on_no_default
-      @initialization_timeout_sec = initialization_timeout_sec
+      # qfg-39za: canonical name is init_timeout_ms. The legacy
+      # initialization_timeout_sec (seconds) kwarg is kept as a deprecated
+      # alias for one minor cycle. The canonical kwarg wins if both are
+      # passed; otherwise the legacy value is forwarded (and the seconds-based
+      # timeout is multiplied *1000 transparently).
+      @init_timeout_ms = if !init_timeout_ms.nil?
+                           init_timeout_ms
+                         elsif !initialization_timeout_sec.nil?
+                           (initialization_timeout_sec * 1000).to_i
+                         else
+                           DEFAULT_INIT_TIMEOUT_MS
+                         end
       @on_init_failure = on_init_failure
 
       @collect_max_paths = collect_max_paths

data/lib/quonfig/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 0.0.18
+  version: 0.0.19
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-21 00:00:00.000000000 Z
+date: 2026-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport