RubyGems - coolhand - Versions diffs - 0.5.1 → 0.6.0 - Mend

coolhand 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

checksums.yaml +4 -4
data/AGENTS.harness.md +139 -0
data/CHANGELOG.md +31 -0
data/README.md +30 -1
data/docs/configuration.md +40 -0
data/docs/openai.md +31 -0
data/docs/template-search.md +218 -0
data/lib/coolhand/api_service.rb +49 -15
data/lib/coolhand/base_interceptor.rb +27 -17
data/lib/coolhand/configuration.rb +37 -4
data/lib/coolhand/default_exclude_api_patterns.yml +3 -2
data/lib/coolhand/default_intercept_addresses.yml +10 -5
data/lib/coolhand/default_intercept_path_patterns.yml +12 -0
data/lib/coolhand/errors.rb +19 -0
data/lib/coolhand/logger_service.rb +1 -1
data/lib/coolhand/net_http_interceptor.rb +127 -20
data/lib/coolhand/open_ai/batch_result_processor.rb +1 -1
data/lib/coolhand/open_ai/webhook_id_store.rb +45 -0
data/lib/coolhand/open_ai/webhook_validator.rb +44 -10
data/lib/coolhand/pagination.rb +82 -0
data/lib/coolhand/read_requests.rb +77 -0
data/lib/coolhand/template_service.rb +76 -0
data/lib/coolhand/version.rb +1 -1
data/lib/coolhand.rb +9 -4
metadata +10 -2

data/lib/coolhand/api_service.rb CHANGED Viewed

@@ -4,9 +4,19 @@ require "net/http"
 require "uri"
 require "json"
 require_relative "collector"
+require_relative "errors"
+require_relative "read_requests"
 module Coolhand
   class ApiService
+    # The GET half of this class. See Coolhand::ReadRequests for why reads raise where writes
+    # log and return nil.
+    include ReadRequests
+    # Caps how much of a failed response body is interpolated into a log line or an exception
+    # message. Without it an oversized body from a proxy or gateway becomes the message.
+    ERROR_BODY_LIMIT = 2000
     attr_reader :api_endpoint
     def initialize(endpoint = "v2/llm_request_logs")
@@ -77,12 +87,7 @@ module Coolhand
       http.read_timeout = 5
       request = Net::HTTP::Post.new(uri.request_uri)
-      headers = create_request_options(payload)
-      headers.each do |key, value|
-        # Ensure header values are UTF-8 encoded
-        encoded_value = value.is_a?(String) ? value.dup.force_encoding("UTF-8") : value
-        request[key] = encoded_value
-      end
+      apply_headers(request, create_request_options(payload))
       # Clean payload and ensure UTF-8 encoding before JSON generation
       cleaned_payload = sanitize_payload_for_json(payload)
@@ -105,14 +110,7 @@ module Coolhand
           log success_message
           result
         else
-          body = response.body.force_encoding("UTF-8") if response.body
-          # Only show first part of HTML error pages
-          error_msg = if body&.include?("<!DOCTYPE html>")
-            "#{body[0..200]}... [HTML error page truncated]"
-          else
-            body
-          end
-          log "❌ Request failed: #{response.code} - #{error_msg}"
+          log "❌ Request failed: #{response.code} - #{format_error_body(response.body)}"
           nil
         end
       rescue StandardError => e
@@ -210,6 +208,26 @@ module Coolhand
     private
+    # Shared by the write path's failure log and the read path's raised message, so a large
+    # response body never dumps a whole document into either. An HTML error page (a proxy's 502,
+    # say) is cut short hard; anything else keeps enough to diagnose from and no more.
+    def format_error_body(body)
+      return nil if body.nil?
+      text = body.dup.force_encoding("UTF-8")
+      return "#{text[0..200]}... [HTML error page truncated]" if text.include?("<!DOCTYPE html>")
+      return text if text.length <= ERROR_BODY_LIMIT
+      "#{text[0, ERROR_BODY_LIMIT]}... [truncated]"
+    end
+    def apply_headers(request, headers)
+      headers.each do |key, value|
+        # Net::HTTP rejects header values that are not UTF-8.
+        request[key] = value.is_a?(String) ? value.dup.force_encoding("UTF-8") : value
+      end
+    end
     def missing_api_key?
       return false if Coolhand.required_field?(api_key)
@@ -281,8 +299,24 @@ module Coolhand
       return if silent
       puts "\n🎉 LOGGING OpenAI API Call #{@api_endpoint}"
-      puts captured_data
+      if debug_mode?
+        puts captured_data
+      else
+        puts request_body_summary(captured_data)
+      end
       puts "📤 Sending to: #{@api_endpoint}"
     end
+    def request_body_summary(captured_data)
+      return "captured_data: (unavailable)" unless captured_data.is_a?(Hash)
+      id = captured_data[:id] || captured_data["id"] || "N/A"
+      body = captured_data[:request_body] || captured_data["request_body"]
+      "id: #{id}, request_body: #{body.to_json.bytesize} bytes"
+    rescue StandardError
+      "captured_data: (unavailable)"
+    end
   end
 end

data/lib/coolhand/base_interceptor.rb CHANGED Viewed

@@ -23,7 +23,9 @@ module Coolhand
         begin
           headers.to_hash.transform_keys(&:to_s).transform_values { |v| normalize_header_value(v) }
         rescue StandardError
-          # fall through to other enumeration strategies
+          # Deliberately fails closed to an empty hash rather than trying each_header/each on
+          # this object next — an object whose own to_hash raises is untrustworthy enough that
+          # guessing at another enumeration strategy isn't worth the risk of a second failure.
           nil
         end
       elsif headers.respond_to?(:each_header)
@@ -80,25 +82,33 @@ module Coolhand
     def sanitize_url(url)
       uri = URI.parse(url)
-      return url unless uri.query
-      params = URI.decode_www_form(uri.query)
-      redacted = false
-      params.map! do |n, v|
-        if n.match?(SENSITIVE_QUERY_PARAM_PATTERN)
-          redacted = true
-          [n, "[REDACTED]"]
-        else
-          [n, v]
-        end
+      modified = false
+      if uri.userinfo
+        # URI userinfo syntax disallows "[" / "]", so this can't reuse the [REDACTED]
+        # placeholder used elsewhere.
+        uri.userinfo = "REDACTED"
+        modified = true
       end
-      if redacted
-        uri.query = URI.encode_www_form(params)
-        uri.to_s
-      else
-        url
+      if uri.query
+        params = URI.decode_www_form(uri.query)
+        redacted_query = false
+        params.map! do |n, v|
+          if n.match?(SENSITIVE_QUERY_PARAM_PATTERN)
+            redacted_query = true
+            [n, "[REDACTED]"]
+          else
+            [n, v]
+          end
+        end
+        if redacted_query
+          uri.query = URI.encode_www_form(params)
+          modified = true
+        end
       end
+      modified ? uri.to_s : url
     rescue URI::InvalidURIError
       url
     end

data/lib/coolhand/configuration.rb CHANGED Viewed

@@ -3,6 +3,8 @@
 require "yaml"
 require "uri"
+require_relative "open_ai/webhook_id_store"
 module Coolhand
   # Handles all configuration settings for the gem.
   class Configuration
@@ -14,11 +16,21 @@ module Coolhand
       File.join(__dir__, "default_intercept_addresses.yml")
     ).freeze
+    DEFAULT_INTERCEPT_PATH_PATTERNS = YAML.safe_load_file(
+      File.join(__dir__, "default_intercept_path_patterns.yml")
+    ).freeze
     BASE_URL_ERROR_MSG = "base_url must use https:// (or http://localhost / http://127.0.0.1 for local dev)"
     LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
-    attr_accessor :api_key, :environment, :silent, :debug_mode, :capture, :exclude_api_patterns, :enabled
-    attr_reader :intercept_addresses, :base_url
+    # 1 MB — generous for real chat/completion payloads, small enough to stop
+    # a multi-MB file upload from being logged in full when its content-type
+    # happens to look JSON-ish (or is unset).
+    DEFAULT_MAX_CAPTURED_BODY_BYTES = 1_000_000
+    attr_accessor :api_key, :environment, :silent, :debug_mode, :capture, :exclude_api_patterns, :enabled,
+      :max_captured_body_bytes, :webhook_replay_tolerance_seconds, :webhook_id_store
+    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url
     def initialize
       # Set defaults
@@ -26,20 +38,41 @@ module Coolhand
       @api_key = nil
       @silent = false
       @intercept_addresses = DEFAULT_INTERCEPT_ADDRESSES.dup
+      @intercept_path_patterns = DEFAULT_INTERCEPT_PATH_PATTERNS.dup
       self.base_url = "https://coolhandlabs.com/api"
       @debug_mode = false
       @capture = true
       @exclude_api_patterns = DEFAULT_EXCLUDE_API_PATTERNS.dup
       @enabled = true
+      @max_captured_body_bytes = DEFAULT_MAX_CAPTURED_BODY_BYTES
+      @webhook_replay_tolerance_seconds = 300
+      @webhook_id_store = Coolhand::OpenAi::WebhookIdStore.new
     end
-    # Custom setter that preserves defaults when nil/empty array is provided
+    # intercept_addresses is a required allow-list: NetHttpInterceptor#intercept? only
+    # captures a request whose URL matches an entry here, so an empty list would mean
+    # "never capture anything" (validate! deliberately rejects that). Unlike
+    # exclude_api_patterns, `= []` is not a supported way to disable it — use
+    # config.enabled = false or config.capture = false to disable capture entirely.
+    # nil/empty here is treated as "leave the current value alone" rather than cleared.
     def intercept_addresses=(value)
-      return if value.nil? || (value.is_a?(Array) && value.empty?)
+      if value.nil? || (value.is_a?(Array) && value.empty?)
+        Coolhand.log "⚠️  Coolhand: intercept_addresses = #{value.inspect} is ignored " \
+                     "(would disable capture entirely) — keeping the current value. " \
+                     "Use config.enabled = false or config.capture = false to disable capture."
+        return
+      end
       @intercept_addresses = value.is_a?(Array) ? value : [value]
     end
+    # Custom setter that preserves defaults when nil/empty array is provided
+    def intercept_path_patterns=(value)
+      return if value.nil? || (value.is_a?(Array) && value.empty?)
+      @intercept_path_patterns = value.is_a?(Array) ? value : [value]
+    end
     def base_url=(value)
       stripped = value&.sub(%r{/+\z}, "")
       raise Error, BASE_URL_ERROR_MSG unless stripped.nil? || valid_base_url?(stripped)

data/lib/coolhand/default_exclude_api_patterns.yml CHANGED Viewed

@@ -1,6 +1,7 @@
 # Coolhand default exclude API patterns
-# These substrings are matched against request URLs after the intercept_addresses
-# allow-list passes. Matching URLs are skipped and not forwarded as llm_request_logs.
+# These substrings are matched against the request's path (not the full URL or
+# query string). A request whose path matches is skipped and not forwarded as
+# an llm_request_log, regardless of whether it would otherwise match intercept_addresses.
 #
 # Users can extend defaults:   c.exclude_api_patterns << "/myOperationalPath/"
 # Users can override entirely: c.exclude_api_patterns = ["/only_this/"]

data/lib/coolhand/default_intercept_addresses.yml CHANGED Viewed

@@ -1,9 +1,15 @@
 # Coolhand default intercept addresses
-# These substrings are matched against request URLs to decide whether a request
-# should be captured and forwarded as an llm_request_log.
+# These are matched against the request's parsed host (exact match, or a
+# dot-boundary suffix match, case-insensitive) to decide whether a request
+# should be captured and forwarded as an llm_request_log. A single "*" in an
+# entry matches exactly one host label — e.g. "bedrock-runtime.*.amazonaws.com"
+# matches "bedrock-runtime.us-east-1.amazonaws.com" but nothing else.
 #
 # Users can extend defaults:   c.intercept_addresses << "my.custom.api.com"
 # Users can override entirely: c.intercept_addresses = ["only.this.com"]
+# This list cannot be emptied — it's required (unlike exclude_api_patterns, which
+# can be disabled with `= []`). To disable capture entirely, use
+# c.enabled = false or c.capture = false instead.
 - "api.openai.com"
 - "api.anthropic.com"
@@ -11,9 +17,8 @@
 - "generativelanguage.googleapis.com"
 - "models.github.ai"
 - "models.inference.ai.azure.com"
-- ":generateContent"
-- ":streamGenerateContent"
 - "aiplatform.googleapis.com"
 - "gateway.ai.cloudflare.com"
-- "bedrock-runtime"
+- "bedrock-runtime.*.amazonaws.com"
 - "openrouter.ai"
+- "opencode.ai"

data/lib/coolhand/default_intercept_path_patterns.yml ADDED Viewed

@@ -0,0 +1,12 @@
+# Colon-action path suffixes from Google's API Discovery convention
+# (e.g. ".../v1beta/models/gemini-pro:generateContent"). These have no host
+# component of their own, so — unlike intercept_addresses — they are only
+# ever matched against the *path* of requests whose host is already
+# googleapis.com or a googleapis.com subdomain. They can never match on
+# their own against an unrelated/attacker-controlled host.
+#
+# Users can extend defaults:   c.intercept_path_patterns << ":myAction"
+# Users can override entirely: c.intercept_path_patterns = [":onlyThis"]
+- ":generateContent"
+- ":streamGenerateContent"

data/lib/coolhand/errors.rb ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -24,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?
@@ -131,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)
@@ -153,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 CHANGED Viewed

@@ -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 ADDED Viewed

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