camada 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 450a1a841ac03fb9490c0a6c1c3e45d62b0eec927795bb3fc3b2064f89432349
-  data.tar.gz: 8cd0ffee6f1686a7ad8150094898f3faaaff7f7b797306b5bb2af936a05ccc84
+  metadata.gz: 66753d06b68709a8360519bc64f67cc2278112b804da0d83bebfbe74ab211ae6
+  data.tar.gz: fc1423d70058d49223d3a3462d882fc6898013266c130d4be2835bb5696e9f5b
 SHA512:
-  metadata.gz: 27a5225cff7c94d36f2d5d1d85e91a4304bc71d7edff69c5706ffb9cba903132e67723e650f991a1445abd96f402ac3b2fa920240bc6184e82441870dc0a94cb
-  data.tar.gz: 677d632f45dab7351fd8982c396335a9ab02b8bfc1f6598301b4b1c334d520922d6b11e543353e314b8c5aead17b0b66ae4aefbaac6e5ccec0a9e773aa066f58
+  metadata.gz: 94a9c22c64a0f100c47c6312bc81cd9d4cf0b38a73d30f901a7951815b42b9f111d617f69acd2fa5541945b9626a4259c9ad39e5a2021fd7c8a6a03d38d30809
+  data.tar.gz: 07d7bfc337bc64e69781e507efcd1269acbd79e626608e27631aec91004a4de820ad80bc5ba3fbe02d3192005a8f1278fd7825a66df31ea6b7063f87c13c5f9a

data/README.md

@@ -176,7 +176,9 @@ here (and never raises), while it does at the edge.
 
 Every entry point runs inside the fail-open envelope: a dead ingest drops telemetry (logged at
 most once a minute, one line, no backtrace), a corrupt snapshot keeps the previous one, a bug in
-the gem costs the request its join, never its response. `CAMADA_DISABLED=1` bypasses everything.
+the gem costs the request its join, never its response. A failed snapshot poll (401, 5xx, no
+answer) keeps the rules in place and paces the next one: `Retry-After` in seconds is honoured,
+floored at 5 s and capped at the refresh interval. `CAMADA_DISABLED=1` bypasses everything.
 
 ## Development
 

data/lib/camada/snapshot/client.rb

@@ -23,6 +23,21 @@ module Camada
     # Process.pid with the pid that built the client and starts over in a forked worker.
     COLD = MatchResult.new(reason: "cold") # never loaded yet: fail open, mirrors the collector
     NONE = MatchResult.new
+    POLL_FLOOR_S = 5.0
+
+    # Seconds to wait before the next self-initiated poll after a poll answered `status`, or nil
+    # when the answer was 200/204/304 (not paced: the normal cadence governs). A Retry-After in
+    # delta-seconds is honoured, floored at 5 s and capped at the current cadence (the cap wins).
+    # HTTP-dates and anything else that is not all digits read as absent (edge-analyst only sends
+    # delta-seconds). status 0 = no answer. Internal.
+    def self.next_poll_delay(status, retry_after, refresh_s)
+      return nil if [200, 204, 304].include?(status)
+
+      ra = retry_after.to_s.gsub(/\A[ \t]+|[ \t]+\z/, "")
+      secs = ra.match?(/\A[0-9]+\z/) ? [ra.to_i, 1_000_000_000].min : 0 # overflow reads as huge, not invalid
+      cap = [refresh_s.to_f, 0.0].max
+      [[secs, POLL_FLOOR_S].max, cap].min.to_f # rubocop:disable Style/ComparableClamp -- not #clamp: it raises when the cap is under the floor
+    end
 
     class Client
       attr_accessor :transport
@@ -46,6 +61,7 @@ module Camada
         @pinned = !refresh_s.nil?
         @etag = nil
         @loaded_at = nil
+        @not_before = 0.0 # a failed poll gates the next self-initiated one until this monotonic time
         fresh_state!
       end
 
@@ -81,24 +97,55 @@ module Camada
         @loaded_at.nil? || monotonic - @loaded_at > @refresh_s * 0.9
       end
 
-      # Kicks a refresh when stale; never blocks the request path, never raises.
+      # Kicks a refresh when due; never blocks the request path, never raises.
       def ensure_fresh
         check_fork!
-        return if !stale? || @loading.locked?
+        return if !due? || @loading.locked?
 
-        t = Thread.new { refresh }
+        t = Thread.new { refresh_if_due }
         t.name = "camada-snapshot-load"
         t.report_on_exception = false
         nil
       end
 
-      # One synchronous poll (single in-flight): what the threads call, and what tests and warm-ups call directly.
+      # One synchronous poll (single in-flight): what tests and warm-ups call directly, ignoring the gate.
       def refresh
+        poll { true }
+      end
+
+      # Cold (never loaded) and no-snapshot both fail open, mirroring the edge collector.
+      def verdict(i)
+        return COLD if @loaded_at.nil?
+
+        m = @matcher
+        m ? m.match(i) : NONE
+      end
+
+      private
+
+      # What the background kick calls: take the slot, then re-check, so a second kick that lost the
+      # race to a poll that has just finished (and gated the next one) does nothing.
+      def refresh_if_due
+        poll { due? }
+      end
+
+      # Stale and past the failure gate: what every self-initiated poll (request path, timer tick)
+      # asks. A gate further away than one cadence means the clock stepped; treat it as open.
+      def due?
+        return false unless stale?
+
+        now = monotonic
+        @not_before <= now || @not_before - now > @refresh_s
+      end
+
+      def poll
         check_fork!
         lock = @loading # bound once: after_fork! swaps the attribute
         return unless lock.try_lock
 
         begin
+          return unless yield
+
           load_once
         rescue StandardError => e # a poll that can never succeed must not be silent, nor fatal
           Guarded.log_rate_limited(e)
@@ -107,16 +154,6 @@ module Camada
         end
       end
 
-      # Cold (never loaded) and no-snapshot both fail open, mirroring the edge collector.
-      def verdict(i)
-        return COLD if @loaded_at.nil?
-
-        m = @matcher
-        m ? m.match(i) : NONE
-      end
-
-      private
-
       def fresh_state!
         @pid = Process.pid
         @loading = Mutex.new
@@ -150,8 +187,18 @@ module Camada
         headers["x-camada-sdk"] = @sdk if @sdk
         # a tenant without that container is answered with the next one down
         headers["x-camada-snapshot"] = @snapshot_version.to_s if @snapshot_version > 3
-        res = @transport.call(HttpRequest.new(method: "GET", url: @url, headers: headers, body: nil, timeout_s: @timeout_s))
-        return unless [200, 204, 304].include?(res.status) # 401/5xx/network: keep what we have
+        res = begin
+          @transport.call(HttpRequest.new(method: "GET", url: @url, headers: headers, body: nil, timeout_s: @timeout_s))
+        rescue StandardError => e
+          Guarded.log_rate_limited(e) # still logged (rate-limited), and gated below as status 0
+          HttpResponse.new(status: 0, headers: {}, body: "".b) # a transport that raises is no answer
+        end
+        delay = Snapshot.next_poll_delay(res.status, res.headers["retry-after"], @refresh_s)
+        unless delay.nil? # 401/5xx/network: keep what we have (cold stays cold) and back off
+          @not_before = monotonic + delay # written before the slot is released
+          return
+        end
+        @not_before = 0.0
 
         # loaded_at is stamped last (even when the body turns out corrupt): "not cold" is what Puma's
         # request threads read as "rules in place", so it must not be visible before the matcher and

data/lib/camada/transport.rb

@@ -42,11 +42,11 @@ module Camada
     end
 
     def self.response(status, headers, body)
-      if headers["content-encoding"].to_s.downcase == "gzip"
+      if !body.empty? && headers["content-encoding"].to_s.downcase == "gzip"
         begin
           body = Zlib::GzipReader.new(StringIO.new(body)).read.b
         rescue StandardError
-          return HttpResponse.new(status: 0, headers: headers, body: "".b) # a body we cannot read is no answer at all
+          return HttpResponse.new(status: 0, headers: {}, body: "".b) # a body we cannot read is no answer at all: no retry-after either
         end
         headers.delete("content-encoding")
       end

data/lib/camada/version.rb

@@ -5,6 +5,6 @@ module Camada
   # source: camada.gemspec reads it at build, and the sibling drift guards (camada-backend,
   # camada-web, camada-mkt) parse this file with /^\s*VERSION = "([^"]+)"/m the way they parse
   # a package.json. Plain X.Y.Z only: the analyst's SDK_RE drops anything else.
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
   SDK_ID = "@camada/ruby/#{VERSION}".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: camada
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - camada
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-04 00:00:00.000000000 Z
+date: 2026-10-09 00:00:00.000000000 Z
 dependencies: []
 description: 'camada SDK for Ruby: inline enforcement of your snapshot (ordered custom
   rules, then allow, block, challenge), first-party beacon and proof-of-work challenge,