patient_http 1.6.0 → 1.7.0

data/lib/patient_http/connection_endpoint.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "socket"
+
+module PatientHttp
+  # Wraps an HTTP endpoint to configure each connection as it is established.
+  #
+  # When a connection timeout is given, establishing the connection (the TCP
+  # connect and the TLS handshake) is bounded by a fiber scheduler timeout that
+  # raises `IO::TimeoutError`. The timeout is not set as the socket's
+  # `IO#timeout`, which would also limit every later read and write for as long
+  # as the connection lives, so once the connection is established the request
+  # timeout alone governs the exchange.
+  #
+  # When TCP keepalive settings are given, they are applied to each TCP socket.
+  # Keepalive probes keep the mappings of NAT gateways and stateful firewalls
+  # alive while a pooled connection is idle, and let the kernel detect a dead
+  # peer so the connection is retired before a request is sent on it.
+  #
+  # When a TCP user timeout is given, the kernel aborts a connection whose
+  # transmitted data stays unacknowledged for that long, so a request sent to a
+  # peer that has silently gone away fails quickly instead of waiting for the
+  # request timeout. Data the peer has acknowledged is not affected, so a slow
+  # response is never cut short. Only Linux supports this option.
+  #
+  # @api private
+  class ConnectionEndpoint < SimpleDelegator
+    # @return [Numeric, nil] Seconds allowed to establish a connection.
+    attr_reader :connection_timeout
+
+    # @return [Hash, nil] The keepalive settings with :idle, :interval, and :count.
+    attr_reader :tcp_keepalive
+
+    # @return [Numeric, nil] Seconds transmitted data may stay unacknowledged.
+    attr_reader :tcp_user_timeout
+
+    # @param endpoint [Async::HTTP::Endpoint] The endpoint to wrap.
+    # @param connection_timeout [Numeric, nil] Seconds allowed to establish a
+    #   connection, or nil for no limit beyond the endpoint's own.
+    # @param tcp_keepalive [Hash, nil] Keepalive settings with :idle, :interval, and
+    #   :count in seconds and probes (:interval and :count optional), or nil to leave
+    #   the kernel defaults.
+    # @param tcp_user_timeout [Numeric, nil] Seconds transmitted data may stay
+    #   unacknowledged, or nil to leave the kernel default.
+    def initialize(endpoint, connection_timeout: nil, tcp_keepalive: nil, tcp_user_timeout: nil)
+      super(endpoint)
+      @connection_timeout = connection_timeout
+      @tcp_keepalive = tcp_keepalive
+      @tcp_user_timeout = tcp_user_timeout
+    end
+
+    # Connects to the wrapped endpoint and configures the socket.
+    #
+    # @yield [socket] The connected socket, closed when the block returns.
+    # @return [IO] The connected socket when no block is given.
+    def connect
+      socket = connect_within_timeout
+      begin
+        apply_tcp_keepalive(socket)
+        apply_tcp_user_timeout(socket)
+      rescue
+        socket.close
+        raise
+      end
+
+      return socket unless block_given?
+
+      begin
+        yield socket
+      ensure
+        socket.close
+      end
+    end
+
+    private
+
+    def connect_within_timeout
+      task = ::Async::Task.current?
+      return __getobj__.connect unless @connection_timeout && task
+
+      task.with_timeout(@connection_timeout, ::IO::TimeoutError, "Connect timed out") do
+        __getobj__.connect
+      end
+    end
+
+    # Keepalive is a TCP feature, so it is skipped for the socket pair behind a
+    # proxy tunnel. The kernel constants differ by platform: Linux names the idle
+    # time TCP_KEEPIDLE, macOS names it TCP_KEEPALIVE. A socket that rejects an
+    # option keeps working without it, and an interval or count that is not
+    # given keeps the kernel default.
+    #
+    # Top-level constants are written with a leading `::` because Delegator
+    # descends from BasicObject, where `defined?` cannot see them.
+    def apply_tcp_keepalive(socket)
+      return unless @tcp_keepalive
+
+      raw_socket = tcp_socket(socket)
+      return unless raw_socket
+
+      raw_socket.setsockopt(::Socket::SOL_SOCKET, ::Socket::SO_KEEPALIVE, true)
+      if (idle_option = keepalive_idle_option)
+        raw_socket.setsockopt(::Socket::IPPROTO_TCP, idle_option, @tcp_keepalive[:idle])
+      end
+      interval = @tcp_keepalive[:interval]
+      if interval && defined?(::Socket::TCP_KEEPINTVL)
+        raw_socket.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_KEEPINTVL, interval)
+      end
+      count = @tcp_keepalive[:count]
+      if count && defined?(::Socket::TCP_KEEPCNT)
+        raw_socket.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_KEEPCNT, count)
+      end
+    rescue ::SystemCallError
+      nil
+    end
+
+    def keepalive_idle_option
+      if defined?(::Socket::TCP_KEEPIDLE)
+        ::Socket::TCP_KEEPIDLE
+      elsif defined?(::Socket::TCP_KEEPALIVE)
+        ::Socket::TCP_KEEPALIVE
+      end
+    end
+
+    # The kernel takes the user timeout in milliseconds, and a value of zero
+    # restores its default instead of enforcing a limit, so a positive duration
+    # is rounded up to at least one millisecond. Platforms without the option
+    # keep their default retransmission limits.
+    def apply_tcp_user_timeout(socket)
+      return unless @tcp_user_timeout && defined?(::Socket::TCP_USER_TIMEOUT)
+
+      raw_socket = tcp_socket(socket)
+      return unless raw_socket
+
+      milliseconds = (@tcp_user_timeout * 1000).ceil
+      raw_socket.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_USER_TIMEOUT, milliseconds)
+    rescue ::SystemCallError
+      nil
+    end
+
+    # The TCP socket behind a plain or TLS connection, or nil for a socket that
+    # is not TCP, such as the socket pair behind a proxy tunnel.
+    def tcp_socket(socket)
+      raw_socket = socket.respond_to?(:to_io) ? socket.to_io : socket
+      return nil unless raw_socket.is_a?(::BasicSocket) && raw_socket.local_address.ip?
+
+      raw_socket
+    end
+  end
+end

data/lib/patient_http/encryptor.rb

@@ -1,27 +1,36 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Handles encryption and decryption of payloads for secure storage.
+  # Encrypts payloads before they're stored in a job queue, and decrypts them
+  # after they're read.
   #
-  # 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.
+  # The encryptor serializes a hash to JSON, passes the bytes to the encryption
+  # callable, and stores the Base64-encoded result as
+  # `{"__encrypted__" => true, "value" => "<base64>"}`. You can use any
+  # encryption library.
+  #
+  # @see Configuration#encryptor
   class Encryptor
-    # Initialize a new Encryptor with optional encryption and decryption callables.
+    # Creates an encryptor. Without callables, the encryptor returns data
+    # unchanged.
     #
-    # @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
+    # @param encryption [#call, nil] An object that takes the bytes as a String
+    #   and returns the encrypted bytes.
+    # @param decryption [#call, nil] An object that takes the encrypted bytes and
+    #   returns the decrypted bytes.
     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.
+    # Encrypts a hash. If no encryption callable is set, the hash is returned
+    # unchanged.
     #
-    # @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
+    # @param data [Hash, nil] The data to encrypt.
+    # @return [Hash, nil] The encrypted data, or the original data if no
+    #   encryption callable is set.
+    # @raise [ArgumentError] If the data isn't a Hash or `nil`.
+    # @raise [JSON::GeneratorError] If the data can't be serialized to JSON.
     def encrypt(data)
       return nil if data.nil?
 
@@ -37,13 +46,14 @@ module PatientHttp
       }
     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.
+    # Decrypts a hash. If no decryption callable is set, or if the hash isn't
+    # encrypted, the hash is returned unchanged. As a result, data written
+    # before encryption was turned on can still be read.
     #
-    # @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
+    # @param data [Hash, nil] The data to decrypt.
+    # @return [Hash, nil] The decrypted data, or the original data.
+    # @raise [ArgumentError] If the data isn't a Hash or `nil`.
+    # @raise [JSON::ParserError] If the decrypted data isn't valid JSON.
     def decrypt(data)
       return nil if data.nil?
 

data/lib/patient_http/error.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Base error class for async HTTP errors. This is an abstract class that
-  # defines the common error interface.
+  # The abstract base class for errors that a request passes to the `on_error`
+  # callback. It defines the methods that all of these errors have.
+  #
+  # The subclasses are {HttpError}, {RedirectError}, and {RequestError}.
   class Error < StandardError
     class << self
-      # Load an error from a hash, dispatching to the appropriate subclass.
+      # Creates an error from its serialized form. The hash determines the
+      # subclass.
       #
-      # @param hash [Hash] hash representation of the error
-      # @return [Error] the reconstructed error
+      # @param hash [Hash] The hash from {#as_json}.
+      # @return [Error] The error.
       def load(hash)
         # Dispatch based on hash structure
         if hash.key?("response")
@@ -21,54 +24,57 @@ module PatientHttp
       end
     end
 
-    # Returns the error type symbol. Provided for compatibility with RequestError.
+    # Returns the error type. Subclasses return a more specific value.
     #
-    # @return [Symbol] the error type
+    # @return [Symbol] The error type.
     def error_type
       :unknown
     end
 
-    # @return [String] Request URL
+    # @return [String] The request URL.
     def url
       raise NotImplementedError, "Subclasses must implement #url"
     end
 
-    # @return [Symbol] HTTP method
+    # @return [Symbol] The HTTP method.
     def http_method
       raise NotImplementedError, "Subclasses must implement #http_method"
     end
 
-    # @return [Float] Request duration in seconds
+    # @return [Float] The request duration in seconds.
     def duration
       raise NotImplementedError, "Subclasses must implement #duration"
     end
 
-    # @return [String] Unique request identifier
+    # @return [String] The unique request ID.
     def request_id
       raise NotImplementedError, "Subclasses must implement #request_id"
     end
 
-    # @return [Class] the class of the exception that caused the error
+    # @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
+    # @return [CallbackArgs] The callback arguments that were passed with the
+    #   request.
     def callback_args
       raise NotImplementedError, "Subclasses must implement #callback_args"
     end
 
-    # Serialize to a hash for JSON encoding. Subclasses must implement this.
+    # Returns the error as a JSON-compatible hash. Subclasses must implement
+    # this method.
     #
-    # @return [Hash] hash representation of the error
+    # @return [Hash] The serialized error.
     def as_json
       raise NotImplementedError, "Subclasses must implement #as_json"
     end
 
-    # Serialize to JSON string.
+    # Returns the error as a JSON string.
     #
-    # @param options [Hash] options to pass to JSON.generate (for ActiveSupport compatibility)
-    # @return [String] JSON representation
+    # @param options [Hash, nil] The options for `JSON.generate`. This parameter
+    #   makes the method compatible with Active Support.
+    # @return [String] The JSON string.
     def to_json(options = nil)
       JSON.generate(as_json, options)
     end

data/lib/patient_http/external_storage.rb

@@ -1,18 +1,19 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Handles external storage of large payloads.
+  # Stores large payloads in the registered payload store, and replaces them
+  # with a reference.
   #
-  # This class provides methods for storing, fetching, and deleting
-  # payloads from external storage. It is decoupled from the models
-  # being stored (Request, Response, Error).
+  # A reference has the form `{"$ref" => {"store" => name, "key" => key}}`. This
+  # class works with any JSON-compatible hash, such as a serialized {Request},
+  # {Response}, or {Error}.
   #
-  # @example Storing a large payload
+  # @example Store a payload
   #   external_storage = ExternalStorage.new(config)
   #   data = response.as_json
   #   stored_data = external_storage.store(data)
   #
-  # @example Fetching and deleting
+  # @example Fetch and delete a payload
   #   if ExternalStorage.storage_ref?(data)
   #     external_storage = ExternalStorage.new(config)
   #     original_data = external_storage.fetch(data)
@@ -20,59 +21,61 @@ module PatientHttp
   #     external_storage.delete(data)
   #   end
   class ExternalStorage
-    # Key used in serialized JSON to indicate an external storage reference
+    # The key that identifies a storage reference in serialized JSON.
     REFERENCE_KEY = "$ref"
 
+    # Raised when no payload store is registered, or when a reference names a
+    # store that isn't registered.
     class PayloadStoreNotFoundError < StandardError; end
+
+    # Raised when a referenced payload isn't in the store.
     class PayloadNotFoundError < StandardError; end
 
     class << self
-      # Check if a hash is a storage reference.
+      # Returns whether data is a storage reference.
       #
-      # @param data [Hash, Object] Data to check
-      # @return [Boolean] true if this is a reference to external storage
+      # @param data [Hash, Object] The data to check.
+      # @return [Boolean] `true` if the data is a storage reference.
       def storage_ref?(data)
         data.is_a?(Hash) && data.key?(REFERENCE_KEY)
       end
     end
 
-    # @return [Configuration] the pool configuration
+    # @return [Configuration] The configuration that has the payload stores.
     attr_reader :config
 
-    # Create a new ExternalStorage instance.
+    # Creates an external storage object.
     #
-    # @param config [Configuration] the pool configuration
+    # @param config [Configuration] The configuration that has the payload
+    #   stores.
     def initialize(config)
       @config = config
     end
 
-    # Check if a hash is a storage reference.
+    # Returns whether data is a storage reference.
     #
-    # @param data [Hash, Object] Data to check
-    # @return [Boolean] true if this is a reference to external storage
+    # @param data [Hash, Object] The data to check.
+    # @return [Boolean] `true` if the data is a storage reference.
     def storage_ref?(data)
       self.class.storage_ref?(data)
     end
 
-    # Check if external storage is enabled (i.e. a payload store is configured).
+    # Returns whether a payload store is registered.
     #
-    # @return [Boolean] true if external storage is configured
+    # @return [Boolean] `true` if a payload store is registered.
     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.
+    # Stores a hash in the default payload store, and returns a reference to
+    # it.
     #
-    # @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
+    # @param data [Hash] The hash to store.
+    # @param max_size [Integer, nil] The size in bytes above which the hash is
+    #   stored. If the JSON is this size or smaller, the original hash is
+    #   returned. If `nil`, the hash is always stored.
+    # @return [Hash] The reference, or the original hash if it wasn't stored.
+    # @raise [PayloadStoreNotFoundError] If no payload store is registered.
     def store(data, max_size: nil)
       store = config.payload_store
       raise PayloadStoreNotFoundError.new("No payload store configured") unless store
@@ -91,12 +94,13 @@ module PatientHttp
       }
     end
 
-    # Fetch a hash from external storage.
+    # Fetches a stored hash.
     #
-    # @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
+    # @param data [Hash] The reference.
+    # @return [Hash] The stored hash.
+    # @raise [ArgumentError] If the data isn't a storage reference.
+    # @raise [PayloadStoreNotFoundError] If the store isn't registered.
+    # @raise [PayloadNotFoundError] If the payload isn't in the store.
     def fetch(data)
       raise ArgumentError.new("Not a storage reference") unless self.class.storage_ref?(data)
 
@@ -113,12 +117,12 @@ module PatientHttp
       stored_data
     end
 
-    # Delete payload from external storage.
+    # Deletes a stored payload.
     #
-    # This method is idempotent - it's safe to call on non-reference hashes,
-    # already-deleted payloads, or nil values.
+    # This method is idempotent. You can call it with `nil`, with a hash that
+    # isn't a reference, or with a reference to a deleted payload.
     #
-    # @param data [Hash, nil] Reference hash (or regular hash, which is ignored)
+    # @param data [Hash, nil] The reference. Other values are ignored.
     # @return [void]
     def delete(data)
       return unless data && self.class.storage_ref?(data)

data/lib/patient_http/http_error.rb

@@ -1,23 +1,22 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Error raised when an HTTP request receives a non-2xx response status code
-  # and the raise_error_responses option is enabled.
+  # The error for a non-2xx response when the `raise_error_responses` option is
+  # set.
   #
-  # This error includes the full Response object so you can access the status code,
-  # headers, body, and other response data.
+  # The error holds the full {Response}, so you can read the status, headers,
+  # and body.
   class HttpError < Error
-    # @return [Response] The HTTP response that triggered the error
+    # @return [Response] The HTTP response that caused the error.
     attr_reader :response
 
     class << self
-      # Create a new HttpError (or subclass) from a response.
+      # Creates an error for a response. The status determines the class: a
+      # {ClientError} for 4xx, a {ServerError} for 5xx, and an `HttpError` for
+      # other non-2xx statuses.
       #
-      # Returns ClientError for 4xx responses, ServerError for 5xx responses,
-      # or HttpError for other non-2xx responses.
-      #
-      # @param response [Response] The HTTP response with non-2xx status code
-      # @return [HttpError, ClientError, ServerError] The appropriate error instance
+      # @param response [Response] The HTTP response with a non-2xx status.
+      # @return [HttpError, ClientError, ServerError] The error.
       def new(response)
         if response.client_error?
           ClientError.allocate.tap { |error| error.send(:initialize, response) }
@@ -28,65 +27,72 @@ module PatientHttp
         end
       end
 
-      # Reconstruct an HttpError from a hash
+      # Creates an error from its serialized form.
       #
-      # @param hash [Hash] hash representation
-      # @return [HttpError] reconstructed error
+      # @param hash [Hash] The hash from {#as_json}.
+      # @return [HttpError] The error.
       def load(hash)
         response = Response.load(hash["response"])
         new(response)
       end
     end
 
-    # Initializes a new HttpError.
+    # Creates an error.
     #
-    # @param response [Response] The HTTP response with non-2xx status code
+    # @param response [Response] The HTTP response with a non-2xx status.
     def initialize(response)
       super("HTTP #{response.status} response from #{response.http_method.to_s.upcase} #{response.url}")
       @response = response
     end
 
-    # Delegate common response methods for convenience.
+    # Returns the HTTP status of the response.
     #
-    # @return [Integer] HTTP status code
+    # @return [Integer] The HTTP status code.
     def status
       @response.status
     end
 
-    # Returns the error type symbol. Provided for compatibility with RequestError.
+    # Returns the error type.
     #
-    # @return [Symbol] the error type
+    # @return [Symbol] Always `:http_error`.
     def error_type
       :http_error
     end
 
+    # @return [String] The request URL.
     def url
       response.url
     end
 
+    # @return [Symbol] The HTTP method.
     def http_method
       response.http_method
     end
 
+    # @return [Float] The request duration in seconds.
     def duration
       response.duration
     end
 
+    # @return [String] The unique request ID.
     def request_id
       response.request_id
     end
 
+    # @return [Class] The class of this error.
     def error_class
       self.class
     end
 
+    # @return [CallbackArgs] The callback arguments that were passed with the
+    #   request.
     def callback_args
       response.callback_args
     end
 
-    # Convert to hash with string keys for serialization
+    # Returns the error as a JSON-compatible hash.
     #
-    # @return [Hash] hash representation
+    # @return [Hash] The serialized error.
     def as_json
       {
         "response" => @response.as_json
@@ -94,13 +100,11 @@ module PatientHttp
     end
   end
 
-  # Error raised when an HTTP request receives a 4xx (client error) response status code
-  # and the raise_error_responses option is enabled.
+  # The error for a 4xx response when the `raise_error_responses` option is set.
   class ClientError < HttpError
   end
 
-  # Error raised when an HTTP request receives a 5xx (server error) response status code
-  # and the raise_error_responses option is enabled.
+  # The error for a 5xx response when the `raise_error_responses` option is set.
   class ServerError < HttpError
   end
 end