feat(deploy): coordinator/API backwards-image-update guard (reject backwards pins + hide backwards updates) #157

Merged
charles merged 3 commits from feat/no-backwards-updates-coordinator into main 2026-08-27 20:02:51 +00:00
Owner

Completes the backwards-image-update guard on the coordinator/API side (guard #1, the sidecar, shipped in #156).

What

Three coordinated parts that prevent the deploy plane from ever pinning or advertising an image older than what's running:

  • A (docker-registry-client.ts): fetchImageCreated(ref, digest) resolves an image's OCI config .created build-time (manifest → config blob, manifest-list aware, 401→bearer retry, immutable by-digest cache). peekImageCreated is the sync cache peek. isStrictlyNewer(target, running) fails open — returns true whenever either timestamp is null/unparseable; false only when both are known and target ≤ running.
  • B (members.ts update-image, mesh-hosts.ts update-sidecar): reject a backwards pin with 409 before writing desired_image_digest / desired_sidecar_image_digest. Skipped entirely when running digest is unknown; any registry error falls through to allow.
  • C (members.ts list / docker-registry-image-poller.ts): the members list hides latest_image_digest (nulls it) when it is not strictly newer than running, so the UI never shows a backwards "update available". Hot path uses only the synchronous cache peek + fire-and-forget warm — never awaits a registry fetch.

Safety

  • Fail-open is absolute: a slow/unreachable registry never blocks a legitimate forward update and never wedges a deploy.
  • List path never awaits a network call (verified in final review).

Tests

47 pass / 0 fail across the three suites (registry created-fetch, update-image backwards-guard, members-list backwards-hide).

Follow-ups (non-blocking, noted in review)

  • Loopback-registry cache-key divergence (list peek uses raw host, poller warms under LAN-substituted host) — degrades to fail-open only; live grid uses git.forked.io, unaffected.
  • Single-member GET /members/:id not gated — visual only; the update button hits the 409-guarded route.

🤖 Generated with Claude Code

Completes the backwards-image-update guard on the coordinator/API side (guard #1, the sidecar, shipped in #156). ## What Three coordinated parts that prevent the deploy plane from ever pinning or advertising an image older than what's running: - **A** (`docker-registry-client.ts`): `fetchImageCreated(ref, digest)` resolves an image's OCI config `.created` build-time (manifest → config blob, manifest-list aware, 401→bearer retry, immutable by-digest cache). `peekImageCreated` is the sync cache peek. `isStrictlyNewer(target, running)` **fails open** — returns `true` whenever either timestamp is null/unparseable; `false` only when both are known and target ≤ running. - **B** (`members.ts` update-image, `mesh-hosts.ts` update-sidecar): reject a backwards pin with **409** before writing `desired_image_digest` / `desired_sidecar_image_digest`. Skipped entirely when running digest is unknown; any registry error falls through to allow. - **C** (`members.ts` list / `docker-registry-image-poller.ts`): the members list **hides** `latest_image_digest` (nulls it) when it is not strictly newer than running, so the UI never shows a backwards "update available". Hot path uses only the **synchronous** cache peek + fire-and-forget warm — never awaits a registry fetch. ## Safety - Fail-open is absolute: a slow/unreachable registry never blocks a legitimate forward update and never wedges a deploy. - List path never awaits a network call (verified in final review). ## Tests 47 pass / 0 fail across the three suites (registry created-fetch, update-image backwards-guard, members-list backwards-hide). ## Follow-ups (non-blocking, noted in review) - Loopback-registry cache-key divergence (list peek uses raw host, poller warms under LAN-substituted host) — degrades to fail-open only; live grid uses `git.forked.io`, unaffected. - Single-member `GET /members/:id` not gated — visual only; the update button hits the 409-guarded route. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Guard #3: both routes now call fetchImageCreated for target + running
digests and return 409 when !isStrictlyNewer. Fails open when running
digest is null, build-time is unknown (fetchImageCreated null), or the
registry is unreachable. 10 new tests covering all branches, 0 tsc errors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SXQLnx5xqLwiNChwcj3N27
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SXQLnx5xqLwiNChwcj3N27
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
charles/projectoctet!157
No description provided.