patient_http 1.0.0

data/lib/patient_http/configuration.rb

@@ -0,0 +1,365 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Configuration for the PatientHttp processor.
+  #
+  # This class holds all configuration options for the HTTP connection pool,
+  # including connection limits, timeouts, and other HTTP client settings.
+  # It has no dependencies on any job system.
+  class Configuration
+    # Salt used for generating encryption keys. This is a fixed value to ensure
+    # consistent key generation across instances and must never be changed.
+    SALT = "patient_http_payload_encryption"
+    private_constant :SALT
+
+    # @return [Integer] Maximum number of concurrent connections
+    attr_reader :max_connections
+
+    # @return [Numeric] Default request timeout in seconds
+    attr_reader :request_timeout
+
+    # @return [Numeric] Graceful shutdown timeout in seconds
+    attr_reader :shutdown_timeout
+
+    # @return [Integer] Maximum response size in bytes
+    attr_reader :max_response_size
+
+    # @return [String, nil] Default User-Agent header value
+    attr_accessor :user_agent
+
+    # @return [Boolean] Whether to raise HttpError for non-2xx responses by default
+    attr_accessor :raise_error_responses
+
+    # @return [Integer] Maximum number of redirects to follow (0 disables redirects)
+    attr_reader :max_redirects
+
+    # @return [Integer] This is the maximum number of hosts for which connections
+    #   will be kept alive for at one time.
+    attr_reader :connection_pool_size
+
+    # @return [Numeric, nil] Connection timeout in seconds
+    attr_reader :connection_timeout
+
+    # @return [String, nil] HTTP/HTTPS proxy URL (supports authentication)
+    attr_reader :proxy_url
+
+    # @return [Integer] Number of retries for failed requests
+    attr_reader :retries
+
+    # Initializes a new Configuration with the specified options.
+    #
+    # @param max_connections [Integer] Maximum number of concurrent connections
+    # @param request_timeout [Numeric] Default request timeout in seconds
+    # @param shutdown_timeout [Numeric] Graceful shutdown timeout in seconds
+    # @param logger [Logger, nil] Logger instance to use (defaults to stdout)
+    # @param max_response_size [Integer] Maximum response size in bytes
+    # @param user_agent [String, nil] Default User-Agent header value
+    # @param raise_error_responses [Boolean] Whether to raise HttpError for non-2xx responses by default
+    # @param max_redirects [Integer] Maximum number of redirects to follow (0 disables redirects)
+    # @param connection_pool_size [Integer] Maximum number of host clients to pool
+    # @param connection_timeout [Numeric, nil] Connection timeout in seconds
+    # @param proxy_url [String, nil] HTTP/HTTPS proxy URL (supports authentication)
+    # @param retries [Integer] Number of retries for failed requests
+    def initialize(
+      max_connections: 256,
+      request_timeout: 60,
+      shutdown_timeout: 30,
+      logger: nil,
+      max_response_size: 1024 * 1024,
+      user_agent: "PatientHttp",
+      raise_error_responses: false,
+      max_redirects: 5,
+      connection_pool_size: 100,
+      connection_timeout: nil,
+      proxy_url: nil,
+      retries: 3,
+      encryption_key: nil
+    )
+      # Initialize payload store configuration
+      @payload_stores = {}
+      @default_payload_store_name = nil
+      @payload_store_mutex = Mutex.new
+
+      @encryptor = nil
+
+      self.max_connections = max_connections
+      self.request_timeout = request_timeout
+      self.shutdown_timeout = shutdown_timeout
+      self.logger = logger || Logger.new($stderr, level: Logger::ERROR)
+      self.max_response_size = max_response_size
+      self.user_agent = user_agent
+      self.raise_error_responses = raise_error_responses
+      self.max_redirects = max_redirects
+      self.connection_pool_size = connection_pool_size
+      self.connection_timeout = connection_timeout
+      self.proxy_url = proxy_url
+      self.retries = retries
+      self.encryption_key = encryption_key
+    end
+
+    # Get the logger to use to report pool events. Default is to log errors to STDERR.
+    # @return [Logger] the logger instance
+    attr_accessor :logger
+
+    def max_connections=(value)
+      validate_positive(:max_connections, value)
+      @max_connections = value
+    end
+
+    def request_timeout=(value)
+      validate_positive(:request_timeout, value)
+      @request_timeout = value
+    end
+
+    def shutdown_timeout=(value)
+      validate_positive(:shutdown_timeout, value)
+      @shutdown_timeout = value
+    end
+
+    def max_response_size=(value)
+      validate_positive(:max_response_size, value)
+      @max_response_size = value
+    end
+
+    def max_redirects=(value)
+      validate_non_negative_integer(:max_redirects, value)
+      @max_redirects = value
+    end
+
+    def connection_pool_size=(value)
+      validate_positive_integer(:connection_pool_size, value)
+      @connection_pool_size = value
+    end
+
+    def connection_timeout=(value)
+      if value.nil?
+        @connection_timeout = nil
+        return
+      end
+
+      validate_positive(:connection_timeout, value)
+      @connection_timeout = value
+    end
+
+    def proxy_url=(value)
+      if value.nil?
+        @proxy_url = nil
+        return
+      end
+
+      validate_url(:proxy_url, value)
+      @proxy_url = value
+    end
+
+    def retries=(value)
+      validate_non_negative_integer(:retries, value)
+      @retries = value
+    end
+
+    # Set the encryption callable for encrypting payloads before serialization.
+    #
+    # @param callable [#call, nil] An object that responds to #call, taking data and returning encrypted data
+    # @yield [data] A block that takes data and returns encrypted data
+    # @raise [ArgumentError] If both callable and block are provided, or if callable doesn't respond to #call
+    def encryption(callable = nil, &block)
+      @encryption = resolve_callable(:encryption, callable, &block)
+      @encryptor = nil
+    end
+
+    # Set the decryption callable for decrypting payloads after deserialization.
+    #
+    # @param callable [#call, nil] An object that responds to #call, taking data and returning decrypted data
+    # @yield [data] A block that takes data and returns decrypted data
+    # @raise [ArgumentError] If both callable and block are provided, or if callable doesn't respond to #call
+    def decryption(callable = nil, &block)
+      @decryption = resolve_callable(:decryption, callable, &block)
+      @encryptor = nil
+    end
+
+    def encryption_key=(keys)
+      keys = Array(keys).map(&:to_s).reject(&:empty?)
+      if keys.empty?
+        @encryption = nil
+        @decryption = nil
+        @encryptor = nil
+        return
+      end
+
+      unless defined?(ActiveSupport::MessageEncryptor)
+        begin
+          require "active_support/key_generator"
+          require "active_support/message_encryptor"
+        rescue LoadError
+          raise ArgumentError.new("ActiveSupport::MessageEncryptor is required for encryption_key")
+        end
+      end
+
+      key_length = ActiveSupport::MessageEncryptor.key_len
+      key_generator = lambda do |key|
+        ActiveSupport::KeyGenerator.new(key).generate_key(SALT, key_length)
+      end
+
+      encryptor = ActiveSupport::MessageEncryptor.new(key_generator.call(keys.first), cipher: "aes-256-gcm")
+      keys[1..].each { |key| encryptor.rotate(key_generator.call(key)) }
+
+      encryption { |data| encryptor.encrypt_and_sign(data) }
+      decryption { |data| encryptor.decrypt_and_verify(data) }
+      @encryptor = nil
+    end
+
+    # Return an Encryptor instance. If encryption and decryption are not set, then
+    # this will be an empty Encryptor that returns data unchanged.
+    #
+    # @return [Encryptor] the encryptor instance
+    def encryptor
+      @encryptor ||= Encryptor.new(encryption: @encryption, decryption: @decryption)
+    end
+
+    # Register a payload store for external storage of large payloads.
+    #
+    # The name is included in the serialized references to the stored data.
+    # Changing it will cause any existing reference to become invalid.
+    #
+    # Multiple stores can be registered for migration purposes. The last
+    # store registered becomes the default used for new writes. References
+    # to other registered stores remain valid for reading.
+    #
+    # @param name [Symbol, String] Unique name for this store registration
+    # @param adapter [Symbol, String] The adapter type (:file, :redis, :s3, etc.)
+    # @param options [Hash] Options passed to the adapter constructor
+    # @return [void]
+    # @raise [ArgumentError] If the adapter is not registered
+    def register_payload_store(name, adapter:, **options)
+      name = name.to_sym
+      adapter = adapter.to_sym
+
+      # Trigger autoload for common adapters
+      ensure_adapter_loaded(adapter)
+
+      unless PayloadStore::Base.lookup(adapter)
+        raise ArgumentError, "Unknown payload store adapter: #{adapter.inspect}. " \
+          "Available adapters: #{PayloadStore::Base.registered_adapters.inspect}"
+      end
+
+      store = PayloadStore::Base.create(adapter, **options)
+
+      @payload_store_mutex.synchronize do
+        @payload_stores[name] = store
+        @default_payload_store_name = name
+      end
+    end
+
+    # Get a registered payload store by name.
+    #
+    # @param name [Symbol, String, nil] Store name. If nil, returns the default store.
+    # @return [PayloadStore::Base, nil] The store instance or nil if not found
+    def payload_store(name = nil)
+      @payload_store_mutex.synchronize do
+        if name.nil?
+          return nil unless @default_payload_store_name
+
+          @payload_stores[@default_payload_store_name]
+        else
+          @payload_stores[name.to_sym]
+        end
+      end
+    end
+
+    # Get the name of the default payload store.
+    #
+    # @return [Symbol, nil] The default store name or nil if none registered
+    def default_payload_store_name
+      @payload_store_mutex.synchronize do
+        @default_payload_store_name
+      end
+    end
+
+    # Get all registered payload stores.
+    #
+    # @return [Hash{Symbol => PayloadStore::Base}] Copy of registered stores
+    def payload_stores
+      @payload_store_mutex.synchronize do
+        @payload_stores.dup
+      end
+    end
+
+    # Convert to hash for inspection
+    # @return [Hash] hash representation with string keys
+    def to_h
+      {
+        "max_connections" => max_connections,
+        "request_timeout" => request_timeout,
+        "shutdown_timeout" => shutdown_timeout,
+        "logger" => logger,
+        "max_response_size" => max_response_size,
+        "user_agent" => user_agent,
+        "raise_error_responses" => raise_error_responses,
+        "max_redirects" => max_redirects,
+        "connection_pool_size" => connection_pool_size,
+        "connection_timeout" => connection_timeout,
+        "proxy_url" => proxy_url,
+        "retries" => retries,
+        "payload_stores" => payload_stores.keys,
+        "default_payload_store" => default_payload_store_name
+      }
+    end
+
+    private
+
+    def resolve_callable(name, callable = nil, &block)
+      if callable && block
+        raise ArgumentError, "#{name} accepts either a callable argument or a block, not both"
+      end
+
+      if callable && !callable.respond_to?(:call)
+        raise ArgumentError, "#{name} callable must respond to #call"
+      end
+
+      callable || block
+    end
+
+    def validate_positive(attribute, value)
+      return if value.is_a?(Numeric) && value > 0
+
+      raise ArgumentError.new("#{attribute} must be a positive number, got: #{value.inspect}")
+    end
+
+    def validate_non_negative_integer(attribute, value)
+      return if value.is_a?(Integer) && value >= 0
+
+      raise ArgumentError.new("#{attribute} must be a non-negative integer, got: #{value.inspect}")
+    end
+
+    def validate_positive_integer(attribute, value)
+      return if value.is_a?(Integer) && value > 0
+
+      raise ArgumentError.new("#{attribute} must be a positive integer, got: #{value.inspect}")
+    end
+
+    def validate_url(attribute, value)
+      uri = URI.parse(value)
+      return if uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+
+      raise ArgumentError.new("#{attribute} must be an HTTP or HTTPS URL, got: #{value.inspect}")
+    rescue URI::InvalidURIError
+      raise ArgumentError.new("#{attribute} must be a valid URL, got: #{value.inspect}")
+    end
+
+    # Ensure adapter class is loaded (triggers autoload).
+    #
+    # @param adapter [Symbol] The adapter name
+    # @return [void]
+    def ensure_adapter_loaded(adapter)
+      case adapter
+      when :file
+        PayloadStore::FileStore
+      when :redis
+        PayloadStore::RedisStore
+      when :s3
+        PayloadStore::S3Store
+      when :active_record
+        PayloadStore::ActiveRecordStore
+      end
+    end
+  end
+end

data/lib/patient_http/encryptor.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Handles encryption and decryption of payloads for secure storage.
+  #
+  # This class provides a simple interface for encrypting data before storage and
+  # decrypting it after retrieval. It supports pluggable encryption and decryption
+  # logic, allowing you to use any encryption library or method that fits your needs.
+  class Encryptor
+    # Initialize a new Encryptor with optional encryption and decryption callables.
+    #
+    # @param encryption [#call, nil] A callable object that takes data and returns encrypted data
+    # @param decryption [#call, nil] A callable object that takes encrypted data and returns decrypted data
+    def initialize(encryption: nil, decryption: nil)
+      @encryption = encryption
+      @decryption = decryption
+    end
+
+    # Encrypt data using the provided encryption callable. If no encryption callable is set,
+    # returns the original data.
+    #
+    # @param data [Hash] The data to be encrypted
+    # @return [Hash, nil] The encrypted data as a hash or the original data if no encryption callable is set
+    # @raise [JSON::GeneratorError] If the data cannot be serialized to JSON
+    def encrypt(data)
+      return nil if data.nil?
+
+      raise ArgumentError.new("Data is not a Hash") unless data.is_a?(Hash)
+
+      return data unless @encryption
+
+      json = JSON.generate(data)
+
+      {
+        "__encrypted__" => true,
+        "value" => base64_encode(@encryption.call(json))
+      }
+    end
+
+    # Decrypt data using the provided decryption callable. If no decryption callable is set,
+    # or if the data is not marked as encrypted, returns the original data.
+    #
+    # @param data [Hash] The data to be decrypted
+    # @return [Hash, nil] The decrypted data as a hash or the original data if no decryption callable
+    #   is set or if data is not encrypted
+    # @raise [JSON::ParserError] If the decrypted data cannot be parsed as JSON
+    def decrypt(data)
+      return nil if data.nil?
+
+      raise ArgumentError.new("Data is not a Hash") unless data.is_a?(Hash)
+
+      return data unless @decryption && data["__encrypted__"]
+      return nil if data["value"].nil?
+
+      decrypted = @decryption.call(base64_decode(data["value"]))
+      JSON.parse(decrypted)
+    end
+
+    private
+
+    def base64_encode(data)
+      [data].pack("m0")
+    end
+
+    def base64_decode(data)
+      data.unpack1("m")
+    end
+  end
+end

data/lib/patient_http/error.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Base error class for async HTTP errors. This is an abstract class that
+  # defines the common error interface.
+  class Error < StandardError
+    class << self
+      # Load an error from a hash, dispatching to the appropriate subclass.
+      #
+      # @param hash [Hash] hash representation of the error
+      # @return [Error] the reconstructed error
+      def load(hash)
+        # Dispatch based on hash structure
+        if hash.key?("response")
+          HttpError.load(hash)
+        elsif hash.key?("redirects")
+          RedirectError.load(hash)
+        else
+          RequestError.load(hash)
+        end
+      end
+    end
+
+    # Returns the error type symbol. Provided for compatibility with RequestError.
+    #
+    # @return [Symbol] the error type
+    def error_type
+      :unknown
+    end
+
+    # @return [String] Request URL
+    def url
+      raise NotImplementedError, "Subclasses must implement #url"
+    end
+
+    # @return [Symbol] HTTP method
+    def http_method
+      raise NotImplementedError, "Subclasses must implement #http_method"
+    end
+
+    # @return [Float] Request duration in seconds
+    def duration
+      raise NotImplementedError, "Subclasses must implement #duration"
+    end
+
+    # @return [String] Unique request identifier
+    def request_id
+      raise NotImplementedError, "Subclasses must implement #request_id"
+    end
+
+    # @return [Class] the class of the exception that caused the error
+    def error_class
+      raise NotImplementedError, "Subclasses must implement #error_class"
+    end
+
+    # @return [CallbackArgs] the callback arguments
+    def callback_args
+      raise NotImplementedError, "Subclasses must implement #callback_args"
+    end
+
+    # Serialize to a hash for JSON encoding. Subclasses must implement this.
+    #
+    # @return [Hash] hash representation of the error
+    def as_json
+      raise NotImplementedError, "Subclasses must implement #as_json"
+    end
+
+    # Serialize to JSON string.
+    #
+    # @param options [Hash] options to pass to JSON.generate (for ActiveSupport compatibility)
+    # @return [String] JSON representation
+    def to_json(options = nil)
+      JSON.generate(as_json, options)
+    end
+  end
+end

data/lib/patient_http/external_storage.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Handles external storage of large payloads.
+  #
+  # This class provides methods for storing, fetching, and deleting
+  # payloads from external storage. It is decoupled from the models
+  # being stored (Request, Response, Error).
+  #
+  # @example Storing a large payload
+  #   external_storage = ExternalStorage.new(config)
+  #   data = response.as_json
+  #   stored_data = external_storage.store(data)
+  #
+  # @example Fetching and deleting
+  #   if ExternalStorage.storage_ref?(data)
+  #     external_storage = ExternalStorage.new(config)
+  #     original_data = external_storage.fetch(data)
+  #     response = Response.load(original_data)
+  #     external_storage.delete(data)
+  #   end
+  class ExternalStorage
+    # Key used in serialized JSON to indicate an external storage reference
+    REFERENCE_KEY = "$ref"
+
+    class PayloadStoreNotFoundError < StandardError; end
+    class PayloadNotFoundError < StandardError; end
+
+    class << self
+      # Check if a hash is a storage reference.
+      #
+      # @param data [Hash, Object] Data to check
+      # @return [Boolean] true if this is a reference to external storage
+      def storage_ref?(data)
+        data.is_a?(Hash) && data.key?(REFERENCE_KEY)
+      end
+    end
+
+    # @return [Configuration] the pool configuration
+    attr_reader :config
+
+    # Create a new ExternalStorage instance.
+    #
+    # @param config [Configuration] the pool configuration
+    def initialize(config)
+      @config = config
+    end
+
+    # Check if a hash is a storage reference.
+    #
+    # @param data [Hash, Object] Data to check
+    # @return [Boolean] true if this is a reference to external storage
+    def storage_ref?(data)
+      self.class.storage_ref?(data)
+    end
+
+    # Check if external storage is enabled (i.e. a payload store is configured).
+    #
+    # @return [Boolean] true if external storage is configured
+    def enabled?
+      !!config.payload_store
+    end
+
+    # Store a hash externally if it exceeds the configured threshold.
+    #
+    # If no payload store is configured, or if the hash is below the
+    # threshold, the original hash is returned unchanged.
+    #
+    # @param data [Hash] Hash to potentially store
+    # @param max_size [Integer, nil] Optional payload size threshold in bytes.
+    #   The JSON payload will only be stored externally if it exceeds this size.
+    #   If the JSON payload does not exceed the threshold, the original hash is returned.
+    #   When nil (the default), the payload is always stored externally.
+    # @return [Hash] Reference hash if stored, original hash if not
+    # @raise [PayloadStoreNotFoundError] If no payload store is configured
+    def store(data, max_size: nil)
+      store = config.payload_store
+      raise PayloadStoreNotFoundError.new("No payload store configured") unless store
+
+      json = JSON.generate(data)
+      return data if max_size && json.bytesize <= max_size
+
+      key = store.generate_key
+      store.store_json(key, json)
+
+      {
+        REFERENCE_KEY => {
+          "store" => config.default_payload_store_name.to_s,
+          "key" => key
+        }
+      }
+    end
+
+    # Fetch a hash from external storage.
+    #
+    # @param data [Hash] Reference hash containing storage location
+    # @return [Hash] Original hash from storage
+    # @raise [PayloadStoreNotFoundError] If the store is not registered
+    # @raise [PayloadNotFoundError] If the stored payload is not found
+    def fetch(data)
+      raise ArgumentError.new("Not a storage reference") unless self.class.storage_ref?(data)
+
+      ref = data[REFERENCE_KEY]
+      store_name = ref["store"].to_sym
+      key = ref["key"]
+
+      store = config.payload_store(store_name)
+      raise PayloadStoreNotFoundError.new("Payload store '#{store_name}' not registered") unless store
+
+      stored_data = store.fetch(key)
+      raise PayloadNotFoundError.new("Stored payload not found: #{store_name}/#{key}") unless stored_data
+
+      stored_data
+    end
+
+    # Delete payload from external storage.
+    #
+    # This method is idempotent - it's safe to call on non-reference hashes,
+    # already-deleted payloads, or nil values.
+    #
+    # @param data [Hash, nil] Reference hash (or regular hash, which is ignored)
+    # @return [void]
+    def delete(data)
+      return unless data && self.class.storage_ref?(data)
+
+      ref = data[REFERENCE_KEY]
+      store_name = ref["store"].to_sym
+      key = ref["key"]
+
+      store = config.payload_store(store_name)
+      store&.delete(key)
+    end
+  end
+end