coolhand 0.4.0 → 0.5.1

data/docs/vertex.md

@@ -0,0 +1,54 @@
+# Google Vertex AI Batch Result Logging
+
+Log completed Google Vertex AI batch prediction job results the same way regular synchronous calls are logged. Unlike the [OpenAI batch handler](openai.md), this is not webhook-driven — you call `Coolhand::Vertex::BatchResultProcessor` directly from your own batch-job callback/polling code.
+
+For monitoring regular (non-batch) Vertex AI calls, no extra setup is required beyond `Coolhand.configure` — `aiplatform.googleapis.com` is intercepted by default.
+
+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.
+
+## Usage
+
+```ruby
+require "coolhand/vertex/batch_result_processor"
+```
+
+- Call the `Coolhand::Vertex::BatchResultProcessor` service with `batch_info` and the downloaded batch results.
+- Optionally pass `model:` to populate the logged `model` field. It falls back to a `"model"` key in `batch_info` if present, and is omitted from the payload entirely when neither is available. If the value (from either source) looks like a Vertex model resource path (`publishers/<publisher>/models/<id>` or `projects/<project>/locations/<location>/models/<id>`), it's normalized down to just the trailing id/version before being logged; any other string is sent as-is.
+- `batch_info["name"]` must be the exact Vertex job resource name (`projects/<project>/locations/<location>/batchPredictionJobs/<job-id>`), and `batch_info["startTime"]`/`["endTime"]` must be valid ISO 8601 timestamps — a batch with a missing or malformed resource name or timestamps is skipped entirely (logged as an error) rather than sent with a broken URL.
+- If `endTime` precedes `startTime` (e.g. clock skew), the batch is still logged — `duration_ms` is clamped to `0` and a warning is logged — rather than dropping the results.
+- Each element of the `batch_results` array passed to `.call` must be a `Hash` with a `"request"` and/or `"response"` key (the request/response body to log for that item — either key alone is accepted). Any other shape is treated as malformed and skipped, with the skip counted in a `Rails.logger.warn` summary rather than raised.
+
+## Minimal example
+
+Only the key lines are shown — wire this into your own batch callback service.
+
+```ruby
+class Vertex::BatchCallbackProcessor < BaseService
+  option :batch_request, model: BatchApiRequest
+  option :batch_info
+
+  def call
+    case batch_info["state"]
+    when "JOB_STATE_PENDING"
+      nil
+    when "JOB_STATE_RUNNING", "JOB_STATE_QUEUED"
+      batch_request.update!(status: "processing")
+
+      Coolhand::Vertex::BatchResultProcessor.new(batch_info:).call
+    when "JOB_STATE_SUCCEEDED"
+      output_file_id = batch_info["outputInfo"]["gcsOutputDirectory"]
+      results = download_batch_results(output_file_id)
+      results.each { |batch_item| process_batch_result(batch_item) }
+
+      batch_request.update!(status: "completed", completed_at: Time.current, output_file_id:)
+
+      Coolhand::Vertex::BatchResultProcessor.new(batch_info:, model: batch_request.llm_model).call(results)
+
+      # Clean up GCS files after successful processing
+      cleanup_gcs_files(output_file_id)
+    when "JOB_STATE_FAILED"
+      handle_failed_batch(batch_info["error"]["message"])
+    end
+  end
+end
+```

data/lib/coolhand/api_service.rb

@@ -70,6 +70,11 @@ module Coolhand
       uri = URI.parse(@api_endpoint)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = (uri.scheme == "https")
+      # Bound worst-case latency: this call happens inline in the intercepted
+      # request's path, so a slow/unreachable Coolhand backend must not hang
+      # the host app's real LLM call for Ruby's ~60s Net::HTTP defaults.
+      http.open_timeout = 5
+      http.read_timeout = 5
 
       request = Net::HTTP::Post.new(uri.request_uri)
       headers = create_request_options(payload)
@@ -87,7 +92,13 @@ module Coolhand
       request.body = json_body.force_encoding("UTF-8")
 
       begin
-        response = http.request(request)
+        # This request goes through the same patched Net::HTTP as the host
+        # app's real LLM calls. Without this, a base_url/intercept_addresses
+        # configuration that also matches Coolhand's own API host would
+        # re-intercept this log-shipping call, generating a second log
+        # request that itself gets intercepted, and so on — unbounded
+        # request amplification.
+        response = Coolhand.without_capture { http.request(request) }
 
         if response.is_a?(Net::HTTPSuccess)
           result = JSON.parse(response.body, symbolize_names: true)

data/lib/coolhand/base_interceptor.rb

@@ -5,93 +5,13 @@ module Coolhand
   module BaseInterceptor
     module_function
 
-    def extract_response_data(response)
-      case response
-      when Hash
-        response
-      when Struct
-        response.to_h
-      else
-        # Handle streaming responses - these are often enumerator objects
-        # that can't be serialized directly
-        if response.class.name.include?("Stream") || response.respond_to?(:each)
-          {
-            response_type: "streaming",
-            class: response.class.name,
-            note: "Streaming response - content captured during enumeration"
-          }
-        elsif response.respond_to?(:to_h)
-          begin
-            response.to_h
-          rescue StandardError => e
-            {
-              serialization_error: e.message,
-              class: response.class.name,
-              raw_response: response.to_s
-            }
-          end
-        else
-          # Extract content and token usage information
-          response_data = {}
-
-          # Get content
-          response_data[:content] = response.content if response.respond_to?(:content)
-
-          # Extract token usage information
-          response_data[:usage] = extract_usage_metadata(response.usage) if response.respond_to?(:usage)
-
-          # Extract model information
-          response_data[:model] = response.model if response.respond_to?(:model)
-
-          # Extract role information
-          response_data[:role] = response.role if response.respond_to?(:role)
-
-          # Extract ID if available
-          response_data[:id] = response.id if response.respond_to?(:id)
-
-          # Extract stop reason if available
-          response_data[:stop_reason] = response.stop_reason if response.respond_to?(:stop_reason)
-
-          # Add class info for debugging
-          response_data[:class] = response.class.name
-
-          response_data.empty? ? { raw_response: response.to_s, class: response.class.name } : response_data
-        end
-      end
-    end
-
-    def extract_usage_metadata(usage)
-      if usage.respond_to?(:to_h)
-        usage.to_h
-      elsif usage.is_a?(Hash)
-        usage
-      else
-        # Extract individual usage fields
-        usage_data = {}
-        usage_data[:input_tokens] = usage.input_tokens if usage.respond_to?(:input_tokens)
-        usage_data[:output_tokens] = usage.output_tokens if usage.respond_to?(:output_tokens)
-        usage_data[:total_tokens] = usage_data[:input_tokens].to_i + usage_data[:output_tokens].to_i
-        usage_data
-      end
-    end
-
-    def clean_request_headers(headers)
-      cleaned = headers.dup
-
-      # Remove sensitive headers
-      cleaned.delete("Authorization")
-      cleaned.delete("authorization")
-      cleaned.delete("x-api-key")
-      cleaned.delete("X-API-Key")
-
-      cleaned
-    end
-
-    def clean_response_headers(headers)
-      # Response headers typically don't contain sensitive data
-      # but we can filter if needed
-      headers.dup
-    end
+    # Matches any header whose *name* signals sensitive content, regardless of
+    # provider — covers known keys (x-api-key, x-goog-api-key, openai-api-key),
+    # AWS SigV4 session tokens (x-amz-security-token), session/CSRF cookies
+    # (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
 
     def sanitize_headers(headers)
       return {} if headers.nil?
@@ -122,7 +42,6 @@ module Coolhand
 
       sanitized = raw.dup
 
-      sanitized_keys = %w[openai-api-key api-key x-api-key x-goog-api-key]
       sanitized.each do |k, v|
         next if v.nil?
 
@@ -134,7 +53,7 @@ module Coolhand
           else
             "[REDACTED]"
           end
-        elsif sanitized_keys.include?(key_down)
+        elsif key_down.match?(SENSITIVE_HEADER_PATTERN)
           sanitized[k] = "[REDACTED]"
         end
       end
@@ -151,15 +70,22 @@ module Coolhand
       end
     end
 
+    # Matches query param *names* that signal sensitive content, the same way
+    # SENSITIVE_HEADER_PATTERN does for headers — covers exact params this
+    # gem already knew about (key/token/secret) as well as presigned-URL
+    # credential params used by AWS (X-Amz-Signature, X-Amz-Credential,
+    # X-Amz-Security-Token) and Google Cloud (X-Goog-Signature,
+    # X-Goog-Credential) storage APIs.
+    SENSITIVE_QUERY_PARAM_PATTERN = /key|token|secret|sig|credential|password|auth/i
+
     def sanitize_url(url)
       uri = URI.parse(url)
       return url unless uri.query
 
-      sensitive = %w[key api_key apikey token access_token secret]
       params = URI.decode_www_form(uri.query)
       redacted = false
       params.map! do |n, v|
-        if sensitive.include?(n.downcase)
+        if n.match?(SENSITIVE_QUERY_PARAM_PATTERN)
           redacted = true
           [n, "[REDACTED]"]
         else
@@ -178,23 +104,25 @@ module Coolhand
     end
 
     def send_complete_request_log(request_id:, method:, url:, request_headers:, request_body:, response_headers:,
-      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:)
-      request_data = {
-        raw_request: {
-          id: request_id,
-          timestamp: start_time.iso8601,
-          method: method.to_s.downcase,
-          url: sanitize_url(url),
-          headers: request_headers,
-          request_body: request_body,
-          response_headers: response_headers,
-          response_body: response_body,
-          status_code: status_code,
-          duration_ms: duration_ms,
-          completed_at: end_time.iso8601,
-          is_streaming: is_streaming
-        }
+      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil)
+      raw_request = {
+        id: request_id,
+        timestamp: start_time.iso8601,
+        method: method.to_s.downcase,
+        url: sanitize_url(url),
+        headers: sanitize_headers(request_headers),
+        request_body: request_body,
+        response_headers: sanitize_headers(response_headers),
+        response_body: response_body,
+        status_code: status_code,
+        duration_ms: duration_ms,
+        completed_at: end_time.iso8601,
+        is_streaming: is_streaming
       }
+      raw_request[:source_api] = source_api if Coolhand.required_field?(source_api)
+      raw_request[:model] = model if Coolhand.required_field?(model)
+
+      request_data = { raw_request: raw_request }
 
       api_service = Coolhand::ApiService.new
       api_service.send_llm_request_log(request_data)

data/lib/coolhand/configuration.rb

@@ -6,11 +6,11 @@ require "uri"
 module Coolhand
   # Handles all configuration settings for the gem.
   class Configuration
-    DEFAULT_EXCLUDE_API_PATTERNS = YAML.load_file(
+    DEFAULT_EXCLUDE_API_PATTERNS = YAML.safe_load_file(
       File.join(__dir__, "default_exclude_api_patterns.yml")
     ).freeze
 
-    DEFAULT_INTERCEPT_ADDRESSES = YAML.load_file(
+    DEFAULT_INTERCEPT_ADDRESSES = YAML.safe_load_file(
       File.join(__dir__, "default_intercept_addresses.yml")
     ).freeze
 

data/lib/coolhand/logger_service.rb

@@ -73,8 +73,9 @@ module Coolhand
         # Convert Rails HTTP_ prefix headers
         clean_key = key.to_s.gsub(/^HTTP_/, "").tr("_", "-").downcase
 
-        # Redact sensitive headers
-        clean_value = clean_key.match?(/key|token|secret|authorization|signature/i) ? "[REDACTED]" : value.to_s
+        # Redact sensitive headers (shared with BaseInterceptor so both logging
+        # paths treat the same header names as sensitive)
+        clean_value = clean_key.match?(BaseInterceptor::SENSITIVE_HEADER_PATTERN) ? "[REDACTED]" : value.to_s
         clean_headers[clean_key] = clean_value
       end
       clean_headers

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] ||= +""
@@ -49,8 +56,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 +74,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 +95,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)
 
@@ -141,7 +164,7 @@ module Coolhand
 
       matched = patterns.find { |pattern| url.include?(pattern) }
       if matched && Coolhand.configuration.debug_mode
-        Coolhand.log "🚫 Skipping capture for #{url} (matched exclude_api_pattern: \"#{matched}\")"
+        Coolhand.log "🚫 Skipping capture for #{sanitize_url(url)} (matched exclude_api_pattern: \"#{matched}\")"
       end
       !!matched
     end

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

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "openssl"
+
 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,7 +18,7 @@ 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
@@ -32,6 +34,8 @@ module Coolhand
 
       private
 
+      attr_reader :webhook_secret
+
       def payload_valid?
         return true if @payload
 

data/lib/coolhand/version.rb

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

data/lib/coolhand/vertex/batch_result_processor.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "../../coolhand"
+
 module Coolhand
   module Vertex
     class BatchResultProcessor
-      attr_reader :batch_info
+      # Global endpoint, not the job's region-specific one — matches the
+      # "aiplatform.googleapis.com" entry in default_intercept_addresses.yml
+      # so backend URL-shape classification stays consistent with the rest
+      # of the gem's Vertex traffic. The URL this produces always contains
+      # "/batchPredictionJobs/", which is also the default client-side
+      # exclude_api_patterns entry — that's harmless here since this class
+      # sends via BaseInterceptor/ApiService directly and never goes through
+      # NetHttpInterceptor's intercept/exclude filtering.
+      VERTEX_API_BASE_URL = "https://aiplatform.googleapis.com/v1/"
+      SOURCE_API = "vertex"
+      VALID_NAME_PATTERN = %r{\Aprojects/[^/?#\s]+/locations/[^/?#\s]+/batchPredictionJobs/[^/?#\s]+\z}
+
+      attr_reader :batch_info, :model
 
-      def initialize(batch_info:)
+      def initialize(batch_info:, model: nil)
         @batch_info = batch_info
+        @model = model
       end
 
       def call(batch_results = [])
@@ -16,7 +31,7 @@ module Coolhand
         when "JOB_STATE_PENDING", "JOB_STATE_RUNNING", "JOB_STATE_QUEUED"
           Rails.logger.info("[Interceptor] Vertex batch #{batch_info} still processing")
         when "JOB_STATE_SUCCEEDED"
-          batch_results.each { |batch_item| process_completed_batch(batch_item) }
+          process_completed_batch(batch_results)
         when "JOB_STATE_FAILED"
           handle_failed_batch
         else
@@ -28,56 +43,98 @@ module Coolhand
 
       private
 
-      def process_completed_batch(batch_item)
-        send_complete_request_log(request_id: SecureRandom.hex(16),
+      def process_completed_batch(batch_results)
+        name = batch_info["name"].to_s.sub(%r{\A/+}, "")
+        unless name.match?(VALID_NAME_PATTERN)
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a missing or " \
+                             "invalid job resource name (#{batch_info['name'].inspect}); skipping request log")
+          return
+        end
+
+        begin
+          start_time = Time.iso8601(batch_info["startTime"])
+          end_time   = Time.iso8601(batch_info["endTime"])
+        rescue TypeError, ArgumentError
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a missing or " \
+                             "invalid startTime/endTime; skipping request log")
+          return
+        end
+
+        if end_time < start_time
+          Rails.logger.warn("[Interceptor] Vertex batch #{batch_info['displayName']} has an endTime before " \
+                            "its startTime; sending request log(s) with duration_ms clamped to 0")
+          end_time = start_time
+        end
+
+        duration_ms = ((end_time - start_time) * 1000).to_i
+        url = "#{VERTEX_API_BASE_URL}#{name}"
+        resolved = resolved_model
+
+        sent = batch_results.count do |batch_item|
+          send_item_log(batch_item, url: url, model: resolved, start_time: start_time, end_time: end_time,
+            duration_ms: duration_ms)
+        end
+
+        # "Sent" here means dispatched to BaseInterceptor without a local
+        # error (e.g. a malformed batch_item) — BaseInterceptor swallows any
+        # downstream delivery failure itself, so this can't confirm the
+        # Coolhand API actually received the log.
+        if sent == batch_results.size
+          Rails.logger.info("[Interceptor] Dispatched #{sent} result(s) for Vertex batch " \
+                            "#{batch_info['displayName']} for logging")
+        else
+          Rails.logger.warn("[Interceptor] Dispatched #{sent}/#{batch_results.size} result(s) for Vertex " \
+                            "batch #{batch_info['displayName']} for logging — " \
+                            "#{batch_results.size - sent} item(s) were malformed and skipped")
+        end
+      end
+
+      def send_item_log(batch_item, url:, model:, start_time:, end_time:, duration_ms:)
+        unless batch_item.is_a?(Hash) && (batch_item.key?("request") || batch_item.key?("response"))
+          Rails.logger.error("[Interceptor] Vertex batch #{batch_info['displayName']} has a malformed result " \
+                             "item (#{batch_item.class}); skipping request log")
+          return false
+        end
+
+        BaseInterceptor.send_complete_request_log(
+          request_id: SecureRandom.hex(16),
           method: "POST",
-          url: batch_info["name"],
+          url: url,
+          source_api: SOURCE_API,
+          model: model,
+          request_headers: {},
           request_body: batch_item["request"],
+          response_headers: {},
           response_body: batch_item["response"],
           status_code: 200,
-          start_time: batch_info["startTime"],
-          end_time: batch_info["endTime"])
-
-        Rails.logger.info("[Interceptor] Successfully processed Vertex batch #{batch_info['displayName']}")
+          start_time: start_time,
+          end_time: end_time,
+          duration_ms: duration_ms,
+          is_streaming: false
+        )
+        true
       rescue StandardError => e
         Rails.logger.error("[Interceptor] Failed to send request log: #{e.message}")
+        false
       end
 
-      def send_complete_request_log(request_id:, method:, url:, request_body:, response_body:, status_code:,
-        start_time:, end_time:)
-        start_time = Time.iso8601(start_time)
-        end_time   = Time.iso8601(end_time)
-        duration_ms = ((end_time - start_time) * 1000).to_i
+      def resolved_model
+        candidate = [model, batch_info["model"]].find { |c| Coolhand.required_field?(c) }&.to_s&.strip
+        return if candidate.nil?
 
-        request_data = {
-          raw_request: {
-            id: request_id,
-            timestamp: start_time,
-            method: method.to_s.downcase,
-            url: url,
-            headers: {},
-            request_body: request_body,
-            response_headers: {},
-            response_body: response_body,
-            status_code: status_code,
-            duration_ms: duration_ms,
-            completed_at: end_time,
-            is_streaming: false
-          }
-        }
-
-        api_service = Coolhand::ApiService.new
-        api_service.send_llm_request_log(request_data)
-
-        Coolhand.log "📤 Sent complete request/response log for #{request_id} (duration: #{duration_ms}ms)"
-      rescue StandardError => e
-        Coolhand.log "❌ Error sending complete request log: #{e.message}"
+        # Only normalize genuine Vertex model resource paths (e.g.
+        # "publishers/google/models/gemini-2.0-flash" or
+        # "projects/P/locations/L/models/M@1") down to their bare id. A
+        # caller-supplied `model:` might itself be a provider-qualified slug
+        # that happens to contain a slash (e.g. "meta-llama/Llama-3") —
+        # leave anything that isn't a resource path untouched.
+        candidate.match?(%r{\A(publishers|projects)/}) ? candidate.split("/").last : candidate
       end
 
       # TODO: implement API to handle failed batch results and display errors on dashboard page
       def handle_failed_batch
-        Rails.logger.error("[Interceptor] Vertex batch for #{batch_info['displayName']} " \
-                           "failed: #{batch_info['error']['message']}")
+        message = batch_info["error"].is_a?(Hash) ? batch_info["error"]["message"] : batch_info["error"]
+        Rails.logger.error("[Interceptor] Vertex batch for #{batch_info['displayName']} failed: #{message}")
       end
     end
   end

data/lib/coolhand/webhook_interceptor.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "open_ai/webhook_validator"
+require_relative "open_ai/batch_result_processor"
+
 module Coolhand
   module WebhookInterceptor
     def intercept_batch_request
@@ -14,10 +17,18 @@ module Coolhand
       end
 
       payload = JSON.parse(@validator.payload)
+      raise TypeError, "webhook payload must be a JSON object, got #{payload.class}" unless payload.is_a?(Hash)
 
       process_event(payload)
     rescue StandardError => e
+      # Fail closed: any error here (malformed payload, a bug in
+      # process_event/BatchResultProcessor, etc.) must still halt the
+      # before_action chain. Falling through without calling `head` would
+      # let the controller action run for a request whose webhook
+      # signature was never confirmed valid.
       Rails.logger.error("[Interceptor] Failed to intercept batch request: #{e.message}")
+      head :unauthorized
+      false
     end
 
     def webhook_secret

data/lib/coolhand.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require "uri"
-require "faraday"
 require "securerandom"
 require "json"
 require "base64"
+require "time"
 
 require_relative "coolhand/version"
 require_relative "coolhand/configuration"