patient_http 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 393cbf361701d9e1dc190b80f571d78059a21dae85f225750198a1ab173e8bb8
-  data.tar.gz: 3d5349e55335d4cd262699481517d3c44825c27449a2b3b11d9559a7b4f468b0
+  metadata.gz: d0888d7e92f43f2031bf7f0eb5b0f4dd528ac7b79957b506f1df61825309990a
+  data.tar.gz: 87b5817b8205a0b605edb7cb41facf0f6b5690122ff63cb669dbcc6c6b090cd0
 SHA512:
-  metadata.gz: '06894a234fca9e2c12aa77b69cf5347824de6f6be9e3b912dcc3e7834e2137231144e69ba58bef85fb026b200369ad976befc4e540ba9f2779a31fe3e68991a0'
-  data.tar.gz: ac60b71f532664b3083697dd1c225f4a5a787f07de04d2458d3f849c3b3962d68062740b7e0f03b981edf7aa9ab6fac98aadff98ef9549a0efe15c0b3b968de1
+  metadata.gz: 4bd3586a382436ac11872d10380afb28326497c9538383ae0e884ecaf901dd952df0202e9ed740047b6336c60960ebff20b83abcdc86a585c67e0915097dbe92
+  data.tar.gz: d86c67c48c1aa03d0aa47f4675626696ab9012b526add67a4d8ebf611aca40b8229e722bd2e07c2ef6de6caa6110a01507d3317f029668fa89a768d145fea299

data/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.4.0
+
+### Added
+
+ - `ProcessorObserver` events for the full task pipeline: `request_enqueued` is sent when a task is announced to the processor, before the task is visible to the reactor, so observers can set up durable tracking (e.g. a crash-recovery registry entry) before `Processor#enqueue` returns or raises. `request_rejected` is sent when an announced task is not accepted (not running or at capacity). `request_requeued` is sent when an incomplete task is re-enqueued through its task handler, so observers can tear down tracking for tasks the job system owns again. Redirect tasks are announced with `request_enqueued` as well.
+ - `Processor#tracked_request_ids` returns the IDs of all tasks in the pipeline (queued, pending, and in-flight), so durable tracking can keep heartbeats alive for tasks that have not started yet.
+
+### Fixed
+
+- A task is now marked as started before the `request_start` notification is sent. Before this fix, a shutdown that snapshotted the task between the two steps re-enqueued the task without a `request_end` notification, which could leak observer tracking for the task and cause a duplicate execution through crash recovery.
+
+## 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
@@ -686,6 +744,14 @@ end
 processor.observe(MetricsObserver.new)
 ```
 
+Observers can also track the full task pipeline:
+
+ - `request_enqueued(request_task)` is called when a task is announced to the processor (before the task is visible to the reactor). It is guaranteed to arrive before `request_start`, so observers can set up durable tracking (e.g. a crash-recovery registry entry) before `Processor#enqueue` returns or raises.
+ - `request_rejected(request_task)` is called when an announced task is not accepted (not running or at capacity), so observers can tear down anything they set up in `request_enqueued`.
+- `request_requeued(request_task)` is called when an incomplete task is re-enqueued through its task handler (processor shutdown or reactor failure). The job system owns the request again once this is sent.
+
+Use `Processor#tracked_request_ids` to get the IDs of all tasks in the pipeline (queued, pending, and in-flight), for example to keep heartbeats alive for tasks that have not started yet.
+
 ## Testing
 
 Use `SynchronousExecutor` to execute requests synchronously in tests. This class can be used in place of the async processor for testing your request handling logic without needing to start the full async infrastructure.

data/VERSION

@@ -1 +1 @@
-1.2.0
+1.4.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

@@ -33,6 +33,10 @@ module PatientHttp
       @reactor_generation = 0
       @inflight_requests = Concurrent::Hash.new
       @pending_tasks = Concurrent::Hash.new
+      # Tasks pushed onto @queue but not yet popped by the reactor. Kept in a
+      # hash because Thread::Queue cannot be enumerated; used to report all
+      # tracked task ids (e.g. for heartbeat updates on queued tasks).
+      @queued_tasks = Concurrent::Hash.new
       @tasks_lock = Mutex.new
       @idle_condition = ConditionVariable.new
       @testing_callback = nil
@@ -76,14 +80,21 @@ module PatientHttp
           # lock; re-enqueueing runs outside it. This is idempotent with stop()'s
           # reenqueue_pending_requests: whichever runs second snapshots an empty
           # set.
+          current_generation = false
           orphaned_tasks = @tasks_lock.synchronize do
             if @reactor_generation == generation
+              current_generation = true
               drain_tracked_tasks_locked
             else
               []
             end
           end
           reenqueue_tasks(orphaned_tasks)
+          # Hand back tasks still sitting in the queue as well; a reactor that
+          # exits without a stop() call is the last owner of those tasks.
+          # stop() performs the same drain after reaping the reactor, and
+          # whichever drain runs second finds nothing left.
+          reenqueue_remaining_queue_items if current_generation
         end
 
         # The transition can fail if the reactor thread already failed and
@@ -198,22 +209,18 @@ module PatientHttp
     # @raise [MaxCapacityError] if at max capacity
     # @return [void]
     def enqueue(task)
-      at_capacity = false
+      raise NotRunningError.new("Cannot enqueue request: processor is #{state}") unless running?
 
-      @tasks_lock.synchronize do
+      accepted = announce_and_enqueue(task) do
+        # The pre-check above is advisory; re-check the running state under
+        # the lock since observers were notified outside of it.
         raise NotRunningError.new("Cannot enqueue request: processor is #{state}") unless running?
 
-        # Check capacity - raise error if at max connections
-        total = @queue.size + @pending_tasks.size + @inflight_requests.size
-        if total >= @config.max_connections
-          at_capacity = true
-        else
-          task.enqueued!
-          @queue.push(task)
-        end
+        # Check capacity - the task is only accepted below max connections.
+        @queue.size + @pending_tasks.size + @inflight_requests.size < @config.max_connections
       end
 
-      if at_capacity
+      unless accepted
         notify_observers { |observer| observer.capacity_exceeded }
         raise MaxCapacityError.new("Cannot enqueue request: already at max capacity (#{@config.max_connections} connections)")
       end
@@ -307,6 +314,17 @@ module PatientHttp
       end
     end
 
+    # Get the IDs of all tasks in the pipeline (queued, pending, and in-flight).
+    # Use this to keep durable tracking (e.g. heartbeats) alive for tasks the
+    # processor has accepted but not yet started.
+    #
+    # @return [Array<String>]
+    def tracked_request_ids
+      @tasks_lock.synchronize do
+        (@queued_tasks.keys + @pending_tasks.keys + @inflight_requests.keys).uniq
+      end
+    end
+
     # Add an observer for processor events.
     #
     # @param observer [ProcessorObserver] the observer to add
@@ -393,6 +411,7 @@ module PatientHttp
 
           # Track as pending immediately to avoid race condition with stop()
           @tasks_lock.synchronize do
+            @queued_tasks.delete(request_task.id)
             @pending_tasks[request_task.id] = request_task
           end
 
@@ -432,10 +451,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
@@ -468,12 +492,15 @@ module PatientHttp
 
         @pending_tasks.delete(task.id)
         @inflight_requests[task.id] = task
+        # Mark the task started in the same locked section that tracks it so
+        # a shutdown snapshot always sees a consistent started state. The
+        # shutdown re-enqueue path uses started? to pair request_end with
+        # request_start.
+        task.started!
       end
 
       notify_observers { |observer| observer.request_start(task) }
 
-      # Mark task as started
-      task.started!
       claimed = false
 
       begin
@@ -606,13 +633,9 @@ module PatientHttp
       # from in-flight) and enqueue the redirect. If the claim fails the
       # shutdown sequence already re-enqueued the original, so drop the redirect.
       redirect_task = task.redirect_task(location: location, status: status)
-      redirect_task.enqueued!
-
-      claimed = @tasks_lock.synchronize do
-        next false if @inflight_requests.delete(task.id).nil?
 
-        @queue.push(redirect_task)
-        true
+      claimed = announce_and_enqueue(redirect_task) do
+        !@inflight_requests.delete(task.id).nil?
       end
       return false unless claimed
 
@@ -641,6 +664,47 @@ module PatientHttp
       raise if PatientHttp.testing?
     end
 
+    # Announce a task to observers and make it visible to the reactor. The
+    # task is announced before it can start, finish, or be re-enqueued, so
+    # observers can set up durable tracking first. Errors from the
+    # request_enqueued announcement propagate and reject the task, because a
+    # failed tracking setup must not let the task be accepted as if it were
+    # durable. The block runs while {@tasks_lock} is held and decides whether
+    # the task is accepted; when it returns false or raises, observers receive
+    # request_rejected so they can tear down anything they set up for the
+    # request_enqueued announcement. The rejection notification never replaces
+    # an exception that is already being raised.
+    #
+    # @param task [RequestTask] the request task to announce and enqueue
+    # @return [Boolean] true if the task was accepted
+    def announce_and_enqueue(task)
+      task.enqueued!
+      accepted = false
+
+      begin
+        notify_observers! { |observer| observer.request_enqueued(task) }
+
+        @tasks_lock.synchronize do
+          if yield
+            @queued_tasks[task.id] = task
+            @queue.push(task)
+            accepted = true
+          end
+        end
+      ensure
+        unless accepted
+          pending_error = $!
+          begin
+            notify_observers { |observer| observer.request_rejected(task) }
+          rescue
+            raise unless pending_error
+          end
+        end
+      end
+
+      accepted
+    end
+
     # Notify all observers of an event. Observers are called outside of any
     # internal lock so they can safely call back into the processor.
     def notify_observers(&block)
@@ -650,6 +714,16 @@ module PatientHttp
       end
     end
 
+    # Notify all observers of an event and let observer errors propagate.
+    # Used for notifications the caller must be able to react to, such as
+    # durable tracking setup in request_enqueued.
+    def notify_observers!
+      observers = @tasks_lock.synchronize { @observers.dup }
+      observers.each do |observer|
+        yield(observer)
+      end
+    end
+
     def notify_observer(observer)
       yield(observer)
     rescue => e
@@ -692,16 +766,27 @@ module PatientHttp
     end
 
     def reenqueue_remaining_queue_items
-      tasks_to_reenqueue = []
-
-      # Drain remaining items from the queue (skip nil sentinels from stop)
-      until @queue.empty?
-        begin
-          task = @queue.pop(true)
-          tasks_to_reenqueue << task if task
-        rescue ThreadError
-          break
+      tasks_to_reenqueue = @tasks_lock.synchronize do
+        tasks = []
+
+        # Drain remaining items from the queue (skip nil sentinels from stop)
+        until @queue.empty?
+          begin
+            task = @queue.pop(true)
+            tasks << task if task
+          rescue ThreadError
+            break
+          end
         end
+
+        tasks.each { |task| @queued_tasks.delete(task.id) }
+        # The reactor has exited and no new tasks can be accepted, so any id
+        # still tracked as queued belongs to a task that left the queue
+        # without reaching pending or in-flight tracking. Reclaim those tasks
+        # as well so they are not tracked forever.
+        tasks.concat(@queued_tasks.values)
+        @queued_tasks.clear
+        tasks
       end
 
       reenqueue_tasks(tasks_to_reenqueue)
@@ -710,6 +795,10 @@ module PatientHttp
     def reenqueue_tasks(tasks_to_reenqueue)
       tasks_to_reenqueue.each do |task|
         task.retry
+        # The task handler's job system owns the request again; let observers
+        # tear down any durable tracking for the task. Only sent after a
+        # successful retry so a failed retry leaves the tracking in place.
+        notify_observers { |observer| observer.request_requeued(task) }
         # Only emit request_end for tasks that actually started, so observers
         # that pair request_start/request_end (e.g. an in-flight gauge) stay
         # balanced. Queued-but-never-started tasks emit neither.

data/lib/patient_http/processor_observer.rb

@@ -24,6 +24,41 @@ module PatientHttp
     def capacity_exceeded
     end
 
+    # Called when a request task is handed to the processor, before the task is
+    # visible to the reactor. The notification is guaranteed to arrive before
+    # request_start for the task, so observers can set up durable tracking
+    # (e.g. a crash-recovery registry entry) with no risk that the task
+    # completes first. If the processor does not accept the task,
+    # request_rejected is sent afterward. Unlike other notifications, an error
+    # raised here propagates from Processor#enqueue and rejects the task, so a
+    # failed tracking setup does not let the task be accepted as if it were
+    # durable.
+    #
+    # @param request_task [RequestTask] the request task that was enqueued
+    # @return [void]
+    def request_enqueued(request_task)
+    end
+
+    # Called when a request task announced with request_enqueued was not
+    # accepted by the processor (not running or at capacity). Observers should
+    # tear down anything they set up in request_enqueued; the caller owns the
+    # request again once this is sent.
+    #
+    # @param request_task [RequestTask] the request task that was rejected
+    # @return [void]
+    def request_rejected(request_task)
+    end
+
+    # Called when an incomplete request task was re-enqueued through its task
+    # handler (processor shutdown or reactor failure). The task handler's job
+    # system owns the request again once this is sent, so observers should
+    # tear down any durable tracking for the task.
+    #
+    # @param request_task [RequestTask] the request task that was re-enqueued
+    # @return [void]
+    def request_requeued(request_task)
+    end
+
     # Called when a request starts processing.
     #
     # @param request_task [RequestTask] the request task that started

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

data/patient_http.gemspec

@@ -43,6 +43,4 @@ Gem::Specification.new do |spec|
   spec.add_dependency "async-http", "~> 0.60"
   spec.add_dependency "concurrent-ruby", "~> 1.2"
   spec.add_dependency "logger"
-
-  spec.add_development_dependency "bundler"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patient_http
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Brian Durand
@@ -65,20 +65,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: This gem provides a dedicated async HTTP processor that uses Ruby's Fiber
   scheduler for non-blocking I/O. Application threads hand off HTTP requests to the
   processor and return immediately. The processor handles hundreds of concurrent HTTP
@@ -109,6 +95,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
@@ -158,7 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Generic async HTTP connection pool for Ruby applications using Fiber-based
   concurrency