Make Sparoid::Instance public-IP resolution thread-safe and self-healing

[oskgu360]

Problem

Sparoid::Instance memoized its public IP with @public_ips ||= super, which has two defects:

1. Empty result pinned forever. [] is truthy in Ruby, so once @public_ips is [] the ||= short-circuits and never re-resolves. A single transient empty resolution (icanhazip down or returning an empty body) poisons the instance for its whole life — every later knock then builds zero messages and auth sends zero SPA packets.
2. Non-atomic race / thundering herd. ||= is read-modify-write. When one Instance is shared across a thread pool, the first wave of knocks all resolve concurrently (a herd of icanhazip requests) and one slow/empty response clobbers a good value via last-writer-wins — then defect Include gem name in warnings #1 pins it.

This was caught in production (ssh-monitor worker.26, 2026-06-26): a dyno sent zero-packet knocks for its whole lifetime and alarmed every host as SSH-down. ssh-monitor currently carries an app-side monkey-patch for this; this PR moves the proper fix into the gem.

Fix

• Move the caching into Instance#cached_public_ips (calling the inherited raw public_ips fetch directly — no super, no public_ips override).
• Resolve behind a per-instance mutex with a double-check — kills the thundering herd and the last-writer-wins clobber; concurrent callers wait and reuse the freshly cached IP.
• Cache only a non-empty result (the stable egress IP, returned lock-free on the fast path); never memoize empty, so a transient failure self-heals on the next knock.
• Close the silent-success hole: generate_messages now raises when an empty public-IP resolution and no IPv6 fallback would otherwise produce no messages, instead of letting auth report success having sent nothing.
• The raise is a new Sparoid::PublicIPError — a sibling of ResolvError under Error (so existing rescue Sparoid::Error still catches it), letting callers distinguish "I can't resolve my own public IP" (a client-side failure affecting every host) from "the target host is unreachable." Notably it is not a ResolvError, so ssh-monitor's rescue Sparoid::ResolvError "machine deleted" no-op won't silently swallow it.

Tests

• test_instance_retries_and_recovers_instead_of_pinning_empty — empty resolve is not memoized; recovers once icanhazip responds again (webmock).
• test_auth_raises_when_no_public_ip_resolved — auth raises Sparoid::PublicIPError rather than silently sending zero packets.
• Manual concurrency check: 40 threads on one instance → a single resolution (2 HTTP calls, not 80), all threads get the good IP.

Adds webmock as a dev dependency.

Note

Version bump + CHANGELOG and the ssh-monitor cleanup are intentionally left to separate follow-up PRs. The follow-up can rescue Sparoid::PublicIPError specifically so an icanhazip outage doesn't mark every host as SSH-down.

[Copilot]

Pull request overview

This PR hardens Sparoid::Instance public-IP resolution by making it thread-safe, avoiding permanently caching empty resolutions, and by failing fast when an auth attempt would otherwise send zero SPA packets.

Changes:

• Add Sparoid::PublicIPError and raise it when no public IP can be resolved for message generation.
• Implement per-instance, mutex-guarded, non-empty memoization via Instance#cached_public_ips.
• Add WebMock-backed tests for retry/self-healing behavior and for the new error path; add webmock to dev deps.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
lib/sparoid.rb	Adds PublicIPError, raises on empty IP resolution, and introduces mutex-protected per-instance caching of public IPs.
test/test_helper.rb	Enables WebMock for the suite (but currently allows real network connections).
test/sparoid_test.rb	Adds WebMock stubs and tests covering non-pinning empty results and raising on zero-message auth.
Gemfile	Adds webmock for development/test usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[oskgu360]

Ran ssh-monitor fix with this patch locally (just verified it were able to ssh).

Will rescue PublicIPError to handle that gracefully in case of this happening again. If we decide to merge this that is