coolhand 0.9.0 → 0.10.1

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

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -20,6 +20,7 @@ module Coolhand
 
       def valid?
         @errors.clear
+        @claimed_id = nil
         @payload = request.raw_post || request.body.read
 
         return false unless payload_valid?
@@ -28,7 +29,9 @@ module Coolhand
         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 && webhook_id
+        unless webhook_signature && webhook_timestamp && webhook_id
+          return reject_unsigned("Missing OpenAI webhook signature, timestamp, or id headers")
+        end
 
         verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
       end
@@ -37,12 +40,29 @@ module Coolhand
         @errors.join(", ")
       end
 
+      # Gives back the webhook-id claim made by the last successful `valid?` so a same-id retry
+      # (e.g. after processing failed) isn't rejected as a replay. A no-op when nothing was claimed
+      # or when the store has no `release!` (custom stores may implement only `claim!`).
+      def release_claim!
+        claimed_id = @claimed_id
+        return unless claimed_id
+
+        @claimed_id = nil
+        id_store.release!(claimed_id) if id_store.respond_to?(:release!)
+      rescue StandardError => e
+        # Best effort: a failing store must not stop the caller from rejecting the request.
+        Rails.logger.error("OpenAI webhook id release failed: #{e.message}")
+      end
+
       private
 
       attr_reader :webhook_secret
 
+      # Only a nil payload counts as missing. An empty string is a real (empty) body, so it continues
+      # to the signature check, where it is accepted only if it was actually signed.
       def payload_valid?
         return true if @payload
+        return reject_unsigned("Empty webhook payload") if Coolhand.required_field?(webhook_secret)
 
         enforce_or_allow("Empty webhook payload",
           "Empty webhook payload - allowing in #{Rails.env} environment")
@@ -57,10 +77,8 @@ module Coolhand
       # check is skipped with a warning.
       def enforce_or_allow(problem, allow_warning)
         if should_enforce_strict_validation?
-          @errors << "#{problem} - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
-                     "not in development/test allowlist)"
-          Rails.logger.error(@errors.last)
-          false
+          reject("#{problem} - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+                 "not in development/test allowlist)")
         else
           Rails.logger.warn(allow_warning)
           true
@@ -83,16 +101,15 @@ module Coolhand
         [webhook_signature, webhook_timestamp, webhook_id]
       end
 
-      def validate_headers_in_non_production_env
-        if should_enforce_strict_validation?
-          @errors << "Missing OpenAI webhook signature, timestamp, or id headers - " \
-                     "rejecting webhook (Rails.env=#{Rails.env.inspect} not in development/test allowlist)"
-          Rails.logger.error(@errors.last)
-          false
-        else
-          Rails.logger.warn("Missing OpenAI webhook headers - skipping verification in #{Rails.env}")
-          true
-        end
+      # A secret is configured, so anything that can't be verified is rejected in every environment.
+      def reject_unsigned(problem)
+        reject("#{problem} - rejecting webhook")
+      end
+
+      def reject(message)
+        @errors << message
+        Rails.logger.error(message)
+        false
       end
 
       def verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
@@ -102,11 +119,7 @@ module Coolhand
         # An empty key (a bare "whsec_" secret) makes the HMAC forgeable by anyone, so never accept it.
         signature_valid = !secret_bytes.empty? && signature_matches?(webhook_signature, expected_signature)
 
-        unless signature_valid
-          @errors << "OpenAI webhook signature verification failed"
-          Rails.logger.error(@errors.last)
-          return false
-        end
+        return reject("OpenAI webhook signature verification failed") unless signature_valid
 
         return false unless timestamp_fresh?(webhook_timestamp)
         return false unless webhook_id_unused?(webhook_id)
@@ -134,18 +147,20 @@ module Coolhand
         age = (Time.now.to_i - webhook_timestamp.to_i).abs
         return true if age <= tolerance
 
-        @errors << "OpenAI webhook timestamp outside replay-protection tolerance window"
-        Rails.logger.error(@errors.last)
-        false
+        reject("OpenAI webhook timestamp outside replay-protection tolerance window")
       end
 
+      # The timestamp check accepts anything within +/- tolerance of now, so a request stamped
+      # `now + tolerance` stays fresh until `now + 2 * tolerance`. Remember the id for twice the
+      # tolerance so it can't be replayed after its claim expires but while it is still fresh.
       def webhook_id_unused?(webhook_id)
-        tolerance = Coolhand.configuration.webhook_replay_tolerance_seconds
-        return true if id_store.claim!(webhook_id, tolerance)
+        ttl = Coolhand.configuration.webhook_replay_tolerance_seconds * 2
+        if id_store.claim!(webhook_id, ttl)
+          @claimed_id = webhook_id
+          return true
+        end
 
-        @errors << "OpenAI webhook id already processed (replay protection)"
-        Rails.logger.error(@errors.last)
-        false
+        reject("OpenAI webhook id already processed (replay protection)")
       end
 
       def id_store

data/lib/coolhand/path_normalizer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module PathNormalizer
+    UNRESERVED_CHAR = /\A[A-Za-z0-9\-._~]\z/
+    private_constant :UNRESERVED_CHAR
+
+    module_function
+
+    # Path used for matching only (the URL that is sent and logged is never touched), so
+    # sloppy joins like "/openai//files", "/openai/./files", "/openai/%66iles" or
+    # "/v2/chat/../../v1/rerank" can't slip past an exclude pattern or a path anchor.
+    # Decodes unreserved-character escapes (%2F and other reserved escapes stay encoded, and
+    # decoding is one pass, so "%252e" stays literal), collapses repeated "/", and resolves
+    # "." and ".." segments without ever climbing above the root. Case is left as is. A path
+    # that can't be normalized falls back to the raw one rather than raising, and an empty
+    # path comes back as "/".
+    def normalize(path)
+      decoded = path.gsub(/%\h\h/) do |escape|
+        char = escape[1, 2].hex.chr
+        UNRESERVED_CHAR.match?(char) ? char : escape
+      end
+      segments = decoded.split("/").each_with_object([]) do |segment, kept|
+        case segment
+        when "", "." then next
+        when ".." then kept.pop
+        else kept << segment
+        end
+      end
+      directory = !segments.empty? && decoded.end_with?("/", "/.", "/..")
+      "/#{segments.join('/')}#{'/' if directory}"
+    rescue StandardError
+      path
+    end
+  end
+end

data/lib/coolhand/read_requests.rb

@@ -29,7 +29,9 @@ module Coolhand
 
     # Also returns the response, for endpoints that carry pagination in headers rather than the body.
     def get_json_with_headers(url, noun)
-      raise Error, "#{noun} request failed: an API key is required" unless Coolhand.required_field?(api_key)
+      if api_key_required? && !Coolhand.required_field?(api_key)
+        raise Error, "#{noun} request failed: an API key is required"
+      end
 
       response = perform_get(url, noun)
 
@@ -38,6 +40,11 @@ module Coolhand
       [parse_json_body(response.body, noun), response]
     end
 
+    # Overridden by services over public endpoints, which work anonymously and send the key only if set.
+    def api_key_required?
+      true
+    end
+
     private
 
     def perform_get(url, noun)
@@ -45,7 +52,9 @@ module Coolhand
       http = build_http(uri)
 
       request = Net::HTTP::Get.new(uri.request_uri)
-      apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
+      headers = { "Accept" => "application/json" }
+      headers["X-API-Key"] = api_key if Coolhand.required_field?(api_key)
+      apply_headers(request, headers)
 
       # Net::HTTP does not follow redirects, so a 3xx raises rather than replaying the API key at
       # an unapproved host. without_capture is the same recursion guard send_request uses.

data/lib/coolhand/string_body_redactor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Redacts credentials in raw String bodies, which BodyRedactor's tree walk never sees: a streamed
+  # (server-sent event) response arrives as one String of `data: {...}` lines, and a webhook body
+  # may be raw JSON text. Each JSON object/array payload is parsed, run through BodyRedactor and
+  # re-serialized; text that is not JSON (plain text, `[DONE]`, `event:` and comment lines, a
+  # payload that fails to parse) is left byte for byte. A JSON payload is always re-serialized, even
+  # when nothing in it needed redacting: JSON.parse keeps only the last of a repeated key, so
+  # "nothing changed" cannot be trusted to mean "no credential in the original text".
+  module StringBodyRedactor
+    module_function
+
+    NESTING_MARKER = { "_coolhand_capture_skipped" => "nesting_too_deep" }.freeze
+    FAILED_MARKER = { "_coolhand_capture_skipped" => "redaction_failed" }.freeze
+
+    # A `data:` field at the start of a line (LF, CRLF or bare CR), or after a byte order mark,
+    # which the SSE spec ignores. Whitespace after the colon is captured apart from the payload so
+    # a rewritten line keeps its own.
+    DATA_LINE = /(?<![^\r\n\uFEFF])data:([ \t]*)([^\r\n]*)/
+    JSON_CONTAINER = /\A\uFEFF?\s*[\[{]/
+
+    def redact(body)
+      text = utf8_text(body)
+      json = redacted_json(text) if text.match?(JSON_CONTAINER)
+      json || redact_stream(body, text)
+    rescue StandardError => e
+      # Fail closed: never log a body that could not be checked. The message is left out because
+      # a parser error can quote the payload.
+      Coolhand.log "❌ Error redacting string body: #{e.class}"
+      FAILED_MARKER
+    end
+
+    # Captured bodies are UTF-8, but a binary-tagged, other-encoded or invalid-UTF-8 String (a
+    # webhook body can be any of them) is not worth a failure: inspect a UTF-8 working copy, with
+    # invalid bytes replaced, so every line can still be checked.
+    def utf8_text(body)
+      text = case body.encoding
+             when Encoding::UTF_8 then body
+             when Encoding::BINARY then body.dup.force_encoding(Encoding::UTF_8)
+             else body.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+      text.valid_encoding? ? text : text.scrub
+    end
+
+    # One pass with gsub (linear in the body); the original String is returned when no line differs
+    # once re-serialized (providers emit compact JSON, so a clean stream usually round-trips as is).
+    def redact_stream(body, text)
+      changed = false
+      redacted = text.gsub(DATA_LINE) do |line|
+        match = Regexp.last_match
+        payload = match[2].match?(JSON_CONTAINER) ? redacted_json(match[2]) : nil
+        next line if payload.nil? || payload == match[2]
+
+        changed = true
+        "data:#{match[1]}#{payload}"
+      end
+      changed ? redacted : body
+    end
+
+    # The redacted, re-serialized JSON; nil when the text should stay as is (not a JSON
+    # object/array, or unparsable). Anything else that goes wrong yields a `redaction_failed`
+    # marker rather than the unchecked text.
+    def redacted_json(text)
+      # NaN/Infinity are not JSON, but some servers emit them; a payload that failed to parse
+      # would be logged unredacted next to its credential-named fields.
+      parsed = JSON.parse(text.delete_prefix("\uFEFF"), allow_nan: true)
+      return unless parsed.is_a?(Hash) || parsed.is_a?(Array)
+
+      redacted = BodyRedactor.redact(parsed)
+      JSON.generate(redacted, allow_nan: true)
+    rescue JSON::NestingError
+      JSON.generate(NESTING_MARKER)
+    rescue JSON::ParserError
+      nil
+    rescue StandardError => e
+      # e.g. a string with a lone surrogate that parses but cannot be serialized: fail closed for
+      # this payload alone so the rest of the body is still redacted.
+      Coolhand.log "❌ Error redacting JSON payload: #{e.class}"
+      JSON.generate(FAILED_MARKER)
+    end
+  end
+end

data/lib/coolhand/version.rb

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

data/lib/coolhand/vertex/batch_result_processor.rb

@@ -111,9 +111,9 @@ module Coolhand
           source_api: SOURCE_API,
           model: model,
           request_headers: {},
-          request_body: batch_item["request"],
+          request_body: BatchBodyCap.cap(batch_item["request"]),
           response_headers: {},
-          response_body: batch_item["response"],
+          response_body: BatchBodyCap.cap(batch_item["response"]),
           status_code: 200,
           start_time: start_time,
           end_time: end_time,

data/lib/coolhand/webhook_interceptor.rb

@@ -5,6 +5,27 @@ require_relative "open_ai/batch_result_processor"
 
 module Coolhand
   module WebhookInterceptor
+    # Helpers that must never be routable as controller actions.
+    HELPER_METHODS = %w[intercept_batch_request webhook_secret process_event].freeze
+    private_constant :HELPER_METHODS
+
+    # `private` below only covers the definitions in this module. A host that
+    # re-defines `webhook_secret` or `process_event` as public would make them
+    # public again, and Rails would then count them as action methods. Filtering
+    # them out of `action_methods` keeps them unroutable either way, without this
+    # gem depending on Rails (`super` is Rails' own `action_methods`).
+    module ClassMethods
+      def action_methods
+        super - HELPER_METHODS
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    private
+
     def intercept_batch_request
       Rails.logger.info("[Interceptor] #{controller_name}##{action_name}")
 
@@ -27,6 +48,8 @@ module Coolhand
       # 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}")
+      # Give the webhook-id back so the sender's retry isn't rejected as a replay.
+      @validator&.release_claim!
       head :unauthorized
       false
     end

data/lib/coolhand.rb

@@ -14,14 +14,18 @@ require_relative "coolhand/declared_context"
 require_relative "coolhand/declarable"
 require_relative "coolhand/rails_auto_declare"
 require_relative "coolhand/log_queue"
+require_relative "coolhand/body_redactor"
+require_relative "coolhand/string_body_redactor"
 require_relative "coolhand/base_interceptor"
 require_relative "coolhand/net_http_interceptor"
+require_relative "coolhand/batch_body_cap"
 require_relative "coolhand/api_service"
 require_relative "coolhand/logger_service"
 require_relative "coolhand/feedback_service"
 require_relative "coolhand/template_service"
 require_relative "coolhand/optimization_feedback_link_service"
 require_relative "coolhand/workload_service"
+require_relative "coolhand/help_center_service"
 require_relative "coolhand/log_service"
 require_relative "coolhand/webhook_interceptor"
 # Only when Rails is already loaded; the gem has no Rails dependency.
@@ -147,6 +151,12 @@ module Coolhand
       LogService.new
     end
 
+    # Creates a new HelpCenterService, for reading the Coolhand help center. Needs no API key; a
+    # configured one is sent and lifts the anonymous rate limit.
+    def help_center_service
+      HelpCenterService.new
+    end
+
     # Creates a new OptimizationFeedbackLinkService instance, for linking feedback to an
     # optimization as evidence. Needs the private API key.
     def optimization_feedback_link_service