rails_pod_kit 0.0.3 → 0.2.0

data/lib/rails_pod_kit/global_scheduler.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+require 'rails_pod_kit/supervisor'
+
+module RailsPodKit
+  # Runs the sidekiq-cron poller in a process that is *not* a Sidekiq server, so
+  # a Sidekiq deployment can be autoscaled to zero without losing its schedule.
+  #
+  # sidekiq-cron installs its poller from inside `Sidekiq.configure_server`, so
+  # the schedule exists only while a Sidekiq server is alive. At zero replicas
+  # nothing polls, nothing is enqueued, and nothing ever raises the queue depth
+  # that would wake a worker back up — a closed loop that forces a permanent
+  # floor of one replica just to keep a poller alive. Recurring jobs are not
+  # caught up afterwards either: `reschedule_grace_period` (60s by default)
+  # discards any run older than itself, so a worker started later skips it.
+  #
+  # The poller has no such requirement of its own. `Sidekiq::Cron::Poller` is a
+  # Redis-polling thread and runs in any process holding a Sidekiq config, so
+  # hosting it on an always-on singleton — the dedicated exporter pod, see
+  # GlobalExporter — breaks the cycle and leaves the workers free to scale to
+  # zero.
+  #
+  # Deliberately Rails-free, like the exporter it sits beside: enqueueing does
+  # not need the job classes. When `Job#enqueue!` cannot resolve the class it
+  # pushes a plain Sidekiq message naming the ActiveJob wrapper with the job
+  # class as a *string*, and the worker — which does have Rails — resolves it.
+  # That fallback is only correct for entries declaring `active_job: true`, so
+  # `start!` warns about any that would instead be pushed as bare Sidekiq jobs.
+  #
+  # The poller runs under the shared Supervisor, exactly like SolidQueue's
+  # scheduler thread. Its own loop swallows StandardError (`Poller#enqueue` and
+  # `#wait` both do), so a Redis blip costs one skipped tick — but anything it
+  # does not catch takes the thread down and, since this process is the only
+  # scheduler, the schedule with it, silently.
+  module GlobalScheduler
+    SOURCE = 'rails_pod_kit.global_scheduler'
+
+    module_function
+
+    # Loads the schedule and starts the supervisor, which starts the poller on
+    # its first (immediate) tick, then returns without blocking. Idempotent: a
+    # second call is a no-op rather than a second poller in the same process.
+    #
+    # `schedule_file:`, `poll_interval:` and `reschedule_grace_period:` override
+    # sidekiq-cron's own defaults (`config/schedule.yml`, resolved against the
+    # working directory, polled every 30s, catching up runs at most 60s late);
+    # `supervision_interval:` is the shared Supervisor's.
+    #
+    # Raising the grace period is what makes a restart of the single scheduling
+    # process free: below it a missed occurrence is caught up on the next poll,
+    # above it the run is skipped silently. Size it over the worst restart —
+    # eviction, reschedule, image pull, boot — not over the poll interval.
+    def start!(schedule_file: nil, poll_interval: nil, reschedule_grace_period: nil,
+               supervision_interval: Supervisor::DEFAULT_INTERVAL)
+      return @supervisor if @supervisor
+      return unless RailsPodKit.scheduler_enabled?('sidekiq-cron poller')
+
+      require 'sidekiq'
+      require 'sidekiq-cron'
+      # sidekiq-cron renders the schedule file through ERB without requiring it:
+      # under Rails it is always already loaded, here it is not.
+      require 'erb'
+
+      configure!(schedule_file: schedule_file, poll_interval: poll_interval,
+                 reschedule_grace_period: reschedule_grace_period)
+      load_schedule!
+
+      @supervisor = build_supervisor(supervision_interval).start
+    end
+
+    # Winds the poller down so an in-flight tick finishes before the process
+    # exits, instead of being cut off mid-enqueue by the signal.
+    def stop!
+      @supervisor&.stop
+      @supervisor = nil
+    end
+
+    def poller
+      @supervisor&.subject
+    end
+
+    def build_supervisor(interval)
+      Supervisor.new(
+        source: SOURCE,
+        interval: interval,
+        start: -> { build_poller.tap(&:start) },
+        alive: method(:poller_alive?),
+        stop: :terminate
+      )
+    end
+
+    # `Sidekiq::Scheduled::Poller` keeps its thread in `@thread` and `start` is a
+    # no-op once that is set, so there is no public way to ask whether the poller
+    # is still running, nor to revive it. Reading the ivar lets the supervisor
+    # replace a dead poller wholesale — schedule state lives in Redis, so a fresh
+    # one picks up exactly where the old one stopped. An unrecognised shape reads
+    # as alive, so an upstream rename costs the supervision, never a restart loop.
+    def poller_alive?(poller)
+      return true unless poller.instance_variable_defined?(:@thread)
+
+      !!poller.instance_variable_get(:@thread)&.alive?
+    end
+
+    def configure!(schedule_file: nil, poll_interval: nil, reschedule_grace_period: nil)
+      ::Sidekiq::Cron.configure do |cron|
+        cron.cron_schedule_file = schedule_file if schedule_file
+        cron.cron_poll_interval = poll_interval if poll_interval
+        cron.reschedule_grace_period = reschedule_grace_period if reschedule_grace_period
+      end
+    end
+
+    # sidekiq-cron reads the schedule file from a Sidekiq server's `:startup`
+    # lifecycle event, which never fires here, so load it explicitly.
+    def load_schedule!
+      return unless ::Sidekiq::Cron.configuration.enabled
+
+      loader = ::Sidekiq::Cron::ScheduleLoader.new
+      return unless loader.has_schedule_file?
+
+      loader.load_schedule
+      warn_unresolvable_entries!
+    end
+
+    # sidekiq-cron's own Launcher publishes these two into the Sidekiq config
+    # before instantiating the poller, which reads them straight back out.
+    # Pinning the process count keeps the poll interval at the configured value:
+    # the inherited default counts *live Sidekiq servers*, which here is a count
+    # of anything but cron pollers — and is zero while the workers are scaled in.
+    def build_poller
+      config = ::Sidekiq.default_configuration
+      config[:cron_poll_interval] = ::Sidekiq::Cron.configuration.cron_poll_interval.to_i
+      config[:cron_poll_process_count] = ::Sidekiq::Cron.configuration.cron_poll_process_count || 1
+
+      ::Sidekiq::Cron::Poller.new(config)
+    end
+
+    # An entry whose class this process cannot load and which does not declare
+    # `active_job: true` is pushed as a bare Sidekiq job message, so the worker
+    # runs `perform` outside ActiveJob — no callbacks, no argument
+    # deserialization, no retry bookkeeping.
+    def warn_unresolvable_entries!
+      names = ::Sidekiq::Cron::Job.all('*').reject { |job| enqueueable_without_class?(job) }.map(&:name)
+      return if names.empty?
+
+      ::Sidekiq.logger.warn do
+        "[rails_pod_kit] cron entries #{names.join(', ')} name a class this Rails-free process cannot load and " \
+          'are not marked `active_job: true`; they would be enqueued as plain Sidekiq jobs.'
+      end
+    end
+
+    def enqueueable_without_class?(job)
+      job.to_hash[:active_job] == '1' || !::Sidekiq::Cron::Support.safe_constantize(job.klass.to_s).nil?
+    end
+  end
+end

data/lib/rails_pod_kit/shutdown.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RailsPodKit
+  # Blocks the main thread of an always-on entry point until the orchestrator
+  # signals. A self-pipe rather than a Queue or a Mutex: writing to an IO is one
+  # of the few things safe to do from a trap handler.
+  module Shutdown
+    SIGNALS = %w[INT TERM].freeze
+
+    module_function
+
+    def await(signals: SIGNALS)
+      reader, writer = IO.pipe
+      signals.each { |signal| Signal.trap(signal) { writer.puts(signal) } }
+      reader.gets
+    end
+  end
+end

data/lib/rails_pod_kit/sidekiq.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rails_pod_kit/config'
+require 'rails_pod_kit/exporter'
 
 module RailsPodKit
   # Sidekiq integration. Called from inside `Sidekiq.configure_server`:
@@ -81,19 +82,11 @@ module RailsPodKit
       apply_retries_segmentation!
     end
 
-    # Starts the background WEBrick exporter. `start_metrics_server!` reads the
-    # bind port from PROMETHEUS_EXPORTER_PORT, so we set it from config first.
-    # Guarded so a re-entrant Sidekiq boot doesn't try to double-bind the port.
+    # Starts the background WEBrick exporter shared with the other non-Puma
+    # entry points; guarded there so a re-entrant Sidekiq boot can't double-bind
+    # the port.
     def start_metrics_server!
-      return if @server_started
-
-      ENV['PROMETHEUS_EXPORTER_PORT'] ||= RailsPodKit.config.port.to_s
-      # Drop the WEBrick exporter's per-scrape access log (Rack::CommonLogger,
-      # which the mmap exporter mounts unless this is exactly 'false'). See
-      # Config#silence_exporter_access_log.
-      ENV['PROMETHEUS_EXPORTER_LOG_REQUESTS'] = 'false' if RailsPodKit.config.silence_exporter_access_log
-      Yabeda::Prometheus::Exporter.start_metrics_server!
-      @server_started = true
+      RailsPodKit::Exporter.start!
     end
   end
 end

data/lib/rails_pod_kit/solid_queue/metrics.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+require 'rails_pod_kit/error_reporter'
+
+module RailsPodKit
+  module SolidQueue
+    # DB-backed queue gauges for SolidQueue, in the shape yabeda-sidekiq exposes
+    # for Redis: SolidQueue ships no metrics endpoint and there is no
+    # `yabeda-solid_queue`.
+    #
+    # Two series, both per `queue`, both computed at scrape time from a yabeda
+    # `collect` block — no background thread, no cached snapshot:
+    #
+    #   solid_queue_backlog          how many jobs could be claimed right now
+    #   solid_queue_latency_seconds  how long the oldest of them has been waiting
+    #
+    # "Claimable right now" is ready executions plus scheduled ones whose time
+    # has come (the dispatcher has yet to move them across). Backlog alone misses
+    # a small-but-stalled queue and latency alone misses a large-but-moving one,
+    # so the pair is what dashboards, alerts and an HPA feed actually need.
+    #
+    # `::SolidQueue` is the host's — the gem declares no dependency on it and
+    # nothing here loads until the host calls `install!`.
+    module Metrics
+      SOURCE = 'rails_pod_kit.solid_queue_metrics'
+
+      module_function
+
+      # Declares the gauges and registers the scrape-time collector. Safe before
+      # or after `Yabeda.configure!` (yabeda replays configurators either way).
+      #
+      # `queues:` pins the zero baseline (see #baseline_queues) instead of
+      # discovering it. `fail_scrape_on_error:` makes a collection failure fail
+      # the whole response rather than serve the last reading — right when this
+      # collector owns the endpoint, wrong when it shares one (see #collect!).
+      #
+      # Declaration is one-shot but the options are not: the dedicated pod boots
+      # the host's initializers before `run_exporter!` runs, so by the time the
+      # pod asks for `fail_scrape_on_error` the app's own `install_metrics!` has
+      # normally already declared the gauges. An option given here always wins;
+      # one left out keeps whatever an earlier call set.
+      def install!(queues: nil, fail_scrape_on_error: nil)
+        @baseline_queues = queues unless queues.nil?
+        @fail_scrape_on_error = fail_scrape_on_error unless fail_scrape_on_error.nil?
+
+        return false if @installed
+
+        require 'yabeda'
+        declare!
+        @installed = true
+      end
+
+      def declare!
+        Yabeda.configure do
+          group :solid_queue do
+            gauge :backlog,
+                  tags: %i[queue],
+                  comment: 'Jobs claimable right now: ready executions plus scheduled ones whose time has come'
+            gauge :latency,
+                  unit: :seconds,
+                  tags: %i[queue],
+                  comment: 'How long the oldest claimable job has been waiting'
+
+            collect { RailsPodKit::SolidQueue::Metrics.collect! }
+          end
+        end
+      end
+
+      # Called by yabeda on every scrape.
+      #
+      # An error is always reported, and then either swallowed or re-raised
+      # depending on who owns the endpoint. Swallowing keeps a transient DB
+      # failure from taking the Puma series down with it on a shared endpoint —
+      # at the cost of serving the last reading, which a consumer cannot tell
+      # apart from a live one. On the dedicated pod (`run_exporter!`) there is
+      # nothing else to protect, so failing the scrape is the honest answer: the
+      # gauges go to no-data and the scraper's own `up` series carries the
+      # failure.
+      def collect!
+        now = ::Time.now.utc
+        with_connection { publish_all(claimable_by_queue(now), now) }
+      rescue StandardError => e
+        ErrorReporter.report(e, source: SOURCE)
+        raise if @fail_scrape_on_error
+      end
+
+      # Collection runs on the exporter's HTTP thread, which would otherwise
+      # check out a connection and pin it there for the life of the process.
+      def with_connection(&)
+        ::ActiveRecord::Base.connection_pool.with_connection(&)
+      end
+
+      # => { "default" => { backlog: 12, waiting_since: <Time> }, … }
+      def claimable_by_queue(now)
+        merge(ready_rows, due_rows(now))
+      end
+
+      def ready_rows
+        rows(::SolidQueue::ReadyExecution.all, :created_at)
+      end
+
+      # A scheduled execution whose time has come is claimable too. Its wait
+      # started at `scheduled_at`, not `created_at` — a job enqueued a week ahead
+      # of its slot is not a week late.
+      def due_rows(now)
+        rows(::SolidQueue::ScheduledExecution.where(scheduled_at: ..now), :scheduled_at)
+      end
+
+      # Two grouped aggregates over an indexed, normally-small table. Both go
+      # through ActiveRecord's calculations so the timestamp comes back
+      # type-cast on every adapter.
+      def rows(relation, waiting_since_column)
+        counts = relation.group(:queue_name).count
+        oldest = relation.group(:queue_name).minimum(waiting_since_column)
+
+        counts.map { |queue, count| [queue, count, oldest[queue]] }
+      end
+
+      def merge(*row_sets)
+        row_sets.flatten(1).each_with_object({}) do |(queue, count, waiting_since), acc|
+          entry = acc[queue] ||= { backlog: 0, waiting_since: nil }
+          entry[:backlog] += count
+          entry[:waiting_since] = [entry[:waiting_since], waiting_since].compact.min
+        end
+      end
+
+      def publish_all(queues, now)
+        queues.each do |queue, entry|
+          publish(queue, backlog: entry[:backlog], latency: age_in_seconds(entry[:waiting_since], now))
+        end
+
+        zero_drained_queues(queues.keys)
+      end
+
+      def publish(queue, backlog:, latency:)
+        Yabeda.solid_queue.backlog.set({ queue: queue }, backlog)
+        Yabeda.solid_queue.latency.set({ queue: queue }, latency)
+      end
+
+      # A gauge keeps its last value per label set, so a queue that just drained
+      # would stay pinned at its final backlog forever — the exact reading that
+      # would keep an alert firing on an idle system. Track the label sets this
+      # process has published and zero the ones missing from this round.
+      def zero_drained_queues(current)
+        seen = seen_queues
+        (seen - current).each { |queue| publish(queue, backlog: 0, latency: 0) }
+        @seen_queues = seen | current
+      end
+
+      # Seeded with the baseline, so the zeroing above also covers queues this
+      # process has never seen busy. A gauge only exists once it has been set:
+      # without the seed an exporter that boots while the queue is empty — the
+      # steady state of a scale-to-zero deployment — publishes no series at all,
+      # and every consumer reads no-data where it should read 0.
+      def seen_queues
+        @seen_queues ||= baseline_queues
+      end
+
+      # The queues the app is known to use, pinned by the host or discovered
+      # once per process from the jobs table (one index scan, never repeated).
+      # Discovery is best-effort by construction: that table is bounded by
+      # `clear_finished_jobs_after`, so a queue idle for longer than the
+      # retention window leaves no trace. Pin `queues:` where the zero has to be
+      # guaranteed.
+      def baseline_queues
+        @baseline_queues || ::SolidQueue::Job.distinct.pluck(:queue_name).compact
+      end
+
+      def age_in_seconds(waiting_since, now)
+        return 0 if waiting_since.nil?
+
+        [(now - waiting_since).to_f, 0].max
+      end
+
+      # Test/reset hook — drops the published-label-set memo and the install
+      # options.
+      def reset!
+        @seen_queues = nil
+        @baseline_queues = nil
+        @fail_scrape_on_error = false
+        @installed = false
+      end
+    end
+  end
+end

data/lib/rails_pod_kit/solid_queue/scheduler_runner.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'active_support/configuration_file'
+require 'active_support/core_ext/hash/keys'
+
+require 'rails_pod_kit/config'
+require 'rails_pod_kit/supervisor'
+
+module RailsPodKit
+  module SolidQueue
+    # Runs a SolidQueue *scheduler* — and only the scheduler — as a supervised
+    # background thread, so the process running jobs can scale to zero.
+    #
+    # Scaling the executor to zero is otherwise a chicken-and-egg problem: with
+    # no executor there is no scheduler, so nothing enqueues the recurring or
+    # scheduled jobs that would wake one. A k8s CronJob can't take over either,
+    # because it can't own *dynamic* recurring tasks (created and updated at
+    # runtime through `SolidQueue.schedule_recurring_task`). Moving just the
+    # scheduler onto an always-on process — the web, or the exporter pod —
+    # breaks the cycle: it keeps evaluating the crons and enqueueing, and the
+    # queue depth wakes the executor.
+    #
+    # Deliberately *not* the full supervisor (`plugin :solid_queue`): that one
+    # forks, and its Puma watchdog takes the host process down when the
+    # supervisor exits — which a transient Postgres disconnect is enough to
+    # cause (rails/solid_queue#512). Here a DB blip at worst kills the scheduler
+    # thread; the supervising timer notices on its next tick and starts a fresh
+    # one, and the host process never notices.
+    #
+    # Running it on every replica is safe: enqueues stay exactly-once via the
+    # unique index on `solid_queue_recurring_executions (task_key, run_at)`.
+    class SchedulerRunner
+      # How often the scheduler re-reads the dynamic tasks from the DB.
+      DEFAULT_POLLING_INTERVAL = 5
+      # How often we check that the scheduler thread is still alive.
+      DEFAULT_SUPERVISION_INTERVAL = 5
+
+      SOURCE = 'rails_pod_kit.solid_queue_scheduler'
+
+      def initialize(polling_interval: DEFAULT_POLLING_INTERVAL,
+                     supervision_interval: DEFAULT_SUPERVISION_INTERVAL,
+                     recurring_schedule_file: nil)
+        @polling_interval = polling_interval
+        @supervision_interval = supervision_interval
+        @recurring_schedule_file = recurring_schedule_file
+      end
+
+      # Starts the supervisor, which starts the scheduler on its first (immediate)
+      # tick and returns without blocking.
+      def start
+        @supervisor = build_supervisor.start
+        self
+      end
+
+      # Graceful stop: the supervisor drops its timer before winding the
+      # scheduler down (unschedule its timers and deregister the process,
+      # instead of leaving a row to expire).
+      def stop
+        @supervisor&.stop
+        @supervisor = nil
+      end
+
+      def running?
+        !!@supervisor&.running?
+      end
+
+      private
+
+      def build_supervisor
+        Supervisor.new(
+          source: SOURCE,
+          interval: @supervision_interval,
+          start: -> { build_scheduler },
+          alive: :alive?,
+          stop: :stop
+        )
+      end
+
+      def build_scheduler
+        scheduler = ::SolidQueue::Scheduler.new(
+          recurring_tasks: static_recurring_tasks,
+          dynamic_tasks_enabled: true,
+          polling_interval: @polling_interval
+        )
+        scheduler.mode = :async
+        scheduler.start # spawns the scheduler's own thread and returns
+        scheduler
+      end
+
+      # The static tasks from config/recurring.yml; the dynamic ones come from
+      # the DB via `dynamic_tasks_enabled`. `SolidQueue::Configuration#recurring_tasks`
+      # is private, so parse the file with the same public helper it uses.
+      def static_recurring_tasks
+        path = recurring_schedule_file
+        return [] unless path && ::File.exist?(path)
+
+        config = ::ActiveSupport::ConfigurationFile.parse(path).deep_symbolize_keys
+        config.fetch(environment.to_sym, {}).filter_map do |key, options|
+          ::SolidQueue::RecurringTask.from_configuration(key, **options) if options&.key?(:schedule)
+        end
+      end
+
+      # Same resolution order SolidQueue's own CLI uses.
+      def recurring_schedule_file
+        return @recurring_schedule_file if @recurring_schedule_file
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+
+        ::Rails.root.join(ENV.fetch('SOLID_QUEUE_RECURRING_SCHEDULE', 'config/recurring.yml'))
+      end
+
+      def environment
+        return ::Rails.env if defined?(::Rails) && ::Rails.respond_to?(:env)
+
+        ENV.fetch('RAILS_ENV', 'development')
+      end
+    end
+  end
+end

data/lib/rails_pod_kit/solid_queue.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+require 'rails_pod_kit/exporter'
+require 'rails_pod_kit/shutdown'
+require 'rails_pod_kit/solid_queue/metrics'
+require 'rails_pod_kit/solid_queue/scheduler_runner'
+
+module RailsPodKit
+  # SolidQueue integration — the pieces a Rails 8 app needs to run its job
+  # executor with scale-to-zero autoscaling (KEDA/HPA). All three are opt-in;
+  # requiring this file only defines them.
+  #
+  #   install_metrics!    the `solid_queue_backlog` / `solid_queue_latency_seconds`
+  #                       gauges on /metrics (see Metrics)
+  #   start_scheduler!    the SolidQueue scheduler as a supervised background
+  #                       thread on an always-on process (see SchedulerRunner)
+  #   run_exporter!       both of the above in a dedicated always-on pod, with
+  #                       the /metrics server, blocking until SIGTERM
+  #
+  # Nothing here loads `solid_queue` itself: it is the host's dependency, the
+  # same way Puma and Sidekiq are.
+  #
+  # Wiring the two halves separately, when the always-on process is the web:
+  #
+  #   # config/initializers/rails_pod_kit.rb
+  #   RailsPodKit::SolidQueue.install_metrics!
+  #
+  #   # config/puma.rb — after_booted only runs in the real Puma process,
+  #   # never in a console, a rake task or the test suite.
+  #   after_booted { RailsPodKit::SolidQueue.start_scheduler! }
+  #   at_exit      { RailsPodKit::SolidQueue.stop_scheduler! }
+  module SolidQueue
+    module_function
+
+    # Declares the queue gauges. Call from an initializer, in whichever process
+    # should publish them — see the README on keeping one source per series.
+    #
+    # Options are Metrics.install!'s: `queues:` to pin the zero baseline,
+    # `fail_scrape_on_error:` to fail the scrape instead of serving the last
+    # reading when the DB is unreachable (the default only holds on an endpoint
+    # this collector shares with another group).
+    def install_metrics!(**)
+      Metrics.install!(**)
+    end
+
+    # Starts the supervised scheduler thread and returns the runner. Idempotent:
+    # a second call returns the running one rather than starting a second
+    # scheduler in the same process.
+    #
+    # Not gated on `RailsPodKit.enabled?` — that switch owns the metrics
+    # exporter, and an app may well want the scheduler with metrics turned off.
+    # `scheduler_enabled` is the switch that does own this (see Config); beyond
+    # it, the guard against starting one in a console or in specs is *where* you
+    # call this from (`after_booted`, or the exporter entrypoint).
+    def start_scheduler!(**)
+      return scheduler_runner if scheduler_runner
+      return unless RailsPodKit.scheduler_enabled?('SolidQueue scheduler')
+
+      @scheduler_runner = SchedulerRunner.new(**).start
+    end
+
+    def stop_scheduler!
+      @scheduler_runner&.stop
+      @scheduler_runner = nil
+    end
+
+    def scheduler_runner
+      @scheduler_runner
+    end
+
+    # Runs the dedicated always-on SolidQueue pod and blocks until SIGTERM:
+    # the queue gauges, the scheduler thread and the /metrics server in one
+    # 1-replica Deployment, so both survive the web and the executor scaling to
+    # zero and each series has exactly one source.
+    #
+    # Unlike GlobalExporter this one is *not* Rails-free — SolidQueue is
+    # ActiveRecord-backed and reads the app's own tables — so the host's
+    # entrypoint boots the environment first, e.g. `bin/solid-queue-pod`:
+    #
+    #   #!/usr/bin/env ruby
+    #   require_relative '../config/environment'
+    #   RailsPodKit::SolidQueue.run_exporter!
+    #
+    # Pass `scheduler: false` to serve the gauges only (an app whose web process
+    # already hosts the scheduler), and `metrics:` to override the gauge options
+    # — this endpoint is the collector's own, so a collection failure fails the
+    # scrape here rather than serving the last reading.
+    def run_exporter!(scheduler: true, metrics: {}, **scheduler_options)
+      install_metrics!(fail_scrape_on_error: true, **metrics)
+      start_scheduler!(**scheduler_options) if scheduler
+
+      warn '[rails_pod_kit] disabled — /metrics not served by the SolidQueue exporter' unless Exporter.start!
+
+      require 'yabeda'
+      Yabeda.configure! unless Yabeda.already_configured?
+
+      await_shutdown
+      stop_scheduler!
+    end
+
+    # Blocks the main thread (the exporter and the scheduler both run on their
+    # own) until the kubelet signals.
+    def await_shutdown
+      Shutdown.await
+    end
+  end
+end