activejob-temporal 0.1.0 → 0.2.0

data/lib/activejob/temporal/inspect.rb

@@ -2,13 +2,13 @@
 
 require "temporalio/client/workflow_execution_status"
 require "temporalio/error"
+require_relative "job_id_validation"
 require_relative "visibility_query"
 require_relative "workflow_id_builder"
 
 module ActiveJob
   module Temporal
     module Inspect
-      UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
       JOB_CLASS_NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
       WORKFLOW_STATES = {
         Temporalio::Client::WorkflowExecutionStatus::RUNNING => :running,
@@ -26,7 +26,8 @@ module ActiveJob
           validate_job_id!(job_id)
 
           client = ActiveJob::Temporal.client
-          describe_default_workflow(client, job_class, job_id) ||
+          describe_schedule_execution_workflow(client, job_id) ||
+            describe_default_workflow(client, job_class, job_id) ||
             describe_search_attribute_workflow(client, job_class, job_id)
         rescue ArgumentError
           raise
@@ -40,7 +41,9 @@ module ActiveJob
         def completed?(job_class, job_id) = workflow_state?(job_class, job_id, :completed)
 
         def failed?(job_class, job_id) = workflow_state?(job_class, job_id, :failed)
+      end
 
+      class << self
         private
 
         def workflow_state?(job_class, job_id, state)
@@ -58,11 +61,7 @@ module ActiveJob
         end
 
         def validate_job_id!(job_id)
-          return if job_id.is_a?(String) && job_id.match?(UUID_REGEX)
-
-          raise ArgumentError,
-                "Invalid job_id format: expected UUID (e.g., '550e8400-e29b-41d4-a716-446655440000'), " \
-                "got: #{job_id.inspect}"
+          JobIdValidation.validate!(job_id)
         end
 
         def describe_default_workflow(client, job_class, job_id)
@@ -73,6 +72,17 @@ module ActiveJob
           nil
         end
 
+        def describe_schedule_execution_workflow(client, job_id)
+          workflow_reference = JobIdValidation.schedule_execution_reference(job_id)
+          return unless workflow_reference
+
+          describe_workflow(client, workflow_reference)
+        rescue StandardError => e
+          raise unless rpc_not_found?(e)
+
+          nil
+        end
+
         def describe_search_attribute_workflow(client, job_class, job_id)
           workflow_reference = find_workflow_reference(client, job_class, job_id)
           return unless workflow_reference

data/lib/activejob/temporal/job_id_validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "workflow_id_builder"
+
+module ActiveJob
+  module Temporal
+    module JobIdValidation
+      MAX_JOB_ID_LENGTH = WorkflowIdBuilder::MAX_WORKFLOW_ID_LENGTH
+      CONTROL_CHARACTER_PATTERN = WorkflowIdBuilder::CONTROL_CHARACTER_PATTERN
+      SCHEDULE_WORKFLOW_ID_PREFIX = "ajschwf:"
+
+      module_function
+
+      def validate!(job_id)
+        unless job_id.is_a?(String)
+          raise ArgumentError, "job_id must be a String, got #{job_id.class}: #{job_id.inspect}"
+        end
+
+        raise ArgumentError, "job_id must be valid UTF-8" unless job_id.valid_encoding?
+        raise ArgumentError, "job_id must not be blank" if job_id.strip.empty?
+
+        if job_id.length > MAX_JOB_ID_LENGTH
+          raise ArgumentError, "job_id maximum length is #{MAX_JOB_ID_LENGTH} characters (got #{job_id.length})"
+        end
+
+        return unless job_id.match?(CONTROL_CHARACTER_PATTERN)
+
+        raise ArgumentError, "job_id control characters are not allowed (got #{job_id.inspect})"
+      end
+
+      def schedule_execution_reference(job_id)
+        return unless job_id.start_with?(SCHEDULE_WORKFLOW_ID_PREFIX)
+
+        workflow_id, separator, run_id = job_id.rpartition(":")
+        return if separator.empty? || workflow_id.empty? || run_id.empty?
+
+        { workflow_id: workflow_id, run_id: run_id }
+      end
+    end
+  end
+end

data/lib/activejob/temporal/job_payload_dependencies.rb

@@ -16,6 +16,7 @@ module ActiveJob
         payload[:dependencies] = dependencies.map { |dependency| enrich_dependency(dependency) }
         policy = job.respond_to?(:temporal_dependency_failure_policy) ? job.temporal_dependency_failure_policy : :fail
         payload[:dependency_failure_policy] = policy.to_s
+        payload[:dependency_wait] = dependency_wait_options(job)
       end
 
       def enrich_dependency(dependency)
@@ -35,6 +36,28 @@ module ActiveJob
         WorkflowIdBuilder.validate!(workflow_id)
         workflow_id
       end
+
+      def dependency_wait_options(job)
+        default_dependency_wait_options.merge(job_dependency_wait_options(job))
+      end
+
+      def default_dependency_wait_options
+        {
+          timeout: @config.dependency_wait_timeout.to_f,
+          initial_interval: @config.dependency_wait_initial_interval.to_f,
+          max_interval: @config.dependency_wait_max_interval.to_f,
+          backoff: @config.dependency_wait_backoff.to_f
+        }
+      end
+
+      def job_dependency_wait_options(job)
+        return {} unless job.respond_to?(:temporal_dependency_wait)
+
+        dependency_wait = job.temporal_dependency_wait
+        return {} unless dependency_wait.is_a?(Hash)
+
+        dependency_wait
+      end
     end
   end
 end

data/lib/activejob/temporal/locales/en.yml

@@ -101,18 +101,30 @@ en:
               not_a_duration: "must be a duration (e.g., 1.day or 6.hours), got: %{value}"
               duration_not_positive: "must be positive (got: %{seconds} seconds). Use values like 1.hour or 7.days"
 
+            dependency_wait_timeout:
+              not_a_duration: "must be a duration (e.g., 10.minutes or 1.day), got: %{value}"
+              duration_not_positive: "must be positive (got: %{seconds} seconds). Use values like 1.minute or 1.day"
+
+            dependency_wait_initial_interval:
+              not_a_duration: "must be a duration (e.g., 5.seconds or 1.minute), got: %{value}"
+              duration_not_positive: "must be positive (got: %{seconds} seconds). Use values like 5.seconds or 1.minute"
+
+            dependency_wait_max_interval:
+              not_a_duration: "must be a duration (e.g., 30.seconds or 5.minutes), got: %{value}"
+              duration_not_positive: "must be positive (got: %{seconds} seconds). Use values like 30.seconds or 5.minutes"
+
             tls_cert_path:
               requires_key_path: "requires tls_key_path so the client certificate and private key rotate together"
               invalid_path: "must be a non-empty file path, got: %{value}"
-              unreadable_path: "must point to a readable, non-symlink file, got: %{value}"
+              unreadable_path: "must resolve to a readable regular file, got: %{value}"
 
             tls_key_path:
               invalid_path: "must be a non-empty file path, got: %{value}"
-              unreadable_path: "must point to a readable, non-symlink file, got: %{value}"
+              unreadable_path: "must resolve to a readable regular file, got: %{value}"
 
             tls_server_root_ca_cert_path:
               invalid_path: "must be a non-empty file path, got: %{value}"
-              unreadable_path: "must point to a readable, non-symlink file, got: %{value}"
+              unreadable_path: "must resolve to a readable regular file, got: %{value}"
 
             tls_domain:
               blank: "must be present when configured"

data/lib/activejob/temporal/metrics_server.rb

@@ -5,18 +5,22 @@ require "socket"
 
 require_relative "connection_worker_pool"
 require_relative "bind_policy"
+require_relative "http_request_failure_handling"
 require_relative "http_line_reader"
 
 module ActiveJob
   module Temporal
     class MetricsServer
       include HttpLineReader
+      include HttpRequestFailureHandling
 
       DEFAULT_BIND_ADDRESS = "127.0.0.1"
       READ_TIMEOUT_SECONDS = 1
       CONTENT_TYPE = "text/plain; version=0.0.4"
       CONNECTION_WORKERS = 4
       CONNECTION_QUEUE_SIZE = 16
+      REQUEST_FAILURE_EVENT = "metrics_request_failed"
+      REQUEST_FAILURE_FORMAT = :text
 
       attr_reader :port, :bind_address
 
@@ -86,25 +90,24 @@ module ActiveJob
           connection_pool.enqueue(server.accept)
         rescue IOError, Errno::EBADF
           break
+        rescue SystemCallError => e
+          # Transient accept failures (fd exhaustion, aborted connections) must not kill the listener.
+          ActiveJob::Temporal::Logger.error(
+            "metrics_accept_failed", error_class: e.class.name, message: e.message.to_s
+          )
+          sleep 0.05
         end
       ensure
         @mutex.synchronize { @running = false if @server }
       end
 
-      def serve_client(client)
-        handle_client(client)
-      rescue IOError, SystemCallError
-        nil
-      ensure
-        client&.close
-      end
-
       def handle_client(client)
-        request_line = read_line(client)
+        deadline = request_deadline
+        request_line = read_line(client, deadline)
         return unless request_line
 
         method, path = request_line.split.first(2)
-        drain_headers(client)
+        drain_headers(client, deadline)
 
         unless method && path
           write_text(client, 400, "bad_request\n")
@@ -121,13 +124,6 @@ module ActiveJob
         end
       end
 
-      def drain_headers(client)
-        loop do
-          line = read_line(client)
-          break if line.nil? || line == "\r\n" || line == "\n"
-        end
-      end
-
       def write_text(client, status, payload, body: true)
         response = "HTTP/1.1 #{status} #{reason_phrase(status)}\r\n"
         response << "Content-Type: #{CONTENT_TYPE}\r\n"
@@ -142,7 +138,8 @@ module ActiveJob
           200 => "OK",
           400 => "Bad Request",
           404 => "Not Found",
-          405 => "Method Not Allowed"
+          405 => "Method Not Allowed",
+          500 => "Internal Server Error"
         }.fetch(status)
       end
     end

data/lib/activejob/temporal/middleware/chain.rb

@@ -16,6 +16,13 @@ module ActiveJob
           entries.each { |entry| add(entry) }
         end
 
+        def initialize_copy(original)
+          super
+          @entries = original.instance_variable_get(:@entries).dup
+          @entry_indexes_by_key = original.instance_variable_get(:@entry_indexes_by_key).dup
+          @compiled_call_chain = compile_call_chain
+        end
+
         def add(middleware, *args, **kwargs, &block)
           key = entry_key(middleware, args, kwargs, block)
           callable = build_callable(middleware, args, kwargs, block)

data/lib/activejob/temporal/observability.rb

@@ -164,6 +164,13 @@ module ActiveJob
 
         def initialize
           @adapters = []
+          @stop_replaced_adapters = true
+        end
+
+        def initialize_copy(original)
+          super
+          @adapters = original.adapters.dup
+          @stop_replaced_adapters = false
         end
 
         def use(name, **)
@@ -185,7 +192,7 @@ module ActiveJob
         end
 
         def reset!
-          adapters.each(&:stop!)
+          adapters.each(&:stop!) if @stop_replaced_adapters
           adapters.clear
         end
 
@@ -193,11 +200,16 @@ module ActiveJob
           adapters.each(&:validate!)
         end
 
+        def finalize_configuration_copy!
+          @stop_replaced_adapters = true
+          self
+        end
+
         private
 
         def replace_adapter(adapter)
           previous_adapter = self.adapter(adapter.name)
-          previous_adapter&.stop!
+          previous_adapter&.stop! if @stop_replaced_adapters
           adapters.delete(previous_adapter)
           adapters << adapter
         end

data/lib/activejob/temporal/payload.rb

@@ -38,7 +38,10 @@ module ActiveJob
     #     job_class: "MyJob",
     #     job_id: "abc-123",
     #     queue_name: "default",
-    #     arguments: [{"_aj_serialized"=>"ActiveJob::Serializers::ObjectSerializer", ...}],
+    #     active_job: {
+    #       "arguments" => [{"_aj_serialized"=>"ActiveJob::Serializers::ObjectSerializer", ...}],
+    #       ...
+    #     },
     #     executions: 0,
     #     exception_executions: {},
     #     scheduled_at: "2025-10-29T12:00:00Z" # optional
@@ -83,7 +86,7 @@ module ActiveJob
       #   - :job_class [String] Fully-qualified job class name
       #   - :job_id [String] Unique job identifier
       #   - :queue_name [String] Target queue name
-      #   - :arguments [Array] Serialized job arguments (via ActiveJob::Arguments)
+      #   - :active_job [Hash] ActiveJob serialized payload, including arguments
       #   - :executions [Integer] Current execution count (default 0)
       #   - :exception_executions [Hash] Exception execution counts (default {})
       #   - :scheduled_at [String] ISO8601 timestamp (optional)
@@ -98,7 +101,7 @@ module ActiveJob
       # @example Basic job payload
       #   job = MyJob.new
       #   payload = Payload.from_job(job)
-      #   # => { job_class: "MyJob", job_id: "...", arguments: [...], ... }
+      #   # => { job_class: "MyJob", job_id: "...", active_job: { "arguments" => [...] }, ... }
       #
       # @example Scheduled job payload
       #   job = MyJob.new
@@ -155,19 +158,25 @@ module ActiveJob
         final_payload = serializer_for(config).dump(payload)
         final_payload[:scheduled_at] = scheduled_timestamp if scheduled_timestamp
         final_payload = encrypt_payload_for_transport(final_payload, encrypt, config, encryption_context)
-        final_payload = offload_payload_for_transport(final_payload, storage_metadata, config) if offload
-        enforce_size!(final_payload, metrics_payload: payload, config: config) if enforce_size
-        final_payload
+        finalize_transport_payload(
+          final_payload,
+          metrics_payload: payload,
+          config: config,
+          offload: offload ? storage_metadata || {} : nil,
+          enforce_size: enforce_size
+        )
       end
 
       # Deserializes job arguments from a payload hash.
       #
-      # Extracts the serialized arguments array from the payload and uses
-      # ActiveJob's built-in deserialization to reconstruct Ruby objects
+      # Extracts the serialized arguments array from ActiveJob's canonical
+      # serialized job data, falling back to legacy top-level arguments, then
+      # uses ActiveJob's built-in deserialization to reconstruct Ruby objects
       # (including GlobalID references to ActiveRecord models).
       #
-      # @param payload [Hash] Payload hash containing serialized arguments
-      # @option payload [Array] :arguments Serialized arguments (required)
+      # @param payload [Hash] Payload hash containing serialized ActiveJob data
+      # @option payload [Hash] :active_job Full ActiveJob serialized payload
+      # @option payload [Array] :arguments Legacy serialized arguments
       #
       # @return [Array] Deserialized arguments array ready for job.perform(*args)
       #
@@ -175,13 +184,13 @@ module ActiveJob
       # @raise [GlobalID::RecordNotFound] if a GlobalID reference points to a deleted record
       #
       # @example Deserialize arguments
-      #   payload = { arguments: [{"_aj_serialized"=>"..."}] }
+      #   payload = { active_job: { "arguments" => [{"_aj_serialized"=>"..."}] } }
       #   args = Payload.deserialize_args(payload)
       #   # => [actual_ruby_object]
       #
       # @example GlobalID deserialization with deleted record
       #   begin
-      #     payload = { arguments: [{"_aj_globalid"=>"gid://app/User/999"}] }
+      #     payload = { active_job: { "arguments" => [{"_aj_globalid"=>"gid://app/User/999"}] } }
       #     args = Payload.deserialize_args(payload)
       #   rescue ActiveRecord::RecordNotFound => e
       #     # Record was deleted between enqueue and execution
@@ -192,7 +201,7 @@ module ActiveJob
       end
 
       def deserialize_payload_args(payload)
-        serialized_args = payload[:arguments] || payload["arguments"]
+        serialized_args = active_job_arguments(payload) || payload[:arguments] || payload["arguments"]
         ActiveJob::Arguments.deserialize(serialized_args)
       rescue ActiveJob::SerializationError, ActiveJob::Temporal::ConfigurationError
         raise
@@ -216,12 +225,13 @@ module ActiveJob
         encrypt_payload_if_configured(payload, config, encryption_context: encryption_context)
       end
 
-      def offload_payload(payload, metadata:, config: ActiveJob::Temporal.config)
+      def offload_payload(payload, metadata:, config: ActiveJob::Temporal.config, byte_size: nil)
         PayloadStorage.offload_if_needed(
           payload,
           config: config,
           metadata: metadata,
-          workflow_control_fields: WORKFLOW_CONTROL_FIELDS
+          workflow_control_fields: WORKFLOW_CONTROL_FIELDS,
+          byte_size: byte_size
         )
       end
 
@@ -229,19 +239,19 @@ module ActiveJob
         PayloadStorage.delete(payload, config: config)
       end
 
-      def enforce_size!(payload, metrics_payload: payload, config: ActiveJob::Temporal.config)
-        json = JSON.generate(payload)
+      def enforce_size!(payload, metrics_payload: payload, config: ActiveJob::Temporal.config, byte_size: nil)
+        bytes = byte_size || JSON.generate(payload).bytesize
         max_size_kb = config.max_payload_size_kb || 250
         size_limit_bytes = max_size_kb * 1024
-        actual_size_kb = json.bytesize / 1024.0
-        usage_ratio = json.bytesize.to_f / size_limit_bytes
+        actual_size_kb = bytes / 1024.0
+        usage_ratio = bytes.to_f / size_limit_bytes
 
         Observability.emit(
           :payload_serialize,
-          Observability.attributes_from_payload(metrics_payload, bytes: json.bytesize)
+          Observability.attributes_from_payload(metrics_payload, bytes: bytes)
         )
         log_payload_size(metrics_payload, actual_size_kb, max_size_kb, usage_ratio)
-        return if json.bytesize <= size_limit_bytes
+        return if bytes <= size_limit_bytes
 
         message = format(
           "Job payload size (%<actual>.1f KB) exceeds maximum allowed size (%<max>d KB). " \
@@ -262,8 +272,18 @@ module ActiveJob
         encrypt_payload(payload, config: config, encryption_context: encryption_context)
       end
 
-      def offload_payload_for_transport(payload, storage_metadata, config)
-        offload_payload(payload, metadata: storage_metadata || {}, config: config)
+      # One JSON pass feeds both the storage threshold check and the size limit check.
+      def finalize_transport_payload(payload, metrics_payload:, config:, offload:, enforce_size:)
+        return payload unless offload || enforce_size
+
+        byte_size = JSON.generate(payload).bytesize
+        if offload
+          offloaded = offload_payload(payload, metadata: offload, config: config, byte_size: byte_size)
+          byte_size = nil unless offloaded.equal?(payload)
+          payload = offloaded
+        end
+        enforce_size!(payload, metrics_payload: metrics_payload, config: config, byte_size: byte_size) if enforce_size
+        payload
       end
 
       def decrypt_transport_payload(payload, config, encryption_context)
@@ -296,12 +316,24 @@ module ActiveJob
         PayloadSerializers.fetch(config.payload_serializer)
       end
 
-      def serializer_for_transport_payload(payload, _config)
+      def serializer_for_transport_payload(payload, config)
         payload_serializer = payload_serializer_name(payload)
         validate_payload_serializer_version!(payload) if payload_serializer_metadata?(payload)
+        validate_payload_serializer_allowed!(payload_serializer, config)
         PayloadSerializers.fetch(payload_serializer)
       end
 
+      # The payload names its own serializer, so an attacker-supplied workflow input could
+      # otherwise select Marshal (arbitrary code execution) regardless of configuration.
+      def validate_payload_serializer_allowed!(payload_serializer, config)
+        return if PayloadSerializers::DATA_ONLY.include?(payload_serializer)
+        return if payload_serializer == PayloadSerializers.normalize_name(config.payload_serializer)
+
+        raise ActiveJob::SerializationError,
+              "Payload serializer #{payload_serializer.inspect} is not permitted by the configured " \
+              "payload_serializer (#{config.payload_serializer.inspect})"
+      end
+
       def payload_serializer_name(payload)
         serializer_name = payload[:payload_serializer] || payload["payload_serializer"]
         return PayloadSerializers::JSON unless serializer_name
@@ -327,6 +359,13 @@ module ActiveJob
         end
       end
 
+      def active_job_arguments(payload)
+        active_job_payload = payload[:active_job] || payload["active_job"]
+        return unless active_job_payload.respond_to?(:[])
+
+        active_job_payload[:arguments] || active_job_payload["arguments"]
+      end
+
       # Serializes job arguments using ActiveJob's built-in serializer.
       # @api private
       def serialize_arguments(arguments)
@@ -352,12 +391,12 @@ module ActiveJob
           job_class: job.class.name,
           job_id: job.job_id,
           queue_name: job.queue_name,
-          arguments: serialize_arguments(job.arguments || []),
           executions: job.executions || 0,
           exception_executions: job.exception_executions || {}
         }
         active_job_payload = serialized_active_job(job)
         payload[:active_job] = active_job_payload if active_job_payload
+        payload[:arguments] = serialize_arguments(job.arguments || []) unless active_job_payload
         payload
       end
 

data/lib/activejob/temporal/payload_encryption.rb

@@ -32,7 +32,15 @@ module ActiveJob
 
       def decrypt(payload, config, context: nil)
         version = payload[:encrypted_payload_version] || payload["encrypted_payload_version"]
-        return decrypt_legacy(payload, config) if version == LEGACY_VERSION
+        if version == LEGACY_VERSION
+          unless config.allow_legacy_encrypted_payloads
+            raise ActiveJob::SerializationError,
+                  "Version 1 encrypted payloads are rejected; set allow_legacy_encrypted_payloads " \
+                  "to accept payloads enqueued before context-bound encryption"
+          end
+
+          return decrypt_legacy(payload, config)
+        end
         return decrypt_v2(payload, config, context) if version == VERSION
 
         raise ActiveJob::SerializationError, "Unsupported encrypted payload version: #{version.inspect}"

data/lib/activejob/temporal/payload_serializers.rb

@@ -15,6 +15,9 @@ module ActiveJob
       MESSAGE_PACK_ALIAS = :msgpack
       MARSHAL = :marshal
       SUPPORTED = [JSON, MESSAGE_PACK, MESSAGE_PACK_ALIAS, MARSHAL].freeze
+      # Serializers that cannot instantiate arbitrary objects, so a payload may select them
+      # even when the configuration names a different serializer.
+      DATA_ONLY = [JSON, MESSAGE_PACK].freeze
 
       def fetch(name)
         case normalize_name(name)

data/lib/activejob/temporal/payload_storage.rb

@@ -16,9 +16,9 @@ module ActiveJob
         payload[:external_payload] == true || payload["external_payload"] == true
       end
 
-      def offload_if_needed(payload, config:, metadata:, workflow_control_fields:)
+      def offload_if_needed(payload, config:, metadata:, workflow_control_fields:, byte_size: nil)
         return payload unless configured?(config)
-        return payload unless payload_exceeds_threshold?(payload, config)
+        return payload unless payload_exceeds_threshold?(payload, config, byte_size)
 
         reference = dump_payload(payload, config, metadata)
         envelope = {
@@ -62,8 +62,8 @@ module ActiveJob
         !config.payload_storage_adapter.nil? && !config.payload_storage_threshold_kb.nil?
       end
 
-      def payload_exceeds_threshold?(payload, config)
-        JSON.generate(payload).bytesize > (config.payload_storage_threshold_kb * 1024)
+      def payload_exceeds_threshold?(payload, config, byte_size = nil)
+        (byte_size || JSON.generate(payload).bytesize) > (config.payload_storage_threshold_kb * 1024)
       end
 
       def dump_payload(payload, config, metadata)

data/lib/activejob/temporal/rails_environment_loader.rb

@@ -129,14 +129,7 @@ module ActiveJob
         return unless Object.const_defined?(:Rails)
 
         rails = Object.const_get(:Rails)
-        return unless rails.respond_to?(:application) && rails.respond_to?(:env)
-
-        environment = rails.env
-        return unless environment.respond_to?(:development?) && environment.respond_to?(:test?)
-        return unless environment.development? || environment.test?
-
-        application = rails.application
-        application.eager_load! if application.respond_to?(:eager_load!)
+        rails.application.eager_load! if rails.env.development? || rails.env.test?
       end
     end
   end

data/lib/activejob/temporal/reload_signal_queue.rb

@@ -2,38 +2,38 @@
 
 module ActiveJob
   module Temporal
+    # Single-slot signal handoff between a trap handler and the reload thread.
+    #
+    # Backed by Thread::Queue because trap context forbids taking a Mutex.
     class ReloadSignalQueue
-      POLL_INTERVAL_SECONDS = 0.05
-
       def initialize
-        @pending_signal = nil
-        @closed = false
+        @queue = Thread::Queue.new
       end
 
+      # Enqueues a reload signal unless one is already pending or the queue is closed.
+      #
+      # @param signal [String] Signal name
+      # @return [String, nil] The signal when enqueued, nil when coalesced or closed
       def push(signal)
-        return if @closed || @pending_signal
+        return nil if @queue.closed? || !@queue.empty?
 
-        @pending_signal = signal
+        @queue << signal
         signal
+      rescue ClosedQueueError
+        nil
       end
 
+      # Blocks until a signal is pending or the queue is closed.
+      #
+      # @return [String, nil] The pending signal, or nil once closed
       def pop
-        loop do
-          return nil if @closed
-
-          if @pending_signal
-            signal = @pending_signal
-            @pending_signal = nil
-            return signal
-          end
-
-          sleep(POLL_INTERVAL_SECONDS)
-        end
+        @queue.pop
       end
 
+      # @return [void]
       def close
-        @closed = true
-        @pending_signal = nil
+        @queue.clear
+        @queue.close
       end
     end
   end