coolhand 0.2.0 → 0.3.0

data/lib/coolhand/logger_service.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+
+module Coolhand
+  class LoggerService < ApiService
+    def initialize
+      super("v2/llm_request_logs")
+    end
+
+    def log_to_api(captured_data)
+      create_log(captured_data, "auto-monitor")
+    end
+
+    # Helper method for forwarding webhook data to Coolhand
+    def forward_webhook(webhook_body:, source:, event_type: nil, headers: {}, **options)
+      # Validate required parameters
+      unless Coolhand.required_field?(webhook_body)
+        error_msg = "webhook_body is required and cannot be nil or empty"
+        if Coolhand.configuration.silent
+          puts "COOLHAND WARNING: #{error_msg}"
+          return false
+        else
+          raise ArgumentError, error_msg
+        end
+      end
+
+      unless Coolhand.required_field?(source)
+        error_msg = "source is required and cannot be nil or empty"
+        if Coolhand.configuration.silent
+          puts "COOLHAND WARNING: #{error_msg}"
+          return false
+        else
+          raise ArgumentError, error_msg
+        end
+      end
+
+      # Auto-generate required fields unless provided
+      webhook_data = {
+        id: options[:id] || SecureRandom.uuid,
+        timestamp: options[:timestamp] || Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ"),
+        method: options[:method] || "POST",
+        url: options[:url] || build_webhook_url(source, event_type),
+        headers: sanitize_headers(headers),
+        request_body: clean_webhook_body(webhook_body, source),
+        response_body: options[:response_body],
+        response_headers: options[:response_headers],
+        status_code: options[:status_code] || 200,
+        source: "#{source}_webhook"
+      }.merge(options.slice(:metadata, :conversation_id, :agent_id))
+
+      # Send to API asynchronously
+      log_to_api(webhook_data)
+    end
+
+    private
+
+    def build_webhook_url(source, event_type)
+      base = "webhook://#{source}"
+      event_type ? "#{base}/#{event_type}" : base
+    end
+
+    def sanitize_headers(headers)
+      return {} if headers.nil?
+      return {} if headers.respond_to?(:empty?) && headers.empty?
+      return {} unless headers.respond_to?(:each)
+
+      # Handle Rails request headers or plain hash
+      clean_headers = {}
+      headers.each do |key, value|
+        next unless key && value
+
+        # 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
+        clean_headers[clean_key] = clean_value
+      end
+      clean_headers
+    end
+
+    def clean_webhook_body(body, source)
+      # Service-specific binary field filters
+      binary_fields = case source.to_s.downcase
+                      when "elevenlabs"
+                        %w[full_audio audio audio_data raw_audio audio_base64 voice_sample audio_url]
+                      when "twilio"
+                        %w[recording_url media_url]
+                      else
+                        %w[audio_data image_data file_content binary_content]
+      end
+
+      remove_binary_fields(body, binary_fields)
+    end
+
+    def remove_binary_fields(obj, fields_to_remove)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), cleaned|
+          next if fields_to_remove.any? { |field| key.to_s.downcase.include?(field) }
+
+          cleaned[key] = remove_binary_fields(value, fields_to_remove)
+        end
+      when Array
+        obj.map { |item| remove_binary_fields(item, fields_to_remove) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/coolhand/net_http_interceptor.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module NetHttpInterceptor
+    include BaseInterceptor
+
+    # Response streaming interceptor nested under NetHttpInterceptor
+    module ResponseInterceptor
+      def read_body(dest = nil, &block)
+        return super unless block
+
+        super do |chunk|
+          Thread.current[:coolhand_stream_buffer] ||= +""
+          Thread.current[:coolhand_stream_buffer] << chunk
+          yield(chunk)
+        end
+      end
+    end
+
+    def self.patch!
+      return if @patched
+
+      Net::HTTP.prepend(self)
+      Net::HTTPResponse.prepend(ResponseInterceptor)
+
+      @patched = true
+      Coolhand.log "🔗 Net::HTTP interceptor patched"
+    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 ..."
+    end
+
+    def self.patched?
+      @patched
+    end
+
+    def request(req, body = nil, &block)
+      return super unless NetHttpInterceptor.patched?
+
+      active = (Thread.current[:coolhand_active_requests] ||= {}.compare_by_identity)
+      return super if active.key?(self)
+
+      url = build_url_for_request(self, req)
+      return super unless intercept?(url)
+      return super unless should_capture?
+
+      # 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)
+
+      active[self] = true
+      start_time = Time.now
+      request_id = SecureRandom.uuid
+      response = nil
+      status_code = nil
+      response_body = nil
+
+      Thread.current[:coolhand_stream_buffer] = nil
+
+      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 = parse_json(body_content)
+      rescue StandardError => e
+        status_code = extract_status_from_exception(e)
+        response_body = { "error" => { "class" => e.class.name, "message" => e.message } }
+        raise
+      ensure
+        active.delete(self)
+        Thread.current[:coolhand_stream_buffer] = nil
+        end_time = Time.now
+        duration_ms = ((end_time - start_time) * 1000).round(2)
+
+        send_complete_request_log(
+          request_id: request_id,
+          method: req.method,
+          url: url,
+          request_headers: sanitize_headers(req),
+          request_body: captured_body,
+          response_headers: sanitize_headers(response),
+          response_body: response_body,
+          status_code: status_code,
+          start_time: start_time,
+          end_time: end_time,
+          duration_ms: duration_ms,
+          is_streaming: !!block
+        )
+      end
+
+      response
+    end
+
+    private
+
+    def should_capture?
+      return true if Coolhand.configuration.debug_mode
+
+      override = Thread.current[:coolhand_capture_override]
+      return override unless override.nil?
+
+      Coolhand.configuration.capture
+    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
+        content = req.body_stream.read
+        req.body_stream = StringIO.new(content)
+        return parse_json(content)
+      end
+
+      nil
+    end
+
+    def extract_status_from_exception(e)
+      return e.status if e.respond_to?(:status) && e.status.is_a?(Integer)
+      return e.response.status if e.respond_to?(:response) && e.response.respond_to?(:status)
+
+      match = e.message.to_s.match(/status[=:\s]+(\d{3})/)
+      match ? match[1].to_i : nil
+    end
+
+    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) }
+    end
+
+    def excluded_by_pattern?(url)
+      patterns = Coolhand.configuration.exclude_api_patterns
+      return false if patterns.nil? || patterns.empty?
+
+      matched = patterns.find { |pattern| url.include?(pattern) }
+      if matched && Coolhand.configuration.debug_mode
+        Coolhand.log "🚫 Skipping capture for #{url} (matched exclude_api_pattern: \"#{matched}\")"
+      end
+      !!matched
+    end
+
+    def build_url_for_request(http, req)
+      return req.path if %r{\Ahttps?://}.match?(req.path)
+
+      scheme = http.use_ssl? ? "https" : "http"
+      host = http.address
+      port = http.port
+      default = http.use_ssl? ? 443 : 80
+
+      url = "#{scheme}://#{host}"
+      url << ":#{port}" if port != default
+      url << req.path
+      url
+    end
+  end
+end

data/lib/coolhand/open_ai/batch_result_processor.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module OpenAi
+    class BatchResultProcessor
+      attr_reader :event_data
+
+      def initialize(event_data:)
+        @event_data = event_data
+      end
+
+      def call
+        Rails.logger.info("[Interceptor] BatchResultProcessor: #{event_data}")
+
+        case batch_info["status"]
+        when "completed"
+          process_completed_batch
+        when "failed", "expired", "cancelled"
+          handle_failed_batch
+        when "in_progress", "validating", "finalizing"
+          Rails.logger.info("[Interceptor] OpenAI batch #{event_data} still processing")
+        else
+          Rails.logger.warn("[Interceptor] Unknown batch status: #{batch_info['status']} for batch #{event_data}")
+        end
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to process OpenAI batch results for #{event_data}: #{e.message}")
+      end
+
+      private
+
+      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)
+
+        # Download and process results
+        batch_response_items = download_batch_results(output_file_id)
+
+        batch_response_items.each do |response_item|
+          request_item = batch_request_items.detect { |item| item["custom_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}")
+        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)
+
+        # 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?
+
+            JSON.parse(line)
+          end
+        end
+      rescue JSON::ParserError => e
+        Rails.logger.error("[Interceptor] Failed to parse OpenAI batch results: #{e.message}")
+        []
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to download OpenAI batch results: #{e.message}")
+        []
+      end
+
+      def send_complete_request_log(request_id:, method:, url:, request_body:, response_body:, status_code:,
+        start_time:, end_time:)
+        timestamp = Time.at(start_time).iso8601
+        completed_at = Time.at(end_time).iso8601
+        duration_ms = ((end_time - start_time) * 1000).to_i
+
+        request_data = {
+          raw_request: {
+            id: request_id,
+            timestamp: timestamp,
+            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: completed_at,
+            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}"
+      end
+
+      def batch_info
+        @batch_info ||= client.batches.retrieve(id: event_data["id"])
+      end
+
+      def client
+        @client ||= begin
+          require "openai"
+          OpenAI::Client.new
+        rescue LoadError => e
+          raise LoadError, "The 'openai' gem is required to process OpenAI batches. " \
+                           "Install it with: gem 'openai'\n\nOriginal error: #{e.message}"
+        end
+      end
+
+      # TODO: implement API to handle failed batch results and display errors on dashboard page
+      def handle_failed_batch
+        Rails.logger.error("[Interceptor] OpenAI batch #{batch_info['id']} failed: #{batch_info['errors']}")
+      end
+    end
+  end
+end

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module OpenAi
+    class WebhookValidator
+      attr_reader :request, :errors, :payload, :webhook_secret
+
+      def initialize(request, webhook_secret)
+        @request = request
+        @errors = []
+        @webhook_secret = webhook_secret
+      end
+
+      def valid?
+        @errors.clear
+        @payload = request.raw_post || request.body.read
+
+        return false unless payload_valid?
+        return validate_in_non_production_env unless webhook_secret
+
+        secret_bytes = extract_secret_bytes
+        webhook_signature, webhook_timestamp, webhook_id = extract_webhook_headers
+
+        return validate_headers_in_non_production_env unless webhook_signature && webhook_timestamp
+
+        verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
+      end
+
+      def error_message
+        @errors.join(", ")
+      end
+
+      private
+
+      def payload_valid?
+        return true if @payload
+
+        if should_enforce_strict_validation?
+          @errors << "Empty webhook payload - rejecting webhook in production/staging"
+          Rails.logger.error(@errors.last)
+          false
+        else
+          Rails.logger.warn("Empty webhook payload - allowing in #{Rails.env} environment")
+          true
+        end
+      end
+
+      def validate_in_non_production_env
+        if should_enforce_strict_validation?
+          @errors << "OpenAI webhook secret not configured - rejecting webhook in production/staging"
+          Rails.logger.error(@errors.last)
+          false
+        else
+          Rails.logger.warn(
+            "Webhook Secret is not configured - skipping signature verification in #{Rails.env}"
+          )
+          true
+        end
+      end
+
+      def extract_secret_bytes
+        if @webhook_secret.start_with?("whsec_")
+          webhook_secret_key = @webhook_secret[6..]
+          Base64.strict_decode64(webhook_secret_key)
+        else
+          @webhook_secret
+        end
+      end
+
+      def extract_webhook_headers
+        webhook_signature = request.headers["webhook-signature"] || request.headers["openai-signature"]
+        webhook_timestamp = request.headers["webhook-timestamp"] || request.headers["openai-timestamp"]
+        webhook_id = request.headers["webhook-id"] || request.headers["openai-id"]
+        [webhook_signature, webhook_timestamp, webhook_id]
+      end
+
+      def validate_headers_in_non_production_env
+        if should_enforce_strict_validation?
+          @errors << "Missing OpenAI webhook signature or timestamp headers - " \
+                     "rejecting webhook in production/staging"
+          Rails.logger.error(@errors.last)
+          false
+        else
+          Rails.logger.warn("Missing OpenAI webhook headers - skipping verification in #{Rails.env}")
+          true
+        end
+      end
+
+      def verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
+        signed_payload = "#{webhook_id}.#{webhook_timestamp}.#{@payload}"
+        expected_signature = calculate_expected_signature(secret_bytes, signed_payload)
+
+        signature_valid = webhook_signature.start_with?("v1,") &&
+                          secure_compare(webhook_signature[3..], expected_signature)
+        if signature_valid
+          true
+        else
+          @errors << "OpenAI webhook signature verification failed"
+          Rails.logger.error(@errors.last)
+          false
+        end
+      end
+
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        result = 0
+        a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+        result.zero?
+      end
+
+      def calculate_expected_signature(secret_bytes, signed_payload)
+        Base64.strict_encode64(
+          OpenSSL::HMAC.digest(
+            OpenSSL::Digest.new("sha256"),
+            secret_bytes,
+            signed_payload
+          )
+        )
+      end
+
+      def should_enforce_strict_validation?
+        ["production", "staging"].include?(Rails.env)
+      end
+    end
+  end
+end

data/lib/coolhand/{ruby/version.rb → version.rb}

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
 module Coolhand
-  module Ruby
-    VERSION = "0.2.0"
-  end
+  VERSION = "0.3.0"
 end

data/lib/coolhand/vertex/batch_result_processor.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module Vertex
+    class BatchResultProcessor
+      attr_reader :batch_info
+
+      def initialize(batch_info:)
+        @batch_info = batch_info
+      end
+
+      def call(batch_results = [])
+        Rails.logger.info("[Interceptor] BatchResultProcessor: #{batch_info}")
+
+        case batch_info["state"]
+        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) }
+        when "JOB_STATE_FAILED"
+          handle_failed_batch
+        else
+          Rails.logger.warn("[Interceptor] Unknown batch status: #{batch_info['state']} for batch #{batch_info}")
+        end
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to process Vertex batch results for #{batch_info}: #{e.message}")
+      end
+
+      private
+
+      def process_completed_batch(batch_item)
+        send_complete_request_log(request_id: SecureRandom.hex(16),
+          method: "POST",
+          url: batch_info["name"],
+          request_body: batch_item["request"],
+          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']}")
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to send request log: #{e.message}")
+      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
+
+        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}"
+      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']}")
+      end
+    end
+  end
+end

data/lib/coolhand/webhook_interceptor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module WebhookInterceptor
+    def intercept_batch_request
+      Rails.logger.info("[Interceptor] #{controller_name}##{action_name}")
+
+      @validator = Coolhand::OpenAi::WebhookValidator.new(request, webhook_secret)
+
+      unless @validator.valid?
+        Rails.logger.info("[Interceptor] Webhook validated failed: #{@validator.error_message}")
+        head :unauthorized
+        return false
+      end
+
+      payload = JSON.parse(@validator.payload)
+
+      process_event(payload)
+    rescue StandardError => e
+      Rails.logger.error("[Interceptor] Failed to intercept batch request: #{e.message}")
+    end
+
+    def webhook_secret
+      raise NotImplementedError, "#{self.class} must implement #webhook_secret"
+    end
+
+    def process_event(payload)
+      event_type = payload["type"]
+      event_data = payload["data"]
+
+      case event_type
+      when "batch.completed", "batch.failed", "batch.expired", "batch.cancelled"
+        Coolhand::OpenAi::BatchResultProcessor.new(event_data: event_data).call
+      else
+        Rails.logger.info("[Interceptor] Unhandled OpenAI webhook event type: #{event_type}")
+      end
+    end
+  end
+end