quonfig 1.4.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ecc1b6f2a6c327c36d7da4cf091623b8c44b81d6949b887356301961229a684
-  data.tar.gz: bf357130f83dc29baf032c8dd0db652c8910797aac2fc6a499ec3461e5b56ff6
+  metadata.gz: 96d17a74751571b9c6099b8239b2ccaafb25a5f7e55d006cecae5cb1f8651979
+  data.tar.gz: 6bbe54bd07a5fb1e20b987ef8a8aaef417533ca8ef26000873db8a671142d4bb
 SHA512:
-  metadata.gz: '08951e8e2261dce91f0308de7920ea46eef5077979efdd0bd8df55b403719d8fb1f2e7f6ed863a12d38108b30cdef8b92d08832059a68c45b96425a5ced249f6'
-  data.tar.gz: 81738455b310e66693801fe2b2aa3ff027e676b28b032398271d1de17c9421212d5e0c9d3b20c37164a7299c74f2347a52f371abfabc36d8ebca3c75492d17d0
+  metadata.gz: dcb86b3f98c5f986d61f0b0db084b992fe4c3bfefc86ef2f7d0f65487fa95dc6d66fdd4b5150dd2c0f8b6ddd819f6c0bc77980e4ae89d618d31daa3649bc48c6
+  data.tar.gz: 9faba58f93536256b216dd70dc95849adbb1c4e18b033feb9419d87d26dd8b04ec132738f4bfcbee3b0e7dca0b9051bad43971644b3312d0320ee496e8550efc

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.6.0 - 2026-09-28
+
+- **Change: a weighted rollout that hashes on a property missing from the context now hashes an empty value, so every such caller gets the same variant for that flag (qfg-9dxb.8).** Before, such evaluations got a random variant on every call. It is the same variant a context with the property set to `""` gets, and a variant with weight 0 is not served. The reason is still `SPLIT`. The `flag_metadata` of `get_*_details` results includes `'hashPropertyMissing' => true` when the property is missing, and the SDK logs one warning per flag. A weighted rollout with no hash property configured still picks a random variant on every evaluation, unchanged. Users whose context has the property keep the same variant as in 1.5.0.
+- **Change: once the client holds a numbered config generation, a payload with generation 0 is ignored and the client keeps its current config (qfg-9dxb.9).** Only a delivery server with a damaged git store sends one. In 1.5.0 such a payload installed and could move the client back to older config. `held_generation` never goes backward. A client that has never received a real generation (for example one talking to `qfg serve`) still installs every payload.
+- **Fix: a segment or `decryptWith` key that references itself (directly or through a chain) no longer crashes with `SystemStackError` (qfg-9dxb.7).** The looping segment reference evaluates as a missing segment. A `decryptWith` loop raises `DecryptionError`.
+- **Fix: an HTTP 200 or SSE event that is not a config payload (for example `{}` from a proxy) is ignored instead of deleting all configs (qfg-9dxb.3).** Over HTTP the SDK tries the next server.
+
+## 1.5.0 - 2026-09-25
+
+- **Telemetry transport policy (qfg-y8je.8).** The telemetry POST had no timeout of its own (Faraday's defaults, 60s connect + 60s read); it now has a 15s overall deadline (`telemetry_timeout_ms`) and a 5s connect + TLS deadline (`telemetry_connect_timeout_ms`). A failed batch is kept byte-for-byte and resent (never merged with newer data, so the server dedups a resend of a batch that did land). Resends happen no sooner than 30s after a failure and honor `Retry-After` up to 10 min. The retained queue is capped at 5 batches / 2MB / 5 min (oldest dropped). At most one POST is in flight. 401/403/404 disable telemetry for the process with one ERROR; any other 4xx drops that batch with one ERROR. Before this, a failed batch was simply lost.
+- **Oversize batches are dropped on failure.** A single batch larger than the 2MB byte cap (`telemetry_max_retained_bytes`) is POSTed once and, if that POST fails, dropped rather than kept; the drop counts toward the warning below. This fires for Ruby in practice: in a 24h production sample, sdk-ruby was the only SDK sending large batches (p95 874KB, p99 1.73MB, max 5.2MB, all example-context data) and 0.07% of its POSTs were over 2MB. Most of that size came from the old interval (next item), which let a window grow for up to 10 minutes; at 60s batches should be much smaller. To keep batches small regardless, use `context_upload_mode: :shapes_only` or a lower `context_max_size`.
+- **Flush interval is a fixed 60s (`collect_sync_interval`, now explicitly defaulted).** The old default started at 8s and grew by 1.5x on every tick, including successful ones (a bug), reaching the 600s ceiling about 23 minutes after start; the exponential backoff is gone.
+- **Logging (was a WARN on every failed POST):** a failed POST logs at debug; one WARN when data is actually dropped (then a summary at most every 10 min while drops continue); one INFO on recovery.
+- **Shutdown:** `Client#stop` and the reporter's `at_exit` hook send the live window once with a 5s deadline and do not resend kept batches; an in-flight POST is abandoned. Exit is never blocked longer than that.
+- **Memory caps:** the evaluation-summary, context-shape and example-context caps drop from 100,000 to 10,000 per window (`collect_max_evaluation_summaries`, `context_max_size`), the uniform server-SDK cap. The example-context once-per-hour rate-limit map is bounded at 100,000 keys. A summary key already seen keeps counting at the cap.
+- **New options:** `telemetry_timeout_ms`, `telemetry_connect_timeout_ms`, `telemetry_max_retained_batches`, `telemetry_max_retained_bytes`, `telemetry_max_retained_age_ms`. Invalid values (non-numeric or <= 0) fall back to the default.
+- Internal classes: `Quonfig::HttpConnection` gains `open_timeout_ms:` and sends a String body verbatim. `Quonfig::Telemetry::TelemetryReporter` gains `.build`, `tick`, `flush`, `close` and `debug_state`; `sync` and `stop` remain as aliases of `flush` and `close`. New `Quonfig::Telemetry::TransportQueue`.
+- `context_upload_mode` default is unchanged (`:periodic_example`). No wire change, no removed public API, no new dependencies. Fork safety is unchanged: a forked child still builds its own reporter (and its own retained queue) on first use and never sends the parent's data.
+
 ## 1.4.1 - 2026-09-11
 
 - **Fix (fork/telemetry): a forked child now reports under its OWN `instanceHash` (qfg-xcym).** `@instance_hash` was minted once in `Client#initialize` and survived `fork(2)`, so every forked child POSTed its telemetry under the **parent's** hash. The Quonfig Debugger groups SDK last-seen by that hash, so an 8-worker Puma cluster (or a `parallel`-gem batch) collapsed into a single instance row with the parent's and the children's windows interleaved on top of each other. A child now mints a fresh hash as part of the same post-fork rebuild that gives it fresh aggregators and a fresh reporter — before the reporter is constructed, so the hash the child POSTs under is its own. This is parity with Reforge, where a forked process simply builds a whole new client. The parent's hash is never touched, and a child's row count is unchanged (it already reported its own window; it just did so under the wrong identity). Present since 0.0.16.

data/README.md

@@ -2,7 +2,7 @@
 
 Ruby SDK for [Quonfig](https://quonfig.com) — Feature Flags, Live Config, and Dynamic Log Levels.
 
-> **Note:** This SDK is pre-1.0 and the API is not yet stable.
+> **Note:** This SDK is stable (v1) and follows [Semantic Versioning](https://semver.org): breaking changes to the public API land only in a major (`x.0.0`) release.
 
 ## Installation
 
@@ -284,6 +284,16 @@ Quonfig::Client.new(
 | `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. |
+| `collect_evaluation_summaries`      | `Boolean`         | `true`                                                              | Send per-flag evaluation counts. See [Telemetry](#telemetry). |
+| `collect_max_evaluation_summaries`  | `Integer`         | `10_000`                                                            | Distinct flags/configs counted per telemetry window; a key already seen keeps counting at the cap. |
+| `context_upload_mode`               | `Symbol`          | `:periodic_example`                                                 | `:periodic_example` (context shapes + example contexts), `:shapes_only`, or `:none`. |
+| `context_max_size`                  | `Integer`         | `10_000`                                                            | Context-shape fields, and separately example contexts, kept per telemetry window. |
+| `collect_sync_interval`             | `Numeric` (s)     | `60`                                                                | Seconds between telemetry POSTs. |
+| `telemetry_timeout_ms`              | `Integer` (ms)    | `15_000`                                                            | Overall deadline for one telemetry POST. |
+| `telemetry_connect_timeout_ms`      | `Integer` (ms)    | `5_000`                                                             | TCP connect + TLS deadline for one telemetry POST. |
+| `telemetry_max_retained_batches`    | `Integer`         | `5`                                                                 | Failed telemetry batches kept for resend. |
+| `telemetry_max_retained_bytes`      | `Integer`         | `2_097_152`                                                         | Byte cap (2MB) on kept batches; a single batch larger than this is sent once and never kept. |
+| `telemetry_max_retained_age_ms`     | `Integer` (ms)    | `300_000`                                                           | A kept batch older than this is discarded. |
 
 ## Failover & `QUONFIG_DOMAIN`
 
@@ -634,6 +644,58 @@ process.
 
 There is intentionally no `client.healthy?` primitive.
 
+## Telemetry
+
+With an SDK key the client sends usage telemetry to `telemetry_url` so the
+Quonfig dashboard can show which flags and configs are evaluated and with what
+contexts. Telemetry never affects flag evaluation: every failure below is
+contained in the background reporter thread.
+
+**What is sent.** Evaluation summaries (per flag/config: counts per rule and
+value), context shapes (context field names and types), example contexts (up to
+one per context key per hour) and failover counters. Opt out with
+`collect_evaluation_summaries: false` and `context_upload_mode: :shapes_only`
+(no example contexts) or `:none` (no context data). With both off, no reporter
+runs.
+
+**How it is sent.**
+
+- One POST every `collect_sync_interval` seconds (60), with at most one POST in
+  flight. A tick that fires while a POST is still out is skipped and its data
+  rolls into the next window.
+- Each POST has an overall deadline of `telemetry_timeout_ms` (15s) and a
+  connect + TLS deadline of `telemetry_connect_timeout_ms` (5s).
+- When a POST fails (timeout, network error, 408, 429 or 5xx), the serialized
+  batch is kept byte-for-byte and resent unchanged, never merged with newer
+  data, so the server can recognize a resend of a batch that did land. Up to 5
+  batches / 2MB are kept for up to 5 minutes; beyond that the oldest is
+  dropped. A single batch larger than 2MB is sent once and never kept: if that
+  one POST fails, the batch is dropped. Large batches come from example
+  contexts; `context_upload_mode: :shapes_only` or a lower `context_max_size`
+  keeps batches small.
+- Resends happen no sooner than 30s after a failure and after any
+  `Retry-After` (honored up to 10 minutes), oldest first, then the current
+  window.
+- A 401, 403 or 404 means the SDK key or `telemetry_url` is wrong: the SDK logs
+  one error and disables telemetry for the rest of the process. Any other 4xx
+  drops that one batch with an error (the server rejected the payload) and
+  telemetry continues.
+
+**Logging.** A failed POST logs at debug only. The first batch actually dropped
+logs one warning with the last POST result and queue depth; further drops log
+at debug with a summary warning at most every 10 minutes; the first success
+after failures logs one info line. The SDK's default logger prints warnings and
+errors only; pass `logger:` to receive the debug and info lines.
+
+**Shutdown.** `stop` (and the `at_exit` hook the reporter registers) sends the
+current window once with a 5s deadline, does not resend kept batches, and never
+blocks process exit longer than that.
+
+**Memory.** Everything is bounded: at most 10,000 evaluation-summary keys,
+10,000 context-shape fields and 10,000 example contexts per window (keys
+already seen keep counting at the cap), a 100,000-entry example-context
+rate-limit map, and the 2MB retained queue.
+
 ## Documentation
 
 Full documentation, including SPEC, SDK reference, and operational guides, is

data/lib/quonfig/client.rb

@@ -1123,40 +1123,12 @@ module Quonfig
     # The reporter runs on a background thread and periodically POSTs
     # context-shape and example-context batches to +telemetry_destination+.
     def initialize_telemetry(start: true)
-      shape_aggregator = nil
-      example_aggregator = nil
-      summaries_aggregator = nil
-
-      if @options.collect_max_shapes.to_i.positive?
-        shape_aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(
-          max_shapes: @options.collect_max_shapes
-        )
-      end
-
-      if @options.collect_max_example_contexts.to_i.positive?
-        example_aggregator = Quonfig::Telemetry::ExampleContextsAggregator.new(
-          max_contexts: @options.collect_max_example_contexts
-        )
-      end
-
-      if @options.collect_max_evaluation_summaries.to_i.positive?
-        summaries_aggregator = Quonfig::Telemetry::EvaluationSummariesAggregator.new(
-          max_keys: @options.collect_max_evaluation_summaries
-        )
-      end
-
-      return if shape_aggregator.nil? && example_aggregator.nil? && summaries_aggregator.nil?
-
-      @telemetry_reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      @telemetry_reporter = Quonfig::Telemetry::TelemetryReporter.build(
         options: @options,
         instance_hash: @instance_hash,
-        context_shape_aggregator: shape_aggregator,
-        example_contexts_aggregator: example_aggregator,
-        evaluation_summaries_aggregator: summaries_aggregator,
-        failover_aggregator: @failover_aggregator,
-        sync_interval: @options.collect_sync_interval
+        failover_aggregator: @failover_aggregator
       )
-
+      return if @telemetry_reporter.nil?
       return unless @telemetry_reporter.enabled?
       return unless start
 
@@ -1664,13 +1636,15 @@ module Quonfig
       end
 
       reason = result.of_reason
+      flag_metadata = build_flag_metadata(
+        config_id, config_type, result.rule_index, result.weighted_value_index, reason
+      )
+      flag_metadata['hashPropertyMissing'] = true if result.hash_property_missing
       Quonfig::EvaluationDetails.new(
         value: coerced,
         reason: reason,
         variant: build_variant(reason, result.rule_index, result.weighted_value_index),
-        flag_metadata: build_flag_metadata(
-          config_id, config_type, result.rule_index, result.weighted_value_index, reason
-        )
+        flag_metadata: flag_metadata
       )
     rescue StandardError => e
       Quonfig::EvaluationDetails.new(

data/lib/quonfig/config_envelope.rb

@@ -1,5 +1,20 @@
 # frozen_string_literal: true
 
 module Quonfig
-  ConfigEnvelope = Struct.new(:configs, :meta, keyword_init: true)
+  ConfigEnvelope = Struct.new(:configs, :meta, keyword_init: true) do
+    # qfg-9dxb.3: true when a decoded wire payload is a config envelope — a
+    # Hash carrying a +meta+ object with a non-empty +version+. api-delivery and
+    # `qfg serve` always send one; a `{}` or `{"error":"x"}` 200 from a
+    # misbehaving proxy/WAF does not, and must never be installed (it would
+    # read as "zero configs" and wipe every key on an established client).
+    def self.wire_envelope?(data)
+      return false unless data.is_a?(Hash)
+
+      meta = data['meta']
+      return false unless meta.is_a?(Hash)
+
+      version = meta['version']
+      !version.nil? && !version.to_s.empty?
+    end
+  end
 end

data/lib/quonfig/config_loader.rb

@@ -325,7 +325,11 @@ module Quonfig
         envelope = parse_envelope(response.body)
         result = install_envelope(envelope, source: source, source_index: index)
         # Write this leg's ETag back AFTER the response (per-leg, race-free).
-        set_etag_for(index, new_etag)
+        # Exception (qfg-9dxb.9): an ignored gen<=0 payload keeps the previous
+        # ETag. Its ETag is the git sha, and the server may later repair the
+        # generation for the SAME sha; remembering it would 304 that repair.
+        ignored_unversioned = result == :not_modified && extract_generation(envelope.meta || {}) <= 0
+        set_etag_for(index, new_etag) unless ignored_unversioned
         # install_envelope returns :not_modified when the reject-older guard drops
         # an equal/older payload — surface that so the caller doesn't double-count.
         result == :not_modified ? :not_modified : :updated
@@ -339,6 +343,12 @@ module Quonfig
         @logger.info "Config fetch failed: status #{response.status} from #{source}"
         :failed
       end
+    rescue NonEnvelopeError => e
+      # qfg-9dxb.3: a non-envelope 200 is a leg error, NOT an install — the
+      # hedge/failover proceeds and this leg's ETag is never stored (so a junk
+      # 200 cannot pin itself through later 304s).
+      @logger.warn "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg"
+      :failed
     rescue Faraday::ConnectionFailed => e
       @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
       :failed
@@ -355,8 +365,14 @@ module Quonfig
       @etag_mutex.synchronize { @etags[index || 0] = value }
     end
 
+    # Raised by #parse_envelope for a 200 whose body is not a config envelope
+    # (qfg-9dxb.3). Caught in #fetch_from as a leg error.
+    class NonEnvelopeError < StandardError; end
+
     def parse_envelope(body)
       data = body.is_a?(String) ? JSON.parse(body) : body
+      raise NonEnvelopeError, 'missing meta.version' unless Quonfig::ConfigEnvelope.wire_envelope?(data)
+
       Quonfig::ConfigEnvelope.new(
         configs: data['configs'] || [],
         meta: data['meta'] || {}
@@ -375,23 +391,37 @@ module Quonfig
       incoming_gen = extract_generation(meta)
 
       @install_mutex.synchronize do
-        # Reject-older install guard (canonical ordering, §5f). A fresh client
-        # (no held generation) seeds off whatever arrives first — even an older
-        # or gen-0 snapshot. An established client installs ONLY when the incoming
-        # generation strictly advances the held one: a same-generation snapshot is
-        # a no-op (no store churn, no install-count bump, no resolved-from change)
-        # so a duplicate leg never flaps an established client, and an OLDER
-        # snapshot (a stale secondary reached on failover) is dropped so the client
-        # never regresses. Reject-older is the whole rule — no source ranking; a
-        # newer primary landing late heals forward automatically. Applies on every
-        # network install path (initial fetch, failover/poll fetch, SSE snapshot,
-        # SSE update, fallback poller); datadir install bypasses this (it is the
-        # local source of truth and goes through Client#apply_datadir_envelope).
-        # Carve-out: an UNVERSIONED snapshot (generation <= 0 — a server that
-        # predates the watermark, or one whose rev-count failed) carries no
-        # ordering info, so it is never rejected as "older"; freezing the client
-        # on stale config would be worse (mirrors sdk-node).
-        unless @held_generation.nil? || incoming_gen <= 0 || incoming_gen > @held_generation
+        # Reject-older install guard (canonical ordering, §5f; mirrors sdk-go
+        # shouldInstall). The rule:
+        #   - fresh client (nothing installed yet)  -> install, whatever arrives
+        #   - incoming generation <= 0 (unversioned) -> install ONLY if the held
+        #     generation is 0 (the client has never held a real generation)
+        #   - otherwise -> install iff incoming strictly exceeds held
+        # A same-generation snapshot is a no-op (no store churn, no install-count
+        # bump, no resolved-from change) so a duplicate leg never flaps an
+        # established client, and an OLDER snapshot (a stale secondary reached on
+        # failover) is dropped so the client never regresses. Reject-older is the
+        # whole rule — no source ranking; a newer primary landing late heals
+        # forward automatically. Applies on every network install path (initial
+        # fetch, failover/poll fetch, SSE snapshot, SSE update, fallback poller);
+        # datadir install bypasses this (it is the local source of truth and goes
+        # through Client#apply_datadir_envelope).
+        #
+        # Unversioned payloads (qfg-9dxb.9): the pre-watermark servers that sent
+        # gen 0 on every payload are long gone. Today gen 0 comes only from a
+        # server whose git store is damaged (rev-count failed) — the least
+        # trustworthy source — so it must not override a held real generation.
+        # A client that has only ever seen gen 0 (e.g. `qfg serve`) keeps
+        # installing each gen 0 payload.
+        unless should_install?(incoming_gen)
+          if incoming_gen <= 0
+            # Unversioned payload while a real generation is held: not provably
+            # older (it carries no ordering info), so a silent no-op — NOT
+            # counted as guardRejected.
+            @logger.debug "Unversioned payload ignored: held generation #{@held_generation} (source=#{source})"
+            return :not_modified
+          end
+
           if incoming_gen < @held_generation
             @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} < held #{@held_generation} (source=#{source})"
             # Failover observability (qfg-41nh.18): count the guard rejection.
@@ -431,7 +461,11 @@ module Quonfig
         @version = meta['version'] || meta[:version] || @version
         @environment_id = meta['environment'] || meta[:environment] || @environment_id
 
-        @held_generation = incoming_gen
+        # qfg-9dxb.3 Fix A: an unversioned install (generation <= 0) carries no
+        # ordering info and must never LOWER a positive held generation. Under
+        # the qfg-9dxb.9 rule it only installs when held is nil/0 anyway, so
+        # this keeps held at 0 there; a fresh client seeds off it as usual.
+        @held_generation = incoming_gen if @held_generation.nil? || incoming_gen.positive?
         @install_count += 1
         @resolved_from_index = source_index unless source_index.nil?
         # Failover observability (qfg-41nh.18): record which leg served this
@@ -457,6 +491,14 @@ module Quonfig
       end
     end
 
+    # The install decision for a network payload (see #install_envelope).
+    def should_install?(incoming_gen)
+      return true if @held_generation.nil?
+      return @held_generation.zero? if incoming_gen <= 0
+
+      incoming_gen > @held_generation
+    end
+
     # Read Meta.generation (qfg-7h5d.1.1) — the monotonic per-branch commit
     # counter the backend stamps on every envelope. Absent/garbage → 0 (an old
     # backend that doesn't emit it, or fixture mode with no FIXTURE_GENERATION).

data/lib/quonfig/evaluator.rb

@@ -131,10 +131,15 @@ module Quonfig
 
     # --- Rule evaluation ------------------------------------------------
 
-    def evaluate_rules(rules, context, config)
+    # +seg_path+ holds the keys of the configs being evaluated above this one
+    # through IN_SEG / NOT_IN_SEG, so segment resolution can detect a
+    # reference cycle instead of recursing until SystemStackError
+    # (qfg-9dxb.7). It is a path, not a global visited set, so a diamond (two
+    # segments that both reference a third) still resolves.
+    def evaluate_rules(rules, context, config, seg_path = [])
       rules.each_with_index do |rule, index|
         criteria = Array(hget(rule, :criteria) || [])
-        next unless all_criteria_match?(criteria, context, config)
+        next unless all_criteria_match?(criteria, context, config, seg_path)
 
         value_hash = hget(rule, :value)
         return EvalResult.new(value: value_hash, rule_index: index, config: config)
@@ -142,8 +147,8 @@ module Quonfig
       nil
     end
 
-    def all_criteria_match?(criteria, context, config)
-      criteria.all? { |c| evaluate_criterion(c, context, config) }
+    def all_criteria_match?(criteria, context, config, seg_path)
+      criteria.all? { |c| evaluate_criterion(c, context, config, seg_path) }
     end
 
     # --- Per-operator evaluation ---------------------------------------
@@ -151,7 +156,7 @@ module Quonfig
     # Faithful port of sdk-node/src/operators.ts evaluateCriterion. Matches
     # context-exists / missing-context semantics (e.g. PROP_IS_NOT_ONE_OF is
     # true when context is missing).
-    def evaluate_criterion(criterion, context, _config)
+    def evaluate_criterion(criterion, context, config, seg_path)
       property_name = hget(criterion, :propertyName) || ''
       operator = hget(criterion, :operator)
       match_value = hget(criterion, :valueToMatch)
@@ -296,7 +301,7 @@ module Quonfig
       when OP_IN_SEG, OP_NOT_IN_SEG
         if match_value
           segment_key = to_s_nil(hget(match_value, :value))
-          found, result = resolve_segment(segment_key, context)
+          found, result = resolve_segment(segment_key, context, config, seg_path)
           return operator == OP_NOT_IN_SEG unless found
 
           return result == (operator == OP_IN_SEG)
@@ -319,16 +324,22 @@ module Quonfig
 
     # --- Segment resolution -------------------------------------------
 
-    def resolve_segment(segment_key, context)
+    def resolve_segment(segment_key, context, config, seg_path)
       return [false, false] if segment_key.nil? || segment_key.empty?
 
+      # A reference back onto the current evaluation path is a cycle. Treat
+      # it like a missing segment (IN_SEG false, NOT_IN_SEG true), matching
+      # sdk-go (qfg-9dxb.4).
+      current_key = hget(config, :key).to_s
+      return [false, false] if segment_key == current_key || seg_path.include?(segment_key)
+
       seg_config = @store.get(segment_key)
       return [false, false] if seg_config.nil?
 
       # Segments have no environment-specific rules in the JSON shape; we
       # evaluate against default rules only (mirrors sdk-node behaviour —
       # evaluate_config with env_id='' falls through to default).
-      match = evaluate_rules(default_rules_of(seg_config), context, seg_config)
+      match = evaluate_rules(default_rules_of(seg_config), context, seg_config, seg_path + [current_key])
       return [false, false] if match.nil?
 
       raw = match.raw_value
@@ -424,14 +435,18 @@ module Quonfig
     REASON_TARGETING_MATCH  = 2
     REASON_SPLIT            = 3
 
-    attr_reader :value, :rule_index, :config, :reportable_value
+    attr_reader :value, :rule_index, :config, :reportable_value, :hash_property_missing
     attr_accessor :weighted_value_index
 
-    def initialize(value:, rule_index:, config:, weighted_value_index: nil, reportable_value: nil)
+    def initialize(value:, rule_index:, config:, weighted_value_index: nil, reportable_value: nil,
+                   hash_property_missing: false)
       @value = value
       @rule_index = rule_index
       @config = config
       @weighted_value_index = weighted_value_index
+      # True when a weighted rollout's hash property was missing from the
+      # context and an empty value was hashed instead (qfg-9dxb.8).
+      @hash_property_missing = hash_property_missing
       # Telemetry-safe substitute for #unwrapped_value. Set by Resolver when
       # the underlying Value was confidential / decryptWith, so callers
       # (the eval-summary aggregator) never see the plaintext. Mirrors

data/lib/quonfig/http_connection.rb

@@ -34,10 +34,16 @@ module Quonfig
     # Options#config_fetch_timeout_ms (sequential) or the hedge abort (hedged
     # legs) so a hung OR drip-feeding upstream aborts fast instead of blocking
     # the caller's whole init budget.
-    def initialize(uri, sdk_key, timeout_ms: nil)
+    #
+    # +open_timeout_ms+ (qfg-y8je.8): a separate, usually shorter, bound on the
+    # connect (open) phase — TCP connect plus TLS handshake. nil uses
+    # +timeout_ms+ for it, as before. The telemetry reporter passes 5s here and
+    # 15s as +timeout_ms+.
+    def initialize(uri, sdk_key, timeout_ms: nil, open_timeout_ms: nil)
       @uri = uri
       @sdk_key = sdk_key
       @timeout_ms = timeout_ms
+      @open_timeout_ms = open_timeout_ms
     end
 
     attr_reader :uri
@@ -46,8 +52,11 @@ module Quonfig
       with_wall_clock_deadline { connection(headers).get(path) }
     end
 
+    # A String +body+ is sent verbatim (the telemetry reporter resends a
+    # retained batch byte-for-byte); anything else is serialized as JSON.
     def post(path, body)
-      with_wall_clock_deadline { connection.post(path, body.to_json) }
+      payload = body.is_a?(String) ? body : body.to_json
+      with_wall_clock_deadline { connection.post(path, payload) }
     end
 
     def connection(headers = {})
@@ -63,6 +72,7 @@ module Quonfig
           conn.options.open_timeout = seconds
           conn.options.timeout = seconds
         end
+        conn.options.open_timeout = @open_timeout_ms / 1000.0 if @open_timeout_ms
       end
     end
 

data/lib/quonfig/options.rb

@@ -8,7 +8,9 @@ module Quonfig
     attr_reader :sdk_key, :environment, :api_urls, :sse_api_urls, :telemetry_destination, :config_api_urls,
                 :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, :config_fetch_timeout_ms,
-                :config_fetch_hedge_delay_ms, :config_fetch_hedge_abort_ms, :api_urls_explicit
+                :config_fetch_hedge_delay_ms, :config_fetch_hedge_abort_ms, :api_urls_explicit,
+                :telemetry_timeout_ms, :telemetry_connect_timeout_ms, :telemetry_max_retained_batches,
+                :telemetry_max_retained_bytes, :telemetry_max_retained_age_ms
     attr_accessor :is_fork
 
     # Default fallback poll interval, in milliseconds. The SDK polls api-delivery
@@ -85,9 +87,28 @@ module Quonfig
     end
 
     DEFAULT_MAX_PATHS = 1_000
-    DEFAULT_MAX_KEYS = 100_000
-    DEFAULT_MAX_EXAMPLE_CONTEXTS = 100_000
-    DEFAULT_MAX_EVAL_SUMMARIES = 100_000
+    # Telemetry aggregator caps per flush window (P6 of the telemetry transport
+    # policy, qfg-y8je.8): the uniform server-SDK cap. Were 100,000 before 1.5.0.
+    DEFAULT_MAX_KEYS = 10_000
+    DEFAULT_MAX_EXAMPLE_CONTEXTS = 10_000
+    DEFAULT_MAX_EVAL_SUMMARIES = 10_000
+
+    # Telemetry transport defaults (qfg-y8je.8; policy P1-P5 in
+    # project/plans/2026-09-24-sdk-telemetry-transport-policy.md).
+    # Seconds between telemetry POSTs (a fixed cadence; was an 8s interval
+    # that grew to 600s).
+    DEFAULT_COLLECT_SYNC_INTERVAL = 60
+    # Overall deadline for one telemetry POST.
+    DEFAULT_TELEMETRY_TIMEOUT_MS = 15_000
+    # TCP connect + TLS deadline for one telemetry POST.
+    DEFAULT_TELEMETRY_CONNECT_TIMEOUT_MS = 5_000
+    # Failed batches kept for resend: at most this many...
+    DEFAULT_TELEMETRY_MAX_RETAINED_BATCHES = 5
+    # ...and at most this many serialized bytes (2MB); a single batch larger
+    # than this is POSTed once and never kept.
+    DEFAULT_TELEMETRY_MAX_RETAINED_BYTES = 2 * 1024 * 1024
+    # A kept batch older than this is discarded.
+    DEFAULT_TELEMETRY_MAX_RETAINED_AGE_MS = 300_000
 
     # Hardcoded fallback domain. Overridden by ENV['QUONFIG_DOMAIN'].
     DEFAULT_DOMAIN = 'quonfig.com'
@@ -213,6 +234,22 @@ 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 [Numeric] :collect_sync_interval (60)
+    #     Seconds between telemetry POSTs, on a fixed cadence. At most one POST
+    #     is in flight; a tick that fires while one is out is skipped and its
+    #     data rolls into the next window.
+    #   @option options [Integer] :telemetry_timeout_ms (15000)
+    #     Overall deadline for one telemetry POST.
+    #   @option options [Integer] :telemetry_connect_timeout_ms (5000)
+    #     TCP connect + TLS deadline for one telemetry POST.
+    #   @option options [Integer] :telemetry_max_retained_batches (5)
+    #     Failed batches kept (byte-for-byte) for resend; the oldest is dropped
+    #     beyond this.
+    #   @option options [Integer] :telemetry_max_retained_bytes (2097152)
+    #     Byte cap on kept batches. A single batch larger than this is POSTed
+    #     once and dropped if that POST fails.
+    #   @option options [Integer] :telemetry_max_retained_age_ms (300000)
+    #     A kept batch older than this is discarded.
     #   @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
@@ -240,6 +277,11 @@ module Quonfig
       config_fetch_hedge_abort_ms: nil,
       collect_max_paths: DEFAULT_MAX_PATHS,
       collect_sync_interval: nil,
+      telemetry_timeout_ms: nil,
+      telemetry_connect_timeout_ms: nil,
+      telemetry_max_retained_batches: nil,
+      telemetry_max_retained_bytes: nil,
+      telemetry_max_retained_age_ms: nil,
       context_upload_mode: :periodic_example, # :periodic_example, :shapes_only, :none
       context_max_size: DEFAULT_MAX_EVAL_SUMMARIES,
       collect_evaluation_summaries: true,
@@ -303,7 +345,15 @@ module Quonfig
       @config_fetch_hedge_abort_ms = config_fetch_hedge_abort_ms || DEFAULT_CONFIG_FETCH_HEDGE_ABORT_MS
 
       @collect_max_paths = collect_max_paths
-      @collect_sync_interval = collect_sync_interval
+      @collect_sync_interval = collect_sync_interval.nil? ? DEFAULT_COLLECT_SYNC_INTERVAL : collect_sync_interval
+      # Telemetry transport (qfg-y8je.8). nil, non-numeric or <= 0 -> default.
+      @telemetry_timeout_ms = positive_or(telemetry_timeout_ms, DEFAULT_TELEMETRY_TIMEOUT_MS)
+      @telemetry_connect_timeout_ms = positive_or(telemetry_connect_timeout_ms, DEFAULT_TELEMETRY_CONNECT_TIMEOUT_MS)
+      @telemetry_max_retained_batches = positive_or(telemetry_max_retained_batches,
+                                                    DEFAULT_TELEMETRY_MAX_RETAINED_BATCHES)
+      @telemetry_max_retained_bytes = positive_or(telemetry_max_retained_bytes, DEFAULT_TELEMETRY_MAX_RETAINED_BYTES)
+      @telemetry_max_retained_age_ms = positive_or(telemetry_max_retained_age_ms,
+                                                   DEFAULT_TELEMETRY_MAX_RETAINED_AGE_MS)
       @collect_evaluation_summaries = collect_evaluation_summaries
       @collect_max_evaluation_summaries = collect_max_evaluation_summaries
       # Retained for back-compat only; nothing reads it (qfg-5x9x).
@@ -379,6 +429,10 @@ module Quonfig
       option && sdk_key?
     end
 
+    def positive_or(value, default)
+      value.is_a?(Numeric) && value.positive? && value.finite? ? value : default
+    end
+
     def remove_trailing_slash(url)
       url.end_with?('/') ? url[0..-2] : url
     end