patient_http 1.0.0

data/lib/patient_http/request_helper.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Mixin that provides a compact API for scheduling async HTTP requests.
+  #
+  # Include this module in your class to get instance-level and class-level helpers for building
+  # requests and dispatching them through a registered handler.
+  #
+  # This module allows you to use the same interface for making HTTP requests while swapping out
+  # the underlying queueing mechanism for handling responses asynchronously. By registering a
+  # custom handler, you can integrate with any job queue system (Sidekiq, Solid Queue, etc.)
+  # without changing your application code that makes HTTP requests. This decouples your request
+  # interface from your async processing infrastructure.
+  #
+  # The common workflow is:
+  # 1. Register a global request handler with {PatientHttp.register_handler}.
+  # 2. Include this module in a class.
+  # 3. Optionally configure defaults with {.request_template}.
+  # 4. Call `async_get`, `async_post`, `async_put`, `async_patch`, `async_delete`, or
+  #    `async_request`.
+  #
+  # @example Register a handler
+  #   PatientHttp.register_handler do |request:, callback:, callback_args: nil, raise_error_responses: nil|
+  #     # Dispatch the request through your app-specific task/enqueue operation
+  #     # and return the request id
+  #   end
+  #
+  # @example Include in a class and enqueue requests
+  #   class ApiClient
+  #     include PatientHttp::RequestHelper
+  #
+  #     request_template base_url: "https://api.example.com", headers: {"Authorization" => "Bearer token"}
+  #
+  #     def fetch_user(user_id)
+  #       async_get("/users/#{user_id}", callback: UserCallback, callback_args: {"user_id" => user_id})
+  #     end
+  #   end
+  module RequestHelper
+    extend self
+
+    class << self
+      # Hooks helper behavior into the including class.
+      #
+      # Extends the class with {.ClassMethods} and initializes template storage.
+      #
+      # @param base [Class] class including this module
+      # @return [void]
+      def included(base)
+        base.extend(ClassMethods)
+        base.instance_variable_set(:@patient_http_request_template, nil)
+      end
+    end
+
+    module HttpMethodHelpers
+      # Enqueues an asynchronous HTTP GET request.
+      #
+      # @param uri [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param kwargs [Hash] forwarded to `async_request`
+      # @return [Object] return value from the registered request handler
+      def async_get(uri, callback:, **kwargs)
+        async_request(:get, uri, callback: callback, **kwargs)
+      end
+
+      # Enqueues an asynchronous HTTP POST request.
+      #
+      # @param uri [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param kwargs [Hash] forwarded to `async_request`
+      # @return [Object] return value from the registered request handler
+      def async_post(uri, callback:, **kwargs)
+        async_request(:post, uri, callback: callback, **kwargs)
+      end
+
+      # Enqueues an asynchronous HTTP PUT request.
+      #
+      # @param uri [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param kwargs [Hash] forwarded to `async_request`
+      # @return [Object] return value from the registered request handler
+      def async_put(uri, callback:, **kwargs)
+        async_request(:put, uri, callback: callback, **kwargs)
+      end
+
+      # Enqueues an asynchronous HTTP PATCH request.
+      #
+      # @param uri [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param kwargs [Hash] forwarded to `async_request`
+      # @return [Object] return value from the registered request handler
+      def async_patch(uri, callback:, **kwargs)
+        async_request(:patch, uri, callback: callback, **kwargs)
+      end
+
+      # Enqueues an asynchronous HTTP DELETE request.
+      #
+      # @param uri [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param kwargs [Hash] forwarded to `async_request`
+      # @return [Object] return value from the registered request handler
+      def async_delete(uri, callback:, **kwargs)
+        async_request(:delete, uri, callback: callback, **kwargs)
+      end
+    end
+
+    module ClassMethods
+      include HttpMethodHelpers
+
+      # Defines a default request template for this class.
+      #
+      # Requests created with the helper methods merge these defaults unless explicitly overridden.
+      #
+      # @param base_url [String, nil] optional base URL used to resolve relative request URLs
+      # @param headers [Hash] default headers for requests
+      # @param params [Hash, nil] default query parameters for requests
+      # @param timeout [Float] default timeout in seconds
+      # @return [void]
+      def request_template(base_url: nil, headers: {}, params: nil, timeout: 30)
+        @patient_http_request_template = RequestTemplate.new(
+          base_url: base_url,
+          headers: headers,
+          params: params,
+          timeout: timeout
+        )
+      end
+
+      # Builds and dispatches an asynchronous HTTP request.
+      #
+      # When a request template is configured, the request is built from the template. Otherwise,
+      # it is built directly from the provided arguments.
+      #
+      # @param method [Symbol] HTTP method (`:get`, `:post`, `:put`, `:patch`, `:delete`)
+      # @param url [String] absolute URL or path (when using a request template)
+      # @param callback [Class, String] callback class to handle the response
+      # @param headers [Hash, nil] request headers
+      # @param body [String, nil] raw request body
+      # @param json [Hash, Array, nil] JSON payload encoded by the request layer
+      # @param params [Hash, nil] query parameters
+      # @param timeout [Numeric, nil] timeout in seconds for this request
+      # @param raise_error_responses [Boolean, nil] when true, non-success responses are
+      #   reported as errors
+      # @param callback_args [Hash, nil] JSON-compatible callback arguments
+      # @return [Object] return value from the registered request handler
+      def async_request(
+        method,
+        url,
+        callback:,
+        headers: nil,
+        body: nil,
+        json: nil,
+        params: nil,
+        timeout: nil,
+        raise_error_responses: nil,
+        callback_args: nil
+      )
+        template = async_request_template
+        kwargs = {body: body, json: json, headers: headers, params: params, timeout: timeout}
+        request = if template
+          template.request(method, url, **kwargs)
+        else
+          Request.new(method, url, **kwargs)
+        end
+
+        PatientHttp.execute(
+          request: request,
+          callback: callback,
+          callback_args: callback_args,
+          raise_error_responses: raise_error_responses
+        )
+      end
+
+      # Returns the RequestTemplate defined for this class or its ancestors, or nil if none
+      # is defined. This allows subclasses to inherit the request template from their parent
+      # class if they don't define their own.
+      #
+      # @return [RequestTemplate, nil] the request template for this class or its ancestors
+      # @api private
+      def async_request_template
+        return @patient_http_request_template if @patient_http_request_template
+        return superclass.async_request_template if superclass.include?(PatientHttp::RequestHelper)
+
+        nil
+      end
+    end
+
+    # Dispatches an asynchronous HTTP request from an instance context.
+    #
+    # This delegates to {.ClassMethods#async_request} on the including class.
+    #
+    # @param method [Symbol] HTTP method (`:get`, `:post`, `:put`, `:patch`, `:delete`)
+    # @param url [String] absolute URL or path (when using a request template)
+    # @param callback [Class, String] callback class to handle the response
+    # @param headers [Hash, nil] request headers
+    # @param body [String, nil] raw request body
+    # @param json [Hash, Array, nil] JSON payload encoded by the request layer
+    # @param params [Hash, nil] query parameters
+    # @param timeout [Numeric, nil] timeout in seconds for this request
+    # @param raise_error_responses [Boolean, nil] when true, non-success responses are
+    #   reported as errors
+    # @param callback_args [Hash, nil] JSON-compatible callback arguments
+    # @return [Object] return value from the registered request handler
+    def async_request(
+      method,
+      url,
+      callback:,
+      headers: nil,
+      body: nil,
+      json: nil,
+      params: nil,
+      timeout: nil,
+      raise_error_responses: nil,
+      callback_args: nil
+    )
+      self.class.async_request(
+        method,
+        url,
+        callback: callback,
+        headers: headers,
+        body: body,
+        json: json,
+        params: params,
+        timeout: timeout,
+        raise_error_responses: raise_error_responses,
+        callback_args: callback_args
+      )
+    end
+
+    include HttpMethodHelpers
+  end
+end

data/lib/patient_http/request_task.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # A wrapper around {Request} that includes callback and job context for the Processor.
+  # This class allows HTTP requests to be enqueued and processed asynchronously,
+  # tracking their lifecycle and providing methods to handle success and error callbacks.
+  class RequestTask
+    include TimeHelper
+
+    # Headers that are sensitive to origin and should be stripped on cross-origin redirects
+    SENSITIVE_HEADERS = %w[authorization cookie].freeze
+
+    # @return [String] Unique UUID for tracking the task
+    attr_reader :id
+
+    # @return [Request] The HTTP request details
+    attr_reader :request
+
+    # @return [TaskHandler] The handler for job lifecycle operations
+    attr_reader :task_handler
+
+    # @return [String] Class name for the callback service
+    attr_reader :callback
+
+    # @return [Hash] Callback arguments to include in Response/Error objects (never nil, defaults to empty hash)
+    attr_reader :callback_args
+
+    # @return [Boolean] Whether to raise HttpError for non-2xx responses
+    attr_reader :raise_error_responses
+
+    # @return [Array<String>] URLs visited during redirect chain
+    attr_reader :redirects
+
+    # @return [Response, nil] The HTTP response, set on success
+    attr_reader :response
+
+    # @return [Exception, nil] The error, set on failure
+    attr_reader :error
+
+    # Initializes a new RequestTask.
+    #
+    # @param request [Request] The HTTP request to wrap.
+    # @param task_handler [TaskHandler] The handler for job lifecycle operations.
+    # @param callback [String, Class] Class name or class for the callback service.
+    # @param callback_args [Hash] Callback arguments (with string keys) to include
+    #   in Response/Error objects. These will be accessible via response.callback_args
+    #   or error.callback_args.
+    # @param raise_error_responses [Boolean] Whether to raise HttpError for non-2xx responses.
+    # @param redirects [Array<String>] URLs visited during redirect chain.
+    # @param id [String, nil] Unique UUID for tracking the task. If nil, a new UUID will be generated.
+    # @param default_max_redirects [Integer] Fallback max_redirects when request doesn't specify one.
+    def initialize(
+      request:,
+      task_handler:,
+      callback:,
+      callback_args: {},
+      raise_error_responses: false,
+      redirects: [],
+      id: nil,
+      default_max_redirects: 5
+    )
+      @id = id&.to_s || SecureRandom.uuid
+      @request = request
+      @task_handler = task_handler
+      @callback = callback.is_a?(Class) ? callback.name : callback.to_s
+      @callback_args = CallbackValidator.validate_callback_args(callback_args) || {}
+      @raise_error_responses = raise_error_responses
+      @redirects = redirects || []
+      @default_max_redirects = default_max_redirects
+
+      @enqueued_at = nil
+      @started_at = nil
+      @completed_at = nil
+      @response = nil
+      @error = nil
+
+      raise ArgumentError, "request is required" unless @request
+      raise ArgumentError, "task_handler is required" unless @task_handler
+      raise ArgumentError, "callback is required" if @callback.nil? || @callback.empty?
+      CallbackValidator.validate!(@callback)
+    end
+
+    # Mark task as enqueued
+    # @return [void]
+    def enqueued!
+      @enqueued_at = monotonic_time
+    end
+
+    # Mark task as started
+    # @return [void]
+    def started!
+      @started_at = monotonic_time
+    end
+
+    # Returns the wall clock time when the task was enqueued.
+    #
+    # @return [Time, nil] The enqueued time or nil if not enqueued.
+    def enqueued_at
+      wall_clock_time(@enqueued_at) if @enqueued_at
+    end
+
+    # Returns the wall clock time when the task was started.
+    #
+    # @return [Time, nil] The started time or nil if not started.
+    def started_at
+      wall_clock_time(@started_at) if @started_at
+    end
+
+    # Returns the wall clock time when the task was completed.
+    #
+    # @return [Time, nil] The completed time or nil if not completed.
+    def completed_at
+      wall_clock_time(@completed_at) if @completed_at
+    end
+
+    # Enqueued duration in seconds.
+    # @return [Float, nil] duration or nil if not enqueued yet.
+    def enqueued_duration
+      return nil unless @enqueued_at
+
+      (@started_at || monotonic_time) - @enqueued_at
+    end
+
+    # Execution duration in seconds.
+    # @return [Float, nil] duration or nil if not started yet.
+    def duration
+      return nil unless @started_at
+
+      ((@completed_at || monotonic_time) - @started_at).round(9)
+    end
+
+    # Re-enqueue the original job via the task handler.
+    # @return [String] job ID
+    def retry
+      @task_handler.retry
+    end
+
+    # Called with the HTTP response on a completed request. Note that
+    # the response may represent an HTTP error (4xx or 5xx status).
+    #
+    # @param response [Response] the HTTP response
+    # @return [void]
+    def completed!(response)
+      @completed_at = monotonic_time
+      @response = response
+
+      @task_handler.on_complete(response, @callback)
+    end
+
+    # Called with the HTTP error on a failed request.
+    #
+    # @param exception [Exception] the error that occurred
+    # @return [void]
+    def error!(exception)
+      @completed_at = monotonic_time
+      @error = exception
+
+      wrapped_error = exception
+      unless wrapped_error.is_a?(Error)
+        wrapped_error = RequestError.from_exception(
+          exception,
+          request_id: @id,
+          duration: duration,
+          url: request.url,
+          http_method: request.http_method,
+          callback_args: @callback_args
+        )
+      end
+
+      @task_handler.on_error(wrapped_error, @callback)
+    end
+
+    # Return true if the task successfully received a response from the server.
+    # Note that the response may represent an HTTP error (4xx or 5xx status).
+    #
+    # @return [Boolean]
+    def success?
+      !@response.nil?
+    end
+
+    # Return true if an error was raised during the request.
+    #
+    # @return [Boolean]
+    def error?
+      !@error.nil?
+    end
+
+    # Returns the maximum number of redirects to follow.
+    # Uses the request's max_redirects if set, otherwise falls back to the default.
+    #
+    # @return [Integer] maximum number of redirects
+    def max_redirects
+      request.max_redirects || @default_max_redirects
+    end
+
+    # Create a new RequestTask for following a redirect.
+    #
+    # @param location [String] The redirect URL from the Location header
+    # @param status [Integer] The HTTP status code of the redirect response
+    # @return [RequestTask] A new task configured for the redirect
+    def redirect_task(location:, status:)
+      # Determine the HTTP method and body for the redirect
+      # 301, 302, 303: Convert to GET (no body) - standard browser behavior
+      # 307, 308: Preserve original method and body
+      if [301, 302, 303].include?(status)
+        redirect_method = :get
+        redirect_body = nil
+      else
+        redirect_method = request.http_method
+        redirect_body = request.body
+      end
+
+      # Resolve the redirect URL (handle relative URLs)
+      redirect_url = resolve_redirect_url(location)
+
+      # Strip sensitive headers on cross-origin redirects to prevent credential leakage
+      redirect_headers = if cross_origin?(request.url, redirect_url)
+        request.headers.except(*SENSITIVE_HEADERS)
+      else
+        request.headers
+      end
+
+      # Create a new request for the redirect
+      redirect_request = Request.new(
+        redirect_method,
+        redirect_url,
+        headers: redirect_headers,
+        body: redirect_body,
+        timeout: request.timeout,
+        max_redirects: request.max_redirects
+      )
+
+      redirect_task_id = "#{id.split("/").first}/#{@redirects.size + 2}"
+
+      # Create the new task with updated redirects chain
+      self.class.new(
+        request: redirect_request,
+        task_handler: @task_handler,
+        callback: @callback,
+        callback_args: @callback_args,
+        raise_error_responses: @raise_error_responses,
+        redirects: @redirects + [request.url],
+        id: redirect_task_id,
+        default_max_redirects: @default_max_redirects
+      )
+    end
+
+    # Build a Response object from async response data.
+    #
+    # @param status [Integer] HTTP status code
+    # @param headers [Hash] HTTP response headers
+    # @param body [String, nil] HTTP response body
+    # @return [Response] the response object
+    # @api private
+    def build_response(status:, headers:, body:)
+      original_id = id.split("/").first
+
+      Response.new(
+        status: status,
+        headers: headers,
+        body: body,
+        duration: duration,
+        request_id: original_id,
+        url: request.url,
+        http_method: request.http_method,
+        callback_args: @callback_args,
+        redirects: @redirects
+      )
+    end
+
+    # Get the id of the first request task before any redirects. This is useful for tracking
+    # the overall request across multiple redirect tasks.
+    #
+    # @return [String] the original request id
+    def original_id
+      id.split("/").first
+    end
+
+    private
+
+    # Check if two URLs have different origins (scheme + host + port).
+    #
+    # @param original_url [String] The original request URL
+    # @param target_url [String] The redirect target URL
+    # @return [Boolean] true if the origins differ
+    def cross_origin?(original_url, target_url)
+      original = URI.parse(original_url)
+      target = URI.parse(target_url)
+
+      original.scheme != target.scheme ||
+        original.host != target.host ||
+        original.port != target.port
+    end
+
+    # Resolve a redirect URL, handling relative URLs.
+    #
+    # @param location [String] The Location header value
+    # @return [String] The resolved absolute URL
+    def resolve_redirect_url(location)
+      base_uri = URI.parse(request.url)
+      redirect_uri = URI.parse(location)
+
+      return location if redirect_uri.absolute?
+
+      base_uri.merge(redirect_uri).to_s
+    end
+  end
+end

data/lib/patient_http/request_template.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # The RequestTemplate is used to build HTTP requests with shared configuration.
+  #
+  # Use RequestTemplate when you need to make multiple requests to the same API with shared
+  # configuration (base URL, headers, timeout).
+  #
+  # @example Basic usage
+  #   template = PatientHttp::RequestTemplate.new(
+  #     base_url: "https://api.example.com",
+  #     headers: {"Authorization" => "Bearer token"},
+  #     timeout: 60
+  #   )
+  #   request = template.get("/users/123")
+  #
+  # The RequestTemplate handles building HTTP requests with proper URL joining, header merging,
+  # and parameter encoding.
+  class RequestTemplate
+    # @return [String, URI::HTTP, nil] Base URL for relative URIs
+    attr_accessor :base_url
+
+    # @return [HttpHeaders] Default headers for all requests
+    attr_accessor :headers
+
+    # @return [Float] Default request timeout in seconds
+    attr_accessor :timeout
+
+    # Initializes a new RequestTemplate.
+    #
+    # @param base_url [String, URI::HTTP, nil] Base URL for relative URIs
+    # @param headers [Hash] Default headers for all requests
+    # @param params [Hash, nil] Default query parameters to add to all requests
+    # @param timeout [Float] Default request timeout in seconds
+    def initialize(base_url: nil, headers: {}, params: nil, timeout: 30)
+      @base_url = base_url
+      @headers = HttpHeaders.new(headers)
+      @params = params
+      @timeout = timeout
+    end
+
+    # Build an async HTTP request. Returns a Request object.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :patch, :delete)
+    # @param uri [String, URI::HTTP] URI path to request (joined with base_url if relative)
+    # @param body [String, nil] request body
+    # @param json [Object, nil] JSON object to serialize (cannot use with body)
+    # @param headers [Hash] additional headers to merge with client headers
+    # @param params [Hash, nil] query parameters to add to URL
+    # @return [Request] request object
+    def request(method, uri, body: nil, json: nil, headers: nil, params: nil, timeout: nil)
+      full_uri = @base_url ? URI.join(@base_url, uri.to_s) : URI(uri)
+
+      merged_headers = headers&.any? ? @headers.merge(headers) : @headers
+      merged_params = @params ? (@params.merge(params || {})) : params
+
+      # Create request with all parameters
+      Request.new(
+        method,
+        full_uri.to_s,
+        headers: merged_headers.to_h,
+        body: body,
+        json: json,
+        params: merged_params,
+        timeout: timeout || @timeout
+      )
+    end
+
+    # Convenience method for GET requests.
+    #
+    # @param uri [String, URI::HTTP] URI path to request
+    # @param kwargs [Hash] additional options (see #request)
+    # @return [Request] request object
+    def get(uri, **kwargs)
+      request(:get, uri, **kwargs)
+    end
+
+    # Convenience method for POST requests.
+    #
+    # @param uri [String, URI::HTTP] URI path to request
+    # @param kwargs [Hash] additional options (see #request)
+    # @return [Request] request object
+    def post(uri, **kwargs)
+      request(:post, uri, **kwargs)
+    end
+
+    # Convenience method for PUT requests.
+    #
+    # @param uri [String, URI::HTTP] URI path to request
+    # @param kwargs [Hash] additional options (see #request)
+    # @return [Request] request object
+    def put(uri, **kwargs)
+      request(:put, uri, **kwargs)
+    end
+
+    # Convenience method for PATCH requests.
+    #
+    # @param uri [String, URI::HTTP] URI path to request
+    # @param kwargs [Hash] additional options (see #request)
+    # @return [Request] request object
+    def patch(uri, **kwargs)
+      request(:patch, uri, **kwargs)
+    end
+
+    # Convenience method for DELETE requests.
+    #
+    # @param uri [String, URI::HTTP] URI path to request
+    # @param kwargs [Hash] additional options (see #request)
+    # @return [Request] request object
+    def delete(uri, **kwargs)
+      request(:delete, uri, **kwargs)
+    end
+  end
+end