coolhand 0.10.0 → 0.10.1

data/lib/coolhand/net_http_interceptor.rb

@@ -1,22 +1,29 @@
 # frozen_string_literal: true
 
+require "net/http"
+require "openssl"
 require "stringio"
+require "timeout"
+require "zlib"
+
+require_relative "body_stream_tap"
+require_relative "path_normalizer"
 
 module Coolhand
   module NetHttpInterceptor
     # Response streaming interceptor nested under NetHttpInterceptor
     module ResponseInterceptor
       def read_body(dest = nil, &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]
+        # Only buffer this exact response while a #request call below is
+        # actively capturing it — otherwise every block-form read_body in
+        # the process (including ones on responses this gem never
+        # intercepted, such as a nested request made from inside the host's
+        # streaming block) accumulates into a thread-local that's never
+        # freed, and leaks one request's chunks into another's log.
+        return super unless block && Thread.current[:coolhand_capturing_stream].equal?(self)
 
         super do |chunk|
-          Thread.current[:coolhand_stream_buffer] ||= +""
-          Thread.current[:coolhand_stream_buffer] << chunk
+          Helpers.buffer_stream_chunk(chunk)
           yield(chunk)
         end
       end
@@ -119,19 +126,19 @@ module Coolhand
       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
+      Thread.current[:coolhand_capturing_stream] = nil
+      host_block_errors = []
+      tracked_block = Helpers.track_streaming_block(block, host_block_errors)
 
       begin
-        response = super
-        body_content = Thread.current[:coolhand_stream_buffer] || response&.body
-        body_content = body_content.dup.force_encoding("UTF-8") if body_content.is_a?(String)
-        status_code = response.respond_to?(:code) ? response.code.to_i : nil
-        response_body = BaseInterceptor.parse_json(body_content)
+        response = super(req, body, &tracked_block)
+        status_code, response_body = Helpers.capture_response(response)
       rescue StandardError => e
-        status_code = Helpers.extract_status_from_exception(e)
-        response_body = { "error" => { "class" => e.class.name, "message" => e.message } }
+        status_code, response_body = Helpers.error_details(e, host_block_errors)
         raise
       ensure
+        # First, so the host's own stream is back on its request whatever fails below.
+        request_body = Helpers.finalize_request_body(captured_body, req)
         active.delete(self)
         Thread.current[:coolhand_stream_buffer] = previous_stream_buffer
         Thread.current[:coolhand_capturing_stream] = previous_capturing_stream
@@ -145,7 +152,7 @@ module Coolhand
           method: req.method,
           url: url,
           request_headers: BaseInterceptor.sanitize_headers(req),
-          request_body: captured_body,
+          request_body: request_body,
           response_headers: BaseInterceptor.sanitize_headers(response),
           response_body: response_body,
           status_code: status_code,
@@ -166,6 +173,46 @@ module Coolhand
     module Helpers
       module_function
 
+      HOST_BLOCK_ERROR_MESSAGE = "[redacted: raised in host streaming block]"
+      # Socket-level failures can surface inside the host's block (read_body runs there); they
+      # carry no app data, so they keep their message even when they pass through the host block.
+      TRANSPORT_ERRORS = [
+        IOError, SystemCallError, Timeout::Error, Net::ProtocolError, OpenSSL::SSL::SSLError,
+        Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Zlib::Error
+      ].freeze
+      private_constant :HOST_BLOCK_ERROR_MESSAGE, :TRANSPORT_ERRORS
+
+      # Wraps the host's streaming block so (a) read_body only buffers the response being
+      # captured here, and (b) exceptions raised by the host's own code can be told apart from
+      # transport errors (see TRANSPORT_ERRORS). Returns nil when there is no block.
+      def track_streaming_block(block, host_block_errors)
+        return unless block
+
+        proc do |res|
+          Thread.current[:coolhand_capturing_stream] = res
+          block.call(res)
+        rescue StandardError => e
+          host_block_errors << e unless transport_error?(e)
+          raise
+        end
+      end
+
+      # Matched by class, so a host block raising its own IOError/SystemCallError subclass keeps its
+      # message too; accepted trade-off, as telling those apart from socket failures isn't possible.
+      def transport_error?(error)
+        TRANSPORT_ERRORS.any? { |klass| error.is_a?(klass) }
+      end
+
+      # An error raised by the host's streaming block can carry app-level data in its message (and
+      # in a #status or message-embedded status code), so only its class is logged and no status is
+      # derived from it; transport errors keep their message and status. Returns [status, body].
+      def error_details(error, host_block_errors)
+        from_host = host_block_errors.any? { |host_error| host_error.equal?(error) }
+        status = from_host ? nil : extract_status_from_exception(error)
+        message = from_host ? HOST_BLOCK_ERROR_MESSAGE : error.message
+        [status, { "error" => { "class" => error.class.name, "message" => message } }]
+      end
+
       def should_capture?
         return true if Coolhand.configuration.debug_mode
 
@@ -184,24 +231,132 @@ module Coolhand
 
         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)
+          result = capture_body_stream(req)
+          return result unless result.is_a?(String)
+
+          content = result
         end
         return nil if content.nil?
 
         cap_and_parse(content, req)
       end
 
+      # A body_stream request: the log body (a marker, or the BodyStreamTap resolved after the send),
+      # or the stream's content as a String when it was read here and still needs cap_and_parse.
+      def capture_body_stream(req)
+        # A declared Content-Length over the cap means we never need the bytes: skip
+        # before .read so a huge stream is not buffered just to be discarded.
+        too_large = oversized_declared_length(req)
+        return too_large if too_large
+
+        # No usable Content-Length (chunked): the size is unknown, so don't read ahead. Tap the
+        # stream instead and build the log body once Net::HTTP has sent it (finalize_request_body).
+        unless declared_content_length(req)
+          return skipped_capture_marker(req, "unsupported_body_stream") unless BodyStreamTap.tappable?(req.body_stream)
+
+          return BodyStreamTap.install(req)
+        end
+
+        content = req.body_stream.read
+        req.body_stream = StringIO.new(content)
+        content
+      end
+
+      # The effective cap: nil disables it; a non-Integer or negative value (e.g. an unparsed
+      # ENV string) falls back to the default rather than raising into the host's request or stream.
+      def capture_limit
+        limit = Coolhand.configuration.max_captured_body_bytes
+        return limit if limit.nil? || (limit.is_a?(Integer) && !limit.negative?)
+
+        Coolhand::Configuration::DEFAULT_MAX_CAPTURED_BODY_BYTES
+      end
+
+      def over_capture_limit?(size)
+        limit = capture_limit
+        !limit.nil? && size > limit
+      end
+
+      def body_too_large_marker(carrier, size)
+        skipped_capture_marker(carrier, "body_too_large", size_bytes: size, max_bytes: capture_limit)
+      end
+
+      # Returns a body_too_large marker when the request declares a Content-Length above the
+      # cap, else nil. Chunked/absent/malformed lengths return nil (the caller then taps the
+      # stream, which enforces the cap on the bytes actually sent).
+      def oversized_declared_length(req)
+        length = declared_content_length(req)
+        body_too_large_marker(req, length) if length && over_capture_limit?(length)
+      end
+
+      # Net::HTTP sends a chunked body without regard to any Content-Length header, so it is not a
+      # declaration of what goes on the wire then.
+      def declared_content_length(req)
+        req.content_length if req.respond_to?(:content_length) && !req.chunked?
+      rescue StandardError
+        nil
+      end
+
+      # The request body for the log. A tapped body_stream (see BodyStreamTap.install) only has its
+      # content once the request has been attempted, so it is resolved here and the host's own
+      # stream is put back on the request. Runs in #request's ensure: it must not raise.
+      def finalize_request_body(captured, req)
+        return captured unless captured.is_a?(BodyStreamTap)
+
+        captured.restore_stream(req)
+        captured.body_for_log(req)
+      rescue StandardError => e
+        Coolhand.log "❌ Error capturing request body: #{e.message}"
+        nil
+      end
+
+      # Appends a streamed response chunk to the thread-local capture buffer, up to the cap.
+      # Past the cap the buffer is dropped and replaced by a running byte count (an Integer),
+      # so memory stays bounded; the host always still receives every chunk because the caller
+      # yields it regardless. Only #request (via response_body_for_log) reads this slot.
+      def buffer_stream_chunk(chunk)
+        buffer = Thread.current[:coolhand_stream_buffer]
+        total = (buffer.is_a?(Integer) ? buffer : buffer.to_s.bytesize) + chunk.bytesize
+
+        Thread.current[:coolhand_stream_buffer] =
+          if buffer.is_a?(Integer) || over_capture_limit?(total)
+            total
+          else
+            (buffer || +"") << chunk
+          end
+      rescue StandardError => e
+        # Runs inside the host's read_body loop: a capture failure must never reach the host.
+        Coolhand.log "❌ Error buffering streamed response chunk: #{e.message}"
+      end
+
+      # [status_code, response_body] for the log. Called after the real request has succeeded, so a
+      # failure here is logged and swallowed rather than re-raised into the host app.
+      def capture_response(response)
+        captured = Thread.current[:coolhand_stream_buffer] || response&.body
+        # captured is a String, or an Integer byte count when a streamed body overflowed the cap.
+        [response.respond_to?(:code) ? response.code.to_i : nil, response_body_for_log(captured, response)]
+      rescue StandardError => e
+        Coolhand.log "❌ Error capturing response: #{e.message}"
+        [nil, nil]
+      end
+
+      # Builds the logged response body from either an Integer (streamed body that overflowed
+      # the cap, see buffer_stream_chunk) or the body String/nil. An oversized String is
+      # replaced by a marker before the dup/JSON.parse so we don't copy or parse it.
+      def response_body_for_log(body, response)
+        size = body.is_a?(Integer) ? body : body.to_s.bytesize
+        return body_too_large_marker(response, size) if body.is_a?(Integer) || over_capture_limit?(size)
+
+        body = body.dup.force_encoding("UTF-8") if body.is_a?(String)
+        BaseInterceptor.parse_json(body)
+      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
+        return body_too_large_marker(req, content.bytesize) if over_capture_limit?(content.bytesize)
 
         BaseInterceptor.parse_json(content)
       end
@@ -227,10 +382,11 @@ module Coolhand
         uri = safe_parse(url)
         return false unless uri&.host
 
-        return false if excluded_by_pattern?(uri)
+        raw_path = uri.path.to_s
+        path = normalize_path(raw_path)
+        return false if excluded_by_pattern?(uri, raw_path, path)
 
         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) } }
@@ -251,12 +407,13 @@ module Coolhand
         nil
       end
 
-      def excluded_by_pattern?(uri)
+      # The deny-list fails closed: a pattern that matches either the raw or the normalized path
+      # excludes the request, so normalization can only add exclusions, never lift one.
+      def excluded_by_pattern?(uri, raw_path, path)
         patterns = Coolhand.configuration.exclude_api_patterns
         return false if patterns.nil? || patterns.empty?
 
-        path = uri.path.to_s
-        matched = patterns.find { |pattern| path.include?(pattern) }
+        matched = patterns.find { |pattern| path.include?(pattern) || raw_path.include?(pattern) }
         if matched && Coolhand.configuration.debug_mode
           Coolhand.log "🚫 Skipping capture for #{BaseInterceptor.sanitize_url(uri.to_s)} " \
                        "(matched exclude_api_pattern: \"#{matched}\")"
@@ -264,6 +421,11 @@ module Coolhand
         !!matched
       end
 
+      # See PathNormalizer: used for matching only, never for the URL that is sent or logged.
+      def normalize_path(path)
+        PathNormalizer.normalize(path)
+      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.

data/lib/coolhand/open_ai/batch_result_processor.rb

@@ -5,6 +5,16 @@ require_relative "../../coolhand"
 module Coolhand
   module OpenAi
     class BatchResultProcessor
+      # Batch input/output files carry relative URLs (e.g. "/v1/chat/completions"); logs need the
+      # absolute form so backend URL-shape classification matches the rest of the gem's OpenAI traffic.
+      OPENAI_API_BASE_URL = "https://api.openai.com"
+      SOURCE_API = "openai"
+      # Real IDs look like "batch_<hex>" and "file-<alnum>" (Azure uses UUID tails with hyphens).
+      # These values end up in OpenAI API calls made with the host app's key, so keep "/", "?", "#",
+      # "." and whitespace out of them.
+      BATCH_ID_PATTERN = /\Abatch_[A-Za-z0-9_-]{1,128}\z/
+      FILE_ID_PATTERN = /\Afile[-_][A-Za-z0-9_-]{1,128}\z/
+
       attr_reader :event_data
 
       def initialize(event_data:)
@@ -13,6 +23,7 @@ module Coolhand
 
       def call
         Rails.logger.info("[Interceptor] BatchResultProcessor: #{event_data}")
+        return unless valid_id?(event_data.is_a?(Hash) ? event_data["id"] : nil, BATCH_ID_PATTERN, "batch")
 
         case batch_info["status"]
         when "completed"
@@ -41,84 +52,159 @@ module Coolhand
       end
 
       def process_completed_batch
-        input_file_id = batch_info["input_file_id"]
-        return unless input_file_id
-
-        output_file_id = batch_info["output_file_id"]
-        return unless output_file_id
-
-        # Download and process results
-        batch_request_items = download_batch_results(input_file_id)
+        input_file_id, output_file_id = result_file_ids
+        return unless input_file_id && output_file_id
 
-        # Download and process results
-        batch_response_items = download_batch_results(output_file_id)
+        window = batch_window
+        return unless window
 
-        request_items_by_id = batch_request_items.each_with_object({}) do |item, index|
-          index[item["custom_id"]] ||= item
+        request_items_by_id = {}
+        each_batch_result(input_file_id) do |item, line_size|
+          request_items_by_id[item["custom_id"]] ||= request_entry(item, line_size)
         end
 
-        batch_response_items.each do |response_item|
+        each_batch_result(output_file_id) do |response_item, line_size|
           request_item = request_items_by_id[response_item["custom_id"]]
-
-          next unless request_item
-
-          send_complete_request_log(request_id: response_item["response"]["request_id"],
-            method: request_item["method"],
-            url: request_item["url"],
-            request_body: request_item["body"],
-            response_body: response_item["response"]["body"],
-            status_code: response_item["response"]["status_code"],
-            start_time: batch_info["in_progress_at"].to_i,
-            end_time: batch_info["completed_at"].to_i)
-        rescue StandardError => e
-          Rails.logger.error("[Interceptor] Failed to send request log: #{e.message}")
+          send_item_log(request_item, response_item, window, line_size) if request_item
         end
 
         Rails.logger.info("[Interceptor] Successfully processed OpenAI batch #{batch_info['id']}")
       end
 
-      def download_batch_results(file_id)
-        file_content = client.files.content(id: file_id)
+      # Returns [input_file_id, output_file_id], or nil when either is absent (quietly: a completed
+      # batch where every item failed legitimately has no output file) or malformed (logged).
+      def result_file_ids
+        input_file_id = batch_info["input_file_id"]
+        output_file_id = batch_info["output_file_id"]
+        return unless input_file_id && output_file_id
+        return unless valid_id?(input_file_id, FILE_ID_PATTERN, "input file") &&
+                      valid_id?(output_file_id, FILE_ID_PATTERN, "output file")
 
-        # Handle both string and array responses from the OpenAI client
-        if file_content.is_a?(Array)
-          # Client already parsed the JSONL into an array
-          file_content
-        else
-          # Parse JSONL response manually
-          file_content.split("\n").filter_map do |line|
-            line.strip!
-            next if line.empty?
+        [input_file_id, output_file_id]
+      end
+
+      def send_item_log(request_item, response_item, window, line_size)
+        send_complete_request_log(request_item: request_item, response_item: response_item, window: window,
+          line_size: line_size)
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to send request log: #{e.message}")
+      end
+
+      # What is kept of each input item while the output file is read: only the fields that get
+      # logged, with the body capped (see BatchBodyCap) so the index stays small. The model is read
+      # from the full body first, since a capped body is just a marker.
+      def request_entry(item, line_size)
+        { "method" => item["method"], "url" => item["url"], "model" => item_model(item["body"]),
+          "body" => BatchBodyCap.cap(item["body"], source_size: line_size) }
+      end
+
+      # Returns [start_time, end_time] or nil (after logging) when OpenAI didn't report usable
+      # in_progress_at/completed_at epoch seconds — better to skip than log epoch-0 timestamps.
+      def batch_window
+        started = batch_info["in_progress_at"]
+        completed = batch_info["completed_at"]
+        unless [started, completed].all? { |t| t.is_a?(Integer) && t.positive? }
+          Rails.logger.error("[Interceptor] OpenAI batch #{batch_info['id']} has a missing or invalid " \
+                             "in_progress_at/completed_at; skipping request log")
+          return
+        end
+
+        warn_inverted_window if completed < started
+        [Time.at(started), Time.at([started, completed].max)]
+      end
 
-            JSON.parse(line)
-          end
+      def warn_inverted_window
+        Rails.logger.warn("[Interceptor] OpenAI batch #{batch_info['id']} has a completed_at before its " \
+                          "in_progress_at; clamping duration_ms to 0")
+      end
+
+      def valid_id?(value, pattern, label)
+        return true if value.is_a?(String) && value.match?(pattern)
+
+        Rails.logger.error("[Interceptor] OpenAI batch has a missing or invalid #{label} ID " \
+                           "(#{value.to_s[0, 100].inspect}); skipping")
+        false
+      end
+
+      # Yields each item of a batch input/output file with the byte size of the JSONL line it came
+      # from (nil when the client had already parsed it). A String/StringIO/IO result is read a line
+      # at a time, so only one parsed item exists at once instead of the whole file split into lines.
+      # A client that returns the whole file already parsed (an Array, or a Hash for a one-line file)
+      # has loaded it already; that is out of reach here.
+      def each_batch_result(file_id, &block)
+        file_content = download_batch_file(file_id)
+
+        case file_content
+        when nil then nil
+        when Array then file_content.each { |item| yield(item, nil) if item.is_a?(Hash) }
+        when Hash then yield(file_content, nil)
+        else each_jsonl_item(file_content, &block)
         end
-      rescue JSON::ParserError => e
-        Rails.logger.error("[Interceptor] Failed to parse OpenAI batch results: #{e.message}")
-        []
+      end
+
+      def download_batch_file(file_id)
+        client.files.content(id: file_id)
       rescue StandardError => e
         Rails.logger.error("[Interceptor] Failed to download OpenAI batch results: #{e.message}")
-        []
+        nil
       end
 
-      def send_complete_request_log(request_id:, method:, url:, request_body:, response_body:, status_code:,
-        start_time:, end_time:)
+      # A malformed line is skipped (JSONL lines are independent) and reported once at the end.
+      def each_jsonl_item(file_content)
+        skipped = 0
+        file_content.each_line do |line|
+          size = line.bytesize
+          next unless line.b.match?(/\S/) # byte-wise: String#strip raises on invalid UTF-8
+
+          item = parse_jsonl_line(line)
+          item ? yield(item, size) : skipped += 1
+        end
+        return if skipped.zero?
+
+        Rails.logger.error("[Interceptor] Failed to parse OpenAI batch results: skipped #{skipped} malformed line(s)")
+      end
+
+      # Only a JSON object is an item; any other valid JSON (a number, an array) counts as malformed.
+      def parse_jsonl_line(line)
+        item = JSON.parse(line)
+        item if item.is_a?(Hash)
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+
+      def send_complete_request_log(request_item:, response_item:, window:, line_size:)
+        start_time, end_time = window
+        response = response_item["response"]
         BaseInterceptor.send_complete_request_log(
-          request_id: request_id,
-          method: method,
-          url: url,
+          request_id: response["request_id"],
+          method: request_item["method"],
+          url: absolute_url(request_item["url"]),
+          source_api: SOURCE_API,
+          model: request_item["model"] || item_model(response["body"]),
           request_headers: {},
-          request_body: request_body,
+          request_body: request_item["body"],
           response_headers: {},
-          response_body: response_body,
-          status_code: status_code,
-          start_time: Time.at(start_time),
-          end_time: Time.at(end_time),
+          response_body: BatchBodyCap.cap(response["body"], source_size: line_size),
+          status_code: response["status_code"],
+          start_time: start_time,
+          end_time: end_time,
           duration_ms: ((end_time - start_time) * 1000).to_i,
           is_streaming: false
         )
       end
 
+      def absolute_url(url)
+        url.is_a?(String) && url.start_with?("/") ? "#{OPENAI_API_BASE_URL}#{url}" : url
+      end
+
+      def item_model(*bodies)
+        bodies.each do |body|
+          model = body["model"] if body.is_a?(Hash)
+          return model if model.is_a?(String) && Coolhand.required_field?(model)
+        end
+        nil
+      end
+
       def batch_info
         @batch_info ||= client.batches.retrieve(id: event_data["id"])
       end

data/lib/coolhand/open_ai/webhook_id_store.rb

@@ -27,6 +27,13 @@ module Coolhand
         end
       end
 
+      # Forgets a claim so the same id can be claimed again (used when processing failed and the
+      # sender retries). A no-op for an unknown id.
+      def release!(id)
+        @mutex.synchronize { @entries.delete(id) }
+        nil
+      end
+
       def seen?(id)
         @mutex.synchronize do
           prune