async-background 1.0.0 → 1.0.2

data/lib/async/background/runner.rb

@@ -47,11 +47,7 @@ module Async
         @total_workers = total_workers
         @running = true
         @shutdown = ::Async::Condition.new
-        @metrics = Metrics.new(
-          worker_index: worker_index,
-          total_workers: total_workers,
-          shm_path: metrics_shm_path
-        )
+        @metrics = Metrics.new(worker_index: worker_index, total_workers: total_workers, shm_path: metrics_shm_path)
         logger.info { "Async::Background worker_index=#{worker_index}/#{total_workers}, job_count=#{job_count}" }
 
         @drain_barrier = ::Async::Barrier.new
@@ -91,7 +87,7 @@ module Async
         # continues independently in its own Async task.
         return shutdown.wait if heap.empty? && @listen_queue
 
-        loop do
+        while running?
           entry = heap.peek
           break unless entry
 
@@ -123,12 +119,7 @@ module Async
       end
 
       def dispatch_entry(entry)
-        if entry.running
-          skip_entry(entry)
-        else
-          execute_entry(entry)
-        end
-
+        entry.running ? skip_entry(entry) : execute_entry(entry)
         entry.reschedule(monotonic_now)
         heap.replace_top(entry)
       end
@@ -182,12 +173,11 @@ module Async
 
       def start_signal_watcher(task)
         task.async(transient: true) do
-          loop do
+          while running?
             @signal_r.wait_readable
             @signal_r.read_nonblock(256) rescue nil
             shutdown.signal
             @queue_waker&.signal
-            break unless running?
           end
         end
       end

data/lib/async/background/version.rb

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

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

@@ -6,7 +6,8 @@ module Async
       class App
         def initialize(config)
           @config = config.validate!
-          @auth = Auth.new(@config.auth)
+          @logger = @config.logger
+          @auth = Auth.new(@config.auth, logger: @logger)
           @snapshot = Snapshot.new(path: @config.queue_path, counts_cache_ttl: @config.counts_cache_ttl).open!
           @metrics_reader = build_metrics_reader
           @serializer = Serializer.new(@config)
@@ -15,30 +16,45 @@ module Async
         end
 
         def call(env)
+          head = env['REQUEST_METHOD'] == 'HEAD'
+          response = handle(env, head: head)
+          return response unless head
+
+          status, headers, _body = response
+          [status, headers, []]
+        end
+
+        def close
+          @event_hub&.close
+          @snapshot.close
+          self
+        end
+
+        private
+
+        def handle(env, head:)
           return Response.unauthorized unless @auth.authorized?(env)
 
           route = @router.match(env)
           return Response.not_found unless route
 
+          if head && route == :stream
+            return @config.transport == :sse ? [200, Response.sse_headers, []] : Response.not_found
+          end
+
           dispatch(route, env)
         rescue RequestError => error
           Response.bad_request(error.message)
         rescue UnavailableError, ClosedError
           Response.unavailable
-        rescue StandardError
+        rescue StandardError => error
           # Do not turn internal class names, paths or database errors into an
-          # unauthenticated information disclosure channel.
+          # unauthenticated information disclosure channel — but do surface
+          # them to the operator via the configured logger.
+          log_internal_error(env, error)
           Response.internal_error
         end
 
-        def close
-          @event_hub&.close
-          @snapshot.close
-          self
-        end
-
-        private
-
         def build_metrics_reader
           return unless @config.metrics_enabled?
 
@@ -48,12 +64,7 @@ module Async
         def build_event_hub
           return unless @config.transport == :sse
 
-          EventHub.new(
-            @snapshot,
-            @serializer,
-            metrics_reader: @metrics_reader,
-            poll_seconds: @config.stream_poll_seconds
-          )
+          EventHub.new(@snapshot, @serializer, metrics_reader: @metrics_reader)
         end
 
         def dispatch(route, env)
@@ -128,10 +139,20 @@ module Async
             Stream.new(
               @event_hub,
               heartbeat_seconds: @config.stream_heartbeat_seconds,
-              retry_ms: @config.stream_retry_ms
+              retry_ms: @config.stream_retry_ms,
+              poll_seconds: @config.stream_poll_seconds,
+              logger: @logger
             )
           )
         end
+
+        def log_internal_error(env, error)
+          @logger&.error(
+            "[async-background-web] internal error on " \
+            "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}: " \
+            "#{error.class}: #{error.message}"
+          )
+        end
       end
     end
   end

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

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

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

@@ -31,7 +31,8 @@ module Async
                       :stream_heartbeat_seconds,
                       :stream_retry_ms,
                       :title,
-                      :mount_path
+                      :mount_path,
+                      :logger
 
         def initialize
           @queue_path = Queue::Store.default_path
@@ -49,6 +50,7 @@ module Async
           @stream_retry_ms = DEFAULT_STREAM_RETRY_MS
           @title = 'Async::Background'
           @mount_path = ''
+          @logger = nil
         end
 
         def validate!
@@ -62,6 +64,7 @@ module Async
           validate_redactor!
           validate_metrics!
           validate_mount_path!
+          validate_logger!
           self
         end
 
@@ -148,9 +151,20 @@ module Async
         end
 
         def validate_mount_path!
-          return if mount_path.is_a?(String)
+          raise ConfigurationError, 'mount_path must be a String' unless mount_path.is_a?(String)
+          return if mount_path.empty?
 
-          raise ConfigurationError, 'mount_path must be a String'
+          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

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

@@ -9,184 +9,61 @@ module Async
         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)
+        def initialize(snapshot, serializer, metrics_reader: 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 = {}
+          @cached_version = nil
+          @cached_frame = nil
           @closed = false
-          @monitor = nil
-          @last_data_version = nil
-          @unavailable = false
         end
 
-        def subscribe
-          subscription = Subscription.new
-          frame, data_version = current_overview
+        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
 
-            @subscribers[subscription.object_id] = subscription
-            @last_data_version ||= data_version
-            start_monitor_unless_running!
-            @condition.signal
+            refresh_frame_locked!
+            @cached_frame
           end
-
-          [subscription, frame]
         end
 
-        def unsubscribe(subscription)
+        def initial_frame
           @mutex.synchronize do
-            @subscribers.delete(subscription.object_id)
+            raise ClosedError, 'event hub is closed' if @closed
+
+            refresh_frame_locked!
+            [@cached_version, @cached_frame]
           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
+            @cached_frame = nil
+            @cached_version = nil
           end
-
-          subscribers.each(&:close)
-          monitor&.join(1) unless monitor == Thread.current
-          nil
+          self
         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
+        def closed?
+          @mutex.synchronize { @closed }
         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
+        private
 
-        def current_overview
+        def refresh_frame_locked!
           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
+          @cached_version = payload.fetch(:data_version)
+          @cached_frame = "event: overview\ndata: #{JSON.generate(payload)}\n\n"
         end
       end
     end

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

@@ -15,9 +15,27 @@ module Async
         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'
+        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
@@ -32,7 +50,7 @@ module Async
         end
 
         def html(body)
-          [200, no_store_headers(HTML_TYPE), [body]]
+          [200, html_headers, [body]]
         end
 
         def javascript(body)
@@ -44,11 +62,11 @@ module Async
         end
 
         def unauthorized
-          [401, no_store_headers(TEXT_TYPE), [UNAUTHORIZED_BODY]]
+          [401, no_store_headers(JSON_TYPE), [UNAUTHORIZED_BODY]]
         end
 
         def not_found
-          [404, no_store_headers(TEXT_TYPE), [NOT_FOUND_BODY]]
+          [404, no_store_headers(JSON_TYPE), [NOT_FOUND_BODY]]
         end
 
         def bad_request(message = nil)
@@ -65,11 +83,15 @@ module Async
         end
 
         def no_store_headers(content_type)
-          {'content-type' => content_type, 'cache-control' => NO_STORE}
+          {'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}
+          {'content-type' => content_type, 'cache-control' => ASSET_CACHE}.merge(BASE_SECURITY_HEADERS)
         end
 
         def sse_headers
@@ -77,7 +99,7 @@ module Async
             'content-type' => EVENT_STREAM_TYPE,
             'cache-control' => 'no-cache, no-transform',
             'x-accel-buffering' => 'no'
-          }
+          }.merge(BASE_SECURITY_HEADERS)
         end
       end
     end

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

@@ -19,8 +19,10 @@ module Async
           '/api/stream' => :stream
         }.freeze
 
+        ALLOWED_METHODS = %w[GET HEAD].freeze
+
         def match(env)
-          return unless env['REQUEST_METHOD'] == 'GET'
+          return unless ALLOWED_METHODS.include?(env['REQUEST_METHOD'])
 
           GET_ROUTES[env['PATH_INFO'] || '/']
         end

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

@@ -1,41 +1,80 @@
 # frozen_string_literal: true
 
+require_relative '../clock'
+
 module Async
   module Background
     module Web
       class Stream
-        def initialize(hub, heartbeat_seconds:, retry_ms:)
+        include Clock
+
+        def initialize(hub, heartbeat_seconds:, retry_ms:, poll_seconds:, logger: nil)
           @hub = hub
           @heartbeat_seconds = heartbeat_seconds
           @retry_ms = retry_ms
+          @poll_seconds = poll_seconds
+          @logger = logger
         end
 
         def each
-          subscription, initial_frame = @hub.subscribe
           yield "retry: #{@retry_ms}\n\n"
-          yield initial_frame
+
+          version, frame = initial_state
+          if version.nil?
+            yield EventHub::UNAVAILABLE_FRAME
+            return
+          end
+
+          yield frame
+          last_yield = monotonic_now
+          unavailable_announced = false
 
           loop do
-            frame = subscription.pop(timeout: @heartbeat_seconds)
-            break if frame.nil? && subscription.closed?
+            sleep_for_poll
+
+            begin
+              new_version = @hub.current_version
 
-            yield(frame || EventHub::HEARTBEAT_FRAME)
+              if new_version != version
+                version = new_version
+                yield @hub.frame_for(version)
+                last_yield = monotonic_now
+              elsif (monotonic_now - last_yield) >= @heartbeat_seconds
+                yield EventHub::HEARTBEAT_FRAME
+                last_yield = monotonic_now
+              end
+
+              unavailable_announced = false
+            rescue ClosedError
+              break
+            rescue UnavailableError
+              unless unavailable_announced
+                yield EventHub::UNAVAILABLE_FRAME
+                unavailable_announced = true
+                last_yield = monotonic_now
+              end
+            end
           end
-        rescue Errno::EPIPE, IOError
+        rescue Errno::EPIPE, Errno::ECONNRESET, IOError
           nil
-        rescue ClosedError, UnavailableError
-          safe_yield(EventHub::UNAVAILABLE_FRAME) { |frame| yield frame }
+        rescue StandardError => error
+          @logger&.error(
+            "[async-background-web] SSE stream terminated: " \
+            "#{error.class}: #{error.message}"
+          )
           nil
-        ensure
-          @hub.unsubscribe(subscription) if subscription
         end
 
         private
 
-        def safe_yield(frame)
-          yield frame
-        rescue Errno::EPIPE, IOError
-          nil
+        def initial_state
+          @hub.initial_frame
+        rescue ClosedError, UnavailableError
+          [nil, nil]
+        end
+
+        def sleep_for_poll
+          sleep(@poll_seconds)
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-28 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -198,7 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
+rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
 summary: Lightweight heap-based cron/interval scheduler for Async.