coolhand 0.5.1 → 0.7.0

data/docs/vertex.md

@@ -6,6 +6,8 @@ For monitoring regular (non-batch) Vertex AI calls, no extra setup is required b
 
 Requires Rails — `Coolhand::Vertex::BatchResultProcessor` logs via `Rails.logger` internally. `config.capture = false` and `Coolhand.without_capture` do not suppress these logs: unlike the passive Net::HTTP interceptor, calling this processor is an explicit, deliberate act, so it always sends.
 
+> **Note:** As of May 2026, Google markets this product as "Gemini Enterprise Agent Platform" rather than "Vertex AI." The API endpoint (`aiplatform.googleapis.com`) and Ruby SDK are unchanged — it's a console/marketing rename, not an SDK rename — so `Coolhand::Vertex` naming stays accurate here. It's also still a distinct integration from the separate Gemini Developer API (`generativelanguage.googleapis.com`), which Coolhand intercepts independently.
+
 ## Usage
 
 ```ruby

data/lib/coolhand/api_service.rb

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

@@ -11,7 +11,7 @@ module Coolhand
     # (cookie, set-cookie), and future/unknown providers using a
     # similarly-named header. Shared with LoggerService so the two logging
     # paths (interceptor + webhook forwarding) stay consistent.
-    SENSITIVE_HEADER_PATTERN = /key|token|secret|signature|authorization|cookie/i
+    SENSITIVE_HEADER_PATTERN = /key|token|secret|signature|auth|passw|credential|bearer|jwt|session|cookie/i
 
     def sanitize_headers(headers)
       return {} if headers.nil?
@@ -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,27 +82,70 @@ 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]
+      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 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
+      # Fail closed: an unparseable URL can't be checked param-by-param, so drop everything
+      # that could carry a credential (userinfo, query, fragment) rather than pass it through.
+      url.to_s.sub(%r{//[^/?#]*@}, "//REDACTED@").split(/[?#]/, 2).first
+    end
+
+    # Key names inside an Azure OpenAI "On Your Data" data_sources/dataSources entry that carry
+    # live datastore credentials in the request body, where header/query-param sanitization never
+    # looks. Matched against a separator-stripped, lowercased key name so both `connection_string`
+    # and `connectionString` (Cosmos/Mongo, embeds `AccountKey=...`) and `encoded_api_key`
+    # (Elasticsearch) are caught — not just exact or snake_case-only names.
+    SENSITIVE_BODY_KEY_PATTERN = /key|token|secret|passw|pwd|credential|bearer|jwt|connectionstring|signature/i
+
+    def sanitize_body(body)
+      return body unless body.is_a?(Hash)
+
+      sanitized = body.dup
+      sanitized.each_key do |key|
+        next unless key.to_s.delete("_-").casecmp?("datasources")
+
+        sanitized[key] = redact_sensitive_body_values(sanitized[key])
       end
+      sanitized
+    end
 
-      if redacted
-        uri.query = URI.encode_www_form(params)
-        uri.to_s
+    def redact_sensitive_body_values(node)
+      case node
+      when Hash
+        node.each_with_object({}) do |(k, v), acc|
+          normalized = k.to_s.gsub(/[_\-\s]/, "").downcase
+          acc[k] = normalized.match?(SENSITIVE_BODY_KEY_PATTERN) ? "[REDACTED]" : redact_sensitive_body_values(v)
+        end
+      when Array
+        node.map { |v| redact_sensitive_body_values(v) }
       else
-        url
+        node
       end
-    rescue URI::InvalidURIError
-      url
     end
 
     def send_complete_request_log(request_id:, method:, url:, request_headers:, request_body:, response_headers:,
@@ -111,7 +156,7 @@ module Coolhand
         method: method.to_s.downcase,
         url: sanitize_url(url),
         headers: sanitize_headers(request_headers),
-        request_body: request_body,
+        request_body: sanitize_body(request_body),
         response_headers: sanitize_headers(response_headers),
         response_body: response_body,
         status_code: status_code,

data/lib/coolhand/configuration.rb

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

@@ -1,9 +1,21 @@
 # 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/"]
 # Users can disable:           c.exclude_api_patterns = []
 
 - "/batchPredictionJobs/"
+# Azure OpenAI control-plane paths (not inference) — both spellings are needed
+# since substring matching is contiguous: "/openai/files" does not match
+# "/openai/v1/files".
+- "/openai/files"
+- "/openai/batches"
+- "/openai/fine_tuning"
+- "/openai/models"
+- "/openai/v1/files"
+- "/openai/v1/batches"
+- "/openai/v1/fine_tuning"
+- "/openai/v1/models"

data/lib/coolhand/default_intercept_addresses.yml

@@ -1,9 +1,19 @@
 # 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.
+# An entry may also pin a port and/or a path prefix: "host:port", "host/path",
+# or "host:port/path" (the path match is on a segment boundary) — useful for
+# multi-service hosts where unrelated APIs (e.g. Azure Speech, Vision, Language)
+# share a domain with the LLM inference path.
 #
 # 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 +21,58 @@
 - "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"
+- "api.deepseek.com"
+- "api.mistral.ai"
+- "api.perplexity.ai"
+- "api.x.ai"
+# Cohere is path-scoped, never host-wide: the server only ingests v2 chat and
+# v1/v2 embed, and its other endpoints (v1 chat, rerank, tokenize, classify...)
+# have different envelopes that would be recorded as empty "successes".
+- "api.cohere.com/v2/chat"
+- "api.cohere.com/v1/embed"
+- "api.cohere.com/v2/embed"
+- "api.cohere.ai/v2/chat"
+- "api.cohere.ai/v1/embed"
+- "api.cohere.ai/v2/embed"
+# TypeSafe Jev (a "System One" model, not an LLM) — only /v1/systemone is ingested.
+- "api.typesafe.ai/v1/systemone"
+# Ollama (self-hosted) has no fixed host, so an entry must pin BOTH the default
+# port (11434) and the path — a bare "/api/chat" would capture any app's own
+# unrelated chat endpoint. "*" matches one host label (localhost, an "ollama"
+# compose service, a bare hostname); a LAN IP or dotted host needs its own
+# entry, e.g. "192.168.1.5:11434/api/chat".
+- "*:11434/api/chat"
+- "*:11434/api/generate"
+- "*:11434/api/embed"
+- "*:11434/api/embeddings"
+- "127.0.0.1:11434/api/chat"
+- "127.0.0.1:11434/api/generate"
+- "127.0.0.1:11434/api/embed"
+- "127.0.0.1:11434/api/embeddings"
 - "openrouter.ai"
+- "opencode.ai"
+# Azure OpenAI dedicated hosts (commercial, US Gov, China/21Vianet)
+- "openai.azure.com"
+- "openai.azure.us"
+- "openai.azure.cn"
+# Azure AI Services / Foundry multi-service hosts — path-anchored so Speech,
+# Vision, Language and Content Safety on the same host are NOT captured
+- "cognitiveservices.azure.com/openai/"
+- "cognitiveservices.azure.com/models/"
+- "cognitiveservices.azure.us/openai/"
+- "cognitiveservices.azure.us/models/"
+- "cognitiveservices.azure.cn/openai/"
+- "cognitiveservices.azure.cn/models/"
+- "services.ai.azure.com/openai/"
+- "services.ai.azure.com/models/"
+- "services.ai.azure.us/openai/"
+- "services.ai.azure.us/models/"
+# Serverless / MaaS + Azure ML managed online endpoints. inference.ml.azure.*
+# is deliberately unanchored — see docs/configuration.md for why.
+- "inference.ai.azure.com"
+- "models.ai.azure.com"
+- "inference.ml.azure.com"
+- "inference.ml.azure.us"

data/lib/coolhand/default_intercept_path_patterns.yml

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

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