kicks_liveness 0.1.0

data/docs/SETUP.md

@@ -0,0 +1,181 @@
+# Setup
+
+## Requirements
+
+You need **either** `kicks` (>= 3.0) **or** `sneakers` (>= 2.11). Neither is
+declared as a dependency of this gem: at runtime it needs only the `Sneakers`
+namespace, and both provide it. Install exactly one — see
+[LIMITATIONS.md](LIMITATIONS.md#do-not-install-both-kicks-and-sneakers) for why
+having both is worse than it looks.
+
+Those two floors are exact, not aspirational: CI runs the suite against
+`kicks 3.0.0` and `sneakers 2.11.0` pinned, alongside the matrix that tracks the
+newest release of each. A `~>` matrix on its own would only ever prove that the
+latest version works.
+
+```ruby
+gem 'kicks_liveness'
+```
+
+If neither is present, `install!` raises a `LoadError` naming both with their
+required versions.
+
+## Installing the hooks
+
+The gem works by prepending two modules — one to `Sneakers::Worker`, one to
+`Sneakers::WorkerGroup`. `KicksLiveness.install!` does that, and it must run
+before the runner starts. It is idempotent, so calling it twice is harmless.
+
+### Rails
+
+Nothing to do. A Railtie calls `install!` from `to_prepare`.
+
+That is the one path where this gem acts on its own rather than when told, so it
+is worth saying how far it has been checked: a production Rails application whose
+only kicks_liveness code is the `configure` block below — no `install!` anywhere —
+boots its workers with both hooks in place and the probe green. See
+[VERIFYING.md](VERIFYING.md#the-scenarios).
+
+The Railtie file is loaded only when `Rails::Railtie` is already defined at the
+time this gem is required, which is what `Bundler.require` in
+`config/application.rb` gives you. If your application requires this gem
+*before* Rails itself is loaded, the Railtie never loads and the hooks are never
+installed — call `install!` manually in that case.
+
+### Sinatra, Hanami, Roda, or no framework at all
+
+Call `install!` yourself, before the runner starts:
+
+```ruby
+require 'kicks_liveness'
+
+KicksLiveness.install!
+```
+
+There is no Rails coupling to work around: outside Rails the Railtie file is
+never loaded, and the gem pulls in no Rails code. The web framework is not
+involved at all — workers run in their own process, started by
+`rake sneakers:run` or your own runner script, and that process usually contains
+no web framework.
+
+### Getting the application loaded under `rake sneakers:run`
+
+The line above is the easy half. The half that actually costs people time is
+how the application gets into the rake process at all, because outside Rails
+nothing loads it for you.
+
+`sneakers/tasks` declares `task :environment` **empty**, precisely so that you
+can fill it in. Rake accumulates blocks for the same task rather than replacing
+them, so adding your own is the supported way:
+
+```ruby
+# Rakefile
+require 'sneakers/tasks'
+
+task(:environment) { require_relative 'app' }
+```
+
+where `app.rb` is whatever configures Sneakers, calls `install!` and defines (or
+requires) the worker classes. In Rails this is already handled — its own
+`:environment` task loads the application — which is why the problem only shows
+up outside it, usually as `sneakers:run` starting with no workers at all.
+
+This is exactly the wiring the gem's own integration fixture uses
+(`spec/integration/fixture/Rakefile`), so it is checked against a real broker on
+every run of [VERIFYING.md](VERIFYING.md).
+
+**Hanami 2** differs only in what that block contains: load the app the way
+Hanami wants (`require 'hanami/prepare'` for a prepared, not fully booted,
+application) and call `install!` after it. There is nothing Hanami-specific in
+the gem — as above, the framework is not in the picture, only the question of
+which file brings your worker classes into the process.
+
+A minimal standalone runner:
+
+```ruby
+require 'sneakers'          # kicks installs this same file
+require 'kicks_liveness'
+require_relative 'workers/orders_worker'
+
+Sneakers.configure(amqp: ENV.fetch('AMQP_URL'), workers: 2, threads: 10)
+KicksLiveness.install!
+
+Sneakers::Runner.new([OrdersWorker]).run
+```
+
+## Workers must be started through `Sneakers::Runner`
+
+This is the one real constraint, and it has nothing to do with frameworks.
+
+The monitor thread is started from the hook on
+`Sneakers::WorkerGroup#after_fork`, and `WorkerGroup` enters the picture through
+`Sneakers::Runner`, which builds a ServerEngine supervisor. If you boot workers
+by hand — instantiating worker classes and calling `worker.run` in your own
+loop, without ServerEngine — that hook never fires. The registry will fill up,
+but nothing writes the mark files, so the probe stays red and the pod is killed.
+
+Use `Sneakers::Runner` (that is what `rake sneakers:run` does), or do not use
+this gem.
+
+## Configuration
+
+Everything has a sensible default; in most applications the block is one line.
+
+```ruby
+KicksLiveness.configure do |config|
+  config.enabled = ENV['RACK_ENV'] != 'test'
+end
+```
+
+**Do not set `config.logger = Sneakers.logger`.** That is already the default,
+and writing it out is worse than leaving it alone, because the default is
+resolved *lazily* and the assignment is not. `Sneakers.logger` is `nil` until
+`Sneakers.configure` runs, so whether the assignment captures a logger or a
+`nil` depends on which file Rails loads first — and initializers load in
+alphabetical order, which is not something you chose or want to depend on. An
+initializer named `kicks_liveness.rb` sorts *before* `sneakers.rb`; one named
+`worker_liveness.rb` sorts after. Same code, different outcome.
+
+Set it only to point somewhere **other** than `Sneakers.logger`:
+
+```ruby
+config.logger = Rails.logger
+```
+
+| Option | Default | |
+|---|---|---|
+| `logger` | `Sneakers.logger`, resolved lazily | where transitions are logged |
+| `enabled` | `true` | set to `false` in tests, so no thread is started |
+| `tick` | `10` | seconds between checks |
+| `startup_grace_ticks` | `6` | unhealthy ticks tolerated at startup before one ERROR |
+
+`dir` and `max_age` are **not** here — they come from environment variables
+only. See
+[DESIGN.md](DESIGN.md#what-is-configurable-and-where) for why, and
+[KUBERNETES.md](KUBERNETES.md#environment-variables) for the variables.
+
+## Checking that the hooks are in place
+
+In a console of the process that boots your workers:
+
+```ruby
+Sneakers::Worker.ancestors.include?(KicksLiveness::Hooks::Worker)       # => true
+Sneakers::WorkerGroup.ancestors.include?(KicksLiveness::Hooks::WorkerGroup) # => true
+```
+
+Both must be `true` before the runner starts. If either is `false`, either
+`install!` has not run, or it ran before `kicks`/`sneakers` was loaded.
+
+Once workers are running, the marks directory is the other half of the answer:
+
+```
+$ ls -l /opt/app/tmp/health/
+expected
+worker-0
+worker-1
+```
+
+One `worker-<slot>` file per fork, plus `expected`. If `expected` is there and
+the slot files are not, the workers have not finished subscribing. A slot that
+keeps restarting without ever subscribing also leaves an `attempt-<slot>` file,
+which is removed as soon as that slot becomes healthy.

data/docs/VERIFYING.md

@@ -0,0 +1,330 @@
+# Verifying the probe against a real broker
+
+[KUBERNETES.md](KUBERNETES.md#verifying-on-a-live-pod) shows how to confirm the
+probe on a pod you already run. This document is the other half: a disposable
+local cluster where the **failures themselves** can be caused on purpose, so
+that every claim the gem makes is watched rather than reasoned about.
+
+Two of those claims cannot be checked any other way, because both are properties
+of Bunny rather than of this gem:
+
+- that `channel.any_consumers?` turns false when the broker takes a consumer
+  away, which is what the probe fails on;
+- that `recovering_from_network_failure?` stays true for the whole of a broker
+  outage, which is what keeps a hiccup from restarting every replica.
+
+And one is a property of the kubelet: that a red probe actually restarts the
+container. The `touch -d` recipe in KUBERNETES.md deliberately repairs itself
+within one tick, so on its own it never reaches `failureThreshold`.
+
+The fixture lives in `spec/integration/` in the repository. It is not part of the
+published gem, and it is not part of `rake` — nothing under it is a `_spec.rb`
+file, so `rspec` does not collect it.
+
+## What you need
+
+A local single-node cluster. Docker Desktop's built-in Kubernetes is the
+cheapest option, because an image built locally is visible to the cluster
+immediately, with no registry and no load step — `imagePullPolicy: Never` is all
+it takes.
+
+```bash
+spec/integration/verify.sh build   # image, into the engine the cluster uses
+spec/integration/verify.sh up      # namespace, broker, worker
+spec/integration/verify.sh down    # deletes the namespace
+```
+
+Every `kubectl` call in that script names its context and namespace explicitly.
+That is not politeness: a liveness experiment deletes queues and kills pods, and
+it must not be able to reach a real cluster because someone's current-context
+happened to point at one.
+
+Three things that cost time if you meet them the hard way:
+
+- **Build into the right engine.** If the machine also runs OrbStack, Colima or
+  Rancher Desktop, the default docker context is not the one Docker Desktop's
+  Kubernetes reads images from, and the pod fails with `ErrImageNeverPull`. The
+  script passes `--context desktop-linux` for this reason.
+- **A `path:` gem is not in `GEM_HOME`.** Bundler adds it to the load path and
+  nothing else. The standard command, `bundle exec kicks-liveness`, does not care
+  — Bundler put it there and Bundler finds it. The **optimised** command,
+  plain `ruby -e` with no Bundler, raises `LoadError`. It is one instance of
+  [where your image puts its gems](KUBERNETES.md#where-your-image-puts-its-gems),
+  and worth meeting here rather than in a rollout. The fixture image therefore
+  also `gem install`s the gem it builds, so that both commands are exercised the
+  way a published gem would be.
+- **`ruby:*-slim` has no compiler.** `bunny` pulls `sorted_set`, which pulls
+  `rbtree`, which is a native extension.
+
+## The scenarios
+
+Each one is an action and a single observable value. The values below are the
+ones actually recorded on Kubernetes v1.25 with kicks 3.4.0, bunny 3.3.0 and
+ruby 3.4, using the probe settings printed in KUBERNETES.md
+(`tick` 10 s, `max_age` 45 s, liveness `periodSeconds` 30 × `failureThreshold` 3).
+
+The same scenarios have since been replayed against a production Rails
+application — five consumers, two runners, one of them an ActiveJob adapter
+whose worker set is a callable registry rather than an array — on the same kind
+of throwaway cluster. Every outcome matched the fixture's, which is the point of
+keeping the fixture small: if a two-queue toy and a real application disagree,
+the disagreement is the finding.
+
+The **startup** budget never binds anything here, so no number below depends on
+it: this fixture subscribes in under a second, where a real application takes
+tens of seconds. That is precisely why the cold-start measurement in
+[KUBERNETES.md](KUBERNETES.md#measure-the-cold-start-not-the-restart) has to be
+made against your own application — a fixture cannot do it for you.
+
+### 1. It comes up
+
+```bash
+spec/integration/verify.sh logs | grep liveness
+spec/integration/verify.sh marks
+spec/integration/verify.sh probe
+```
+
+```
+INFO: [liveness] slot 0: started: dir=/opt/app/tmp/health max_age=45s tick=10s processes=1 consumers=2
+INFO: [liveness] slot 0: waiting for 2 consumers
+INFO: [liveness] slot 0: healthy          # one tick later
+expected  worker-0                        # in the marks directory
+1 process(es) healthy                     # probe, exit 0
+```
+
+The hooks fired inside a real ServerEngine fork, which no double can show.
+
+### 2. A stale mark
+
+The recipe from KUBERNETES.md. Proves the probe's threshold and the
+self-repair, and nothing else — the mark is fixed on the next tick, well inside
+`failureThreshold`, so the container is never killed.
+
+Worth running through **both** commands here, since this is the one scenario
+where the probe is supposed to answer `1`. `spec/integration/verify.sh probe`
+does exactly that: the standard `bundle exec kicks-liveness` and the optimised
+`ruby -e`, which in this image are both available and must agree.
+
+```
+worker-0 stale 120s > 45s   # exit 1
+1 process(es) healthy       # exit 0, twelve seconds later
+```
+
+### 3. The broker takes the consumer away
+
+The one that matters. Delete a queue the worker consumes from:
+
+```bash
+kubectl exec deploy/rabbitmq -- rabbitmqctl delete_queue kicks_liveness.alpha
+```
+
+Observed, from the moment of deletion:
+
+| after the deletion | what |
+|---|---|
+| 9 s | `ERROR: [liveness] slot 0: became unhealthy (expected 2 consumers)` |
+| 59 s | `ERROR: [liveness] slot 0: not healthy 60s, expected 2 consumers` |
+| 61 s | first kubelet failure: `Liveness probe failed: worker-0 stale 69s > 45s` |
+| 91 s, 121 s | the second and third, `stale 99s` and `stale 129s` |
+| 132 s | `Killing: Container worker failed liveness probe, will be restarted` |
+
+The two clocks in that table are different, which is worth reading carefully
+if you are checking the arithmetic. The left column counts from the deletion.
+The `stale Ns` in the probe's own text is the age of the mark, and the mark
+stopped being refreshed one tick *before* the transition was logged — the tick
+that found the process unhealthy is also the first one that did not touch the
+file. So the probe's number runs about eight seconds ahead of the left column,
+and the kill lands at `max_age + periodSeconds × failureThreshold` counted
+from the last refresh, not from the deletion.
+
+So `any_consumers?` does turn false, the transition is reported within one tick,
+and the pod is restarted after `max_age + periodSeconds × failureThreshold`
+— 132 s against the 135 s the arithmetic in KUBERNETES.md predicts. The worker
+re-declares the queue on boot, so the pod recovers by itself.
+
+Note where the probe's own text appears: in the kubelet's `Unhealthy` event,
+not in the pod log. An exec probe's stdout goes nowhere else, which is why
+`kubectl describe pod` is the place to read it.
+
+### 4. The broker dies
+
+```bash
+kubectl delete pod -l app=rabbitmq --grace-period=0 --force
+```
+
+The pod must **not** restart. "It survived" is not enough on its own — a broker
+that never actually went away would look the same — so check the log for
+Bunny's own account of the outage:
+
+```
+WARN: Recovering from connection.close (CONNECTION_FORCED - broker forced connection closure with reason 'shutdown')
+WARN: Will recover from a network failure (no retry limit)...
+WARN: Could not establish TCP connection to rabbitmq:5672 ... TCP connection failed
+WARN: Reconnecting in 5.0 seconds
+```
+
+Against that: `restartCount` stayed 0, the probe exited 0 at every check, and
+no `became unhealthy` was logged. Bunny's topology recovery brought both
+consumers back on its own.
+
+### 5. The broker stays dead
+
+`kubectl scale deploy/rabbitmq --replicas=0`, then wait. Observed over 319 s
+— seven times `max_age`, more than twice the 135 s steady-state budget — the
+mark's age never exceeded 9 s and `restartCount` stayed 0. The monitor kept
+writing, because `recovering_from_network_failure?` never stops being true:
+Bunny has no retry limit, which its own log line above says out loud.
+
+This is
+[Broker unavailability is invisible by design](LIMITATIONS.md#broker-unavailability-is-invisible-by-design),
+seen rather than deduced. It is the reason the
+[consumer alert](KUBERNETES.md#required-companion-an-alert-on-consumers) is part
+of the design and not a suggestion.
+
+Scaling the broker back up: the worker resumed consuming **in the same
+container**, no restart.
+
+### 6. An ordinary deploy
+
+`kubectl delete pod` on the worker, with the log followed. Not one ERROR line.
+Bunny cancels each consumer and the process exits.
+
+If the shutdown finishes inside a single tick — an idle thread pool cancels
+quickly — the monitor never gets to run again, so
+`shutting down: consumers are no longer checked` may not appear at all. The
+absence of ERROR is the observable, not the presence of that line.
+
+### 7. Bad broker credentials
+
+Point `AMQP_URL` at a wrong password. The fork cannot subscribe, so the
+supervisor respawns it every `start_worker_delay`, forever. Over 120 s:
+
+| | lines |
+|---|---|
+| fork starts | 426 |
+| `started: dir=... consumers=2` | 1 |
+| `waiting for 2 consumers` | 1 |
+| liveness ERROR | 2 |
+
+```
+INFO:  [liveness] slot 0: started: dir=/opt/app/tmp/health max_age=45s tick=10s processes=1 consumers=2
+INFO:  [liveness] slot 0: waiting for 2 consumers
+ERROR: [liveness] slot 0: not healthy 60s over 224 starts, expected 2 consumers
+ERROR: [liveness] slot 0: not healthy 60s over 426 starts, expected 2 consumers
+```
+
+Four lines from the gem across 426 respawns: the first incarnation announces
+itself and reports waiting, every one after that is silent, and the escalation
+speaks once per grace window carrying the number of starts, which is the
+diagnosis. This is the behaviour
+[the respawn section](LIMITATIONS.md#a-respawn-loop-is-reported-once-per-grace-window-not-once-per-respawn)
+describes, against a real storm rather than a simulated one.
+
+Worth knowing what the pod log looks like anyway: 27 000 lines in those same
+120 s, an authentication error and a full backtrace printed by the worker gem on
+every respawn. The gem's four lines are in there — `grep liveness` is how you
+find them.
+
+### 8. More than one fork
+
+`WORKER_COUNT=2` needs no rebuild; the rake task turns it into
+`config[:workers]`.
+
+```
+INFO: [liveness] slot 0: started: ... processes=2 consumers=2
+INFO: [liveness] slot 1: started: ... processes=2 consumers=2
+expected  worker-0  worker-1      # expected contains "2"
+2 process(es) healthy             # exit 0
+worker-1 stale 120s > 45s         # exit 1 — staling either mark is enough
+```
+
+Both marks are required, not just the first.
+
+One trap while checking this by hand: `kubectl exec deploy/worker` picks any pod
+matching the deployment, and during a rollout that can still be the old one.
+Read the marks on a pod named explicitly.
+
+### 9. A rolling deploy keeps the queue covered
+
+Scenario 6 kills a pod outright. A deploy is the more interesting case,
+because KUBERNETES.md claims the startup probe *incidentally fixes rollouts
+where the old pod was removed before the new one had subscribed* — and that
+claim is about ordering, which needs two pods to be watched at once.
+
+`kubectl rollout restart deploy/worker`, with `WORKER_COUNT=2`, so a fully
+subscribed pod is worth two consumers per queue. Counting consumers on the
+broker is what makes the ordering visible:
+
+| after | consumers on the queue | pods |
+|---|---|---|
+| 1 s | 2 | old Ready, new Pending |
+| 10 s | **4** | old Ready, new Running but **not** Ready |
+| 16 s | — | the old pod cancels its consumers |
+| 18 s | 2 | new pod only, Ready |
+
+Coverage went 2 → 4 → 2 and never dipped. The new pod had subscribed before
+the old one was asked to stop, and the old one logged no ERROR on its way out.
+
+The mechanism is worth being explicit about, because it is the probe doing it:
+a container running its startup probe is not Ready, and with one replica
+`maxUnavailable: 25%` rounds down to zero, so Kubernetes may not remove the
+old pod until the new one is Ready. Readiness here means *the mark is on
+tmpfs*, which means the consumers are subscribed. A probe that answered on
+process liveness instead would have released the old pod while the new one was
+still booting.
+
+### 10. The alert's metric is the one the docs name
+
+The [consumer alert](KUBERNETES.md#required-companion-an-alert-on-consumers) is
+part of the design, not a suggestion — so its expression deserves the same
+treatment as everything else here. The broker in this fixture is enough to check
+it; the plugin is not on by default:
+
+```bash
+kubectl exec deploy/rabbitmq -- rabbitmq-plugins enable rabbitmq_prometheus
+```
+
+Then read all three endpoints from the worker pod, which has a Ruby but no
+`curl`:
+
+```bash
+kubectl exec deploy/worker -- ruby -rnet/http -e \
+  'puts Net::HTTP.get(URI("http://rabbitmq:15692/metrics/detailed?family=queue_consumer_count"))'
+```
+
+Recorded on RabbitMQ 3.13.7:
+
+| endpoint | what comes back |
+|---|---|
+| `/metrics` | `rabbitmq_queue_consumers 4` — one label-less cluster total |
+| `/metrics/detailed` | telemetry and build info only, no queue metrics |
+| `/metrics/detailed?family=queue_consumer_count` | `rabbitmq_detailed_queue_consumers{vhost="/",queue="kicks_liveness.alpha"} 2` |
+
+Three things follow, and all three are now in the manifest documentation: the
+metric is a *different* name from the aggregate, the detailed endpoint needs the
+`family` parameter, and the series carries a `vhost` label.
+
+Then check the two halves of the alert against a throwaway queue — declare one
+with no consumers, scrape, delete it, scrape again:
+
+```
+-- queue exists, zero consumers
+   rabbitmq_detailed_queue_consumers{vhost="/",queue="kicks_liveness.tmpcheck"} 0
+-- queue deleted
+   (no such series)
+```
+
+Both halves matter and they are different failures. An **idle** queue reports
+`0`, which is what `== 0` is for. A **deleted** queue reports nothing at all,
+and neither does a stopped broker or a stopped exporter — so `== 0` cannot fire
+on the very failure scenario 3 demonstrates, where the queue goes away and the
+pod is restarted. That is why the documented rule set pairs it with
+`absent_over_time`, and why an `up == 0` on the scrape job is worth having
+beside both.
+
+## What to do with a disagreement
+
+Record it, then fix whichever is wrong — the code or the document. The numbers
+above are a baseline: the arithmetic in KUBERNETES.md is meant to predict them,
+and a scenario that lands far from its prediction means one of the two is out of
+date.

data/exe/kicks-liveness

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require 'kicks_liveness/probe'

data/lib/kicks_liveness/attempts.rb

@@ -0,0 +1,86 @@
+require 'fileutils'
+
+module KicksLiveness
+  # Counts starts of a supervisor slot that have not reached healthy yet.
+  #
+  # Deliberately separate from {Heartbeat}. Heartbeat is the contract shared
+  # with the probe and is loaded by it alone, so nothing the probe does not need
+  # belongs there — including the +fileutils+ this class requires freely.
+  #
+  # The count lives in the marks directory rather than in memory because a
+  # respawn storm destroys process state every few hundred milliseconds: the
+  # supervisor brings a failing fork back after +start_worker_delay+, and every
+  # incarnation of the monitor believes it is the first. That is how an outage
+  # can produce thousands of identical INFO lines and not one ERROR. The
+  # directory is the only state that survives the fork.
+  #
+  # @see file:docs/DESIGN.md#logging-events-not-the-pulse
+  # @api private
+  class Attempts
+    # @param dir [String] marks directory
+    def initialize(dir)
+      @dir = dir
+    end
+
+    # Records a start of this slot.
+    #
+    # @param slot [Integer] supervisor slot of this fork
+    # @param now [Time] injected in specs
+    # @return [Array(Integer, Float)] this start's number, and seconds since the
+    #   first start of the current unhealthy run
+    def record!(slot, now: Time.now.utc)
+      count, first = read(slot)
+      first ||= now
+      write(slot, count + 1, first)
+      [count + 1, now - first]
+    end
+
+    # Resets the elapsed-time window while keeping the count, so a respawn loop
+    # reports once per window instead of once per respawn.
+    #
+    # @param slot [Integer]
+    # @param now [Time]
+    # @return [void]
+    def restart_window!(slot, now: Time.now.utc)
+      count, = read(slot)
+      write(slot, count, now)
+    end
+
+    # Called once the slot is healthy: the next start of it is a fresh one.
+    #
+    # @param slot [Integer]
+    # @return [void]
+    def clear!(slot)
+      File.unlink(path(slot))
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def path(slot)
+      File.join(@dir, "attempt-#{slot}")
+    end
+
+    # A missing or unreadable counter means "no previous start", never an
+    # exception: this is instrumentation, and it may not break a worker.
+    def read(slot)
+      count, epoch = File.read(path(slot)).split
+      [Integer(count), Time.at(Integer(epoch)).utc]
+    rescue StandardError
+      [0, nil]
+    end
+
+    # Failing to write degrades the reporting back to one line per respawn,
+    # which is noisy but harmless — so a read-only directory is swallowed here
+    # rather than escalated.
+    def write(slot, count, first)
+      FileUtils.mkdir_p(@dir)
+      tmp = "#{path(slot)}.#{Process.pid}"
+      File.write(tmp, "#{count} #{first.to_i}\n")
+      File.rename(tmp, path(slot))
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/kicks_liveness/configuration.rb

@@ -0,0 +1,83 @@
+require_relative 'heartbeat'
+
+module KicksLiveness
+  # What the application may configure, and what comes from the environment only.
+  #
+  # +dir+ and +max_age+ are deliberately read-only here: the probe runs as a
+  # separate process launched by the container runtime and cannot read the
+  # application's initializer. Were they settable in both places, a mismatch
+  # between what the worker writes and what the probe expects would pass
+  # unnoticed.
+  #
+  # @see file:docs/SETUP.md#configuration
+  # @see file:docs/DESIGN.md#what-is-configurable-and-where
+  class Configuration
+    # @return [Integer] default seconds between checks
+    DEFAULT_TICK = 10
+    # @return [Integer] unhealthy ticks tolerated at startup before one ERROR
+    DEFAULT_STARTUP_GRACE_TICKS = 6
+
+    # @return [Integer] seconds between checks
+    attr_reader :tick
+    # @return [Integer] unhealthy ticks tolerated at startup before one ERROR
+    attr_accessor :startup_grace_ticks
+    # @return [Logger, nil] explicit logger; defaults to +Sneakers.logger+
+    attr_accessor :logger
+    # @param value [Boolean] set false to start no monitor thread, e.g. in tests
+    attr_writer :enabled
+
+    def initialize
+      @tick = Heartbeat.env_int(:tick, DEFAULT_TICK)
+      @startup_grace_ticks = DEFAULT_STARTUP_GRACE_TICKS
+      @enabled = true
+      @logger = nil
+    end
+
+    # @return [Boolean]
+    def enabled?
+      @enabled
+    end
+
+    # A tick is what the monitor thread sleeps on, so a non-positive value is
+    # not a setting but a broken monitor. The environment gets a silent fallback
+    # instead (see {Heartbeat.env_int}) because a ConfigMap typo must not bring
+    # a worker down; an initializer is code, and code should say so at boot,
+    # where the developer is looking.
+    #
+    # @param seconds [Integer]
+    # @raise [ArgumentError] if not a positive number
+    # @return [Integer]
+    def tick=(seconds)
+      raise ArgumentError, "tick must be a positive number, got #{seconds.inspect}" unless positive_number?(seconds)
+
+      @tick = seconds
+    end
+
+    # Read-only, sourced from the environment so that it matches what the probe
+    # sees.
+    # @return [String] marks directory
+    def dir
+      Heartbeat.env_dir
+    end
+
+    # Read-only, sourced from the environment so that it matches what the probe
+    # sees.
+    # @return [Integer] seconds after which a mark is considered stale
+    def max_age
+      Heartbeat.env_max_age
+    end
+
+    # Resolved lazily: at the time this object is built, +Sneakers.logger+ may
+    # not be configured yet.
+    # @return [Logger, false, nil]
+    def resolved_logger
+      @logger || (defined?(::Sneakers) && ::Sneakers.logger)
+    end
+
+    private
+
+    def positive_number?(value)
+      value.is_a?(Numeric) && value.positive?
+    end
+  end
+end