async-background 1.0.2 → 1.1.1

data/lib/async/background/runtime.rb

@@ -0,0 +1,246 @@
+# 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
+
+      module FiberLocals
+        def current_task
+          fiber_local(CURRENT_TASK_KEY)
+        end
+
+        def current_task=(task)
+          set_fiber_local(CURRENT_TASK_KEY, task)
+        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
+      end
+      extend FiberLocals
+
+      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 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)
+        park_until_ready(scheduler, blocker, waiter, deadline, task) { yield }
+      ensure
+        waiter[:blocker] = nil
+        clear_fiber_local(WAITER_KEY, waiter)
+        task&.exit_block
+      end
+
+      def park_until_ready(scheduler, blocker, waiter, deadline, task)
+        until waiter[:ready] || yield
+          return false if wait_for_blocker(scheduler, blocker, deadline) == :expired
+
+          task&.raise_if_cancelled!
+        end
+        true
+      end
+
+      def wait_for_blocker(scheduler, blocker, deadline)
+        return scheduler.block(blocker, nil) unless deadline
+
+        remaining = deadline - monotonic_now
+        return :expired if remaining <= 0
+
+        scheduler.block(blocker, remaining)
+      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
+
+      attr_writer :error_handler
+      attr_reader :error_handler
+      module_function :error_handler=, :error_handler
+
+      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 with_timeout(duration, on_timeout: UNSET, &block)
+        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, &block)
+        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 yield 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 = yield }
+        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 = yield
+          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 = yield
+          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.1'
   end
 end

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

@@ -32,6 +32,23 @@ module Async
 
         private
 
+        LIST_ROUTES = {
+          executing: [:executing, :executing, nil].freeze,
+          claimed: [:claimed, :claimed, nil].freeze,
+          done: %i[recent_done done finished_cursor].freeze,
+          failed: %i[recent_failed failed finished_cursor].freeze,
+          pending: %i[pending pending pending_cursor].freeze
+        }.freeze
+        STATIC_ROUTES = {
+          index: :index_response,
+          javascript: :javascript_response,
+          stylesheet: :stylesheet_response,
+          overview: :overview_response,
+          metrics: :metrics_response,
+          config: :config_response,
+          stream: :stream_response
+        }.freeze
+
         def handle(env, head:)
           return Response.unauthorized unless @auth.authorized?(env)
 
@@ -43,15 +60,15 @@ module Async
           end
 
           dispatch(route, env)
-        rescue RequestError => error
-          Response.bad_request(error.message)
+        rescue RequestError => e
+          Response.bad_request(e.message)
         rescue UnavailableError, ClosedError
           Response.unavailable
-        rescue StandardError => error
+        rescue StandardError => e
           # Do not turn internal class names, paths or database errors into an
           # unauthenticated information disclosure channel — but do surface
           # them to the operator via the configured logger.
-          log_internal_error(env, error)
+          log_internal_error(env, e)
           Response.internal_error
         end
 
@@ -68,51 +85,37 @@ module Async
         end
 
         def dispatch(route, env)
-          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
-          else Response.not_found
-          end
-        end
+          return list_response(route, env) if LIST_ROUTES.key?(route)
 
-        def overview_response
-          Response.json(@serializer.overview(@snapshot.overview, metrics_payload))
+          handler = STATIC_ROUTES[route]
+          handler ? send(handler) : Response.not_found
         end
 
-        def in_flight_response(kind, env)
-          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 index_response = Response.html(Assets.render_index(@config))
+
+        def javascript_response = Response.javascript(Assets::JS)
 
-        def terminal_response(kind, env)
+        def stylesheet_response = Response.stylesheet(Assets::CSS)
+
+        def list_response(route, env)
+          reader, shape, cursor_kind = LIST_ROUTES.fetch(route)
           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
@@ -148,7 +151,7 @@ module Async
 
         def log_internal_error(env, error)
           @logger&.error(
-            "[async-background-web] internal error on " \
+            '[async-background-web] internal error on ' \
             "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}: " \
             "#{error.class}: #{error.message}"
           )

data/lib/async/background/web/assets/app.css

@@ -0,0 +1,174 @@
+:root {
+  --bg: #0f1115;
+  --panel: #161a20;
+  --panel-soft: #1c2128;
+  --border: #2a313b;
+  --text: #e6e8ec;
+  --text-dim: #98a2b3;
+  --accent: #4f8ef7;
+  --green: #4ade80;
+  --amber: #fbbf24;
+  --red: #f87171;
+  --blue: #60a5fa;
+  --gray: #94a3b8;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: var(--bg);
+  color: var(--text);
+}
+header {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 14px 24px;
+  border-bottom: 1px solid var(--border);
+  background: var(--panel);
+}
+header h1 { font-size: 16px; margin: 0; font-weight: 600; }
+header .meta { color: var(--text-dim); font-size: 12px; }
+header .status-dot {
+  width: 8px; height: 8px; border-radius: 50%;
+  background: var(--gray);
+  display: inline-block; margin-right: 6px;
+}
+header .status-dot.ok { background: var(--green); }
+header .status-dot.stale { background: var(--amber); }
+header .status-dot.error { background: var(--red); }
+main { padding: 16px 24px; }
+.counts {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 12px;
+  margin-bottom: 20px;
+}
+.count-card {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 12px 14px;
+}
+.count-card .label { color: var(--text-dim); font-size: 11px; text-transform: uppercase; letter-spacing: .04em; }
+.count-card .value { font-size: 24px; font-weight: 600; margin-top: 4px; font-variant-numeric: tabular-nums; }
+.count-card.executing .value { color: var(--blue); }
+.count-card.claimed .value { color: var(--amber); }
+.count-card.pending .value { color: var(--text); }
+.count-card.done .value { color: var(--green); }
+.count-card.failed .value { color: var(--red); }
+.totals {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 12px;
+  margin-bottom: 20px;
+}
+.total-card {
+  background: var(--panel-soft);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 10px 12px;
+}
+.total-card .label { color: var(--text-dim); font-size: 11px; }
+.total-card .value { font-variant-numeric: tabular-nums; font-size: 18px; margin-top: 2px; }
+nav.tabs {
+  display: flex;
+  gap: 2px;
+  border-bottom: 1px solid var(--border);
+  margin-bottom: 12px;
+  flex-wrap: wrap;
+}
+nav.tabs button {
+  background: transparent;
+  color: var(--text-dim);
+  border: none;
+  border-bottom: 2px solid transparent;
+  padding: 10px 14px;
+  font: inherit;
+  cursor: pointer;
+  border-radius: 0;
+}
+nav.tabs button:hover { color: var(--text); }
+nav.tabs button.active {
+  color: var(--text);
+  border-bottom-color: var(--accent);
+}
+nav.tabs button .badge {
+  display: inline-block;
+  background: var(--panel-soft);
+  color: var(--text-dim);
+  border-radius: 10px;
+  padding: 1px 8px;
+  font-size: 11px;
+  margin-left: 6px;
+  font-variant-numeric: tabular-nums;
+}
+table {
+  width: 100%;
+  border-collapse: collapse;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+th, td {
+  text-align: left;
+  padding: 9px 12px;
+  border-bottom: 1px solid var(--border);
+  vertical-align: top;
+  font-variant-numeric: tabular-nums;
+}
+tbody tr:last-child td { border-bottom: none; }
+th {
+  background: var(--panel-soft);
+  color: var(--text-dim);
+  font-weight: 500;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: .04em;
+}
+td.dim { color: var(--text-dim); }
+td.mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+.empty {
+  padding: 32px;
+  text-align: center;
+  color: var(--text-dim);
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+.pagination {
+  display: flex;
+  gap: 8px;
+  margin-top: 12px;
+}
+button.btn {
+  background: var(--panel-soft);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 6px 12px;
+  font: inherit;
+  cursor: pointer;
+}
+button.btn:hover { border-color: var(--accent); }
+button.btn:disabled { opacity: .4; cursor: not-allowed; }
+.err-msg {
+  color: var(--red);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  max-width: 480px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.err-class { color: var(--amber); font-weight: 600; }
+.args-cell pre {
+  margin: 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  color: var(--text-dim);
+  white-space: pre-wrap;
+  word-break: break-all;
+  max-width: 380px;
+}
+.args-redacted { color: var(--text-dim); font-style: italic; }