async-background 0.7.1 → 1.0.0

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Web
+      class Auth
+        def initialize(callable)
+          @callable = callable
+        end
+
+        def authorized?(env)
+          !!@callable.call(env)
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative '../queue/store'
+
+module Async
+  module Background
+    module Web
+      class Configuration
+        DEFAULT_LIST_LIMIT = 50
+        MAX_LIST_LIMIT = 200
+        DEFAULT_COUNTS_TTL = 3.0
+        DEFAULT_POLL_INTERVAL_MS = 2000
+        DEFAULT_STREAM_POLL_SECONDS = 0.5
+        DEFAULT_STREAM_HEARTBEAT_SECONDS = 25.0
+        DEFAULT_STREAM_RETRY_MS = 5000
+        TRANSPORTS = %i[polling sse].freeze
+        DEFAULT_TRANSPORT = :sse
+        DEFAULT_REDACT = ->(args) { args.is_a?(Array) ? args.map { '***' } : args }
+
+        attr_accessor :queue_path,
+                      :auth,
+                      :expose_args,
+                      :redact_args,
+                      :metrics_path,
+                      :total_workers,
+                      :counts_cache_ttl,
+                      :list_limit,
+                      :poll_interval_ms,
+                      :transport,
+                      :stream_poll_seconds,
+                      :stream_heartbeat_seconds,
+                      :stream_retry_ms,
+                      :title,
+                      :mount_path
+
+        def initialize
+          @queue_path = Queue::Store.default_path
+          @auth = nil
+          @expose_args = false
+          @redact_args = DEFAULT_REDACT
+          @metrics_path = nil
+          @total_workers = nil
+          @counts_cache_ttl = DEFAULT_COUNTS_TTL
+          @list_limit = DEFAULT_LIST_LIMIT
+          @poll_interval_ms = DEFAULT_POLL_INTERVAL_MS
+          @transport = DEFAULT_TRANSPORT
+          @stream_poll_seconds = DEFAULT_STREAM_POLL_SECONDS
+          @stream_heartbeat_seconds = DEFAULT_STREAM_HEARTBEAT_SECONDS
+          @stream_retry_ms = DEFAULT_STREAM_RETRY_MS
+          @title = 'Async::Background'
+          @mount_path = ''
+        end
+
+        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!
+          self
+        end
+
+        # Strict request-path parsing. Silently changing a malformed requested
+        # page size to the default makes API clients repeat or skip work.
+        def limit_for(requested)
+          return list_limit if requested.nil? || requested.empty?
+
+          value = Integer(requested, 10)
+          raise RequestError, 'limit must be a positive integer' unless value.positive?
+
+          [value, MAX_LIST_LIMIT].min
+        rescue ArgumentError, TypeError
+          raise RequestError, 'limit must be a positive integer'
+        end
+
+        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!
+          return if mount_path.is_a?(String)
+
+          raise ConfigurationError, 'mount_path must be a String'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Async
+  module Background
+    module Web
+      module Cursor
+        module_function
+
+        def encode_finished(finished_at, id)
+          encode(finished_at, id)
+        end
+
+        def encode_pending(run_at, id)
+          encode(run_at, id)
+        end
+
+        def decode_finished(value)
+          timestamp, id = decode(value)
+          return unless timestamp
+
+          {finished_at: timestamp, id: id}
+        end
+
+        def decode_pending(value)
+          timestamp, id = decode(value)
+          return unless timestamp
+
+          {run_at: timestamp, id: id}
+        end
+
+        def encode(timestamp, id)
+          return if timestamp.nil? || id.nil?
+
+          Base64.urlsafe_encode64("#{Float(timestamp)}:#{Integer(id)}", padding: false)
+        end
+        private_class_method :encode
+
+        def decode(value)
+          return if value.nil? || value.to_s.empty?
+
+          timestamp_raw, id_raw, extra = Base64.urlsafe_decode64(value.to_s).split(':', 3)
+          raise RequestError, 'invalid cursor' if timestamp_raw.nil? || id_raw.nil? || extra
+
+          timestamp = Float(timestamp_raw)
+          id = Integer(id_raw)
+          raise RequestError, 'invalid cursor' unless timestamp.finite? && id.positive?
+
+          [timestamp, id]
+        rescue ArgumentError, TypeError
+          raise RequestError, 'invalid cursor'
+        end
+        private_class_method :decode
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Web
+      class Error < StandardError; end
+      class ConfigurationError < Error; end
+      class NotConfiguredError < Error; end
+      class RequestError < Error; end
+      class UnavailableError < Error; end
+      class ClosedError < Error; end
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Async
+  module Background
+    module Web
+      class EventHub
+        HEARTBEAT_FRAME = ":keepalive\n\n"
+        UNAVAILABLE_FRAME = "event: unavailable\ndata: #{JSON.generate(error: 'unavailable')}\n\n".freeze
+
+        class Subscription
+          def initialize(clock: nil)
+            @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+            @mutex = Mutex.new
+            @condition = ConditionVariable.new
+            @frame = nil
+            @closed = false
+          end
+
+          def publish(frame)
+            @mutex.synchronize do
+              return false if @closed
+
+              @frame = frame
+              @condition.signal
+              true
+            end
+          end
+
+          def pop(timeout:)
+            deadline = @clock.call + timeout
+
+            @mutex.synchronize do
+              while @frame.nil? && !@closed
+                remaining = deadline - @clock.call
+                break if remaining <= 0
+
+                @condition.wait(@mutex, remaining)
+              end
+
+              frame = @frame
+              @frame = nil
+              frame
+            end
+          end
+
+          def close
+            @mutex.synchronize do
+              return if @closed
+
+              @closed = true
+              @condition.broadcast
+            end
+          end
+
+          def closed?
+            @mutex.synchronize { @closed }
+          end
+        end
+
+        def initialize(snapshot, serializer, metrics_reader: nil, poll_seconds:, sleeper: nil)
+          @snapshot = snapshot
+          @serializer = serializer
+          @metrics_reader = metrics_reader
+          @poll_seconds = poll_seconds
+          @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+          @mutex = Mutex.new
+          @condition = ConditionVariable.new
+          @subscribers = {}
+          @closed = false
+          @monitor = nil
+          @last_data_version = nil
+          @unavailable = false
+        end
+
+        def subscribe
+          subscription = Subscription.new
+          frame, data_version = current_overview
+
+          @mutex.synchronize do
+            raise ClosedError, 'event hub is closed' if @closed
+
+            @subscribers[subscription.object_id] = subscription
+            @last_data_version ||= data_version
+            start_monitor_unless_running!
+            @condition.signal
+          end
+
+          [subscription, frame]
+        end
+
+        def unsubscribe(subscription)
+          @mutex.synchronize do
+            @subscribers.delete(subscription.object_id)
+          end
+          subscription.close
+          nil
+        end
+
+        def close
+          monitor = nil
+          subscribers = nil
+
+          @mutex.synchronize do
+            return if @closed
+
+            @closed = true
+            subscribers = @subscribers.values
+            @subscribers.clear
+            monitor = @monitor
+            @condition.broadcast
+          end
+
+          subscribers.each(&:close)
+          monitor&.join(1) unless monitor == Thread.current
+          nil
+        end
+
+        private
+
+        def start_monitor_unless_running!
+          return if @monitor&.alive?
+
+          @monitor = Thread.new { monitor_loop }
+          @monitor.name = 'async-background-web-events' if @monitor.respond_to?(:name=)
+          @monitor.abort_on_exception = false
+        end
+
+        def monitor_loop
+          loop do
+            break unless wait_for_subscribers
+
+            begin
+              detect_change
+            rescue ClosedError, UnavailableError
+              notify_unavailable
+            end
+
+            @sleeper.call(@poll_seconds)
+          end
+        ensure
+          @mutex.synchronize { @monitor = nil if @monitor == Thread.current }
+        end
+
+        def wait_for_subscribers
+          @mutex.synchronize do
+            @condition.wait(@mutex) while !@closed && @subscribers.empty?
+            !@closed
+          end
+        end
+
+        def detect_change
+          version = @snapshot.data_version
+          previous_version = @mutex.synchronize { @last_data_version }
+          if version == previous_version
+            @mutex.synchronize { @unavailable = false }
+            return
+          end
+
+          frame, observed_version = current_overview
+          @mutex.synchronize do
+            @last_data_version = observed_version
+            @unavailable = false
+          end
+          broadcast(frame)
+        end
+
+        def current_overview
+          overview = @snapshot.overview(force: true)
+          metrics = @metrics_reader&.aggregated
+          payload = @serializer.overview(overview, metrics)
+          ["event: overview\ndata: #{JSON.generate(payload)}\n\n", payload.fetch(:data_version)]
+        end
+
+        def notify_unavailable
+          should_broadcast = @mutex.synchronize do
+            next false if @unavailable
+
+            @unavailable = true
+            true
+          end
+          broadcast(UNAVAILABLE_FRAME) if should_broadcast
+        end
+
+        def broadcast(frame)
+          subscribers = @mutex.synchronize { @subscribers.values.dup }
+          subscribers.each { |subscription| subscription.publish(frame) }
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative '../clock'
+require_relative '../metrics'
+
+module Async
+  module Background
+    module Web
+      class MetricsReader
+        include Clock
+
+        DEFAULT_TTL = 1.0
+        EMPTY_WORKERS = [].freeze
+        EMPTY_TOTALS = {
+          total_runs: 0,
+          total_successes: 0,
+          total_failures: 0,
+          total_timeouts: 0,
+          total_skips: 0,
+          active_jobs: 0,
+          last_run_at: 0,
+          last_duration_ms: nil
+        }.freeze
+
+        def initialize(path:, total_workers:, ttl: DEFAULT_TTL)
+          @path = path
+          @total_workers = total_workers
+          @ttl = ttl
+          @mutex = Mutex.new
+          @cache = nil
+          @cached_at = nil
+        end
+
+        def aggregated
+          @mutex.synchronize do
+            now = monotonic_now
+            return @cache if cache_current?(now)
+
+            @cache = read_metrics.freeze
+            @cached_at = now
+            @cache
+          end
+        end
+
+        private
+
+        def cache_current?(now)
+          @cache && @cached_at && (now - @cached_at) < @ttl
+        end
+
+        def read_metrics
+          return unavailable unless Metrics.available? && File.file?(@path)
+
+          workers = Metrics.read_all(total_workers: @total_workers, path: @path)
+          {available: true, workers: workers, totals: aggregate(workers)}
+        rescue StandardError
+          unavailable
+        end
+
+        def unavailable
+          {available: false, workers: EMPTY_WORKERS, totals: EMPTY_TOTALS}
+        end
+
+        def aggregate(workers)
+          totals = {
+            total_runs: 0,
+            total_successes: 0,
+            total_failures: 0,
+            total_timeouts: 0,
+            total_skips: 0,
+            active_jobs: 0,
+            last_run_at: 0,
+            last_duration_ms: nil
+          }
+
+          workers.each do |worker|
+            totals[:total_runs] += worker[:total_runs].to_i
+            totals[:total_successes] += worker[:total_successes].to_i
+            totals[:total_failures] += worker[:total_failures].to_i
+            totals[:total_timeouts] += worker[:total_timeouts].to_i
+            totals[:total_skips] += worker[:total_skips].to_i
+            totals[:active_jobs] += worker[:active_jobs].to_i
+
+            last_run_at = worker[:last_run_at].to_i
+            next unless last_run_at > totals[:last_run_at]
+
+            totals[:last_run_at] = last_run_at
+            totals[:last_duration_ms] = worker[:last_duration_ms]
+          end
+
+          totals.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Web
+      class Request
+        def initialize(env, config)
+          @config = config
+          @params = parse(env['QUERY_STRING'])
+        end
+
+        def limit
+          @config.limit_for(@params['limit'])
+        end
+
+        def finished_cursor
+          Cursor.decode_finished(@params['cursor'])
+        end
+
+        def pending_cursor
+          Cursor.decode_pending(@params['cursor'])
+        end
+
+        private
+
+        def parse(query)
+          return {} if query.nil? || query.empty?
+
+          Rack::Utils.parse_query(query)
+        rescue StandardError
+          raise RequestError, 'invalid query string'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Async
+  module Background
+    module Web
+      module Response
+        module_function
+
+        JSON_TYPE = 'application/json; charset=utf-8'
+        HTML_TYPE = 'text/html; charset=utf-8'
+        TEXT_TYPE = 'text/plain; charset=utf-8'
+        JAVASCRIPT_TYPE = 'application/javascript; charset=utf-8'
+        CSS_TYPE = 'text/css; charset=utf-8'
+        NO_STORE = 'no-store'
+        ASSET_CACHE = 'public, max-age=31536000, immutable'
+
+        UNAUTHORIZED_BODY = 'unauthorized'
+        NOT_FOUND_BODY = 'not found'
+        BAD_REQUEST_BODY = JSON.generate(error: 'invalid_request').freeze
+        UNAVAILABLE_BODY = JSON.generate(error: 'service_unavailable').freeze
+        INTERNAL_ERROR_BODY = JSON.generate(error: 'internal_error').freeze
+        EVENT_STREAM_TYPE = 'text/event-stream; charset=utf-8'
+
+        def sse(body)
+          [200, sse_headers, body]
+        end
+
+        def json(payload, status: 200)
+          [status, no_store_headers(JSON_TYPE), [JSON.generate(payload)]]
+        end
+
+        def html(body)
+          [200, no_store_headers(HTML_TYPE), [body]]
+        end
+
+        def javascript(body)
+          [200, asset_headers(JAVASCRIPT_TYPE), [body]]
+        end
+
+        def stylesheet(body)
+          [200, asset_headers(CSS_TYPE), [body]]
+        end
+
+        def unauthorized
+          [401, no_store_headers(TEXT_TYPE), [UNAUTHORIZED_BODY]]
+        end
+
+        def not_found
+          [404, no_store_headers(TEXT_TYPE), [NOT_FOUND_BODY]]
+        end
+
+        def bad_request(message = nil)
+          body = message.nil? ? BAD_REQUEST_BODY : JSON.generate(error: 'invalid_request', message: message)
+          [400, no_store_headers(JSON_TYPE), [body]]
+        end
+
+        def unavailable
+          [503, no_store_headers(JSON_TYPE), [UNAVAILABLE_BODY]]
+        end
+
+        def internal_error
+          [500, no_store_headers(JSON_TYPE), [INTERNAL_ERROR_BODY]]
+        end
+
+        def no_store_headers(content_type)
+          {'content-type' => content_type, 'cache-control' => NO_STORE}
+        end
+
+        def asset_headers(content_type)
+          {'content-type' => content_type, 'cache-control' => ASSET_CACHE}
+        end
+
+        def sse_headers
+          {
+            'content-type' => EVENT_STREAM_TYPE,
+            'cache-control' => 'no-cache, no-transform',
+            'x-accel-buffering' => 'no'
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Web
+      class Router
+        GET_ROUTES = {
+          '/' => :index,
+          '/assets/app.js' => :javascript,
+          '/assets/app.css' => :stylesheet,
+          '/api/overview' => :overview,
+          '/api/executing' => :executing,
+          '/api/claimed' => :claimed,
+          '/api/done' => :done,
+          '/api/failed' => :failed,
+          '/api/pending' => :pending,
+          '/api/metrics' => :metrics,
+          '/api/config' => :config,
+          '/api/stream' => :stream
+        }.freeze
+
+        def match(env)
+          return unless env['REQUEST_METHOD'] == 'GET'
+
+          GET_ROUTES[env['PATH_INFO'] || '/']
+        end
+      end
+    end
+  end
+end