patient_http 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5cda06fbc0db9bc2beb2264a718afb1dedc8c2b27fee4f8e8bd9c417086a6b2
-  data.tar.gz: edaa46086b479884d618fc144aeb5bd231196424df7061c71fa242c61de4a564
+  metadata.gz: bf333a4e860c7ec2acbabd0b2d99b050a2574fd3fe97e7d9cb10b5ba08868fed
+  data.tar.gz: ea8fdac974792444d4f82ded653beeb644d39a58a88b2c1d7796029266dd0e39
 SHA512:
-  metadata.gz: 617a2dbbdb9df31eb19f9b48d852cfb15f1c43ed26e4d552f0674fcced748c88b90cbbc7d47e7b8e2a0b7b88b8b4285c3cbca5dd09fec6fbee91e6e7b050378c
-  data.tar.gz: e8ea8de4be59c91cb686b1e4249d57a5c4dc50bc1ccf94e6c0dfd8a091d9b3ceb94544eb580924578d845b074d7a478fddce8a1e694706a814e62bd3d03fd604
+  metadata.gz: 1ca730c46c12d7be338959fbb45b4c0863e7b81fc2c09ec43aa5e27f073cf4e6023df63441ffc7fa4b244e7fe560a26041872fc4013ed8dfaf8dfdd5b9390fb4
+  data.tar.gz: 4073af1b84aac90f73e41efaded611eff0c46d2521221eedcdbb3dd640269d4fcf2865cb881e88134897825adc0899b022cf9ca041d0ec3a4818c93fade351f3

data/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.1.0
+
+### Added
+
+- Secret manager for referencing sensitive headers and query parameters indirectly. Register secrets on the `Configuration` with `register_secret` (static value or lazy block), then reference them when building a request via `PatientHttp.secret(name)`. The serialized request stores only a `{"$secret" => name}` reference; the value is resolved by the processor when the request is sent, keeping sensitive values out of the job queue and logs.
+
 ## 1.0.0
 
 ### Added

data/README.md

@@ -485,6 +485,39 @@ end
 
 Encrypted data is stored as `{"__encrypted__" => true, "value" => "<base64>"}`. The `Encryptor` JSON-serializes the original hash, passes the bytes to your callable, and Base64-encodes the result. Decryption reverses the process. Hashes without the `"__encrypted__"` key are passed through unchanged, so un-encrypted historical data continues to work while you roll out encryption.
 
+## Secrets
+
+Requests are serialized into your job queue before they run. If you put a sensitive value — an API token in an `Authorization` header, or an API key in a query parameter — directly on the request, that value is written into the queue. Requests can be encrypted in the queue, but a better practice is to avoid putting sensitive values on the request at all.
+
+The secret manager lets you reference a sensitive values in headers or query parameters by name instead. The serialized request stores only a reference marker (`{"$secret" => "name"}`), never the value. The actual value lives on the `Configuration` (which exists on the processor side) and is resolved at the moment the request is sent.
+
+### Defining secrets
+
+Register named secrets on the `Configuration`. A value can be given directly, or as a block that is evaluated lazily each time the secret is resolved (useful for reading from the environment on demand):
+
+```ruby
+config = PatientHttp::Configuration.new
+config.register_secret(:authorization, "Bearer #{ENV['API_TOKEN']}") # static value
+config.register_secret(:api_key) { ENV["MY_API_KEY"] } # lazy block
+```
+
+I a secret is not found when resolving a request, a `PatientHttp::SecretManager::SecretNotFoundError` is raised, which surfaces through the normal request error path.
+
+### Referencing secrets when building a request
+
+Use `PatientHttp.secret(name)` anywhere you would put a sensitive header or query parameter value. No value is needed (or available) at build time:
+
+```ruby
+PatientHttp.get(
+  "https://api.example.com/data",
+  callback: MyCallback,
+  headers: {"Authorization" => PatientHttp.secret(:api_token)},
+  params: {"api_key" => PatientHttp.secret(:api_key), "page" => 2}
+)
+```
+
+The request serializes the secret header as `{"$secret" => "api_token"}` and keeps the secret query parameter out of the URL (non-secret params like `page` are still folded into the URL as usual). The processor dereferences both just before sending: the header is set to its resolved value and the resolved query parameter is appended to the URL.
+
 ## Configuration
 
 ```ruby
@@ -525,6 +558,9 @@ config = PatientHttp::Configuration.new(
   # Logger instance (default: Logger to STDERR at ERROR level)
   logger: Logger.new($stdout)
 )
+
+# Register named secrets to reference sensitive headers/params indirectly (see Secrets)
+config.register_secret(:api_token, ENV["MY_API_TOKEN"])
 ```
 
 ### Tuning Tips

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/lib/patient_http/client.rb

@@ -23,11 +23,12 @@ module PatientHttp
 
       begin
         headers = request_headers(request, request_id)
+        url = config.secret_manager.resolve_url(request.url, request.secret_params)
         body = Protocol::HTTP::Body::Buffered.wrap([request.body.to_s]) if request.body
         timeout = request.timeout || config.request_timeout
 
         Async::Task.current.with_timeout(timeout) do
-          async_response = @client_pool.request(request.http_method, request.url, headers, body)
+          async_response = @client_pool.request(request.http_method, url, headers, body)
           headers_hash = async_response.headers.to_h.transform_values(&:to_s)
           body = @response_reader.read_body(async_response, headers_hash)
 
@@ -72,7 +73,8 @@ module PatientHttp
     end
 
     def request_headers(request, request_id)
-      headers = request.headers.to_h.merge("x-request-id" => request_id)
+      headers = config.secret_manager.resolve_headers(request.headers.to_h)
+      headers["x-request-id"] = request_id
       headers["user-agent"] ||= config.user_agent if config.user_agent
       headers
     end

data/lib/patient_http/configuration.rb

@@ -46,6 +46,9 @@ module PatientHttp
     # @return [Integer] Number of retries for failed requests
     attr_reader :retries
 
+    # @return [SecretManager] the secret manager instance
+    attr_reader :secret_manager
+
     # Initializes a new Configuration with the specified options.
     #
     # @param max_connections [Integer] Maximum number of concurrent connections
@@ -75,10 +78,15 @@ module PatientHttp
       retries: 3,
       encryption_key: nil
     )
+      @mutex = Mutex.new
+
       # Initialize payload store configuration
       @payload_stores = {}
       @default_payload_store_name = nil
-      @payload_store_mutex = Mutex.new
+
+      # Initialize secret configuration
+      @secrets = {}
+      @secret_manager = SecretManager.new
 
       @encryptor = nil
 
@@ -215,6 +223,33 @@ module PatientHttp
       @encryptor ||= Encryptor.new(encryption: @encryption, decryption: @decryption)
     end
 
+    # Register a named secret whose value can be referenced indirectly when building
+    # requests via {PatientHttp.secret}.
+    #
+    # The value can be provided directly or as a block (callable). A block is invoked
+    # lazily with the secret name each time the secret is resolved, which is useful for
+    # values that should be read on demand (for example, from the environment).
+    #
+    # @param name [String, Symbol] the secret name
+    # @param value [Object, nil] the secret value (omit when providing a block)
+    # @yield [name] a block that returns the secret value (omit when providing a value)
+    # @raise [ArgumentError] if neither or both of value and block are provided
+    # @return [void]
+    def register_secret(name, value = nil, &block)
+      if value.nil? && block.nil?
+        raise ArgumentError.new("register_secret requires a value or a block")
+      end
+
+      if !value.nil? && block
+        raise ArgumentError.new("register_secret accepts either a value or a block, not both")
+      end
+
+      @mutex.synchronize do
+        @secrets[name.to_s] = block || value
+        @secret_manager = SecretManager.new(secrets: @secrets.dup)
+      end
+    end
+
     # Register a payload store for external storage of large payloads.
     #
     # The name is included in the serialized references to the stored data.
@@ -243,8 +278,8 @@ module PatientHttp
 
       store = PayloadStore::Base.create(adapter, **options)
 
-      @payload_store_mutex.synchronize do
-        @payload_stores[name] = store
+      @mutex.synchronize do
+        @payload_stores = @payload_stores.merge(name => store)
         @default_payload_store_name = name
       end
     end
@@ -254,33 +289,25 @@ module PatientHttp
     # @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
+      if name.nil?
+        return nil unless @default_payload_store_name
 
-          @payload_stores[@default_payload_store_name]
-        else
-          @payload_stores[name.to_sym]
-        end
+        @payload_stores[@default_payload_store_name]
+      else
+        @payload_stores[name.to_sym]
       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
+    attr_reader :default_payload_store_name
 
     # 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
+      @payload_stores.dup
     end
 
     # Convert to hash for inspection
@@ -300,7 +327,8 @@ module PatientHttp
         "proxy_url" => proxy_url,
         "retries" => retries,
         "payload_stores" => payload_stores.keys,
-        "default_payload_store" => default_payload_store_name
+        "default_payload_store" => default_payload_store_name,
+        "secrets" => @mutex.synchronize { @secrets.keys }
       }
     end
 

data/lib/patient_http/request.rb

@@ -34,6 +34,10 @@ module PatientHttp
     # @return [Integer, nil] Maximum number of redirects to follow (nil uses config default, 0 disables)
     attr_reader :max_redirects
 
+    # @return [Hash{String, Symbol => SecretReference}] Query parameters whose values are
+    #   secret references, kept out of the serialized URL and resolved at send time
+    attr_reader :secret_params
+
     class << self
       # Reconstruct a Request from a hash
       #
@@ -43,12 +47,31 @@ module PatientHttp
         new(
           hash["http_method"].to_sym,
           hash["url"],
-          headers: hash["headers"],
+          headers: load_headers(hash["headers"]),
           body: Payload.load(hash["body"])&.value,
+          params: load_secret_params(hash["secret_params"]),
           timeout: hash["timeout"],
           max_redirects: hash["max_redirects"]
         )
       end
+
+      private
+
+      # Convert serialized secret-reference header markers back into SecretReference
+      # objects, leaving plain header values unchanged.
+      def load_headers(headers)
+        return headers if headers.nil?
+
+        headers.transform_values { |value| SecretReference.load(value) }
+      end
+
+      # Reconstruct secret params from their serialized markers. Returned as a params
+      # hash so the constructor folds them back into the request's secret params.
+      def load_secret_params(secret_params)
+        return nil if secret_params.nil? || secret_params.empty?
+
+        secret_params.transform_values { |value| SecretReference.load(value) }
+      end
     end
 
     # Initializes a new Request.
@@ -77,6 +100,7 @@ module PatientHttp
         raise ArgumentError.new("url must be a String or URI, got: #{url.class}")
       end
 
+      @secret_params = {}
       @url = normalized_url(url, params)
       @headers = headers.is_a?(HttpHeaders) ? headers : HttpHeaders.new(headers)
       @body = (body == "") ? nil : body
@@ -109,23 +133,49 @@ module PatientHttp
     #
     # @return [Hash]
     def as_json
-      {
+      hash = {
         "http_method" => @http_method.to_s,
         "url" => @url.to_s,
-        "headers" => @headers.to_h,
+        "headers" => serialized_headers,
         "body" => @payload&.as_json,
         "timeout" => @timeout,
         "max_redirects" => @max_redirects
       }
+
+      if @secret_params.any?
+        hash["secret_params"] = @secret_params.transform_values(&:as_json)
+      end
+
+      hash
     end
 
     private
 
+    # Header values may be SecretReference objects; serialize those as markers.
+    def serialized_headers
+      @headers.to_h.transform_values do |value|
+        value.is_a?(SecretReference) ? value.as_json : value
+      end
+    end
+
     def normalized_url(url, params)
       uri = url.is_a?(URI::Generic) ? url.dup : URI(url.to_s)
       return uri.to_s unless params&.any?
 
-      serialized_params = URI.encode_www_form(params)
+      # Partition out secret params: they are kept off the serialized URL and resolved
+      # at send time by the processor. Only non-secret params are folded into the URL.
+      regular_params = {}
+      params.each do |key, value|
+        if SecretReference.reference?(value)
+          @secret_params[key] = SecretReference.load(value)
+        else
+          regular_params[key] = value
+        end
+      end
+
+      return uri.to_s if regular_params.empty?
+
+      serialized_params = URI.encode_www_form(regular_params)
       uri.query = [uri.query, serialized_params].compact.reject(&:empty?).join("&")
       uri.to_s
     end

data/lib/patient_http/secret_manager.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # Resolves {SecretReference} values into their actual secret values when a request
+  # is sent by the processor.
+  #
+  # A SecretManager is built from the secrets registered on the {Configuration}.
+  #
+  # @see Configuration#secret_manager
+  class SecretManager
+    # Raised when a referenced secret cannot be resolved.
+    class SecretNotFoundError < StandardError; end
+
+    # Initialize a new SecretManager.
+    #
+    # @param secrets [Hash{String => Object}] static registry mapping names to values
+    #   (a value may be a callable, which is invoked with the name to produce the value)
+    #   secret not found in the static registry
+    def initialize(secrets: {})
+      @secrets = secrets || {}
+    end
+
+    # Check if a secret name is registered in the static registry.
+    #
+    # @param name [String, Symbol] the secret name
+    # @return [Boolean] true if the name is registered, false otherwise
+    def include?(name)
+      @secrets.include?(name.to_s)
+    end
+
+    # Resolve a secret by name.
+    #
+    # The static registry is checked first; if the registered value responds to #call
+    # it is invoked with the name. If the name is not in the registry, an error is raised.
+    #
+    # @param name [String, Symbol] the secret name
+    # @return [String] the resolved secret value
+    # @raise [SecretNotFoundError] if the secret cannot be resolved
+    def resolve(name)
+      name = name.to_s
+
+      unless @secrets.include?(name)
+        raise SecretNotFoundError.new("No secret registered for #{name.inspect}")
+      end
+
+      value = @secrets[name]
+      value = value.call(name) if value.respond_to?(:call)
+      value&.to_s
+    end
+
+    # Resolve any secret references in a headers hash, returning a new hash.
+    #
+    # @param headers [Hash, nil] header name/value pairs
+    # @return [Hash, nil] a new hash with secret references replaced by resolved values
+    def resolve_headers(headers)
+      resolve_values(headers)
+    end
+
+    # Resolve any secret references in a params hash, returning a new hash.
+    #
+    # @param params [Hash, nil] param name/value pairs
+    # @return [Hash, nil] a new hash with secret references replaced by resolved values
+    def resolve_params(params)
+      resolve_values(params)
+    end
+
+    # Append resolved secret params to a URL's query string.
+    #
+    # @param url [String] the request URL
+    # @param secret_params [Hash, nil] secret param name/value (SecretReference) pairs
+    # @return [String] the URL with resolved secret params appended (unchanged if none)
+    def resolve_url(url, secret_params)
+      return url if secret_params.nil? || secret_params.empty?
+
+      serialized_params = URI.encode_www_form(resolve_params(secret_params))
+      uri = URI(url)
+      uri.query = [uri.query, serialized_params].compact.reject(&:empty?).join("&")
+      uri.to_s
+    end
+
+    private
+
+    # Return a new hash with any secret-reference values replaced by their resolved
+    # values. Non-secret values are passed through unchanged.
+    def resolve_values(hash)
+      return hash if hash.nil?
+
+      hash.each_with_object({}) do |(key, value), result|
+        result[key] = if SecretReference.reference?(value)
+          resolve(SecretReference.load(value).name)
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/patient_http/secret_reference.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # A reference to a named secret that can be used as a header or query parameter
+  # value when building a {Request}.
+  #
+  # A SecretReference holds only the secret's name -- never its value. When a request
+  # is serialized (for example, to be enqueued in a job system), the reference is
+  # serialized as a lightweight marker (`{"$secret" => name}`) so the sensitive value
+  # is never written to the queue or logs. The actual value is resolved on the
+  # processor side at the moment the request is sent, using the secrets registered on
+  # the {Configuration}.
+  #
+  # @example Referencing a secret when building a request
+  #   PatientHttp.get(
+  #     "https://api.example.com/data",
+  #     callback: MyCallback,
+  #     headers: {"Authorization" => PatientHttp.secret(:api_token)},
+  #     params: {"api_key" => PatientHttp.secret(:api_key)}
+  #   )
+  class SecretReference
+    # Key used in serialized JSON to indicate a secret reference.
+    REFERENCE_KEY = "$secret"
+
+    # @return [String] the name of the referenced secret
+    attr_reader :name
+
+    class << self
+      # Check if a value is a secret reference (either a SecretReference instance or a
+      # serialized marker hash).
+      #
+      # @param value [Object] the value to check
+      # @return [Boolean] true if the value is a secret reference
+      def reference?(value)
+        value.is_a?(SecretReference) ||
+          (value.is_a?(Hash) && value.key?(REFERENCE_KEY))
+      end
+
+      # Reconstruct a SecretReference from a serialized marker hash. Any other value
+      # (including an existing SecretReference) is returned unchanged.
+      #
+      # @param value [Object] a serialized marker hash or any other value
+      # @return [Object] a SecretReference for a marker hash, otherwise the original value
+      def load(value)
+        return value unless value.is_a?(Hash) && value.key?(REFERENCE_KEY)
+
+        new(value[REFERENCE_KEY])
+      end
+    end
+
+    # Initialize a new SecretReference.
+    #
+    # @param name [String, Symbol] the name of the secret to reference
+    # @raise [ArgumentError] if the name is empty
+    def initialize(name)
+      @name = name.to_s
+      raise ArgumentError.new("secret name cannot be empty") if @name.empty?
+    end
+
+    # Serialize to a marker hash. Only the name is included; the value is never present.
+    #
+    # @return [Hash] the marker hash
+    def as_json
+      {REFERENCE_KEY => name}
+    end
+
+    def ==(other)
+      other.is_a?(SecretReference) && other.name == name
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [self.class, name].hash
+    end
+
+    # Inspect the reference. Only the name is shown (there is no value to leak).
+    #
+    # @return [String]
+    def inspect
+      "#<PatientHttp::SecretReference name=#{name.inspect}>"
+    end
+  end
+end

data/lib/patient_http/synchronous_executor.rb

@@ -39,11 +39,12 @@ module PatientHttp
             timeout = @task.request.timeout || @config.request_timeout
 
             response_data = Async::Task.current.with_timeout(timeout) do
-              headers = @task.request.headers.to_h.merge("x-request-id" => @task.id)
+              headers = @config.secret_manager.resolve_headers(@task.request.headers.to_h)
+              headers["x-request-id"] = @task.id
               headers["user-agent"] ||= @config.user_agent if @config.user_agent
               body = Protocol::HTTP::Body::Buffered.wrap([@task.request.body.to_s]) if @task.request.body
 
-              endpoint = Async::HTTP::Endpoint.parse(@task.request.url)
+              endpoint = Async::HTTP::Endpoint.parse(request_url)
               endpoint = configure_endpoint(endpoint) if @config.connection_timeout
 
               verb = @task.request.http_method.to_s.upcase
@@ -124,11 +125,18 @@ module PatientHttp
 
     private
 
+    # Resolve the current task's request URL, appending any secret query params.
+    #
+    # @return [String] the resolved request URL
+    def request_url
+      @config.secret_manager.resolve_url(@task.request.url, @task.request.secret_params)
+    end
+
     # Create HTTP client with config settings (retries, proxy, connection timeout).
     #
     # @return [Protocol::HTTP::AcceptEncoding] wrapped HTTP client
     def create_http_client
-      endpoint = Async::HTTP::Endpoint.parse(@task.request.url)
+      endpoint = Async::HTTP::Endpoint.parse(request_url)
       endpoint = configure_endpoint(endpoint) if @config.connection_timeout
 
       client = if @config.proxy_url

data/lib/patient_http.rb

@@ -66,6 +66,8 @@ module PatientHttp
   autoload :RequestTemplate, File.join(__dir__, "patient_http/request_template")
   autoload :Response, File.join(__dir__, "patient_http/response")
   autoload :ResponseReader, File.join(__dir__, "patient_http/response_reader")
+  autoload :SecretManager, File.join(__dir__, "patient_http/secret_manager")
+  autoload :SecretReference, File.join(__dir__, "patient_http/secret_reference")
   autoload :ServerError, File.join(__dir__, "patient_http/http_error")
   autoload :SynchronousExecutor, File.join(__dir__, "patient_http/synchronous_executor")
   autoload :TaskHandler, File.join(__dir__, "patient_http/task_handler")
@@ -258,6 +260,19 @@ module PatientHttp
       )
     end
 
+    # Build a reference to a named secret for use as a sensitive header or query
+    # parameter value when building a request.
+    #
+    # The reference holds only the secret's name; the value is resolved on the
+    # processor side at send time using the secrets registered on the configuration.
+    #
+    # @param name [String, Symbol] the name of the secret to reference
+    # @return [SecretReference] a reference to the named secret
+    # @see Configuration#register_secret
+    def secret(name)
+      SecretReference.new(name)
+    end
+
     private
 
     # Validates that the handler accepts the required keyword arguments.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_http
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Brian Durand
@@ -129,6 +129,8 @@ files:
 - lib/patient_http/request_template.rb
 - lib/patient_http/response.rb
 - lib/patient_http/response_reader.rb
+- lib/patient_http/secret_manager.rb
+- lib/patient_http/secret_reference.rb
 - lib/patient_http/synchronous_executor.rb
 - lib/patient_http/task_handler.rb
 - lib/patient_http/time_helper.rb