patient_http 1.6.0 → 1.7.0

data/lib/patient_http/secret_reference.rb

@@ -1,17 +1,16 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # A reference to a named secret that can be used as a header or query parameter
-  # value when building a {Request}.
+  # A reference to a named secret. Use it as a header or query parameter value
+  # in a {Request}. Create one with {PatientHttp.secret}.
   #
-  # A SecretReference holds only the secret's name -- never its value. When a request
-  # is serialized (for example, to be enqueued in a job system), the reference is
-  # serialized as a lightweight marker (`{"$secret" => name}`) so the sensitive value
-  # is never written to the queue or logs. The actual value is resolved on the
-  # processor side at the moment the request is sent, using the secrets registered on
-  # the {Configuration}.
+  # The reference holds only the name of the secret, not its value. A
+  # serialized request stores the marker `{"$secret" => name}`, so the value
+  # isn't written to the job queue or to logs. The processor resolves the value
+  # from the secrets registered in the {Configuration} when it sends the
+  # request.
   #
-  # @example Referencing a secret when building a request
+  # @example Refer to secrets in a request
   #   PatientHttp.get(
   #     "https://api.example.com/data",
   #     callback: MyCallback,
@@ -19,28 +18,28 @@ module PatientHttp
   #     params: {"api_key" => PatientHttp.secret(:api_key)}
   #   )
   class SecretReference
-    # Key used in serialized JSON to indicate a secret reference.
+    # The key that identifies a secret reference in serialized JSON.
     REFERENCE_KEY = "$secret"
 
-    # @return [String] the name of the referenced secret
+    # @return [String] The secret name.
     attr_reader :name
 
     class << self
-      # Check if a value is a secret reference (either a SecretReference instance or a
-      # serialized marker hash).
+      # Returns whether a value is a secret reference. The value can be a
+      # `SecretReference` or a serialized marker hash.
       #
-      # @param value [Object] the value to check
-      # @return [Boolean] true if the value is a secret reference
+      # @param value [Object] The value to check.
+      # @return [Boolean] `true` if the value is a secret reference.
       def reference?(value)
         value.is_a?(SecretReference) ||
           (value.is_a?(Hash) && value.key?(REFERENCE_KEY))
       end
 
-      # Reconstruct a SecretReference from a serialized marker hash. Any other value
-      # (including an existing SecretReference) is returned unchanged.
+      # Creates a reference from a serialized marker hash. Other values are
+      # returned unchanged.
       #
-      # @param value [Object] a serialized marker hash or any other value
-      # @return [Object] a SecretReference for a marker hash, otherwise the original value
+      # @param value [Object] A serialized marker hash, or any other value.
+      # @return [Object] A `SecretReference` for a marker hash, or the value.
       def load(value)
         return value unless value.is_a?(Hash) && value.key?(REFERENCE_KEY)
 
@@ -48,34 +47,42 @@ module PatientHttp
       end
     end
 
-    # Initialize a new SecretReference.
+    # Creates a reference.
     #
-    # @param name [String, Symbol] the name of the secret to reference
-    # @raise [ArgumentError] if the name is empty
+    # @param name [String, Symbol] The secret name.
+    # @raise [ArgumentError] If the name is empty.
     def initialize(name)
       @name = name.to_s
       raise ArgumentError.new("secret name cannot be empty") if @name.empty?
     end
 
-    # Serialize to a marker hash. Only the name is included; the value is never present.
+    # Returns the reference as a marker hash. The hash has the name, not the
+    # value.
     #
-    # @return [Hash] the marker hash
+    # @return [Hash] The marker hash.
     def as_json
       {REFERENCE_KEY => name}
     end
 
+    # Returns whether another object is a reference to the same secret.
+    #
+    # @param other [Object] The object to compare.
+    # @return [Boolean] `true` if the names are equal.
     def ==(other)
       other.is_a?(SecretReference) && other.name == name
     end
     alias_method :eql?, :==
 
+    # Returns a hash code based on the secret name.
+    #
+    # @return [Integer] The hash code.
     def hash
       [self.class, name].hash
     end
 
-    # Inspect the reference. Only the name is shown (there is no value to leak).
+    # Returns a description of the reference. It shows only the name.
     #
-    # @return [String]
+    # @return [String] The description.
     def inspect
       "#<PatientHttp::SecretReference name=#{name.inspect}>"
     end

data/lib/patient_http/synchronous_executor.rb

@@ -1,77 +1,60 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Handles synchronous/inline execution of HTTP requests.
+  # Runs a request synchronously on the calling thread, and then calls the
+  # callback service.
   #
-  # Used for testing or when synchronous execution is needed.
-  # Accepts configuration and optional callback hooks so it has
-  # no dependency on any module-level singleton state.
+  # Use it in tests, and wherever a request must run inline. It doesn't depend
+  # on module-level state: you give it the configuration and optional hooks.
+  #
+  # The request uses a {ClientPool} that exists only for this call. The
+  # connection timeout, TCP settings, protocol, proxy, and retry rules are the
+  # same as for requests on a processor.
+  #
+  # @example Run a request
+  #   executor = PatientHttp::SynchronousExecutor.new(
+  #     task,
+  #     config: config,
+  #     on_complete: ->(response) { StatsD.increment("complete") },
+  #     on_error: ->(error) { StatsD.increment("error") }
+  #   )
+  #   executor.call
   class SynchronousExecutor
     include RedirectHelper
+    include ImmediateRetries
 
-    # @param task [RequestTask] the request task to execute
-    # @param config [Configuration] the pool configuration
-    # @param on_complete [Proc, nil] hook called with response on success
-    # @param on_error [Proc, nil] hook called with error on failure
+    # Creates an executor.
+    #
+    # @param task [RequestTask] The task to run.
+    # @param config [Configuration] The configuration for the request.
+    # @param on_complete [Proc, nil] A hook that runs with the response before
+    #   the callback service's `on_complete` method.
+    # @param on_error [Proc, nil] A hook that runs with the error before the
+    #   callback service's `on_error` method.
     def initialize(task, config:, on_complete: nil, on_error: nil)
       @task = task
       @config = config
       @on_complete = on_complete
       @on_error = on_error
-      @proxy_client = nil
       @request_preparer = RequestPreparer.new(config)
       @response_reader = ResponseReader.new(nil, config: config)
+      @client_pool = ClientPool.from_config(config)
     end
 
-    # Execute the request synchronously.
+    # Runs the request, and then calls the hook and the callback service with
+    # the response or error.
+    #
     # @return [void]
     def call
       Async do
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
         begin
-          http_client = nil
           response_data = nil
           redirect_error = nil
 
           loop do
-            http_client&.close
-            @proxy_client&.close
-            @proxy_client = nil
-            outgoing = @request_preparer.prepare(@task.request, @task.id)
-            http_client = create_http_client(outgoing.url)
-            timeout = @task.request.timeout || @config.request_timeout
-
-            response_data = Async::Task.current.with_timeout(timeout) do
-              headers = outgoing.headers.to_h
-              body = Protocol::HTTP::Body::Buffered.wrap([@task.request.body.to_s]) if @task.request.body
-
-              endpoint = Async::HTTP::Endpoint.parse(outgoing.url)
-              endpoint = configure_endpoint(endpoint) if @config.connection_timeout
-
-              verb = @task.request.http_method.to_s.upcase
-              options = {
-                headers: headers,
-                body: body,
-                scheme: endpoint.scheme,
-                authority: endpoint.authority
-              }
-
-              request = Protocol::HTTP::Request[verb, endpoint.path, **options]
-              async_response = http_client.call(request)
-              # Note: headers that appear multiple times (e.g. set-cookie) are
-              # flattened to a single joined string value.
-              headers_hash = async_response.headers.to_h.transform_values(&:to_s)
-
-              chunks = @response_reader.read_raw_body(async_response, headers_hash)
-              body_content = @response_reader.decode_body(chunks, headers_hash)
-
-              {
-                status: async_response.status,
-                headers: ResponseReader.rewrite_content_encoding(headers_hash),
-                body: body_content
-              }
-            end
+            response_data = perform_request
 
             # Check for redirect
             break unless should_follow_redirect?(@task, response_data)
@@ -123,65 +106,54 @@ module PatientHttp
           )
           invoke_callback(error, :error)
         ensure
-          http_client&.close
-          @proxy_client&.close
-          @proxy_client = nil
+          @client_pool.close
         end
       end
     end
 
     private
 
-    # Create HTTP client with config settings (retries, proxy, connection timeout).
-    #
-    # The client is not wrapped in a Protocol::HTTP::AcceptEncoding middleware.
-    # That wrapper overwrites the request's accept-encoding header, which would
-    # ignore a caller opting out of compression, so response bodies are decoded
-    # by ResponseReader here exactly as they are on the async path.
-    #
-    # @param url [String] the resolved request URL
-    # @return [Async::HTTP::Client] the HTTP client
-    def create_http_client(url)
-      endpoint = Async::HTTP::Endpoint.parse(url)
-      endpoint = configure_endpoint(endpoint) if @config.connection_timeout
-
-      if @config.proxy_url
-        create_proxied_client(endpoint)
-      else
-        Async::HTTP::Client.new(endpoint, retries: @config.retries)
-      end
-    end
+    attr_reader :config
 
-    # Create a proxied HTTP client.
+    # Sends the request of the current task and reads the full response.
     #
-    # @param endpoint [Async::HTTP::Endpoint] the target endpoint
-    # @return [Async::HTTP::Client] the proxied client
-    def create_proxied_client(endpoint)
-      require "async/http/proxy"
-
-      proxy_endpoint = Async::HTTP::Endpoint.parse(@config.proxy_url)
-      proxy_endpoint = configure_endpoint(proxy_endpoint) if @config.connection_timeout
-      @proxy_client = Async::HTTP::Client.new(proxy_endpoint)
-
-      proxy = @proxy_client.proxy(endpoint)
-      Async::HTTP::Client.new(proxy.wrap_endpoint(endpoint), retries: @config.retries)
-    end
-
-    # Configure endpoint with connection timeout if specified.
+    # {ResponseReader} decodes the body. A `Protocol::HTTP::AcceptEncoding`
+    # wrapper isn't used, because it replaces an `accept-encoding` header that
+    # the caller set to turn off compression.
     #
-    # @param endpoint [Async::HTTP::Endpoint] the endpoint to configure
-    # @return [Async::HTTP::Endpoint] the configured endpoint
-    def configure_endpoint(endpoint)
-      Async::HTTP::Endpoint.new(
-        endpoint.url,
-        timeout: @config.connection_timeout
-      )
+    # @return [Hash] The response data, with the `:status`, `:headers`, and
+    #   `:body` keys.
+    def perform_request
+      outgoing = @request_preparer.prepare(@task.request, @task.id)
+      timeout = @task.request.timeout || @config.request_timeout
+
+      Async::Task.current.with_timeout(timeout) do
+        headers = outgoing.headers.to_h
+        body = Protocol::HTTP::Body::Buffered.wrap([@task.request.body.to_s]) if @task.request.body
+
+        endpoint = Async::HTTP::Endpoint.parse(outgoing.url)
+        async_response = request_with_immediate_retries(
+          @client_pool, @task.request, endpoint, headers, body
+        )
+        # Note: headers that appear multiple times (e.g. set-cookie) are
+        # flattened to a single joined string value.
+        headers_hash = async_response.headers.to_h.transform_values(&:to_s)
+
+        chunks = @response_reader.read_raw_body(async_response, headers_hash)
+        body_content = @response_reader.decode_body(chunks, headers_hash)
+
+        {
+          status: async_response.status,
+          headers: ResponseReader.rewrite_content_encoding(headers_hash),
+          body: body_content
+        }
+      end
     end
 
-    # Invoke callback synchronously.
+    # Calls the hook and the callback service with a result.
     #
-    # @param result [Response, Error] the result to pass to callback
-    # @param type [Symbol] :response or :error
+    # @param result [Response, Error] The result.
+    # @param type [Symbol] `:response` or `:error`.
     def invoke_callback(result, type)
       callback_class = @task.callback.is_a?(Class) ? @task.callback : ClassHelper.resolve_class_name(@task.callback)
       callback = callback_class.new

data/lib/patient_http/task_handler.rb

@@ -1,53 +1,57 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Abstract base class for handling task lifecycle operations.
+  # The abstract base class that connects a {RequestTask} to a job system.
   #
-  # TaskHandler abstracts the job system integration, allowing RequestTask
-  # to work with any job system without direct dependencies. Implementations
-  # handle completion callbacks, error callbacks, and job retry operations.
+  # The processor calls the task handler to deliver a result and to re-enqueue
+  # a request that didn't finish. Because of this class, {RequestTask} doesn't
+  # depend on a job system.
   #
-  # @abstract Subclass and implement all methods to create a concrete handler.
+  # The processor calls {#on_complete} and {#on_error} on its completion worker
+  # threads. The methods must be thread-safe and idempotent, and they should
+  # return quickly, for example after they enqueue a job.
   #
-  # @example Creating a custom handler
+  # @abstract Subclass it and implement all methods.
+  #
+  # @example Create a task handler
   #   class MyTaskHandler < PatientHttp::TaskHandler
   #     def on_complete(response, callback)
-  #       # Trigger completion callback
+  #       MyJobSystem.enqueue(callback, :on_complete, response.as_json)
   #     end
   #
   #     def on_error(error, callback)
-  #       # Trigger error callback
+  #       MyJobSystem.enqueue(callback, :on_error, error.as_json)
   #     end
   #
   #     def retry
-  #       # Re-enqueue the job
+  #       MyJobSystem.enqueue_job(@job_id)
   #     end
   #   end
   class TaskHandler
-    # Trigger the completion callback with the response.
+    # Delivers a response to the callback service's `on_complete` method.
     #
-    # @param response [Response] the HTTP response object
-    # @param callback [String] callback class name
+    # @param response [Response] The HTTP response.
+    # @param callback [String] The callback service class name.
     # @return [void]
     def on_complete(response, callback)
       raise NotImplementedError, "#{self.class}#on_complete must be implemented"
     end
 
-    # Trigger the error callback with the error.
+    # Delivers an error to the callback service's `on_error` method.
     #
-    # @param error [Error] the error object
-    # @param callback [String] callback class name
+    # @param error [Error] The error.
+    # @param callback [String] The callback service class name.
     # @return [void]
     def on_error(error, callback)
       raise NotImplementedError, "#{self.class}#on_error must be implemented"
     end
 
-    # Re-enqueue the original job for retry.
+    # Re-enqueues the original job, so the request runs again later.
     #
-    # Called when a request cannot be completed (e.g., processor shutdown)
-    # and needs to be retried later.
+    # The processor calls this method for a request that didn't finish, for
+    # example when the processor shuts down.
     #
-    # @return [String] the new job ID
+    # @return [String] The new job ID.
     def retry
       raise NotImplementedError, "#{self.class}#retry must be implemented"
     end

data/lib/patient_http/time_helper.rb

@@ -1,26 +1,26 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Helper module for time-related operations using monotonic and wall clock time.
+  # Measures time with the monotonic clock, which system clock changes don't
+  # affect, and converts monotonic times to wall clock times.
   #
-  # This module provides utilities for accurate timing measurements that are immune
-  # to system clock changes, as well as conversion between monotonic and wall clock time.
+  # @api private
   module TimeHelper
     extend self
 
-    # Get the current monotonic time.
+    # Returns the current monotonic time.
     #
     # Monotonic time is guaranteed to be non-decreasing and immune to system clock changes.
     #
-    # @return [Float] current monotonic time in seconds since an unspecified starting point
+    # @return [Float] Current monotonic time in seconds since an unspecified starting point.
     def monotonic_time
       ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
     end
 
-    # Convert a monotonic timestamp to wall clock time.
+    # Converts a monotonic timestamp to wall clock time.
     #
-    # @param monotonic_timestamp [Float] monotonic timestamp to convert
-    # @return [Time] wall clock time corresponding to the monotonic timestamp
+    # @param monotonic_timestamp [Float] Monotonic timestamp to convert.
+    # @return [Time] Wall clock time corresponding to the monotonic timestamp.
     def wall_clock_time(monotonic_timestamp)
       return nil unless monotonic_timestamp