coolhand 0.8.0 → 0.10.0

data/lib/coolhand/declarable.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Declares the workload/template of the LLM calls a class makes, once, on the class, so passive
+  # capture picks them up without a `Coolhand.with_context` block at every call site. Wrapped methods
+  # run inside `with_context`, so nesting and precedence are exactly those documented in
+  # docs/declared_workloads.md. Settings are inherited by subclasses.
+  #
+  #   class ApplicationService
+  #     include Coolhand::Declarable
+  #     coolhand_workload reporter: "my-app"
+  #     coolhand_declare_all
+  #   end
+  #
+  #   class Parser < ApplicationService
+  #     def call = client.chat(...) # workload "Parser#call", template "Parser#call"
+  #   end
+  module Declarable
+    def self.included(base)
+      raise ArgumentError, "Coolhand::Declarable can only be included in a class" unless base.is_a?(Class)
+
+      base.extend(ClassMethods)
+    end
+
+    # Never an LLM call site, and wrapping them would tax every call or declare a junk workload.
+    SKIPPED_METHODS = %i[method_missing respond_to? respond_to_missing? == === eql? equal? hash to_s inspect
+                         to_str to_ary to_proc coerce <=>].freeze
+    ATTRIBUTE_MACROS = %w[attr attr_reader attr_writer attr_accessor].freeze
+    private_constant :SKIPPED_METHODS, :ATTRIBUTE_MACROS
+
+    module ClassMethods
+      # Class-level defaults, inherited field by field (the nearest class that sets a field wins). With
+      # no `key`, each wrapped method declares its own workload, "ClassName#method"; a `key` makes every
+      # method share one workload. The class name is the runtime class, so an inherited method declares
+      # under the subclass.
+      def coolhand_workload(key: nil, name: nil, description: nil, reporter: nil)
+        workload = DeclaredContext.normalize_part(:workload, { key: key, name: name, description: description }.compact,
+          DeclaredContext::WORKLOAD_FIELDS)
+        @coolhand_settings = { workload: workload, reporter: DeclaredContext.normalize_reporter(reporter) }.compact
+      end
+
+      # Wraps the named instance methods (now, or when they are defined later). `template:` is a key or a
+      # `{ key:, name: }` Hash; by default the template key is "ClassName#method".
+      def coolhand_declare(*names, template: nil)
+        # Checked here, at class definition, so a bad value never surfaces inside the host's method.
+        template = DeclaredContext.normalize_part(:template, template.is_a?(String) ? { key: template } : template,
+          DeclaredContext::TEMPLATE_FIELDS)
+        names.flatten.each do |name|
+          name = name.to_sym
+          (@coolhand_declared ||= {})[name] = { template: template }
+          coolhand_wrap(name) if method_defined?(name) || private_method_defined?(name)
+        end
+      end
+
+      # Wraps every public instance method defined in this class and its subclasses after this call, so
+      # put it at the top of the class body. Private and protected methods, attribute readers/writers
+      # and object-protocol methods (see SKIPPED_METHODS) are left alone; `coolhand_declare` wraps one of
+      # those if you name it.
+      def coolhand_declare_all
+        @coolhand_declare_all = true
+      end
+
+      # @api private
+      def coolhand_identity(method_name)
+        key = "#{name}##{method_name}"
+        template = coolhand_template_for(method_name)
+        {
+          reporter: coolhand_setting(:reporter),
+          workload: { key: key }.merge(coolhand_setting(:workload) || {}),
+          template: template || { key: key }
+        }
+      end
+
+      # @api private
+      def coolhand_declare_call?(method_name)
+        return false if name.nil? || !Coolhand.configuration.enabled
+        return false unless DeclaredContext.valid_key?("#{name}##{method_name}")
+
+        public_method_defined?(method_name) || !coolhand_declaration(method_name).nil?
+      end
+
+      # @api private
+      def coolhand_own_state
+        [@coolhand_settings, @coolhand_declared, @coolhand_declare_all]
+      end
+
+      private
+
+      def method_added(method_name)
+        super
+        coolhand_wrap(method_name) if !@coolhand_wrapping && coolhand_wrap?(method_name)
+      end
+
+      def coolhand_wrap?(method_name)
+        return true if coolhand_declaration(method_name)
+
+        public_method_defined?(method_name) && !SKIPPED_METHODS.include?(method_name) &&
+          coolhand_declare_all? && !attribute_definition?
+      end
+
+      # True while `attr_reader`/`attr_writer`/`attr_accessor` is what is defining the method. Read from
+      # the stack rather than by overriding those macros, which would lose the class body's
+      # `private`/`protected` default visibility. A window of frames, not one fixed depth, so a
+      # `method_added` override that calls `super` does not hide the macro.
+      def attribute_definition?
+        caller_locations(1, 8)&.any? { |frame| ATTRIBUTE_MACROS.include?(frame.base_label) } || false
+      end
+
+      def coolhand_declare_all?
+        coolhand_each_class { |klass| return true if klass.coolhand_own_state[2] }
+        false
+      end
+
+      # Redefines the method in the same class, rather than prepending a wrapper, so a later
+      # `private :name` (or `private def name`) applies to the wrapper like it would to the original.
+      def coolhand_wrap(method_name)
+        original = instance_method(method_name)
+        wrappers = (@coolhand_wrappers ||= {})
+        return if wrappers[method_name] == original
+
+        visibility = coolhand_visibility(method_name)
+        @coolhand_wrapping = true
+        define_method(method_name) do |*args, **kwargs, &block|
+          klass = self.class
+          next original.bind_call(self, *args, **kwargs, &block) unless klass.coolhand_declare_call?(method_name)
+
+          Coolhand.with_context(**klass.coolhand_identity(method_name)) do
+            original.bind_call(self, *args, **kwargs, &block)
+          end
+        end
+        send(visibility, method_name)
+        wrappers[method_name] = instance_method(method_name)
+      ensure
+        @coolhand_wrapping = false
+      end
+
+      # Includes inherited methods: wrapping one a parent made private must not make it public here.
+      def coolhand_visibility(method_name)
+        return :private if private_method_defined?(method_name)
+        return :protected if protected_method_defined?(method_name)
+
+        :public
+      end
+
+      # Yields this class and its superclasses that include Declarable, nearest first. A loop rather
+      # than a collected Array, since the lookups below run on every wrapped call.
+      def coolhand_each_class
+        klass = self
+        while klass.respond_to?(:coolhand_own_state)
+          yield klass
+          klass = klass.superclass
+        end
+      end
+
+      def coolhand_declaration(method_name)
+        coolhand_nearest(1, method_name)
+      end
+
+      def coolhand_template_for(method_name)
+        coolhand_declaration(method_name)&.fetch(:template)
+      end
+
+      def coolhand_setting(field)
+        coolhand_nearest(0, field)
+      end
+
+      # The value for `key` in the nearest class whose own state (slot `slot` of `coolhand_own_state`)
+      # sets it, or nil.
+      def coolhand_nearest(slot, key)
+        coolhand_each_class do |klass|
+          state = klass.coolhand_own_state[slot]
+          return state[key] if state&.key?(key)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/coolhand/declared_context.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Ambient workload/template identity for captured calls, set with {Coolhand.with_context}. The
+  # interceptor snapshots {current} on the calling thread before a log is queued, because the
+  # background log worker does not inherit thread-locals. See docs/declared_workloads.md.
+  module DeclaredContext
+    THREAD_KEY = :coolhand_declared_context
+
+    # The fields the server accepts under `declared.workload` / `declared.template`; anything else
+    # is dropped here rather than sent.
+    WORKLOAD_FIELDS = %i[id key name description].freeze
+    TEMPLATE_FIELDS = %i[id key name].freeze
+
+    module_function
+
+    # A frozen Hash, or nil when no context is active.
+    def current
+      Thread.current[THREAD_KEY]
+    end
+
+    def clear!
+      Thread.current[THREAD_KEY] = nil
+    end
+
+    # Each field is replaced wholesale by the innermost block that sets it. Hashes are not merged
+    # key by key: `{ id: x }` merged with `{ key: y }` would declare both, and the server prefers `id`.
+    # A template belongs to a workload, so a block that declares a workload without a template does
+    # not inherit the outer one; it would pair the new workload with a template from another.
+    def with(reporter: nil, workload: nil, template: nil)
+      previous = current
+      declared = {
+        reporter: normalize_reporter(reporter),
+        workload: normalize_part(:workload, workload, WORKLOAD_FIELDS),
+        template: normalize_part(:template, template, TEMPLATE_FIELDS)
+      }.compact
+      inherited = previous || {}
+      inherited = inherited.except(:template) if declared.key?(:workload) && !declared.key?(:template)
+      merged = inherited.merge(declared)
+      ensure_template_has_workload!(merged)
+      Thread.current[THREAD_KEY] = merged.empty? ? nil : merged.freeze
+      yield
+    ensure
+      Thread.current[THREAD_KEY] = previous
+    end
+
+    def normalize_reporter(reporter)
+      return nil if reporter.nil?
+
+      reporter.to_s
+    end
+
+    # Mirrors the server's key rules: at most 255 characters, no control or invisible characters, no
+    # leading or trailing whitespace, and no leading, trailing or doubled "/". The server answers a
+    # bad key with a 422 that rejects the whole log, so it is checked here, before the call is made.
+    MAX_KEY_LENGTH = 255
+    KEY_FORMAT = %r{
+      \A(?!/)(?!.*//)
+      [^\p{Cntrl}\p{Cf}[:space:]]
+      (?:[^\p{Cntrl}\p{Cf}]*[^\p{Cntrl}\p{Cf}[:space:]])?
+      (?<!/)\z
+    }x
+
+    def valid_key?(key)
+      key.is_a?(String) && key.length <= MAX_KEY_LENGTH && KEY_FORMAT.match?(key)
+    rescue ArgumentError, EncodingError
+      false # a string with a broken or incompatible encoding is not a valid key
+    end
+
+    # A template given by key, with no workload to create it in, is a 422 that drops the log. A
+    # template `id` refers to an existing record and needs no workload.
+    def ensure_template_has_workload!(declared)
+      template = declared[:template]
+      return if template.nil? || template.key?(:id) || declared.key?(:workload)
+
+      raise ArgumentError, "template with a :key needs a workload; declare one in this or an enclosing block"
+    end
+
+    # Validated up front: the server answers a non-object `workload`/`template` with a 422 for the
+    # whole log, which would drop the call from Coolhand rather than just its identity.
+    def normalize_part(name, value, fields)
+      return nil if value.nil?
+      raise ArgumentError, "#{name} must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+      part = value.each_with_object({}) do |(k, v), acc|
+        field = k.respond_to?(:to_sym) ? k.to_sym : nil
+        next unless fields.include?(field) && !v.nil?
+        # A blank id refers to nothing and would 422 the log, so it counts as not given.
+        next if field == :id && v.to_s.strip.empty?
+
+        acc[field] = v.to_s.dup.freeze
+      end
+      return nil if part.empty?
+
+      if part.key?(:key) && !valid_key?(part[:key])
+        raise ArgumentError, "#{name} key must be at most #{MAX_KEY_LENGTH} printable characters with no " \
+                             "surrounding whitespace and no leading, trailing or doubled \"/\""
+      end
+      unless part.key?(:id) || part.key?(:key)
+        raise ArgumentError, "#{name} needs an :id or a :key, got #{value.keys.inspect}"
+      end
+
+      part.freeze
+    end
+  end
+end

data/lib/coolhand/log_service.rb

@@ -47,13 +47,7 @@ module Coolhand
         per: per
       }.compact
 
-      logs, response = get_json_with_headers(list_url(query), ERROR_NOUN)
-      raise Error, "#{ERROR_NOUN} response was not a JSON array" unless logs.is_a?(Array)
-
-      LogSearchResult.new(
-        logs: logs,
-        pagination: Pagination.from_headers(response, items: logs, page: page, per: per)
-      ).freeze
+      fetch_list(query, LogSearchResult, :logs, page: page, per: per)
     end
 
     # The full log, with `cost` and `cost_breakdown`. Both are nil when the log has no tokens or its

data/lib/coolhand/logger_service.rb

@@ -15,24 +15,8 @@ module Coolhand
     # 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
+      { webhook_body: webhook_body, source: source }.each do |name, value|
+        return reject_webhook("#{name} is required and cannot be nil or empty") unless Coolhand.required_field?(value)
       end
 
       # Auto-generate required fields unless provided
@@ -40,7 +24,7 @@ module Coolhand
         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),
+        url: BaseInterceptor.sanitize_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],
@@ -55,6 +39,14 @@ module Coolhand
 
     private
 
+    # Silent mode warns and drops the webhook; otherwise the caller gets the error.
+    def reject_webhook(error_msg)
+      raise ArgumentError, error_msg unless Coolhand.configuration.silent
+
+      puts "COOLHAND WARNING: #{error_msg}"
+      false
+    end
+
     def build_webhook_url(source, event_type)
       base = "webhook://#{source}"
       event_type ? "#{base}/#{event_type}" : base

data/lib/coolhand/net_http_interceptor.rb

@@ -46,13 +46,12 @@ module Coolhand
           Net::HTTPResponse.prepend(ResponseInterceptor)
 
           @patched = true
-          Coolhand.log "🔗 Net::HTTP interceptor patched"
         rescue StandardError
           # Roll back this call's hold — it never actually took effect, so it must not count
           # toward the refcount or a legitimate later unpatch! would underflow against it. This
           # branch only runs when @patched was false on entry (see `next if @patched` above), so
           # forcing it back to false here is correct regardless of which line above raised —
-          # including a failure in the log call itself, after prepend already succeeded.
+          # including a failure in the second prepend, after the first already succeeded.
           @patch_count -= 1
           @patched = false
           raise
@@ -139,7 +138,9 @@ module Coolhand
         end_time = Time.now
         duration_ms = ((end_time - start_time) * 1000).round(2)
 
+        # Read here on the calling thread: the log worker thread has no access to our thread-locals.
         BaseInterceptor.send_complete_request_log(
+          declared: DeclaredContext.current,
           request_id: request_id,
           method: req.method,
           url: url,

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -7,6 +7,9 @@ require_relative "webhook_id_store"
 module Coolhand
   module OpenAi
     class WebhookValidator
+      SIGNATURE_VERSION_PREFIX = "v1,"
+      private_constant :SIGNATURE_VERSION_PREFIX
+
       attr_reader :request, :errors, :payload
 
       def initialize(request, webhook_secret)
@@ -41,27 +44,25 @@ module Coolhand
       def payload_valid?
         return true if @payload
 
-        if should_enforce_strict_validation?
-          @errors << "Empty webhook payload - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
-                     "not in development/test allowlist)"
-          Rails.logger.error(@errors.last)
-          false
-        else
-          Rails.logger.warn("Empty webhook payload - allowing in #{Rails.env} environment")
-          true
-        end
+        enforce_or_allow("Empty webhook payload",
+          "Empty webhook payload - allowing in #{Rails.env} environment")
       end
 
       def validate_in_non_production_env
+        enforce_or_allow("OpenAI webhook secret not configured",
+          "Webhook Secret is not configured - skipping signature verification in #{Rails.env}")
+      end
+
+      # Outside the development/test allowlist the webhook is rejected with `problem`; inside it the
+      # check is skipped with a warning.
+      def enforce_or_allow(problem, allow_warning)
         if should_enforce_strict_validation?
-          @errors << "OpenAI webhook secret not configured - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+          @errors << "#{problem} - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
                      "not in development/test allowlist)"
           Rails.logger.error(@errors.last)
           false
         else
-          Rails.logger.warn(
-            "Webhook Secret is not configured - skipping signature verification in #{Rails.env}"
-          )
+          Rails.logger.warn(allow_warning)
           true
         end
       end
@@ -99,8 +100,7 @@ module Coolhand
         expected_signature = calculate_expected_signature(secret_bytes, signed_payload)
 
         # 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)
+        signature_valid = !secret_bytes.empty? && signature_matches?(webhook_signature, expected_signature)
 
         unless signature_valid
           @errors << "OpenAI webhook signature verification failed"
@@ -114,6 +114,18 @@ module Coolhand
         true
       end
 
+      # Standard Webhooks allows several space-separated signatures (e.g. during secret rotation);
+      # accept the request if any v1 entry matches. Every candidate is compared (`map`, not an
+      # `any?` block) so there is no early exit on the first match.
+      # Split as binary so a header that isn't valid UTF-8 is rejected rather than raising.
+      def signature_matches?(webhook_signature, expected_signature)
+        candidates = webhook_signature.b.split.select { |entry| entry.start_with?(SIGNATURE_VERSION_PREFIX) }
+        results = candidates.map do |entry|
+          secure_compare(entry.delete_prefix(SIGNATURE_VERSION_PREFIX), expected_signature)
+        end
+        results.any?
+      end
+
       # Checked only after the signature is confirmed valid, so an
       # unsigned/forged request can't poison the id-dedup store (or fail a
       # freshness check) and DoS a later legitimate webhook with the same id.

data/lib/coolhand/public_content_service.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+require_relative "pagination"
+require_relative "read_query"
+
+module Coolhand
+  # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
+  HelpArticleSearchResult = Struct.new(:articles, :pagination, keyword_init: true)
+
+  # Read-only access to the Coolhand help center: the `public_content` endpoints (`GET /api/v2/public_content`,
+  # `/:slug` and `/categories`), the same pages served at `/help/:slug` and `/updates/:slug`. Create, update and
+  # archive are Coolhand-internal and not wrapped.
+  #
+  # Unlike every other service this one needs no API key. A configured `api_key` is sent as `X-API-Key` and lifts
+  # the anonymous limit of 30 requests per minute per IP (429 beyond); with none, no key header is sent. A key the
+  # server rejects raises a 401 {Coolhand::HttpError}; it is not retried anonymously. See docs/help-center.md.
+  class PublicContentService < ApiService
+    include ReadQuery
+
+    ERROR_NOUN = "Help center"
+    BLANK_SLUG_MESSAGE = "get_help_article: slug must be a non-empty string"
+
+    def initialize
+      super("v2/public_content")
+    end
+
+    # Relevance search with `query`, a full listing without. `category` filters to one section slug; the
+    # endpoint has no such parameter, so it is sent as `q[help_category_slug_eq]` and `query` moves to
+    # `q[full_text]` (the plain `q` string and the `q[...]` form cannot be mixed). A blank `query` or
+    # `category` counts as omitted. Returns a {HelpArticleSearchResult}; raises {Coolhand::HttpError} on a
+    # non-2xx response.
+    def search_help_articles(query: nil, category: nil, page: nil, per_page: nil)
+      params = { **search_params(query, category), page: page, per_page: per_page }.compact
+
+      fetch_list(params, HelpArticleSearchResult, :articles, page: page, per: per_page)
+    end
+
+    # One published article with its markdown `body`, `noindex` and `toc`. Raises {Coolhand::Error} before any
+    # request for a blank slug, and {Coolhand::HttpError} (404) for an unknown or unpublished one.
+    def get_help_article(slug)
+      get_json(resource_url(slug, BLANK_SLUG_MESSAGE), ERROR_NOUN)
+    end
+
+    # Every section an article can be filed under, with its `url_prefix` and `allowed_tags`.
+    def list_help_categories
+      get_json(URI.parse("#{api_endpoint}/categories"), ERROR_NOUN)
+    end
+
+    protected
+
+    def api_key_required?
+      false
+    end
+
+    private
+
+    def search_params(query, category)
+      query = nil if omitted?(query)
+      return { q: query } if omitted?(category)
+
+      { "q[help_category_slug_eq]": category, "q[full_text]": query }
+    end
+
+    def omitted?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/coolhand/rails_auto_declare.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Opt-in (`config.auto_declare`) declaration of the workload and template for LLM calls made from a
+  # Rails job or controller action, keyed "JobClass#perform" / "ControllerClass#action". Installed from
+  # {Railtie} once the app has configured Coolhand. Kept free of any Rails require: it only touches
+  # ActiveSupport and ActiveJob when a target is enabled, and only through their own load hooks.
+  module RailsAutoDeclare
+    REPORTER = "rails"
+    TARGETS = %i[active_job controller].freeze
+
+    @installed = []
+
+    module_function
+
+    def install(targets = Coolhand.configuration.auto_declare)
+      TARGETS.each do |target|
+        next unless targets.include?(target) && !@installed.include?(target)
+
+        @installed << target
+        send(:"hook_#{target}")
+      end
+    end
+
+    def hook_active_job
+      ActiveSupport.on_load(:active_job) do
+        around_perform do |job, block|
+          Coolhand::RailsAutoDeclare.declare(job.class, "perform", &block)
+        end
+      end
+    end
+
+    def hook_controller
+      ActiveSupport.on_load(:action_controller) do
+        around_action do |controller, block|
+          Coolhand::RailsAutoDeclare.declare(controller.class, controller.action_name, &block)
+        end
+      end
+    end
+
+    # Runs the block inside a declared context. Anonymous classes have no stable key, so they are left
+    # undeclared rather than named after an object id.
+    def declare(klass, method_name, &block)
+      key = "#{klass.name}##{method_name}"
+      return yield if klass.name.nil? || !Coolhand.configuration.enabled || !DeclaredContext.valid_key?(key)
+
+      Coolhand.with_context(reporter: REPORTER, workload: { key: key }, template: { key: key }, &block)
+    end
+
+    # Testing-only: forget which targets were hooked.
+    def reset!
+      @installed.clear
+    end
+  end
+end

data/lib/coolhand/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Loaded by lib/coolhand.rb only when Rails is present, so the gem keeps no Rails dependency.
+  class Railtie < ::Rails::Railtie
+    # After the app's initializers, so `config.auto_declare` has been set by `Coolhand.configure`.
+    config.after_initialize do
+      Coolhand::RailsAutoDeclare.install
+    end
+  end
+end

data/lib/coolhand/read_query.rb

@@ -4,6 +4,7 @@ require "date"
 require "time"
 require "uri"
 require_relative "errors"
+require_relative "pagination"
 
 module Coolhand
   # URL building shared by the read services. Everything goes through `URI.encode_www_form`, so a
@@ -17,6 +18,19 @@ module Coolhand
       uri
     end
 
+    # GETs a list endpoint and wraps the JSON array and its pagination headers in `result_class`,
+    # keyed by `rows_key` (the field the result struct names its rows by).
+    def fetch_list(query, result_class, rows_key, page:, per:)
+      noun = self.class::ERROR_NOUN
+      rows, response = get_json_with_headers(list_url(query), noun)
+      raise Error, "#{noun} response was not a JSON array" unless rows.is_a?(Array)
+
+      result_class.new(
+        rows_key => rows,
+        pagination: Pagination.from_headers(response, items: rows, page: page, per: per)
+      ).freeze
+    end
+
     def resource_url(id, blank_message, query = {})
       raise Error, blank_message unless id.is_a?(String)
 

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.