patient_http 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 393cbf361701d9e1dc190b80f571d78059a21dae85f225750198a1ab173e8bb8
-  data.tar.gz: 3d5349e55335d4cd262699481517d3c44825c27449a2b3b11d9559a7b4f468b0
+  metadata.gz: ba7400987a1a1483e88f8c0e3c3fb3579544a02f5f3bdb6da7752f5864792fcb
+  data.tar.gz: cc1ab11246151f2b9843e81c730653e922a34db6f4a57600267637fbe72d7f49
 SHA512:
-  metadata.gz: '06894a234fca9e2c12aa77b69cf5347824de6f6be9e3b912dcc3e7834e2137231144e69ba58bef85fb026b200369ad976befc4e540ba9f2779a31fe3e68991a0'
-  data.tar.gz: ac60b71f532664b3083697dd1c225f4a5a787f07de04d2458d3f849c3b3962d68062740b7e0f03b981edf7aa9ab6fac98aadff98ef9549a0efe15c0b3b968de1
+  metadata.gz: e021b76930cc0c1d6c0741723d2db084947f04b8daee1564bc1b04d56d24399443dc6567fe153a99795d5c322810ab56f9cd218f1b8ddafb3a127785352f0bb7
+  data.tar.gz: 5d920b85e033e9fbfcd551ca2f7702d260da8ddbea04f105173e591c07fab7b66df2c6d6a85303463fa6faa6d2c8e6357296c317e6ccec8e7599dbbd97b1f842

data/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.3.0
+
+### Added
+
+- `PatientHttp.inline!` registers a request handler that executes requests inline (synchronously, in-process) through `SynchronousExecutor`, for consoles, tests, and development environments with no job-system integration. `PatientHttp.inline?` checks whether the inline handler is currently registered, and `PatientHttp.execute_inline` executes a single request inline without registering a handler.
+- `PatientHttp.register_secret` registers named secrets at the module level, independent of any `Configuration`. Module-level secrets are applied to the new `PatientHttp.default_configuration` (immediately if set, or when it is set later), making registration order between application code and integration gem configuration irrelevant. `PatientHttp.secret_registered?` checks whether a secret is registered at the module level or on the default configuration.
+- `PatientHttp::RequestHelper`'s `request_template` and `async_request` now accept `preprocessors:`, matching `PatientHttp.request` and `RequestTemplate`.
+- `PatientHttp.handler_registered?` checks whether a request handler is registered.
+
 ## 1.2.0
 
 ### Added

data/README.md

@@ -194,6 +194,30 @@ PatientHttp.get(
 
 If you are using the [patient_http-sidekiq](https://github.com/bdurand/patient_http-sidekiq) gem or the [patient_http-solid_queue](https://github.com/bdurand/patient_http-solid_queue) gem, the appropriate handler will automatically be registered for you.
 
+### Inline Execution
+
+For consoles, tests, and development environments where no job system is configured, you can register a handler that executes requests inline — synchronously, in-process — instead of dispatching them to a queue:
+
+```ruby
+PatientHttp.inline!
+```
+
+Now every request made through the `PatientHttp` interface (or the `RequestHelper` mixin) runs immediately through the full request lifecycle (timeouts, redirects, error wrapping) and invokes its callback on the calling thread before returning. Callbacks can make further requests; those execute inline as well.
+
+```ruby
+PatientHttp.inline!
+PatientHttp.get("https://api.example.com/users/123", callback: FetchUserCallback)
+# FetchUserCallback#on_complete has already been invoked by this point
+```
+
+Inline requests run against `PatientHttp.default_configuration` by default (or a lazily created default configuration that includes any secrets registered with `PatientHttp.register_secret` — see [Secrets](#secrets)). You can also pass an explicit configuration:
+
+```ruby
+PatientHttp.inline!(config: PatientHttp::Configuration.new(raise_error_responses: true))
+```
+
+Use `PatientHttp.inline?` to check whether the inline handler is the currently registered handler. To execute a single request inline without registering a handler, use `PatientHttp.execute_inline(request:, callback:)`.
+
 ### RequestHelper Mixin
 
 Use `PatientHttp::RequestHelper` when you want a simple API for creating and dispatching async HTTP requests directly from your class.
@@ -505,6 +529,23 @@ config.register_secret(:api_key) { ENV["MY_API_KEY"] } # lazy block
 
 If a secret is not found when resolving a request, a `PatientHttp::SecretManager::SecretNotFoundError` is raised, which surfaces through the normal request error path.
 
+#### Module-level registration
+
+If the `Configuration` is owned by an integration gem (patient_http-sidekiq, patient_http-solid_queue), your application code may not have a convenient reference to it — or may load before it exists. In that case, register secrets at the module level instead:
+
+```ruby
+PatientHttp.register_secret(:authorization, "Bearer #{ENV['API_TOKEN']}")
+PatientHttp.register_secret(:api_key) { ENV["MY_API_KEY"] }
+```
+
+Module-level secrets are applied to `PatientHttp.default_configuration` — immediately if one is already set, or as soon as one is set later — so registration order between your application code and the integration gem's configuration does not matter. Integration gems set the default configuration at the end of their configure step; you can also set it yourself:
+
+```ruby
+PatientHttp.default_configuration = config
+```
+
+Use `PatientHttp.secret_registered?(name)` to check whether a secret is available, either at the module level or on the default configuration.
+
 ### 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:
@@ -567,12 +608,29 @@ PatientHttp.post(
 )
 ```
 
-Multiple preprocessors can be given as an array; they run in order, each seeing the changes made by the ones before it. `RequestTemplate` also accepts `preprocessors:` as a template-wide default.
+Multiple preprocessors can be given as an array; they run in order, each seeing the changes made by the ones before it. `RequestTemplate` and the `RequestHelper` mixin's `request_template` also accept `preprocessors:` as a template-wide default, and the mixin's `async_*` helpers accept `preprocessors:` per request.
 
 If a request references a preprocessor name that is not registered, a `PatientHttp::RequestPreparer::PreprocessorNotFoundError` is raised, which surfaces through the normal request error path.
 
 When redirects are followed, preprocessors are re-run against each redirect URL so signatures stay valid. On cross-origin redirects they are dropped entirely, consistent with the stripping of `Authorization` and `Cookie` headers, so signed credentials are never sent to an unexpected origin.
 
+## Troubleshooting
+
+### Warning: `ThreadError: Attempt to unlock a mutex which is not locked`
+
+On some Ruby versions you may see a warning like this in your logs:
+
+```
+warn: Async::Task: Async::Pool::Controller Gardener [...]
+    | Task may have ended with unhandled exception.
+    |   ThreadError: Attempt to unlock a mutex which is not locked
+    |   → .../async-pool-x.y.z/lib/async/pool/controller.rb:132 in `synchronize'
+```
+
+This is caused by [Ruby bug #20907](https://bugs.ruby-lang.org/issues/20907) (see also [socketry/async#424](https://github.com/socketry/async/issues/424)): under the fiber scheduler, a fiber interrupted while waiting on a `ConditionVariable` fails to re-acquire its mutex before unwinding, raising a spurious `ThreadError`. It appears whenever a pooled HTTP client is closed while its connection pool's background "gardener" task is idle — for example when a connection is evicted after a connection error, when the least recently used client is evicted because the pool is full, or when the processor shuts down.
+
+The warning is harmless — connections are still closed correctly; only the log noise is wrong. The fix is to upgrade Ruby: the bug is fixed in Ruby 3.2.7+, 3.3.7+, and 3.4+.
+
 ## Configuration
 
 ```ruby

data/VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

data/lib/patient_http/inline_task_handler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PatientHttp
+  # No-op task handler used for inline request execution.
+  #
+  # The {SynchronousExecutor} invokes the user callback directly, so the
+  # completion and error hooks here are never exercised in practice; they are
+  # defined as no-ops to satisfy the {TaskHandler} contract. Inline requests
+  # have no job queue, so retrying is not supported.
+  #
+  # @api private
+  class InlineTaskHandler < TaskHandler
+    # @param response [Response] the HTTP response object
+    # @param callback [String] callback class name
+    # @return [void]
+    def on_complete(response, callback)
+    end
+
+    # @param error [Error] the error object
+    # @param callback [String] callback class name
+    # @return [void]
+    def on_error(error, callback)
+    end
+
+    # @raise [NotImplementedError] inline requests cannot be retried
+    def retry
+      raise NotImplementedError, "Inline requests cannot be retried"
+    end
+  end
+end

data/lib/patient_http/processor.rb

@@ -432,10 +432,15 @@ module PatientHttp
         @config.logger&.error("[PatientHttp] Reactor loop error: #{e.inspect}\n#{e.backtrace.join("\n")}")
       ensure
         # Close the HTTP connection pools while still inside the reactor so the
-        # pools' background gardener tasks shut down gracefully. Otherwise the
-        # reactor stops with open pools and async-pool force-cancels each
-        # gardener mid-wait, emitting a noisy (but harmless) ThreadError:
-        # "Attempt to unlock a mutex which is not locked".
+        # pools shut down in an orderly fashion: in-flight responses have been
+        # delivered above, and each pool's background gardener task is stopped
+        # by the pool itself rather than force-cancelled by the dying reactor.
+        #
+        # Note: on Ruby < 3.2.7 / < 3.3.7, stopping a gardener still logs a
+        # spurious (harmless) ThreadError: "Attempt to unlock a mutex which is
+        # not locked" — a fiber interrupted in ConditionVariable#wait fails to
+        # re-acquire its mutex (https://bugs.ruby-lang.org/issues/20907, fixed
+        # in Ruby 3.2.7+, 3.3.7+, and 3.4+).
         begin
           @http_client.close
         rescue => e

data/lib/patient_http/request_helper.rb

@@ -114,13 +114,16 @@ module PatientHttp
       # @param headers [Hash] default headers for requests
       # @param params [Hash, nil] default query parameters for requests
       # @param timeout [Float] default timeout in seconds
+      # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] default names of
+      #   preprocessors registered on the configuration to apply to requests
       # @return [void]
-      def request_template(base_url: nil, headers: {}, params: nil, timeout: 30)
+      def request_template(base_url: nil, headers: {}, params: nil, timeout: 30, preprocessors: nil)
         @patient_http_request_template = RequestTemplate.new(
           base_url: base_url,
           headers: headers,
           params: params,
-          timeout: timeout
+          timeout: timeout,
+          preprocessors: preprocessors
         )
       end
 
@@ -140,6 +143,8 @@ module PatientHttp
       # @param raise_error_responses [Boolean, nil] when true, non-success responses are
       #   reported as errors
       # @param callback_args [Hash, nil] JSON-compatible callback arguments
+      # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] names of preprocessors
+      #   registered on the configuration to apply to the request when it is sent
       # @return [Object] return value from the registered request handler
       def async_request(
         method,
@@ -151,10 +156,11 @@ module PatientHttp
         params: nil,
         timeout: nil,
         raise_error_responses: nil,
-        callback_args: nil
+        callback_args: nil,
+        preprocessors: nil
       )
         template = async_request_template
-        kwargs = {body: body, json: json, headers: headers, params: params, timeout: timeout}
+        kwargs = {body: body, json: json, headers: headers, params: params, timeout: timeout, preprocessors: preprocessors}
         request = if template
           template.request(method, url, **kwargs)
         else
@@ -198,6 +204,8 @@ module PatientHttp
     # @param raise_error_responses [Boolean, nil] when true, non-success responses are
     #   reported as errors
     # @param callback_args [Hash, nil] JSON-compatible callback arguments
+    # @param preprocessors [String, Symbol, Array<String, Symbol>, nil] names of preprocessors
+    #   registered on the configuration to apply to the request when it is sent
     # @return [Object] return value from the registered request handler
     def async_request(
       method,
@@ -209,7 +217,8 @@ module PatientHttp
       params: nil,
       timeout: nil,
       raise_error_responses: nil,
-      callback_args: nil
+      callback_args: nil,
+      preprocessors: nil
     )
       self.class.async_request(
         method,
@@ -221,7 +230,8 @@ module PatientHttp
         params: params,
         timeout: timeout,
         raise_error_responses: raise_error_responses,
-        callback_args: callback_args
+        callback_args: callback_args,
+        preprocessors: preprocessors
       )
     end
 

data/lib/patient_http.rb

@@ -51,6 +51,7 @@ module PatientHttp
   autoload :ExternalStorage, File.join(__dir__, "patient_http/external_storage")
   autoload :HttpError, File.join(__dir__, "patient_http/http_error")
   autoload :HttpHeaders, File.join(__dir__, "patient_http/http_headers")
+  autoload :InlineTaskHandler, File.join(__dir__, "patient_http/inline_task_handler")
   autoload :LifecycleManager, File.join(__dir__, "patient_http/lifecycle_manager")
   autoload :OutgoingRequest, File.join(__dir__, "patient_http/outgoing_request")
   autoload :Payload, File.join(__dir__, "patient_http/payload")
@@ -78,6 +79,11 @@ module PatientHttp
   @testing = %w[RAILS_ENV RACK_ENV APP_ENV].any? { |var| ENV[var] == "test" }
   @handler = nil
   @handler_mutex = Monitor.new
+  @inline_handler = nil
+  @default_configuration = nil
+  @inline_configuration = nil
+  @module_secrets = {}
+  @config_mutex = Monitor.new
 
   class << self
     # Check if running in testing mode.
@@ -153,6 +159,81 @@ module PatientHttp
       end
     end
 
+    # Registers a request handler that executes requests inline (synchronously,
+    # in-process) instead of dispatching them to a job system.
+    #
+    # This is intended for consoles, tests, and development environments where no
+    # job-system integration gem is configured. Each request runs through
+    # {SynchronousExecutor} and the callback is invoked on the calling thread
+    # before the handler returns.
+    #
+    # @param config [Configuration, nil] configuration to execute requests against.
+    #   Defaults to {.default_configuration}, or a lazily created configuration that
+    #   includes any secrets registered with {.register_secret}.
+    # @return [void]
+    def inline!(config: nil)
+      handler = lambda do |request:, callback:, callback_args: nil, raise_error_responses: nil|
+        execute_inline(
+          request: request,
+          callback: callback,
+          callback_args: callback_args,
+          raise_error_responses: raise_error_responses,
+          config: config
+        )
+      end
+
+      @handler_mutex.synchronize do
+        register_handler(handler)
+        @inline_handler = handler
+      end
+    end
+
+    # Check if the currently registered handler is the inline handler registered
+    # by {.inline!}.
+    #
+    # @return [Boolean]
+    def inline?
+      @handler_mutex.synchronize { !@handler.nil? && @handler.equal?(@inline_handler) }
+    end
+
+    # Check if a request handler is registered.
+    #
+    # @return [Boolean]
+    def handler_registered?
+      @handler_mutex.synchronize { !@handler.nil? }
+    end
+
+    # Executes a request inline (synchronously, in-process) through
+    # {SynchronousExecutor}, invoking the callback with the response or error
+    # before returning.
+    #
+    # @param request [Request] the HTTP request to execute
+    # @param callback [Class, String] the callback class or name
+    # @param callback_args [Hash, nil] JSON-compatible callback arguments
+    # @param raise_error_responses [Boolean, nil] when true, non-success responses are
+    #   reported as errors; defaults to the configuration's setting
+    # @param config [Configuration, nil] configuration to execute the request against.
+    #   Defaults to {.default_configuration}, or a lazily created configuration that
+    #   includes any secrets registered with {.register_secret}.
+    # @return [String] the request id
+    def execute_inline(request:, callback:, callback_args: nil, raise_error_responses: nil, config: nil)
+      config ||= default_configuration || inline_configuration
+      raise_error_responses = config.raise_error_responses if raise_error_responses.nil?
+
+      task = RequestTask.new(
+        request: request,
+        task_handler: InlineTaskHandler.new,
+        callback: callback,
+        callback_args: callback_args,
+        raise_error_responses: raise_error_responses,
+        default_max_redirects: config.max_redirects
+      )
+
+      SynchronousExecutor.new(task, config: config).call
+
+      task.id
+    end
+
     # Executes the registered request handler with the given request parameters.
     #
     # @param request [Request] the HTTP request to handle
@@ -287,8 +368,93 @@ module PatientHttp
       SecretReference.new(name)
     end
 
+    # Register a named secret at the module level, independent of any configuration.
+    #
+    # Secrets registered here are applied to the {.default_configuration} (immediately
+    # if one is already set, or when one is set later) and to the configuration used
+    # for inline execution. This makes boot order irrelevant: application code can
+    # register secrets before or after the job-system integration gem configures the
+    # processor.
+    #
+    # @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]
+    # @see Configuration#register_secret
+    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
+
+      @config_mutex.synchronize do
+        secret_value = block || value
+        @module_secrets[name.to_s] = secret_value
+        @default_configuration&.register_secret(name, secret_value)
+        @inline_configuration&.register_secret(name, secret_value)
+      end
+    end
+
+    # Check if a secret name is registered, either at the module level via
+    # {.register_secret} or on the {.default_configuration}.
+    #
+    # @param name [String, Symbol] the secret name
+    # @return [Boolean]
+    def secret_registered?(name)
+      @config_mutex.synchronize do
+        return true if @module_secrets.include?(name.to_s)
+
+        !@default_configuration.nil? && @default_configuration.secret_manager.include?(name)
+      end
+    end
+
+    # The default configuration used for inline execution when none is provided.
+    # Job-system integration gems should set this at the end of their configure
+    # step so that module-level secrets registered with {.register_secret} are
+    # applied to the configuration the processor runs with.
+    #
+    # @return [Configuration, nil] the default configuration
+    def default_configuration
+      @config_mutex.synchronize { @default_configuration }
+    end
+
+    # Set the default configuration. Any secrets registered with {.register_secret}
+    # are applied to it; the module-level registry is retained, so re-assigning a
+    # new configuration re-applies the same secrets.
+    #
+    # @param config [Configuration, nil] the configuration to use as the default
+    # @return [void]
+    def default_configuration=(config)
+      @config_mutex.synchronize do
+        @default_configuration = config
+        apply_module_secrets(config) if config
+      end
+    end
+
     private
 
+    # The lazily created configuration used for inline execution when no explicit
+    # or default configuration is available. Module-level secrets are applied to it.
+    #
+    # @return [Configuration]
+    def inline_configuration
+      @config_mutex.synchronize do
+        @inline_configuration ||= Configuration.new.tap { |config| apply_module_secrets(config) }
+      end
+    end
+
+    # Apply all module-level secrets to the given configuration.
+    #
+    # @param config [Configuration] the configuration to apply secrets to
+    # @return [void]
+    def apply_module_secrets(config)
+      @module_secrets.each { |name, value| config.register_secret(name, value) }
+    end
+
     # Validates that the handler accepts the required keyword arguments.
     #
     # @param handler [#call] the handler to validate

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_http
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Brian Durand
@@ -109,6 +109,7 @@ files:
 - lib/patient_http/external_storage.rb
 - lib/patient_http/http_error.rb
 - lib/patient_http/http_headers.rb
+- lib/patient_http/inline_task_handler.rb
 - lib/patient_http/lifecycle_manager.rb
 - lib/patient_http/outgoing_request.rb
 - lib/patient_http/payload.rb