decentraland / archipelago-workers / 34336605130

92%

main: 79%

Pull #133

github

docs: scope the connect-publish counter to refused publishes, not lost ones

Round-1 review, minor 2. Runbook §7 told the operator to read
`ws_connector_peer_connect_publish_failures_total` as "one increment per
completed handshake whose announcement the broker refused. It should be
flat at zero" — but the counter cannot see the loss mode §7 exists to
catch. `nats.publish` throws only when the component was never started
or the connection is closed; while the client is *reconnecting* (a
broker rolling restart, a partition) it neither throws nor delivers, it
buffers, and the buffer is discarded if the reconnect never succeeds.
Every handshake in that window is announced to nothing with the counter
still at zero, so an operator reading a flat series signs the step-7
gate off while those clients hold live sockets with no island.

- `docs/stats-decommission-runbook.md:249` scopes the counter to
  refusals ("not started, or connection closed") and adds a paragraph
  at `:254` saying a flat zero is not evidence that announcements are
  landing: `nats sub 'peer.*.connect'` is the real check, paired with
  the broker's own connection/reconnect metrics for the window.
- `docs/ai-agent-context.md:58` and the `peer.<addr>.connect` row of the
  NATS subject table carry the same clause.
- `ws-connector/.env.default:55` — the §7 pointer now names the broker
  subscription as the check rather than leaving the counter to look like
  one.
- `ws-connector/src/metrics.ts:9` — the declaration comment says what
  the series can and cannot see, and `help` now reads "the NATS client
  refused (not started / closed)" instead of "could not be published on
  NATS", which claimed more than the counter knows.
- `ws-connector/src/controllers/handlers/ws-handler.ts:119` — the same
  caveat beside the publish, so the next reader of the failure path does
  not have to rediscover it.

Wording only; no behaviour and no metric name changed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

93 of 113 branches covered (82.3%)

Branch coverage included in aggregate %.

197 of 199 new or added lines in 20 files covered. (98.99%)

457 of 484 relevant lines covered (94.42%)

22.08 hits per line