v1.6.0 - Optional dual-send mirror so a standby server stays a live replica. #12

2026-06-25T10:53:17-04:00

serversdown commented

2026-06-25 10:53:17 -04:00

[6-25-26] — v1.6.0

Optional dual-send mirror so a standby server stays a live replica.

Added — Mirror (dual-send)

Post every heartbeat and event to a second ("mirror") server in addition to the primary. When MIRROR_API_URL and/or MIRROR_SFM_URL are set, each heartbeat POST and each forwarded Blastware event is also sent to the mirror destination — letting a standby box (e.g. the office NAS) stay a continuous replica of prod during a migration so the eventual cutover is a non-event. Default off — blank URLs mean existing 1.5.x installs don't change behaviour after an auto-update.
Heartbeat mirror (best-effort). After the primary send_api_payload, the same payload is fired at MIRROR_API_URL when set. It is fully wrapped and bounded by the existing API timeout — the mirror can never delay or fail the primary heartbeat; its outcome is ignored except for a debug log line.
Event mirror (reliable, isolated). Events are re-forwarded to MIRROR_SFM_URL through a separate sha256 state file (MIRROR_SFM_STATE_FILE, blank → <log dir>/sfm_forwarded_mirror.json) so the mirror tracks its own delivery independently of the primary forwarder. Before each mirror pass a quick reachability probe (~3 s) checks the mirror server; if it's down the pass is skipped and retried next tick rather than blocking the loop on per-event timeouts. Skipped events stay pending in the mirror state and deliver once the mirror returns — no data loss.
Isolation invariant. Nothing on the mirror path can delay or fail the primary: its own state file, its own try/except, the reachability guard + bounded timeouts, and all exceptions swallowed-and-logged. The primary path stays exactly as reliable as before. The mirror rides along with the primary — there is no separate enable flag (heartbeat-mirror active iff the primary heartbeat is on and MIRROR_API_URL is set; event-mirror active iff primary forwarding is on and MIRROR_SFM_URL is set).
Mirror fields in the Settings dialog: Mirror API URL + Mirror SFM URL (blank = off).
New unit tests in test_event_forwarder.py covering mirror reachability, the down-mirror skip, separate-state idempotency, and the isolation invariant (a mirror failure leaves the primary's result + state untouched).

Configuration

New [agent] keys (all default-off — existing 1.5.x deployments don't change behaviour on auto-update):

Key	Default	Notes
`MIRROR_API_URL`	empty	Second heartbeat base URL, e.g. `http://10.0.0.x:8001` (blank = off)
`MIRROR_SFM_URL`	empty	Second SFM base URL, e.g. `http://10.0.0.x:8200` (blank = off)
`MIRROR_SFM_STATE_FILE`	`<log dir>/sfm_forwarded_mirror.json`	Override location of the mirror's forwarded-sha256 state file

Operational (migration seeding)

To make the mirror re-deliver only the gap since a one-time replica snapshot, copy the primary state file to the mirror state file and drop entries whose forwarded_at is after the snapshot. SFM-side dedup covers any overlap. See docs/mirror-dual-send-design.md.

## [6-25-26] — v1.6.0 Optional dual-send mirror so a standby server stays a live replica. ### Added — Mirror (dual-send) - **Post every heartbeat and event to a second ("mirror") server in addition to the primary.** When `MIRROR_API_URL` and/or `MIRROR_SFM_URL` are set, each heartbeat POST and each forwarded Blastware event is *also* sent to the mirror destination — letting a standby box (e.g. the office NAS) stay a continuous replica of prod during a migration so the eventual cutover is a non-event. **Default off** — blank URLs mean existing 1.5.x installs don't change behaviour after an auto-update. - **Heartbeat mirror (best-effort).** After the primary `send_api_payload`, the same payload is fired at `MIRROR_API_URL` when set. It is fully wrapped and bounded by the existing API timeout — the mirror can **never** delay or fail the primary heartbeat; its outcome is ignored except for a debug log line. - **Event mirror (reliable, isolated).** Events are re-forwarded to `MIRROR_SFM_URL` through a *separate* sha256 state file (`MIRROR_SFM_STATE_FILE`, blank → `<log dir>/sfm_forwarded_mirror.json`) so the mirror tracks its own delivery independently of the primary forwarder. Before each mirror pass a quick reachability probe (~3 s) checks the mirror server; if it's down the pass is skipped and retried next tick rather than blocking the loop on per-event timeouts. Skipped events stay pending in the mirror state and deliver once the mirror returns — **no data loss**. - **Isolation invariant.** Nothing on the mirror path can delay or fail the primary: its own state file, its own try/except, the reachability guard + bounded timeouts, and all exceptions swallowed-and-logged. The primary path stays exactly as reliable as before. The mirror rides along with the primary — there is no separate enable flag (heartbeat-mirror active iff the primary heartbeat is on *and* `MIRROR_API_URL` is set; event-mirror active iff primary forwarding is on *and* `MIRROR_SFM_URL` is set). - **Mirror fields in the Settings dialog**: `Mirror API URL` + `Mirror SFM URL` (blank = off). - New unit tests in `test_event_forwarder.py` covering mirror reachability, the down-mirror skip, separate-state idempotency, and the isolation invariant (a mirror failure leaves the primary's result + state untouched). ### Configuration New `[agent]` keys (all default-off — existing 1.5.x deployments don't change behaviour on auto-update): | Key | Default | Notes | |---|---|---| | `MIRROR_API_URL` | empty | Second heartbeat base URL, e.g. `http://10.0.0.x:8001` (blank = off) | | `MIRROR_SFM_URL` | empty | Second SFM base URL, e.g. `http://10.0.0.x:8200` (blank = off) | | `MIRROR_SFM_STATE_FILE` | `<log dir>/sfm_forwarded_mirror.json` | Override location of the mirror's forwarded-sha256 state file | ### Operational (migration seeding) To make the mirror re-deliver only the gap since a one-time replica snapshot, copy the primary state file to the mirror state file and drop entries whose `forwarded_at` is after the snapshot. SFM-side dedup covers any overlap. See `docs/mirror-dual-send-design.md`.

serversdown added 4 commits 2026-06-25 10:53:17 -04:00

docs: mirror dual-send design spec 730f215e23

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat: best-effort mirror (dual-send) of heartbeats + events 4adaa09d75

Optional second destination so each heartbeat and event is posted to a
mirror server (the office NAS) alongside the primary — dual-write to
de-risk the migration. Default off (blank mirror URLs); existing installs
unchanged.

- event_forwarder: mirror_reachable() fast-fail probe + mirror_forward_pass()
  (reliable event mirror with its OWN state file, total exception isolation,
  never raises into the primary path).
- series3_watcher: MIRROR_API_URL/MIRROR_SFM_URL/MIRROR_SFM_STATE_FILE config;
  best-effort heartbeat mirror; isolated event-mirror pass after the primary.
- settings dialog + config-template: new 'Mirror' tab / keys.
- 8 new tests incl. the isolation invariant. 44 passing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge pull request 'feat: add optional mirror server config' (#11 ) from feat/mirror-dual-send into dev 92ebbd6537

Reviewed-on: #11

chore(release): bump to v1.6.0 — mirror (dual-send) docs e6e4c94f19

Version bump across series3_watcher.py / tray / settings dialog / installer.iss.
CHANGELOG + README document the optional best-effort mirror server
(MIRROR_API_URL / MIRROR_SFM_URL / MIRROR_SFM_STATE_FILE, default off).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

serversdown merged commit fb1edfbad4 into main

2026-06-25 10:53:30 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: serversdown/series3-watcher#12