Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
package projects
import (
"context"
"log/slog"
"strings"
"time"
composetypes "github.com/compose-spec/compose-go/v2/types"
composeapi "github.com/docker/compose/v5/pkg/api"
kit "go.getarcane.app/kit/pkg"
)
// ImagePullMode describes when Arcane should pull an image for a project.
type ImagePullMode int
const (
// ImagePullModeNever skips pulling the image.
ImagePullModeNever ImagePullMode = iota
// ImagePullModeIfMissing pulls only when the image is missing locally.
ImagePullModeIfMissing
// ImagePullModeRefresh pulls when the image is missing locally or was last
// tagged longer ago than the policy's refresh window.
ImagePullModeRefresh
// ImagePullModeAlways pulls even when the image is present locally.
ImagePullModeAlways
)
// ImagePullStep is one entry of an image pull plan: the mode plus, for
// ImagePullModeRefresh, the window after which a new pull is due.
type ImagePullStep struct {
Mode ImagePullMode
RefreshAfter time.Duration
}
// DeployImageDecision describes how deploy should handle a service image.
type DeployImageDecision struct {
Build bool
PullAlways bool
PullIfMissing bool
// PullIfStale pulls when the image is missing or its last-tag time is
// older than StaleAfter (pull_policy daily/weekly/every_N).
PullIfStale bool
StaleAfter time.Duration
FallbackBuildOnPullFail bool
RequireLocalOnly bool
}
// ResolveServiceImagePullMode resolves compose pull_policy into Arcane's pull step.
func ResolveServiceImagePullMode(svc composetypes.ServiceConfig) ImagePullStep {
rawPolicy := strings.ToLower(strings.TrimSpace(svc.PullPolicy))
switch rawPolicy {
case composetypes.PullPolicyNever:
return ImagePullStep{Mode: ImagePullModeNever}
case composetypes.PullPolicyAlways:
return ImagePullStep{Mode: ImagePullModeAlways}
case composetypes.PullPolicyMissing,
composetypes.PullPolicyIfNotPresent,
composetypes.PullPolicyBuild,
"":
return ImagePullStep{Mode: ImagePullModeIfMissing}
}
// Refresh windows (daily, weekly, every_<duration>) and anything else:
// compose-go owns the parsing, matching compose's own `up` semantics —
// unknown or unparseable policies fall back to pull-if-missing.
normalized := svc
normalized.PullPolicy = rawPolicy
policy, refreshAfter, err := normalized.GetPullPolicy()
if err != nil {
slog.WarnContext(context.Background(), "failed to parse service pull_policy, defaulting to missing", //nolint:forbidigo // Pull policy parsing is a pure helper without a request context.
"service", svc.Name, "pullPolicy", svc.PullPolicy, "error", err)
return ImagePullStep{Mode: ImagePullModeIfMissing}
}
switch policy {
case composetypes.PullPolicyNever:
return ImagePullStep{Mode: ImagePullModeNever}
case composetypes.PullPolicyAlways:
return ImagePullStep{Mode: ImagePullModeAlways}
case composetypes.PullPolicyRefresh:
return ImagePullStep{Mode: ImagePullModeRefresh, RefreshAfter: refreshAfter}
default:
return ImagePullStep{Mode: ImagePullModeIfMissing}
}
}
// BuildImagePullPlan builds a deduplicated image pull plan covering non-build
// service images, pre_start hook images, and type:image volume sources.
func BuildImagePullPlan(project *composetypes.Project) map[string]ImagePullStep {
plan := map[string]ImagePullStep{}
record := func(img string, step ImagePullStep) {
img = strings.TrimSpace(img)
if img == "" {
return
}
existing, exists := plan[img]
// A higher mode wins; between two refresh policies the shorter window does.
moreEager := kit.Ternary(
step.Mode != existing.Mode,
step.Mode > existing.Mode,
step.Mode == ImagePullModeRefresh && step.RefreshAfter < existing.RefreshAfter,
)
if !exists || moreEager {
plan[img] = step
}
}
for _, svc := range project.Services {
step := ResolveServiceImagePullMode(svc)
if svc.Build == nil {
record(svc.Image, step)
}
// pre_start hook images inherit the parent service's policy, except that
// they can never be built: `build` still means pull-if-missing here.
if step.Mode != ImagePullModeNever {
for _, img := range composeapi.GetDependentImages(svc, project.Name) {
record(img, step)
}
}
for _, vol := range svc.Volumes {
if vol.Type == composetypes.VolumeTypeImage {
record(vol.Source, ImagePullStep{Mode: ImagePullModeIfMissing})
}
}
}
return plan
}
// NormalizePullPolicy normalizes compose pull policy aliases.
func NormalizePullPolicy(policy string) string {
policy = strings.ToLower(strings.TrimSpace(policy))
return kit.Ternary(policy == "if_not_present", "missing", policy)
}
// NormalizeDeployPullPolicy returns a supported deploy pull policy or empty string.
func NormalizeDeployPullPolicy(policy string) string {
normalized := NormalizePullPolicy(policy)
switch normalized {
case "always", "missing", "never":
return normalized
default:
return ""
}
}
// IsAlwaysPullPolicy reports whether policy means an unconditional pull.
// Refresh windows (daily/weekly/every_N) are not "always": they pull only
// once their window has elapsed, matching compose v5.5.0.
func IsAlwaysPullPolicy(policy string) bool {
return policy == "always"
}
// refreshWindowForPolicyInternal resolves policy as a refresh window
// (daily/weekly/every_N), reporting false for every other policy.
func refreshWindowForPolicyInternal(svc composetypes.ServiceConfig, policy string) (time.Duration, bool) {
normalized := svc
normalized.PullPolicy = policy
parsed, window, err := normalized.GetPullPolicy()
if err != nil || parsed != composetypes.PullPolicyRefresh {
return 0, false
}
return window, true
}
// DecideDeployImageAction decides whether deploy should build, pull, or require local images.
func DecideDeployImageAction(svc composetypes.ServiceConfig, pullPolicyOverride string) DeployImageDecision {
policy := NormalizePullPolicy(svc.PullPolicy)
if policy == "" {
if override := NormalizeDeployPullPolicy(pullPolicyOverride); override != "" {
policy = override
}
}
buildEnabled := svc.Build != nil
if buildEnabled {
switch {
case policy == "build":
return DeployImageDecision{Build: true}
case policy == "never":
return DeployImageDecision{RequireLocalOnly: true}
case IsAlwaysPullPolicy(policy):
return DeployImageDecision{PullAlways: true, FallbackBuildOnPullFail: true}
default:
if window, ok := refreshWindowForPolicyInternal(svc, policy); ok {
return DeployImageDecision{
PullIfStale: true,
StaleAfter: window,
FallbackBuildOnPullFail: true,
}
}
return DeployImageDecision{PullIfMissing: true, FallbackBuildOnPullFail: true}
}
}
switch {
case policy == "never":
return DeployImageDecision{RequireLocalOnly: true}
case IsAlwaysPullPolicy(policy):
return DeployImageDecision{PullAlways: true}
default:
if window, ok := refreshWindowForPolicyInternal(svc, policy); ok {
return DeployImageDecision{PullIfStale: true, StaleAfter: window}
}
return DeployImageDecision{PullIfMissing: true}
}
}