restless-sdk 0.1.0

data/lib/restless/caches.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Restless
+  # CONTRACT.md section 11.
+  #
+  # Both caches are Mutex-guarded. Puma, Falcon and Unicorn-with-threads all
+  # serve requests on many threads at once, so an unsynchronized Hash here is a
+  # real data race rather than a theoretical one.
+
+  # CACHE-001..007. Enriched owner metadata, keyed by owner id (or the masked
+  # end-user key when there is no id).
+  #
+  # The point is that `enrich` runs once per key per TTL window rather than
+  # once per request, AND that the enriched VALUE is stored -- not merely a
+  # freshness flag. Every upload has to carry owner metadata, including the
+  # ones that skipped the callback, because the ingest cannot backfill: without
+  # it every request after the first lands in the dashboard as unauthenticated.
+  class EnrichCache
+    DEFAULT_TTL_MS = 3_600_000 # CACHE-004: 1 hour
+
+    def initialize(ttl_ms = DEFAULT_TTL_MS)
+      @ttl_ms = ttl_ms
+      @entries = {}
+      @mutex = Mutex.new
+    end
+
+    def get(key)
+      @mutex.synchronize do
+        entry = @entries[key]
+        next nil if entry.nil?
+
+        if now_ms - entry[:ts] > @ttl_ms # CACHE-015
+          @entries.delete(key)
+          next nil
+        end
+        entry[:value]
+      end
+    end
+
+    def set(key, value)
+      @mutex.synchronize { @entries[key] = { value: value, ts: now_ms } }
+      value
+    end
+
+    # CACHE-006. Server-driven, via `needsEnrichment` on an upload response.
+    def invalidate(key)
+      @mutex.synchronize { @entries.delete(key) }
+    end
+
+    def clear
+      @mutex.synchronize { @entries.clear }
+    end
+
+    def size
+      @mutex.synchronize { @entries.size }
+    end
+
+    private
+
+    def now_ms
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+    end
+  end
+
+  # CACHE-010..015. Agent Recovery messages keyed by error fingerprint.
+  #
+  # Performance is the whole point. The lookup sits on the hot path of every
+  # 4xx/5xx, so it is synchronous, in-process and never does I/O. A cold miss
+  # injects nothing and returns immediately; the server piggybacks the message
+  # onto the next upload response, so the SECOND occurrence hits.
+  #
+  # "No message for this fingerprint" is itself a cacheable answer, stored as
+  # nil, so a cold miss does not stay cold on every request. The negative TTL
+  # is shorter so a freshly-attached dashboard message starts working within
+  # minutes.
+  class RecoveryCache
+    DEFAULT_TTL_MS = 3_600_000 # CACHE-014: 1 hour, positive
+    DEFAULT_NEGATIVE_TTL_MS = 300_000 # CACHE-014: 5 minutes, negative
+
+    # Distinguishes "cached as absent" (nil) from "never seen" (MISS).
+    MISS = Object.new.freeze
+
+    def initialize(ttl_ms = DEFAULT_TTL_MS, negative_ttl_ms = DEFAULT_NEGATIVE_TTL_MS)
+      @ttl_ms = ttl_ms
+      @negative_ttl_ms = negative_ttl_ms
+      @entries = {}
+      @mutex = Mutex.new
+    end
+
+    # Returns a String (inject it), nil (the server confirmed there is none),
+    # or MISS (never seen, or expired).
+    def get(key)
+      @mutex.synchronize do
+        entry = @entries[key]
+        next MISS if entry.nil?
+
+        ttl = entry[:message].nil? ? @negative_ttl_ms : @ttl_ms
+        if now_ms - entry[:ts] > ttl # CACHE-015
+          @entries.delete(key)
+          next MISS
+        end
+        entry[:message]
+      end
+    end
+
+    # Convenience for the hot path: the message to inject, or nil.
+    def lookup(key)
+      value = get(key)
+      value.is_a?(String) ? value : nil
+    end
+
+    def set(key, message)
+      @mutex.synchronize { @entries[key] = { message: message, ts: now_ms } }
+    end
+
+    # CACHE-013. A negative entry must never overwrite a positive one.
+    def set_negative_unless_present(key)
+      @mutex.synchronize do
+        entry = @entries[key]
+        if entry
+          ttl = entry[:message].nil? ? @negative_ttl_ms : @ttl_ms
+          fresh = now_ms - entry[:ts] <= ttl
+          next if fresh && !entry[:message].nil?
+        end
+        @entries[key] = { message: nil, ts: now_ms }
+      end
+    end
+
+    def invalidate(key)
+      @mutex.synchronize { @entries.delete(key) }
+    end
+
+    def clear
+      @mutex.synchronize { @entries.clear }
+    end
+
+    def size
+      @mutex.synchronize { @entries.size }
+    end
+
+    private
+
+    def now_ms
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+    end
+  end
+end

data/lib/restless/capture.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "caches"
+require_relative "fingerprint"
+require_relative "redact"
+require_relative "uploader"
+
+module Restless
+  # The capture engine: redaction choke point (section 4), the two caches
+  # (section 11), fingerprinting (section 5) and the hand-off to the uploader
+  # (sections 8 and 9).
+  #
+  # Every adapter goes through here. No adapter may bypass `record`, which is
+  # the single point where redaction runs.
+  class CaptureEngine
+    # REDACT-030.
+    MAX_BODY_BYTES = Redact::MAX_BODY_BYTES
+
+    attr_reader :uploader, :enrich_cache, :recovery_cache
+
+    def initialize(api_key:, base_url:, request_id_prefix: nil, redact: nil,
+                   transport: nil)
+      @redact = redact || {}
+      @enrich_cache = EnrichCache.new
+      @recovery_cache = RecoveryCache.new
+      @docs_url = nil
+      @docs_mutex = Mutex.new
+      @callback = nil
+      @uploader = Uploader.new(
+        api_key: api_key,
+        base_url: base_url,
+        request_id_prefix: request_id_prefix,
+        transport: transport,
+        on_response: method(:handle_server_response)
+      )
+    end
+
+    def callback=(callback)
+      @callback = callback
+    end
+
+    # INJECT-006. The latest server-resolved docs origin, or nil when no batch
+    # has round-tripped yet.
+    def docs_url
+      @docs_mutex.synchronize { @docs_url }
+    end
+
+    def flush
+      @uploader.flush
+    end
+
+    # WIRE-020..023, CACHE-006, CACHE-011..013.
+    def handle_server_response(body, batch_fingerprints)
+      needs = body["needsEnrichment"]
+      if needs.is_a?(Array)
+        needs.each { |key| @enrich_cache.invalidate(key) if key.is_a?(String) }
+      end
+
+      docs = body["docsUrl"]
+      if docs.is_a?(String) && !docs.empty?
+        # Origin only; strip trailing slashes so the server can be lax.
+        @docs_mutex.synchronize { @docs_url = docs.sub(%r{/+\z}, "") }
+      end
+
+      messages = body["recoveryMessages"].is_a?(Hash) ? body["recoveryMessages"] : {}
+      batch_fingerprints.each do |key|
+        value = messages[key]
+        if value.is_a?(String)
+          @recovery_cache.set(key, value) # CACHE-011
+        elsif messages.key?(key)
+          @recovery_cache.set(key, nil)
+        else
+          # CACHE-012 + CACHE-013: negative-cache anything the server did not
+          # answer for, without clobbering an existing positive entry. This is
+          # what guarantees the SECOND occurrence of any error is a cache hit.
+          @recovery_cache.set_negative_unless_present(key)
+        end
+      end
+    rescue StandardError => e
+      Env.debug_log("server response handling failed: #{e.class}: #{e.message}")
+    end
+
+    # CACHE-010. Synchronous, in-process, no I/O, never blocks the response.
+    def lookup_recovery(fingerprint_key)
+      @recovery_cache.lookup(fingerprint_key)
+    end
+
+    # FP-002. Errors only; the ingest treats an absent fingerprint as success.
+    def compute_fingerprint(captured, stack_frame = nil)
+      response = captured["response"] || {}
+      status = response["status"].to_i
+      return nil if status < 400
+
+      body = response["body"]
+      if body.is_a?(String)
+        begin
+          body = JSON.parse(body, max_nesting: false)
+        rescue StandardError
+          # Leave it as a string; `extract_message` handles both shapes.
+        end
+      end
+
+      request = captured["request"] || {}
+      Fingerprint.compute(
+        status: status,
+        method: request["method"],
+        route: captured["routePattern"],
+        response_headers: response["headers"],
+        response_body: body,
+        stack_frame: stack_frame
+      )
+    rescue StandardError => e
+      Env.debug_log("fingerprint failed: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # WIRE-017. The serialized form of a fingerprint.
+    #
+    # `Fingerprint::Result` is a Struct with symbol members, and the wire wants
+    # string keys, so the mapping has to be written somewhere. It is written
+    # once: the Rack middleware computes the fingerprint early (INJECT-009) and
+    # must serialize it identically to `record` below.
+    def self.wire_fingerprint(fingerprint)
+      {
+        "strategy" => fingerprint.strategy,
+        "key" => fingerprint.key,
+        "reason" => fingerprint.reason
+      }
+    end
+
+    # Run the user's setup callback and resolve owner metadata.
+    #
+    # SAFETY-002: a callback that raises is caught and the request proceeds
+    # with no user context attached.
+    def resolve(request)
+      return {} if @callback.nil?
+
+      begin
+        raw = @callback.call(request)
+      rescue StandardError => e
+        Env.debug_log("setup callback raised: #{e.class}: #{e.message}")
+        return {}
+      end
+      return {} unless raw.is_a?(Hash)
+
+      result = normalize_setup(raw)
+      owner = result[:owner]
+      return { "apiKey" => result[:api_key], "block" => result[:block],
+               "extra" => result[:extra] }.compact if owner.nil?
+
+      owner_id = owner[:id]
+      enrich = owner[:enrich]
+      # CACHE-002: key on owner id when present, else the masked end-user key,
+      # so multiple end-users in one workspace share a slot.
+      cache_key = (owner_id if owner_id && !owner_id.empty?) || result[:api_key]
+
+      resolved_owner = { "id" => owner_id }.compact
+
+      if enrich.respond_to?(:call) && owner_id && !owner_id.empty? && cache_key
+        cached = @enrich_cache.get(cache_key)
+        if cached
+          # CACHE-003: the VALUE is cached, not merely a freshness flag, so
+          # every upload carries owner metadata even when the callback was
+          # skipped. The ingest cannot backfill.
+          resolved_owner = resolved_owner.merge(cached)
+        else
+          enriched = begin
+            enrich.call(owner_id)
+          rescue StandardError => e
+            # CACHE-005 / SAFETY-003: swallowed, and NOT cached, so the next
+            # request retries.
+            Env.debug_log("enrich raised: #{e.class}: #{e.message}")
+            nil
+          end
+          if enriched.is_a?(Hash)
+            stringified = stringify_keys(enriched)
+            @enrich_cache.set(cache_key, stringified)
+            resolved_owner = resolved_owner.merge(stringified)
+          end
+        end
+      end
+
+      # CACHE-007: when enrichment did not run or produced nothing, the upload
+      # still carries the bare owner id so the dashboard can group by it.
+      {
+        "apiKey" => result[:api_key],
+        "owner" => resolved_owner,
+        "block" => result[:block],
+        "extra" => result[:extra]
+      }.compact
+    end
+
+    # SETUP-004.
+    def self.resolve_block(block)
+      return nil if block.nil? || block == false
+      return { status: 403, message: "Forbidden" } if block == true
+      return nil unless block.is_a?(Hash)
+
+      status = block[:status] || block["status"] || 403
+      message = block[:message] || block["message"] || "Forbidden"
+      { status: status.to_i, message: message.to_s }
+    end
+
+    # The single redaction choke point. Redact, truncate, fingerprint, enqueue.
+    def record(captured, stack_frame: nil)
+      request = captured["request"] || {}
+      response = captured["response"] || {}
+      request_headers = request["headers"] || {}
+      response_headers = response["headers"] || {}
+
+      sanitized = captured.dup
+      sanitized["request"] = request.merge(
+        "url" => Redact.redact_url(request["url"].to_s, @redact[:query_params] || []),
+        "headers" => Redact.redact_headers(request_headers, @redact[:headers] || []),
+        # REDACT-033: truncation runs AFTER redaction, so a secret cannot
+        # survive by sitting past the byte limit.
+        "body" => Redact.truncate_body(
+          Redact.redact_body(request["body"], request_headers["content-type"],
+                             @redact[:body_keys] || []),
+          MAX_BODY_BYTES
+        )
+      )
+      sanitized["response"] = response.merge(
+        "headers" => Redact.redact_headers(response_headers, @redact[:headers] || []),
+        "body" => Redact.truncate_body(
+          Redact.redact_body(response["body"], response_headers["content-type"],
+                             @redact[:body_keys] || []),
+          MAX_BODY_BYTES
+        )
+      )
+
+      if sanitized["errorFingerprint"].nil? && response["status"].to_i >= 400
+        fingerprint = compute_fingerprint(sanitized, stack_frame)
+        sanitized["errorFingerprint"] = self.class.wire_fingerprint(fingerprint) if fingerprint
+      end
+
+      @uploader.push(sanitized)
+      nil
+    rescue StandardError => e
+      # SAFETY-001. Nothing in here may reach customer handler code.
+      Env.debug_log("record failed: #{e.class}: #{e.message}")
+      nil
+    end
+
+    private
+
+    # Accept both `:api_key`/`"apiKey"` spellings so the callback reads
+    # naturally in Ruby without losing the documented wire names (SETUP-001).
+    def normalize_setup(raw)
+      api_key = fetch_any(raw, :api_key, :apiKey, "api_key", "apiKey")
+      owner_raw = fetch_any(raw, :owner, "owner")
+      block = fetch_any(raw, :block, "block")
+
+      known = %i[api_key apiKey owner block] + %w[api_key apiKey owner block]
+      extra = {}
+      raw.each do |key, value|
+        next if known.include?(key)
+
+        extra[key.to_s] = value
+      end
+
+      owner = nil
+      if owner_raw.is_a?(Hash)
+        owner = {
+          id: fetch_any(owner_raw, :id, "id"),
+          # SETUP-003: `enrich` is the ONLY channel for owner metadata.
+          # Anything else inline on `owner` is dropped.
+          enrich: fetch_any(owner_raw, :enrich, "enrich")
+        }
+      end
+
+      { api_key: api_key, owner: owner, block: block,
+        extra: extra.empty? ? nil : extra }
+    end
+
+    def fetch_any(hash, *keys)
+      keys.each { |key| return hash[key] if hash.key?(key) }
+      nil
+    end
+
+    def stringify_keys(hash)
+      out = {}
+      hash.each { |k, v| out[k.to_s] = v }
+      out
+    end
+  end
+end

data/lib/restless/client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "capture"
+require_relative "env"
+require_relative "mask"
+require_relative "request_id"
+require_relative "settings"
+require_relative "version"
+
+module Restless
+  # The public entry point.
+  #
+  #     client = Restless::Client.new(ENV["RESTLESS_KEY"])
+  #     client.setup { |request| { api_key: client.mask(request.header("authorization")) } }
+  #     use client.rack
+  class Client
+    attr_reader :engine
+
+    # CONFIG-001..003, CONFIG-010..015.
+    #
+    # `redact` extends the built-in denylists; it can never shrink or replace
+    # them (REDACT-014). Both the settings file and this option are additive
+    # on top of the defaults (REDACT-015).
+    #
+    # `transport` is an internal test hook -- anything responding to
+    # `call(url, headers, body) -> [status, body]` -- and is not public API.
+    def initialize(api_key = nil, base_url: nil, api: nil, redact: nil,
+                   transport: nil)
+      resolved_key = Env.resolve_api_key(api_key)
+
+      # CONFIG-002. Construction still succeeds and capture still runs; only
+      # upload is disabled.
+      if resolved_key.empty? && !Env.test_run?
+        warn("[restless-sdk] no API key found -- set RESTLESS_KEY in your " \
+             "environment or pass it to Restless::Client.new. Captured requests " \
+             "will not be uploaded.")
+      end
+
+      # CONFIG-013/CONFIG-014 raise here, deliberately: guessing which API
+      # entry to use would silently apply the wrong redaction list.
+      entry = Settings.resolve_api(Settings.load, api)
+      settings_redact = entry && entry[:redact]
+
+      @engine = CaptureEngine.new(
+        api_key: resolved_key,
+        base_url: Env.resolve_base_url(base_url),
+        request_id_prefix: entry && entry[:request_id_prefix],
+        redact: merge_redact(settings_redact, redact),
+        transport: transport
+      )
+    end
+
+    # Register the per-request callback. Accepts a block or any callable.
+    #
+    #     client.setup do |request|
+    #       { api_key: client.mask(request.header("authorization")),
+    #         owner: { id: workspace_id, enrich: ->(id) { load_workspace(id) } } }
+    #     end
+    def setup(callable = nil, &block)
+      @engine.callback = callable || block
+      self
+    end
+
+    # MASK-001. Pass the RAW header value through; never substitute a
+    # placeholder like "anonymous", whose last 4 characters would become the
+    # mask tail and cluster unrelated callers together (SETUP-001).
+    def mask(api_key)
+      Mask.mask(api_key)
+    end
+
+    # BATCH-005.
+    def flush
+      @engine.flush
+    end
+
+    def new_request_id
+      RequestId.new_request_id
+    end
+
+    # The Rack middleware factory. `use client.rack` in a `config.ru`, or
+    # `app = client.rack.new(app)` by hand.
+    def rack(**options)
+      Middleware.factory(self, **options)
+    end
+
+    def spec_version
+      SPEC_VERSION
+    end
+
+    def conformance_level
+      CONFORMANCE_LEVEL
+    end
+
+    private
+
+    def merge_redact(from_settings, from_options)
+      settings = from_settings || {}
+      options = from_options || {}
+      {
+        headers: list(settings["headers"]) + list(options[:headers] || options["headers"]),
+        body_keys: list(settings["bodyKeys"]) + list(options[:body_keys] || options["bodyKeys"]),
+        query_params: list(settings["queryParams"]) +
+                      list(options[:query_params] || options["queryParams"])
+      }
+    end
+
+    def list(value)
+      value.is_a?(Array) ? value.map(&:to_s) : []
+    end
+  end
+end