quonfig 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ecc1b6f2a6c327c36d7da4cf091623b8c44b81d6949b887356301961229a684
-  data.tar.gz: bf357130f83dc29baf032c8dd0db652c8910797aac2fc6a499ec3461e5b56ff6
+  metadata.gz: 5be29a29cae00eb43e09f2aadef25191ec4dc9959ff0037cdfd7ba89dfbd5a10
+  data.tar.gz: b47703c3beb5a4f85f6b2237b3e4295e8e82055ab105168827e750dbd428d13e
 SHA512:
-  metadata.gz: '08951e8e2261dce91f0308de7920ea46eef5077979efdd0bd8df55b403719d8fb1f2e7f6ed863a12d38108b30cdef8b92d08832059a68c45b96425a5ced249f6'
-  data.tar.gz: 81738455b310e66693801fe2b2aa3ff027e676b28b032398271d1de17c9421212d5e0c9d3b20c37164a7299c74f2347a52f371abfabc36d8ebca3c75492d17d0
+  metadata.gz: 7616048fcd0a2a0727ac79a0a801f35d71be44cd54667dc4aaa8aa86009033194f20abbfb69f0b959dc5ba90cdf3e29069db1384e8a432caafe34898f69e3165
+  data.tar.gz: 31d412725f88752b8cbde55daa05c99b926212c2951519a177c24dae72b19d665b3452f4f723e5b2b7e78258cdb37e064733e18249316f7b055846408d2eda92

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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
 

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

data/lib/quonfig/telemetry/example_contexts_aggregator.rb

@@ -10,11 +10,16 @@ module Quonfig
     # matching sdk-node and sdk-go. This is NOT the old Prefab protobuf.
     class ExampleContextsAggregator
       ONE_HOUR_SECONDS = 60 * 60
+      # Bound on the once-per-hour rate-limit map (P6 of the telemetry
+      # transport policy, qfg-y8je.8): a new key arriving when it is full
+      # prunes expired entries, and is not recorded if it is still full.
+      SEEN_CAP = 100_000
 
       attr_reader :data, :cache
 
-      def initialize(max_contexts:, rate_limit_seconds: ONE_HOUR_SECONDS)
+      def initialize(max_contexts:, rate_limit_seconds: ONE_HOUR_SECONDS, seen_cap: SEEN_CAP)
         @max_contexts = max_contexts
+        @seen_cap = seen_cap
         @data = Concurrent::Array.new
         @cache = Quonfig::RateLimitCache.new(rate_limit_seconds)
       end
@@ -30,6 +35,7 @@ module Quonfig
         return if key.nil? || key.empty?
 
         return unless @data.size < @max_contexts && !@cache.fresh?(key)
+        return unless room_in_cache?
 
         @cache.set(key)
         @data.push([Quonfig::TimeHelpers.now_in_ms, context])
@@ -59,6 +65,13 @@ module Quonfig
 
       private
 
+      def room_in_cache?
+        return true if @cache.data.size < @seen_cap
+
+        @cache.prune
+        @cache.data.size < @seen_cap
+      end
+
       def grouped_key_for(context)
         return context.grouped_key if context.respond_to?(:grouped_key)
 

data/lib/quonfig/telemetry/telemetry_reporter.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Quonfig
   module Telemetry
-    # Owns the background thread that periodically drains the context
-    # aggregators and POSTs a JSON telemetry batch to
-    # +<telemetry_destination>/api/v1/telemetry/+.
+    # Owns the background thread that drains the aggregators once per tick and
+    # hands the serialized window to a TransportQueue, which retains failed
+    # batches byte-for-byte and resends them under the telemetry transport
+    # policy (qfg-y8je.8: 60s ticks, one POST in flight, 15s timeout / 5s
+    # connect, 30s floor after a failure, Retry-After up to 10 min,
+    # 5 batches / 2MB / 5 min retention, disable on 401/403/404; see
+    # TransportQueue).
     #
     # Wire shape matches api-telemetry's TelemetryEventsSchema:
     #
@@ -24,16 +30,47 @@ module Quonfig
     class TelemetryReporter
       LOG = Quonfig::InternalLogger.new(self)
 
-      DEFAULT_INITIAL_DELAY_SECONDS = 8
-      DEFAULT_MAX_DELAY_SECONDS = 600
+      TELEMETRY_PATH = '/api/v1/telemetry/'
+      BODY_SNIPPET_BYTES = 1024
+      private_constant :BODY_SNIPPET_BYTES
+
+      # Build the aggregators the options enable and a reporter over them, or
+      # nil when every collector is off. Client#initialize_telemetry uses this;
+      # +clock+ is a test seam (defaults to the monotonic clock).
+      def self.build(options:, instance_hash:, failover_aggregator: nil, clock: nil)
+        shapes = (ContextShapeAggregator.new(max_shapes: options.collect_max_shapes) if options.collect_max_shapes.to_i.positive?)
+        examples = (ExampleContextsAggregator.new(max_contexts: options.collect_max_example_contexts) if options.collect_max_example_contexts.to_i.positive?)
+        summaries = (EvaluationSummariesAggregator.new(max_keys: options.collect_max_evaluation_summaries) if options.collect_max_evaluation_summaries.to_i.positive?)
+        return nil if shapes.nil? && examples.nil? && summaries.nil?
+
+        new(
+          options: options,
+          instance_hash: instance_hash,
+          context_shape_aggregator: shapes,
+          example_contexts_aggregator: examples,
+          evaluation_summaries_aggregator: summaries,
+          failover_aggregator: failover_aggregator,
+          clock: clock
+        )
+      end
+
+      # Resolved transport settings (the +telemetry_*+ options and
+      # +collect_sync_interval+). +flush_interval_ms+ is nil when the interval
+      # is a callable.
+      attr_reader :config
 
+      # +sync_interval+ (seconds, or a callable returning seconds) defaults to
+      # +options.collect_sync_interval+ (60). +http_connection+ is a test seam:
+      # anything answering +post(path, body_string)+ with a response that has
+      # +status+.
       def initialize(options:, instance_hash:,
                      context_shape_aggregator: nil,
                      example_contexts_aggregator: nil,
                      evaluation_summaries_aggregator: nil,
                      failover_aggregator: nil,
                      sync_interval: nil,
-                     http_connection: nil)
+                     http_connection: nil,
+                     clock: nil)
         @options = options
         @instance_hash = instance_hash
         @sdk_key = options.sdk_key
@@ -47,8 +84,31 @@ module Quonfig
         # aggregator at the failover call sites; the reporter only drains it.
         @failover_aggregator = failover_aggregator
         @http_connection = http_connection
-        @sync_interval = calculate_sync_interval(sync_interval)
-        @stopped = Concurrent::AtomicBoolean.new(false)
+        @sync_interval = sync_interval.nil? ? options.collect_sync_interval : sync_interval
+        @config = {
+          flush_interval_ms: @sync_interval.is_a?(Numeric) ? (@sync_interval * 1000).to_i : nil,
+          timeout_ms: options.telemetry_timeout_ms,
+          connect_timeout_ms: options.telemetry_connect_timeout_ms,
+          max_retained_batches: options.telemetry_max_retained_batches,
+          max_retained_bytes: options.telemetry_max_retained_bytes,
+          max_retained_age_ms: options.telemetry_max_retained_age_ms
+        }.freeze
+        @queue = TransportQueue.new(
+          sender: method(:post_batch),
+          telemetry_url: "#{@telemetry_destination}#{TELEMETRY_PATH}",
+          timeout_ms: @config[:timeout_ms],
+          max_retained_batches: @config[:max_retained_batches],
+          max_retained_bytes: @config[:max_retained_bytes],
+          max_retained_age_ms: @config[:max_retained_age_ms],
+          clock: clock || MonotonicClock,
+          on_disabled: method(:on_disabled)
+        )
+        # Held for a whole tick (serialize + drain), so at most one POST is in
+        # flight (P2); a tick that finds it held is skipped.
+        @tick_mutex = Mutex.new
+        @state_mutex = Mutex.new
+        @wake = ConditionVariable.new
+        @closed = false
         @thread = nil
         @at_exit_registered = false
         # Set on #start. Everything that can EMIT is gated on it so a forked
@@ -69,97 +129,104 @@ module Quonfig
       # summaries are recorded separately via
       # +record_evaluation(...)+ since they require the evaluation result.
       def record(context)
-        return if context.nil?
+        return if context.nil? || @queue.disabled?
 
         @context_shape_aggregator&.push(context)
         @example_contexts_aggregator&.record(context)
       end
 
       def record_evaluation(**kwargs)
+        return if @queue.disabled?
+
         @evaluation_summaries_aggregator&.record(**kwargs)
       end
 
       def start
         return if @thread&.alive?
         return unless enabled?
+        return if @closed || @queue.disabled?
 
         # Claim ownership for THIS process. fork(2) copies the reporter, its
         # aggregators, and the process-wide at_exit closure registered below;
         # the pid recorded here is what lets the copy know it is not the
         # owner and must stay silent (qfg-lv4n.1, dd-trace-rb's pattern).
         @owner_pid = Process.pid
-        @stopped.make_false
         register_at_exit_handler
         @thread = Thread.new do
           Thread.current.name = 'quonfig-telemetry-reporter'
           LOG.debug "Telemetry reporter started instance_hash=#{@instance_hash} destination=#{@telemetry_destination}"
-
-          until @stopped.true?
-            begin
-              sleep_duration = @sync_interval.call
-              slept = 0.0
-              step = 0.5
-              while slept < sleep_duration && !@stopped.true?
-                sleep([step, sleep_duration - slept].min)
-                slept += step
-              end
-              break if @stopped.true?
-
-              sync
-            rescue StandardError => e
-              LOG.warn "[quonfig] Telemetry reporter error: #{e.class}: #{e.message}"
-            end
-          end
+          run_loop
         end
       end
 
-      def stop
-        return if foreign_process?('stop')
+      # One tick of the contract's model: skip if closed, disabled or a POST is
+      # in flight (P2; the live window keeps aggregating); expire aged batches;
+      # skip if the 30s floor or Retry-After has not elapsed; serialize the
+      # live window once and append it; drain oldest-first.
+      def tick
+        return if foreign_process?('tick')
+        return unless @tick_mutex.try_lock
 
-        @stopped.make_true
-        thread = @thread
-        @thread = nil
-        thread&.wakeup if thread&.alive?
-        # Final drain attempt on stop so tests / short-lived processes
-        # don't silently drop pending telemetry.
         begin
-          sync
-        rescue StandardError => e
-          LOG.debug "[quonfig] Final telemetry sync failed: #{e.class}: #{e.message}"
+          run_tick
+        ensure
+          @tick_mutex.unlock
         end
       end
 
-      # Drain all aggregators and POST the batch. Public so tests can
-      # trigger a sync without waiting for the background loop.
+      # Send the live window now. Waits for an in-flight POST first (bounded by
+      # the request timeout), then runs a tick, so after a failure it respects
+      # the 30s floor and Retry-After. Never raises.
       #
       # Silent in any process other than the one that started the reporter:
       # after a fork the child holds a full copy of the PARENT's un-flushed
       # window, and the parent is still going to flush it itself.
-      def sync
+      def flush
         return if foreign_process?('sync')
 
-        events = []
-        if (summaries_event = @evaluation_summaries_aggregator&.drain_event)
-          events << summaries_event
-        end
-        if (shape_event = @context_shape_aggregator&.drain_event)
-          events << shape_event
-        end
-        if (example_event = @example_contexts_aggregator&.drain_event)
-          events << example_event
-        end
-        if (failover_event = @failover_aggregator&.drain_event)
-          events << failover_event
+        @tick_mutex.synchronize { run_tick }
+      rescue StandardError => e
+        LOG.debug "Telemetry flush failed: #{e.class}: #{e.message}"
+      end
+      alias sync flush
+
+      # Shutdown (P8): stop the reporter thread (aborting an in-flight POST),
+      # then give the live window one POST with a 5s deadline. The retained
+      # queue is not drained. Idempotent; never raises; never blocks exit for
+      # longer than that deadline.
+      def close
+        return if foreign_process?('close')
+
+        thread = @state_mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          current = @thread
+          @thread = nil
+          current
         end
+        stop_thread(thread)
+        return if @queue.disabled?
 
-        return if events.empty?
+        body = serialize_window
+        return if body.nil?
 
-        payload = {
-          'instanceHash' => @instance_hash,
-          'events' => events
+        @queue.send_final(body, [TransportQueue::SHUTDOWN_FLUSH_DEADLINE_MS, @config[:timeout_ms]].min)
+      rescue StandardError => e
+        LOG.debug "Telemetry close failed: #{e.class}: #{e.message}"
+      end
+      alias stop close
+
+      # Test-visible state (the contract's retained_count / retained_bytes /
+      # telemetry_enabled).
+      def debug_state
+        {
+          retained_count: @queue.retained_count,
+          retained_bytes: @queue.retained_bytes,
+          enabled: !@queue.disabled?,
+          in_flight: @queue.in_flight?,
+          thread_alive: @thread&.alive? || false
         }
-
-        post(payload)
       end
 
       # Visible for tests.
@@ -180,7 +247,7 @@ module Quonfig
       # not exist in the child, and the HTTP connection's fd is shared with
       # the parent.
       def discard_inherited!
-        @stopped.make_true
+        @closed = true
         @thread = nil
         @context_shape_aggregator = nil
         @example_contexts_aggregator = nil
@@ -190,6 +257,106 @@ module Quonfig
 
       private
 
+      def run_tick
+        return if @closed || @queue.disabled?
+
+        @queue.expire
+        return unless @queue.send_allowed?
+
+        body = serialize_window
+        @queue.append(body) if body
+        @queue.drain
+      end
+
+      # Fixed cadence: tick k fires at k * interval regardless of how long a
+      # drain takes. The interval never grows (the old exponential backoff,
+      # which grew even on success, is gone: P4).
+      def run_loop
+        next_at = MonotonicClock.now_ms + next_interval_ms
+        until loop_done?
+          wait_ms = next_at - MonotonicClock.now_ms
+          if wait_ms.positive?
+            @state_mutex.synchronize { @wake.wait(@state_mutex, wait_ms / 1000.0) unless loop_done? }
+            next
+          end
+          next_at += next_interval_ms
+          next_at = MonotonicClock.now_ms + next_interval_ms if next_at <= MonotonicClock.now_ms
+          begin
+            tick
+          rescue StandardError => e
+            LOG.debug "Telemetry tick failed: #{e.class}: #{e.message}"
+          end
+        end
+      end
+
+      def loop_done?
+        @closed || @queue.disabled?
+      end
+
+      def next_interval_ms
+        seconds = @sync_interval.respond_to?(:call) ? @sync_interval.call : @sync_interval
+        [(seconds.to_f * 1000).to_i, 1].max
+      end
+
+      def wake_thread
+        @state_mutex.synchronize { @wake.broadcast }
+      end
+
+      # Stop the reporter thread. A thread parked in its wait exits on the
+      # broadcast; one still busy (a POST in flight) is killed, which aborts
+      # the POST like sdk-node's close() does. The aborted batch is never resent.
+      def stop_thread(thread)
+        return if thread.nil? || thread == Thread.current || !thread.alive?
+
+        wake_thread
+        thread.kill unless thread.join(0.1)
+      end
+
+      def on_disabled
+        # Nothing aggregates for a dead endpoint: drop what the window holds.
+        serialize_window
+        wake_thread
+      end
+
+      # Drain the aggregators into one serialized payload. This is the only
+      # serialization: the queue stores and resends these exact bytes (P5, P9).
+      def serialize_window
+        events = [
+          @evaluation_summaries_aggregator&.drain_event,
+          @context_shape_aggregator&.drain_event,
+          @example_contexts_aggregator&.drain_event,
+          # nil unless the window saw failover activity.
+          @failover_aggregator&.drain_event
+        ].compact
+        return nil if events.empty?
+
+        JSON.generate('instanceHash' => @instance_hash, 'events' => events)
+      end
+
+      # The TransportQueue sender: one POST of +body+ verbatim.
+      def post_batch(body, timeout_ms)
+        response = telemetry_connection(timeout_ms).post(TELEMETRY_PATH, body)
+        headers = response.respond_to?(:headers) ? response.headers : nil
+        snippet = response.respond_to?(:body) ? response.body.to_s.byteslice(0, BODY_SNIPPET_BYTES) : ''
+        TransportQueue::Result.new(
+          status: response.status.to_i,
+          retry_after: headers && headers['retry-after'],
+          body_snippet: snippet
+        )
+      end
+
+      # A connection bounded by +timeout_ms+ overall and the connect timeout
+      # (never longer than +timeout_ms+) for TCP connect + TLS (P1).
+      def telemetry_connection(timeout_ms)
+        return @http_connection if @http_connection
+
+        Quonfig::HttpConnection.new(
+          @telemetry_destination, @sdk_key,
+          timeout_ms: timeout_ms,
+          open_timeout_ms: [@config[:connect_timeout_ms], timeout_ms].min
+        )
+      end
+
       # True when this reporter belongs to a different process — i.e. we are
       # a fork(2) copy. Never true before #start (nothing has been claimed,
       # and nothing was registered at_exit either).
@@ -204,7 +371,7 @@ module Quonfig
 
       # Rails / Passenger / Puma workers often terminate via SIGTERM without
       # a chance to call Client#stop. Register a Kernel.at_exit hook on
-      # first start so the in-flight batch still gets flushed.
+      # first start so the live window still gets its one final flush.
       def register_at_exit_handler
         return if @at_exit_registered
 
@@ -212,62 +379,11 @@ module Quonfig
         @at_exit_registered = true
       end
 
-      # Wait this long for the background reporter thread to exit before
-      # giving up. Bounded so a thread blocked on a dead telemetry endpoint
-      # can't hang process exit.
-      AT_EXIT_THREAD_JOIN_TIMEOUT_SECONDS = 1.0
-      private_constant :AT_EXIT_THREAD_JOIN_TIMEOUT_SECONDS
-
-      # Idempotent final drain. Safe to call after #stop has already
-      # drained: aggregators return nil when empty and #sync becomes a
-      # no-op. Bounded so a stuck reporter thread or dead telemetry
+      # Idempotent final flush (#close). Safe after #stop: a second close is a
+      # no-op. Bounded by the 5s shutdown deadline, so a dead telemetry
       # endpoint can't hang process exit.
       def final_drain_on_exit
-        return if foreign_process?('at_exit drain')
-
-        @stopped.make_true
-        thread = @thread
-        @thread = nil
-        if thread&.alive?
-          thread.wakeup
-          thread.join(AT_EXIT_THREAD_JOIN_TIMEOUT_SECONDS)
-        end
-        sync
-      rescue StandardError => e
-        LOG.debug "[quonfig] at_exit telemetry drain failed: #{e.class}: #{e.message}"
-      end
-
-      def post(payload)
-        conn = http_connection
-        return if conn.nil?
-
-        response = conn.post('/api/v1/telemetry/', payload)
-        status = response.respond_to?(:status) ? response.status : nil
-        if status && status >= 400
-          LOG.warn "[quonfig] Telemetry POST failed: #{status}"
-        else
-          LOG.debug "[quonfig] Telemetry POST ok: events=#{payload['events'].size}"
-        end
-        response
-      end
-
-      def http_connection
-        @http_connection ||= begin
-          return nil if @sdk_key.nil? || @telemetry_destination.nil?
-
-          Quonfig::HttpConnection.new(@telemetry_destination, @sdk_key)
-        end
-      end
-
-      def calculate_sync_interval(sync_interval)
-        return proc { sync_interval } if sync_interval.is_a?(Numeric)
-        return sync_interval if sync_interval.respond_to?(:call)
-
-        Quonfig::ExponentialBackoff.new(
-          initial_delay: DEFAULT_INITIAL_DELAY_SECONDS,
-          max_delay: DEFAULT_MAX_DELAY_SECONDS,
-          multiplier: 1.5
-        )
+        close
       end
     end
   end

data/lib/quonfig/telemetry/transport_queue.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Quonfig
+  module Telemetry
+    # Monotonic milliseconds for the telemetry transport: the 30s floor,
+    # Retry-After, retained-batch age and the WARN cadence all read it. Tests
+    # inject a manual clock through TelemetryReporter.build(clock:).
+    module MonotonicClock
+      def self.now_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      end
+    end
+
+    # Telemetry transport policy (qfg-y8je.8; policy P1-P10 in
+    # project/plans/2026-09-24-sdk-telemetry-transport-policy.md, contract tests
+    # in integration-test-data/chaos/telemetry-transport-contract.md; mirrors
+    # sdk-node's src/telemetry/transportQueue.ts).
+    #
+    # Owns the retained queue of serialized batches, the send gate (30s floor
+    # after a failure + Retry-After), the drain loop, disable-on-auth and the P7
+    # logging episodes. It knows nothing about aggregators or payload shape: it
+    # stores and resends opaque bytes, never re-serializing or merging them.
+    #
+    # Not thread-safe on its own: TelemetryReporter serializes every call under
+    # its tick mutex, which is also what keeps one POST in flight (P2).
+    class TransportQueue
+      LOG = Quonfig::InternalLogger.new(self)
+
+      # No send sooner than this after a failed POST (P4).
+      RESEND_FLOOR_MS = 30_000
+      # Retry-After is honored up to this (P4).
+      RETRY_AFTER_CAP_MS = 600_000
+      # At most one drop WARN per this interval while dropping continues (P7).
+      DROP_WARN_INTERVAL_MS = 600_000
+      # close() gives the live window one POST with this deadline (P8).
+      SHUTDOWN_FLUSH_DEADLINE_MS = 5_000
+
+      # Outcome of one POST that got an HTTP response.
+      Result = Struct.new(:status, :retry_after, :body_snippet, keyword_init: true)
+
+      Batch = Struct.new(:body, :bytes, :created_at, :oversize, keyword_init: true)
+
+      # 2xx -> :ok; 401, 403, 404 -> :auth; 408, 429, 5xx -> :retryable; every
+      # other status (other 4xx, 3xx, 1xx) -> :rejected (P3).
+      def self.classify_status(status)
+        return :ok if status >= 200 && status < 300
+        return :auth if [401, 403, 404].include?(status)
+        return :retryable if [408, 429].include?(status) || (status >= 500 && status < 600)
+
+        :rejected
+      end
+
+      # Parse a Retry-After header into a wait in ms: delta-seconds, or an
+      # HTTP-date relative to now (past dates -> 0). Unparseable -> nil.
+      # Clamped to RETRY_AFTER_CAP_MS.
+      def self.parse_retry_after_ms(header, wall_now: Time.now)
+        return nil if header.nil?
+
+        value = header.to_s.strip
+        return nil if value.empty?
+
+        ms =
+          if value.match?(/\A\d+\z/)
+            value.to_i * 1000
+          else
+            begin
+              [((Time.httpdate(value) - wall_now) * 1000).round, 0].max
+            rescue ArgumentError
+              return nil
+            end
+          end
+        [ms, RETRY_AFTER_CAP_MS].min
+      end
+
+      # +sender+ is called as +sender.call(body, timeout_ms)+ and returns a
+      # Result, or raises (a Faraday/Timeout error for a timeout, anything else
+      # for a network failure).
+      def initialize(sender:, telemetry_url:, timeout_ms:, max_retained_batches:,
+                     max_retained_bytes:, max_retained_age_ms:, clock: MonotonicClock,
+                     on_disabled: nil)
+        @sender = sender
+        @telemetry_url = telemetry_url
+        @timeout_ms = timeout_ms
+        @max_retained_batches = max_retained_batches
+        @max_retained_bytes = max_retained_bytes
+        @max_retained_age_ms = max_retained_age_ms
+        @clock = clock
+        @on_disabled = on_disabled
+
+        @queue = []
+        @in_flight = false
+        @last_failure_at = nil
+        @retry_after_until = nil
+        @disabled = false
+
+        # Outage episode (P7).
+        @failures_since_success = 0
+        @first_failure_at = nil
+        @last_result = nil
+        @last_drop_warn_at = nil
+        @drops_since_warn = 0
+        @drops_this_outage = 0
+
+        # Rejected-batch (other 4xx) cadence.
+        @last_reject_error_at = nil
+        @rejects_since_error = 0
+      end
+
+      def in_flight? = @in_flight
+      def disabled? = @disabled
+
+      # Every queued batch, including a not-yet-sent oversize one.
+      def retained_count = @queue.size
+
+      def retained_bytes = @queue.sum(&:bytes)
+
+      # Discard batches older than the max age (strictly greater). Tick step 2.
+      def expire
+        now = @clock.now_ms
+        while (head = @queue.first) && now - head.created_at > @max_retained_age_ms
+          @queue.shift
+          record_drop("batch older than #{(@max_retained_age_ms / 60_000.0).round} min")
+        end
+      end
+
+      # The 30s floor after a failure and any Retry-After have both elapsed.
+      # Tick step 3.
+      def send_allowed?
+        now = @clock.now_ms
+        return false if @last_failure_at && now < @last_failure_at + RESEND_FLOOR_MS
+        return false if @retry_after_until && now < @retry_after_until
+
+        true
+      end
+
+      # Append a serialized window and enforce the caps, dropping oldest. An
+      # oversize batch is never counted against the caps and never evicted by
+      # them: it is sent once and then dropped (see #drain). Tick step 4.
+      def append(body)
+        oversize = body.bytesize > @max_retained_bytes
+        @queue << Batch.new(body: body, bytes: body.bytesize, created_at: @clock.now_ms, oversize: oversize)
+
+        kept = @queue.reject(&:oversize)
+        count = kept.size
+        bytes = kept.sum(&:bytes)
+        while count > @max_retained_batches || bytes > @max_retained_bytes
+          index = @queue.index { |b| !b.oversize }
+          break if index.nil?
+
+          evicted = @queue.delete_at(index)
+          count -= 1
+          bytes -= evicted.bytes
+          record_drop('retained queue full')
+        end
+      end
+
+      # POST queued batches oldest-first, one at a time; stop at the first
+      # failure. Tick step 5.
+      def drain
+        until @queue.empty? || @disabled
+          batch = @queue.first
+          outcome = post(batch.body, @timeout_ms)
+
+          if outcome.is_a?(String)
+            on_retryable_failure(batch, outcome, nil)
+            break
+          end
+
+          case self.class.classify_status(outcome.status)
+          when :ok
+            @queue.shift
+            on_success
+          when :retryable
+            on_retryable_failure(batch, outcome.status.to_s, outcome.retry_after)
+            break
+          when :auth
+            disable(outcome.status)
+            return
+          else
+            # Rejected: drop this batch, report, carry on with the next one.
+            @queue.shift
+            on_rejected(outcome.status, batch.bytes, outcome.body_snippet)
+          end
+        end
+
+        # Oversize batches are never carried across ticks.
+        @queue.select(&:oversize).each do |batch|
+          remove(batch)
+          record_drop('batch larger than the byte cap')
+        end
+      end
+
+      # close(): one POST of the live window bounded by +deadline_ms+. Never
+      # retains, never touches the outage episode, never raises.
+      def send_final(body, deadline_ms)
+        outcome = post(body, deadline_ms)
+        result =
+          if outcome.is_a?(String)
+            outcome
+          elsif self.class.classify_status(outcome.status) != :ok
+            outcome.status.to_s
+          end
+        return if result.nil?
+
+        LOG.debug "Telemetry final flush at shutdown failed (#{result}); #{body.bytesize} bytes dropped, " \
+                  "#{retained_count} retained batch(es) abandoned"
+      end
+
+      private
+
+      # Remove by identity (two batches may carry equal bytes).
+      def remove(batch)
+        @queue.reject! { |b| b.equal?(batch) }
+      end
+
+      # One POST. Returns a Result, or a String describing a request that got
+      # no HTTP response ("timeout", "network error: ...").
+      def post(body, timeout_ms)
+        @in_flight = true
+        @sender.call(body, timeout_ms)
+      rescue Faraday::TimeoutError, Timeout::Error
+        'timeout'
+      rescue StandardError => e
+        "network error: #{e.class}: #{e.message}"
+      ensure
+        @in_flight = false
+      end
+
+      def on_success
+        return if @failures_since_success.zero?
+
+        seconds = ((@clock.now_ms - (@first_failure_at || @clock.now_ms)) / 1000.0).round
+        LOG.info "Telemetry recovered: POST succeeded after #{@failures_since_success} failed attempt(s) " \
+                 "over #{seconds}s; #{@drops_this_outage} batch(es) were dropped."
+        @failures_since_success = 0
+        @first_failure_at = nil
+        @drops_this_outage = 0
+        @last_drop_warn_at = nil
+        @drops_since_warn = 0
+      end
+
+      def on_retryable_failure(batch, result, retry_after)
+        now = @clock.now_ms
+        @failures_since_success += 1
+        @first_failure_at ||= now
+        @last_failure_at = now
+        @last_result = result
+        wait = self.class.parse_retry_after_ms(retry_after)
+        @retry_after_until = now + wait if wait
+
+        next_ms = [@last_failure_at + RESEND_FLOOR_MS, @retry_after_until || 0].max - now
+        LOG.debug "Telemetry POST failed (#{result}); #{retained_count} batch(es) / #{retained_bytes} bytes " \
+                  "retained, next send in >= #{(next_ms / 1000.0).ceil}s"
+
+        return unless batch.oversize
+
+        remove(batch)
+        record_drop('batch larger than the byte cap')
+      end
+
+      def disable(status)
+        hint = status == 404 ? 'wrong telemetry_url' : 'the SDK key was rejected'
+        LOG.error "Telemetry disabled for this process: #{@telemetry_url} answered #{status} (#{hint}). " \
+                  'Flag evaluation is unaffected.'
+        @queue.clear
+        @disabled = true
+        @on_disabled&.call
+      end
+
+      def on_rejected(status, bytes, body_snippet)
+        now = @clock.now_ms
+        if @last_reject_error_at.nil? || now - @last_reject_error_at >= DROP_WARN_INTERVAL_MS
+          more = @rejects_since_error.positive? ? ", #{@rejects_since_error} more since the last report" : ''
+          LOG.error "Telemetry batch rejected with #{status} and dropped (#{bytes} bytes#{more}): " \
+                    "#{body_snippet}. This is likely an SDK bug; please report it."
+          @last_reject_error_at = now
+          @rejects_since_error = 0
+        else
+          @rejects_since_error += 1
+          LOG.debug "Telemetry batch rejected with #{status} and dropped (#{bytes} bytes)"
+        end
+      end
+
+      def record_drop(reason)
+        now = @clock.now_ms
+        @drops_since_warn += 1
+        @drops_this_outage += 1
+        last_result = @last_result || 'none'
+        if @last_drop_warn_at.nil?
+          LOG.warn "Telemetry is dropping data: #{reason} (last POST result: #{last_result}). " \
+                   "#{@drops_this_outage} batch(es) dropped so far; retained queue " \
+                   "#{retained_count}/#{@max_retained_batches} batches, #{retained_bytes} bytes. " \
+                   'Flag evaluation is unaffected; further drops log at debug with a summary every 10 min.'
+          @last_drop_warn_at = now
+          @drops_since_warn = 0
+        elsif now - @last_drop_warn_at >= DROP_WARN_INTERVAL_MS
+          minutes = ((now - @last_drop_warn_at) / 60_000.0).round
+          LOG.warn "Telemetry still dropping data: #{@drops_since_warn} batch(es) dropped in the last " \
+                   "#{minutes} min (last POST result: #{last_result}); retained queue #{retained_count} " \
+                   "batches, #{retained_bytes} bytes."
+          @last_drop_warn_at = now
+          @drops_since_warn = 0
+        else
+          LOG.debug "Telemetry dropped a batch: #{reason}; #{@drops_since_warn} since the last warning"
+        end
+      end
+    end
+  end
+end

data/lib/quonfig/version.rb

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

data/lib/quonfig.rb

@@ -62,6 +62,7 @@ require 'quonfig/telemetry/context_shape_aggregator'
 require 'quonfig/telemetry/example_contexts_aggregator'
 require 'quonfig/telemetry/evaluation_summaries_aggregator'
 require 'quonfig/telemetry/failover_aggregator'
+require 'quonfig/telemetry/transport_queue'
 require 'quonfig/telemetry/telemetry_reporter'
 require 'quonfig/client'
 require 'quonfig/bound_client'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -132,6 +132,7 @@ files:
 - lib/quonfig/telemetry/example_contexts_aggregator.rb
 - lib/quonfig/telemetry/failover_aggregator.rb
 - lib/quonfig/telemetry/telemetry_reporter.rb
+- lib/quonfig/telemetry/transport_queue.rb
 - lib/quonfig/time_helpers.rb
 - lib/quonfig/types.rb
 - lib/quonfig/version.rb