patient_http 1.0.0

data/lib/patient_http/payload_store/base.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module PatientHttp
+  module PayloadStore
+    # 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.
+    #
+    # Subclasses must implement the abstract methods: store, fetch, and delete.
+    #
+    # @example Creating a custom store
+    #   class MyStore < PatientHttp::PayloadStore::Base
+    #     register :my_store, self
+    #
+    #     def initialize(connection:)
+    #       @connection = connection
+    #       @mutex = Mutex.new
+    #     end
+    #
+    #     def store(key, data)
+    #       @mutex.synchronize { @connection.set(key, JSON.generate(data)) }
+    #       key
+    #     end
+    #
+    #     def fetch(key)
+    #       @mutex.synchronize { JSON.parse(@connection.get(key)) }
+    #     rescue KeyNotFoundError
+    #       nil
+    #     end
+    #
+    #     def delete(key)
+    #       @mutex.synchronize { @connection.delete(key) }
+    #       true
+    #     rescue KeyNotFoundError
+    #       true
+    #     end
+    #   end
+    class Base
+      class << self
+        # Register a payload store adapter.
+        #
+        # @param name [Symbol] Unique identifier for this adapter
+        # @param klass [Class] The adapter class
+        # @return [void]
+        def register(name, klass)
+          registry_mutex.synchronize do
+            registry[name.to_sym] = klass
+          end
+        end
+
+        # Look up a registered adapter by name.
+        #
+        # @param name [Symbol, String] The adapter name
+        # @return [Class, nil] The adapter class or nil if not found
+        def lookup(name)
+          registry_mutex.synchronize do
+            registry[name.to_sym]
+          end
+        end
+
+        # Create a new store instance 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
+        def create(name, **options)
+          klass = lookup(name)
+          raise ArgumentError, "Unknown payload store adapter: #{name.inspect}" unless klass
+
+          klass.new(**options)
+        end
+
+        # List all registered adapter names.
+        #
+        # @return [Array<Symbol>] Registered adapter names
+        def registered_adapters
+          registry_mutex.synchronize do
+            registry.keys
+          end
+        end
+
+        private
+
+        def registry
+          @registry ||= {}
+        end
+
+        def registry_mutex
+          @registry_mutex ||= Mutex.new
+        end
+      end
+
+      # Store data with the given key.
+      #
+      # @param key [String] Unique key for this data
+      # @param data [Hash] The data to store (will be serialized as JSON)
+      # @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.
+      #
+      # 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
+      def store_json(key, json)
+        raise NotImplementedError, "#{self.class.name} must implement #store_json"
+      end
+
+      # Fetch data by key.
+      #
+      # @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
+      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.
+      #
+      # @param key [String] The key to delete
+      # @return [Boolean] true
+      # @raise [NotImplementedError] Subclasses must implement this method
+      def delete(key)
+        raise NotImplementedError, "#{self.class.name} must implement #delete"
+      end
+
+      # Generate a unique key for storing data.
+      #
+      # @return [String] A UUID key
+      def generate_key
+        SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/patient_http/payload_store/file_store.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module PatientHttp
+  module PayloadStore
+    # File-based payload store for testing and development.
+    #
+    # 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.
+    #
+    # Thread-safe through mutex synchronization.
+    #
+    # @example Configuration
+    #   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
+      attr_reader :directory
+
+      # Initialize a new file store.
+      #
+      # @param directory [String] Directory for storing payload files.
+      #   Defaults to Dir.tmpdir. Will be 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.
+      #
+      # @param key [String] Unique key (used as filename)
+      # @param json [String] Pre-serialized JSON string
+      # @return [String] The key
+      def store_json(key, json)
+        path = file_path(key)
+        @mutex.synchronize do
+          File.write(path, json)
+        end
+        key
+      end
+
+      # Fetch data from a JSON file.
+      #
+      # @param key [String] The key to fetch
+      # @return [Hash, nil] The stored data or nil if not found
+      def fetch(key)
+        path = file_path(key)
+        @mutex.synchronize do
+          return nil unless File.exist?(path)
+
+          JSON.parse(File.read(path))
+        end
+      end
+
+      # Delete a payload file.
+      #
+      # Idempotent - does not raise if file doesn't exist.
+      #
+      # @param key [String] The key to delete
+      # @return [Boolean] true
+      def delete(key)
+        path = file_path(key)
+        @mutex.synchronize do
+          File.delete(path) if File.exist?(path)
+        end
+        true
+      rescue Errno::ENOENT
+        true
+      end
+
+      # Check if a payload exists.
+      #
+      # @param key [String] The key to check
+      # @return [Boolean] true if the payload exists
+      def exists?(key)
+        @mutex.synchronize do
+          File.exist?(file_path(key))
+        end
+      end
+
+      private
+
+      def file_path(key)
+        File.join(@directory, "#{key}.json")
+      end
+    end
+  end
+end

data/lib/patient_http/payload_store/redis_store.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  module PayloadStore
+    # Redis-based payload store for production deployments.
+    #
+    # Stores payloads as JSON strings in Redis. This store is recommended
+    # for production environments where multiple processes need to share
+    # payload data.
+    #
+    # Thread-safe: Redis clients handle their own thread safety.
+    #
+    # @example Configuration with direct Redis client
+    #   redis = RedisClient.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
+      attr_reader :key_prefix
+
+      # @return [Float, nil] TTL in seconds for stored payloads
+      attr_reader :ttl
+
+      # Initialize a new 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
+      def initialize(redis:, ttl: nil, key_prefix: nil)
+        raise ArgumentError, "redis client is required" unless redis
+
+        @redis = redis
+        @ttl = ttl
+        @key_prefix = key_prefix || "patient_http:payloads:"
+      end
+
+      # Store pre-serialized JSON string directly in Redis.
+      #
+      # @param key [String] Unique key (appended to key_prefix)
+      # @param json [String] Pre-serialized JSON string
+      # @return [String] The key
+      def store_json(key, json)
+        full_key = key_with_prefix(key)
+
+        if @ttl
+          ttl_ms = (@ttl * 1000).round
+          @redis.set(full_key, json, px: ttl_ms)
+        else
+          @redis.set(full_key, json)
+        end
+        key
+      end
+
+      # Fetch data from Redis.
+      #
+      # @param key [String] The key to fetch
+      # @return [Hash, nil] The stored data or nil if not found
+      def fetch(key)
+        full_key = key_with_prefix(key)
+        json = @redis.get(full_key)
+        return nil if json.nil?
+
+        JSON.parse(json)
+      end
+
+      # Delete a payload from Redis.
+      #
+      # Idempotent - does not raise if key doesn't exist.
+      #
+      # @param key [String] The key to delete
+      # @return [Boolean] true
+      def delete(key)
+        full_key = key_with_prefix(key)
+        @redis.del(full_key)
+        true
+      end
+
+      # Check if a payload exists.
+      #
+      # @param key [String] The key to check
+      # @return [Boolean] true if the payload exists
+      def exists?(key)
+        full_key = key_with_prefix(key)
+        @redis.exists(full_key) > 0
+      end
+
+      private
+
+      def key_with_prefix(key)
+        "#{@key_prefix}#{key}"
+      end
+    end
+  end
+end

data/lib/patient_http/payload_store/s3_store.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+begin
+  require "aws-sdk-s3"
+rescue LoadError
+  raise LoadError, "The aws-sdk-s3 gem is required to use S3Store. Add it to your Gemfile: gem 'aws-sdk-s3'"
+end
+
+module PatientHttp
+  module PayloadStore
+    # S3-based payload store for production deployments.
+    #
+    # Stores payloads as JSON objects in S3. This store is recommended
+    # for production environments where payloads need durable storage
+    # and can be shared across multiple processes/instances.
+    #
+    # Thread-safe: S3 clients handle their own thread safety.
+    #
+    # @example Configuration with S3 bucket
+    #   s3 = Aws::S3::Resource.new
+    #   bucket = s3.bucket("my-payloads-bucket")
+    #   config.register_payload_store(:s3, adapter: :s3, bucket: bucket)
+    class S3Store < Base
+      Base.register :s3, self
+
+      # @return [String] The key prefix used for all stored payloads
+      attr_reader :key_prefix
+
+      # Initialize a new S3 store.
+      #
+      # @param bucket [Aws::S3::Bucket] S3 Bucket object. Required.
+      # @param key_prefix [String] Prefix for all S3 object keys.
+      #   Defaults to "patient_http/payloads/"
+      # @raise [ArgumentError] If bucket is not provided
+      def initialize(bucket:, key_prefix: nil)
+        raise ArgumentError, "S3 bucket is required" unless bucket
+
+        @bucket = bucket
+        @key_prefix = key_prefix || "patient_http/payloads/"
+      end
+
+      # Store pre-serialized JSON string directly in S3.
+      #
+      # @param key [String] Unique key (appended to key_prefix)
+      # @param json [String] Pre-serialized JSON string
+      # @return [String] The key
+      def store_json(key, json)
+        full_key = key_with_prefix(key)
+        @bucket.object(full_key).put(body: json, content_type: "application/json")
+        key
+      end
+
+      # Fetch data from S3.
+      #
+      # @param key [String] The key to fetch
+      # @return [Hash, nil] The stored data or nil if not found
+      def fetch(key)
+        full_key = key_with_prefix(key)
+        response = @bucket.object(full_key).get
+
+        JSON.parse(response.body.read)
+      rescue Aws::S3::Errors::NoSuchKey
+        nil
+      end
+
+      # Delete a payload from S3.
+      #
+      # Idempotent - does not raise if object doesn't exist.
+      #
+      # @param key [String] The key to delete
+      # @return [Boolean] true
+      def delete(key)
+        full_key = key_with_prefix(key)
+        @bucket.object(full_key).delete
+        true
+      end
+
+      # Check if a payload exists.
+      #
+      # @param key [String] The key to check
+      # @return [Boolean] true if the payload exists
+      def exists?(key)
+        full_key = key_with_prefix(key)
+        @bucket.object(full_key).exists?
+      end
+
+      private
+
+      def key_with_prefix(key)
+        "#{@key_prefix}#{key}"
+      end
+    end
+  end
+end

data/lib/patient_http/payload_store.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  module PayloadStore
+    autoload :Base, File.join(__dir__, "payload_store/base")
+    autoload :ActiveRecordStore, File.join(__dir__, "payload_store/active_record_store")
+    autoload :FileStore, File.join(__dir__, "payload_store/file_store")
+    autoload :RedisStore, File.join(__dir__, "payload_store/redis_store")
+    autoload :S3Store, File.join(__dir__, "payload_store/s3_store")
+  end
+end