patient_http-solid_queue 1.2.1 → 1.3.0

data/lib/patient_http/solid_queue/request_executor.rb

@@ -2,21 +2,32 @@
 
 module PatientHttp
   module SolidQueue
-    # Helper methods for executing HTTP requests asynchronously.
+    # Runs HTTP requests on a processor in the current process.
     class RequestExecutor
       class << self
-        # Execute the request directly on the async processor.
+        # Hands the request to the async processor.
         #
-        # @param request [PatientHttp::Request] the HTTP request to execute
-        # @param callback [Class, String] Callback service class or its fully qualified class name
-        # @param active_job_data [Hash, nil] Active Job serialized hash with "job_class" and "arguments" keys
-        # @param synchronous [Boolean] If true, runs the request inline (for testing)
-        # @param callback_args [#to_h, nil] Arguments to pass to callback
-        # @param raise_error_responses [Boolean] If true, treats non-2xx responses as errors
-        # @param request_id [String, nil] Unique request ID for tracking
-        # @param processor_name [Symbol, String, nil] Name of the processor profile to run
-        #   the request on. Defaults to the request's own processor name or :default.
-        # @return [String] the request ID
+        # @param request [PatientHttp::Request] The HTTP request to execute.
+        # @param callback [Class, String] The callback service class, or its
+        #   fully qualified class name.
+        # @param active_job_data [Hash, nil] The serialized Active Job, with
+        #   `"job_class"` and `"arguments"` keys. Defaults to the current job.
+        # @param synchronous [Boolean] If `true`, runs the request inline. Use
+        #   this in tests.
+        # @param callback_args [#to_h, nil] Arguments to pass to the callback.
+        # @param raise_error_responses [Boolean, nil] If `true`, treats non-2xx
+        #   responses as errors. If `nil`, uses the processor profile's
+        #   `raise_error_responses` option.
+        # @param request_id [String, nil] A unique request ID for tracking.
+        # @param processor_name [Symbol, String, nil] The name of the processor
+        #   profile that runs the request. Defaults to the request's processor
+        #   name, or `:default`.
+        # @return [String] The request ID.
+        # @raise [ArgumentError] If the Active Job data is missing or invalid.
+        # @raise [PatientHttp::UnknownProcessorError] If the processor profile
+        #   isn't configured.
+        # @raise [PatientHttp::NotRunningError] If the processor isn't running.
+        # @raise [PatientHttp::MaxCapacityError] If the processor is at capacity.
         # @api private
         def execute(
           request,
@@ -24,19 +35,26 @@ module PatientHttp
           active_job_data: nil,
           synchronous: false,
           callback_args: nil,
-          raise_error_responses: false,
+          raise_error_responses: nil,
           request_id: nil,
           processor_name: nil
         )
           active_job_data = validate_active_job_data(active_job_data)
-          task_handler = TaskHandler.new(active_job_data)
-          config = PatientHttp::SolidQueue.configuration
 
           # Resolve the processor profile up front so the task is built with
-          # the options of the processor that will run it. An unknown name
+          # the options of the processor that will run it. A running processor
+          # already holds its built profile configuration. An unknown name
           # falls back to the base configuration here and is reported below.
           name = (processor_name || request.processor || :default).to_sym
-          profile_config = config.processor_profiles.key?(name) ? config.processor_config(name) : config
+          processor = PatientHttp::SolidQueue.processor(name)
+          declared_config = PatientHttp::SolidQueue.processor_config_for(name)
+          profile_config = declared_config || PatientHttp::SolidQueue.configuration
+
+          # A nil value means the caller did not ask for a specific behavior.
+          # Jobs enqueued by earlier versions of the gem can also carry nil.
+          raise_error_responses = profile_config.raise_error_responses if raise_error_responses.nil?
+
+          task_handler = TaskHandler.new(active_job_data, config: profile_config)
 
           task = PatientHttp::RequestTask.new(
             request: request,
@@ -58,12 +76,11 @@ module PatientHttp
             return task.id
           end
 
-          # Look up the named processor. An unknown name raises so the job
+          # An unknown processor name raises so the job
           # lands in Active Job's retry mechanism instead of being dropped;
           # this covers rolling deploys where an old process has not
           # configured a new profile yet.
-          processor = PatientHttp::SolidQueue.processor(name)
-          if processor.nil? && !config.processor_profiles.key?(name)
+          if declared_config.nil?
             raise PatientHttp::UnknownProcessorError, "No processor profile configured for #{name.inspect}"
           end
 

data/lib/patient_http/solid_queue/request_job.rb

@@ -2,11 +2,11 @@
 
 module PatientHttp
   module SolidQueue
-    # Active Job that executes HTTP requests asynchronously.
+    # Active Job that hands HTTP requests to the async processor.
     #
-    # Enqueued when calling PatientHttp::SolidQueue.get, .post, etc.
-    # On completion, the specified callback service's on_complete or on_error is
-    # invoked via CallbackJob.
+    # `PatientHttp.get`, `PatientHttp.post`, and the other request methods
+    # enqueue this job. When the request completes, `CallbackJob` calls the
+    # callback service's `on_complete` or `on_error` method.
     #
     # @api private
     class RequestJob < ActiveJob::Base
@@ -38,13 +38,22 @@ module PatientHttp
         )
       end
 
-      # @param data [Hash] Request data (possibly a storage reference)
-      # @param callback_service_name [String] Fully qualified callback service class name
-      # @param raise_error_responses [Boolean, nil] Whether to treat non-2xx responses as errors
-      # @param callback_args [Hash, nil] Arguments to pass to the callback
-      # @param request_id [String, nil] Unique request ID for tracking
-      # @param processor_name [String, nil] Name of the processor profile to run the request
-      #   on; nil (jobs enqueued by older versions) runs on the default processor
+      # Runs the HTTP request on a processor.
+      #
+      # @param data [Hash] The serialized request, or a reference to it in
+      #   external storage. The request can be encrypted.
+      # @param callback_service_name [String] The fully qualified callback
+      #   service class name.
+      # @param raise_error_responses [Boolean, nil] Whether to treat non-2xx
+      #   responses as errors. If `nil`, uses the processor profile's
+      #   `raise_error_responses` option.
+      # @param callback_args [Hash, nil] The arguments to pass to the callback.
+      # @param request_id [String, nil] The request ID.
+      # @param processor_name [String, nil] The name of the processor profile
+      #   that runs the request. If `nil`, uses the processor set on the
+      #   request, then the default processor. Jobs enqueued by earlier
+      #   versions of the gem don't have this argument.
+      # @return [void]
       def perform(data, callback_service_name, raise_error_responses, callback_args, request_id, processor_name = nil)
         actual_data = PatientHttp::ExternalStorage.storage_ref?(data) ? PatientHttp::SolidQueue.external_storage.fetch(data) : data
         actual_data = PatientHttp::SolidQueue.decrypt(actual_data)
@@ -63,7 +72,7 @@ module PatientHttp
           callback_args: callback_args,
           active_job_data: active_job_data,
           request_id: request_id,
-          processor_name: processor_name || "default"
+          processor_name: processor_name
         )
       end
     end

data/lib/patient_http/solid_queue/task_handler.rb

@@ -2,50 +2,82 @@
 
 module PatientHttp
   module SolidQueue
-    # Active Job implementation of TaskHandler.
+    # Task handler that uses Active Job to deliver results and retry requests.
     #
-    # Handles task lifecycle operations using Active Job for job management:
-    # - Completion and error callbacks are triggered via CallbackJob
-    # - Large payloads are stored via ExternalStorage before enqueuing
-    # - Job retry uses ActiveJob::Base.deserialize
+    # - A `CallbackJob` delivers each result to the callback service.
+    # - Large payloads are written to external storage before the job is
+    #   enqueued.
+    # - A retry enqueues the original Active Job again.
     class TaskHandler < PatientHttp::TaskHandler
+      # @return [Hash] The serialized Active Job that made the request.
       attr_reader :active_job_data
 
-      def initialize(active_job_data)
+      # Creates a task handler for an Active Job.
+      #
+      # @param active_job_data [Hash] The serialized Active Job that made the
+      #   request.
+      # @param config [PatientHttp::Configuration, nil] The configuration of the
+      #   processor that runs the request. If `nil`, uses the base configuration.
+      def initialize(active_job_data, config: nil)
         @active_job_data = active_job_data
+        @config = config
       end
 
+      # Enqueues a `CallbackJob` that calls the callback service's `on_complete`
+      # method. A large response is written to external storage first.
+      #
+      # @param response [PatientHttp::Response] The HTTP response.
+      # @param callback [String] The callback service class name.
+      # @return [void]
       def on_complete(response, callback)
         data = store_if_needed(response.as_json)
         CallbackJob.perform_later(data, "response", callback)
         delete_stored_request_payload
       end
 
+      # Enqueues a `CallbackJob` that calls the callback service's `on_error`
+      # method. A large error is written to external storage first.
+      #
+      # @param error [PatientHttp::Error] The error.
+      # @param callback [String] The callback service class name.
+      # @return [void]
       def on_error(error, callback)
         data = store_if_needed(error.as_json)
         CallbackJob.perform_later(data, "error", callback)
         delete_stored_request_payload
       end
 
+      # Re-enqueues the original Active Job with its execution count reset.
+      #
+      # @return [ActiveJob::Base, false] The enqueued job, or `false` if it
+      #   wasn't enqueued.
       def retry
         ActiveJob::Base.deserialize(@active_job_data).tap { |j| j.executions = 0 }.enqueue
       end
 
+      # Returns the Active Job ID.
+      #
+      # @return [String] The job ID.
       def job_id
         @active_job_data["job_id"]
       end
 
+      # Returns the class of the Active Job.
+      #
+      # @return [Class] The job class.
       def worker_class
         PatientHttp::ClassHelper.resolve_class_name(@active_job_data["job_class"])
       end
 
       private
 
-      # Delete the externally stored request payload once the request has
-      # completed. Until then the payload must remain fetchable because the
-      # Active Job data referencing it can be re-enqueued by Active Job retries,
-      # processor shutdown retries, and crash recovery. Only applies to
-      # RequestJob jobs; other job types own their own arguments.
+      # Deletes the externally stored request payload after the request
+      # finishes. The payload must stay available until then, because Active Job
+      # retries, processor shutdown retries, and crash recovery can enqueue the
+      # job again. Applies only to `RequestJob` jobs, because other job types
+      # manage their own arguments.
+      #
+      # @return [void]
       def delete_stored_request_payload
         return unless @active_job_data["job_class"] == RequestJob.name
 
@@ -63,7 +95,7 @@ module PatientHttp
         encrypted = PatientHttp::SolidQueue.encrypt(data)
         external_storage = PatientHttp::SolidQueue.external_storage
         if external_storage.enabled?
-          external_storage.store(encrypted, max_size: PatientHttp::SolidQueue.configuration.payload_store_threshold)
+          external_storage.store(encrypted, max_size: (@config || PatientHttp::SolidQueue.configuration).payload_store_threshold)
         else
           encrypted
         end

data/lib/patient_http/solid_queue/task_monitor.rb

@@ -2,27 +2,35 @@
 
 module PatientHttp
   module SolidQueue
-    # Manages inflight request tracking in the database for crash recovery.
+    # Tracks in-flight requests in the database for crash recovery.
     #
-    # This class maintains Active Record records for each in-flight request.
-    # It provides distributed locking for orphan detection and automatic
-    # re-enqueueing of requests interrupted by process crashes.
+    # The registry keeps an Active Record row for each in-flight request, with
+    # its heartbeat time and its Active Job. If a process crashes, another
+    # process finds the orphaned requests and re-enqueues their jobs. A
+    # distributed lock lets only one process at a time look for orphaned
+    # requests.
     #
-    # Task ID format: "hostname:pid:hex/request-uuid"
-    # - hostname: sanitized hostname (colons and slashes replaced with dashes)
-    # - pid: process ID
-    # - hex: 8-character random hex for uniqueness
-    # - request-uuid: unique identifier for the request
+    # Each entry has a registry ID in the format
+    # `hostname:pid:hex/request-uuid`:
+    #
+    # - `hostname`: The host name, with colons and slashes replaced by dashes.
+    # - `pid`: The process ID.
+    # - `hex`: 16 random hex characters that make the ID unique.
+    # - `request-uuid`: The request ID.
     class TaskMonitor
+      # Name of the garbage collection lock row.
       GC_LOCK_NAME = "gc"
 
-      # @return [Configuration] the configuration object
+      # @return [Configuration] The gem configuration.
       attr_reader :config
 
-      # @param config [Configuration] the configuration object
-      # @param max_connections [#call, nil] callable returning the process's total
-      #   configured max connections; defaults to the configuration's value. With
-      #   named processors the module passes a sum across all processors.
+      # Creates a task monitor for this process.
+      #
+      # @param config [Configuration] The gem configuration.
+      # @param max_connections [#call, nil] A callable that returns the total
+      #   maximum number of connections for the process. Defaults to the
+      #   configuration's value. With named processors, the module passes the
+      #   sum across all processors.
       def initialize(config, max_connections: nil)
         @config = config
         @max_connections_source = max_connections || -> { config.max_connections }
@@ -31,16 +39,17 @@ module PatientHttp
         @lock_identifier = "#{hostname}:#{pid}:#{SecureRandom.hex(8)}".freeze
       end
 
-      # Register a request as inflight in the database.
+      # Records a request as in flight in the database.
       #
-      # Runs on the caller's thread via the request_enqueued observer event.
-      # Errors propagate so a task is never accepted without a durable record:
-      # the processor rejects the task and the enqueue raises to the caller.
-      # They are wrapped in RegistrationError so the job retries instead of
-      # failing outright, since the usual cause is a transient database issue.
+      # Runs on the caller's thread through the `request_enqueued` observer
+      # event. Errors propagate, so a task is never accepted without a durable
+      # record. The processor rejects the task, and the enqueue raises to the
+      # caller. The error is wrapped in `RegistrationError` so the job retries
+      # instead of failing, because the usual cause is a transient database
+      # issue.
       #
-      # @param task [PatientHttp::RequestTask] the request task to register
-      # @raise [RegistrationError] if the record cannot be written
+      # @param task [PatientHttp::RequestTask] The request task to register.
+      # @raise [RegistrationError] If the record can't be written.
       # @return [void]
       def register(task)
         job_payload = task.task_handler.active_job_data.to_json
@@ -61,9 +70,9 @@ module PatientHttp
         raise RegistrationError.new("Failed to register task #{task_id}: #{e.class} - #{e.message}")
       end
 
-      # Unregister a request from the database (called when request completes).
+      # Removes a request from the registry.
       #
-      # @param task [PatientHttp::RequestTask] the request task to unregister
+      # @param task [PatientHttp::RequestTask] The request task.
       # @return [void]
       def unregister(task)
         task_id = full_task_id(task.id)
@@ -75,14 +84,15 @@ module PatientHttp
         raise if PatientHttp.testing?
       end
 
-      # Release a request from this process so the orphan collector re-enqueues
-      # it on its next pass. Used when a result could not be delivered: the
-      # request is no longer tracked here, so its record must not keep looking
-      # like it belongs to a live process. Orphan collection skips records
-      # whose process is still registered, which would otherwise strand the
-      # request until this process exits.
+      # Releases a request from this process, so the orphan collector
+      # re-enqueues it on its next pass.
+      #
+      # Use this when a result can't be delivered. This process no longer
+      # tracks the request, so its record must not look like it belongs to a
+      # live process. Orphan collection skips records whose process is still
+      # registered, which would strand the request until this process exits.
       #
-      # @param task [PatientHttp::RequestTask] the request task to release
+      # @param task [PatientHttp::RequestTask] The request task to release.
       # @return [void]
       def release(task)
         task_id = full_task_id(task.id)
@@ -97,9 +107,9 @@ module PatientHttp
         raise if PatientHttp.testing?
       end
 
-      # Update heartbeat timestamps for multiple requests in a single operation.
+      # Updates the heartbeat times of requests in one query.
       #
-      # @param task_ids [Array<String>] the request IDs to update
+      # @param task_ids [Array<String>] The request IDs.
       # @return [void]
       def update_heartbeats(task_ids)
         return if task_ids.empty?
@@ -113,7 +123,7 @@ module PatientHttp
         raise if PatientHttp.testing?
       end
 
-      # Record or refresh this process's registration.
+      # Creates or refreshes this process's registration.
       #
       # @return [void]
       def ping_process
@@ -130,7 +140,7 @@ module PatientHttp
         raise if PatientHttp.testing?
       end
 
-      # Remove this process's registration.
+      # Removes this process from the process registrations.
       #
       # @return [void]
       def remove_process
@@ -142,14 +152,14 @@ module PatientHttp
         raise if PatientHttp.testing?
       end
 
-      # Try to acquire the distributed garbage collection lock.
+      # Tries to acquire the distributed garbage collection lock.
       #
-      # Uses a single semaphore row and pessimistic locking to ensure only one
-      # process can claim the lock at a time.
-      # Returns false if another process holds a non-expired lock, or if GC was
-      # run recently (within heartbeat_interval).
+      # A single semaphore row with pessimistic locking makes sure that only
+      # one process at a time can claim the lock.
       #
-      # @return [Boolean] true if lock acquired, false otherwise
+      # @return [Boolean] `true` if the lock was acquired. `false` if another
+      #   process holds an unexpired lock, or if garbage collection ran within
+      #   the last `heartbeat_interval` seconds.
       def acquire_gc_lock
         now = Time.current
         expires_at = now + gc_lock_ttl.seconds
@@ -181,7 +191,8 @@ module PatientHttp
         false
       end
 
-      # Release the garbage collection lock if held by this process, and record last_gc_at.
+      # Releases the garbage collection lock if this process holds it, and
+      # records the time in `last_gc_at`.
       #
       # @return [void]
       def release_gc_lock
@@ -192,11 +203,12 @@ module PatientHttp
         raise if PatientHttp.testing?
       end
 
-      # Find and re-enqueue orphaned requests.
+      # Finds orphaned requests and re-enqueues them.
       #
-      # @param orphan_threshold_seconds [Numeric] age threshold for considering a request orphaned
-      # @param logger [Logger] logger for output
-      # @return [Integer] number of orphaned requests re-enqueued
+      # @param orphan_threshold_seconds [Numeric] The number of seconds without
+      #   a heartbeat after which a request is considered orphaned.
+      # @param logger [Logger] The logger for output.
+      # @return [Integer] The number of orphaned requests re-enqueued.
       def cleanup_orphaned_requests(orphan_threshold_seconds, logger)
         threshold = Time.current - orphan_threshold_seconds.seconds
 
@@ -222,18 +234,19 @@ module PatientHttp
         reenqueued_count
       end
 
-      # Build unique task ID for a request task that includes process identifier.
+      # Returns the registry ID for a request. The registry ID includes this
+      # process's ID.
       #
-      # @param task_id [String] the request task ID
-      # @return [String] the unique task ID
+      # @param task_id [String] The request ID.
+      # @return [String] The registry ID.
       def full_task_id(task_id)
         "#{@lock_identifier}/#{task_id}"
       end
 
-      # Check if a task is registered in the inflight table.
+      # Returns whether a request is in the registry.
       #
-      # @param task [PatientHttp::RequestTask] the request task
-      # @return [Boolean]
+      # @param task [PatientHttp::RequestTask] The request task.
+      # @return [Boolean] `true` if the request is registered.
       # @api private
       def registered?(task)
         with_connection do
@@ -241,9 +254,9 @@ module PatientHttp
         end
       end
 
-      # Clear all records. Only allowed in test environment.
+      # Deletes all records. Works only in test mode.
       #
-      # @raise [RuntimeError] if called outside of test environment
+      # @raise [RuntimeError] If called outside test mode.
       # @return [void]
       # @api private
       def self.clear_all!
@@ -258,9 +271,9 @@ module PatientHttp
 
       private
 
-      # Check out a database connection only for the duration of the work so
-      # gem-owned threads (completion workers, the monitor thread) do not pin
-      # connections from the pool between operations.
+      # Checks out a database connection only for the duration of the work, so
+      # the gem's threads don't hold pool connections between operations. The
+      # gem's threads are the completion workers and the monitor thread.
       def with_connection(&block)
         Record.connection_pool.with_connection(&block)
       end
@@ -275,29 +288,34 @@ module PatientHttp
         GcLock.insert_all([{lock_name: GC_LOCK_NAME}])
       end
 
-      # MySQL does not support an explicit conflict target for upserts; it always
-      # resolves conflicts via the table's unique indexes (ON DUPLICATE KEY UPDATE).
-      # Adapters with conflict targets (PostgreSQL, SQLite) require one to be given.
+      # Returns the conflict target for an upsert. MySQL doesn't support an
+      # explicit conflict target. It resolves conflicts through the table's
+      # unique indexes with `ON DUPLICATE KEY UPDATE`. Adapters that support
+      # conflict targets, such as PostgreSQL and SQLite, require one.
       #
-      # @param column [Symbol] the unique column to use as the conflict target
-      # @return [Symbol, nil] the column, or nil when the adapter forbids a target
+      # @param column [Symbol] The unique column to use as the conflict target.
+      # @return [Symbol, nil] The column, or `nil` if the adapter doesn't allow
+      #   a target.
       def upsert_unique_by(column)
         Record.connection.supports_insert_conflict_target? ? column : nil
       end
 
-      # Re-enqueue a single orphaned record.
+      # Re-enqueues one orphaned record.
       #
-      # Uses a claim-by-exact-heartbeat update to handle race conditions: if the
-      # heartbeat was updated between our read and the claim, the update returns
-      # 0 rows and we skip re-enqueueing. Claiming (refreshing the heartbeat)
-      # before enqueueing means a crash mid-recovery leaves the record behind to
-      # go stale and be retried by a later GC pass, instead of losing the request.
-      # The record is only deleted after the job has been enqueued.
+      # The method claims the record with an update that matches its exact
+      # heartbeat, which handles race conditions. If the heartbeat changed
+      # between the read and the claim, the update matches no rows and the
+      # method skips the record. The claim refreshes the heartbeat before the
+      # job is enqueued. If the process crashes during recovery, the record
+      # goes stale again and a later garbage collection pass retries it, so the
+      # request isn't lost. The record is deleted only after the job is
+      # enqueued.
       #
-      # @param record [InflightRequest] the orphaned record
-      # @param threshold [Float] heartbeat threshold (only records below this are orphaned)
-      # @param logger [Logger] logger for output
-      # @return [Boolean] true if successfully re-enqueued
+      # @param record [InflightRequest] The orphaned record.
+      # @param threshold [Time] The heartbeat cutoff. Only records with an
+      #   older heartbeat are orphaned.
+      # @param logger [Logger] The logger for output.
+      # @return [Boolean] `true` if the record was re-enqueued.
       def reenqueue_orphaned_record(record, threshold, logger)
         # Atomically claim only if still orphaned (heartbeat unchanged). The dead
         # process_id is left in place so a failed recovery becomes orphaned again.

data/lib/patient_http/solid_queue/task_monitor_thread.rb

@@ -2,26 +2,27 @@
 
 module PatientHttp
   module SolidQueue
-    # Background thread that maintains heartbeats and performs garbage collection
-    # for in-flight HTTP requests.
+    # Background thread that updates heartbeats for in-flight requests and
+    # re-enqueues orphaned requests.
     class TaskMonitorThread
       include PatientHttp::TimeHelper
 
       # Maximum seconds to sleep between monitor thread checks.
       MAX_MONITOR_SLEEP = 5.0
 
-      # @return [Configuration] the configuration object
+      # @return [Configuration] The gem configuration.
       attr_reader :config
 
-      # @return [TaskMonitor] the inflight request registry
+      # @return [TaskMonitor] The in-flight request registry.
       attr_reader :task_monitor
 
-      # Initialize the monitor thread.
+      # Creates the monitor thread. Call {#start} to run it.
       #
-      # @param config [Configuration] the configuration object
-      # @param task_monitor [TaskMonitor] the inflight request registry
-      # @param tracked_ids_callback [Proc] callback to get the IDs of all requests the
-      #   processors are tracking (queued, pending, and in-flight)
+      # @param config [Configuration] The gem configuration.
+      # @param task_monitor [TaskMonitor] The in-flight request registry.
+      # @param tracked_ids_callback [Proc] A callable that returns the IDs of
+      #   all requests that the processors track, including queued, pending,
+      #   and in-flight requests.
       def initialize(config, task_monitor, tracked_ids_callback)
         @config = config
         @task_monitor = task_monitor
@@ -31,7 +32,7 @@ module PatientHttp
         @stop_signal = Concurrent::Event.new
       end
 
-      # Start the monitor thread.
+      # Starts the thread. Has no effect if the thread is running.
       #
       # @return [void]
       def start
@@ -50,7 +51,8 @@ module PatientHttp
         @thread.name = "async-http-monitor"
       end
 
-      # Stop the monitor thread.
+      # Stops the thread. Waits up to 1 second for the thread to finish, and
+      # then kills it.
       #
       # @return [void]
       def stop
@@ -61,9 +63,9 @@ module PatientHttp
         @thread = nil
       end
 
-      # Check if monitor thread is running.
+      # Returns whether the thread is running.
       #
-      # @return [Boolean]
+      # @return [Boolean] `true` if the thread is running.
       def running?
         @running.true?
       end