Add layer-level caching for rootfs extraction

Introduce per-layer content-addressable caching keyed by DiffID
(uncompressed content hash), so shared base layers across images are
extracted only once. Uncached layers are extracted in parallel with
bounded concurrency, then composed sequentially with OCI whiteout
support. Falls back to flat mutate.Extract on failure.

Security: path containment checks on whiteouts, symlink target
validation during composition, shared atomic size budget across
layers to prevent decompression bombs.

Closes #19

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: JAORMX

image/cache.go

@@ -35,6 +35,15 @@ func (c *Cache) BaseDir() string {
 	return c.baseDir
 }
 
+// LayerCache returns the per-layer cache, creating the layers/ subdirectory
+// lazily. Returns nil if the receiver is nil.
+func (c *Cache) LayerCache() *LayerCache {
+	if c == nil {
+		return nil
+	}
+	return NewLayerCache(filepath.Join(c.baseDir, "layers"))
+}
+
 // Get returns the path to a cached rootfs for the given digest, and true
 // if it exists and appears valid. Returns ("", false) on a cache miss.
 // On a hit, the entry's modification time is updated so that Evict does
@@ -125,6 +134,14 @@ func (c *Cache) Evict(maxAge time.Duration) (int, error) {
 		}
 	}
 
+	// Also evict from the per-layer cache.
+	lc := c.LayerCache()
+	layerRemoved, err := lc.Evict(maxAge)
+	if err != nil {
+		return removed, fmt.Errorf("evict layer cache: %w", err)
+	}
+	removed += layerRemoved
+
 	return removed, nil
 }
 

image/layer_cache.go

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package image
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	v1 "github.com/google/go-containerregistry/pkg/v1"
+)
+
+// LayerCache provides content-addressable caching of individual OCI image layers.
+// Layers are cached by their DiffID (uncompressed content hash from the image
+// config), which is stable across registries and compression changes.
+type LayerCache struct {
+	baseDir string
+}
+
+// NewLayerCache creates a new layer cache rooted at baseDir. The directory is
+// created lazily when the first entry is stored.
+func NewLayerCache(baseDir string) *LayerCache {
+	return &LayerCache{baseDir: baseDir}
+}
+
+// Has returns true if a cached layer exists for the given DiffID.
+func (lc *LayerCache) Has(diffID v1.Hash) bool {
+	_, ok := lc.Get(diffID)
+	return ok
+}
+
+// Get returns the path to a cached layer for the given DiffID, and true
+// if it exists and appears valid. Returns ("", false) on a cache miss.
+// On a hit, the entry's modification time is updated so that Evict does
+// not remove frequently used entries.
+func (lc *LayerCache) Get(diffID v1.Hash) (string, bool) {
+	dir := lc.pathFor(diffID)
+
+	info, err := os.Stat(dir)
+	if err != nil || !info.IsDir() {
+		return "", false
+	}
+
+	// Touch mtime so Evict treats this as recently used.
+	now := time.Now()
+	_ = os.Chtimes(dir, now, now)
+
+	return dir, true
+}
+
+// Put records that tempDir contains the extracted layer for diffID.
+// It moves (renames) tempDir into the cache directory. After a
+// successful Put, tempDir should no longer be used directly;
+// callers should use the path returned by Get instead.
+func (lc *LayerCache) Put(diffID v1.Hash, tempDir string) error {
+	if err := os.MkdirAll(lc.baseDir, 0o700); err != nil {
+		return fmt.Errorf("create layer cache dir: %w", err)
+	}
+
+	dst := lc.pathFor(diffID)
+
+	// If the destination already exists, another concurrent extraction may
+	// have beaten us. Remove the duplicate we just extracted.
+	if _, err := os.Stat(dst); err == nil {
+		_ = os.RemoveAll(tempDir)
+		return nil
+	}
+
+	if err := os.Rename(tempDir, dst); err != nil {
+		return fmt.Errorf("move layer to cache: %w", err)
+	}
+
+	return nil
+}
+
+// TempDir creates a temporary directory inside the cache's base directory.
+// This ensures os.Rename in Put stays on the same filesystem, avoiding
+// cross-device link errors (e.g. /tmp on tmpfs vs cache on a different mount).
+func (lc *LayerCache) TempDir() (string, error) {
+	if err := os.MkdirAll(lc.baseDir, 0o700); err != nil {
+		return "", fmt.Errorf("create layer cache dir: %w", err)
+	}
+	return os.MkdirTemp(lc.baseDir, "tmp-layer-*")
+}
+
+// Evict removes cached entries whose modification time is older than maxAge.
+// Stale temporary directories (tmp-*) from interrupted extractions are also
+// cleaned if they are older than maxAge. Returns the number of entries removed.
+func (lc *LayerCache) Evict(maxAge time.Duration) (int, error) {
+	entries, err := os.ReadDir(lc.baseDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, nil
+		}
+		return 0, fmt.Errorf("read layer cache dir: %w", err)
+	}
+
+	cutoff := time.Now().Add(-maxAge)
+	removed := 0
+
+	for _, entry := range entries {
+		info, err := entry.Info()
+		if err != nil {
+			continue
+		}
+
+		if info.ModTime().Before(cutoff) {
+			entryPath := filepath.Join(lc.baseDir, entry.Name())
+			if err := os.RemoveAll(entryPath); err != nil {
+				continue
+			}
+			removed++
+		}
+	}
+
+	return removed, nil
+}
+
+// pathFor converts a DiffID into a filesystem path inside the cache directory.
+func (lc *LayerCache) pathFor(diffID v1.Hash) string {
+	safe := diffID.Algorithm + "-" + diffID.Hex
+	return filepath.Join(lc.baseDir, safe)
+}

image/layer_cache_test.go

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package image
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	v1 "github.com/google/go-containerregistry/pkg/v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var testDiffID = v1.Hash{Algorithm: "sha256", Hex: "deadbeef1234567890abcdef"}
+
+func TestLayerCache_Has_EmptyCache(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+	lc := NewLayerCache(tmpDir)
+
+	assert.False(t, lc.Has(testDiffID))
+}
+
+func TestLayerCache_Get_UnknownDiffID(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+	lc := NewLayerCache(tmpDir)
+
+	path, ok := lc.Get(testDiffID)
+	assert.False(t, ok)
+	assert.Empty(t, path)
+}
+
+func TestLayerCache_PutGet_RoundTrip(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	lc := NewLayerCache(cacheDir)
+
+	// Create a temporary directory to simulate an extracted layer.
+	layerDir := t.TempDir()
+	markerFile := filepath.Join(layerDir, "marker.txt")
+	err := os.WriteFile(markerFile, []byte("layer content"), 0o644)
+	require.NoError(t, err)
+
+	// Put the layer into the cache.
+	err = lc.Put(testDiffID, layerDir)
+	require.NoError(t, err)
+
+	// The original layerDir should have been renamed (moved).
+	_, err = os.Stat(layerDir)
+	assert.True(t, os.IsNotExist(err), "original layer dir should no longer exist after Put")
+
+	// Get should return the cached path.
+	cachedPath, ok := lc.Get(testDiffID)
+	require.True(t, ok)
+	assert.NotEmpty(t, cachedPath)
+
+	// Verify the marker file is present in the cached directory.
+	data, err := os.ReadFile(filepath.Join(cachedPath, "marker.txt"))
+	require.NoError(t, err)
+	assert.Equal(t, "layer content", string(data))
+
+	// Has should also return true now.
+	assert.True(t, lc.Has(testDiffID))
+}
+
+func TestLayerCache_DoublePut_NoConcurrencyError(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	lc := NewLayerCache(cacheDir)
+
+	// First put.
+	layer1 := t.TempDir()
+	err := os.WriteFile(filepath.Join(layer1, "first"), []byte("1"), 0o644)
+	require.NoError(t, err)
+
+	err = lc.Put(testDiffID, layer1)
+	require.NoError(t, err)
+
+	// Second put with a different dir should succeed without error.
+	// The second dir should be cleaned up since the cache entry already exists.
+	layer2 := t.TempDir()
+	err = os.WriteFile(filepath.Join(layer2, "second"), []byte("2"), 0o644)
+	require.NoError(t, err)
+
+	err = lc.Put(testDiffID, layer2)
+	require.NoError(t, err)
+
+	// The second layer directory should have been removed.
+	_, err = os.Stat(layer2)
+	assert.True(t, os.IsNotExist(err), "second layer dir should be removed on duplicate Put")
+
+	// The original cached content should still be intact.
+	cachedPath, ok := lc.Get(testDiffID)
+	require.True(t, ok)
+
+	data, err := os.ReadFile(filepath.Join(cachedPath, "first"))
+	require.NoError(t, err)
+	assert.Equal(t, "1", string(data))
+}
+
+func TestLayerCache_TempDir_SameFilesystem(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	lc := NewLayerCache(cacheDir)
+
+	tmpDir, err := lc.TempDir()
+	require.NoError(t, err)
+	defer func() { _ = os.RemoveAll(tmpDir) }()
+
+	// The temp dir should be under the cache's base directory.
+	assert.True(t, strings.HasPrefix(tmpDir, cacheDir),
+		"temp dir %q should be under cache dir %q", tmpDir, cacheDir)
+}
+
+func TestLayerCache_Evict_RemovesOldEntries(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	lc := NewLayerCache(cacheDir)
+
+	// Create a cache entry and backdate its mtime.
+	oldDir := filepath.Join(cacheDir, "sha256-old")
+	require.NoError(t, os.MkdirAll(oldDir, 0o700))
+	oldTime := time.Now().Add(-10 * 24 * time.Hour)
+	require.NoError(t, os.Chtimes(oldDir, oldTime, oldTime))
+
+	removed, err := lc.Evict(7 * 24 * time.Hour)
+	require.NoError(t, err)
+	assert.Equal(t, 1, removed)
+
+	// Old entry should be gone.
+	_, err = os.Stat(oldDir)
+	assert.True(t, os.IsNotExist(err))
+}
+
+func TestLayerCache_Evict_PreservesFreshEntries(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	lc := NewLayerCache(cacheDir)
+
+	// Create a fresh cache entry.
+	freshDir := filepath.Join(cacheDir, "sha256-fresh")
+	require.NoError(t, os.MkdirAll(freshDir, 0o700))
+
+	removed, err := lc.Evict(7 * 24 * time.Hour)
+	require.NoError(t, err)
+	assert.Equal(t, 0, removed)
+
+	// Fresh entry should still exist.
+	_, err = os.Stat(freshDir)
+	assert.NoError(t, err)
+}
+
+func TestLayerCache_Get_TouchesMtime(t *testing.T) {
+	t.Parallel()
+
+	cacheDir := t.TempDir()
+	lc := NewLayerCache(cacheDir)
+
+	// Create a cache entry and backdate it.
+	entryDir := lc.pathFor(testDiffID)
+	require.NoError(t, os.MkdirAll(entryDir, 0o700))
+	oldTime := time.Now().Add(-10 * 24 * time.Hour)
+	require.NoError(t, os.Chtimes(entryDir, oldTime, oldTime))
+
+	// Get should update the mtime.
+	before := time.Now()
+	path, ok := lc.Get(testDiffID)
+	require.True(t, ok)
+	assert.Equal(t, entryDir, path)
+
+	info, err := os.Stat(entryDir)
+	require.NoError(t, err)
+	assert.True(t, info.ModTime().After(before) || info.ModTime().Equal(before),
+		"Get should update mtime to prevent eviction")
+}
+
+func TestLayerCache_Evict_NonExistentDir(t *testing.T) {
+	t.Parallel()
+
+	lc := NewLayerCache(filepath.Join(t.TempDir(), "does-not-exist"))
+
+	removed, err := lc.Evict(7 * 24 * time.Hour)
+	require.NoError(t, err)
+	assert.Equal(t, 0, removed)
+}