kicks_liveness 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 206f62be48c616553a219c499e1106beb68a49fd3c91ca30a1d7f3ee812c15f7
-  data.tar.gz: b2edcb9d1a6dd351df5b7a25d27e358582def6b6d8cdc4f7ad70b055ad1c25a9
+  metadata.gz: 3c784de1ca564182e9e36f8fb2956bb61a854c50995bdfe656c68805df671aed
+  data.tar.gz: e40f05ab3385e7b6dd680e040888120693751bda5ff5b2ff2625e107c4ff7cf9
 SHA512:
-  metadata.gz: 06caaf5bfe502f5a83eebe11d03a8122f91ad03672fe2b11f046143ed107d6b81d126344cc293afc2ee311c6fb2f1a1f42739e82ff37b3e737cad7d3b71d97fb
-  data.tar.gz: 6cf539fef1a39318702015363035bc8f1538fa9cabaaa6543eca038a62059db98a21b9b82a2a53be62a0315e6872adc7b6891c586df52d1bff3700b2071eb700
+  metadata.gz: e4e1088cc18b3a51493f330e2f37b3eba223dd6b21be77adcaf50833362a29b805d35f7d851ad31a2f84f2d7a9e5b69792cf443fd5cac2e8b2a44e53d70b9f29
+  data.tar.gz: 99345f3a010f4f6c72936e80a81fdff2a6ebf0ea371596bc90850b47cfe5abacaa93694b629fd9121de386e04a5272d44b46b3425f88229ae66c2e3fc0c555f7

data/.yardopts

@@ -0,0 +1,13 @@
+--markup markdown
+--readme README.md
+--title "kicks_liveness"
+--no-private
+lib/**/*.rb
+-
+docs/SETUP.md
+docs/DESIGN.md
+docs/KUBERNETES.md
+docs/LIMITATIONS.md
+docs/VERIFYING.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -3,6 +3,45 @@
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.1.1] - 2026-09-09
+
+### Added
+
+- Add a repository-hosted social-preview asset for the project documentation.
+
+### Changed
+
+- Rework the README into a shorter entry point while retaining the operational
+  detail in the focused guides under `docs/`.
+- Reject initializer values where `tick >= max_age`, and require
+  `startup_grace_ticks` to be a positive integer. Initializers that previously
+  supplied either invalid value now stop application boot with `ArgumentError`.
+- Reject bundles that activate both `kicks` and `sneakers` with `LoadError`
+  instead of letting their shared `lib/sneakers.rb` resolve silently by
+  load-path order. Applications that still bundle both worker gems must remove
+  one before upgrading.
+- Replace the contributor-only `AMQP_WORKER_GEM` and
+  `AMQP_WORKER_GEM_VERSION` test selection with Appraisal-generated dependency
+  sets, including current and supported-floor targets for both worker gems.
+
+### Fixed
+
+- Recover environment values where `tick >= max_age` with a warning and a safe
+  interval, preventing a healthy heartbeat from becoming stale between normal
+  monitor ticks.
+- Keep worker startup, heartbeat publication, and the monitor loop alive when a
+  custom logger raises while handling an INFO or ERROR event.
+- Correct the runtime-scaling documentation: live changes to `workers` are not
+  supported in either direction. During scale-up, old and new forks otherwise
+  race to publish different expected counts; during scale-down, retired slots
+  remain expected.
+- Strengthen the release gate with floor-version coverage, style checks, tag
+  ancestry validation, and a packaged-executable smoke test.
+- Include `.yardopts` in the gem so RubyDoc builds the intended README and
+  public guide set from the packaged release.
+
 ## [0.1.0] - 2026-09-08
 
 ### Added
@@ -18,4 +57,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   [docs/](https://github.com/PoroshkinaVV/kicks_liveness/tree/main/docs); start
   with `SETUP.md`, and read `LIMITATIONS.md` before relying on it.
 
+[Unreleased]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/PoroshkinaVV/kicks_liveness/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/PoroshkinaVV/kicks_liveness/releases/tag/v0.1.0

data/README.md

@@ -1,119 +1,69 @@
 # kicks_liveness
 
-A liveness probe for [Kicks](https://github.com/ruby-amqp/kicks) workers (and
-for its predecessor Sneakers): the worker itself publishes a liveness mark to
-tmpfs, and the probe only reads it.
+[![Gem Version](https://badge.fury.io/rb/kicks_liveness.svg)](https://rubygems.org/gems/kicks_liveness)
+[![CI](https://github.com/PoroshkinaVV/kicks_liveness/actions/workflows/ci.yml/badge.svg)](https://github.com/PoroshkinaVV/kicks_liveness/actions/workflows/ci.yml)
 
-## Documentation
+![kicks_liveness — Kicks and Sneakers worker health](https://raw.githubusercontent.com/PoroshkinaVV/kicks_liveness/main/assets/github-social-preview.png)
+
+**Know when a [Kicks](https://github.com/ruby-amqp/kicks) or
+[Sneakers](https://github.com/jondot/sneakers) worker is stuck — without booting
+Rails or querying RabbitMQ from the probe.**
 
-- [docs/SETUP.md](docs/SETUP.md) — installation and wiring: Rails, Sinatra,
-  Hanami, Roda, and no framework at all; what `install!` does and when to call
-  it.
-- [docs/DESIGN.md](docs/DESIGN.md) — why the gem is built this way: the health
-  predicate, the mark files, slots instead of PIDs, where the hooks attach, what
-  is configurable and why `dir` and `max_age` live in the environment only.
-- [docs/KUBERNETES.md](docs/KUBERNETES.md) — the manifest, the budget
-  arithmetic, verifying on a live pod, the alert on consumers.
-- [docs/LIMITATIONS.md](docs/LIMITATIONS.md) — where the in-memory predicate
-  stops being truthful.
-- [docs/VERIFYING.md](docs/VERIFYING.md) — the runbook that causes the real failures on a local cluster: what was observed, and how long each took.
-
-## Why
-
-The usual implementation is a rake task that boots Rails and asks RabbitMQ for
-`consumer_count`. It has three defects that cannot be fixed in place:
-
-1. **It is expensive.** Booting Rails every few seconds inside the worker's own
-   cgroup. On one real service this cost 2.7 s per invocation on a 15 s
-   period — 38% of the container's CPU request, around the clock.
-2. **It depends on the disk.** A disk that stalls for a few seconds stretches
-   the boot past `timeoutSeconds`, and the kubelet kills a healthy pod.
-3. **It cascades.** A liveness probe that checks an external dependency turns a
-   broker hiccup into every replica restarting at once, finishing the broker off.
-
-On top of that, `consumer_count` is a metric of the **queue**, not of the pod:
-with two replicas the live one covers for the stalled one, and the probe cannot
-tell.
-
-This gem inverts that. Every 10 seconds the worker checks, against the Bunny
-objects **in its own memory**, that its consumers are in place, and touches a
-file. The standard probe invocation took 156 ms in the fixture container, makes
-no network call, boots no framework, and reads the state it judges from tmpfs,
-which is RAM. It does still load Bundler, the interpreter and the gem's probe
-files from the image filesystem, so the disk is not out of the picture
-altogether — it is reduced to a small process startup instead of a full
-application boot on every probe.
-
-## Installation
+The worker checks its own Bunny consumers and publishes a heartbeat to tmpfs.
+The probe only reads that heartbeat. No application boot, no network call, and
+no healthy replica hiding a stalled one.
+
+## Install: one line in Rails
 
 ```ruby
+# Gemfile — keep exactly one of kicks or sneakers alongside it
 gem 'kicks_liveness'
 ```
 
-You need `kicks` (>= 3.0) **or** `sneakers` (>= 2.11). Neither is declared as a
-dependency of this gem, on purpose: at runtime only the `Sneakers` namespace is
-required, and both gems provide it. If neither is present, `install!` raises a
-`LoadError` naming both. Both floors are exercised in CI at their exact
-versions, not just through a `~>` that resolves to the newest release.
-
-Keeping both gems in one `Gemfile` is **not** allowed, and nothing enforces
-that: not Bundler, not a crash at boot. Both own the file `lib/sneakers.rb`, so
-one silently wins the load path. An application that has moved to `kicks` would
-keep executing `sneakers` 2.12 code while its `Gemfile.lock` claims otherwise.
-`sneakers` also caps the `kicks` and `bunny` versions.
-
-The gem installs its hooks itself through a Railtie. Outside Rails, call
-`KicksLiveness.install!` before the runner starts: the tie to Rails is a single
-conditionally required file; it is not loaded outside Rails, and no Rails code is
-pulled in. The details, including the one genuine restriction — workers must be
-started through `Sneakers::Runner` — are in [docs/SETUP.md](docs/SETUP.md).
-
-### Initializer
+```bash
+bundle install
+```
 
-Optional. For example, a Rails application can disable the monitor locally:
+In Rails, that is all the application-side setup: the Railtie installs the hooks
+automatically. Without Rails, add two lines before `Sneakers::Runner` starts:
 
 ```ruby
-KicksLiveness.configure do |config|
-  config.enabled = !Rails.env.local?
-end
+require 'kicks_liveness'
+KicksLiveness.install!
 ```
 
-The full list: `logger` (defaults lazily to `Sneakers.logger`), `enabled`,
-`tick` (10 s), `startup_grace_ticks` (6).
-A non-positive `tick` raises `ArgumentError`: the monitor thread sleeps on it,
-so a non-positive value is not a setting but a broken monitor.
+Requirements: Ruby >= 3.1 and exactly one of `kicks` >= 3.0 or `sneakers` >=
+2.11. CI pins both floors and tracks the current release of both worker lines.
+Do not put both worker gems in the same bundle: both provide
+`lib/sneakers.rb`, so `install!` rejects that ambiguous process.
+Framework-specific examples are in [Setup](docs/SETUP.md).
+
+## Why replace the usual probe?
 
-### Environment variables
+The common alternative is a rake task that boots the application and asks
+RabbitMQ for `consumer_count`.
 
-| Variable | Default | |
+| | Rails + `consumer_count` probe | `kicks_liveness` |
 |---|---|---|
-| `KICKS_LIVENESS_DIR` | `/opt/app/tmp/health` | marks directory, **must live on tmpfs** |
-| `KICKS_LIVENESS_MAX_AGE` | `45` | seconds after which a mark is stale |
-| `KICKS_LIVENESS_TICK` | `10` | interval between ticks |
-
-`tick` is the one setting that appears in both places; the initializer wins over
-the variable, and only the worker reads it either way.
-
-**Two runners in one pod need two directories.** An application that runs both
-`rake sneakers:run` and `rake sneakers:active_job` has two supervisors, each
-numbering its forks from zero — so with the default `KICKS_LIVENESS_DIR` they
-would overwrite each other's `expected` and `worker-0`, and the probe would
-answer for whichever wrote last. In separate pods, which is the usual
-arrangement, there is nothing to do: each gets its own `emptyDir`. In one pod,
-give each runner its own `KICKS_LIVENESS_DIR`.
-
-`dir` and `max_age` deliberately **cannot** be set in the initializer. The probe
-is launched by the kubelet as a separate process, which does not — and cannot —
-read the application's initializer. Were they settable in two places, a
-mismatch between the worker and the probe would pass unnoticed.
-
-Garbage in a value does not bring the worker down — it falls back to the default.
-An empty string counts as unset: in a ConfigMap that is what you get by
-declaring a key and leaving it blank. `max_age` and `tick` are durations, so
-zero and negative values fall back too: they parse perfectly well, and a
-negative `max_age` would make every mark stale on arrival.
-
-## Manifest
+| Code started on every probe | Rails and the application | Ruby, Bundler, and the probe files |
+| Network call | RabbitMQ request | none |
+| Health scope | a queue shared by every replica | this worker process |
+| Decision path | application files plus RabbitMQ | process memory plus a tmpfs heartbeat |
+| Measured invocation | **2.7 s of CPU** on a real service | **156 ms** in the fixture container |
+| Continuous cost in the measured setups | **~0.18 core** at a 15 s period | **~0.005 core** at a 30 s period |
+| During Bunny network recovery | may restart every replica together | stays healthy while Bunny reconnects |
+
+Absolute timings depend on the image and hardware; the two columns are measured
+examples, not a same-host microbenchmark. The calculation and faster 52 ms and
+~10 ms probe forms are documented in [Running under Kubernetes](docs/KUBERNETES.md#why-the-command-looks-like-that).
+
+Every 10 seconds by default, each worker verifies that all expected consumers
+are subscribed and touches its own mark. `bundle exec kicks-liveness` exits 0
+only when every expected worker mark is present and fresh.
+
+## Kubernetes
+
+Use a startup probe for the boot budget and a liveness probe for steady state:
 
 ```yaml
         startupProbe:
@@ -131,7 +81,7 @@ negative `max_age` would make every mark stale on arrival.
       terminationGracePeriodSeconds: 60
 ```
 
-The marks directory has to be on tmpfs:
+Put the heartbeat directory on tmpfs:
 
 ```yaml
         volumeMounts:
@@ -140,180 +90,108 @@ The marks directory has to be on tmpfs:
       volumes:
         - name: app-tmp
           emptyDir:
-            medium: Memory        # without this the mark lands on disk
+            medium: Memory
 ```
 
-The container needs a writable volume mounted at, or above,
-`KICKS_LIVENESS_DIR`. The default mount at `/opt/app/tmp` covers
-`/opt/app/tmp/health`, and the gem creates the `health` subdirectory itself.
-Without this mount, a container using `readOnlyRootFilesystem: true` cannot
-publish heartbeat files and never passes the startup probe.
-
-Why it looks like this:
-
-- **`bundle exec kicks-liveness` is the standard command**, and it works
-  regardless of where Bundler installed the gems. There is a faster form —
-  `ruby -e "require 'kicks_liveness/probe'"`, 52 ms against
-  156 ms — but it needs the gems to be in `GEM_HOME`, and **setting
-  `BUNDLE_PATH` at all moves them**, even to the directory `GEM_HOME` already
-  points at. Check before you optimise:
-
-  ```bash
-  docker run --rm your-image bundle exec kicks-liveness
-  docker run --rm your-image ruby -e "require 'kicks_liveness/probe'"
-  ```
-
-  Both should print `no .../expected` and exit 1. If the second raises
-  `LoadError`, keep the standard command — at `periodSeconds: 30` it costs about
-  0.005 of a core, against roughly 0.18 for a probe that boots the application.
-  The trade-offs are in
-  [docs/KUBERNETES.md](docs/KUBERNETES.md#where-your-image-puts-its-gems).
-
-- **`startupProbe` is mandatory.** Startup and steady state have different time
-  budgets, and one probe cannot serve both. While it runs, liveness is disabled
-  and the container is not Ready. `failureThreshold: 60` buys 300 s, which is
-  deliberately generous — measure a *freshly created* pod before trimming it, as
-  a restarted container inherits a warm compile cache and a new pod does not:
-  [measure the cold start](docs/KUBERNETES.md#measure-the-cold-start-not-the-restart).
-- **It also protects rollouts — given `maxUnavailable: 0`.** Because the
-  container is not Ready until the mark exists, a `RollingUpdate` that is not
-  allowed to drop below full capacity cannot remove the old pod before the new
-  one has subscribed. That is a property of the strategy as much as of the probe:
-  with a non-zero `maxUnavailable`, or with `Recreate`, the old pod may go first
-  and leave the queue uncovered.
-- **`initialDelaySeconds` on liveness is unnecessary**; the startupProbe plays
-  that role.
-- Before a kill there is `max_age + periodSeconds × failureThreshold` = 45 + 90 =
-  **135 s** of confirmed silence. Slow on purpose: a worker is not
-  latency-critical, and a false restart costs more than two minutes of stalling.
-
-## Required companion: an alert on consumers
-
-The probe deliberately reports healthy while Bunny is reconnecting — otherwise a
-broker hiccup would restart every replica at once. The price is that **broker
-unavailability stops being visible automatically**. A pod can be consuming
-nothing and look perfectly healthy.
-
-So the probe needs an alert alongside it, and that alert should be in place
-**before** the manifest is switched over:
+The default heartbeat directory is `/opt/app/tmp/health`; the gem creates the
+`health` subdirectory. The mount is also required with
+`readOnlyRootFilesystem: true`.
 
-```yaml
-- alert: QueueWithoutConsumers
-  expr: rabbitmq_detailed_queue_consumers{queue=~"myapp\..+", queue!~".*delayed_active_job.*"} == 0
-  for: 5m
-
-# Not optional: the expression above cannot fire when the series is gone.
-- alert: QueueConsumerMetricMissing
-  expr: absent_over_time(rabbitmq_detailed_queue_consumers{queue=~"myapp\..+"}[10m])
-  for: 5m
-```
+With the values above, confirmed silence lasts at most `45 + 30 × 3 = 135 s`
+before Kubernetes kills the container. Size the startup budget from fresh-pod
+measurements, not warm restarts. See [the full manifest and budget
+arithmetic](docs/KUBERNETES.md).
 
-Excluding the delayed queues is mandatory — they have no consumers by design, and
-without the exclusion the alert fires permanently until someone silences it.
-Match them as a **substring**: under ActiveJob the full name looks like
-`myapp.active_job.myapp.delayed_active_job:60`, so an anchored pattern never
-matches.
+## Configuration
 
-Two traps in getting that metric, both measured on RabbitMQ 3.13.7 rather than
-recalled. The per-queue series is `rabbitmq_detailed_queue_consumers`, and it
-only exists on `/metrics/detailed` **scraped with `family=queue_consumer_count`**
-— bare, that endpoint serves no queue metrics at all, while plain `/metrics`
-offers a same-sounding `rabbitmq_queue_consumers` that is a single label-less
-cluster total, so a `{queue=~...}` matcher against it is quietly never true. And
-the series **disappears** rather than going to zero when the queue is deleted or
-the broker stops, which is why the second alert is there.
-[docs/KUBERNETES.md](docs/KUBERNETES.md#getting-that-metric-at-all) has the
-scrape config.
+Everything is optional. Application settings belong in an initializer:
 
-## What is checked
+```ruby
+KicksLiveness.configure do |config|
+  config.enabled = !Rails.env.local?
+end
+```
 
-The mark is written only if **every** worker in the process has subscribed:
+| Ruby setting | Default | Purpose | Valid values |
+|---|---|---|---|
+| `logger` | `Sneakers.logger`, resolved lazily | transition and error logs | logger-compatible object |
+| `enabled` | `true` | start the monitor thread | `true` or `false` |
+| `tick` | `10` | seconds between worker checks | positive number smaller than `max_age` |
+| `startup_grace_ticks` | `6` | unhealthy startup ticks before one ERROR | positive integer |
 
-| State | Verdict |
-|---|---|
-| consumers in place, channel open | healthy |
-| Bunny is recovering the connection | **healthy** — the broker heals itself |
-| connection open, no consumers | unhealthy, a restart is the cure |
-| not the whole set subscribed | unhealthy |
+The separate probe cannot read an application initializer. The shared path and
+freshness threshold therefore come from the environment; `tick` may use the
+environment too:
 
-The expected consumer count comes from `config[:worker_classes]` — the same set
-kicks itself builds its workers from. That way the queue list is never
-duplicated and cannot drift from the configuration.
+| Environment variable | Default | Purpose | Invalid or blank value |
+|---|---|---|---|
+| `KICKS_LIVENESS_DIR` | `/opt/app/tmp/health` | heartbeat directory; must be on tmpfs | uses the default |
+| `KICKS_LIVENESS_MAX_AGE` | `45` | seconds before a mark is stale | uses the default |
+| `KICKS_LIVENESS_TICK` | `10` | seconds between worker checks | uses the default, then the safety fallback below if needed |
 
-The files are named by supervisor slot rather than by PID: a dead fork is
-respawned into the same slot and overwrites its own file. With a PID in the
-name, SIGKILL would leave a stale file forever. With `workers > 1` the probe
-requires every slot to be fresh.
+If the effective environment tick is not smaller than `max_age`, the worker
+writes a WARN to stderr and uses `10` seconds when that is safe, or half of
+`max_age` otherwise. This keeps a ConfigMap mistake from stopping the worker
+while guaranteeing that a healthy heartbeat cannot become stale between
+ordinary ticks.
 
-## Limitations
+An initializer value for `tick` wins over `KICKS_LIVENESS_TICK`. `dir` and
+`max_age` deliberately have no initializer setters: allowing two configuration
+sources could make the worker and probe silently disagree.
 
-The predicate is computed over the Bunny objects **in the process's memory** —
-that is the whole point, but it has a boundary: it is exactly as truthful as
-Bunny's own bookkeeping. The broker is never asked for its opinion.
+If two runners share one pod — for example `sneakers:run` and
+`sneakers:active_job` — give each a different `KICKS_LIVENESS_DIR`. Separate
+pods already have separate `emptyDir` volumes.
 
-**1. Consumer bookkeeping is updated on the worker's thread pool.** When the
-broker cancels a consumer (on `consumer_timeout`, for example), it sends
-`basic.cancel`, and Bunny removes the entry from its list — but it does so
-through `@work_pool.submit`, that is, on the same pool that processes jobs
-(`threads: 10` by default). Until a thread frees up, `any_consumers?` still
-answers yes.
+## What is healthy?
 
-In practice this means: if **all** of the worker's threads are busy with stuck
-jobs, the probe stays green even though the pod is consuming nothing. One stuck
-job out of ten does not produce that effect.
+| Worker state | Probe verdict | Reason |
+|---|---|---|
+| every consumer subscribed, channel open | healthy | the process can consume work |
+| Bunny recovering its connection | **healthy** | Bunny reconnects itself; restarting adds a reconnect storm |
+| connection open, no consumers | unhealthy | a restart is the cure |
+| only part of the expected worker set subscribed | unhealthy | one healthy worker must not hide a missing one |
+
+The check reads Bunny objects already in the worker's memory. It never asks the
+broker for its view.
 
-**2. `recover_cancelled_consumers!` makes the probe blind to a cancelled
-consumer.** `Bunny::Channel#recover_cancelled_consumers!` is an opt-in method
-that neither Kicks nor Sneakers enables. With it on, Bunny re-subscribes the
-consumer itself on `basic.cancel` and **keeps** the entry in its list — so the
-"consumer was cancelled" case stops being detectable at all. Do not enable it
-together with this probe.
+## Operational contract
 
-**3. Broker unavailability is invisible by design** — see [the alert on
-consumers](#required-companion-an-alert-on-consumers) above.
+- Start workers through `Sneakers::Runner`; that is where the monitor hook is
+  attached. `rake sneakers:run` already does this.
+- Keep the `startupProbe`. With `RollingUpdate` and `maxUnavailable: 0`, it also
+  keeps the old pod until the new worker has subscribed.
+- Add an external alert for queues with zero or missing consumers **before**
+  switching probes. Broker unavailability is invisible here by design; the
+  exact Prometheus rules are in [Running under Kubernetes](docs/KUBERNETES.md#required-companion-an-alert-on-consumers).
+- Restart the runner after changing its process count; changing `workers` at
+  runtime is not supported.
 
-All three limitations point the same way: an alert on consumers, watching the
-broker **from the outside**, is not a nice-to-have but part of the design. It
-catches exactly what an in-memory predicate cannot see.
+The other boundaries — blocked worker pools, cancelled-consumer recovery, and
+per-pod versus per-queue scope — are collected in [Limitations](docs/LIMITATIONS.md).
 
-## Verifying on a live pod
+## Verify it
 
 ```bash
 kubectl exec deploy/myapp -- ls -l /opt/app/tmp/health/
 kubectl exec deploy/myapp -- sh -c 'bundle exec kicks-liveness; echo "exit=$?"'
-kubectl logs deploy/myapp | grep liveness
 ```
 
-Check the **negative** path too — otherwise a working probe is
-indistinguishable from an always-green one:
-
-```bash
-kubectl exec deploy/myapp -- sh -c 'touch -d "2 minutes ago" /opt/app/tmp/health/worker-0; bundle exec kicks-liveness; echo "exit=$?"'
-```
+The healthy result is `N process(es) healthy` with exit code 0. Also test the
+negative path before rollout; the commands and expected output are in
+[Verifying the probe](docs/VERIFYING.md#2-a-stale-mark).
 
-Expect `worker-0 stale 120s > 45s` and `exit=1`. One tick later the mark repairs
-itself.
+## Documentation
 
-## Logs
+| Guide | Use it for |
+|---|---|
+| [Setup](docs/SETUP.md) | Rails, Sinatra, Hanami, Roda, standalone runners, and hook verification |
+| [Design](docs/DESIGN.md) | health predicate, heartbeat files, hooks, configuration choices, and measurements |
+| [Running under Kubernetes](docs/KUBERNETES.md) | full manifest, CPU/startup budgets, alerts, and live-pod verification |
+| [Limitations](docs/LIMITATIONS.md) | cases the in-memory predicate intentionally cannot cover |
+| [Verification scenarios](docs/VERIFYING.md) | ten deliberately induced failures and their observed outcomes |
 
-Events are logged, not the pulse: the pulse lives in the mark's mtime.
+## Contributing
 
-| Event | Level |
-|---|---|
-| started, with the effective settings | INFO |
-| waiting for consumers | INFO |
-| became healthy | INFO |
-| shutting down | INFO |
-| still not healthy after `startup_grace_ticks` ticks | ERROR |
-| was healthy, became unhealthy | ERROR |
-| a slot respawning without ever becoming healthy, once per grace window | ERROR |
-| the monitor thread caught an exception | ERROR |
-| the monitor could not be started at all | ERROR |
-
-ERROR is reserved for genuine failure: a logger usually comes up with
-`LOG_LEVEL` defaulting to `error`, so anything that matters must survive that
-filter, while an ordinary deploy must not make noise. That is also why shutdown
-is an event of its own: the workers unsubscribe while the thread pool drains,
-and judged by the consumer count alone a normal deploy would look exactly like
-a fault. From the moment shutdown begins the probe keeps the mark fresh
-instead, so a slow drain gets the full `terminationGracePeriodSeconds`.
+Setup, running the suite against both worker gems, and the release procedure are
+in [CONTRIBUTING.md](https://github.com/PoroshkinaVV/kicks_liveness/blob/main/CONTRIBUTING.md).

data/docs/DESIGN.md

@@ -249,7 +249,7 @@ check.
 
 ## What is configurable, and where
 
-| | Where | Why |
+| Setting | Where | Why |
 |---|---|---|
 | `logger`, `enabled`, `startup_grace_ticks` | application config block | only the worker needs them |
 | `tick` | either, and the config block wins | only the worker reads it, so two sources cannot contradict each other |
@@ -281,13 +281,27 @@ makes every mark stale on arrival, so the probe can never pass again. They fall
 back to the default too.
 
 Setting `tick` from the application is held to a stricter standard: a
-non-positive value raises `ArgumentError`. The environment gets a silent fallback
-because a ConfigMap typo must not bring a worker down, whereas an initializer is
-code, and code should fail loudly at boot, where the developer is looking.
+non-positive value raises `ArgumentError`, as does a value greater than or equal
+to `max_age`: such a monitor would inevitably let a healthy mark go stale. The
+environment gets a silent fallback for values that cannot be parsed. If its
+effective tick is greater than or equal to `max_age`, configuration emits a
+warning on stderr and uses the default tick when it is safe, or half of `max_age`
+otherwise. A ConfigMap typo must not bring a worker down, whereas an initializer
+is code and should fail loudly at boot, where the developer is looking.
+
+`startup_grace_ticks` must be a positive integer. It is compared directly with
+an integer counter; accepting zero, a float, or a string would silently disable
+the escalation that is supposed to diagnose a worker that never subscribes.
 
 The logger defaults to `Sneakers.logger` but is resolved lazily, because at the
 time the configuration object is built it may not be set up yet.
 
+Logging is diagnostic; the heartbeat is the liveness contract. An exception
+raised by a custom logger is therefore swallowed at the logging boundary. It
+cannot prevent a healthy tick from writing its mark, abort monitor startup, or
+escape the loop's error handler and kill the monitor thread. No fallback message
+is attempted through the same broken logger.
+
 ## Logging: events, not the pulse
 
 The pulse lives in the mtime of a file; writing a log line every tick would only

data/docs/KUBERNETES.md

@@ -286,15 +286,18 @@ redelivered.
 
 ## Environment variables
 
-| Variable | Default | |
-|---|---|---|
-| `KICKS_LIVENESS_DIR` | `/opt/app/tmp/health` | marks directory, **must be on tmpfs** |
-| `KICKS_LIVENESS_MAX_AGE` | `45` | seconds after which a mark is stale |
-| `KICKS_LIVENESS_TICK` | `10` | interval between ticks |
+| Variable | Default | Purpose | Invalid or blank value |
+|---|---|---|---|
+| `KICKS_LIVENESS_DIR` | `/opt/app/tmp/health` | marks directory, **must be on tmpfs** | uses the default |
+| `KICKS_LIVENESS_MAX_AGE` | `45` | seconds after which a mark is stale | uses the default |
+| `KICKS_LIVENESS_TICK` | `10` | interval between ticks | uses the default, then the safety fallback below if needed |
 
 Keep `tick` well below `max_age`. A tick longer than half of `max_age` leaves no
 room for a single missed write, and a tick longer than `max_age` guarantees a
-restart loop.
+restart loop. If environment values produce `tick >= max_age`, the worker writes
+a WARN to stderr and uses the default tick when that is safe, or half of
+`max_age` otherwise. An initializer value with the same mismatch raises
+`ArgumentError`. The half-threshold remains the recommended operational margin.
 
 `KICKS_LIVENESS_DIR` is also what separates two runners that share a pod. An
 application running both `rake sneakers:run` and `rake sneakers:active_job` has
@@ -315,9 +318,8 @@ probe command pointed at its own directory — the probe reads
 `KICKS_LIVENESS_DIR` from its own environment, which the kubelet takes from the
 container it runs in.
 
-Garbage in a value does not crash the worker — it falls back to the default. An
-empty string counts as unset, which is what a ConfigMap gives you when a key is
-declared and left blank.
+An empty string counts as unset, which is what a ConfigMap gives you when a key
+is declared and left blank.
 
 ## Verifying on a live pod
 

data/docs/LIMITATIONS.md

@@ -80,20 +80,17 @@ see the respawn escalation below.
 
 ## Changing the worker count at runtime is not supported
 
-`ServerEngine` re-reads its configuration on SIGHUP, and a changed `workers`
-value scales the fork set. Scaling **up** is fine. Scaling **down** is only
-handled when the supervisor also restarts the forks, which is what the restart
-path does: the surviving monitors re-declare the current count on their next
-tick and the probe follows.
+`ServerEngine` can re-read its configuration on SIGHUP and scale the fork set,
+but a fork holds its own copy of that configuration from the moment it was
+created. Every monitor re-declares that captured count on every tick.
 
-What cannot be handled is a reload that lowers `workers` while leaving existing
-forks running. `reload_config` executes in the supervisor, and a fork holds its
-own copy of the configuration from the moment it was forked — so a fork cannot
-see the new number however often it looks. The declared count then stays too
-high, the marks for the retired slots go stale, and the probe fails until the
-pod restarts.
+After a scale-up, old forks keep declaring the old count while new forks declare
+the new one. The shared `expected` file therefore depends on which fork wrote
+last; it can temporarily require the new slots, or incorrectly report the old
+set as complete. After a scale-down, the surviving forks keep declaring the old
+count and the retired slots eventually go stale. Neither direction is safe.
 
-If you scale workers, restart them.
+If you change `workers`, restart the runner. Runtime scaling is not supported.
 
 ## A respawn loop is reported once per grace window, not once per respawn
 
@@ -126,7 +123,9 @@ executing the `sneakers` code while its lockfile says otherwise, and pulling in
 resolve.
 
 A loud failure gets fixed; a silent substitution does not. Keep exactly one of
-the two.
+the two. Bundler itself still accepts the combination, but `install!` now
+rejects a process in which both gems are activated before either set of hooks is
+installed.
 
 If neither is present, `install!` raises a `LoadError` naming both with their
 required versions.

data/docs/SETUP.md

@@ -10,7 +10,7 @@ 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
+current release of each. A `~>` matrix on its own would only ever prove that the
 latest version works.
 
 ```ruby
@@ -142,12 +142,15 @@ Set it only to point somewhere **other** than `Sneakers.logger`:
 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 |
+| Option | Default | Purpose | Valid values |
+|---|---|---|---|
+| `logger` | `Sneakers.logger`, resolved lazily | transition and error logs | logger-compatible object |
+| `enabled` | `true` | start the monitor thread | `true` or `false` |
+| `tick` | `10` | seconds between checks | positive number smaller than `max_age` |
+| `startup_grace_ticks` | `6` | unhealthy startup ticks before one ERROR | positive integer |
+
+Invalid combinations are rejected before the monitor starts instead of running
+one that is guaranteed to publish stale marks or never report a stalled startup.
 
 `dir` and `max_age` are **not** here — they come from environment variables
 only. See

data/docs/VERIFYING.md

@@ -30,14 +30,23 @@ it takes.
 
 ```bash
 spec/integration/verify.sh build   # image, into the engine the cluster uses
+spec/integration/verify.sh status  # print and verify the exact target
 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.
+Every `kubectl` call names its context and namespace explicitly, so the script
+never falls back to `current-context`. It will still operate on whichever target
+you configure: run `status` and inspect both values before `up` or `down`. The
+script labels namespaces it creates and refuses to apply to or delete an
+existing namespace without that ownership label.
+
+The default image uses Kicks. Build it with Sneakers instead without editing the
+fixture:
+
+```bash
+AMQP_WORKER_GEM=sneakers spec/integration/verify.sh build
+```
 
 Three things that cost time if you meet them the hard way:
 

data/lib/kicks_liveness/configuration.rb

@@ -17,20 +17,26 @@ module KicksLiveness
     # @return [Integer] unhealthy ticks tolerated at startup before one ERROR
     DEFAULT_STARTUP_GRACE_TICKS = 6
 
-    # @return [Integer] seconds between checks
-    attr_reader :tick
+    # Seconds between checks. An incompatibility warning for an environment
+    # fallback is delayed until this value is actually used, so an initializer
+    # can override it or disable the monitor without a misleading warning.
+    # @return [Numeric]
+    def tick
+      warn_incompatible_environment_tick_once
+      @tick
+    end
     # @return [Integer] unhealthy ticks tolerated at startup before one ERROR
-    attr_accessor :startup_grace_ticks
+    attr_reader :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
+      @tick = environment_tick
     end
 
     # @return [Boolean]
@@ -39,20 +45,36 @@ module KicksLiveness
     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.
+    # not a setting but a broken monitor. An initializer is code, and code
+    # should fail loudly at boot, where the developer is looking. Environment
+    # input is resolved separately by {#environment_tick}, with a safe fallback.
     #
-    # @param seconds [Integer]
+    # @param seconds [Numeric]
     # @raise [ArgumentError] if not a positive number
-    # @return [Integer]
+    # @return [Numeric]
     def tick=(seconds)
       raise ArgumentError, "tick must be a positive number, got #{seconds.inspect}" unless positive_number?(seconds)
+      raise ArgumentError, "tick must be less than max_age (#{max_age}s), got #{seconds.inspect}" if seconds >= max_age
 
+      @incompatible_environment_tick = nil
       @tick = seconds
     end
 
+    # The monitor compares an integer tick counter with this value. Accepting
+    # zero, a float, or a string would silently prevent the startup escalation
+    # from ever firing.
+    #
+    # @param ticks [Integer]
+    # @raise [ArgumentError] unless +ticks+ is a positive integer
+    # @return [Integer]
+    def startup_grace_ticks=(ticks)
+      unless ticks.is_a?(Integer) && ticks.positive?
+        raise ArgumentError, "startup_grace_ticks must be a positive integer, got #{ticks.inspect}"
+      end
+
+      @startup_grace_ticks = ticks
+    end
+
     # Read-only, sourced from the environment so that it matches what the probe
     # sees.
     # @return [String] marks directory
@@ -76,6 +98,47 @@ module KicksLiveness
 
     private
 
+    def environment_tick
+      raw = Heartbeat.env_raw(:tick)
+      seconds = Heartbeat.env_int(:tick, DEFAULT_TICK)
+      threshold = max_age
+      return seconds if seconds < threshold
+
+      fallback = [DEFAULT_TICK, threshold / 2.0].min
+      @incompatible_environment_tick = [seconds, threshold, fallback, raw]
+      fallback
+    end
+
+    def warn_incompatible_environment_tick_once
+      warning = @incompatible_environment_tick
+      return unless warning
+
+      @incompatible_environment_tick = nil
+      warn_incompatible_environment_tick(*warning)
+    end
+
+    def warn_incompatible_environment_tick(seconds, threshold, fallback, raw)
+      Kernel.warn(
+        "WARN [liveness] effective tick=#{seconds}s (#{environment_tick_source(raw)}) must be less than " \
+        "KICKS_LIVENESS_MAX_AGE=#{threshold}s; using #{fallback}s"
+      )
+    rescue StandardError
+      # Configuration recovery must not become a worker boot failure merely
+      # because stderr is unavailable or warning output has been overridden.
+      nil
+    end
+
+    def environment_tick_source(raw)
+      return 'default' if raw.nil?
+
+      value = Integer(raw)
+      return "KICKS_LIVENESS_TICK=#{raw}" if value.positive?
+
+      "default after invalid KICKS_LIVENESS_TICK=#{raw.inspect}"
+    rescue ArgumentError, TypeError
+      "default after invalid KICKS_LIVENESS_TICK=#{raw.inspect}"
+    end
+
     def positive_number?(value)
       value.is_a?(Numeric) && value.positive?
     end

data/lib/kicks_liveness/hooks.rb

@@ -60,7 +60,7 @@ module KicksLiveness
             consumers: kicks_liveness_expected_consumers
           )
         rescue StandardError => e
-          KicksLiveness.config.resolved_logger&.error("[liveness] failed to start: #{e.class}: #{e.message}")
+          report_start_failure(e)
         end
       end
 
@@ -80,6 +80,17 @@ module KicksLiveness
 
       private
 
+      def report_start_failure(error)
+        KicksLiveness.config.resolved_logger&.error(
+          "[liveness] failed to start: #{error.class}: #{error.message}"
+        )
+      rescue StandardError
+        # This is already the failure path. Neither resolving the configuration
+        # again nor a broken logger may let liveness instrumentation stop the
+        # worker process it is meant to observe.
+        nil
+      end
+
       # The same set the worker gem itself builds its workers from, so the
       # queue list is never duplicated and cannot drift. An array of classes
       # under sneakers:run, a callable registry under sneakers:active_job.

data/lib/kicks_liveness/monitor.rb

@@ -173,6 +173,12 @@ module KicksLiveness
 
     def log(level, message)
       @config.resolved_logger&.public_send(level, "[liveness] slot #{@slot}: #{message}")
+    rescue StandardError
+      # Logging is diagnostic, while the heartbeat is the liveness contract. A
+      # broken custom logger must not prevent a mark from being written or kill
+      # the only thread that can refresh it. There is deliberately no fallback
+      # log here: calling the same logger again would only repeat the failure.
+      nil
     end
   end
 end

data/lib/kicks_liveness/version.rb

@@ -1,4 +1,4 @@
 module KicksLiveness
   # @return [String] gem version
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.1.1'.freeze
 end

data/lib/kicks_liveness.rb

@@ -46,10 +46,13 @@ module KicksLiveness
     # <tt>gem 'kicks', require: false</tt> the to_prepare hook runs earlier and
     # would fail on NameError.
     #
-    # @raise [LoadError] if neither +kicks+ nor +sneakers+ is available
+    # @raise [LoadError] if neither worker gem is available, or if both +kicks+
+    #   and +sneakers+ are activated
     # @return [Module]
     # @see file:docs/SETUP.md#installing-the-hooks
     def install!
+      reject_ambiguous_worker_gems!
+
       begin
         require 'sneakers'
         require 'sneakers/workergroup'
@@ -80,6 +83,15 @@ module KicksLiveness
 
       Monitor.new(slot: slot, processes: processes, consumers: consumers, config: config).start!
     end
+
+    private
+
+    def reject_ambiguous_worker_gems!
+      return unless defined?(Gem.loaded_specs)
+      return unless Gem.loaded_specs.key?('kicks') && Gem.loaded_specs.key?('sneakers')
+
+      raise LoadError, 'kicks_liveness cannot run with both kicks and sneakers activated; install exactly one'
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kicks_liveness
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - PoroshkinaVV
@@ -24,6 +24,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -48,7 +49,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/PoroshkinaVV/kicks_liveness
-  documentation_uri: https://rubydoc.info/gems/kicks_liveness/0.1.0
+  documentation_uri: https://rubydoc.info/gems/kicks_liveness/0.1.1
   changelog_uri: https://github.com/PoroshkinaVV/kicks_liveness/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/PoroshkinaVV/kicks_liveness/issues
   rubygems_mfa_required: 'true'