async-background 0.7.2 → 1.0.1

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Web
+      class Auth
+        def initialize(callable, logger: nil)
+          @callable = callable
+          @logger = logger
+        end
+
+        def authorized?(env)
+          !!@callable.call(env)
+        rescue StandardError => error
+          @logger&.warn(
+            "[async-background-web] auth callable raised: " \
+            "#{error.class}: #{error.message}"
+          )
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,172 @@
+# 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,
+                      :logger
+
+        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 = ''
+          @logger = nil
+        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!
+          validate_logger!
+          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!
+          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
+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,71 @@
+# 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
+
+        def initialize(snapshot, serializer, metrics_reader: nil)
+          @snapshot = snapshot
+          @serializer = serializer
+          @metrics_reader = metrics_reader
+          @mutex = Mutex.new
+          @cached_version = nil
+          @cached_frame = nil
+          @closed = false
+        end
+
+        def current_version
+          @mutex.synchronize { raise ClosedError, 'event hub is closed' if @closed }
+          @snapshot.data_version
+        end
+
+        def frame_for(version)
+          @mutex.synchronize do
+            raise ClosedError, 'event hub is closed' if @closed
+            return @cached_frame if @cached_version == version && @cached_frame
+
+            refresh_frame_locked!
+            @cached_frame
+          end
+        end
+
+        def initial_frame
+          @mutex.synchronize do
+            raise ClosedError, 'event hub is closed' if @closed
+
+            refresh_frame_locked!
+            [@cached_version, @cached_frame]
+          end
+        end
+
+        def close
+          @mutex.synchronize do
+            @closed = true
+            @cached_frame = nil
+            @cached_version = nil
+          end
+          self
+        end
+
+        def closed?
+          @mutex.synchronize { @closed }
+        end
+
+        private
+
+        def refresh_frame_locked!
+          overview = @snapshot.overview(force: true)
+          metrics = @metrics_reader&.aggregated
+          payload = @serializer.overview(overview, metrics)
+          @cached_version = payload.fetch(:data_version)
+          @cached_frame = "event: overview\ndata: #{JSON.generate(payload)}\n\n"
+        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,107 @@
+# 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'
+        BASE_SECURITY_HEADERS = {
+          'x-content-type-options' => 'nosniff',
+          'referrer-policy' => 'no-referrer',
+          'cross-origin-resource-policy' => 'same-origin'
+        }.freeze
+
+        HTML_SECURITY_HEADERS = BASE_SECURITY_HEADERS.merge(
+          'x-frame-options' => 'DENY',
+          'content-security-policy' =>
+            "default-src 'none'; " \
+            "script-src 'self'; " \
+            "style-src 'self'; " \
+            "img-src 'self' data:; " \
+            "connect-src 'self'; " \
+            "frame-ancestors 'none'; " \
+            "base-uri 'none'; " \
+            "form-action 'none'"
+        ).freeze
+
+        UNAUTHORIZED_BODY = JSON.generate(error: 'unauthorized').freeze
+        NOT_FOUND_BODY = JSON.generate(error: 'not_found').freeze
+        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, html_headers, [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(JSON_TYPE), [UNAUTHORIZED_BODY]]
+        end
+
+        def not_found
+          [404, no_store_headers(JSON_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}.merge(BASE_SECURITY_HEADERS)
+        end
+
+        def html_headers
+          {'content-type' => HTML_TYPE, 'cache-control' => NO_STORE}.merge(HTML_SECURITY_HEADERS)
+        end
+
+        def asset_headers(content_type)
+          {'content-type' => content_type, 'cache-control' => ASSET_CACHE}.merge(BASE_SECURITY_HEADERS)
+        end
+
+        def sse_headers
+          {
+            'content-type' => EVENT_STREAM_TYPE,
+            'cache-control' => 'no-cache, no-transform',
+            'x-accel-buffering' => 'no'
+          }.merge(BASE_SECURITY_HEADERS)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# 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
+
+        ALLOWED_METHODS = %w[GET HEAD].freeze
+
+        def match(env)
+          return unless ALLOWED_METHODS.include?(env['REQUEST_METHOD'])
+
+          GET_ROUTES[env['PATH_INFO'] || '/']
+        end
+      end
+    end
+  end
+end