patient_http 1.6.1 → 1.7.0

data/lib/patient_http/payload.rb

@@ -1,25 +1,27 @@
 # frozen_string_literal: true
 
 module PatientHttp
-  # Handles encoding and decoding of HTTP response bodies for storage.
+  # Encodes request and response bodies so they can be serialized to JSON.
   #
-  # This class provides compression and encoding strategies for different content types
-  # to optimize storage and transmission of response data.
+  # Large text bodies are compressed with gzip, and binary bodies are encoded
+  # with Base64.
+  #
+  # @api private
   class Payload
-    # @return [Symbol] the encoding type
+    # @return [Symbol] The encoding type.
     attr_reader :encoding
 
-    # @return [String] the encoded data
+    # @return [String] The encoded data.
     attr_reader :encoded_value
 
-    # @return [String, nil] the character set (if applicable)
+    # @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
+      # @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?
 
@@ -33,9 +35,9 @@ module PatientHttp
       # claims is text but that does not hold text is encoded as binary as
       # well, because the serialized form must survive JSON 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
+      # @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?
 
@@ -49,10 +51,10 @@ module PatientHttp
 
       # 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
+      # @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?
 
@@ -70,10 +72,10 @@ module PatientHttp
 
       private
 
-      # Encode a text value, compressing it when that makes it smaller.
+      # Encodes a text value, compressing it when that makes it smaller.
       #
-      # @param value [String] the text to encode
-      # @return [Array(Symbol, String, String)] [encoding, encoded_value, charset]
+      # @param value [String] The text to encode.
+      # @return [Array(Symbol, String, String)] [encoding, encoded_value, charset].
       def encode_text(value)
         return [:text, value, value.encoding.name] if value.bytesize < 4096
 
@@ -85,13 +87,13 @@ module PatientHttp
         end
       end
 
-      # Whether a value can be serialized as text. JSON encoding converts a
+      # Returns whether a value can be serialized as text. JSON encoding converts a
       # string to UTF-8, so the value must either be valid text in its own
       # encoding or hold bytes that are already valid UTF-8. A body still
       # carrying a content encoding the reader could not decode holds neither,
       # even though its MIME type names a text type.
       #
-      # @param value [String] the value to check
+      # @param value [String] The value to check.
       # @return [Boolean]
       def text?(value)
         return value.valid_encoding? unless value.encoding == Encoding::BINARY
@@ -117,7 +119,7 @@ module PatientHttp
         end
       end
 
-      # Return the value as a UTF-8 encoded string if possible. If the value cannot
+      # Returns 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:
@@ -150,9 +152,9 @@ module PatientHttp
 
     # 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)
+    # @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
@@ -161,14 +163,14 @@ module PatientHttp
 
     # Returns the decoded value.
     #
-    # @return [String, nil] the decoded data
+    # @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
+    # @return [Hash] Hash with "encoding" and "value" keys.
     def as_json
       {
         "encoding" => encoding.to_s,

data/lib/patient_http/payload_store/active_record_store.rb

@@ -4,32 +4,31 @@ require_relative "base"
 
 module PatientHttp
   module PayloadStore
-    # ActiveRecord-based payload store for production deployments.
+    # A payload store that keeps payloads as JSON in a database table. Use it in
+    # production when you want payloads in your database.
     #
-    # Stores payloads as JSON in a database table. This store is recommended
-    # when you need database-backed storage with transactional guarantees.
+    # Active Record is responsible for connection pooling and thread safety.
+    # The store requires the `patient_http_payloads` table.
     #
-    # Thread-safe: ActiveRecord handles connection pooling and thread safety.
-    #
-    # @example Configuration
-    #   require "patient_http/payload_store/active_record_store"
+    # @example Register an Active Record store
     #   config.register_payload_store(:database, adapter: :active_record)
     #
-    # @example With custom model
+    # @example Register a store with a 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.
+      # The default Active Record model for stored payloads.
       #
-      # Defined in this file to avoid loading ActiveRecord until explicitly required.
-      # The table must be created using the migration provided by this gem.
+      # The model is defined in this file, so Active Record loads only when
+      # the store is used. Create the table with the migration from this gem.
       #
-      # @example Install migrations in a Rails app
-      #   rails patient_http:install:migrations
-      #   rails db:migrate
+      # @example Install the migration in a Rails app
+      #   # Add require "patient_http/rails/engine" to an initializer.
+      #   bin/rails patient_http:install:migrations
+      #   bin/rails db:migrate
       class Payload < ::ActiveRecord::Base
         self.table_name = "patient_http_payloads"
         self.primary_key = "key"
@@ -37,23 +36,23 @@ module PatientHttp
         scope :older_than, ->(time) { where(created_at: nil...time) }
       end
 
-      # @return [Class] The ActiveRecord model class used for storage
+      # @return [Class] The Active Record model for stored payloads.
       attr_reader :model
 
-      # Initialize a new ActiveRecord store.
+      # Creates an Active Record 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
+      # @param model [Class, nil] The Active Record model. If `nil`, {Payload}
+      #   applies. A custom model must have a `key` string primary key, a `data`
+      #   text column, and timestamps.
       def initialize(model: nil)
         @model = model || Payload
       end
 
-      # Store pre-serialized JSON string directly in the database.
+      # Stores a JSON string in the database.
       #
-      # @param key [String] Unique key (used as primary key)
-      # @param json [String] Pre-serialized JSON string
-      # @return [String] The key
+      # @param key [String] The unique key. The primary key is this key.
+      # @param json [String] The serialized JSON.
+      # @return [String] The key.
       def store_json(key, json)
         now = Time.current
 
@@ -68,10 +67,10 @@ module PatientHttp
         key
       end
 
-      # Fetch data from the database.
+      # Fetches stored data.
       #
-      # @param key [String] The key to fetch
-      # @return [Hash, nil] The stored data or nil if not found
+      # @param key [String] The key.
+      # @return [Hash, nil] The parsed data, or `nil` if the key isn't found.
       def fetch(key)
         record = @model.find_by(key: key)
         return nil unless record
@@ -79,21 +78,19 @@ module PatientHttp
         JSON.parse(record.data)
       end
 
-      # Delete a payload from the database.
-      #
-      # Idempotent - does not raise if record doesn't exist.
+      # Deletes stored data. Doesn't raise an error if the key doesn't exist.
       #
-      # @param key [String] The key to delete
-      # @return [Boolean] true
+      # @param key [String] The key.
+      # @return [Boolean] `true`.
       def delete(key)
         @model.where(key: key).delete_all
         true
       end
 
-      # Check if a payload exists.
+      # Returns whether a payload exists.
       #
-      # @param key [String] The key to check
-      # @return [Boolean] true if the payload exists
+      # @param key [String] The key.
+      # @return [Boolean] `true` if the payload exists.
       def exists?(key)
         @model.exists?(key: key)
       end

data/lib/patient_http/payload_store/base.rb

@@ -4,15 +4,15 @@ require "securerandom"
 
 module PatientHttp
   module PayloadStore
-    # Abstract base class for payload stores.
+    # The abstract base class for payload stores.
     #
-    # Payload stores provide external storage for Request and Response objects
-    # that exceed the configured size threshold. This keeps job arguments
-    # small while allowing large payloads to be processed.
+    # A payload store holds serialized payloads that are larger than
+    # `payload_store_threshold`, so that job arguments stay small.
     #
-    # Subclasses must implement the abstract methods: store, fetch, and delete.
+    # Subclasses must implement {#store_json}, {#fetch}, and {#delete}, and be
+    # thread-safe.
     #
-    # @example Creating a custom store
+    # @example Create a custom store
     #   class MyStore < PatientHttp::PayloadStore::Base
     #     register :my_store, self
     #
@@ -21,8 +21,8 @@ module PatientHttp
     #       @mutex = Mutex.new
     #     end
     #
-    #     def store(key, data)
-    #       @mutex.synchronize { @connection.set(key, JSON.generate(data)) }
+    #     def store_json(key, json)
+    #       @mutex.synchronize { @connection.set(key, json) }
     #       key
     #     end
     #
@@ -41,10 +41,10 @@ module PatientHttp
     #   end
     class Base
       class << self
-        # Register a payload store adapter.
+        # Registers a payload store adapter.
         #
-        # @param name [Symbol] Unique identifier for this adapter
-        # @param klass [Class] The adapter class
+        # @param name [Symbol] The unique adapter name.
+        # @param klass [Class] The adapter class.
         # @return [void]
         def register(name, klass)
           registry_mutex.synchronize do
@@ -52,22 +52,22 @@ module PatientHttp
           end
         end
 
-        # Look up a registered adapter by name.
+        # Returns a registered adapter class.
         #
-        # @param name [Symbol, String] The adapter name
-        # @return [Class, nil] The adapter class or nil if not found
+        # @param name [Symbol, String] The adapter name.
+        # @return [Class, nil] The adapter class, or `nil` if it isn't registered.
         def lookup(name)
           registry_mutex.synchronize do
             registry[name.to_sym]
           end
         end
 
-        # Create a new store instance from a registered adapter.
+        # Creates a store from a registered adapter.
         #
-        # @param name [Symbol, String] The adapter name
-        # @param options [Hash] Options to pass to the adapter constructor
-        # @return [Base] A new store instance
-        # @raise [ArgumentError] If the adapter is not registered
+        # @param name [Symbol, String] The adapter name.
+        # @param options [Hash] The options for the adapter constructor.
+        # @return [Base] The store.
+        # @raise [ArgumentError] If the adapter isn't registered.
         def create(name, **options)
           klass = lookup(name)
           raise ArgumentError, "Unknown payload store adapter: #{name.inspect}" unless klass
@@ -75,9 +75,9 @@ module PatientHttp
           klass.new(**options)
         end
 
-        # List all registered adapter names.
+        # Returns the names of all registered adapters.
         #
-        # @return [Array<Symbol>] Registered adapter names
+        # @return [Array<Symbol>] The adapter names.
         def registered_adapters
           registry_mutex.synchronize do
             registry.keys
@@ -95,53 +95,49 @@ module PatientHttp
         end
       end
 
-      # Store data with the given key.
+      # Stores a hash as JSON. This method calls {#store_json}.
       #
-      # @param key [String] Unique key for this data
-      # @param data [Hash] The data to store (will be serialized as JSON)
-      # @return [String] The key
+      # @param key [String] The unique key.
+      # @param data [Hash] The data to store.
+      # @return [String] The key.
       def store(key, data)
         json = JSON.generate(data)
         store_json(key, json)
       end
 
-      # Store pre-serialized JSON data with the given key.
+      # Stores a JSON string. {ExternalStorage} calls this method, so
+      # subclasses must implement it.
       #
-      # Subclasses that serialize in #store should override this to write
-      # the string directly, avoiding double serialization.
-      #
-      # @param key [String] Unique key for this data
-      # @param json [String] Pre-serialized JSON string
-      # @return [String] The key
-      # @raise [NotImplementedError] Subclasses must implement this method
+      # @param key [String] The unique key.
+      # @param json [String] The serialized JSON.
+      # @return [String] The key.
+      # @raise [NotImplementedError] If the subclass doesn't implement it.
       def store_json(key, json)
         raise NotImplementedError, "#{self.class.name} must implement #store_json"
       end
 
-      # Fetch data by key.
+      # Fetches stored data.
       #
-      # @param key [String] The key to fetch
-      # @return [Hash, nil] The stored data or nil if not found
-      # @raise [NotImplementedError] Subclasses must implement this method
+      # @param key [String] The key.
+      # @return [Hash, nil] The parsed data, or `nil` if the key isn't found.
+      # @raise [NotImplementedError] If the subclass doesn't implement it.
       def fetch(key)
         raise NotImplementedError, "#{self.class.name} must implement #fetch"
       end
 
-      # Delete data by key.
-      #
-      # This method should be idempotent - deleting a non-existent key
-      # should not raise an error.
+      # Deletes stored data. The method must be idempotent: deleting a key that
+      # doesn't exist must not raise an error.
       #
-      # @param key [String] The key to delete
-      # @return [Boolean] true
-      # @raise [NotImplementedError] Subclasses must implement this method
+      # @param key [String] The key.
+      # @return [Boolean] `true`.
+      # @raise [NotImplementedError] If the subclass doesn't implement it.
       def delete(key)
         raise NotImplementedError, "#{self.class.name} must implement #delete"
       end
 
-      # Generate a unique key for storing data.
+      # Generates a unique key.
       #
-      # @return [String] A UUID key
+      # @return [String] A UUID.
       def generate_key
         SecureRandom.uuid
       end

data/lib/patient_http/payload_store/file_store.rb

@@ -4,37 +4,35 @@ require "fileutils"
 
 module PatientHttp
   module PayloadStore
-    # File-based payload store for testing and development.
+    # A payload store that keeps payloads as JSON files in a directory. Use it
+    # only for development and tests, because hosts don't share the files. In
+    # production, use another store.
     #
-    # Stores payloads as JSON files in a directory. This store is intended
-    # for local development and testing only - use Redis or S3 stores for
-    # production deployments.
+    # The store is thread-safe.
     #
-    # Thread-safe through mutex synchronization.
-    #
-    # @example Configuration
+    # @example Register a file store
     #   config.register_payload_store(:files, adapter: :file, directory: "/tmp/payloads")
     class FileStore < Base
       Base.register :file, self
 
-      # @return [String] The directory where payload files are stored
+      # @return [String] The directory for the payload files.
       attr_reader :directory
 
-      # Initialize a new file store.
+      # Creates a file store.
       #
-      # @param directory [String] Directory for storing payload files.
-      #   Defaults to Dir.tmpdir. Will be created if it doesn't exist.
+      # @param directory [String] The directory for the payload files. The
+      #   default is `Dir.tmpdir`. The directory is created if it doesn't exist.
       def initialize(directory: nil)
         @directory = directory || Dir.tmpdir
         @mutex = Mutex.new
         FileUtils.mkdir_p(@directory)
       end
 
-      # Store pre-serialized JSON string directly to a file.
+      # Writes a JSON string to a file.
       #
-      # @param key [String] Unique key (used as filename)
-      # @param json [String] Pre-serialized JSON string
-      # @return [String] The key
+      # @param key [String] The unique key. The file name is the key.
+      # @param json [String] The serialized JSON.
+      # @return [String] The key.
       def store_json(key, json)
         path = file_path(key)
         @mutex.synchronize do
@@ -43,10 +41,10 @@ module PatientHttp
         key
       end
 
-      # Fetch data from a JSON file.
+      # Fetches stored data.
       #
-      # @param key [String] The key to fetch
-      # @return [Hash, nil] The stored data or nil if not found
+      # @param key [String] The key.
+      # @return [Hash, nil] The parsed data, or `nil` if the key isn't found.
       def fetch(key)
         path = file_path(key)
         @mutex.synchronize do
@@ -56,12 +54,10 @@ module PatientHttp
         end
       end
 
-      # Delete a payload file.
-      #
-      # Idempotent - does not raise if file doesn't exist.
+      # Deletes stored data. Doesn't raise an error if the key doesn't exist.
       #
-      # @param key [String] The key to delete
-      # @return [Boolean] true
+      # @param key [String] The key.
+      # @return [Boolean] `true`.
       def delete(key)
         path = file_path(key)
         @mutex.synchronize do
@@ -72,10 +68,10 @@ module PatientHttp
         true
       end
 
-      # Check if a payload exists.
+      # Returns whether a payload exists.
       #
-      # @param key [String] The key to check
-      # @return [Boolean] true if the payload exists
+      # @param key [String] The key.
+      # @return [Boolean] `true` if the payload exists.
       def exists?(key)
         @mutex.synchronize do
           File.exist?(file_path(key))

data/lib/patient_http/payload_store/redis_store.rb

@@ -2,37 +2,32 @@
 
 module PatientHttp
   module PayloadStore
-    # Redis-based payload store for production deployments.
+    # A payload store that keeps payloads as JSON strings in Redis. Use it in
+    # production when several processes share payloads.
     #
-    # Stores payloads as JSON strings in Redis. This store is recommended
-    # for production environments where multiple processes need to share
-    # payload data.
+    # The client must respond to `set`, `get`, `del`, and `exists`, like a client
+    # from the `redis` gem. The client is responsible for thread safety.
     #
-    # Thread-safe: Redis clients handle their own thread safety.
-    #
-    # The client must respond to `set`, `get`, `del`, and `exists` (the
-    # interface provided by the `redis` gem).
-    #
-    # @example Configuration with direct Redis client
+    # @example Register a Redis store
     #   redis = Redis.new(url: ENV["REDIS_URL"])
     #   config.register_payload_store(:redis, adapter: :redis, redis: redis, ttl: 86400)
     class RedisStore < Base
       Base.register :redis, self
 
-      # @return [String] The key prefix used for all stored payloads
+      # @return [String] The prefix for the keys of all stored payloads.
       attr_reader :key_prefix
 
-      # @return [Float, nil] TTL in seconds for stored payloads
+      # @return [Float, nil] The time to live in seconds for stored payloads.
       attr_reader :ttl
 
-      # Initialize a new Redis store.
+      # Creates a Redis store.
       #
-      # @param redis [Object] Redis client instance. Required.
-      # @param ttl [Float, nil] Time-to-live in seconds for stored payloads.
-      #   Supports fractional seconds (e.g., 0.5 for 500ms). If nil, payloads do not expire.
-      # @param key_prefix [String] Prefix for all Redis keys.
-      #   Defaults to "patient_http:payloads:"
-      # @raise [ArgumentError] If redis client is not provided
+      # @param redis [Object] The Redis client.
+      # @param ttl [Float, nil] The time to live in seconds for stored payloads.
+      #   Fractions are allowed, for example `0.5` for 500 milliseconds. If `nil`,
+      #   payloads don't expire.
+      # @param key_prefix [String] The prefix for all Redis keys.
+      # @raise [ArgumentError] If the Redis client is missing.
       def initialize(redis:, ttl: nil, key_prefix: nil)
         raise ArgumentError, "redis client is required" unless redis
 
@@ -41,11 +36,12 @@ module PatientHttp
         @key_prefix = key_prefix || "patient_http:payloads:"
       end
 
-      # Store pre-serialized JSON string directly in Redis.
+      # Stores a JSON string in Redis.
       #
-      # @param key [String] Unique key (appended to key_prefix)
-      # @param json [String] Pre-serialized JSON string
-      # @return [String] The key
+      # @param key [String] The unique key. The Redis key is the key prefix and
+      #   this key.
+      # @param json [String] The serialized JSON.
+      # @return [String] The key.
       def store_json(key, json)
         full_key = key_with_prefix(key)
 
@@ -58,10 +54,10 @@ module PatientHttp
         key
       end
 
-      # Fetch data from Redis.
+      # Fetches stored data.
       #
-      # @param key [String] The key to fetch
-      # @return [Hash, nil] The stored data or nil if not found
+      # @param key [String] The key.
+      # @return [Hash, nil] The parsed data, or `nil` if the key isn't found.
       def fetch(key)
         full_key = key_with_prefix(key)
         json = @redis.get(full_key)
@@ -70,22 +66,20 @@ module PatientHttp
         JSON.parse(json)
       end
 
-      # Delete a payload from Redis.
-      #
-      # Idempotent - does not raise if key doesn't exist.
+      # Deletes stored data. Doesn't raise an error if the key doesn't exist.
       #
-      # @param key [String] The key to delete
-      # @return [Boolean] true
+      # @param key [String] The key.
+      # @return [Boolean] `true`.
       def delete(key)
         full_key = key_with_prefix(key)
         @redis.del(full_key)
         true
       end
 
-      # Check if a payload exists.
+      # Returns whether a payload exists.
       #
-      # @param key [String] The key to check
-      # @return [Boolean] true if the payload exists
+      # @param key [String] The key.
+      # @return [Boolean] `true` if the payload exists.
       def exists?(key)
         full_key = key_with_prefix(key)
         @redis.exists(full_key) > 0