async-background 1.0.2 → 1.1.0

data/lib/async/background/runtime/task_group.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Runtime
+      class TaskGroup
+        attr_accessor :on_release
+
+        def initialize(on_error: UNSET, on_release: nil)
+          @members = {}
+          @drained = Notification.new
+          @on_error = on_error
+          @on_release = on_release
+        end
+
+        def size = @members.size
+        def empty? = @members.empty?
+        def tasks = @members.keys
+
+        def spawn(name: nil, &block)
+          raise ArgumentError, 'block required' unless block
+
+          task = Task.new(name: name, group: self, on_error: @on_error)
+          @members[task] = true
+
+          begin
+            task.start(&block)
+          rescue Exception
+            release(task)
+            raise
+          end
+
+          task
+        end
+
+        def wait(timeout = nil)
+          deadline = Runtime.deadline_for(timeout)
+
+          until @members.empty?
+            raise TimeoutError, 'tasks did not finish in time' unless @drained.wait_until(deadline)
+          end
+
+          true
+        end
+
+        def stop_all(grace = nil)
+          tasks.each do |task|
+            task.stop
+          rescue StandardError
+            nil
+          end
+
+          return @members.empty? if grace.nil?
+
+          begin
+            wait(grace)
+          rescue TimeoutError
+            false
+          end
+        end
+
+        def release(task)
+          return unless @members.delete(task)
+
+          @drained.signal_all if @members.empty?
+          notify_release(task)
+        end
+
+        private
+
+        def notify_release(task)
+          handler = @on_release or return
+
+          handler.call(task)
+        rescue StandardError => error
+          Runtime.report_error(task, error, @on_error)
+        end
+      end
+    end
+  end
+end

data/lib/async/background/runtime.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Async
+  module Background
+    class Error < StandardError; end
+
+    module Runtime
+      class Error < Background::Error; end
+      class SchedulerRequired < Error; end
+      class TimeoutError < Error; end
+      class Cancel < Exception; end
+      class Deadline < Exception; end
+
+      UNSET = Object.new
+
+      CURRENT_TASK_KEY = :async_background_current_task
+      WAITER_KEY = :async_background_waiter
+
+      DEADLINE_MESSAGE = 'execution expired'
+
+      NO_SCHEDULER_MESSAGE = <<~MESSAGE
+        Async::Background requires an active Fiber scheduler.
+
+        Install one in the host process before calling this, for example:
+
+          require "async/background/scheduler"
+          Async::Background::Scheduler.run { runner.run }
+
+        or install one yourself:
+
+          Fiber.set_scheduler(Itsi::Scheduler.new)   # itsi-scheduler
+          Async { runner.run }                       # async / falcon
+      MESSAGE
+
+      MISSING_TIMEOUT_HOOK_WARNING = <<~MESSAGE
+        Async::Background: %s does not implement #timeout_after.
+
+        Falling back to stdlib Timeout, which uses Thread#raise and can deliver
+        the timeout to an unrelated fiber. Job timeouts are therefore not safe
+        on this scheduler. Use a scheduler that implements #timeout_after
+        (async, itsi-scheduler) or run jobs with `timeout: nil`.
+      MESSAGE
+
+      @error_handler = nil
+      @warned_schedulers = {}
+
+      module_function
+
+      def spawn(name: nil, on_error: UNSET, &block)
+        Task.spawn(name: name, on_error: on_error, &block)
+      end
+
+      def scheduler
+        Fiber.scheduler
+      end
+
+      def scheduler!
+        Fiber.scheduler or raise SchedulerRequired, NO_SCHEDULER_MESSAGE
+      end
+
+      def native_timeouts?(target = Fiber.scheduler)
+        !target.nil? && target.respond_to?(:timeout_after)
+      end
+
+      def current_task
+        fiber_local(CURRENT_TASK_KEY)
+      end
+
+      def current_task=(task)
+        set_fiber_local(CURRENT_TASK_KEY, task)
+      end
+
+      def build_waiter(blocker)
+        existing = fiber_local(WAITER_KEY)
+        if existing&.[](:blocker)
+          raise Error, "waiter already parked on #{existing[:blocker].class}; " \
+                       'a fiber may only park in one place at a time'
+        end
+
+        waiter = {
+          fiber: Fiber.current,
+          scheduler: scheduler!,
+          ready: false,
+          queued: false,
+          blocker: blocker
+        }
+        set_fiber_local(WAITER_KEY, waiter)
+        waiter
+      end
+
+      def park(blocker, waiter, deadline = nil)
+        scheduler = waiter[:scheduler]
+        task = current_task
+        task&.enter_block(waiter)
+
+        until waiter[:ready] || yield
+          if deadline
+            remaining = deadline - monotonic_now
+            return false if remaining <= 0
+
+            scheduler.block(blocker, remaining)
+          else
+            scheduler.block(blocker, nil)
+          end
+
+          task&.raise_if_cancelled!
+        end
+
+        true
+      ensure
+        waiter[:blocker] = nil
+        clear_fiber_local(WAITER_KEY, waiter)
+        task&.exit_block
+      end
+
+      def with_waiter(blocker, waiters)
+        waiter = build_waiter(blocker)
+        waiter[:queued] = true
+        waiters << waiter
+        yield waiter
+      ensure
+        waiters.delete(waiter) if waiter[:queued]
+      end
+
+      def wake_dequeued(waiter, blocker)
+        waiter[:queued] = false
+        wake(waiter, blocker)
+      end
+
+      def wake(waiter, blocker)
+        return false if waiter[:ready]
+
+        waiter[:ready] = true
+        fiber = waiter[:fiber]
+        return false unless fiber.alive?
+
+        waiter[:scheduler].unblock(blocker, fiber)
+        true
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def deadline_for(timeout)
+        return nil if timeout.nil?
+
+        seconds = Float(timeout)
+        raise ArgumentError, 'timeout must be non-negative and finite' unless seconds.finite? && seconds >= 0
+
+        monotonic_now + seconds
+      end
+
+      def error_handler=(handler)
+        @error_handler = handler
+      end
+
+      def error_handler
+        @error_handler
+      end
+
+      def with_error_handler(handler)
+        previous = @error_handler
+        @error_handler = handler
+        yield
+      ensure
+        @error_handler = previous
+      end
+
+      def report_error(task, error, handler = UNSET)
+        handler = @error_handler if UNSET.equal?(handler)
+        return false unless handler
+
+        handler.call(task, error)
+        true
+      rescue StandardError
+        false
+      end
+
+      def fiber_local(key)
+        Fiber[key]
+      rescue ArgumentError, FiberError
+        fiber_local_fallback[key]
+      end
+
+      def set_fiber_local(key, value)
+        Fiber[key] = value
+      rescue ArgumentError, FiberError
+        fiber_local_fallback[key] = value
+      end
+
+      def clear_fiber_local(key, expected)
+        current = fiber_local(key)
+        set_fiber_local(key, nil) if current.equal?(expected)
+      end
+
+      def fiber_local_fallback
+        fiber = Fiber.current
+        store = fiber.instance_variable_get(:@async_background_locals)
+        store || fiber.instance_variable_set(:@async_background_locals, {})
+      end
+
+      def with_timeout(duration, on_timeout: UNSET)
+        return yield if duration.nil?
+
+        seconds = Float(duration)
+        raise ArgumentError, 'timeout must be positive and finite' unless seconds.finite? && seconds.positive?
+
+        begin
+          arm_deadline(seconds) { yield }
+        rescue Deadline => e
+          raise TimeoutError, e.message if UNSET.equal?(on_timeout)
+
+          on_timeout
+        end
+      end
+
+      def arm_deadline(seconds, &block)
+        target = scheduler!
+
+        return target.timeout_after(seconds, Deadline, DEADLINE_MESSAGE, &block) if native_timeouts?(target)
+
+        warn_missing_timeout_hook(target)
+        ::Timeout.timeout(seconds, Deadline, DEADLINE_MESSAGE, &block)
+      end
+
+      def warn_missing_timeout_hook(target)
+        key = target.class
+        return if @warned_schedulers[key]
+
+        @warned_schedulers[key] = true
+        warn(format(MISSING_TIMEOUT_HOOK_WARNING, key))
+      end
+    end
+  end
+end
+
+require_relative 'runtime/notification'
+require_relative 'runtime/semaphore'
+require_relative 'runtime/task'
+require_relative 'runtime/task_group'

data/lib/async/background/scheduler.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative 'runtime'
+
+module Async
+  module Background
+    module Scheduler
+      ENV_KEY = 'ASYNC_BACKGROUND_SCHEDULER'
+      THREAD_ENV_KEY = 'ASYNC_BACKGROUND_SCHEDULER_THREAD'
+      KNOWN = %i[async itsi].freeze
+
+      class UnknownScheduler < ArgumentError; end
+      class Unavailable < Background::Error; end
+
+      module_function
+
+      def installed? = !Fiber.scheduler.nil?
+
+      def current
+        return nil unless installed?
+
+        Fiber.scheduler.class.name
+      end
+
+      def preload!(kind = nil)
+        case resolve(kind)
+        when :async then require 'async'
+        when :itsi then require 'itsi/scheduler'
+        end
+        true
+      end
+
+      def run(kind = nil, &block)
+        raise ArgumentError, 'block required' unless block
+        return block.call if installed?
+
+        case resolve(kind)
+        when :async then run_async(&block)
+        when :itsi then run_itsi(&block)
+        end
+      end
+
+      def resolve(kind = nil)
+        name = (kind || ENV.fetch(ENV_KEY, 'auto')).to_s.downcase
+        return name.to_sym if KNOWN.include?(name.to_sym)
+        return detect if name == 'auto'
+
+        raise UnknownScheduler, "unknown scheduler #{name.inspect}, expected one of: #{KNOWN.join(', ')}, auto"
+      end
+
+      def detect
+        return :async if defined?(::Async::Scheduler)
+        return :itsi if defined?(::Itsi::Scheduler)
+
+        return :async if available?('async')
+        return :itsi if available?('itsi/scheduler')
+
+        raise Unavailable, 'no fiber scheduler available: add `async` or `itsi-scheduler` to your bundle'
+      end
+
+      def available?(feature)
+        !Gem.find_files(feature).empty? || !Gem.find_files("#{feature}.rb").empty?
+      rescue StandardError
+        try_require(feature)
+      end
+
+      def try_require(feature)
+        require feature
+        true
+      rescue LoadError
+        false
+      end
+
+      def run_async(&block)
+        require 'async'
+
+        result = nil
+        send(:Async) { result = block.call }
+        result
+      end
+
+      def run_itsi(&block)
+        require 'itsi/scheduler'
+
+        return run_on_thread(::Itsi::Scheduler, &block) if threaded?
+
+        run_on_current_thread(::Itsi::Scheduler.new, &block)
+      end
+
+      def threaded?
+        %w[1 true yes].include?(ENV.fetch(THREAD_ENV_KEY, '').to_s.downcase)
+      end
+
+      def run_on_current_thread(scheduler, &block)
+        result = nil
+        failure = nil
+        finished = false
+
+        previous = Fiber.scheduler
+        Fiber.set_scheduler(scheduler)
+
+        begin
+          Fiber.schedule do
+            result = block.call
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            failure = e
+          ensure
+            finished = true
+          end
+
+          scheduler.run if scheduler.respond_to?(:run)
+        ensure
+          Fiber.set_scheduler(previous)
+        end
+
+        raise failure if failure
+        unless finished
+          raise Unavailable,
+                "#{scheduler.class} did not run the scheduled fiber to completion on close; " \
+                "set #{THREAD_ENV_KEY}=1 to fall back to a dedicated scheduler thread"
+        end
+
+        result
+      end
+
+      def run_on_thread(scheduler_class, &block)
+        result = nil
+        failure = nil
+
+        thread = Thread.new do
+          Fiber.set_scheduler(scheduler_class.new)
+          Fiber.schedule do
+            result = block.call
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            failure = e
+          end
+        end
+        thread.join
+        raise failure if failure
+
+        result
+      end
+    end
+  end
+end

data/lib/async/background/version.rb

@@ -2,6 +2,6 @@
 
 module Async
   module Background
-    VERSION = '1.0.2'
+    VERSION = '1.1.0'
   end
 end

data/lib/async/background/web/app.rb

@@ -32,6 +32,14 @@ module Async
 
         private
 
+        LIST_ROUTES = {
+          executing: [:executing, :executing, nil].freeze,
+          claimed: [:claimed, :claimed, nil].freeze,
+          done: [:recent_done, :done, :finished_cursor].freeze,
+          failed: [:recent_failed, :failed, :finished_cursor].freeze,
+          pending: [:pending, :pending, :pending_cursor].freeze
+        }.freeze
+
         def handle(env, head:)
           return Response.unauthorized unless @auth.authorized?(env)
 
@@ -68,16 +76,13 @@ module Async
         end
 
         def dispatch(route, env)
+          return list_response(route, env) if LIST_ROUTES.key?(route)
+
           case route
           when :index then Response.html(Assets.render_index(@config))
           when :javascript then Response.javascript(Assets::JS)
           when :stylesheet then Response.stylesheet(Assets::CSS)
           when :overview then overview_response
-          when :executing then in_flight_response(:executing, env)
-          when :claimed then in_flight_response(:claimed, env)
-          when :done then terminal_response(:done, env)
-          when :failed then terminal_response(:failed, env)
-          when :pending then pending_response(env)
           when :metrics then metrics_response
           when :config then config_response
           when :stream then stream_response
@@ -85,34 +90,25 @@ module Async
           end
         end
 
-        def overview_response
-          Response.json(@serializer.overview(@snapshot.overview, metrics_payload))
-        end
-
-        def in_flight_response(kind, env)
+        def list_response(route, env)
+          reader, shape, cursor_kind = LIST_ROUTES.fetch(route)
           request = Request.new(env, @config)
-          rows = kind == :executing ? @snapshot.executing(limit: request.limit) : @snapshot.claimed(limit: request.limit)
-          payload = kind == :executing ? @serializer.executing(rows) : @serializer.claimed(rows)
-          Response.json({items: payload})
-        end
 
-        def terminal_response(kind, env)
-          request = Request.new(env, @config)
-          cursor = request.finished_cursor
-          rows = kind == :done ? @snapshot.recent_done(limit: request.limit, cursor: cursor) :
-            @snapshot.recent_failed(limit: request.limit, cursor: cursor)
-          payload = kind == :done ? @serializer.done(rows) : @serializer.failed(rows)
-          Response.json(payload)
+          unless cursor_kind
+            rows = @snapshot.public_send(reader, limit: request.limit)
+            return Response.json({items: @serializer.public_send(shape, rows)})
+          end
+
+          rows = @snapshot.public_send(reader, limit: request.limit, cursor: request.public_send(cursor_kind))
+          Response.json(@serializer.public_send(shape, rows))
         end
 
-        def pending_response(env)
-          request = Request.new(env, @config)
-          rows = @snapshot.pending(limit: request.limit, cursor: request.pending_cursor)
-          Response.json(@serializer.pending(rows))
+        def overview_response
+          Response.json(@serializer.overview(@snapshot.overview, metrics_payload))
         end
 
         def metrics_response
-          Response.json(metrics_payload || {available: false, workers: [], totals: MetricsReader::EMPTY_TOTALS})
+          Response.json(metrics_payload || MetricsReader::UNAVAILABLE)
         end
 
         def metrics_payload

data/lib/async/background/web/configuration.rb

@@ -53,18 +53,47 @@ module Async
           @logger = nil
         end
 
+        RULES = [
+          [:queue_path, ->(value, _) { !value.nil? && !value.to_s.empty? }, 'queue_path must be set'],
+          [:auth, ->(value, _) { !value.nil? }, 'auth must be configured (gem ships no permissive default)'],
+          [:auth, ->(value, _) { value.respond_to?(:call) },
+            'auth must respond to #call(env) and return truthy on success'],
+          [:list_limit, ->(value, _) { value.is_a?(Integer) && value.between?(1, MAX_LIST_LIMIT) },
+            "list_limit must be an Integer between 1 and #{MAX_LIST_LIMIT}"],
+          [:counts_cache_ttl, ->(value, _) { value.is_a?(Numeric) && value >= 0 },
+            'counts_cache_ttl must be a non-negative Numeric'],
+          [:poll_interval_ms, ->(value, _) { value.is_a?(Integer) && value >= 200 },
+            'poll_interval_ms must be an Integer >= 200'],
+          [:transport, ->(value, _) { TRANSPORTS.include?(value) },
+            "transport must be one of #{TRANSPORTS.inspect}"],
+          [:stream_poll_seconds, ->(value, _) { value.is_a?(Numeric) && value >= 0.1 },
+            'stream_poll_seconds must be a Numeric >= 0.1'],
+          [:stream_heartbeat_seconds, ->(value, _) { value.is_a?(Numeric) && value >= 5 },
+            'stream_heartbeat_seconds must be a Numeric >= 5'],
+          [:stream_retry_ms, ->(value, _) { value.is_a?(Integer) && value >= 500 },
+            'stream_retry_ms must be an Integer >= 500'],
+          [:redact_args, ->(value, config) { !config.expose_args || value.nil? || value.respond_to?(:call) },
+            'redact_args must respond to #call(args)'],
+          [:total_workers, ->(value, config) {
+            !config.metrics_enabled? || (value.is_a?(Integer) && value.positive?)
+          }, 'metrics_path requires total_workers to be a positive Integer'],
+          [:mount_path, ->(value, _) { value.is_a?(String) }, 'mount_path must be a String'],
+          [:mount_path, ->(value, _) { value.empty? || value.start_with?('/') },
+            'mount_path must start with "/" or be empty'],
+          [:mount_path, ->(value, _) { value.empty? || !value.end_with?('/') },
+            'mount_path must not end with "/"'],
+          [:mount_path, ->(value, _) { value.empty? || !value.match?(/[[:cntrl:]]/) },
+            'mount_path must not contain control characters'],
+          [:mount_path, ->(value, _) { value.empty? || !value.match?(/\s/) },
+            'mount_path must not contain whitespace'],
+          [:logger, ->(value, _) { value.nil? || (value.respond_to?(:warn) && value.respond_to?(:error)) },
+            'logger must respond to #warn and #error']
+        ].freeze
+
         def validate!
-          validate_queue_path!
-          validate_auth!
-          validate_list_limit!
-          validate_cache_ttl!
-          validate_poll_interval!
-          validate_transport!
-          validate_stream!
-          validate_redactor!
-          validate_metrics!
-          validate_mount_path!
-          validate_logger!
+          RULES.each do |attribute, valid, message|
+            raise ConfigurationError, message unless valid.call(public_send(attribute), self)
+          end
           self
         end
 
@@ -84,88 +113,6 @@ module Async
         def metrics_enabled?
           !metrics_path.nil?
         end
-
-        private
-
-        def validate_queue_path!
-          raise ConfigurationError, 'queue_path must be set' if queue_path.nil? || queue_path.to_s.empty?
-        end
-
-        def validate_auth!
-          raise ConfigurationError, 'auth must be configured (gem ships no permissive default)' if auth.nil?
-
-          return if auth.respond_to?(:call)
-
-          raise ConfigurationError, 'auth must respond to #call(env) and return truthy on success'
-        end
-
-        def validate_list_limit!
-          return if list_limit.is_a?(Integer) && list_limit.between?(1, MAX_LIST_LIMIT)
-
-          raise ConfigurationError, "list_limit must be an Integer between 1 and #{MAX_LIST_LIMIT}"
-        end
-
-        def validate_cache_ttl!
-          return if counts_cache_ttl.is_a?(Numeric) && counts_cache_ttl >= 0
-
-          raise ConfigurationError, 'counts_cache_ttl must be a non-negative Numeric'
-        end
-
-        def validate_poll_interval!
-          return if poll_interval_ms.is_a?(Integer) && poll_interval_ms >= 200
-
-          raise ConfigurationError, 'poll_interval_ms must be an Integer >= 200'
-        end
-
-        def validate_transport!
-          return if TRANSPORTS.include?(transport)
-
-          raise ConfigurationError, "transport must be one of #{TRANSPORTS.inspect}"
-        end
-
-        def validate_stream!
-          unless stream_poll_seconds.is_a?(Numeric) && stream_poll_seconds >= 0.1
-            raise ConfigurationError, 'stream_poll_seconds must be a Numeric >= 0.1'
-          end
-
-          unless stream_heartbeat_seconds.is_a?(Numeric) && stream_heartbeat_seconds >= 5
-            raise ConfigurationError, 'stream_heartbeat_seconds must be a Numeric >= 5'
-          end
-
-          return if stream_retry_ms.is_a?(Integer) && stream_retry_ms >= 500
-
-          raise ConfigurationError, 'stream_retry_ms must be an Integer >= 500'
-        end
-
-        def validate_redactor!
-          return unless expose_args && redact_args && !redact_args.respond_to?(:call)
-
-          raise ConfigurationError, 'redact_args must respond to #call(args)'
-        end
-
-        def validate_metrics!
-          return unless metrics_enabled?
-          return if total_workers.is_a?(Integer) && total_workers.positive?
-
-          raise ConfigurationError, 'metrics_path requires total_workers to be a positive Integer'
-        end
-
-        def validate_mount_path!
-          raise ConfigurationError, 'mount_path must be a String' unless mount_path.is_a?(String)
-          return if mount_path.empty?
-
-          raise ConfigurationError, 'mount_path must start with "/" or be empty' unless mount_path.start_with?('/')
-          raise ConfigurationError, 'mount_path must not end with "/"' if mount_path.end_with?('/')
-          raise ConfigurationError, 'mount_path must not contain control characters' if mount_path.match?(/[[:cntrl:]]/)
-          raise ConfigurationError, 'mount_path must not contain whitespace' if mount_path.match?(/\s/)
-        end
-
-        def validate_logger!
-          return if logger.nil?
-          return if logger.respond_to?(:warn) && logger.respond_to?(:error)
-
-          raise ConfigurationError, 'logger must respond to #warn and #error'
-        end
       end
     end
   end