async-background 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1da83cfa99bb2a77a32b8bd72dd5bee692f94f87b453706f4443cc015e065ac4
-  data.tar.gz: b0c60214b0e13a7a0c346f5e681d78b1701a7de95e5e816f84193d6593f2c282
+  metadata.gz: d9bd77f8af5601609ef43abb3b108ce225e0b20357e712023e2118a06c7e3496
+  data.tar.gz: a0e71bfec3a834da9d7a2df0fbd161ee42bbedff00ea1e90f62bee89d9c1edb3
 SHA512:
-  metadata.gz: 6cdc11bc1e0bbfb5d76e8d26bb80a71d498c3a04a0fbd1a7e3212640c3f0ae1513fb8bb18784e1dfdd7b96aafc1771ed8cf0db00ac1fedde8e63579943df1e2b
-  data.tar.gz: ed97b4b602abb304db44199247b533d2fce410ab8a3a80182e9a08ac65eff680d0df198f529ef53b87e947ccf8114b4e89e333f5695928fc1b0137b6dff90c53
+  metadata.gz: 3f7d7bd4011648a53092257c35906face2cb05bb46c24233cd9739fd37fa07b19d6476e1ad3a433891abce6146fde4c6fcbaf7fff1a73721fe2fde0dcdde1243
+  data.tar.gz: 25070911a4a50ed9142f582bffe6f385aeb236885e417409324804b1525cdea5e30889dc92d14f15c0480386a790732cf84aab54858d73c1b0177eff65af8f9c

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.1.1
+
+### Changed
+
+- Refactored runner lifecycle and queue execution, runtime task coordination,
+  job option normalization, metrics access, and web request handling into
+  smaller focused components.
+- Moved dashboard HTML, CSS, and JavaScript into separate packaged assets.
+- No public API or queue schema changes are intended.
+
+### Validation
+
+- Full spec suite: 431 examples, 0 failures.
+
 ## 1.1.0
 
 The gem no longer depends on `async`. The same worker runs under any

data/lib/async/background/job.rb

@@ -8,42 +8,81 @@ module Async
       BACKOFFS        = %i[fixed linear exponential].freeze
       DEFAULT_JITTER_FOR = { fixed: 0.0, linear: 0.0, exponential: 0.5 }.freeze
 
+      NormalizedOptions = Data.define(:timeout, :retries, :retry_delay, :backoff, :attempt, :jitter)
+      private_constant :NormalizedOptions
+
       Options = Data.define(:timeout, :retry, :retry_delay, :backoff, :attempt, :jitter) do
         def initialize(timeout: DEFAULT_TIMEOUT, retry: 0, retry_delay: nil, backoff: :fixed, attempt: nil, jitter: nil)
-          timeout     = Integer(timeout)
-          retries     = Integer(binding.local_variable_get(:retry) || 0)
-          retry_delay = Float(retry_delay) unless retry_delay.nil?
-          backoff     = backoff.to_sym
-          attempt     = Integer(attempt) unless attempt.nil?
-          jitter      = Float(jitter) unless jitter.nil?
-
-          raise ArgumentError, "timeout must be > 0"                        unless timeout.positive?
-          raise ArgumentError, "retry must be >= 0"                         if     retries.negative?
-          raise ArgumentError, "attempt must be >= 0"                       if     attempt && attempt.negative?
-          raise ArgumentError, "backoff must be one of #{BACKOFFS.inspect}" unless BACKOFFS.include?(backoff)
-          if retries.positive?
-            raise ArgumentError, "retry_delay is required when retry > 0" if retry_delay.nil?
-            raise ArgumentError, "retry_delay must be > 0"                unless retry_delay.positive?
-          end
-          raise ArgumentError, "jitter must be in [0, 1]" if jitter && !(0.0..1.0).cover?(jitter)
-
-          super(timeout:, retry: retries, retry_delay:, backoff:, attempt:, jitter:)
+          retries = Integer(binding.local_variable_get(:retry) || 0)
+          settings = NormalizedOptions.new(
+            Integer(timeout), retries, retry_delay.nil? ? nil : Float(retry_delay), backoff.to_sym,
+            attempt.nil? ? nil : Integer(attempt), jitter.nil? ? nil : Float(jitter)
+          )
+          validate_options!(settings)
+          super(timeout: settings.timeout, retry: settings.retries, retry_delay: settings.retry_delay,
+                backoff: settings.backoff, attempt: settings.attempt, jitter: settings.jitter)
         end
 
         def retry?          = self.retry.positive?
         def attempts_made   = attempt || 0
         def next_attempt    = attempts_made + 1
         def with_attempt(n) = with(attempt: Integer(n))
+
         def next_retry_delay(for_attempt = next_attempt, rng: Random)
-          raise ArgumentError, "attempt must be > 0" unless for_attempt.positive?
-          raise ArgumentError, "retry_delay must be configured" if retry_delay.nil?
+          raise ArgumentError, 'attempt must be > 0' unless for_attempt.positive?
+          raise ArgumentError, 'retry_delay must be configured' if retry_delay.nil?
 
-          base = case backoff
-          when :fixed       then retry_delay
-          when :linear      then retry_delay * for_attempt
-          when :exponential then retry_delay * (2**(for_attempt - 1))
-          end
+          apply_jitter(base_retry_delay(for_attempt), rng)
+        end
+
+        private
+
+        def validate_options!(settings)
+          validate_timeout!(settings.timeout)
+          validate_retry_count!(settings.retries)
+          validate_attempt!(settings.attempt)
+          validate_backoff!(settings.backoff)
+          validate_retry_delay!(settings)
+          validate_jitter!(settings.jitter)
+        end
 
+        def validate_timeout!(timeout)
+          raise ArgumentError, 'timeout must be > 0' unless timeout.positive?
+        end
+
+        def validate_retry_count!(retries)
+          raise ArgumentError, 'retry must be >= 0' if retries.negative?
+        end
+
+        def validate_attempt!(attempt)
+          raise ArgumentError, 'attempt must be >= 0' if attempt&.negative?
+        end
+
+        def validate_backoff!(backoff)
+          raise ArgumentError, "backoff must be one of #{BACKOFFS.inspect}" unless BACKOFFS.include?(backoff)
+        end
+
+        def validate_retry_delay!(settings)
+          return unless settings.retries.positive?
+
+          raise ArgumentError, 'retry_delay is required when retry > 0' if settings.retry_delay.nil?
+          raise ArgumentError, 'retry_delay must be > 0' unless settings.retry_delay.positive?
+        end
+
+        def validate_jitter!(jitter)
+          raise ArgumentError, 'jitter must be in [0, 1]' if jitter && !(0.0..1.0).cover?(jitter)
+        end
+
+        def base_retry_delay(for_attempt)
+          multiplier = case backoff
+                       when :fixed then 1
+                       when :linear then for_attempt
+                       when :exponential then 2**(for_attempt - 1)
+                       end
+          retry_delay * multiplier
+        end
+
+        def apply_jitter(base, rng)
           factor = jitter || DEFAULT_JITTER_FOR[backoff]
           factor.zero? ? base : base * (1 + rng.rand * factor)
         end
@@ -56,9 +95,17 @@ module Async
       module ClassMethods
         def perform_now(*args) = new.perform(*args)
 
-        def perform_async(*args, options: EMPTY_OPTIONS)     = Async::Background::Queue.enqueue(self, *args, options: options)
-        def perform_in(delay, *args, options: EMPTY_OPTIONS) = Async::Background::Queue.enqueue_in(delay, self, *args, options: options)
-        def perform_at(time, *args, options: EMPTY_OPTIONS)  = Async::Background::Queue.enqueue_at(time, self, *args, options: options)
+        def perform_async(*args, options: EMPTY_OPTIONS)
+          Async::Background::Queue.enqueue(self, *args, options: options)
+        end
+
+        def perform_in(delay, *args, options: EMPTY_OPTIONS)
+          Async::Background::Queue.enqueue_in(delay, self, *args, options: options)
+        end
+
+        def perform_at(time, *args, options: EMPTY_OPTIONS)
+          Async::Background::Queue.enqueue_at(time, self, *args, options: options)
+        end
 
         def options(**values)
           @options = Options.new(**values).to_h.compact

data/lib/async/background/metrics.rb

@@ -29,53 +29,57 @@ module Async
 
         validate_worker!(worker_index, total_workers)
         initialize_registry!(worker_index, total_workers, shm_path)
-      rescue LoadError => error
-        mark_unavailable!(error)
+      rescue LoadError => e
+        mark_unavailable!(e)
       end
 
       def enabled? = @enabled
 
-      def job_started(_entry)
-        return unless enabled?
+      module JobEvents
+        def job_started(_entry)
+          return unless enabled?
 
-        increment(:total_runs)
-        increment(:active_jobs)
-        set(:last_run_at, Process.clock_gettime(Process::CLOCK_REALTIME).to_i)
-      end
+          increment(:total_runs)
+          increment(:active_jobs)
+          set(:last_run_at, Process.clock_gettime(Process::CLOCK_REALTIME).to_i)
+        end
 
-      def job_succeeded(_entry, duration)
-        return unless enabled?
+        def job_succeeded(_entry, duration)
+          return unless enabled?
 
-        increment(:total_successes)
-        set(:last_duration_ms, duration_to_milliseconds(duration))
-      end
+          increment(:total_successes)
+          set(:last_duration_ms, duration_to_milliseconds(duration))
+        end
 
-      def job_finished(entry, duration)
-        job_succeeded(entry, duration)
-        job_stopped(entry)
-      end
+        def job_finished(entry, duration)
+          job_succeeded(entry, duration)
+          job_stopped(entry)
+        end
 
-      def job_failed(_entry, _error)
-        increment(:total_failures) if enabled?
-      end
+        def job_failed(_entry, _error)
+          increment(:total_failures) if enabled?
+        end
 
-      def job_timed_out(_entry)
-        increment(:total_timeouts) if enabled?
-      end
+        def job_timed_out(_entry)
+          increment(:total_timeouts) if enabled?
+        end
 
-      def job_stopped(_entry)
-        decrement(:active_jobs) if enabled?
-      end
+        def job_stopped(_entry)
+          decrement(:active_jobs) if enabled?
+        end
 
-      def job_skipped(_entry)
-        increment(:total_skips) if enabled?
+        def job_skipped(_entry)
+          increment(:total_skips) if enabled?
+        end
       end
+      private_constant :JobEvents
+      include JobEvents
 
       def values
         enabled? ? registry.values : {}
       end
 
-      class << self
+      module Reader
         def available?
           load_utilization!
           true
@@ -138,6 +142,8 @@ module Async
         end
       end
 
+      extend Reader
+
       private
 
       def initialize_registry!(worker_index, total_workers, path)
@@ -145,9 +151,7 @@ module Async
         ensure_shm!(total_workers, path)
 
         @registry = ::Async::Utilization::Registry.new
-        unless @registry.respond_to?(:metric)
-          raise LoadError, 'async-utilization >= 0.3 is required for metrics'
-        end
+        raise LoadError, 'async-utilization >= 0.3 is required for metrics' unless @registry.respond_to?(:metric)
 
         attach_observer!(worker_index, path)
         @metric_handles = SCHEMA_FIELDS.keys.to_h { |name| [name, @registry.metric(name)] }.freeze
@@ -196,7 +200,11 @@ module Async
           file.flock(File::LOCK_EX)
           file.truncate(mapped_size) if file.size < mapped_size
         ensure
-          file.flock(File::LOCK_UN) rescue nil
+          begin
+            file.flock(File::LOCK_UN)
+          rescue StandardError
+            nil
+          end
         end
       end
 

data/lib/async/background/min_heap.rb

@@ -41,7 +41,7 @@ module Async
       private
 
       def sift_up(i)
-        while i > 0
+        while i.positive?
           parent = (i - 1) >> 1
           break if @data[parent].next_run_at <= @data[i].next_run_at
 
@@ -50,20 +50,24 @@ module Async
         end
       end
 
-      def sift_down(i)
-        while true
-          smallest = i
-          left  = (i << 1) + 1
-          right = left + 1
+      def sift_down(index)
+        loop do
+          child = smallest_child(index)
+          break if child == index
 
-          smallest = left  if left < @data.size && @data[left].next_run_at < @data[smallest].next_run_at
-          smallest = right if right < @data.size && @data[right].next_run_at < @data[smallest].next_run_at
+          swap(index, child)
+          index = child
+        end
+      end
 
-          break if smallest == i
+      def smallest_child(index)
+        left = (index << 1) + 1
+        right = left + 1
+        smallest = index
 
-          swap(i, smallest)
-          i = smallest
-        end
+        smallest = left if left < @data.size && @data[left].next_run_at < @data[smallest].next_run_at
+        smallest = right if right < @data.size && @data[right].next_run_at < @data[smallest].next_run_at
+        smallest
       end
 
       def swap(a, b)

data/lib/async/background/queue/client.rb

@@ -43,17 +43,20 @@ module Async
 
         def enqueue(job_class, *args, options: EMPTY_OPTIONS)
           ensure_configured!
-          default_client.push(resolve_class_name(job_class), normalized_args(args), nil, options: build_options(job_class, options))
+          default_client.push(resolve_class_name(job_class), normalized_args(args), nil,
+                              options: build_options(job_class, options))
         end
 
         def enqueue_in(delay, job_class, *args, options: EMPTY_OPTIONS)
           ensure_configured!
-          default_client.push_in(delay, resolve_class_name(job_class), normalized_args(args), options: build_options(job_class, options))
+          default_client.push_in(delay, resolve_class_name(job_class), normalized_args(args),
+                                 options: build_options(job_class, options))
         end
 
         def enqueue_at(time, job_class, *args, options: EMPTY_OPTIONS)
           ensure_configured!
-          default_client.push_at(time, resolve_class_name(job_class), normalized_args(args), options: build_options(job_class, options))
+          default_client.push_at(time, resolve_class_name(job_class), normalized_args(args),
+                                 options: build_options(job_class, options))
         end
 
         private
@@ -79,7 +82,7 @@ module Async
         end
 
         def ensure_configured!
-          raise "Async::Background::Queue not configured" unless default_client
+          raise 'Async::Background::Queue not configured' unless default_client
         end
 
         def normalized_args(args) = args.empty? ? EMPTY_ARGS : args
@@ -95,10 +98,10 @@ module Async
           return EMPTY_OPTIONS unless job_class.respond_to?(:resolve_options)
 
           options = if job_class.respond_to?(:queue_options)
-            job_class.queue_options
-          else
-            job_class.resolve_options
-          end
+                      job_class.queue_options
+                    else
+                      job_class.resolve_options
+                    end
 
           options.empty? ? EMPTY_OPTIONS : options
         end

data/lib/async/background/queue/options.rb

@@ -6,9 +6,9 @@ module Async
       EMPTY_ARGS = [].freeze
       EMPTY_OPTIONS = {}.freeze
 
-      SYNCHRONOUS_LEVELS = {normal: 'NORMAL', full: 'FULL', extra: 'EXTRA'}.freeze
+      SYNCHRONOUS_LEVELS = { normal: 'NORMAL', full: 'FULL', extra: 'EXTRA' }.freeze
       WAL_AUTOCHECKPOINT_RANGE = 100..10_000
-      DEFAULT_STORE_OPTIONS = {mmap: true, synchronous: :normal, wal_autocheckpoint: 1_000}.freeze
+      DEFAULT_STORE_OPTIONS = { mmap: true, synchronous: :normal, wal_autocheckpoint: 1_000 }.freeze
       DEFAULTS = DEFAULT_STORE_OPTIONS
       MMAP_SIZE = 268_435_456
 
@@ -45,7 +45,7 @@ module Async
         private
 
         def validate_mmap!(value)
-          return if value == true || value == false
+          return if [true, false].include?(value)
 
           raise ArgumentError, "mmap must be true or false, got #{value.inspect}"
         end

data/lib/async/background/queue/schema.rb

@@ -156,7 +156,11 @@ module Async
           db.execute(SQL::COMMIT)
           result
         rescue StandardError
-          db.execute(SQL::ROLLBACK) rescue nil
+          begin
+            db.execute(SQL::ROLLBACK)
+          rescue StandardError
+            nil
+          end
           raise
         end
       end

data/lib/async/background/queue/socket_notifier.rb

@@ -19,7 +19,7 @@ module Async
         ].freeze
 
         DEAD_WORKER_TTL = 5.0
-        WAKE_BYTE = "\x01".freeze
+        WAKE_BYTE = "\x01"
 
         def initialize(socket_dir:, total_workers:)
           @socket_dir = socket_dir
@@ -64,7 +64,11 @@ module Async
           begin
             socket.write_nonblock(WAKE_BYTE)
           ensure
-            socket.close rescue nil
+            begin
+              socket.close
+            rescue StandardError
+              nil
+            end
           end
           true
         rescue IO::WaitWritable
@@ -72,9 +76,15 @@ module Async
         rescue *UNAVAILABLE
           mark_dead(index, now)
           false
-        rescue => e
+        rescue StandardError => e
           mark_dead(index, now)
-          Console.logger.warn(self) { "SocketNotifier#notify_one(#{index + 1}) failed: #{e.class} #{e.message}" } rescue nil
+          begin
+            Console.logger.warn(self) do
+              "SocketNotifier#notify_one(#{index + 1}) failed: #{e.class} #{e.message}"
+            end
+          rescue StandardError
+            nil
+          end
           false
         end
 

data/lib/async/background/queue/socket_waker.rb

@@ -54,10 +54,18 @@ module Async
           hang_up_clients
           stop_clients
 
-          @server&.close rescue nil
+          begin
+            @server&.close
+          rescue StandardError
+            nil
+          end
           @server = nil
           @accept_task = nil
-          File.unlink(@path) rescue nil
+          begin
+            File.unlink(@path)
+          rescue StandardError
+            nil
+          end
         end
 
         private
@@ -101,7 +109,11 @@ module Async
             Console.logger.warn(self) { "SocketWaker client handler error: #{e.class} #{e.message}" }
           ensure
             @sockets.delete(client)
-            client.close rescue nil
+            begin
+              client.close
+            rescue StandardError
+              nil
+            end
             @notification.signal_all
           end
         end
@@ -119,13 +131,17 @@ module Async
         def wake_accept_loop
           return unless @server
 
-          UNIXSocket.open(@path) { |s| s.write_nonblock("\x00") rescue nil }
+          UNIXSocket.open(@path) do |s|
+            s.write_nonblock("\x00")
+          rescue StandardError
+            nil
+          end
         rescue StandardError
           nil
         end
 
         def hang_up_clients
-          @sockets.keys.each do |socket|
+          @sockets.each_key do |socket|
             socket.close
           rescue StandardError
             nil
@@ -166,11 +182,15 @@ module Async
           return unless File.exist?(@path)
 
           begin
-            UNIXSocket.open(@path) { |s| s.close }
+            UNIXSocket.open(@path, &:close)
 
             raise "Socket #{@path} is already in use by another process (worker_index conflict?)"
           rescue Errno::ECONNREFUSED, Errno::ENOENT
-            File.unlink(@path) rescue nil
+            begin
+              File.unlink(@path)
+            rescue StandardError
+              nil
+            end
           end
         end