feat(cache): add locked LRU pruning

go.mod

@@ -6,6 +6,7 @@ require (
 	charm.land/log/v2 v2.0.0
 	cuelang.org/go v0.16.1
 	github.com/charmbracelet/colorprofile v0.4.2
+	github.com/gofrs/flock v0.13.0
 	github.com/lxc/incus-os/incus-osd v0.0.0-20260505023852-d32ba1f13f6f
 	github.com/meigma/imgcli/schemas v0.0.0-20260504225557-fa97d8c3fe0c
 	github.com/spf13/cobra v1.10.2

go.sum

@@ -45,6 +45,8 @@ github.com/go-quicktest/qt v1.101.0 h1:O1K29Txy5P2OK0dGo59b7b0LR6wKfIhttaAhHUyn7
 github.com/go-quicktest/qt v1.101.0/go.mod h1:14Bz/f7NwaXPtdYEgzsx46kqSxVwTbzVZsDC26tQJow=
 github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/gofrs/flock v0.13.0 h1:95JolYOvGMqeH31+FC7D2+uULf6mG61mEZ/A8dRYMzw=
+github.com/gofrs/flock v0.13.0/go.mod h1:jxeyy9R1auM5S6JYDBhDt+E2TCo7DkratH4Pgi8P+Z0=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -138,7 +140,7 @@ golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

go.work.sum

@@ -55,6 +55,7 @@ github.com/containerd/platforms v1.0.0-rc.4/go.mod h1:lKlMXyLybmBedS/JJm11uDofzI
 github.com/cowsql/go-cowsql v1.22.0/go.mod h1:+QzPcM7QRPIBI8XhsKJ47iUtxGY53lsYGX51G1WQ/4s=
 github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
 github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/cyphar/filepath-securejoin v0.6.1/go.mod h1:A8hd4EnAeyujCJRrICiOWqjS1AX0a9kM5XL+NwKoYSc=
 github.com/dgryski/go-farm v0.0.0-20240924180020-3414d57e47da/go.mod h1:SqUrOPUnsFjfmXRMNPybcSiG0BgUW2AuFH8PAnS2iTw=
 github.com/digitalocean/go-smbios v0.0.0-20180907143718-390a4f403a8e/go.mod h1:YTIHhz/QFSYnu/EhlF2SpU2Uk+32abacUYA5ZPljz1A=
@@ -152,6 +153,9 @@ github.com/knadh/koanf/providers/posflag v1.0.1/go.mod h1:3Wn3+YG3f4ljzRyCUgIwH7
 github.com/knadh/koanf/providers/structs v1.0.0/go.mod h1:kjo5TFtgpaZORlpoJqcbeLowM2cINodv8kX+oFAeQ1w=
 github.com/knadh/koanf/v2 v2.3.2/go.mod h1:gRb40VRAbd4iJMYYD5IxZ6hfuopFcXBpc9bbQpZwo28=
 github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/lmittmann/tint v1.1.3/go.mod h1:HIS3gSy7qNwGCj+5oRjAutErFBl4BzdQP6cJZ0NfMwE=
 github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
@@ -212,6 +216,7 @@ github.com/osrg/gobgp/v4 v4.5.0/go.mod h1:pgu8waqTvZUYl4eQuPrKNOaVwhHv7Zt9YymuzC
 github.com/ovn-kubernetes/libovsdb v0.8.1/go.mod h1:ZlnHLzagmLOSvyd9qfxBIZp6wOSOw0IsRsc+6lNUGbU=
 github.com/pierrec/lz4/v4 v4.1.26/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
 github.com/pires/go-proxyproto v0.12.0/go.mod h1:qUvfqUMEoX7T8g0q7TQLDnhMjdTrxnG0hvpMn+7ePNI=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/sftp v1.13.10/go.mod h1:bJ1a7uDhrX/4OII+agvy28lzRvQrmIQuaHrcI1HbeGA=
 github.com/pkg/xattr v0.4.12/go.mod h1:di8WF84zAKk8jzR1UBTEWh9AUlIZZ7M/JNt8e9B6ktU=
@@ -223,6 +228,7 @@ github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4Ul
 github.com/quasilyte/go-ruleguard/dsl v0.3.23/go.mod h1:KeCP03KrjuSO0H1kTuZQCWlQPulDV6YMIXmpQss17rU=
 github.com/rivo/tview v0.42.0/go.mod h1:cSfIYfhpSGCjp3r/ECJb+GKS7cGJnqV8vfjQPwoXyfY=
 github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/rootless-containers/proto/go-proto v0.0.0-20260207013450-f6ee952d53d9/go.mod h1:LLjEAc6zmycfeN7/1fxIphWQPjHpTt7ElqT7eVf8e4A=
 github.com/rs/cors v1.11.1/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU=
 github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
@@ -282,13 +288,17 @@ go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
 go4.org/mem v0.0.0-20240501181205-ae6ca9944745/go.mod h1:reUoABIJ9ikfM5sgtSF3Wushcza7+WeD01VB9Lirh3g=
 golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
 golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
+golang.org/x/mod v0.21.0/go.mod h1:6SkKJ3Xj0I0BrPOZoBy3bdMptDDU9oJrpohJ3eWZ1fY=
 golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/telemetry v0.0.0-20260311193753-579e4da9a98c/go.mod h1:TpUTTEp9frx7rTdLpC9gFG9kdI7zVLFTFFlqaH2Cncw=
 golang.org/x/telemetry v0.0.0-20260409153401-be6f6cb8b1fa/go.mod h1:kHjTxDEnAu6/Nl9lDkzjWpR+bmKfxeiRuSDlsMb70gE=
 golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
 golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
 golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
+golang.org/x/tools v0.26.0/go.mod h1:TPVVj70c7JJ3WCazhD8OdXcZg/og+b9+tH/KxylGwH0=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 golang.org/x/tools/go/expect v0.1.1-deprecated/go.mod h1:eihoPOH+FgIqa3FpoTwguz/bVUSGBlGQU67vpBeOrBY=
 golang.org/x/tools/go/packages/packagestest v0.1.1-deprecated/go.mod h1:RVAQXBGNv1ib0J382/DPCRS/BPnsGebyM1Gj5VSDpG8=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@@ -297,6 +307,7 @@ google.golang.org/genproto/googleapis/api v0.0.0-20260223185530-2f722ef697dc/go.
 google.golang.org/genproto/googleapis/rpc v0.0.0-20260427160629-7cedc36a6bc4/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
 google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 k8s.io/utils v0.0.0-20260319190234-28399d86e0b5/go.mod h1:xDxuJ0whA3d0I4mf/C4ppKHxXynQ+fxnkmQH0vTHnuk=
 libguestfs.org/libnbd v1.20.0/go.mod h1:pSICAuDOpSGplmGmaZ8QettnBAT3IUJFcBU1bVgWgk4=

internal/cache/cache.go

@@ -16,17 +16,21 @@ import (
 
 const (
 	cacheDirName = "imgcli"
+	lockFileName = "cache.lock"
 
 	bytesPerKiB                int64 = 1024
 	bytesPerMiB                      = bytesPerKiB * bytesPerKiB
 	bytesPerGiB                      = bytesPerMiB * bytesPerKiB
 	defaultMaxUnknownSizeGiB         = 64
 	defaultMaxUnknownSizeBytes       = defaultMaxUnknownSizeGiB * bytesPerGiB
+	defaultMaxSizeGiB                = 10
+	defaultMaxSizeBytes              = defaultMaxSizeGiB * bytesPerGiB
 
 	blobPerm          = 0o400
 	hexCharsPerByte   = 2
 	digestShardLength = 2
 	dirPerm           = 0o750
+	metadataPerm      = 0o600
 	sha256HexLength   = sha256.Size * hexCharsPerByte
 	tmpPerm           = 0o700
 	writePermMask     = 0o222
@@ -69,6 +73,7 @@ type Option func(*DiskStore)
 type DiskStore struct {
 	root                string
 	httpClient          *http.Client
+	maxSizeBytes        int64
 	maxUnknownSizeBytes int64
 }
 
@@ -88,6 +93,15 @@ func WithMaxUnknownSizeBytes(size int64) Option {
 	}
 }
 
+// WithMaxSizeBytes configures the maximum cache size for LRU pruning.
+//
+// Zero disables cache-size pruning.
+func WithMaxSizeBytes(size int64) Option {
+	return func(store *DiskStore) {
+		store.maxSizeBytes = size
+	}
+}
+
 // NewDiskStore constructs a disk-backed cache store.
 func NewDiskStore(options ...Option) (*DiskStore, error) {
 	root, err := defaultRoot()
@@ -98,6 +112,7 @@ func NewDiskStore(options ...Option) (*DiskStore, error) {
 	store := &DiskStore{
 		root:                root,
 		httpClient:          http.DefaultClient,
+		maxSizeBytes:        defaultMaxSizeBytes,
 		maxUnknownSizeBytes: defaultMaxUnknownSizeBytes,
 	}
 	for _, option := range options {
@@ -110,6 +125,9 @@ func NewDiskStore(options ...Option) (*DiskStore, error) {
 	if store.maxUnknownSizeBytes < 0 {
 		return nil, errors.New("cache max unknown-size bytes must be non-negative")
 	}
+	if store.maxSizeBytes < 0 {
+		return nil, errors.New("cache max size bytes must be non-negative")
+	}
 
 	return store, nil
 }
@@ -122,20 +140,13 @@ func (s *DiskStore) Fetch(ctx context.Context, req FetchRequest) (Blob, error) {
 	}
 
 	if normalized.ExpectedSHA256 != "" {
-		path := s.blobPath(normalized.ExpectedSHA256)
-		if pathErr := s.ensureExpectedDigestPath(path); pathErr != nil {
-			return Blob{}, pathErr
-		}
-		blob, ok, verifyErr := verifyExistingBlob(path, normalized.ExpectedSHA256, normalized.ExpectedSize)
-		if verifyErr != nil {
-			return Blob{}, verifyErr
+		blob, ok, cacheErr := s.verifiedCacheHit(normalized)
+		if cacheErr != nil {
+			return Blob{}, cacheErr
 		}
 		if ok {
 			return blob, nil
 		}
-		if removeErr := os.Remove(path); removeErr != nil && !errors.Is(removeErr, os.ErrNotExist) {
-			return Blob{}, fmt.Errorf("remove corrupt cached blob: %w", removeErr)
-		}
 	}
 
 	tmpPath, downloaded, err := s.download(ctx, normalized)
@@ -150,10 +161,37 @@ func (s *DiskStore) Fetch(ctx context.Context, req FetchRequest) (Blob, error) {
 	if err != nil {
 		return Blob{}, err
 	}
+	if touchErr := s.touchBlob(blob); touchErr != nil {
+		return Blob{}, touchErr
+	}
 
 	return blob, nil
 }
 
+func (s *DiskStore) verifiedCacheHit(req FetchRequest) (Blob, bool, error) {
+	path := s.blobPath(req.ExpectedSHA256)
+	if pathErr := s.ensureExpectedDigestPath(path); pathErr != nil {
+		return Blob{}, false, pathErr
+	}
+
+	blob, ok, verifyErr := verifyExistingBlob(path, req.ExpectedSHA256, req.ExpectedSize)
+	if verifyErr != nil {
+		return Blob{}, false, verifyErr
+	}
+	if !ok {
+		if removeErr := os.Remove(path); removeErr != nil && !errors.Is(removeErr, os.ErrNotExist) {
+			return Blob{}, false, fmt.Errorf("remove corrupt cached blob: %w", removeErr)
+		}
+		return Blob{}, false, nil
+	}
+
+	if touchErr := s.touchBlob(blob); touchErr != nil {
+		return Blob{}, false, touchErr
+	}
+
+	return blob, true, nil
+}
+
 func (s *DiskStore) ensureExpectedDigestPath(path string) error {
 	if err := s.ensureDirs(); err != nil {
 		return err
@@ -344,6 +382,8 @@ func (s *DiskStore) ensureDirs() error {
 		{path: s.root, perm: dirPerm},
 		{path: filepath.Join(s.root, "blobs"), perm: dirPerm},
 		{path: filepath.Join(s.root, "blobs", "sha256"), perm: dirPerm},
+		{path: filepath.Join(s.root, "metadata"), perm: dirPerm},
+		{path: filepath.Join(s.root, "metadata", "sha256"), perm: dirPerm},
 		{path: s.tmpDir(), perm: tmpPerm},
 	} {
 		if err := ensureCacheDir(dir.path, dir.perm); err != nil {