Skip to content

Modern Docker Management, Designed for Everyone

fix: show the real v2.x.x-next.xx upgrade target for next builds

Kyle Mendell5321b2a776ec
diff --git a/backend/internal/registry/service.go b/backend/internal/registry/service.go
index 23f2392f3..cc0e182af 100644
--- a/backend/internal/registry/service.go
+++ b/backend/internal/registry/service.go
@@ -73,6 +73,7 @@ type ContainerRegistryService struct {
db *database.DB
dockerClient registryDaemonGetter
cache *hot.HotCache[string, string]
+ labelCache *hot.HotCache[string, string]
ecrRefreshGroup singleflight.Group
distributionHTTPClient *http.Client
kvService *kv.KVService
@@ -131,6 +132,11 @@ func NewContainerRegistryService(db *database.DB, dockerClient registryDaemonGet
WithRevalidationErrorPolicy(hot.KeepOnError).
WithJanitor().
Build()
+ // No static loader: ImageVersionLabel uses GetWithLoaders so failed
+ // resolutions are not cached and retry on the next request.
+ service.labelCache = hot.NewHotCache[string, string](hot.LRU, 64).
+ WithTTL(versionLabelCacheTTL).
+ Build()
return service
}
diff --git a/backend/internal/registry/service_label.go b/backend/internal/registry/service_label.go
new file mode 100644
index 000000000..2b8007d0a
--- /dev/null
+++ b/backend/internal/registry/service_label.go
@@ -0,0 +1,74 @@
+package registry
+
+import (
+ "context"
+ "runtime"
+ "strings"
+ "time"
+
+ "emperror.dev/errors"
+ "github.com/google/go-containerregistry/pkg/name"
+ v1 "github.com/google/go-containerregistry/pkg/v1"
+ "github.com/google/go-containerregistry/pkg/v1/remote"
+
+ "github.com/getarcaneapp/arcane/backend/v2/pkg/libarcane/timeouts"
+)
+
+const (
+ ociImageVersionLabel = "org.opencontainers.image.version"
+ versionLabelCacheTTL = 3 * time.Hour
+)
+
+// ErrNoVersionLabel is returned when the remote image config carries no
+// org.opencontainers.image.version label.
+var ErrNoVersionLabel = errors.New("image config has no version label")
+
+// ImageVersionLabel resolves the org.opencontainers.image.version label from the
+// remote image config for a tag or digest reference, without pulling the image.
+// Anonymous access only — this is used for Arcane's own public GHCR images.
+func (s *ContainerRegistryService) ImageVersionLabel(ctx context.Context, imageRef string) (string, error) {
+ imageRef = strings.TrimSpace(imageRef)
+ if imageRef == "" {
+ return "", errors.New("empty image reference")
+ }
+
+ label, found, err := s.labelCache.GetWithLoaders(imageRef, func(_ []string) (map[string]string, error) {
+ loadCtx, cancel := context.WithTimeout(ctx, timeouts.DefaultRegistry)
+ defer cancel()
+
+ value, loadErr := fetchImageVersionLabelInternal(loadCtx, imageRef)
+ if loadErr != nil {
+ return nil, loadErr
+ }
+ return map[string]string{imageRef: value}, nil
+ })
+ if err != nil {
+ return "", err
+ }
+ if !found {
+ return "", errors.New("registry version label cache loader returned no label")
+ }
+ return label, nil
+}
+
+func fetchImageVersionLabelInternal(ctx context.Context, imageRef string) (string, error) {
+ parsedRef, err := name.ParseReference(imageRef)
+ if err != nil {
+ return "", errors.WrapIff(err, "invalid image reference %q", imageRef)
+ }
+
+ img, err := remote.Image(parsedRef,
+ remote.WithContext(ctx),
+ remote.WithPlatform(v1.Platform{OS: "linux", Architecture: runtime.GOARCH}))
+ if err != nil {
+ return "", errors.WrapIff(err, "version label fetch failed for %s", imageRef)
+ }
+ cfg, err := img.ConfigFile()
+ if err != nil {
+ return "", errors.WrapIff(err, "version label fetch failed for %s", imageRef)
+ }
+ if cfg == nil || strings.TrimSpace(cfg.Config.Labels[ociImageVersionLabel]) == "" {
+ return "", ErrNoVersionLabel
+ }
+ return strings.TrimSpace(cfg.Config.Labels[ociImageVersionLabel]), nil
+}
diff --git a/backend/internal/registry/service_label_test.go b/backend/internal/registry/service_label_test.go
new file mode 100644
index 000000000..3b28df680
--- /dev/null
+++ b/backend/internal/registry/service_label_test.go
@@ -0,0 +1,100 @@
+package registry
+
+import (
+ "context"
+ "io"
+ "log"
+ "net/http/httptest"
+ "net/url"
+ "testing"
+
+ "github.com/google/go-containerregistry/pkg/name"
+ ggcrregistry "github.com/google/go-containerregistry/pkg/registry"
+ v1 "github.com/google/go-containerregistry/pkg/v1"
+ "github.com/google/go-containerregistry/pkg/v1/mutate"
+ "github.com/google/go-containerregistry/pkg/v1/random"
+ "github.com/google/go-containerregistry/pkg/v1/remote"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// newLabelTestRegistryInternal starts an in-memory OCI registry and returns its
+// host as "localhost:PORT" so go-containerregistry resolves it over plain HTTP.
+func newLabelTestRegistryInternal(t *testing.T) string {
+ t.Helper()
+ server := httptest.NewServer(ggcrregistry.New(ggcrregistry.Logger(log.New(io.Discard, "", 0))))
+ t.Cleanup(server.Close)
+ serverURL, err := url.Parse(server.URL)
+ require.NoError(t, err)
+ return "localhost:" + serverURL.Port()
+}
+
+func pushLabeledImageInternal(t *testing.T, imageRef string, imageLabels map[string]string) v1.Image {
+ t.Helper()
+ img, err := random.Image(64, 1)
+ require.NoError(t, err)
+
+ if imageLabels != nil {
+ cfg, err := img.ConfigFile()
+ require.NoError(t, err)
+ cfg = cfg.DeepCopy()
+ cfg.Config.Labels = imageLabels
+ img, err = mutate.ConfigFile(img, cfg)
+ require.NoError(t, err)
+ }
+
+ ref, err := name.ParseReference(imageRef)
+ require.NoError(t, err)
+ require.NoError(t, remote.Write(ref, img))
+ return img
+}
+
+func TestContainerRegistryService_ImageVersionLabelInternal(t *testing.T) {
+ host := newLabelTestRegistryInternal(t)
+ imageRef := host + "/getarcaneapp/arcane:next"
+ img := pushLabeledImageInternal(t, imageRef, map[string]string{
+ ociImageVersionLabel: "v2.8.0-next.66",
+ })
+
+ svc := NewContainerRegistryService(nil, nil, nil)
+
+ label, err := svc.ImageVersionLabel(context.Background(), imageRef)
+ require.NoError(t, err)
+ assert.Equal(t, "v2.8.0-next.66", label)
+
+ // Digest references resolve too — the version service prefers them.
+ imgDigest, err := img.Digest()
+ require.NoError(t, err)
+ label, err = svc.ImageVersionLabel(context.Background(), host+"/getarcaneapp/arcane@"+imgDigest.String())
+ require.NoError(t, err)
+ assert.Equal(t, "v2.8.0-next.66", label)
+}
+
+func TestContainerRegistryService_ImageVersionLabelMissingLabelInternal(t *testing.T) {
+ host := newLabelTestRegistryInternal(t)
+ imageRef := host + "/getarcaneapp/arcane:next"
+ pushLabeledImageInternal(t, imageRef, nil)
+
+ svc := NewContainerRegistryService(nil, nil, nil)
+ _, err := svc.ImageVersionLabel(context.Background(), imageRef)
+ assert.ErrorIs(t, err, ErrNoVersionLabel)
+}
+
+func TestContainerRegistryService_ImageVersionLabelErrorNotCachedInternal(t *testing.T) {
+ host := newLabelTestRegistryInternal(t)
+ imageRef := host + "/getarcaneapp/arcane:next"
+
+ svc := NewContainerRegistryService(nil, nil, nil)
+
+ // The image does not exist yet: the lookup must fail...
+ _, err := svc.ImageVersionLabel(context.Background(), imageRef)
+ require.Error(t, err)
+
+ // ...and the failure must not be cached: after the push the same ref resolves.
+ pushLabeledImageInternal(t, imageRef, map[string]string{
+ ociImageVersionLabel: "v2.8.0-next.67",
+ })
+ label, err := svc.ImageVersionLabel(context.Background(), imageRef)
+ require.NoError(t, err)
+ assert.Equal(t, "v2.8.0-next.67", label)
+}
diff --git a/backend/internal/version/service.go b/backend/internal/version/service.go
index 32979f89f..8ad15340f 100644
--- a/backend/internal/version/service.go
+++ b/backend/internal/version/service.go
@@ -207,7 +207,9 @@ func (s *VersionService) GetVersionInformation(ctx context.Context, currentVersi
return check, err
}
- if latest != "" {
+ // Skip when latest is semver-older than current (e.g. a prerelease build
+ // asking the stable release feed) — a downgrade is not a newest version.
+ if latest != "" && !s.IsNewer(cur, latest) {
check.NewestVersion = latest
check.UpdateAvailable = s.IsNewer(latest, cur)
check.ReleaseURL = s.ReleaseURL(latest)
@@ -216,6 +218,46 @@ func (s *VersionService) GetVersionInformation(ctx context.Context, currentVersi
return check, nil
}
+// isNextBuildInternal reports whether this build tracks the next channel: a
+// -next. prerelease version, or a container running the rolling next image tag.
+func (s *VersionService) isNextBuildInternal(currentTag string) bool {
+ return strings.Contains(strings.ToLower(strings.TrimSpace(s.version)), "-next.") ||
+ strings.TrimSpace(currentTag) == "next"
+}
+
+// resolveNextVersionInternal returns the normalized version label of the image
+// an upgrade would pull, or "" when it cannot be resolved. It prefers the
+// digest reference so the reported version and NewestDigest describe the same
+// artifact.
+func (s *VersionService) resolveNextVersionInternal(ctx context.Context, imageRef, tag, newestDigest string) string {
+ if s.containerRegistryService == nil || strings.TrimSpace(imageRef) == "" {
+ return ""
+ }
+
+ lookupRef := ""
+ switch {
+ case strings.TrimSpace(newestDigest) != "":
+ lookupRef = imageRef + "@" + strings.TrimSpace(newestDigest)
+ case strings.TrimSpace(tag) != "":
+ lookupRef = imageRef + ":" + strings.TrimSpace(tag)
+ default:
+ return ""
+ }
+
+ label, err := s.containerRegistryService.ImageVersionLabel(ctx, lookupRef)
+ if err != nil {
+ slog.WarnContext(ctx, "Failed to resolve next-channel version label", "imageRef", lookupRef, "error", err)
+ return ""
+ }
+
+ normalized := s.normalizeVersion(label)
+ if !semver.IsValid(normalized) {
+ slog.WarnContext(ctx, "Next-channel image version label is not valid semver", "imageRef", lookupRef, "label", label)
+ return ""
+ }
+ return normalized
+}
+
// isSemverVersion checks if a version string is semver-based (e.g., v1.0.0)
func (s *VersionService) isSemverVersion() bool {
versionValue := strings.TrimSpace(s.version)
@@ -265,30 +307,31 @@ func (s *VersionService) GetAppVersionInfo(ctx context.Context) *version.Info {
return info
}
- semverUpdateAvailable := false
-
- // For semver versions, check GitHub releases
- if isSemver {
- rel, err := s.getLatestReleaseInternal(ctx)
- if err == nil {
- if rel.TagName != "" {
- info.NewestVersion = rel.TagName
- semverUpdateAvailable = s.IsNewer(rel.TagName, ver)
- info.ReleaseURL = s.ReleaseURL(rel.TagName)
- info.ReleaseNotes = rel.Body
- info.ReleasedAt = rel.PublishedAt
- }
- }
- }
-
digestUpdateAvailable, latestDigest := s.storedOrDigestBasedUpdateInternal(ctx, currentImageID, currentTag, currentDigest, currentImageRef)
if latestDigest != "" {
info.NewestDigest = latestDigest
}
- // Best-effort: pull release notes for non-semver track too, so the modal can preview
- // the latest tagged release even when the running build is digest-tracking.
- if !isSemver {
+ switch {
+ case isSemver && s.isNextBuildInternal(currentTag):
+ nextVersion := s.resolveNextVersionInternal(ctx, currentImageRef, currentTag, latestDigest)
+ if nextVersion != "" && semver.Compare(nextVersion, ver) >= 0 {
+ info.NewestVersion = nextVersion
+ }
+ info.UpdateAvailable = digestUpdateAvailable || (nextVersion != "" && s.IsNewer(nextVersion, ver))
+ case isSemver:
+ // Never surface a release older than the running version as the target.
+ rel, err := s.getLatestReleaseInternal(ctx)
+ if err == nil && rel.TagName != "" && !s.IsNewer(ver, rel.TagName) {
+ info.NewestVersion = rel.TagName
+ info.UpdateAvailable = s.IsNewer(rel.TagName, ver)
+ info.ReleaseURL = s.ReleaseURL(rel.TagName)
+ info.ReleaseNotes = rel.Body
+ info.ReleasedAt = rel.PublishedAt
+ }
+ default:
+ // Best-effort: pull release notes for non-semver track too, so the modal can preview
+ // the latest tagged release even when the running build is digest-tracking.
if rel, err := s.getLatestReleaseInternal(ctx); err == nil && rel.TagName != "" {
info.ReleaseNotes = rel.Body
info.ReleasedAt = rel.PublishedAt
@@ -296,9 +339,9 @@ func (s *VersionService) GetAppVersionInfo(ctx context.Context) *version.Info {
info.ReleaseURL = s.ReleaseURL(rel.TagName)
}
}
+ info.UpdateAvailable = digestUpdateAvailable
}
- info.UpdateAvailable = semverUpdateAvailable || (!isSemver && digestUpdateAvailable)
return info
}
diff --git a/backend/internal/version/service_test.go b/backend/internal/version/service_test.go
index ed2d5c15e..8adf2e5f7 100644
--- a/backend/internal/version/service_test.go
+++ b/backend/internal/version/service_test.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"fmt"
"io"
+ "log"
"net/http"
"net/http/httptest"
"net/url"
@@ -16,6 +17,12 @@ import (
"github.com/getarcaneapp/arcane/backend/v2/internal/docker"
"github.com/getarcaneapp/arcane/backend/v2/internal/imageupdate"
"github.com/getarcaneapp/arcane/backend/v2/internal/models"
+ "github.com/getarcaneapp/arcane/backend/v2/internal/registry"
+ "github.com/google/go-containerregistry/pkg/name"
+ ggcrregistry "github.com/google/go-containerregistry/pkg/registry"
+ "github.com/google/go-containerregistry/pkg/v1/mutate"
+ "github.com/google/go-containerregistry/pkg/v1/random"
+ "github.com/google/go-containerregistry/pkg/v1/remote"
"github.com/libtnb/sqlite"
"github.com/moby/moby/api/types/container"
dockertypesimage "github.com/moby/moby/api/types/image"
@@ -179,3 +186,201 @@ func newTestDockerClientInternal(t *testing.T, server *httptest.Server) *client.
return cli
}
+
+func TestVersionService_IsNextBuildInternal(t *testing.T) {
+ tests := []struct {
+ name string
+ version string
+ currentTag string
+ want bool
+ }{
+ {"next prerelease version", "2.8.0-next.65", "latest", true},
+ {"stable version on next tag", "2.7.0", "next", true},
+ {"stable version on latest tag", "2.7.0", "latest", false},
+ {"stable version on version tag", "2.7.0", "v2.7.0", false},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ svc := NewVersionService(nil, true, tt.version, "rev", nil, nil, nil)
+ assert.Equal(t, tt.want, svc.isNextBuildInternal(tt.currentTag))
+ })
+ }
+}
+
+// newLabelRegistryTestServerInternal starts an in-memory OCI registry and
+// returns its host as "localhost:PORT" so go-containerregistry uses plain HTTP.
+func newLabelRegistryTestServerInternal(t *testing.T) string {
+ t.Helper()
+ server := httptest.NewServer(ggcrregistry.New(ggcrregistry.Logger(log.New(io.Discard, "", 0))))
+ t.Cleanup(server.Close)
+ serverURL, err := url.Parse(server.URL)
+ require.NoError(t, err)
+ return "localhost:" + serverURL.Port()
+}
+
+// newNextChannelDockerServerInternal fakes a Docker daemon whose Arcane
+// container runs repo:tag with the given current repo digest.
+func newNextChannelDockerServerInternal(t *testing.T, containerID, imageID, repo, tag, currentDigest string) *httptest.Server {
+ t.Helper()
+ imageRef := repo + ":" + tag
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch {
+ case strings.HasSuffix(r.URL.Path, "/containers/json"):
+ w.Header().Set("Content-Type", "application/json")
+ assert.NoError(t, json.NewEncoder(w).Encode([]container.Summary{
+ {ID: containerID, State: container.StateRunning, Labels: map[string]string{labels.LabelArcane: "true"}},
+ }))
+ case strings.Contains(r.URL.Path, "/containers/") && strings.HasSuffix(r.URL.Path, "/json"):
+ w.Header().Set("Content-Type", "application/json")
+ assert.NoError(t, json.NewEncoder(w).Encode(container.InspectResponse{
+ ID: containerID,
+ Image: imageID,
+ Config: &container.Config{
+ Image: imageRef,
+ Labels: map[string]string{labels.LabelArcane: "true"},
+ },
+ }))
+ case strings.Contains(r.URL.Path, "/images/") && strings.HasSuffix(r.URL.Path, "/json"):
+ w.Header().Set("Content-Type", "application/json")
+ assert.NoError(t, json.NewEncoder(w).Encode(dockertypesimage.InspectResponse{
+ ID: imageID,
+ RepoTags: []string{imageRef},
+ RepoDigests: []string{repo + "@" + currentDigest},
+ }))
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ t.Cleanup(server.Close)
+ return server
+}
+
+func TestVersionService_GetAppVersionInfoNextChannelUsesImageLabelInternal(t *testing.T) {
+ ctx := context.Background()
+ db := setupImageUpdateTestDB(t)
+
+ const (
+ containerID = "arcane-container-1234567890"
+ imageID = "sha256:arcane-image"
+ )
+ registryHost := newLabelRegistryTestServerInternal(t)
+ repo := registryHost + "/getarcaneapp/arcane"
+
+ img, err := random.Image(64, 1)
+ require.NoError(t, err)
+ cfg, err := img.ConfigFile()
+ require.NoError(t, err)
+ cfg = cfg.DeepCopy()
+ cfg.Config.Labels = map[string]string{"org.opencontainers.image.version": "v2.8.0-next.66"}
+ img, err = mutate.ConfigFile(img, cfg)
+ require.NoError(t, err)
+ pushRef, err := name.ParseReference(repo + ":next")
+ require.NoError(t, err)
+ require.NoError(t, remote.Write(pushRef, img))
+ imgDigest, err := img.Digest()
+ require.NoError(t, err)
+
+ currentDigest := digest.FromString("current-arcane").String()
+ server := newNextChannelDockerServerInternal(t, containerID, imageID, repo, "next", currentDigest)
+
+ require.NoError(t, db.WithContext(ctx).Create(&models.ImageUpdateRecord{
+ ID: imageID,
+ Repository: repo,
+ Tag: "next",
+ HasUpdate: true,
+ UpdateType: models.UpdateTypeDigest,
+ CurrentVersion: "next",
+ CurrentDigest: &currentDigest,
+ LatestDigest: func() *string { s := imgDigest.String(); return &s }(),
+ CheckTime: time.Now().UTC(),
+ }).Error)
+
+ githubHit := false
+ httpClient := &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+ githubHit = true
+ return &http.Response{
+ StatusCode: http.StatusOK,
+ Header: make(http.Header),
+ Body: io.NopCloser(strings.NewReader(`{"tag_name":"v2.7.0"}`)),
+ Request: req,
+ }, nil
+ })}
+ dockerService := docker.NewDockerClientService(t.Context(), nil, nil, nil).WithClient(newTestDockerClientInternal(t, server))
+ imageUpdateService := imageupdate.NewImageUpdateService(db, nil, nil, dockerService, nil, nil, nil)
+ registrySvc := registry.NewContainerRegistryService(nil, nil, nil)
+ svc := NewVersionService(httpClient, false, "2.8.0-next.65", "revision", registrySvc, dockerService, imageUpdateService)
+
+ info := svc.GetAppVersionInfo(ctx)
+
+ require.NotNil(t, info)
+ assert.Equal(t, "v2.8.0-next.66", info.NewestVersion)
+ assert.True(t, info.UpdateAvailable)
+ assert.Equal(t, imgDigest.String(), info.NewestDigest)
+ assert.Empty(t, info.ReleaseNotes)
+ assert.Empty(t, info.ReleaseURL)
+ assert.False(t, githubHit, "next channel must not consult the GitHub stable release feed")
+}
+
+func TestVersionService_GetAppVersionInfoNextChannelLabelFailureFallsBackToDigestInternal(t *testing.T) {
+ ctx := context.Background()
+ db := setupImageUpdateTestDB(t)
+
+ const (
+ containerID = "arcane-container-1234567890"
+ imageID = "sha256:arcane-image"
+ )
+ // Registry with no image pushed: the label fetch fails.
+ registryHost := newLabelRegistryTestServerInternal(t)
+ repo := registryHost + "/getarcaneapp/arcane"
+
+ currentDigest := digest.FromString("current-arcane").String()
+ latestDigest := digest.FromString("latest-arcane").String()
+ server := newNextChannelDockerServerInternal(t, containerID, imageID, repo, "next", currentDigest)
+
+ require.NoError(t, db.WithContext(ctx).Create(&models.ImageUpdateRecord{
+ ID: imageID,
+ Repository: repo,
+ Tag: "next",
+ HasUpdate: true,
+ UpdateType: models.UpdateTypeDigest,
+ CurrentVersion: "next",
+ CurrentDigest: &currentDigest,
+ LatestDigest: &latestDigest,
+ CheckTime: time.Now().UTC(),
+ }).Error)
+
+ dockerService := docker.NewDockerClientService(t.Context(), nil, nil, nil).WithClient(newTestDockerClientInternal(t, server))
+ imageUpdateService := imageupdate.NewImageUpdateService(db, nil, nil, dockerService, nil, nil, nil)
+ registrySvc := registry.NewContainerRegistryService(nil, nil, nil)
+ svc := NewVersionService(nil, false, "2.8.0-next.65", "revision", registrySvc, dockerService, imageUpdateService)
+
+ info := svc.GetAppVersionInfo(ctx)
+
+ require.NotNil(t, info)
+ assert.Empty(t, info.NewestVersion, "label failure must not fall back to a stable tag")
+ assert.True(t, info.UpdateAvailable, "digest change alone flags the update")
+ assert.Equal(t, latestDigest, info.NewestDigest)
+}
+
+func TestVersionService_GetAppVersionInfoSuppressesOlderStableForPrereleaseInternal(t *testing.T) {
+ httpClient := &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+ return &http.Response{
+ StatusCode: http.StatusOK,
+ Header: make(http.Header),
+ Body: io.NopCloser(strings.NewReader(`{"tag_name":"v2.7.0","body":"notes","published_at":"2026-08-05T22:21:04Z"}`)),
+ Request: req,
+ }, nil
+ })}
+ // An -rc. prerelease stays on the stable track; the downgrade guard must
+ // still drop the older stable tag rather than showing a backwards arrow.
+ svc := NewVersionService(httpClient, false, "2.8.0-rc.1", "revision", nil, nil, nil)
+
+ info := svc.GetAppVersionInfo(context.Background())
+
+ require.NotNil(t, info)
+ assert.False(t, info.UpdateAvailable)
+ assert.Empty(t, info.NewestVersion)
+ assert.Empty(t, info.ReleaseNotes)
+ assert.Empty(t, info.ReleaseURL)
+ assert.Empty(t, info.ReleasedAt)
+}