camada 0.1.0

data/lib/camada/snapshot/client.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../config"
+require_relative "../constants"
+require_relative "../guarded"
+require_relative "../transport"
+require_relative "match"
+require_relative "parse"
+
+module Camada
+  module Snapshot
+    # Client: the single-tenant port of the edge collector's snapshot lifecycle over the
+    # GET /snapshot contract (ported from @camada/core src/snapshot/client.ts):
+    #   200  [u32 LE meta-length][meta JSON][BLK container] + etag + x-camada-config
+    #   304  nothing changed; config header repeated (config refreshes every poll for free)
+    #   204  authenticated, no snapshot published -> enforce nothing, fail open
+    # Semantics ported exactly: single-in-flight load; loaded_at stamped even on 204 (retry per
+    # poll cadence, not per request); any error keeps the previous snapshot; cold = fail open.
+    # Timers are threads here: timer mode runs one thread per client sleeping on a condition
+    # variable; lazy mode kicks a one-shot thread from ensure_fresh so the request path never
+    # waits on the network. Ruby has no register_at_fork, so every entry point compares
+    # 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
+
+    class Client
+      attr_accessor :transport
+      attr_reader :url, :token, :matcher, :config, :refresh_s, :mode, :sdk, :snapshot_version, :timeout_s, :poll_thread
+
+      def initialize(url, token, refresh_s: nil, timeout_s: 3.0, mode: :timer, transport: nil, sdk: nil,
+                     snapshot_version: DEFAULT_SNAPSHOT_VERSION)
+        # refresh_s: leave unset and the server's poll_seconds steers it; set it and it is pinned.
+        # sdk: '<package>/<version>', sent as x-camada-sdk on every poll (SDK-03).
+        # snapshot_version: 5 asks for the custom rules too; 4 the sides only; 3 opts out of both.
+        @url = url
+        @token = token
+        @timeout_s = timeout_s
+        @mode = mode
+        @sdk = sdk
+        @snapshot_version = snapshot_version
+        @transport = transport || Transport::DEFAULT
+        @matcher = nil
+        @config = nil
+        @refresh_s = refresh_s.nil? ? DEFAULT_REFRESH_S : refresh_s.to_f
+        @pinned = !refresh_s.nil?
+        @etag = nil
+        @loaded_at = nil
+        fresh_state!
+      end
+
+      # Threads do not survive fork (Puma cluster preload_app!, Unicorn, Passenger): forget the
+      # parent's, then re-arm the timer so the child polls on its own (lazy mode refreshes from
+      # the request path anyway).
+      def after_fork!
+        fresh_state!
+        start if @mode == :timer
+      end
+
+      def start
+        ensure_fresh
+        return if @mode != :timer || !@poll_thread.nil?
+
+        @stopped = false
+        @poll_thread = Thread.new { run }
+        @poll_thread.name = "camada-snapshot"
+        @poll_thread.report_on_exception = false
+      end
+
+      def stop
+        @stop_m.synchronize do
+          @stopped = true
+          @stop_cv.broadcast
+        end
+        @poll_thread = nil
+      end
+
+      # 0.9 x refresh so a timer tick arriving at ~refresh-ε still refreshes; a full-interval
+      # comparison makes every other tick a no-op (effective cadence 2x).
+      def stale?
+        @loaded_at.nil? || monotonic - @loaded_at > @refresh_s * 0.9
+      end
+
+      # Kicks a refresh when stale; never blocks the request path, never raises.
+      def ensure_fresh
+        check_fork!
+        return if !stale? || @loading.locked?
+
+        t = Thread.new { refresh }
+        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.
+      def refresh
+        check_fork!
+        lock = @loading # bound once: after_fork! swaps the attribute
+        return unless lock.try_lock
+
+        begin
+          load_once
+        rescue StandardError => e # a poll that can never succeed must not be silent, nor fatal
+          Guarded.log_rate_limited(e)
+        ensure
+          lock.unlock
+        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
+        @stop_m = Mutex.new
+        @stop_cv = ConditionVariable.new
+        @stopped = false
+        @poll_thread = nil
+      end
+
+      def check_fork!
+        after_fork! if Process.pid != @pid
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Sleeps one cadence; true when stop was called meanwhile.
+      def wait_stop(seconds)
+        @stop_m.synchronize do
+          @stop_cv.wait(@stop_m, seconds) unless @stopped
+          @stopped
+        end
+      end
+
+      def run
+        ensure_fresh until wait_stop(@refresh_s)
+      end
+
+      def load_once
+        headers = { "authorization" => "Bearer #{@token}", "accept-encoding" => "gzip" }
+        headers["if-none-match"] = @etag if @etag
+        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
+
+        @loaded_at = monotonic
+        read_config(res.headers["x-camada-config"])
+        return if res.status == 304
+
+        if res.status == 204 # no snapshot published: enforce nothing
+          @matcher = nil
+          @etag = nil
+          return
+        end
+        body = res.body
+        raise ArgumentError, "camada: truncated snapshot frame" if body.bytesize < 4
+
+        meta_len = body.unpack1("V")
+        raise ArgumentError, "camada: truncated snapshot frame" if 4 + meta_len > body.bytesize
+
+        meta = JSON.parse(body.byteslice(4, meta_len))
+        raise ArgumentError, "camada: snapshot meta is not an object" unless meta.is_a?(Hash)
+
+        # The server ships the v3, v4 and v5 bodies of one publish under the SAME meta.version and
+        # different etags, so version alone cannot say "nothing changed".
+        etag = res.headers["etag"]
+        return if @matcher && meta["version"].to_s == @matcher.snap.version && !etag.nil? && etag == @etag
+
+        # parse_snapshot raises on corrupt data -> caught by refresh, previous kept
+        @matcher = Matcher.new(Snapshot.parse_snapshot(Words.new(body, 4 + meta_len), meta))
+        @etag = etag
+      end
+
+      def read_config(raw)
+        return if raw.nil? || raw.empty?
+
+        cfg = Camada.parse_json(raw)
+        return unless cfg.is_a?(Hash) # not an object, or not JSON: keep the previous config
+
+        @config = cfg
+        # the server steers the poll cadence per tenant (its cost lever) unless the client pinned one
+        secs = Float(cfg["poll_seconds"] || 0, exception: false)
+        return if @pinned || secs.nil? || !secs.finite? || secs < 5 || secs == @refresh_s # JSON admits 1e999
+
+        @refresh_s = secs
+      end
+    end
+  end
+end

data/lib/camada/snapshot/match.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require_relative "parse"
+
+module Camada
+  module Snapshot
+    # Matcher: sub-millisecond checks over a parsed Snap, ported from @camada/core
+    # src/snapshot/match.ts (itself from edge-analyst src/blocklist.js). Matching is fully
+    # synchronous and allocation-light. The original's per-instance scratch request is not ported:
+    # a JS isolate runs one match() at a time, but here one Matcher serves every request thread,
+    # so the rule loop reads a RuleRequest built per call.
+    #
+    # Outcome order is contract (contracts §D3, fixtures pin it): the tenant's ordered custom rules
+    # first (first match wins, the order IS the precedence), then allow -> block -> challenge.
+    # Within each side the axis order is ip4 -> ip6 -> asn -> country -> tls -> path.
+    # At the SDK position only ip, path, ua and the request headers are usually known;
+    # asn/country/tlsx entries and conditions then simply never match — that is the documented,
+    # honest enforcement scope (fail open, never guess).
+    MatchInput = Struct.new(
+      :ip, :asn, :country, :tlsx, :path,
+      :ua,     # v5 rules read it; the three sides never do
+      :header, # v5 header conditions read it, always with a lower-cased name
+      keyword_init: true
+    )
+
+    class MatchResult
+      attr_reader :block, :challenge, :allowed, :warn, :action, :rule, :reason, :version
+
+      # allowed: true for skip (which absorbed the old allow) and for the allow side;
+      # action:  the action of the rule that decided, nil when a side did;
+      # rule:    the rule id, present only when reason is 'rule';
+      # reason:  ip4 | ip6 | asn | country | tls | path | rule | cold.
+      def initialize(block: false, challenge: false, allowed: false, warn: false, action: nil, rule: nil, reason: nil, version: nil)
+        @block = block
+        @challenge = challenge
+        @allowed = allowed
+        @warn = warn
+        @action = action
+        @rule = rule
+        @reason = reason
+        @version = version
+        freeze
+      end
+    end
+
+    def self.clean_path(raw)
+      p = raw.nil? || raw.empty? ? "/" : raw
+      q = p.index("?")
+      q.nil? ? p : p[0, q]
+    end
+
+    # Walks every '/'-terminated ancestor of `path`, the way the block side does.
+    def self.prefix_hit?(prefixes, path)
+      i = path.index("/", 1)
+      until i.nil?
+        return true if prefixes.include?(path[0, i + 1])
+
+        i = path.index("/", i + 1)
+      end
+      false
+    end
+
+    # A rule decided this request (§D3): at most one of allowed / block / challenge / warn is
+    # true, `reason` is 'rule', and `rule` names the id the adapters stamp on the event.
+    def self.rule_result(rule, version)
+      a = rule.action
+      MatchResult.new(
+        block: a == "block", challenge: a == "challenge", allowed: a == "skip", warn: a == "warn",
+        action: a, rule: rule.id, reason: "rule", version: version
+      )
+    end
+
+    class Matcher
+      attr_reader :snap
+
+      def initialize(snap)
+        @snap = snap
+      end
+
+      def match(i)
+        s = @snap
+        ip = i.ip || ""
+        n4 = -1
+        w = nil
+        unless ip.empty?
+          if ip.include?(":")
+            w = IpParse.parse_ip6(ip)
+          else
+            n4 = IpParse.parse_ip4(ip)
+          end
+        end
+        unless s.rules.empty?
+          r = RuleRequest.new(n4: n4, ip6: w, asn: i.asn, country: i.country, tlsx: i.tlsx,
+                              path: Snapshot.clean_path(i.path), ua: i.ua, header: i.header)
+          s.rules.each do |rule| # the order IS the precedence (§A4): first match wins
+            return Snapshot.rule_result(rule, s.version) if rule.conds.all? { |cond| cond.call(r) }
+          end
+        end
+        reason = side(s.allow, i, n4, w)
+        return MatchResult.new(allowed: true, reason: reason, version: s.version) if reason
+
+        reason = block_side(i, n4, w)
+        return MatchResult.new(block: true, reason: reason, version: s.version) if reason
+
+        reason = side(s.challenge, i, n4, w)
+        return MatchResult.new(challenge: true, reason: reason, version: s.version) if reason
+
+        MatchResult.new(version: s.version)
+      end
+
+      private
+
+      def blocked4?(n)
+        s = @snap
+        b = n >> 8
+        return false if (s.bm4[b >> 5] >> (b & 31)) & 1 == 0
+
+        hi = n >> 16
+        left = s.idx4[hi]
+        right = s.idx4[hi + 1] - 1
+        left -= 1 if left > 0
+        return false if right < left
+
+        s4 = s.s4
+        while left < right
+          m = (left + right + 1) >> 1
+          if s4[m] <= n
+            left = m
+          else
+            right = m - 1
+          end
+        end
+        n.between?(s4[left], s.e4[left])
+      end
+
+      def words_at(a, o) = [a[o], a[o + 1], a[o + 2], a[o + 3]]
+
+      def blocked6?(w)
+        s = @snap
+        b = w[0] >> 8
+        return false if (s.bm6[b >> 5] >> (b & 31)) & 1 == 0
+
+        left = 0
+        right = s.n6 - 1
+        return false if right < 0
+
+        s6 = s.s6
+        while left < right
+          m = (left + right + 1) >> 1
+          if (words_at(s6, m * 4) <=> w) <= 0
+            left = m
+          else
+            right = m - 1
+          end
+        end
+        o = left * 4
+        (words_at(s6, o) <=> w) <= 0 && (w <=> words_at(s.e6, o)) <= 0
+      end
+
+      def blocked_asn?(asn)
+        s = @snap
+        return (s.asn_bm[asn >> 5] >> (asn & 31)) & 1 != 0 if asn < 4_194_304
+
+        extra = s.asn_extra
+        left = 0
+        right = extra.length - 1
+        while left <= right
+          m = (left + right) >> 1
+          v = extra[m]
+          return true if v == asn
+
+          if v < asn
+            left = m + 1
+          else
+            right = m - 1
+          end
+        end
+        false
+      end
+
+      def blocked_path?(path)
+        s = @snap
+        return true if s.paths_exact.include?(path)
+        return true if !s.paths_prefix.empty? && Snapshot.prefix_hit?(s.paths_prefix, path)
+
+        s.paths_regex.any? { |rx| Snapshot.regex_hit?(rx, path) }
+      end
+
+      # The block side: v3 sections plus the top-level meta.
+      def block_side(i, n4, w)
+        s = @snap
+        return "ip4" if n4 >= 0 && blocked4?(n4)
+        return "ip6" if !w.nil? && blocked6?(w)
+        return "asn" if !i.asn.nil? && blocked_asn?(i.asn)
+        return "country" if Camada.present(i.country) && !s.country.empty? && s.country.include?(i.country)
+        return "tls" if Camada.present(i.tlsx) && s.tls.include?(i.tlsx)
+        if (!s.paths_exact.empty? || !s.paths_prefix.empty? || !s.paths_regex.empty?) && blocked_path?(Snapshot.clean_path(i.path))
+          return "path"
+        end
+
+        nil
+      end
+
+      # A v4 side list (allow or challenge). No tls axis: §A3's side meta has no tls key.
+      def side(st, i, n4, w)
+        return nil if st.empty # the common v3 snapshot
+        return "ip4" if n4 >= 0 && Snapshot.in_range4?(st.r4, n4)
+        return "ip6" if !w.nil? && Snapshot.in_range6?(st.r6, st.n6, w)
+        return "asn" if !i.asn.nil? && st.asn.include?(i.asn)
+        return "country" if Camada.present(i.country) && st.country.include?(i.country)
+
+        if !st.paths_exact.empty? || !st.paths_prefix.empty?
+          p = Snapshot.clean_path(i.path)
+          return "path" if st.paths_exact.include?(p)
+          return "path" if !st.paths_prefix.empty? && Snapshot.prefix_hit?(st.paths_prefix, p)
+        end
+        nil
+      end
+    end
+  end
+end