async-background 1.0.2 → 1.1.1

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

@@ -11,10 +11,10 @@ module Async
 
         def authorized?(env)
           !!@callable.call(env)
-        rescue StandardError => error
+        rescue StandardError => e
           @logger&.warn(
-            "[async-background-web] auth callable raised: " \
-            "#{error.class}: #{error.message}"
+            '[async-background-web] auth callable raised: ' \
+            "#{e.class}: #{e.message}"
           )
           false
         end

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, lambda { |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

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

@@ -8,50 +8,46 @@ module Async
       module Cursor
         module_function
 
-        def encode_finished(finished_at, id)
-          encode(finished_at, id)
-        end
+        def encode(timestamp, id)
+          return if timestamp.nil? || id.nil?
 
-        def encode_pending(run_at, id)
-          encode(run_at, id)
+          Base64.urlsafe_encode64("#{Float(timestamp)}:#{Integer(id)}", padding: false)
         end
 
-        def decode_finished(value)
-          timestamp, id = decode(value)
-          return unless timestamp
+        def encode_finished(finished_at, id) = encode(finished_at, id)
+        def encode_pending(run_at, id) = encode(run_at, id)
+        def decode_finished(value) = decode_as(:finished_at, value)
+        def decode_pending(value) = decode_as(:run_at, value)
 
-          {finished_at: timestamp, id: id}
-        end
-
-        def decode_pending(value)
+        def decode_as(key, value)
           timestamp, id = decode(value)
           return unless timestamp
 
-          {run_at: timestamp, id: id}
+          { key => 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)
+          decode_fields(Base64.urlsafe_decode64(value.to_s))
+        rescue ArgumentError, TypeError
+          raise RequestError, 'invalid cursor'
+        end
+
+        def decode_fields(payload)
+          timestamp_raw, id_raw, extra = payload.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?
-
+          validate_fields!(timestamp, id)
           [timestamp, id]
-        rescue ArgumentError, TypeError
-          raise RequestError, 'invalid cursor'
         end
-        private_class_method :decode
+
+        def validate_fields!(timestamp, id)
+          raise RequestError, 'invalid cursor' unless timestamp.finite? && id.positive?
+        end
+        private_class_method :decode, :decode_as, :decode_fields, :validate_fields!
       end
     end
   end

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

@@ -20,14 +20,13 @@ module Async
         end
 
         def current_version
-          @mutex.synchronize { raise ClosedError, 'event hub is closed' if @closed }
+          with_open {}
           @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
+          with_open do
+            next @cached_frame if @cached_version == version && @cached_frame
 
             refresh_frame_locked!
             @cached_frame
@@ -35,9 +34,7 @@ module Async
         end
 
         def initial_frame
-          @mutex.synchronize do
-            raise ClosedError, 'event hub is closed' if @closed
-
+          with_open do
             refresh_frame_locked!
             [@cached_version, @cached_frame]
           end
@@ -58,6 +55,14 @@ module Async
 
         private
 
+        def with_open
+          @mutex.synchronize do
+            raise ClosedError, 'event hub is closed' if @closed
+
+            yield
+          end
+        end
+
         def refresh_frame_locked!
           overview = @snapshot.overview(force: true)
           metrics = @metrics_reader&.aggregated

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

@@ -11,16 +11,22 @@ module Async
 
         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
+        SUMMED_FIELDS = %i[
+          total_runs
+          total_successes
+          total_failures
+          total_timeouts
+          total_skips
+          active_jobs
+        ].freeze
+
+        LATEST_FIELD = :last_run_at
+        LATEST_COMPANION = :last_duration_ms
+
+        EMPTY_TOTALS = SUMMED_FIELDS.to_h { |field| [field, 0] }
+                                    .merge(LATEST_FIELD => 0, LATEST_COMPANION => nil).freeze
+
+        UNAVAILABLE = { available: false, workers: EMPTY_WORKERS, totals: EMPTY_TOTALS }.freeze
 
         def initialize(path:, total_workers:, ttl: DEFAULT_TTL)
           @path = path
@@ -52,42 +58,28 @@ module Async
           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)}
+          { available: true, workers: workers, totals: aggregate(workers) }
         rescue StandardError
           unavailable
         end
 
-        def unavailable
-          {available: false, workers: EMPTY_WORKERS, totals: EMPTY_TOTALS}
-        end
+        def unavailable = UNAVAILABLE
 
         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
-          }
+          totals = EMPTY_TOTALS.dup
+          most_recent = 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]
+            SUMMED_FIELDS.each { |field| totals[field] += worker[field].to_i }
+
+            last_run_at = worker[LATEST_FIELD].to_i
+            next unless last_run_at > totals[LATEST_FIELD]
+
+            totals[LATEST_FIELD] = last_run_at
+            most_recent = worker
           end
 
+          totals[LATEST_COMPANION] = most_recent[LATEST_COMPANION] if most_recent
           totals.freeze
         end
       end

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

@@ -13,8 +13,12 @@ module Async
         TEXT_TYPE = 'text/plain; charset=utf-8'
         JAVASCRIPT_TYPE = 'application/javascript; charset=utf-8'
         CSS_TYPE = 'text/css; charset=utf-8'
+        EVENT_STREAM_TYPE = 'text/event-stream; charset=utf-8'
+
         NO_STORE = 'no-store'
         ASSET_CACHE = 'public, max-age=31536000, immutable'
+        SSE_CACHE = 'no-cache, no-transform'
+
         BASE_SECURITY_HEADERS = {
           'x-content-type-options' => 'nosniff',
           'referrer-policy' => 'no-referrer',
@@ -34,73 +38,57 @@ module Async
             "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'
+        ERRORS = {
+          unauthorized: [401, 'unauthorized'],
+          not_found: [404, 'not_found'],
+          bad_request: [400, 'invalid_request'],
+          unavailable: [503, 'service_unavailable'],
+          internal_error: [500, 'internal_error']
+        }.freeze
 
-        def sse(body)
-          [200, sse_headers, body]
-        end
+        ERROR_BODY = ERRORS.to_h { |name, (_, code)| [name, JSON.generate(error: code).freeze] }.freeze
 
-        def json(payload, status: 200)
-          [status, no_store_headers(JSON_TYPE), [JSON.generate(payload)]]
+        def headers(content_type, cache_control, security = BASE_SECURITY_HEADERS)
+          { 'content-type' => content_type, 'cache-control' => cache_control }.merge(security)
         end
 
-        def html(body)
-          [200, html_headers, [body]]
-        end
+        def no_store_headers(content_type) = headers(content_type, NO_STORE)
+        def html_headers = headers(HTML_TYPE, NO_STORE, HTML_SECURITY_HEADERS)
+        def asset_headers(content_type) = headers(content_type, ASSET_CACHE)
 
-        def javascript(body)
-          [200, asset_headers(JAVASCRIPT_TYPE), [body]]
+        def sse_headers
+          {
+            'content-type' => EVENT_STREAM_TYPE,
+            'cache-control' => SSE_CACHE,
+            'x-accel-buffering' => 'no'
+          }.merge(BASE_SECURITY_HEADERS)
         end
 
-        def stylesheet(body)
-          [200, asset_headers(CSS_TYPE), [body]]
-        end
+        def sse(body) = [200, sse_headers, body]
+        def html(body) = [200, html_headers, [body]]
+        def javascript(body) = [200, asset_headers(JAVASCRIPT_TYPE), [body]]
+        def stylesheet(body) = [200, asset_headers(CSS_TYPE), [body]]
 
-        def unauthorized
-          [401, no_store_headers(JSON_TYPE), [UNAUTHORIZED_BODY]]
+        def json(payload, status: 200)
+          [status, no_store_headers(JSON_TYPE), [JSON.generate(payload)]]
         end
 
-        def not_found
-          [404, no_store_headers(JSON_TYPE), [NOT_FOUND_BODY]]
-        end
+        def unauthorized = error_response(:unauthorized)
+        def not_found = error_response(:not_found)
+        def unavailable = error_response(:unavailable)
+        def internal_error = error_response(:internal_error)
 
         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
+          return error_response(:bad_request) if message.nil?
 
-        def asset_headers(content_type)
-          {'content-type' => content_type, 'cache-control' => ASSET_CACHE}.merge(BASE_SECURITY_HEADERS)
+          error_response(:bad_request, JSON.generate(error: 'invalid_request', message: message))
         end
 
-        def sse_headers
-          {
-            'content-type' => EVENT_STREAM_TYPE,
-            'cache-control' => 'no-cache, no-transform',
-            'x-accel-buffering' => 'no'
-          }.merge(BASE_SECURITY_HEADERS)
+        def error_response(name, body = ERROR_BODY.fetch(name))
+          status = ERRORS.fetch(name).first
+          [status, no_store_headers(JSON_TYPE), [body]]
         end
+        private_class_method :error_response
       end
     end
   end

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

@@ -26,97 +26,57 @@ module Async
         end
 
         def executing(rows)
-          rows.map { |row| executing_item(row) }
+          rows.map { |row| item(:executing, row) }
         end
 
         def claimed(rows)
-          rows.map { |row| claimed_item(row) }
+          rows.map { |row| item(:claimed, row) }
         end
 
         def done(rows)
-          page(rows.map { |row| done_item(row) }) { |item| Cursor.encode_finished(item[:finished_at], item[:id]) }
+          page(:done, rows)
         end
 
         def failed(rows)
-          page(rows.map { |row| failed_item(row) }) { |item| Cursor.encode_finished(item[:finished_at], item[:id]) }
+          page(:failed, rows)
         end
 
         def pending(rows)
-          page(rows.map { |row| pending_item(row) }) { |item| Cursor.encode_pending(item[:run_at], item[:id]) }
+          page(:pending, rows)
         end
 
         private
 
-        def page(items)
-          {items: items, next_cursor: items.empty? ? nil : yield(items.last)}
-        end
+        EXTRA_FIELDS = {
+          executing: %i[started_at locked_by locked_at].freeze,
+          claimed: %i[locked_at locked_by].freeze,
+          done: %i[finished_at duration_ms].freeze,
+          failed: %i[finished_at duration_ms last_error_class last_error_message].freeze,
+          pending: %i[created_at run_at].freeze
+        }.freeze
 
-        def executing_item(row)
-          args, args_count = args_for(row[:args_raw])
-          {
-            id: row[:id],
-            class_name: row[:class_name],
-            args: args,
-            args_count: args_count,
-            options: parse_options(row[:options_raw]),
-            started_at: row[:started_at],
-            locked_by: row[:locked_by],
-            locked_at: row[:locked_at]
-          }
-        end
+        CURSOR_KEY = { done: :finished_at, failed: :finished_at, pending: :run_at }.freeze
 
-        def claimed_item(row)
+        def item(kind, row)
           args, args_count = args_for(row[:args_raw])
-          {
-            id: row[:id],
-            class_name: row[:class_name],
-            args: args,
-            args_count: args_count,
-            options: parse_options(row[:options_raw]),
-            locked_at: row[:locked_at],
-            locked_by: row[:locked_by]
-          }
-        end
 
-        def done_item(row)
-          args, args_count = args_for(row[:args_raw])
-          {
+          fields = {
             id: row[:id],
             class_name: row[:class_name],
             args: args,
             args_count: args_count,
-            options: parse_options(row[:options_raw]),
-            finished_at: row[:finished_at],
-            duration_ms: row[:duration_ms]
+            options: parse_options(row[:options_raw])
           }
+          EXTRA_FIELDS.fetch(kind).each { |name| fields[name] = row[name] }
+          fields
         end
 
-        def failed_item(row)
-          args, args_count = args_for(row[:args_raw])
-          {
-            id: row[:id],
-            class_name: row[:class_name],
-            args: args,
-            args_count: args_count,
-            options: parse_options(row[:options_raw]),
-            finished_at: row[:finished_at],
-            duration_ms: row[:duration_ms],
-            last_error_class: row[:last_error_class],
-            last_error_message: row[:last_error_message]
-          }
-        end
+        def page(kind, rows)
+          items = rows.map { |row| item(kind, row) }
+          last = items.last
+          cursor = last && Cursor.encode(last[CURSOR_KEY.fetch(kind)], last[:id])
 
-        def pending_item(row)
-          args, args_count = args_for(row[:args_raw])
-          {
-            id: row[:id],
-            class_name: row[:class_name],
-            args: args,
-            args_count: args_count,
-            options: parse_options(row[:options_raw]),
-            created_at: row[:created_at],
-            run_at: row[:run_at]
-          }
+          { items: items, next_cursor: cursor }
         end
 
         def args_for(raw)