async-background 0.7.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f8593628f08094cc53b6c69eff34e3a4be9e8c12de5bd72f1447857aab2682
-  data.tar.gz: e9e441eb2b6f775cd52d2704c8a2b24d9ac771a24beb07d33f78d81285d41f1c
+  metadata.gz: 3d7244ccfb7156c423229ed59f36df9354d293711bab53e6a87d943743bc7f44
+  data.tar.gz: 84752c52033b89c5b957d39976f5d025a56215b378138eda8813c05635c5d58e
 SHA512:
-  metadata.gz: 194c82e280d24821e756849cc9f3f74db8cbadc424d4984fb3a58d10d21864cbe13b1adfa84aa3bf1bd6b9996d59e1d423d5c865c2d1ec33846679ed2ab936f0
-  data.tar.gz: 518bc2a692d0ade6ea02ff18ebca2a3078e02365ffd77fe9850d8bccc64b7243ea871efeec2913f33fe7ecdaeb8fa6a56067e57f36d5852adf59302cc656416e
+  metadata.gz: 6e90dd0f6be9ff7361aba7d84e7a7cdfdd712b351938c50dc8b84358d10a20f65514880a3eac3ab2ad8c0adf5164c06f9668ead03df5161fc4482b4e27aa03ec
+  data.tar.gz: 1867b17975c63966aeaf437414795b3b5d9083c9871a9f6c44dc6b7280651bbf46a8c929b4751349f969ffbdf72c32aeb8c6965634d149e74a0a352e4ef958df

data/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## Unreleased
+
+### Dashboard SSE hardening
+
+- Make SSE the default dashboard transport. `:polling` remains an explicit compatibility fallback.
+- Replace one `PRAGMA data_version` loop **per browser connection** with one shared `EventHub` watcher per Rack app process while at least one dashboard tab is connected. It fans complete overview snapshots to every SSE body through latest-value mailboxes, so slow tabs do not accumulate unbounded event queues.
+- Use complete snapshots on connect and after a change rather than a replay log: reconnecting EventSource clients cannot miss the current queue state.
+- Coalesce client-side list refreshes after a burst of changes, cancel stale list fetches on tab switches, and retain previous pages when `Load more` is used.
+- Add SSE retry control, 25-second heartbeat frames, `no-cache, no-transform`, and `X-Accel-Buffering: no`. Remove the hop-by-hop `Connection` response header.
+- Fingerprint asset URLs and cache immutable assets by digest, so a dashboard deploy cannot leave a browser on incompatible HTML/JS/CSS.
+- Add coverage for event fan-out, latest-value coalescing, clean stream shutdown, forced overview reads, and the SSE configuration constraints.
+
+## 1.1.0
+
+Server-Sent Events transport for the dashboard. Replaces HTTP polling as the recommended transport.
+
+### Added
+
+- **SSE transport for the dashboard.** Set `c.transport = :sse` in `Async::Background::Web.configure` and the dashboard now uses a single long-lived `text/event-stream` connection per browser tab instead of polling `/api/overview` every 2 seconds. The browser opens `EventSource(mount_path + '/api/stream')` once; the server pushes an `overview` event whenever `PRAGMA data_version` changes, and a `:keepalive` comment frame every 30 seconds. Result: 1 HTTP connection per dashboard tab regardless of how long it stays open, instead of 30 req/min per tab.
+
+  - New module `Async::Background::Web::Stream` implements the event loop as a Rack streaming body (responds to `#each`, yields SSE frames). Holds no state across requests.
+  - New route `GET /api/stream` returns `200 text/event-stream` when `transport == :sse`, `404` otherwise. Subject to the same auth gate as every other endpoint.
+  - New `Response.sse(body)` helper sets the correct headers including `x-accel-buffering: no` (disables nginx buffering for the streaming response).
+  - JS client (`assets.rb`) detects `state.config.transport === 'sse'` at boot and chooses `EventSource` over `setInterval(tick, ...)`. Both transports share the same `applyOverview()` and `refreshActiveList()` handlers, so the UI behaves identically.
+
+- **`Configuration#transport`** with default `:polling` (backward compatible) and accepted values `:polling | :sse`. Validation rejects anything else with `ConfigurationError`. The chosen transport is exposed at `/api/config` so the client knows which path to take.
+
+### Migration
+
+Existing deployments keep working unchanged. To opt into SSE:
+
+```ruby
+Async::Background::Web.configure do |c|
+  c.queue_path = ...
+  c.auth = ->(env) { ... }
+  c.transport = :sse
+end
+```
+
+### Server compatibility note
+
+SSE holds the request thread/fiber open for the lifetime of the dashboard tab. **Recommended for Falcon**, which handles long-lived connections natively via fibers. **Puma works** but each open dashboard tab holds one worker thread for its lifetime — fine for an admin dashboard with a handful of operators, problematic if many concurrent operators would starve the worker pool. **Unicorn does not work** for SSE since its blocking worker model can't hold long-lived connections without timeouts; stay on `:polling` there.
+
+### Backend-side polling
+
+The server still polls `PRAGMA data_version` every 500ms inside the snapshot connection to detect changes. This is a connection-local PRAGMA call, microseconds, never hits a rate limiter. Client-facing transport is push.
+
+### Tests
+
+- New `spec/async/background/web/stream_spec.rb` — covers overview event on data_version change, heartbeat after idle, graceful exit on `EPIPE`/`IOError`, error frame on `ClosedError`/`UnavailableError`.
+- Extended `spec/async/background/web/app_spec.rb` — `/api/stream` returns 404 on polling default, 200 text/event-stream on `:sse`, 401 without auth.
+- Extended `spec/async/background/web/configuration_spec.rb` — accepts `:sse`, rejects unknown transports.
+
+## 1.0.0
+
+First stable release. The queue execution contract from 0.7.2 (claim-token CAS, lifecycle columns, barrier-based shutdown drain, per-status partial indexes, versioned migrations) is now considered the public API.
+
+### Features
+
+- **Web dashboard.** Rack-mountable read-only UI under `require 'async/background/web'`. Vanilla HTML/CSS/JS, no JS framework, no npm.
+  - Endpoints: `GET /`, `GET /assets/app.css`, `GET /assets/app.js`, `GET /api/overview`, `GET /api/executing`, `GET /api/claimed`, `GET /api/pending`, `GET /api/done`, `GET /api/failed`, `GET /api/metrics`, `GET /api/config`.
+  - Default transport is JSON polling (`poll_interval_ms`, default 2000). SSE adapter for Falcon is intentionally deferred to a later release; the dashboard already coalesces work via a shared overview cache, so adding SSE later is a backward-compatible change.
+  - Read path runs through `Async::Background::Web::Snapshot`, which opens SQLite with `file:?mode=ro`, wraps a `Mutex` around a single shared connection, and uses one read transaction per endpoint and caches each overview as one consistent snapshot.
+  - Distinguishes `Executing` (`status='running' AND started_at IS NOT NULL`) from `Claimed` (`status='running' AND started_at IS NULL`).
+  - Overview snapshot cache for `counts_cache_ttl` seconds (default 3.0) so a busy queue does not turn the dashboard into a hot reader.
+  - Cursor pagination for `done`/`failed`/`pending` using `(finished_at, id)` / `(run_at, id)` tuples. Stable on ties.
+  - Args hidden by default (`expose_args: false`); when enabled, content runs through `redact_args`. All user content rendered through `textContent`, never `innerHTML`.
+  - Auth hook is **mandatory**. `Configuration#validate!` rejects an unconfigured `auth`. There is no permissive default.
+
+  - Add the optional Rack dashboard for the SQLite queue.
+  - Make sqlite3 an explicit runtime dependency for queue/dashboard installs.
+
+### Configuration
+
+```ruby
+require 'async/background/web'
+
+Async::Background::Queue::Store.prepare_dashboard!(path: '/var/lib/app/queue.db')
+
+Async::Background::Web.configure do |c|
+  c.queue_path        = '/var/lib/app/queue.db'
+  c.auth              = ->(env) { env['warden'].user&.admin? }
+  c.expose_args       = false
+  c.metrics_path      = '/run/app/async-background.shm'
+  c.total_workers     = 4
+  c.counts_cache_ttl  = 3.0
+  c.poll_interval_ms  = 2000
+  c.list_limit        = 50
+  c.mount_path        = '/admin/background'
+  c.title             = 'My App background jobs'
+end
+
+run Async::Background::Web.app
+```
+
+### Dependencies
+
+- `rack` is an optional dependency. Required only when `require 'async/background/web'` is loaded. Core gem and worker processes do not require it.
+
+### Breaking changes from 0.7.x
+
+None beyond what 0.7.2 already shipped. The 1.0 line locks the existing contract:
+
+- `Queue::Store#fetch` returns `claim_token` in the result hash.
+- All terminal `Queue::Store` methods (`complete`, `fail`, `retry_or_fail`) require the `claim_token:` kwarg and return CAS success boolean / `:retried` / `:failed` / `nil`.
+- Schema is versioned via `PRAGMA user_version`. Use `Queue::Store.migrate!(path:)` to upgrade. Use `Queue::Store.prepare_dashboard!(path:)` from the dashboard process to lazily create dashboard-only indexes (per-status partial indexes for `done` / `failed`, plus separate `executing` and `claimed` indexes).
+
+## 0.7.2
+
+- Harden queue execution, retries, shutdown, and metrics.
+- Add schema v1, optional dashboard indexes, and a faster enqueue path.
+
 ## 0.7.1
 
 ### Features
@@ -97,7 +209,7 @@
   - Proper job distribution validation across worker pool
 - **Test fixtures** — dedicated `ci/fixtures/jobs.rb` and `ci/fixtures/schedule.yml` for scenario testing
 
-### Bug Fixes  
+### Bug Fixes
 - **SQLite busy timeout** — added `PRAGMA busy_timeout = 5000` to `Queue::Store` to prevent `SQLITE_BUSY` errors under concurrent multi-process database access
 - **Enhanced Queue::Notifier error handling** — restructured IO error handling with clearer categorization:
   - `WRITE_DROPPED` for write failures (`IO::WaitWritable`, `Errno::EAGAIN`, `IOError`, `Errno::EPIPE`) — all non-fatal as job is already in store

data/README.md

@@ -12,16 +12,16 @@ A lightweight cron, interval, and job-queue scheduler for Ruby's [Async](https:/
 
 - Ruby >= 3.3
 - `async ~> 2.0`, `fugit ~> 1.0`
-- `sqlite3 ~> 2.0` (optional, for the job queue)
-- `async-utilization ~> 0.3` (optional, for metrics)
+- `sqlite3 ~> 2.0` (optional, storage)
+- `async-utilization >= 0.3, < 0.5` (optional, for metrics)
 
 ## Install
 
 ```ruby
 # Gemfile
 gem "async-background"
-gem "sqlite3", "~> 2.0"            # optional
-gem "async-utilization", "~> 0.3"  # optional
+gem "sqlite3", "~> 2.0"  # optional
+gem "async-utilization", ">= 0.3", "< 0.5"  # optional
 ```
 
 ## ➡️ [Get Started](docs/GET_STARTED.md)
@@ -92,9 +92,8 @@ Without this, you will get database crashes in multi-process mode. See [Get Star
 **Don't share SQLite connections across `fork()`.** The gem opens connections lazily after fork, but if you create a `Queue::Store` manually for schema setup, close it before forking:
 
 ```ruby
-store = Async::Background::Queue::Store.new(path: db_path)
-store.ensure_database!
-store.close  # ← before fork
+Async::Background::Queue.migrate!(path: db_path) # ← once, before fork
+# Every process opens its own Store lazily after fork.
 ```
 
 **Two clocks, on purpose.** Interval jobs use `CLOCK_MONOTONIC` (immune to NTP drift). Cron jobs use wall-clock time, because "every day at 3am" needs to mean 3am.
@@ -127,19 +126,67 @@ The dynamic queue runs alongside it:
 
 Jobs are persisted in SQLite, so a missed wake-up is never a lost job — workers also poll every 5 seconds as a safety net.
 
+### Queue-only workers
+
+Recurring schedules are optional. A worker that serves only dynamic jobs starts with
+`config_path: nil` and a `queue_socket_dir`; it does not need a placeholder schedule file.
+A supplied schedule path stays strict and raises when the file is missing or empty.
+
+### Schema migration during deploy
+
+Run queue migrations once in the release/pre-deploy step, before starting new web or worker
+processes. This serializes the schema upgrade with `BEGIN IMMEDIATE`, records the version in
+SQLite, and avoids a first producer doing DDL under live queue traffic:
+
+```ruby
+Async::Background::Queue.migrate!(path: ENV.fetch("QUEUE_DB_PATH"))
+```
+
+A fresh database still self-initializes on first use for local development, but explicit
+migration is the production path. For an existing queue, finish or stop 0.7.1 producers/workers,
+run the migration once, then start 0.7.2 processes.
+
+### Dashboard indexes
+
+The queue does **not** install dashboard indexes by default. They slow every enqueue even though
+pending rows never enter terminal or in-flight read-model indexes. Enable them once before
+mounting the dashboard:
+
+```ruby
+Async::Background::Queue.prepare_dashboard!(path: ENV.fetch("QUEUE_DB_PATH"))
+```
+
+It adds four compact indexes: cursor-sorted `done` / `failed` history plus separate
+`executing` / `claimed` in-flight lists. It does not change queue behavior or rerun the core migration.
+
 ## Metrics
 
-With `async-utilization` installed, per-worker stats land in shared memory at `/tmp/async-background.shm` with lock-free updates.
+Metrics are an optional integration with `async-utilization` (`>= 0.3`, `< 0.5`). The
+background worker remains fully functional when that gem is absent. With it installed, each
+worker publishes counters to a shared-memory segment.
 
 ```ruby
+runner.metrics.enabled?
 runner.metrics.values
 # => { total_runs: 142, total_successes: 140, total_failures: 2,
 #      total_timeouts: 0, total_skips: 5, active_jobs: 1, ... }
 
 Async::Background::Metrics.read_all(total_workers: 2)
+# => [{ worker: 1, ... }, { worker: 2, ... }]
 ```
 
-Without the gem, metrics are silently disabled — zero overhead.
+`Metrics.read_all` returns `[]` until the optional gem is installed and a worker has created
+the file, so an observer can render an unavailable state without rescuing `LoadError`. Its
+snapshot is lock-free best effort: cumulative fields (`total_runs`, `total_successes`,
+`total_failures`, `total_timeouts`, `total_skips`) are counters; `active_jobs`,
+`last_run_at`, and `last_duration_ms` are gauges. Fields can describe adjacent moments in time
+rather than one globally atomic instant.
+
+By default the file is `/tmp/async-background.shm`. Set `ASYNC_BACKGROUND_METRICS_PATH`
+or pass `metrics_shm_path:` to `Runner.new` when another observer runs in a separate process
+or container; both sides must see the same mounted file.
+
+
 
 ## License
 

data/async-background.gemspec

@@ -33,11 +33,14 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'async',   '~> 2.0'
   spec.add_dependency 'console', '~> 1.0'
   spec.add_dependency 'fugit',   '~> 1.0'
+  spec.add_dependency 'base64',  '~> 0.2'
 
   # Optional: add to your own Gemfile if you need these features
-  #   gem 'sqlite3',          '~> 2.0'  # dynamic job queue
-  #   gem 'async-utilization', '~> 0.3' # shared-memory worker metrics
+  #   gem 'sqlite3', '~> 2.0'
+  #   gem 'async-utilization', '>= 0.3', '< 0.5' # shared-memory worker metrics
 
   spec.add_development_dependency 'rake',  '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rack',  '~> 3.0'
+  spec.add_development_dependency 'async-utilization', '>= 0.3', '< 0.5'
 end

data/lib/async/background/job.rb

@@ -4,6 +4,7 @@ module Async
   module Background
     module Job
       DEFAULT_TIMEOUT = 120
+      EMPTY_OPTIONS   = {}.freeze
       BACKOFFS        = %i[fixed linear exponential].freeze
       DEFAULT_JITTER_FOR = { fixed: 0.0, linear: 0.0, exponential: 0.5 }.freeze
 
@@ -55,15 +56,16 @@ module Async
       module ClassMethods
         def perform_now(*args) = new.perform(*args)
 
-        def perform_async(*args, options: {})     = Async::Background::Queue.enqueue(self, *args, options: options)
-        def perform_in(delay, *args, options: {}) = Async::Background::Queue.enqueue_in(delay, self, *args, options: options)
-        def perform_at(time, *args, options: {})  = Async::Background::Queue.enqueue_at(time, self, *args, options: options)
+        def perform_async(*args, options: EMPTY_OPTIONS)     = Async::Background::Queue.enqueue(self, *args, options: options)
+        def perform_in(delay, *args, options: EMPTY_OPTIONS) = Async::Background::Queue.enqueue_in(delay, self, *args, options: options)
+        def perform_at(time, *args, options: EMPTY_OPTIONS)  = Async::Background::Queue.enqueue_at(time, self, *args, options: options)
 
         def options(**values)
           @options = Options.new(**values).to_h.compact
         end
 
         def resolve_options = @options || {}
+        def queue_options = @options || EMPTY_OPTIONS
       end
 
       def perform(*)

data/lib/async/background/metrics.rb

@@ -1,143 +1,216 @@
 # frozen_string_literal: true
 
+require 'tmpdir'
+
 module Async
   module Background
     class Metrics
       SCHEMA_FIELDS = {
-        total_runs:       :u64,
-        total_successes:  :u64,
-        total_failures:   :u64,
-        total_timeouts:   :u64,
-        total_skips:      :u64,
-        active_jobs:      :u32,
-        last_run_at:      :u64,
+        total_runs: :u64,
+        total_successes: :u64,
+        total_failures: :u64,
+        total_timeouts: :u64,
+        total_skips: :u64,
+        active_jobs: :u32,
+        last_run_at: :u64,
         last_duration_ms: :u32
       }.freeze
 
-      attr_reader :registry
+      EMPTY_HANDLES = {}.freeze
 
-      def initialize(worker_index:, total_workers:, shm_path: self.class.default_shm_path)
-        require 'async/utilization'
+      attr_reader :registry, :shm_path, :unavailable_reason
 
+      def initialize(worker_index:, total_workers:, shm_path: self.class.default_shm_path)
+        @enabled = false
         @registry = nil
-        @enabled  = false
-        @registry = ::Async::Utilization::Registry.new
-        @enabled  = true
-        ensure_shm!(total_workers, shm_path)
-        attach_observer!(worker_index, total_workers, shm_path)
-      rescue LoadError, ArgumentError
-        @registry = nil
-        @enabled  = false
+        @metric_handles = EMPTY_HANDLES
+        @shm_path = shm_path
+        @unavailable_reason = nil
+
+        validate_worker!(worker_index, total_workers)
+        initialize_registry!(worker_index, total_workers, shm_path)
+      rescue LoadError => error
+        mark_unavailable!(error)
       end
 
-      def enabled?
-        @enabled
+      def enabled? = @enabled
+
+      def job_started(_entry)
+        return unless enabled?
+
+        increment(:total_runs)
+        increment(:active_jobs)
+        set(:last_run_at, Process.clock_gettime(Process::CLOCK_REALTIME).to_i)
       end
 
-      def job_started(entry)
-        return unless @enabled
+      def job_succeeded(_entry, duration)
+        return unless enabled?
 
-        @registry.increment(:total_runs)
-        @registry.increment(:active_jobs)
-        @registry.set(:last_run_at, Process.clock_gettime(Process::CLOCK_REALTIME).to_i)
+        increment(:total_successes)
+        set(:last_duration_ms, duration_to_milliseconds(duration))
       end
 
       def job_finished(entry, duration)
-        return unless @enabled
+        job_succeeded(entry, duration)
+        job_stopped(entry)
+      end
 
-        @registry.decrement(:active_jobs)
-        @registry.increment(:total_successes)
-        @registry.set(:last_duration_ms, (duration * 1000).to_i)
+      def job_failed(_entry, _error)
+        increment(:total_failures) if enabled?
       end
 
-      def job_failed(entry, error)
-        return unless @enabled
+      def job_timed_out(_entry)
+        increment(:total_timeouts) if enabled?
+      end
 
-        @registry.decrement(:active_jobs)
-        @registry.increment(:total_failures)
+      def job_stopped(_entry)
+        decrement(:active_jobs) if enabled?
       end
 
-      def job_timed_out(entry)
-        return unless @enabled
+      def job_skipped(_entry)
+        increment(:total_skips) if enabled?
+      end
 
-        @registry.decrement(:active_jobs)
-        @registry.increment(:total_timeouts)
+      def values
+        enabled? ? registry.values : {}
       end
 
-      def job_skipped(entry)
-        return unless @enabled
+      class << self
+        def available?
+          load_utilization!
+          true
+        rescue LoadError
+          false
+        end
 
-        @registry.increment(:total_skips)
-      end
+        def load_utilization!
+          require 'async/utilization'
+        end
 
-      def values
-        return {} unless @enabled
+        def schema
+          load_utilization!
+          ::Async::Utilization::Schema.build(SCHEMA_FIELDS)
+        end
 
-        @registry.values
-      end
+        def read_all(total_workers:, path: default_shm_path)
+          validate_total_workers!(total_workers)
+          return [] unless available? && File.file?(path)
 
-      def self.schema
-        require 'async/utilization'
-        ::Async::Utilization::Schema.build(SCHEMA_FIELDS)
-      end
+          layout = schema
+          segment = segment_size
+          required_size = segment * total_workers
+
+          File.open(path, 'rb') do |file|
+            return [] if file.size < required_size
 
-      # Read metrics for all workers from the shm file.
-      # No server needed — just reads the mmap'd file.
-      #
-      #   Async::Background::Metrics.read_all(total_workers: 2)
-      #   # => [
-      #   #   { worker: 1, total_runs: 142, active_jobs: 1, ... },
-      #   #   { worker: 2, total_runs: 98,  active_jobs: 0, ... }
-      #   # ]
-      #
-      def self.read_all(total_workers:, path: default_shm_path)
-        require 'async/utilization'
+            buffer = IO::Buffer.map(file, required_size, 0, IO::Buffer::READONLY)
+            decode_workers(buffer, layout, segment, total_workers)
+          end
+        rescue Errno::ENOENT
+          []
+        end
 
-        s = schema
-        segment = segment_size
-        file_size = segment * total_workers
+        def default_shm_path
+          ENV.fetch('ASYNC_BACKGROUND_METRICS_PATH') { File.join(Dir.tmpdir, 'async-background.shm') }
+        end
 
-        buffer = File.open(path, "rb") do |f|
-          IO::Buffer.map(f, file_size, 0)
+        def segment_size
+          SCHEMA_FIELDS.sum { |_, type| IO::Buffer.size_of(type) }
         end
 
-        (1..total_workers).map do |i|
-          base = (i - 1) * segment
-          row = { worker: i }
-          s.fields.each do |field|
-            row[field.name] = buffer.get_value(field.type, base + field.offset)
-          end
-          row
+        private
+
+        def validate_total_workers!(total_workers)
+          return if total_workers.is_a?(Integer) && total_workers.positive?
+
+          raise ArgumentError, 'total_workers must be a positive Integer'
+        end
+
+        def decode_workers(buffer, schema, segment, total_workers)
+          (1..total_workers).map do |worker|
+            decode_worker(buffer, schema, segment, worker)
+          end.freeze
+        end
+
+        def decode_worker(buffer, schema, segment, worker)
+          offset = (worker - 1) * segment
+          schema.fields.each_with_object(worker: worker) do |field, values|
+            values[field.name] = buffer.get_value(field.type, offset + field.offset)
+          end.freeze
         end
       end
 
-      def self.default_shm_path
-        File.join(Dir.tmpdir, "async-background.shm")
+      private
+
+      def initialize_registry!(worker_index, total_workers, path)
+        self.class.load_utilization!
+        ensure_shm!(total_workers, path)
+
+        @registry = ::Async::Utilization::Registry.new
+        unless @registry.respond_to?(:metric)
+          raise LoadError, 'async-utilization >= 0.3 is required for metrics'
+        end
+
+        attach_observer!(worker_index, path)
+        @metric_handles = SCHEMA_FIELDS.keys.to_h { |name| [name, @registry.metric(name)] }.freeze
+        @enabled = true
       end
 
-      def self.segment_size
-        SCHEMA_FIELDS.sum { |_, type| IO::Buffer.size_of(type) }
+      def mark_unavailable!(error)
+        @registry = nil
+        @metric_handles = EMPTY_HANDLES
+        @unavailable_reason = error.message
       end
 
-      private
+      def increment(name)
+        metric(name).increment
+      end
 
-      def ensure_shm!(total_workers, path)
-        required = self.class.segment_size * total_workers
+      def decrement(name)
+        metric(name).decrement
+      end
+
+      def set(name, value)
+        metric(name).set(value)
+      end
+
+      def metric(name)
+        @metric_handles.fetch(name)
+      end
 
-        File.open(path, File::CREAT | File::RDWR, 0644) do |f|
-          f.flock(File::LOCK_EX)
-          f.truncate(required) if f.size < required
-          f.flock(File::LOCK_UN)
+      def duration_to_milliseconds(duration)
+        (duration * 1000).to_i
+      end
+
+      def validate_worker!(worker_index, total_workers)
+        self.class.send(:validate_total_workers!, total_workers)
+        return if worker_index.is_a?(Integer) && worker_index.between?(1, total_workers)
+
+        raise ArgumentError, 'worker_index must be an Integer between 1 and total_workers'
+      end
+
+      def ensure_shm!(total_workers, path)
+        required_size = self.class.segment_size * total_workers
+        page_size = IO::Buffer::PAGE_SIZE
+        mapped_size = ((required_size + page_size - 1) / page_size) * page_size
+
+        File.open(path, File::CREAT | File::RDWR, 0o644) do |file|
+          file.flock(File::LOCK_EX)
+          file.truncate(mapped_size) if file.size < mapped_size
+        ensure
+          file.flock(File::LOCK_UN) rescue nil
         end
       end
 
-      def attach_observer!(worker_index, total_workers, path)
+      def attach_observer!(worker_index, path)
         segment = self.class.segment_size
-        offset  = (worker_index - 1) * segment
         observer = ::Async::Utilization::Observer.open(
-          self.class.schema, path, segment, offset
+          self.class.schema,
+          path,
+          segment,
+          (worker_index - 1) * segment
         )
-        @registry.observer = observer
+        registry.observer = observer
       end
     end
   end