coolhand 0.5.0 → 0.6.0

data/lib/coolhand/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Coolhand
+  class Error < StandardError; end
+
+  # Raised by the gem's read methods when the Coolhand API answers with a non-2xx status.
+  #
+  # `status` is carried so callers can branch on it (404 vs retryable 504) without matching the
+  # message text.
+  class HttpError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status:, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+end

data/lib/coolhand/logger_service.rb

@@ -44,7 +44,7 @@ module Coolhand
         headers: sanitize_headers(headers),
         request_body: clean_webhook_body(webhook_body, source),
         response_body: options[:response_body],
-        response_headers: options[:response_headers],
+        response_headers: options[:response_headers] && sanitize_headers(options[:response_headers]),
         status_code: options[:status_code] || 200,
         source: "#{source}_webhook"
       }.merge(options.slice(:metadata, :conversation_id, :agent_id))

data/lib/coolhand/net_http_interceptor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 module Coolhand
   module NetHttpInterceptor
     include BaseInterceptor
@@ -7,7 +9,12 @@ module Coolhand
     # Response streaming interceptor nested under NetHttpInterceptor
     module ResponseInterceptor
       def read_body(dest = nil, &block)
-        return super unless block
+        # Only buffer while a #request call below is actively capturing —
+        # otherwise every block-form read_body in the process (including
+        # ones on responses this gem never intercepted) accumulates into a
+        # thread-local that's never freed, which is an unbounded memory
+        # leak on any thread that streams large non-LLM responses.
+        return super unless block && Thread.current[:coolhand_capturing_stream]
 
         super do |chunk|
           Thread.current[:coolhand_stream_buffer] ||= +""
@@ -17,27 +24,69 @@ module Coolhand
       end
     end
 
+    @patch_mutex = Mutex.new
+    @patch_count = 0
+    @patched = false
+
+    # patch!/unpatch! are reference-counted so concurrent/nested callers (e.g. overlapping
+    # Coolhand.capture blocks across threads) compose safely — the interceptor only actually
+    # unpatches once every outstanding caller has released it. Coolhand.configure's patch! is
+    # never balanced by an unpatch!, so it permanently holds the count at >=1 for the process
+    # lifetime once the gem is enabled; that's intentional, not a leak.
+    #
+    # Unlike before, patch! is no longer idempotent on its own — every call must be matched by
+    # exactly one unpatch! to release it. A host app that calls Coolhand.configure more than once
+    # (e.g. a reloader re-running an initializer) will hold an extra, permanent reference each
+    # time rather than no-op'ing; harmless (interception simply stays on), but worth knowing.
     def self.patch!
-      return if @patched
-
-      Net::HTTP.prepend(self)
-      Net::HTTPResponse.prepend(ResponseInterceptor)
-
-      @patched = true
-      Coolhand.log "🔗 Net::HTTP interceptor patched"
+      @patch_mutex.synchronize do
+        @patch_count += 1
+        next if @patched
+
+        begin
+          Net::HTTP.prepend(self)
+          Net::HTTPResponse.prepend(ResponseInterceptor)
+
+          @patched = true
+          Coolhand.log "🔗 Net::HTTP interceptor patched"
+        rescue StandardError
+          # Roll back this call's hold — it never actually took effect, so it must not count
+          # toward the refcount or a legitimate later unpatch! would underflow against it. This
+          # branch only runs when @patched was false on entry (see `next if @patched` above), so
+          # forcing it back to false here is correct regardless of which line above raised —
+          # including a failure in the log call itself, after prepend already succeeded.
+          @patch_count -= 1
+          @patched = false
+          raise
+        end
+      end
     end
 
     def self.unpatch!
       # NOTE: With prepend, there's no clean way to unpatch
       # We'll mark it as unpatched so it can be re-patched
-      @patched = false
-      Coolhand.log "🔌 Faraday monitoring disabled ..."
+      @patch_mutex.synchronize do
+        @patch_count -= 1 if @patch_count.positive?
+        next if @patch_count.positive? || !@patched
+
+        @patched = false
+        Coolhand.log "🔌 Faraday monitoring disabled ..."
+      end
     end
 
     def self.patched?
       @patched
     end
 
+    # Testing-only: force a clean slate. Real callers should only ever use balanced
+    # patch!/unpatch! pairs.
+    def self.reset!
+      @patch_mutex.synchronize do
+        @patch_count = 0
+        @patched = false
+      end
+    end
+
     def request(req, body = nil, &block)
       return super unless NetHttpInterceptor.patched?
 
@@ -49,8 +98,16 @@ module Coolhand
       return super unless should_capture?
 
       # Capture body before setting the guard — if this raises we skip logging cleanly
-      # and the guard is never set, so there is no leak.
-      captured_body = capture_request_body(req, body)
+      # and the guard is never set, so there is no leak. A failure here (e.g. an
+      # already-consumed body_stream) must never prevent the real request below
+      # from being attempted — this gem must never be the reason the host
+      # app's actual LLM call doesn't happen.
+      captured_body = begin
+        capture_request_body(req, body)
+      rescue StandardError => e
+        Coolhand.log "❌ Error capturing request body: #{e.message}"
+        nil
+      end
 
       active[self] = true
       start_time = Time.now
@@ -59,7 +116,14 @@ module Coolhand
       status_code = nil
       response_body = nil
 
+      # Save/restore rather than just nil-ing: a request made from inside
+      # this request's own streaming block (nested interception) would
+      # otherwise clobber this request's in-progress buffer with its own
+      # chunks, mixing one request's content into another's log.
+      previous_stream_buffer = Thread.current[:coolhand_stream_buffer]
+      previous_capturing_stream = Thread.current[:coolhand_capturing_stream]
       Thread.current[:coolhand_stream_buffer] = nil
+      Thread.current[:coolhand_capturing_stream] = true
 
       begin
         response = super
@@ -73,7 +137,8 @@ module Coolhand
         raise
       ensure
         active.delete(self)
-        Thread.current[:coolhand_stream_buffer] = nil
+        Thread.current[:coolhand_stream_buffer] = previous_stream_buffer
+        Thread.current[:coolhand_capturing_stream] = previous_capturing_stream
         end_time = Time.now
         duration_ms = ((end_time - start_time) * 1000).round(2)
 
@@ -108,16 +173,41 @@ module Coolhand
     end
 
     def capture_request_body(req, body)
-      return parse_json(body) if body
-      return parse_json(req.body) if req.body
-
-      if req.respond_to?(:body_stream) && req.body_stream
+      # Check content-type before touching body_stream at all — for a binary
+      # upload (multipart/form-data, audio/*, etc.) this avoids reading the
+      # stream into memory a second time just to build a log entry no one
+      # can read anyway.
+      return skipped_capture_marker(req, "non_json_content_type") if binary_upload?(req)
+
+      content = body || req.body
+      if content.nil? && req.respond_to?(:body_stream) && req.body_stream
         content = req.body_stream.read
         req.body_stream = StringIO.new(content)
-        return parse_json(content)
       end
+      return nil if content.nil?
 
-      nil
+      cap_and_parse(content, req)
+    end
+
+    def binary_upload?(req)
+      content_type = req.respond_to?(:content_type) ? req.content_type : nil
+      content_type && !content_type.match?(/json/i)
+    end
+
+    def cap_and_parse(content, req)
+      max_bytes = Coolhand.configuration.max_captured_body_bytes
+      if max_bytes && content.bytesize > max_bytes
+        return skipped_capture_marker(req, "body_too_large", size_bytes: content.bytesize, max_bytes: max_bytes)
+      end
+
+      parse_json(content)
+    end
+
+    def skipped_capture_marker(req, reason, extra = {})
+      marker = { "_coolhand_capture_skipped" => reason }.merge(extra.transform_keys(&:to_s))
+      content_type = req.respond_to?(:content_type) ? req.content_type : nil
+      marker["content_type"] = content_type if content_type
+      marker
     end
 
     def extract_status_from_exception(e)
@@ -130,22 +220,62 @@ module Coolhand
 
     def intercept?(url)
       return false unless url && Coolhand.configuration.respond_to?(:intercept_addresses)
-      return false if excluded_by_pattern?(url)
 
-      Coolhand.configuration.intercept_addresses.any? { |a| url.include?(a) }
+      uri = safe_parse(url)
+      return false unless uri&.host
+
+      return false if excluded_by_pattern?(uri)
+
+      host = uri.host.downcase
+      addresses = Coolhand.configuration.intercept_addresses
+      return true if addresses.any? { |a| host_matches?(host, a) }
+
+      return false unless google_api_host_configured?(addresses)
+      return false unless host == "googleapis.com" || host.end_with?(".googleapis.com")
+
+      path = uri.path.to_s
+      Coolhand.configuration.intercept_path_patterns.any? { |p| path.include?(p) }
     end
 
-    def excluded_by_pattern?(url)
+    def excluded_by_pattern?(uri)
       patterns = Coolhand.configuration.exclude_api_patterns
       return false if patterns.nil? || patterns.empty?
 
-      matched = patterns.find { |pattern| url.include?(pattern) }
+      path = uri.path.to_s
+      matched = patterns.find { |pattern| path.include?(pattern) }
       if matched && Coolhand.configuration.debug_mode
-        Coolhand.log "🚫 Skipping capture for #{sanitize_url(url)} (matched exclude_api_pattern: \"#{matched}\")"
+        Coolhand.log "🚫 Skipping capture for #{sanitize_url(uri.to_s)} (matched exclude_api_pattern: \"#{matched}\")"
       end
       !!matched
     end
 
+    # intercept_path_patterns only ever applies to googleapis.com hosts, and only when the
+    # user still wants Google API traffic intercepted at all — otherwise overriding
+    # intercept_addresses to exclude Google hosts wouldn't actually stop Google API capture.
+    def google_api_host_configured?(addresses)
+      addresses.any? do |a|
+        a = a.to_s.downcase
+        a == "googleapis.com" || a.end_with?(".googleapis.com")
+      end
+    end
+
+    # Host-boundary match: exact, or a dot-delimited suffix (case-insensitive).
+    # A single "*" in `pattern` matches exactly one host label, e.g.
+    # "bedrock-runtime.*.amazonaws.com" matches "bedrock-runtime.us-east-1.amazonaws.com".
+    def host_matches?(host, pattern)
+      pattern = pattern.to_s.downcase
+      return host == pattern || host.end_with?(".#{pattern}") unless pattern.include?("*")
+
+      regex = /\A#{pattern.split('*', -1).map { |part| Regexp.escape(part) }.join('[^.]+')}\z/
+      !!(host =~ regex)
+    end
+
+    def safe_parse(url)
+      URI.parse(url)
+    rescue URI::InvalidURIError
+      nil
+    end
+
     def build_url_for_request(http, req)
       return req.path if %r{\Ahttps?://}.match?(req.path)
 

data/lib/coolhand/open_ai/batch_result_processor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../coolhand"
+
 module Coolhand
   module OpenAi
     class BatchResultProcessor
@@ -96,7 +98,7 @@ module Coolhand
             id: request_id,
             timestamp: timestamp,
             method: method.to_s.downcase,
-            url: url,
+            url: BaseInterceptor.sanitize_url(url),
             headers: {},
             request_body: request_body,
             response_headers: {},

data/lib/coolhand/open_ai/webhook_id_store.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module OpenAi
+    # Thread-safe, in-memory, TTL-bounded store used to detect replayed
+    # `webhook-id` values. This is the default for
+    # `Coolhand.configuration.webhook_id_store` and only dedupes within a
+    # single process - deployments running multiple processes/dynos should
+    # supply their own store (e.g. backed by Rails.cache) via configuration.
+    class WebhookIdStore
+      def initialize
+        @entries = {}
+        @mutex = Mutex.new
+      end
+
+      # Atomically checks-and-records `id` in a single critical section, so
+      # two concurrent replays of the same id can't both observe "unseen"
+      # before either records it. Returns true the first time `id` is
+      # claimed, false if it was already claimed within its TTL.
+      def claim!(id, ttl_seconds)
+        @mutex.synchronize do
+          prune
+          return false if @entries.key?(id)
+
+          @entries[id] = Time.now.to_i + ttl_seconds
+          true
+        end
+      end
+
+      def seen?(id)
+        @mutex.synchronize do
+          prune
+          @entries.key?(id)
+        end
+      end
+
+      private
+
+      def prune
+        now = Time.now.to_i
+        @entries.delete_if { |_id, expires_at| expires_at < now }
+      end
+    end
+  end
+end

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require "openssl"
+
+require_relative "webhook_id_store"
+
 module Coolhand
   module OpenAi
     class WebhookValidator
-      attr_reader :request, :errors, :payload, :webhook_secret
+      attr_reader :request, :errors, :payload
 
       def initialize(request, webhook_secret)
         @request = request
@@ -16,12 +20,12 @@ module Coolhand
         @payload = request.raw_post || request.body.read
 
         return false unless payload_valid?
-        return validate_in_non_production_env unless webhook_secret
+        return validate_in_non_production_env unless Coolhand.required_field?(webhook_secret)
 
         secret_bytes = extract_secret_bytes
         webhook_signature, webhook_timestamp, webhook_id = extract_webhook_headers
 
-        return validate_headers_in_non_production_env unless webhook_signature && webhook_timestamp
+        return validate_headers_in_non_production_env unless webhook_signature && webhook_timestamp && webhook_id
 
         verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
       end
@@ -32,11 +36,14 @@ module Coolhand
 
       private
 
+      attr_reader :webhook_secret
+
       def payload_valid?
         return true if @payload
 
         if should_enforce_strict_validation?
-          @errors << "Empty webhook payload - rejecting webhook in production/staging"
+          @errors << "Empty webhook payload - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+                     "not in development/test allowlist)"
           Rails.logger.error(@errors.last)
           false
         else
@@ -47,7 +54,8 @@ module Coolhand
 
       def validate_in_non_production_env
         if should_enforce_strict_validation?
-          @errors << "OpenAI webhook secret not configured - rejecting webhook in production/staging"
+          @errors << "OpenAI webhook secret not configured - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+                     "not in development/test allowlist)"
           Rails.logger.error(@errors.last)
           false
         else
@@ -76,8 +84,8 @@ module Coolhand
 
       def validate_headers_in_non_production_env
         if should_enforce_strict_validation?
-          @errors << "Missing OpenAI webhook signature or timestamp headers - " \
-                     "rejecting webhook in production/staging"
+          @errors << "Missing OpenAI webhook signature, timestamp, or id headers - " \
+                     "rejecting webhook (Rails.env=#{Rails.env.inspect} not in development/test allowlist)"
           Rails.logger.error(@errors.last)
           false
         else
@@ -92,13 +100,43 @@ module Coolhand
 
         signature_valid = webhook_signature.start_with?("v1,") &&
                           secure_compare(webhook_signature[3..], expected_signature)
-        if signature_valid
-          true
-        else
+
+        unless signature_valid
           @errors << "OpenAI webhook signature verification failed"
           Rails.logger.error(@errors.last)
-          false
+          return false
         end
+
+        return false unless timestamp_fresh?(webhook_timestamp)
+        return false unless webhook_id_unused?(webhook_id)
+
+        true
+      end
+
+      # Checked only after the signature is confirmed valid, so an
+      # unsigned/forged request can't poison the id-dedup store (or fail a
+      # freshness check) and DoS a later legitimate webhook with the same id.
+      def timestamp_fresh?(webhook_timestamp)
+        tolerance = Coolhand.configuration.webhook_replay_tolerance_seconds
+        age = (Time.now.to_i - webhook_timestamp.to_i).abs
+        return true if age <= tolerance
+
+        @errors << "OpenAI webhook timestamp outside replay-protection tolerance window"
+        Rails.logger.error(@errors.last)
+        false
+      end
+
+      def webhook_id_unused?(webhook_id)
+        tolerance = Coolhand.configuration.webhook_replay_tolerance_seconds
+        return true if id_store.claim!(webhook_id, tolerance)
+
+        @errors << "OpenAI webhook id already processed (replay protection)"
+        Rails.logger.error(@errors.last)
+        false
+      end
+
+      def id_store
+        Coolhand.configuration.webhook_id_store
       end
 
       def secure_compare(a, b)
@@ -120,7 +158,7 @@ module Coolhand
       end
 
       def should_enforce_strict_validation?
-        ["production", "staging"].include?(Rails.env)
+        !%w[development test].include?(Rails.env)
       end
     end
   end

data/lib/coolhand/pagination.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Paging state for a v2 list endpoint. These send a bare JSON array and carry paging in the
+  # `X-Page`, `X-Per-Page`, `X-Total-Count` and `X-Total-Pages` headers, never in the body.
+  Pagination = Struct.new(
+    :current_page,
+    :per_page,
+    :total_count,
+    :total_pages,
+    :has_next_page,
+    :has_prev_page,
+    keyword_init: true
+  )
+
+  class Pagination
+    # Mirrors of the v2 controllers' values, used only to fill a header the server did not send.
+    DEFAULT_PER_PAGE = 25
+    MAX_PER_PAGE = 100
+
+    class << self
+      def from_headers(response, items:, page: nil, per: nil)
+        requested_page = positive_int(page) || 1
+        requested_per = [positive_int(per) || DEFAULT_PER_PAGE, MAX_PER_PAGE].min
+
+        current_page = header_int(response, "X-Page") || requested_page
+        per_page = header_int(response, "X-Per-Page") || requested_per
+        reported_total_pages = header_int(response, "X-Total-Pages")
+        total_count = header_int(response, "X-Total-Count") || fallback_total_count(current_page, per_page, items)
+        total_pages = reported_total_pages || fallback_total_pages(total_count, per_page)
+
+        new(
+          current_page: current_page,
+          per_page: per_page,
+          total_count: total_count,
+          total_pages: total_pages,
+          has_next_page: next_page?(reported_total_pages, current_page, per_page, items),
+          has_prev_page: current_page > 1
+        ).freeze
+      end
+
+      private
+
+      # Falling back to the computed totals here would report "no next page" for a full page, and
+      # silently truncate a caller's loop.
+      def next_page?(reported_total_pages, current_page, per_page, items)
+        return current_page < reported_total_pages if reported_total_pages
+        return false unless per_page.positive?
+
+        items.size >= per_page
+      end
+
+      # A lower bound, not a count: every earlier page assumed full, plus this page.
+      def fallback_total_count(current_page, per_page, items)
+        return items.size unless per_page.positive?
+
+        [((current_page - 1) * per_page) + items.size, items.size].max
+      end
+
+      def fallback_total_pages(total_count, per_page)
+        return total_count.positive? ? 1 : 0 unless per_page.positive?
+
+        (total_count.to_f / per_page).ceil
+      end
+
+      # Neither `Integer()` nor `to_i` is safe alone: the first raises on `""`, the second turns
+      # `"3.5"` into `3` and `"nonsense"` into `0` — a fabricated, legitimate-looking count.
+      def header_int(response, name)
+        raw = response[name]
+        return nil if raw.nil?
+
+        value = raw.strip
+        value.match?(/\A\d+\z/) ? value.to_i : nil
+      end
+
+      def positive_int(value)
+        integer = Integer(value, exception: false)
+        integer&.positive? ? integer : nil
+      end
+    end
+  end
+end

data/lib/coolhand/read_requests.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require_relative "errors"
+
+module Coolhand
+  # The GET half of {ApiService}, split out to keep that class inside this repo's 200-line budget.
+  #
+  # Reads raise where writes log-and-return-nil, on purpose: a write is instrumentation inline in
+  # the host app's request, while a read's caller must tell a 404 from a timeout from an empty result.
+  module ReadRequests
+    # 60s is deliberate, not a slip: writes allow 5, but the server bounds each *statement* at 10s
+    # and one response runs several. A tighter read timeout pre-empts the 504 callers should retry.
+    READ_OPEN_TIMEOUT = 5
+    READ_TIMEOUT = 60
+
+    # ERROR_BODY_LIMIT caps the message; this caps the body the exception object itself carries.
+    RETAINED_ERROR_BODY_LIMIT = 8_000
+
+    protected
+
+    def get_json(url, noun)
+      body, = get_json_with_headers(url, noun)
+      body
+    end
+
+    # Also returns the response, for endpoints that carry pagination in headers rather than the body.
+    def get_json_with_headers(url, noun)
+      raise Error, "#{noun} request failed: an API key is required" unless Coolhand.required_field?(api_key)
+
+      response = perform_get(url, noun)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise HttpError.new(
+          "#{noun} request failed (#{response.code}): #{format_error_body(response.body)}",
+          status: response.code.to_i,
+          body: retained_error_body(response.body)
+        )
+      end
+
+      [parse_json_body(response.body, noun), response]
+    end
+
+    private
+
+    def perform_get(url, noun)
+      uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = READ_OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
+
+      # Net::HTTP does not follow redirects, so a 3xx raises rather than replaying the API key at
+      # an unapproved host. without_capture is the same recursion guard send_request uses.
+      Coolhand.without_capture { http.request(request) }
+    rescue StandardError => e
+      raise Error, "#{noun} request failed: #{e.message}"
+    end
+
+    def retained_error_body(body)
+      return body if body.nil? || body.length <= RETAINED_ERROR_BODY_LIMIT
+
+      "#{body[0, RETAINED_ERROR_BODY_LIMIT]}... [truncated]"
+    end
+
+    def parse_json_body(body, noun)
+      JSON.parse(body.to_s, symbolize_names: true)
+    rescue JSON::ParserError
+      raise Error, "#{noun} response was not valid JSON: #{format_error_body(body)}"
+    end
+  end
+end