coolhand 0.5.1 → 0.7.0

data/lib/coolhand/net_http_interceptor.rb

@@ -24,36 +24,77 @@ 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?
 
       active = (Thread.current[:coolhand_active_requests] ||= {}.compare_by_identity)
       return super if active.key?(self)
 
-      url = build_url_for_request(self, req)
-      return super unless intercept?(url)
-      return super unless should_capture?
+      url = capturable_url(req)
+      return super unless url
 
       # Capture body before setting the guard — if this raises we skip logging cleanly
       # and the guard is never set, so there is no leak. A failure here (e.g. an
@@ -131,16 +172,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)
@@ -153,22 +219,93 @@ 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.chomp(".")
+      path = uri.path.to_s
+      addresses = Coolhand.configuration.intercept_addresses
+      authorities = [host, "#{host}:#{uri.port}"]
+      return true if addresses.any? { |a| authorities.any? { |authority| address_matches?(authority, path, a) } }
+
+      return false unless google_api_host_configured?(addresses)
+      return false unless host == "googleapis.com" || host.end_with?(".googleapis.com")
+
+      Coolhand.configuration.intercept_path_patterns.any? { |p| path.include?(p) }
+    end
+
+    # The capture decision runs before the host's real request, so a bad config value (e.g. a
+    # non-array exclude_api_patterns) must degrade to "don't capture", never raise into the host.
+    def capturable_url(req)
+      url = build_url_for_request(self, req)
+      url if intercept?(url) && should_capture?
+    rescue StandardError => e
+      Coolhand.log "⚠️ Skipping capture, could not evaluate intercept rules: #{e.class}"
+      nil
     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
+
+    # An intercept_addresses entry may optionally pin a port ("host:port") and/or anchor to a
+    # path prefix by embedding a "/" — e.g. "api.cohere.com/v2/chat" only matches requests to
+    # that host whose path starts with "/v2/chat", and "cognitiveservices.azure.com/openai/" only
+    # matches that multi-service Azure host's OpenAI paths, so unrelated endpoints on a shared
+    # host aren't swept in alongside the ones we mean to capture.
+    # The match is on a path *segment* boundary (trailing "/" on the pattern is optional and
+    # stripped before comparing), so "host.com/openai" matches "/openai" and "/openai/x" but not
+    # a same-prefix-but-different-segment path like "/openaiz".
+    def address_matches?(host, path, pattern)
+      host_pattern, sep, path_pattern = pattern.to_s.partition("/")
+      return host_matches?(host, host_pattern) if sep.empty?
+      return false unless host_matches?(host, host_pattern)
+
+      path_pattern = path_pattern.delete_suffix("/")
+      return true if path_pattern.empty?
+
+      prefix = "/#{path_pattern}"
+      path == prefix || path.start_with?("#{prefix}/")
+    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

@@ -98,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

@@ -2,6 +2,8 @@
 
 require "openssl"
 
+require_relative "webhook_id_store"
+
 module Coolhand
   module OpenAi
     class WebhookValidator
@@ -23,7 +25,7 @@ module Coolhand
         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
@@ -40,7 +42,8 @@ module Coolhand
         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
@@ -51,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
@@ -80,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
@@ -94,15 +98,46 @@ module Coolhand
         signed_payload = "#{webhook_id}.#{webhook_timestamp}.#{@payload}"
         expected_signature = calculate_expected_signature(secret_bytes, signed_payload)
 
-        signature_valid = webhook_signature.start_with?("v1,") &&
+        # An empty key (a bare "whsec_" secret) makes the HMAC forgeable by anyone, so never accept it.
+        signature_valid = !secret_bytes.empty? && 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)
@@ -124,7 +159,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

data/lib/coolhand/template_service.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "api_service"
+require_relative "pagination"
+
+module Coolhand
+  # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
+  TemplateSearchResult = Struct.new(:templates, :pagination, keyword_init: true)
+
+  # Read-only. Requires the client's **private** key — the public key is write-only here and is
+  # rejected like an invalid one.
+  #
+  # Not a port of the MCP `search_templates` tool and does not agree with its `log_count`.
+  # See docs/template-search.md.
+  class TemplateService < ApiService
+    ERROR_NOUN = "Template"
+    BLANK_ID_MESSAGE = "get_template: id must be a non-empty template hashid"
+
+    def initialize
+      super("v2/llm_request_templates")
+    end
+
+    # Filters, error semantics and server behaviour: docs/template-search.md.
+    def search_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil,
+      include_system: nil, page: nil, per: nil)
+      query = {
+        search: search,
+        workload_id: workload_id,
+        status: status,
+        include_deprecated: include_deprecated,
+        include_system: include_system,
+        page: page,
+        per: per
+      }.compact
+
+      templates, response = get_json_with_headers(list_url(query), ERROR_NOUN)
+      raise Error, "#{ERROR_NOUN} response was not a JSON array" unless templates.is_a?(Array)
+
+      TemplateSearchResult.new(
+        templates: templates,
+        pagination: Pagination.from_headers(response, items: templates, page: page, per: per)
+      ).freeze
+    end
+
+    # Adds `user_prompt_pattern` / `system_prompt_pattern`, which the list omits, and unlike the
+    # list reaches deprecated and system templates by id with no opt-in flag.
+    def get_template(id)
+      get_json(resource_url(id), ERROR_NOUN)
+    end
+
+    private
+
+    def list_url(query)
+      uri = URI.parse(api_endpoint)
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    def resource_url(id)
+      raise Error, BLANK_ID_MESSAGE unless id.is_a?(String)
+
+      trimmed = id.strip
+      # A blank id resolves to the index route (bare array, not one template); a bare dot segment
+      # retargets the request at another path. Neither would 404, so both are rejected here.
+      raise Error, BLANK_ID_MESSAGE if trimmed.empty? || [".", ".."].include?(trimmed)
+
+      URI.parse("#{api_endpoint}/#{escape_path_segment(trimmed)}")
+    end
+
+    # Escapes to RFC 3986 unreserved, so an id carrying `/`, `?` or `#` cannot retarget the request.
+    def escape_path_segment(value)
+      URI::DEFAULT_PARSER.escape(value, /[^A-Za-z0-9\-._~]/)
+    end
+  end
+end

data/lib/coolhand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coolhand
-  VERSION = "0.5.1"
+  VERSION = "0.7.0"
 end