coolhand 0.6.0 → 0.8.0

data/lib/coolhand/net_http_interceptor.rb

@@ -4,8 +4,6 @@ require "stringio"
 
 module Coolhand
   module NetHttpInterceptor
-    include BaseInterceptor
-
     # Response streaming interceptor nested under NetHttpInterceptor
     module ResponseInterceptor
       def read_body(dest = nil, &block)
@@ -70,7 +68,7 @@ module Coolhand
         next if @patch_count.positive? || !@patched
 
         @patched = false
-        Coolhand.log "🔌 Faraday monitoring disabled ..."
+        Coolhand.log "🔌 Net::HTTP interceptor unpatched (capture stopped)"
       end
     end
 
@@ -93,9 +91,8 @@ module Coolhand
       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?
+      url = Helpers.capturable_url(self, req)
+      return super unless url
 
       # Capture body before setting the guard — if this raises we skip logging cleanly
       # and the guard is never set, so there is no leak. A failure here (e.g. an
@@ -103,7 +100,7 @@ module Coolhand
       # 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)
+        Helpers.capture_request_body(req, body)
       rescue StandardError => e
         Coolhand.log "❌ Error capturing request body: #{e.message}"
         nil
@@ -130,9 +127,9 @@ module Coolhand
         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)
+        response_body = BaseInterceptor.parse_json(body_content)
       rescue StandardError => e
-        status_code = extract_status_from_exception(e)
+        status_code = Helpers.extract_status_from_exception(e)
         response_body = { "error" => { "class" => e.class.name, "message" => e.message } }
         raise
       ensure
@@ -142,13 +139,13 @@ module Coolhand
         end_time = Time.now
         duration_ms = ((end_time - start_time) * 1000).round(2)
 
-        send_complete_request_log(
+        BaseInterceptor.send_complete_request_log(
           request_id: request_id,
           method: req.method,
           url: url,
-          request_headers: sanitize_headers(req),
+          request_headers: BaseInterceptor.sanitize_headers(req),
           request_body: captured_body,
-          response_headers: sanitize_headers(response),
+          response_headers: BaseInterceptor.sanitize_headers(response),
           response_body: response_body,
           status_code: status_code,
           start_time: start_time,
@@ -161,133 +158,171 @@ module Coolhand
       response
     end
 
-    private
+    # Stateless helpers for #request. They live in their own namespaced module (not on the
+    # prepended module itself) so the only method NetHttpInterceptor adds to Net::HTTP is
+    # `request` — generically named helpers like `intercept?` would otherwise pollute
+    # Net::HTTP and could collide with, or be shadowed by, other code.
+    module Helpers
+      module_function
 
-    def should_capture?
-      return true if Coolhand.configuration.debug_mode
+      def should_capture?
+        return true if Coolhand.configuration.debug_mode
 
-      override = Thread.current[:coolhand_capture_override]
-      return override unless override.nil?
+        override = Thread.current[:coolhand_capture_override]
+        return override unless override.nil?
 
-      Coolhand.configuration.capture
-    end
+        Coolhand.configuration.capture
+      end
+
+      def capture_request_body(req, body)
+        # Check content-type before touching body_stream at all — for a binary
+        # upload (multipart/form-data, audio/*, etc.) this avoids reading the
+        # stream into memory a second time just to build a log entry no one
+        # can read anyway.
+        return skipped_capture_marker(req, "non_json_content_type") if binary_upload?(req)
+
+        content = body || req.body
+        if content.nil? && req.respond_to?(:body_stream) && req.body_stream
+          content = req.body_stream.read
+          req.body_stream = StringIO.new(content)
+        end
+        return nil if content.nil?
 
-    def capture_request_body(req, body)
-      # Check content-type before touching body_stream at all — for a binary
-      # upload (multipart/form-data, audio/*, etc.) this avoids reading the
-      # stream into memory a second time just to build a log entry no one
-      # can read anyway.
-      return skipped_capture_marker(req, "non_json_content_type") if binary_upload?(req)
-
-      content = body || req.body
-      if content.nil? && req.respond_to?(:body_stream) && req.body_stream
-        content = req.body_stream.read
-        req.body_stream = StringIO.new(content)
+        cap_and_parse(content, req)
       end
-      return nil if content.nil?
 
-      cap_and_parse(content, req)
-    end
+      def binary_upload?(req)
+        content_type = req.respond_to?(:content_type) ? req.content_type : nil
+        content_type && !content_type.match?(/json/i)
+      end
 
-    def 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
 
-    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)
+        BaseInterceptor.parse_json(content)
       end
 
-      parse_json(content)
-    end
+      def skipped_capture_marker(req, reason, extra = {})
+        marker = { "_coolhand_capture_skipped" => reason }.merge(extra.transform_keys(&:to_s))
+        content_type = req.respond_to?(:content_type) ? req.content_type : nil
+        marker["content_type"] = content_type if content_type
+        marker
+      end
 
-    def skipped_capture_marker(req, reason, extra = {})
-      marker = { "_coolhand_capture_skipped" => reason }.merge(extra.transform_keys(&:to_s))
-      content_type = req.respond_to?(:content_type) ? req.content_type : nil
-      marker["content_type"] = content_type if content_type
-      marker
-    end
+      def extract_status_from_exception(e)
+        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)
 
-    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
 
-      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)
 
-    def intercept?(url)
-      return false unless url && Coolhand.configuration.respond_to?(:intercept_addresses)
+        uri = safe_parse(url)
+        return false unless uri&.host
 
-      uri = safe_parse(url)
-      return false unless uri&.host
+        return false if excluded_by_pattern?(uri)
 
-      return false if excluded_by_pattern?(uri)
+        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) } }
 
-      host = uri.host.downcase
-      addresses = Coolhand.configuration.intercept_addresses
-      return true if addresses.any? { |a| host_matches?(host, a) }
+        return false unless google_api_host_configured?(addresses)
+        return false unless host == "googleapis.com" || host.end_with?(".googleapis.com")
 
-      return false unless google_api_host_configured?(addresses)
-      return false unless host == "googleapis.com" || host.end_with?(".googleapis.com")
+        Coolhand.configuration.intercept_path_patterns.any? { |p| path.include?(p) }
+      end
 
-      path = uri.path.to_s
-      Coolhand.configuration.intercept_path_patterns.any? { |p| path.include?(p) }
-    end
+      # The capture decision runs before the host's real request, so a bad config value (e.g. a
+      # non-array exclude_api_patterns) must degrade to "don't capture", never raise into the host.
+      def capturable_url(http, req)
+        url = build_url_for_request(http, req)
+        url if intercept?(url) && should_capture?
+      rescue StandardError => e
+        Coolhand.log "⚠️ Skipping capture, could not evaluate intercept rules: #{e.class}"
+        nil
+      end
 
-    def excluded_by_pattern?(uri)
-      patterns = Coolhand.configuration.exclude_api_patterns
-      return false if patterns.nil? || patterns.empty?
+      def excluded_by_pattern?(uri)
+        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) }
-      if matched && Coolhand.configuration.debug_mode
-        Coolhand.log "🚫 Skipping capture for #{sanitize_url(uri.to_s)} (matched exclude_api_pattern: \"#{matched}\")"
+        path = uri.path.to_s
+        matched = patterns.find { |pattern| 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}\")"
+        end
+        !!matched
       end
-      !!matched
-    end
 
-    # intercept_path_patterns only ever applies to googleapis.com hosts, and only when the
-    # user still wants Google API traffic intercepted at all — otherwise overriding
-    # intercept_addresses to exclude Google hosts wouldn't actually stop Google API capture.
-    def google_api_host_configured?(addresses)
-      addresses.any? do |a|
-        a = a.to_s.downcase
-        a == "googleapis.com" || a.end_with?(".googleapis.com")
+      # intercept_path_patterns only ever applies to googleapis.com hosts, and only when the
+      # user still wants Google API traffic intercepted at all — otherwise overriding
+      # intercept_addresses to exclude Google hosts wouldn't actually stop Google API capture.
+      def google_api_host_configured?(addresses)
+        addresses.any? do |a|
+          a = a.to_s.downcase
+          a == "googleapis.com" || a.end_with?(".googleapis.com")
+        end
       end
-    end
 
-    # Host-boundary match: exact, or a dot-delimited suffix (case-insensitive).
-    # A single "*" in `pattern` matches exactly one host label, e.g.
-    # "bedrock-runtime.*.amazonaws.com" matches "bedrock-runtime.us-east-1.amazonaws.com".
-    def host_matches?(host, pattern)
-      pattern = pattern.to_s.downcase
-      return host == pattern || host.end_with?(".#{pattern}") unless pattern.include?("*")
+      # An intercept_addresses entry may optionally pin a port ("host:port") and/or anchor to a
+      # path prefix by embedding a "/" — e.g. "api.cohere.com/v2/chat" only matches requests to
+      # that host whose path starts with "/v2/chat", and "cognitiveservices.azure.com/openai/" only
+      # matches that multi-service Azure host's OpenAI paths, so unrelated endpoints on a shared
+      # host aren't swept in alongside the ones we mean to capture.
+      # The match is on a path *segment* boundary (trailing "/" on the pattern is optional and
+      # stripped before comparing), so "host.com/openai" matches "/openai" and "/openai/x" but not
+      # a same-prefix-but-different-segment path like "/openaiz".
+      def address_matches?(host, path, pattern)
+        host_pattern, sep, path_pattern = pattern.to_s.partition("/")
+        return host_matches?(host, host_pattern) if sep.empty?
+        return false unless host_matches?(host, host_pattern)
+
+        path_pattern = path_pattern.delete_suffix("/")
+        return true if path_pattern.empty?
+
+        prefix = "/#{path_pattern}"
+        path == prefix || path.start_with?("#{prefix}/")
+      end
 
-      regex = /\A#{pattern.split('*', -1).map { |part| Regexp.escape(part) }.join('[^.]+')}\z/
-      !!(host =~ regex)
-    end
+      # Host-boundary match: exact, or a dot-delimited suffix (case-insensitive).
+      # A single "*" in `pattern` matches exactly one host label, e.g.
+      # "bedrock-runtime.*.amazonaws.com" matches "bedrock-runtime.us-east-1.amazonaws.com".
+      def host_matches?(host, pattern)
+        pattern = pattern.to_s.downcase
+        return host == pattern || host.end_with?(".#{pattern}") unless pattern.include?("*")
 
-    def safe_parse(url)
-      URI.parse(url)
-    rescue URI::InvalidURIError
-      nil
-    end
+        regex = /\A#{pattern.split('*', -1).map { |part| Regexp.escape(part) }.join('[^.]+')}\z/
+        !!(host =~ regex)
+      end
 
-    def build_url_for_request(http, req)
-      return req.path if %r{\Ahttps?://}.match?(req.path)
+      def safe_parse(url)
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def build_url_for_request(http, req)
+        return req.path if %r{\Ahttps?://}.match?(req.path)
 
-      scheme = http.use_ssl? ? "https" : "http"
-      host = http.address
-      port = http.port
-      default = http.use_ssl? ? 443 : 80
+        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
+        url = "#{scheme}://#{host}"
+        url << ":#{port}" if port != default
+        url << req.path
+        url
+      end
     end
   end
 end

data/lib/coolhand/open_ai/batch_result_processor.rb

@@ -16,7 +16,9 @@ module Coolhand
 
         case batch_info["status"]
         when "completed"
-          process_completed_batch
+          # Downloads two files and POSTs one log per item — run it on the background log queue so
+          # the webhook response isn't held up for the whole batch.
+          LogQueue.submit(lane: :batch) { process_completed_batch_logging_errors }
         when "failed", "expired", "cancelled"
           handle_failed_batch
         when "in_progress", "validating", "finalizing"
@@ -30,6 +32,14 @@ module Coolhand
 
       private
 
+      # Runs on the batch lane's worker thread, where an escaping error would only reach
+      # Coolhand.log (silenceable) rather than the Rails log `call` reports to.
+      def process_completed_batch_logging_errors
+        process_completed_batch
+      rescue StandardError => e
+        Rails.logger.error("[Interceptor] Failed to process OpenAI batch results for #{event_data}: #{e.message}")
+      end
+
       def process_completed_batch
         input_file_id = batch_info["input_file_id"]
         return unless input_file_id
@@ -43,8 +53,12 @@ module Coolhand
         # Download and process results
         batch_response_items = download_batch_results(output_file_id)
 
+        request_items_by_id = batch_request_items.each_with_object({}) do |item, index|
+          index[item["custom_id"]] ||= item
+        end
+
         batch_response_items.each do |response_item|
-          request_item = batch_request_items.detect { |item| item["custom_id"] == response_item["custom_id"] }
+          request_item = request_items_by_id[response_item["custom_id"]]
 
           next unless request_item
 
@@ -89,33 +103,20 @@ module Coolhand
 
       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: BaseInterceptor.sanitize_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}"
+        BaseInterceptor.send_complete_request_log(
+          request_id: request_id,
+          method: method,
+          url: url,
+          request_headers: {},
+          request_body: request_body,
+          response_headers: {},
+          response_body: response_body,
+          status_code: status_code,
+          start_time: Time.at(start_time),
+          end_time: Time.at(end_time),
+          duration_ms: ((end_time - start_time) * 1000).to_i,
+          is_streaming: false
+        )
       end
 
       def batch_info

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -98,7 +98,8 @@ module Coolhand
         signed_payload = "#{webhook_id}.#{webhook_timestamp}.#{@payload}"
         expected_signature = calculate_expected_signature(secret_bytes, signed_payload)
 
-        signature_valid = webhook_signature.start_with?("v1,") &&
+        # An empty key (a bare "whsec_" secret) makes the HMAC forgeable by anyone, so never accept it.
+        signature_valid = !secret_bytes.empty? && webhook_signature.start_with?("v1,") &&
                           secure_compare(webhook_signature[3..], expected_signature)
 
         unless signature_valid

data/lib/coolhand/optimization_feedback_link_service.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "api_service"
+require_relative "write_requests"
+
+module Coolhand
+  # Requires the client's **private** key; the public key gets a 401. Unlike the logging writes,
+  # every method raises {Coolhand::Error} / {Coolhand::HttpError} on failure. See docs/feedback-links.md.
+  class OptimizationFeedbackLinkService < ApiService
+    include WriteRequests
+
+    ERROR_NOUN = "Feedback link"
+    # The server rejects more ids than this per request with a 422.
+    BULK_BATCH_SIZE = 100
+
+    def initialize
+      super("v2/optimizations")
+    end
+
+    # Returns `{ id:, optimization_id:, feedback_id:, note:, created_at: }`; `id` is the link's hashid.
+    def link_feedback(optimization_id, feedback_id, note: nil)
+      validate_id!("link_feedback", "feedback_id", feedback_id)
+      url = links_url("link_feedback", optimization_id)
+      ensure_object!(request_json(:post, url, ERROR_NOUN, body: { feedback_id: feedback_id.strip, note: note }.compact))
+    end
+
+    # Lists over 100 ids are sent in batches; a failing batch raises and earlier ones stay applied,
+    # so repeating the call is safe. Returns `{ linked:, already_linked:, errored:, not_found: }` summed
+    # across batches.
+    def bulk_link_feedback(optimization_id, feedback_ids, note: nil)
+      unless feedback_ids.is_a?(Array) && !feedback_ids.empty?
+        raise Error, "bulk_link_feedback: feedback_ids must be a non-empty array of hashids"
+      end
+
+      feedback_ids.each { |id| validate_id!("bulk_link_feedback", "feedback_ids entries", id) }
+      feedback_ids = feedback_ids.map(&:strip)
+      url = links_url("bulk_link_feedback", optimization_id)
+
+      totals = { linked: 0, already_linked: 0, errored: 0, not_found: [] }
+      feedback_ids.each_slice(BULK_BATCH_SIZE) do |batch|
+        result = request_json(:post, url, ERROR_NOUN, body: { feedback_ids: batch, note: note }.compact)
+        merge_bulk_result!(totals, result)
+      end
+      totals
+    end
+
+    # `link_id` is the `id` returned by {#link_feedback}, not the feedback's. Returns true.
+    def unlink_feedback(optimization_id, link_id)
+      validate_id!("unlink_feedback", "link_id", link_id)
+      url = URI.parse("#{links_url('unlink_feedback', optimization_id)}/#{escape_path_segment(link_id.strip)}")
+      request_json(:delete, url, ERROR_NOUN)
+      true
+    end
+
+    private
+
+    def merge_bulk_result!(totals, result)
+      ensure_object!(result)
+
+      %i[linked already_linked errored].each { |key| totals[key] += result[key].to_i }
+      totals[:not_found].concat(Array(result[:not_found]))
+    end
+
+    def ensure_object!(result)
+      raise Error, "#{ERROR_NOUN} response was not a JSON object" unless result.is_a?(Hash)
+
+      result
+    end
+
+    def links_url(method_name, optimization_id)
+      validate_id!(method_name, "optimization_id", optimization_id)
+      URI.parse("#{api_endpoint}/#{escape_path_segment(optimization_id.strip)}/feedback_links")
+    end
+
+    # A blank id would resolve to a different route and a bare dot segment would retarget the
+    # request; neither 404s, so both are rejected before any request is made.
+    def validate_id!(method_name, label, value)
+      trimmed = value.is_a?(String) ? value.strip : ""
+      return unless trimmed.empty? || [".", ".."].include?(trimmed)
+
+      raise Error, "#{method_name}: #{label} must be a non-empty hashid"
+    end
+  end
+end

data/lib/coolhand/read_query.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "uri"
+require_relative "errors"
+
+module Coolhand
+  # URL building shared by the read services. Everything goes through `URI.encode_www_form`, so a
+  # `+` UTC offset reaches the server as `%2B` instead of being read as a space.
+  module ReadQuery
+    protected
+
+    def list_url(query)
+      uri = URI.parse(api_endpoint)
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    def resource_url(id, blank_message, query = {})
+      raise Error, blank_message unless id.is_a?(String)
+
+      trimmed = id.strip
+      # A blank id resolves to the index route (bare array, not one record); a bare dot segment
+      # retargets the request at another path. Neither would 404, so both are rejected here.
+      raise Error, blank_message if trimmed.empty? || [".", ".."].include?(trimmed)
+
+      uri = URI.parse("#{api_endpoint}/#{escape_path_segment(trimmed)}")
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    # `until` is a reserved word, so a method taking an `until:` keyword cannot read it by name;
+    # callers pass `binding.local_variable_get(:until)`.
+    def window_params(since, until_)
+      { since: time_param(:since, since), until: time_param(:until, until_) }
+    end
+
+    # Accepts Time, DateTime, Date or an ISO8601 String. Strings go through untouched so the server
+    # stays the one validator. Raises ArgumentError before any request for anything else.
+    def time_param(name, value)
+      case value
+      when nil, String then value
+      when DateTime then utc_iso8601(value.to_time)
+      when Time then utc_iso8601(value)
+      when Date then value.iso8601
+      else
+        raise ArgumentError, "#{name} must be a Time, DateTime, Date or ISO8601 String, got #{value.class}"
+      end
+    end
+
+    private
+
+    # Whole seconds keep the plain form; a fractional instant keeps its microseconds so a window bound
+    # is not silently truncated.
+    def utc_iso8601(time)
+      utc = time.getutc
+      utc.subsec.zero? ? utc.iso8601 : utc.iso8601(6)
+    end
+  end
+end

data/lib/coolhand/read_requests.rb

@@ -6,9 +6,10 @@ require "json"
 require_relative "errors"
 
 module Coolhand
-  # The GET half of {ApiService}, split out to keep that class inside this repo's 200-line budget.
+  # The GET half of {ApiService}, plus the HTTP helpers {WriteRequests} shares, split out to keep
+  # that class inside this repo's 200-line budget.
   #
-  # Reads raise where writes log-and-return-nil, on purpose: a write is instrumentation inline in
+  # Reads raise where the logging writes log-and-return-nil, on purpose: a write is instrumentation inline in
   # the host app's request, while a read's caller must tell a 404 from a timeout from an empty result.
   module ReadRequests
     # 60s is deliberate, not a slip: writes allow 5, but the server bounds each *statement* at 10s
@@ -32,13 +33,7 @@ module Coolhand
 
       response = perform_get(url, noun)
 
-      unless response.is_a?(Net::HTTPSuccess)
-        raise HttpError.new(
-          "#{noun} request failed (#{response.code}): #{format_error_body(response.body)}",
-          status: response.code.to_i,
-          body: retained_error_body(response.body)
-        )
-      end
+      raise_http_error(response, noun) unless response.is_a?(Net::HTTPSuccess)
 
       [parse_json_body(response.body, noun), response]
     end
@@ -47,10 +42,7 @@ module Coolhand
 
     def perform_get(url, noun)
       uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = (uri.scheme == "https")
-      http.open_timeout = READ_OPEN_TIMEOUT
-      http.read_timeout = READ_TIMEOUT
+      http = build_http(uri)
 
       request = Net::HTTP::Get.new(uri.request_uri)
       apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
@@ -62,6 +54,27 @@ module Coolhand
       raise Error, "#{noun} request failed: #{e.message}"
     end
 
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = READ_OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+      http
+    end
+
+    def raise_http_error(response, noun)
+      raise HttpError.new(
+        "#{noun} request failed (#{response.code}): #{format_error_body(response.body)}",
+        status: response.code.to_i,
+        body: retained_error_body(response.body)
+      )
+    end
+
+    # Escapes to RFC 3986 unreserved, so an id carrying `/`, `?` or `#` cannot retarget the request.
+    def escape_path_segment(value)
+      URI::DEFAULT_PARSER.escape(value, /[^A-Za-z0-9\-._~]/)
+    end
+
     def retained_error_body(body)
       return body if body.nil? || body.length <= RETAINED_ERROR_BODY_LIMIT