quonfig 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9da26b9a9f898ec76bf8520043abc42db011adf5e298cffa16ee8764c2c0ed6
-  data.tar.gz: '0189ef6ee1e93cec985f9f5b1f1b81f833527bf3c22a1af7886778d8f2dcb50e'
+  metadata.gz: 8408e71b66de6bfe3e771b4091429d31f15f1dbdc0bb74d2e05bc3bcd83415db
+  data.tar.gz: e22b82909ffbb87dec181aa5c526ae12f7d4d7669c498027809ba8209ccd7c97
 SHA512:
-  metadata.gz: e363cf1a35bbc428f35d1d4cebea4223dc84c4a1ddd39c3a7dcbc22bafb58a757b5fde92f357dd1a9b8c0e0cc90db247addd88c873e19887cd1d0eae0bc5332b
-  data.tar.gz: e81f8441d30449624e3c64b506e113d386ce8a55656943e4523cb2d919d97aad5d8afd68df6462df1324cb2368dd8d9694e808146d622dd790ccf722e630e442
+  metadata.gz: '0149ee240869602465f2ff10180f8f2c35b577bf12d6f73bf33afe02ac16e0742e93744c085cbd641c1640b542a137dbde8650e5dde580174b718d89d4b08ed6'
+  data.tar.gz: b223c20dc4cde206a30e803d43d507c1e4b5f204465c7e5e0c1f19db178842bc3a5013db7d734d09178a23cddca3df4e2b275f4f000b71bb3f2566e6395d337d

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.3.0 - 2026-08-18
+
+> **Heads up — datadir users will start emitting telemetry.** Datadir mode with a valid SDK key now emits usage telemetry as documented; it previously sent nothing. If you run the SDK with a `datadir:` (or `QUONFIG_DIR`) **and** an SDK key, upgrading to 1.3.0 means evaluation summaries and context telemetry begin flowing to the telemetry service from that deployment — data you were not sending on 1.2.0. Disable with the standard telemetry options if unwanted (`collect_evaluation_summaries: false` and `context_upload_mode: :none`). A datadir client with **no** SDK key still sends nothing at all.
+
+- **Fix (telemetry): the telemetry gate is SDK-key presence, not delivery mode (qfg-5x9x).** `Options#telemetry_allowed?` consulted `local_only?` (i.e. "is a datadir set?"), which forced every `collect_max_*` to `0` the moment a datadir was configured. With no collector limits the client built no aggregators, took `initialize_telemetry`'s early return, and never constructed a `TelemetryReporter` — so a datadir client holding a perfectly valid SDK key emitted **no** evaluation summaries, **no** context telemetry, nothing at all. Datadir is a config-**delivery** mode: it decides where config comes from, not whether usage is reported. The gate is now the SDK key alone, which is what identifies the workspace telemetry is attributed to. This aligns sdk-ruby with sdk-node, sdk-go, sdk-python, sdk-java, and sdk-net, and is the inverse of the defect fixed for sdk-go / sdk-python in 1.2.1 (those *over*-sent without a key). No wire-format change, no new dependencies, no public API removed.
+- **Fix (telemetry): a keyless client now collects nothing at all.** Without an SDK key there is no workspace to attribute telemetry to, so the aggregators are no longer even allocated and the reporter never starts (previously the collectors filled up in delivery mode and were discarded at flush time). Behavior for the open-source / no-account path is unchanged from the outside — still zero telemetry HTTP — but nothing is accumulated in memory on the way there.
+- **Deprecated: `allow_telemetry_in_local_mode:` is now a no-op.** It existed only to re-enable telemetry that datadir mode had suppressed; with mode out of the decision there is nothing left for it to unlock. The kwarg is still accepted so existing callers keep working, and it can neither enable telemetry without a key nor suppress it with one. Slated for removal in 2.0.0 — use `collect_evaluation_summaries: false` / `context_upload_mode: :none` to opt out.
+- **Docs:** the README's datadir section previously claimed the mode "performs no network I/O" unconditionally. It now states the delivery-side guarantee precisely (no config fetch, no SSE, no polling) and documents the telemetry gate, including how to run datadir + key with telemetry off.
+
 ## 1.2.0 - 2026-07-08
 
 - **Feat (options): warn when an explicit `api_urls` disables automatic failover (qfg-41nh.26).** The default (and every `QUONFIG_DOMAIN`-derived) `api_urls` list carries a primary AND a secondary leg, and the HTTP config-fetch hedges/fails over between them (the secondary runs on separate infrastructure). An explicit `api_urls:` replaces that list wholesale, so a single-entry override silently dropped the secondary and disabled automatic failover. The client now logs one WARN at init when the caller explicitly set `api_urls` and the resolved list has fewer than two legs, pointing at the fix (pass both a primary and a secondary URL). Behavior is otherwise unchanged; no new dependencies. A new README "Failover & `QUONFIG_DOMAIN`" section documents the URL derivation and the failover model.

data/README.md

@@ -86,7 +86,8 @@ bound.get_int('rate-limit')
 
 For tests, CI, or air-gapped environments, point the client at a local workspace
 directory instead of the Quonfig API. In datadir mode the SDK loads JSON config
-files from disk and performs no network I/O.
+files from disk — config delivery does no network I/O at all: no config fetch,
+no SSE stream, no polling.
 
 ```ruby
 client = Quonfig::Client.new(
@@ -111,6 +112,32 @@ export QUONFIG_ENVIRONMENT=production
 client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
 ```
 
+### Telemetry in datadir mode
+
+Usage telemetry is gated on **SDK-key presence, not on mode**. A datadir client
+with an `sdk_key:` configured still reports evaluation summaries and context
+telemetry to the telemetry service, exactly as a delivery-mode client does —
+that combination is what makes flag usage visible in the Quonfig UI for services
+that read config from a checked-out workspace.
+
+A datadir client with **no** SDK key has no workspace to attribute telemetry to,
+so it collects and sends nothing: fully offline, zero network I/O.
+
+To run with a key but without telemetry, use the standard opt-outs:
+
+```ruby
+client = Quonfig::Client.new(
+  datadir:                      '/path/to/workspace',
+  environment:                  'production',
+  sdk_key:                      ENV['QUONFIG_BACKEND_SDK_KEY'],
+  collect_evaluation_summaries: false,
+  context_upload_mode:          :none
+)
+```
+
+> Changed in 1.3.0: before 1.3.0 a datadir sent nothing even with a valid SDK
+> key. See the CHANGELOG.
+
 ## Datadir mode: auto-reload on file changes
 
 In datadir mode the SDK loads the workspace once at construction time and then

data/lib/quonfig/options.rb

@@ -140,10 +140,21 @@ module Quonfig
 
     # In datadir mode the SDK evaluates config from a local workspace and does
     # not connect to the delivery service.
+    #
+    # NOTE: this says nothing about telemetry. Datadir mode is a config-DELIVERY
+    # mode; usage telemetry still flows whenever an SDK key is configured. See
+    # #telemetry_allowed?.
     def local_only?
       !@datadir.nil?
     end
 
+    # True when an SDK key is configured. The SDK key is what identifies the
+    # workspace telemetry is attributed to, so it is the single gate on whether
+    # any collection happens at all (qfg-j001 / qfg-5x9x).
+    def sdk_key?
+      !(@sdk_key.nil? || @sdk_key.to_s.empty?)
+    end
+
     def datadir?
       !@datadir.nil?
     end
@@ -202,6 +213,13 @@ module Quonfig
     #     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+.
+    #   @option options [Boolean] :allow_telemetry_in_local_mode (false)
+    #     @deprecated No-op since 1.3.0 (qfg-5x9x). Telemetry is gated on SDK-key
+    #       presence alone, so datadir mode no longer suppresses it and this flag
+    #       has nothing left to unlock. Still accepted so existing callers keep
+    #       working; slated for removal in 2.0.0. To turn telemetry off, use the
+    #       standard opt-outs (+:collect_evaluation_summaries+ +false+,
+    #       +:context_upload_mode+ +:none+).
     def init(
       api_urls: nil,
       telemetry_url: nil,
@@ -226,6 +244,7 @@ module Quonfig
       context_max_size: DEFAULT_MAX_EVAL_SUMMARIES,
       collect_evaluation_summaries: true,
       collect_max_evaluation_summaries: DEFAULT_MAX_EVAL_SUMMARIES,
+      # Deprecated no-op since 1.3.0 (qfg-5x9x) — see the @option doc above.
       allow_telemetry_in_local_mode: false,
       global_context: {},
       logger_key: nil,
@@ -287,6 +306,7 @@ module Quonfig
       @collect_sync_interval = collect_sync_interval
       @collect_evaluation_summaries = collect_evaluation_summaries
       @collect_max_evaluation_summaries = collect_max_evaluation_summaries
+      # Retained for back-compat only; nothing reads it (qfg-5x9x).
       @allow_telemetry_in_local_mode = allow_telemetry_in_local_mode
       @is_fork = false
       @global_context = global_context
@@ -342,8 +362,21 @@ module Quonfig
       end
     end
 
+    # The telemetry gate: an explicit per-collector opt-out (+option+) AND the
+    # presence of an SDK key. Mode is deliberately NOT part of this decision.
+    #
+    # qfg-5x9x: this used to read
+    #   `option && (!local_only? || @allow_telemetry_in_local_mode)`
+    # which zeroed every collect_max_* the moment a datadir was set, so a
+    # datadir client holding a perfectly valid SDK key built no aggregators and
+    # therefore never constructed a reporter — it emitted nothing at all.
+    # Datadir + SDK key is a supported combination and telemetry has to flow
+    # there like it does in delivery mode. Conversely a keyless client (the
+    # open-source / no-account path) has no workspace to attribute data to, so
+    # nothing is collected and the reporter never starts. Mirrors sdk-node's
+    # `isTelemetryEnabled` and sdk-go's `Options.TelemetryEnabled()`.
     def telemetry_allowed?(option)
-      option && (!local_only? || @allow_telemetry_in_local_mode)
+      option && sdk_key?
     end
 
     def remove_trailing_slash(url)

data/lib/quonfig/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport