feat: add Image and ResolvedImage fields to SwarmOpts

[tsivaprasad]

Summary

This PR adds Image and ResolvedImage fields to SwarmOpts and implements precedence-based image resolution in the Swarm orchestrator. This provides the foundation for user-controlled image overrides and stable image pinning.

Changes

• Added Image (user override, never managed by CP) and ResolvedImage (CP-managed) fields to SwarmOpts in server/internal/database/spec.go, serialized under orchestrator_opts.docker.
• Updated SwarmOpts.Clone() to correctly copy both new fields.
• Extracted resolveInstanceImages() in the Swarm orchestrator to implement precedence-based image resolution: Image → ResolvedImage → manifest lookup (lazy backfill).
• When Image is explicitly set, the manifest is bypassed entirely, allowing unknown or custom versions to work through user overrides.

Testing

Verification:

• Created cluster
• Created DB using create_db.json
• Confirm Docker service resolved the correct manifest image

docker service ls
ID             NAME                              MODE         REPLICAS   IMAGE                                                       PORTS
l2837hwwvoy8   postgres-storefront-n1-9ptayhma   replicated   1/1        ghcr.io/pgedge/pgedge-postgres:17.9-spock5.0.6-standard-2   
c6wg777c5rig   postgres-storefront-n1-689qacsi   replicated   1/1        ghcr.io/pgedge/pgedge-postgres:17.9-spock5.0.6-standard-2   
seysxqetlp0s   postgres-storefront-n1-ant97dj4   replicated   1/1        ghcr.io/pgedge/pgedge-postgres:17.9-spock5.0.6-standard-2 

Checklist

• Tests added or updated

PLAT-596

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7eb034ac-1472-4be0-b593-22a3860f2265

📥 Commits

Reviewing files that changed from the base of the PR and between f15d712 and 95fe3df.

📒 Files selected for processing (4)

• server/internal/database/spec.go
• server/internal/database/spec_test.go
• server/internal/orchestrator/swarm/orchestrator.go
• server/internal/orchestrator/swarm/resolve_instance_images_test.go

---

📝 Walkthrough

Walkthrough

This PR extends the SwarmOpts data model with image-related fields (Image and ResolvedImage) and introduces a precedence-based image resolution helper for the orchestrator. The resolveInstanceImages method implements a three-tier strategy: use explicit user overrides, fall back to stored resolved images, or lazy-backfill from the version manifest. Both the data model and resolution logic are comprehensively tested.

Changes

Image Resolution and SwarmOpts Enhancement

Layer / File(s)	Summary
SwarmOpts data model and cloning server/internal/database/spec.go, server/internal/database/spec_test.go	SwarmOpts gains Image (user override) and ResolvedImage (control-plane managed) fields with JSON tags. Clone() copies both new fields alongside existing swarm options. TestSwarmOptsClone validates Clone independence and nil receiver handling.
Image resolution orchestrator logic server/internal/orchestrator/swarm/orchestrator.go	New resolveInstanceImages helper applies image precedence (user Image → stored ResolvedImage → manifest fetch with lazy backfill). Defensively allocates nil OrchestratorOpts and SwarmOpts. instanceResources refactored to use this helper instead of direct manifest lookup.
Image resolution test coverage server/internal/orchestrator/swarm/resolve_instance_images_test.go	TestResolveInstanceImages exercises explicit overrides, precedence ordering, lazy backfill with nil struct initialization, error handling on unknown versions, and manifest cache immutability after backfill.

Poem

🐰 Whiskers twitched with delight,
Images now resolve just right,
User choice, then stored, then seek,
Backfill magic, twice a week,
SwarmOpts clones, so neat! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding Image and ResolvedImage fields to SwarmOpts.
Description check	✅ Passed	The description covers Summary, Changes, Testing, and Checklist sections matching the template structure with sufficient detail on implementation and verification.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch PLAT-596-add-image-version-fields-to-database-spec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codacy-production]

Up to standards ✅

🟢 Issues 1 medium

Results:
1 new issue

Category	Results
Complexity	1 medium

View in Codacy

🟢 Metrics 0 duplication

Metric	Results
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}