patient_http 1.0.0

data/lib/patient_http/http_error.rb

@@ -0,0 +1,106 @@
+# 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.
+  #
+  # This error includes the full Response object so you can access the status code,
+  # headers, body, and other response data.
+  class HttpError < Error
+    # @return [Response] The HTTP response that triggered the error
+    attr_reader :response
+
+    class << self
+      # Create a new HttpError (or subclass) from a response.
+      #
+      # 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
+      def new(response)
+        if response.client_error?
+          ClientError.allocate.tap { |error| error.send(:initialize, response) }
+        elsif response.server_error?
+          ServerError.allocate.tap { |error| error.send(:initialize, response) }
+        else
+          super
+        end
+      end
+
+      # Reconstruct an HttpError from a hash
+      #
+      # @param hash [Hash] hash representation
+      # @return [HttpError] reconstructed error
+      def load(hash)
+        response = Response.load(hash["response"])
+        new(response)
+      end
+    end
+
+    # Initializes a new HttpError.
+    #
+    # @param response [Response] The HTTP response with non-2xx status code
+    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.
+    #
+    # @return [Integer] HTTP status code
+    def status
+      @response.status
+    end
+
+    # Returns the error type symbol. Provided for compatibility with RequestError.
+    #
+    # @return [Symbol] the error type
+    def error_type
+      :http_error
+    end
+
+    def url
+      response.url
+    end
+
+    def http_method
+      response.http_method
+    end
+
+    def duration
+      response.duration
+    end
+
+    def request_id
+      response.request_id
+    end
+
+    def error_class
+      self.class
+    end
+
+    def callback_args
+      response.callback_args
+    end
+
+    # Convert to hash with string keys for serialization
+    #
+    # @return [Hash] hash representation
+    def as_json
+      {
+        "response" => @response.as_json
+      }
+    end
+  end
+
+  # Error raised when an HTTP request receives a 4xx (client error) response status code
+  # and the raise_error_responses option is enabled.
+  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.
+  class ServerError < HttpError
+  end
+end

data/lib/patient_http/http_headers.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Case insensitive HTTP headers.
+  #
+  # This class provides a hash-like interface for HTTP headers with case-insensitive
+  # key access. Header names are normalized to lowercase for storage and lookup.
+  class HttpHeaders
+    include Enumerable
+
+    # Initializes a new HttpHeaders instance.
+    #
+    # @param headers [Hash] initial headers to set
+    def initialize(headers = {})
+      @headers = {}
+      headers&.each do |key, value|
+        @headers[key.to_s.downcase] = value
+      end
+    end
+
+    # Retrieves the value for a header (case insensitive).
+    #
+    # @param key [String, Symbol] header name
+    # @return [String, nil] header value or nil if not found
+    def [](key)
+      @headers[key.to_s.downcase]
+    end
+
+    # Sets the value for a header (case insensitive).
+    #
+    # @param key [String, Symbol] header name
+    # @param value [String] header value
+    def []=(key, value)
+      @headers[key.to_s.downcase] = value
+    end
+
+    # Fetches the value for a header with an optional default.
+    #
+    # @param key [String, Symbol] header name
+    # @param default [Object] default value if header not found
+    # @return [String, Object] header value or default
+    def fetch(key, default = nil)
+      @headers.fetch(key.to_s.downcase, default)
+    end
+
+    # Merges another set of headers into a new HttpHeaders instance.
+    #
+    # @param other_headers [Hash, HttpHeaders] headers to merge
+    # @return [HttpHeaders] new instance with merged headers
+    def merge(other_headers)
+      new_headers = dup
+      other_headers.each do |key, value|
+        new_headers[key] = value
+      end
+      new_headers
+    end
+
+    # Returns a new HttpHeaders without the specified keys (case-insensitive).
+    #
+    # @param keys [Array<String, Symbol>] header names to exclude
+    # @return [HttpHeaders] new instance without the specified headers
+    def except(*keys)
+      normalized = keys.map { |k| k.to_s.downcase }
+      filtered_headers = @headers.reject { |key, _value| normalized.include?(key) } # rubocop:disable Style/HashExcept
+      self.class.new(filtered_headers)
+    end
+
+    # Converts to a regular hash with lowercase keys.
+    #
+    # @return [Hash] hash representation
+    def to_h
+      @headers.dup
+    end
+
+    # Iterates over each header.
+    #
+    # @yield [key, value] yields each header key-value pair
+    # @return [Enumerator] if no block given
+    def each(&block)
+      @headers.each(&block)
+    end
+
+    # Checks if a header exists (case insensitive).
+    #
+    # @param name [String, Symbol] header name
+    # @return [Boolean] true if header exists
+    def include?(name)
+      @headers.include?(name.to_s.downcase)
+    end
+
+    def eql?(other)
+      other.is_a?(HttpHeaders) && @headers.eql?(other.to_h)
+    end
+
+    def hash
+      @headers.hash
+    end
+  end
+end

data/lib/patient_http/lifecycle_manager.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Manages the lifecycle state of the Processor.
+  #
+  # Handles state transitions and provides predicates for checking the current state.
+  # Thread-safe state management using Concurrent::AtomicReference.
+  class LifecycleManager
+    include TimeHelper
+
+    # Valid processor states
+    STATES = %i[stopped starting running draining stopping].freeze
+
+    # Polling interval during wait operations
+    POLL_INTERVAL = 0.001
+
+    # Initialize the lifecycle manager.
+    #
+    # @return [void]
+    def initialize
+      @state = Concurrent::AtomicReference.new(:stopped)
+      @shutdown_barrier = Concurrent::Event.new
+      @reactor_ready = Concurrent::Event.new
+      @lock = Mutex.new
+    end
+
+    # Get the current state.
+    #
+    # @return [Symbol] the current state
+    def state
+      @state.get
+    end
+
+    # Check if processor is starting.
+    #
+    # @return [Boolean] true if starting
+    def starting?
+      state == :starting
+    end
+
+    # Check if processor is running.
+    #
+    # @return [Boolean] true if running
+    def running?
+      state == :running
+    end
+
+    # Check if processor is stopped.
+    #
+    # @return [Boolean] true if stopped
+    def stopped?
+      state == :stopped
+    end
+
+    # Check if processor is draining.
+    #
+    # @return [Boolean] true if draining
+    def draining?
+      state == :draining
+    end
+
+    # Check if processor is stopping.
+    #
+    # @return [Boolean] true if stopping
+    def stopping?
+      state == :stopping
+    end
+
+    # Transition to starting state.
+    #
+    # @return [Boolean] true if transition was successful
+    def start!
+      @lock.synchronize do
+        return false if starting? || running? || stopping?
+
+        @state.set(:starting)
+        @shutdown_barrier.reset
+        @reactor_ready.reset
+      end
+
+      true
+    end
+
+    # Transition to running state.
+    #
+    # @return [void]
+    def running!
+      @state.set(:running)
+    end
+
+    # Transition to draining state.
+    #
+    # @return [Boolean] true if transition was successful
+    def drain!
+      @lock.synchronize do
+        return false unless running?
+
+        @state.set(:draining)
+      end
+
+      true
+    end
+
+    # Transition to stopping state.
+    #
+    # @return [Boolean] true if transition was successful
+    def stop!
+      @lock.synchronize do
+        return false if stopped? || stopping? || starting?
+
+        @state.set(:stopping)
+        @shutdown_barrier.set
+      end
+
+      true
+    end
+
+    # Transition to stopped state.
+    #
+    # Also signals the reactor_ready event to unblock any thread
+    # waiting in {#wait_for_reactor} in case the reactor failed
+    # before it could signal readiness.
+    #
+    # @return [void]
+    def stopped!
+      @state.set(:stopped)
+      @reactor_ready.set
+    end
+
+    # Signal that the reactor is ready.
+    #
+    # @return [void]
+    def reactor_ready!
+      @reactor_ready.set
+    end
+
+    # Wait for the reactor to be ready.
+    #
+    # @return [void]
+    def wait_for_reactor
+      @reactor_ready.wait
+    end
+
+    # Check if shutdown has been signaled.
+    #
+    # @return [Boolean] true if shutdown is signaled
+    def shutdown_signaled?
+      @shutdown_barrier.set?
+    end
+
+    # Wait for running state.
+    #
+    # @param timeout [Numeric] maximum time to wait in seconds
+    # @return [Boolean] true if running, false if timeout reached
+    def wait_for_running(timeout: 5)
+      wait_for_condition(timeout: timeout) { running? }
+    end
+
+    # Wait for a condition to be met.
+    #
+    # @param timeout [Numeric] maximum time to wait in seconds
+    # @yield Block that checks the condition.
+    # @return [Boolean] true if the condition is met, false if timeout reached
+    def wait_for_condition(timeout: 1)
+      deadline = monotonic_time + timeout
+      while monotonic_time <= deadline
+        return true if yield
+
+        sleep(POLL_INTERVAL)
+      end
+      false
+    end
+  end
+end

data/lib/patient_http/payload.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Handles encoding and decoding of HTTP response bodies for storage.
+  #
+  # This class provides compression and encoding strategies for different content types
+  # to optimize storage and transmission of response data.
+  class Payload
+    # @return [Symbol] the encoding type
+    attr_reader :encoding
+
+    # @return [String] the encoded data
+    attr_reader :encoded_value
+
+    # @return [String, nil] the character set (if applicable)
+    attr_reader :charset
+
+    class << self
+      # Reconstructs a Payload from a hash representation.
+      #
+      # @param hash [Hash, nil] hash with "encoding" and "value" keys
+      # @return [Payload, nil] reconstructed payload or nil if hash is invalid
+      def load(hash)
+        return nil if hash.nil? || hash["value"].nil?
+
+        new(hash["encoding"].to_sym, hash["value"], hash["charset"])
+      end
+
+      # Encodes a value based on its MIME type.
+      #
+      # For text-based content types, applies gzip compression if beneficial.
+      # For binary content, uses Base64 encoding.
+      #
+      # @param value [String] the value to encode
+      # @param mimetype [String, nil] the MIME type of the content
+      # @return [Array(Symbol, String, String), nil] [encoding, encoded_value, charset] or nil if value is nil
+      def encode(value, mimetype)
+        return nil if value.nil?
+
+        if is_text_mimetype?(mimetype)
+          value = text_value(value, charset(mimetype))
+
+          if value.bytesize < 4096
+            [:text, value, value.encoding.name]
+          else
+            gzipped = Zlib.gzip(value)
+            if gzipped.bytesize < value.bytesize
+              [:gzipped, [gzipped].pack("m0"), value.encoding.name]
+            else
+              [:text, value, value.encoding.name]
+            end
+          end
+        else
+          [:binary, [value].pack("m0"), Encoding::BINARY.name]
+        end
+      end
+
+      # Decodes an encoded value based on its encoding type.
+      #
+      # @param encoded_value [String] the encoded data
+      # @param encoding [Symbol] the encoding type (:text, :binary, :gzipped)
+      # @param charset [String, nil] the character set (if applicable)
+      # @return [String, nil] the decoded value or nil if encoded_value is nil
+      def decode(encoded_value, encoding, charset)
+        return nil if encoded_value.nil?
+
+        decoded_value = case encoding
+        when :text
+          encoded_value
+        when :binary
+          encoded_value.unpack1("m")
+        when :gzipped
+          Zlib.gunzip(encoded_value.unpack1("m"))
+        end
+
+        force_encoding(decoded_value, charset)
+      end
+
+      private
+
+      def is_text_mimetype?(mimetype)
+        mimetype&.match?(/\Atext\/|application\/(?:json|xml|javascript)/)
+      end
+
+      def charset(mimetype)
+        return Encoding::ASCII_8BIT.name if mimetype.nil?
+
+        match = mimetype.match(/charset=([\w-]+)/)
+        return Encoding::ASCII_8BIT.name unless match
+
+        begin
+          Encoding.find(match[1])
+        rescue
+          Encoding::ASCII_8BIT.name
+        end
+      end
+
+      # Return the value as a UTF-8 encoded string if possible. If the value cannot
+      # be converted to UTF-8, return it in the response charset or ASCII-8BIT.
+      #
+      # Encoding strategy:
+      # 1. Force-encode to the response charset
+      # 2. Try to transcode to UTF-8 for storage efficiency
+      # 3. If transcoding fails, keep the charset encoding
+      # 4. If force-encoding itself fails, fall back to ASCII-8BIT
+      def text_value(value, charset)
+        text = force_encoding(value, charset)
+        unless text.encoding == Encoding::UTF_8
+          begin
+            text = text.encode(Encoding::UTF_8)
+          rescue
+            # Ignore if cannot convert to UTF-8
+          end
+        end
+        text
+      rescue
+        force_encoding(value, Encoding::ASCII_8BIT.name)
+      end
+
+      def force_encoding(value, charset)
+        return value if value.nil? || value.encoding.names.include?(charset)
+
+        charset ||= Encoding::ASCII_8BIT.name
+        value = value.dup if value.frozen?
+        value.force_encoding(charset)
+      end
+    end
+
+    # Initializes a new Payload.
+    #
+    # @param encoding [Symbol] the encoding type
+    # @param encoded_value [String] the encoded data
+    # @param charset [String, nil] the character set (if applicable)
+    def initialize(encoding, encoded_value, charset)
+      @encoded_value = encoded_value
+      @encoding = encoding
+      @charset = charset
+    end
+
+    # Returns the decoded value.
+    #
+    # @return [String, nil] the decoded data
+    def value
+      self.class.decode(encoded_value, encoding, charset)
+    end
+
+    # Converts to a hash representation for serialization.
+    #
+    # @return [Hash] hash with "encoding" and "value" keys
+    def as_json
+      {
+        "encoding" => encoding.to_s,
+        "value" => encoded_value,
+        "charset" => charset
+      }
+    end
+
+    alias_method :dump, :as_json
+  end
+end

data/lib/patient_http/payload_store/active_record_store.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PatientHttp
+  module PayloadStore
+    # ActiveRecord-based payload store for production deployments.
+    #
+    # Stores payloads as JSON in a database table. This store is recommended
+    # when you need database-backed storage with transactional guarantees.
+    #
+    # Thread-safe: ActiveRecord handles connection pooling and thread safety.
+    #
+    # @example Configuration
+    #   require "patient_http/payload_store/active_record_store"
+    #   config.register_payload_store(:database, adapter: :active_record)
+    #
+    # @example With custom model
+    #   config.register_payload_store(:database, adapter: :active_record,
+    #     model: MyApp::PayloadRecord
+    #   )
+    class ActiveRecordStore < Base
+      Base.register :active_record, self
+
+      # ActiveRecord model for payload storage.
+      #
+      # Defined in this file to avoid loading ActiveRecord until explicitly required.
+      # The table must be created using the migration provided by this gem.
+      #
+      # @example Install migrations in a Rails app
+      #   rails patient_http:install:migrations
+      #   rails db:migrate
+      class Payload < ::ActiveRecord::Base
+        self.table_name = "patient_http_payloads"
+        self.primary_key = "key"
+
+        scope :older_than, ->(time) { where(created_at: nil...time) }
+      end
+
+      # @return [Class] The ActiveRecord model class used for storage
+      attr_reader :model
+
+      # Initialize a new ActiveRecord store.
+      #
+      # @param model [Class] ActiveRecord model class to use for storage.
+      #   Defaults to PatientHttp::PayloadStore::ActiveRecordStore::Payload.
+      #   Custom models must have: key (string PK), data (text), timestamps
+      def initialize(model: nil)
+        @model = model || Payload
+      end
+
+      # Store pre-serialized JSON string directly in the database.
+      #
+      # @param key [String] Unique key (used as primary key)
+      # @param json [String] Pre-serialized JSON string
+      # @return [String] The key
+      def store_json(key, json)
+        now = Time.current
+
+        @model.with_connection do
+          @model.upsert(
+            {key: key, data: json, created_at: now, updated_at: now},
+            unique_by: :key,
+            update_only: [:data, :updated_at]
+          )
+        end
+
+        key
+      end
+
+      # Fetch data from the database.
+      #
+      # @param key [String] The key to fetch
+      # @return [Hash, nil] The stored data or nil if not found
+      def fetch(key)
+        record = @model.find_by(key: key)
+        return nil unless record
+
+        JSON.parse(record.data)
+      end
+
+      # Delete a payload from the database.
+      #
+      # Idempotent - does not raise if record doesn't exist.
+      #
+      # @param key [String] The key to delete
+      # @return [Boolean] true
+      def delete(key)
+        @model.where(key: key).delete_all
+        true
+      end
+
+      # Check if a payload exists.
+      #
+      # @param key [String] The key to check
+      # @return [Boolean] true if the payload exists
+      def exists?(key)
+        @model.exists?(key: key)
+      end
+    end
+  end
+end