cogworker 0.1.0

data/lib/cogworker/web/routes/stats.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Cogworker
+  class Web
+    module Routes
+      # The 6 job-counter cards, the "Runs per day" Chart.js graph, and a
+      # Redis INFO summary.
+      module Stats
+        COUNTERS_CONTENT_ID = 'stats-counters-content'
+        REDIS_CONTENT_ID = 'stats-redis-content'
+        # The 6 job-counter colors are the same ones `Layout.stat_chip` uses
+        # for the compact bar shown on every page — one shared mapping
+        # (`Layout::JOB_STAT_ACCENTS`) so the two never drift apart.
+        CARD_ACCENTS = Layout::JOB_STAT_ACCENTS.merge(
+          'Version' => 'text-gray-700 dark:text-gray-300', 'Uptime (days)' => 'text-gray-700 dark:text-gray-300',
+          'Connections' => 'text-gray-700 dark:text-gray-300', 'Memory Usage' => 'text-gray-700 dark:text-gray-300',
+          'Peak Memory Usage' => 'text-gray-700 dark:text-gray-300'
+        ).freeze
+        # `INFO` field name => card label. Pulled from the flat Hash
+        # `Cogworker::Stats#redis_info` returns (same field names the
+        # `redis` gem always uses, regardless of Redis version) — a field
+        # missing from a given server/deployment renders as "n/a" rather
+        # than raising.
+        REDIS_INFO_FIELDS = {
+          'redis_version' => 'Version', 'uptime_in_days' => 'Uptime (days)',
+          'connected_clients' => 'Connections', 'used_memory_human' => 'Memory Usage',
+          'used_memory_peak_human' => 'Peak Memory Usage'
+        }.freeze
+        # Period switcher options for the "Runs per day" chart —
+        # `params['period']` (a plain query string, read fresh on every
+        # request; see `registered` below) selects one of these by key.
+        # Ordered as displayed, shortest first.
+        PERIODS = {
+          'week' => { 'label' => 'Week', 'days' => 7 },
+          'month' => { 'label' => 'Month', 'days' => 30 },
+          '3months' => { 'label' => '3 Months', 'days' => 90 },
+          '6months' => { 'label' => '6 Months', 'days' => 182 }
+        }.freeze
+        DEFAULT_PERIOD = 'month'
+        CHART_SUCCESS_COLOR = '#16a34a'
+        CHART_FAILED_COLOR = '#dc2626'
+        CHART_CANVAS_ID = 'runs-chart-canvas'
+        CHART_CONTAINER_HEIGHT_PX = 220
+        # Vendored under assets/ (see CLAUDE.md's "Fully offline" section —
+        # served locally, not fetched from a CDN), the same way AG_GRID_ASSETS
+        # is in `routes/history.rb`.
+        CHART_ASSET = 'assets/chart.umd.min.js'
+
+        module_function
+
+        def registered(app)
+          renderer = lambda do
+            # A plain query param, not htmx state — the period switcher
+            # below is a normal `<a href>` (full page reload), exactly like
+            # `Routes::History`'s status filter links.
+            period = Stats.resolve_period(params['period'])
+            body = Stats.page_body(period, request.script_name)
+            if hx_request?
+              body
+            else
+              Layout.wrap('Stats', body, script_name: request.script_name, show_stats_bar: false,
+                                         extra_head: Stats.chart_head(request.script_name))
+            end
+          end
+
+          app.get('/', &renderer)
+          app.get('/stats', &renderer)
+
+          # Polled by `Layout.stats_bar` (the global counter strip shown
+          # under the header on every page, not just here) — always just
+          # this small fragment, never a full page.
+          app.get('/stats/bar') { Layout.stats_bar_content }
+
+          # The job-counter and Redis grids each poll their own small
+          # fragment independently (see `page_body`) — neither depends on
+          # `period`, so unlike the chart there's no query string to carry.
+          app.get('/stats/counters') { Stats.counters_grid }
+          app.get('/stats/redis') { Stats.redis_grid(Cogworker::Stats.new.redis_info) }
+
+          # Polled directly by the chart's own inline script (`chart`,
+          # below) via `fetch` — NOT an htmx target, and deliberately not a
+          # full HTML fragment: returning just the plotted numbers lets the
+          # chart patch its existing Chart.js instance's data in place
+          # (`chart.update()`) instead of tearing down and recreating the
+          # `<canvas>`/instance on every tick, which is what an htmx
+          # innerHTML-swapped fragment would force. Same idea as
+          # `Routes::History`'s `/history/data` for its AG Grid.
+          app.get('/stats/chart_data') do
+            period = Stats.resolve_period(params['period'])
+            [200, { 'content-type' => 'application/json' }, [JSON.generate(Stats.chart_data_payload(period))]]
+          end
+        end
+
+        def resolve_period(raw)
+          PERIODS.key?(raw) ? raw : DEFAULT_PERIOD
+        end
+
+        def chart_head(script_name)
+          %(<script src="#{Layout.path(script_name, CHART_ASSET)}"></script>)
+        end
+
+        # The counters and Redis grids are each their own independently
+        # htmx-polled fragment (`Layout.poll_div`) — plain, stateless HTML,
+        # cheap to fully replace every tick. The "Runs per day" section in
+        # between is a normal, *unpolled* part of the page: its own chart
+        # keeps itself live via `/stats/chart_data` instead (see
+        # `registered` above and `chart` below), so re-rendering this whole
+        # method's output on a poll would rebuild widgets that don't need
+        # rebuilding — the counters/Redis grids are the only pieces actually
+        # meant to be swapped wholesale on every tick.
+        def page_body(period, script_name)
+          stats = Cogworker::Stats.new
+          counters_poll = Layout.poll_div(COUNTERS_CONTENT_ID, script_name, 'stats/counters', counters_grid(stats))
+          runs_chart = Layout.section('Runs per day', runs_per_day_section(period, script_name))
+          redis_poll = Layout.section('Redis', Layout.poll_div(REDIS_CONTENT_ID, script_name, 'stats/redis',
+                                                               redis_grid(stats.redis_info)))
+          counters_poll + runs_chart + redis_poll
+        end
+
+        def counters_grid(stats = Cogworker::Stats.new)
+          values = {
+            'Enqueued' => stats.enqueued, 'Processed' => stats.processed, 'Failed' => stats.failed,
+            'Retries' => stats.retry_size, 'Scheduled' => stats.scheduled_size, 'Dead' => stats.dead_size
+          }
+          cards = values.map { |label, value| card(label, value) }.join
+          %(<div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-4">#{cards}</div>)
+        end
+
+        def redis_grid(info)
+          cards = REDIS_INFO_FIELDS.map { |field, label| card(label, info[field] || 'n/a') }.join
+          %(<div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-5 gap-4">#{cards}</div>)
+        end
+
+        def runs_per_day_section(period, script_name)
+          period_switcher(script_name, period) + chart_bubble(period, script_name)
+        end
+
+        def period_switcher(script_name, current_period)
+          links = PERIODS.map do |key, opts|
+            period_link(script_name, key, opts['label'], active: key == current_period)
+          end.join
+          %(<div class="mb-4 flex gap-2">#{links}</div>)
+        end
+
+        def period_link(script_name, key, label, active:)
+          classes = if active
+                      'bg-indigo-600 text-white'
+                    else
+                      'bg-gray-100 dark:bg-gray-800 text-gray-600 dark:text-gray-300 hover:bg-gray-200 dark:hover:bg-gray-700'
+                    end
+          href = Layout.path(script_name, "stats?period=#{key}")
+          %(<a href="#{href}" class="px-3 py-1 rounded-md text-sm font-medium #{classes}">#{Layout.h(label)}</a>)
+        end
+
+        # Wraps the chart in the same "bubble" card look as the job-counter/
+        # Redis stat cards (`card`, below).
+        def chart_bubble(period, script_name)
+          %(<div class="rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 shadow-sm p-4">#{chart(
+            period, script_name
+          )}</div>)
+        end
+
+        # Success/failed counts for `period`, keyed exactly as Chart.js
+        # wants them — `labels`/`fullDates` line up index-for-index with
+        # `success`/`failed`. Shared between the initial render (`chart`,
+        # baked into the page) and `/stats/chart_data` (what the chart's own
+        # poll re-fetches from then on), so the two can never drift apart.
+        def chart_data_payload(period)
+          days_count = PERIODS.fetch(period, PERIODS[DEFAULT_PERIOD])['days']
+          # Fully qualified: a bare `History::Storage` from inside
+          # `Routes::Stats` would resolve, via lexical nesting, to
+          # `Cogworker::Web::Routes::History` first (this module's sibling
+          # route file) — the same gotcha `routes/history.rb` itself
+          # documents — not to the top-level `Cogworker::History`.
+          counts = Cogworker::History::Storage.daily_counts(days_count)
+          days = day_labels(days_count)
+          {
+            'labels' => days.map { |d| d[5..] },
+            'fullDates' => days,
+            'success' => days.map { |d| (counts[d] || {})['success'] || 0 },
+            'failed' => days.map { |d| (counts[d] || {})['failed'] || 0 }
+          }
+        end
+
+        # A small two-line chart (success/failed per day) rendered by
+        # Chart.js (vendored, loaded via `chart_head` — see CLAUDE.md's
+        # "Fully offline" section, not fetched from a CDN), not a hand-rolled
+        # SVG: a first attempt at a DIY SVG chart used
+        # `preserveAspectRatio="none"` to stretch full width, which visibly
+        # distorted the plotted lines/points on any card wider than its
+        # aspect ratio, and its styling looked noticeably rougher than a
+        # maintained charting library's own defaults (real user report on
+        # both counts). `responsive: true` + `maintainAspectRatio: false`
+        # fills the fixed-height wrapper div at its full width, at any
+        # screen size, without distortion — Chart.js sizes its own
+        # `<canvas>` (including devicePixelRatio) via `ResizeObserver`.
+        #
+        # This section is NOT inside any `Layout.poll_div` (see `page_body`
+        # above) — the `<canvas>`/`new Chart(...)` below render exactly once
+        # per page load. An earlier version instead re-rendered this whole
+        # chart (canvas included) on every htmx poll, which meant creating a
+        # brand-new Chart.js instance every tick; skipping `.destroy()` on
+        # the previous one (easy to miss, since the *canvas* really was
+        # gone) leaked one more zombie instance per poll — real, observed
+        # root cause of the chart eventually breaking under live updates.
+        # Rather than track and destroy instances across swaps, the fix here
+        # is to not recreate the widget at all: the chart keeps itself
+        # current by polling `/stats/chart_data` on its own (`refreshChart`
+        # below, gated by the same `window.cogworkerLiveUpdate` toggle every
+        # other tab's poll respects) and patching the *existing* instance's
+        # data in place, exactly like `Routes::History`'s AG Grid does via
+        # its own `refreshRows`/`/history/data`.
+        def chart(period, script_name)
+          payload = chart_data_payload(period)
+          data_url = Layout.path(script_name, "stats/chart_data?period=#{period}")
+
+          <<~HTML
+            <div style="position: relative; height: #{CHART_CONTAINER_HEIGHT_PX}px; width: 100%;">
+              <canvas id="#{CHART_CANVAS_ID}"></canvas>
+            </div>
+            <script>
+              (function () {
+                var dataUrl = #{Layout.json_for_script(data_url)};
+                var fullDates = #{Layout.json_for_script(payload['fullDates'])};
+                var chart = new Chart(document.getElementById(#{Layout.json_for_script(CHART_CANVAS_ID)}), {
+                  type: 'line',
+                  data: {
+                    labels: #{Layout.json_for_script(payload['labels'])},
+                    datasets: [
+                      { label: 'Success', data: #{Layout.json_for_script(payload['success'])},
+                        borderColor: #{Layout.json_for_script(CHART_SUCCESS_COLOR)},
+                        backgroundColor: #{Layout.json_for_script(CHART_SUCCESS_COLOR)},
+                        tension: 0.3, pointRadius: 2, borderWidth: 2 },
+                      { label: 'Failed', data: #{Layout.json_for_script(payload['failed'])},
+                        borderColor: #{Layout.json_for_script(CHART_FAILED_COLOR)},
+                        backgroundColor: #{Layout.json_for_script(CHART_FAILED_COLOR)},
+                        tension: 0.3, pointRadius: 2, borderWidth: 2 }
+                    ]
+                  },
+                  options: {
+                    responsive: true,
+                    maintainAspectRatio: false,
+                    interaction: { mode: 'index', intersect: false },
+                    scales: {
+                      x: { ticks: { color: '#6b7280', maxRotation: 0, autoSkip: true, maxTicksLimit: 8 }, grid: { display: false } },
+                      y: { beginAtZero: true, ticks: { color: '#6b7280', precision: 0 }, grid: { color: 'rgba(107, 114, 128, 0.15)' } }
+                    },
+                    plugins: {
+                      legend: { labels: { color: '#6b7280' } },
+                      tooltip: { callbacks: { title: function (items) { return fullDates[items[0].dataIndex]; } } }
+                    }
+                  }
+                });
+
+                function refreshChart() {
+                  if (!window.cogworkerLiveUpdate) return;
+                  fetch(dataUrl, { headers: { 'Accept': 'application/json' } })
+                    .then(function (r) { return r.ok ? r.json() : null; })
+                    .then(function (data) {
+                      if (!data) return;
+                      fullDates = data.fullDates;
+                      chart.data.labels = data.labels;
+                      chart.data.datasets[0].data = data.success;
+                      chart.data.datasets[1].data = data.failed;
+                      chart.update();
+                    })
+                    .catch(function () {});
+                }
+                setInterval(refreshChart, #{Cogworker::Web.live_update_interval * 1000});
+              })();
+            </script>
+          HTML
+        end
+
+        # `days_count` consecutive UTC calendar-day strings ending today —
+        # matches the UTC bucketing `Storage.daily_counts` uses, so lookups
+        # by day string always line up.
+        def day_labels(days_count)
+          now = Time.now.utc
+          (days_count - 1).downto(0).map { |offset| (now - (offset * 86_400)).strftime('%Y-%m-%d') }
+        end
+
+        def card(label, value)
+          <<~HTML
+            <div class="rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 shadow-sm p-4">
+              <div class="text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400">#{Layout.h(label)}</div>
+              <div class="mt-1 text-2xl font-bold #{CARD_ACCENTS.fetch(label, '')}">#{Layout.h(value)}</div>
+            </div>
+          HTML
+        end
+      end
+    end
+  end
+end
+
+Cogworker::Web.register(Cogworker::Web::Routes::Stats)

data/lib/cogworker/web/views.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Cogworker
+  class Web
+    # Reads a built-in view template by name. An extension that wants its
+    # own template file can use the same pattern (read the file itself,
+    # then hand `erb` the resulting String) — `Action#erb` accepts either a
+    # Symbol (looked up here) or a raw ERB-source String directly.
+    module Views
+      VIEWS_PATH = File.join(__dir__, 'views')
+
+      class << self
+        def read(name)
+          cache[name] ||= File.read(File.join(VIEWS_PATH, "#{name}.erb"))
+        end
+
+        private
+
+        def cache
+          @cache ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/cogworker/web.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require 'rack'
+require 'rack/session/cookie'
+require 'rack/static'
+require 'securerandom'
+
+module Cogworker
+  # Rack entry point: `map('/mount-point') { run Cogworker::Web }`.
+  #
+  # A plain, reopenable class on purpose — `safe_request?` is meant to be
+  # overridden by whoever mounts this (e.g. to let one specific external
+  # callback path through a same-origin check) without needing any hook
+  # mechanism from this gem: `class Cogworker::Web; def self.safe_request?(env);
+  # ...; end; end` just works, the same way monkey-patching any Ruby class
+  # does. Note the `self.` — `safe_request?` is defined inside `class << self`
+  # below (it's called as `Cogworker::Web.safe_request?`, not on an
+  # instance), so reopening it as a plain instance method is a silent no-op.
+  class Web
+    # Every built-in tab lives under here; touching each constant once
+    # forces Zeitwerk to load that file (and run its
+    # `Cogworker::Web.register(...)` bottom-of-file side effect) — nothing
+    # else ever references `Routes::Queues` etc. by name, so without this
+    # they would simply never load.
+    BUILT_IN_ROUTE_NAMES = %i[Queues Busy Retries Scheduled Periodic Dead History Stats SaveSession].freeze
+    DEFAULT_TIME_FORMAT = '%Y-%m-%d %H:%M:%S'
+    DEFAULT_HISTORY_PER_PAGE = 25
+    DEFAULT_LIVE_UPDATE_INTERVAL = 3
+
+    # htmx/Tailwind/AG Grid are vendored under here (not fetched from a CDN)
+    # so the Web UI works with no internet access at all — see `Layout`'s
+    # `<script>`/`<link>` tags and `Routes::History#ag_grid_head`, all of
+    # which build their `src`/`href` as `path(script_name, 'assets/...')`,
+    # same as every other in-app link. `root:` is this directory's *parent*
+    # (not `assets/` itself) because `Rack::Static` appends the full,
+    # unstripped request path (e.g. `/assets/htmx.min.js`) onto `root`.
+    ASSETS_ROOT = File.join(__dir__, 'web')
+
+    # Guards every request's dispatch while reloading is enabled — a plain
+    # class-level constant (not lazily memoized via `||=`, which would
+    # itself race) so it exists before any request can possibly reach it.
+    # See `call`/`dispatch` below for why this has to wrap the *entire*
+    # request, not just `reload!`.
+    RELOAD_MUTEX = Mutex.new
+
+    class << self
+      # While `COGWORKER_RELOAD=true`, the whole request — the reload
+      # itself *and* the route handling that follows — runs inside
+      # `RELOAD_MUTEX`, not just the `Cogworker::LOADER.reload` call.
+      # `Zeitwerk::Loader#reload`'s `unload` step removes every constant it
+      # manages *process-wide* for the duration of the reload, not just
+      # from this thread's point of view — so a second thread mid-`app.call`
+      # (already past its own `reload!`, now executing a route that
+      # references `Layout`/`WorkSet`/etc.) can have those constants yanked
+      # out from under it and raise `NameError`, even though it never
+      # touched `reload!` concurrently itself. Only wrapping `reload!` (an
+      # earlier version of this fix) stopped the *permanent* `Zeitwerk::
+      # SetupRequired` wedge but not this — both were caught by
+      # `spec/cogworker/web_reload_spec.rb`'s concurrent-requests spec,
+      # which spawns several threads hammering `.call` at once. Outside
+      # `COGWORKER_RELOAD` (i.e. every real worker-adjacent Web process)
+      # `reloading?` is false and this adds no locking at all.
+      def call(env)
+        if reloading?
+          RELOAD_MUTEX.synchronize do
+            reload!
+            dispatch(env)
+          end
+        else
+          dispatch(env)
+        end
+      end
+
+      # Extends the Rack middleware stack this Web app itself runs behind
+      # (session cookie, an auth middleware wrapping the whole app) —
+      # distinct from mounting external middleware *outside* this app via
+      # plain `Rack::Builder`/`map`, which also works and needs nothing from
+      # here.
+      def use(middleware, *args)
+        middlewares << [middleware, args]
+        @app = nil
+      end
+
+      def register(extension, name: extension.to_s, tab: nil, index: nil)
+        Cogworker::Web::Application.register(extension)
+        tabs[tab] = index if tab && index
+        name
+      end
+
+      # Public, mutable: `Cogworker::Web.tabs['History'] = 'history'` is how
+      # a registered extension actually gets a nav entry.
+      def tabs
+        @tabs ||= {}
+      end
+
+      def session_secret
+        @session_secret ||= SecureRandom.hex(32)
+      end
+
+      # How every `Layout.time_tag` timestamp is rendered — a Ruby
+      # `Time#strftime` pattern, reused as-is client-side (the same tokens:
+      # %Y %m %d %H %M %S %B %b %A %a %p), just evaluated against the
+      # browser's local time instead of the server's UTC fallback. Set this
+      # from your own init file/config.ru, e.g.
+      # `Cogworker::Web.time_format = '%d.%m.%Y %H:%M'`.
+      def time_format
+        @time_format ||= DEFAULT_TIME_FORMAT
+      end
+
+      attr_writer :time_format, :history_per_page, :live_update_interval, :prometheus_exporter_enabled
+
+      # Whether `GET /metrics` (`Cogworker::Prometheus::Exporter`, mounted
+      # automatically by `load_routes!` below like any other built-in) is
+      # actually served — checked at request time by the exporter's own
+      # route, not here, so this can be set any time before a request comes
+      # in, same as `time_format`/`live_update_interval`. Set this to
+      # `false` from your own init file/config.ru to opt back out, e.g. if
+      # you'd rather scrape metrics through a separate, unauthenticated
+      # mount and don't want `/metrics` reachable behind this one at all.
+      def prometheus_exporter_enabled
+        return true unless defined?(@prometheus_exporter_enabled)
+
+        @prometheus_exporter_enabled
+      end
+
+      # Rows per page on the History tab. Retention depth (how many entries
+      # exist to page through at all) is a separate, gem-wide setting:
+      # `Cogworker::History.max_entries`.
+      def history_per_page
+        @history_per_page ||= DEFAULT_HISTORY_PER_PAGE
+      end
+
+      # How often (in seconds) every auto-refreshing tab polls while the
+      # global live-update toggle is on — both the htmx-polled Busy/Stats/
+      # Queues tabs (`Layout.poll_div`'s `hx-trigger="every Ns [...]"`) and
+      # History's own AG Grid `refreshRows()` JS poll share this one value,
+      # so there's a single knob rather than one per tab. Set this from your
+      # own init file/config.ru, e.g. `Cogworker::Web.live_update_interval = 10`.
+      def live_update_interval
+        @live_update_interval ||= DEFAULT_LIVE_UPDATE_INTERVAL
+      end
+
+      # A minimal same-origin check (default-open for safe/read-only HTTP
+      # methods, otherwise requires `Sec-Fetch-Site: same-origin`).
+      # Reopen this method to carve out an exception for a specific
+      # cross-site callback path (e.g. an SSO provider's POST redirect).
+      def safe_request?(env)
+        return true if safe_method?(env['REQUEST_METHOD'])
+
+        env['HTTP_SEC_FETCH_SITE'] == 'same-origin'
+      end
+
+      def safe_method?(method)
+        %w[GET HEAD OPTIONS].include?(method)
+      end
+
+      def reloading?
+        Cogworker::LOADER.reloading_enabled?
+      end
+
+      # Only ever called from `.call` above (always already holding
+      # `RELOAD_MUTEX` — see there for why), i.e. only while handling a Web
+      # UI HTTP request — never from a job-processing thread. Note this
+      # reloads Zeitwerk's *entire* managed tree (there's one loader for the
+      # whole gem), not just lib/cogworker/web/**: editing an engine file
+      # (Processor, Config, ...) while a dev Web UI process is up will also
+      # pick up those changes on the next request. That's harmless for a
+      # process that only ever serves HTTP and never runs `Launcher`, but is
+      # exactly why this must never be wired into `exe/cogworker`.
+      #
+      # `Cogworker::Web` itself is *not* meaningfully reloadable: Rack
+      # captures a single reference to this class object once, at `run
+      # Cogworker::Web` boot time, and calls that same object's `.call`
+      # forever — editing this file's own methods (`call`, `build_app`, ...)
+      # has no effect without a real process restart. What *does* refresh
+      # every request is everything this class only ever reaches through a
+      # fresh, fully-qualified lookup: `@app` is rebuilt every time (so it
+      # re-resolves `Cogworker::Web::Application`, not a memoized stale
+      # reference to whatever object used to be there), and that in turn
+      # re-executes `Routes::*`/`Layout`/`Router`/`Action` fresh, so their
+      # bare cross-references to each other stay internally consistent.
+      def reload!
+        @tabs = {}
+        @app = nil
+        Cogworker::LOADER.reload
+        load_routes!
+      end
+
+      # Fully-qualified references throughout, not bare `Application`/
+      # `Routes`: right after `Zeitwerk::Loader#reload`, a bare constant
+      # lookup relying on lexical nesting can fail to find a freshly
+      # re-armed autoload even though the constant is genuinely there —
+      # `Cogworker::Web::Routes` resolves correctly where a bare `Routes`
+      # (searched via Module.nesting from inside this method) sometimes
+      # raises `NameError` immediately after a reload. Fully-qualifying
+      # sidesteps it entirely.
+      def load_routes!
+        BUILT_IN_ROUTE_NAMES.each { |name| Cogworker::Web::Routes.const_get(name) }
+        # Different namespace (Cogworker::Prometheus::Exporter, not
+        # Cogworker::Web::Routes::*) so it can't join BUILT_IN_ROUTE_NAMES
+        # above, but touching the constant is the same Zeitwerk-autoload
+        # trick either way: it runs that file's own bottom-of-file
+        # `Cogworker::Web.register(...)` exactly like a route file would.
+        # Previously this constant was only ever touched by an app's own
+        # init code remembering to reference it — forgetting to do so left
+        # `/metrics` returning a plain 404 with no indication why the route
+        # was missing.
+        # Mounting it always and gating on `prometheus_exporter_enabled`
+        # instead (checked inside the route itself, not here) fixes that
+        # while keeping the opt-out.
+        Cogworker::Prometheus::Exporter
+      end
+
+      private
+
+      def dispatch(env)
+        return forbidden(env) unless safe_request?(env)
+
+        app.call(env)
+      end
+
+      def forbidden(_env)
+        [403, { 'content-type' => 'text/plain' }, ['Forbidden']]
+      end
+
+      def middlewares
+        @middlewares ||= []
+      end
+
+      def app
+        @app ||= build_app
+      end
+
+      def build_app
+        builder = Rack::Builder.new
+        builder.use(Rack::Session::Cookie, secret: session_secret, key: 'cogworker.session')
+        # No `cache_control:` (no `immutable`/long `max-age`): these files
+        # are plain, unfingerprinted paths that *do* change — every time
+        # this gem's Tailwind bundle gets rebuilt, or on any gem upgrade —
+        # and `immutable` previously told browsers to keep serving a stale
+        # cached copy under the old URL for up to a year with no
+        # revalidation at all (caught by hand: a real edit to tailwind.css
+        # didn't show up in an already-open tab until a hard reload).
+        # `Rack::Static`/`Rack::Files` already sends `Last-Modified` and
+        # honors conditional GETs by default, which is all that's needed
+        # here — a browser still avoids a full re-download when nothing
+        # changed, but always gets fresh content the moment something did.
+        builder.use(Rack::Static, urls: ['/assets'], root: ASSETS_ROOT)
+        middlewares.each { |mw, args| builder.use(mw, *args) }
+        builder.run(Cogworker::Web::Application)
+        builder.to_app
+      end
+    end
+  end
+end
+
+Cogworker::Web.load_routes!

data/lib/cogworker/work.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # One in-flight job on one process/thread.
+  class Work
+    attr_reader :process_id, :thread_id
+
+    def initialize(process_id, thread_id, hash)
+      @process_id = process_id
+      @thread_id = thread_id
+      @hash = hash
+    end
+
+    def queue = @hash['queue']
+    def run_at = @hash['run_at']
+    # already a Hash: nested by the outer JSON.parse in WorkSet#each
+    def job = @hash['payload']
+  end
+end

data/lib/cogworker/work_set.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Cogworker
+  class WorkSet
+    include Enumerable
+
+    def each
+      ProcessSet.new.each do |process|
+        identity = process['identity']
+        workers = Cogworker.config.redis { |c| c.hgetall(RedisKeys.workers(identity)) }
+        workers.each do |tid, raw|
+          yield identity, tid, Work.new(identity, tid, JSON.parse(raw))
+        end
+      end
+    end
+
+    def size
+      count { true }
+    end
+  end
+end

data/lib/cogworker/worker.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cogworker
+  Worker = Job
+end

data/lib/cogworker/workers.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # TZ 3.4 describes Workers and WorkSet with the identical
+  # (process_id, thread_id, work) contract, so this is a bare alias, not a
+  # second implementation to keep in sync.
+  Workers = WorkSet
+end