Files
archie/internal/storage/storage.go
T
sam e4368f70af feat: persistent volumes with TTL for container/worktree storage (archie-core-j7v)
Add [containers].volume_ttl (default 72h). Persistent-storage repos get a
per-repo bare Git cache (--reference-if-able --dissociate) so task
worktrees clone fast without repeated full network clones, while staying
fully independent of the cache's lifecycle — cache expiry can never
corrupt an active or parked task's worktree. Docker repo volumes are
labeled as Archie-owned and swept non-forced (a volume still attached to a
running container survives and retries next cycle); the repo cache
directory is swept by mtime. Both cleanups run at daemon startup and each
poll cycle.

Filed archie-core-756 (repo-wide golangci-lint baseline) and archie-core-340
(intermittent JetStream TempDir teardown flake) as separate follow-ups
rather than scope-creeping them into this change.
2026-07-24 10:22:11 +10:00

317 lines
11 KiB
Go

// Package storage defines the pluggable storage backend interface for agent
// container execution. The Docker backend (DockerBackend) is the MVP
// implementation — no NFS/SMB/S3 yet, just Docker volumes + bind mounts.
//
// /data/ volume layout (implemented):
//
// /data/
// task.json — at /data/worktree/task.json (WriteTaskJSON writes
// to the worktree root, which is bind-mounted)
// worktree/ — bind mount of host worktree
// repo/ — per-repo persistent volume (optional, on request)
// cache/
// go/ — GOMODCACHE (shared across all tasks)
// node/ — npm cache (shared)
// pnpm/ — pnpm store (shared)
// deno/ — Deno module cache (shared)
// bun/ — Bun package cache (shared)
// pip/ — pip cache (shared)
// cargo/ — Rust cargo cache (shared)
//
// TODO(PRD §3): session.jsonl, memory.jsonl, plugins/ volume — these
// require agent-side implementation before the storage layer can mount
// them. session.jsonl needs per-stage structured output from the agent;
// memory.jsonl needs cross-session persistence; plugins/ needs daemon-
// staged bundled plugins.
//
// Cache volumes are named Docker volumes created once and shared across all
// tasks. They are never deleted — the daemon operator manages them.
package storage
import (
"context"
"errors"
"fmt"
"sort"
"strings"
"time"
"github.com/moby/moby/api/types/mount"
"github.com/moby/moby/client"
)
// ── types ──────────────────────────────────────────────────────────────
// TaskRef identifies a task for storage setup.
type TaskRef struct {
Owner, Repo string
IssueNumber int
Ecosystem string // "go", "node", "python", "rust", "custom"
WorktreeDir string // host path to the git worktree
PersistentStorage bool // if true, attach a per-repo Docker volume at /data/repo
}
// Mount describes a container mount point.
type Mount struct {
Type string // "bind" or "volume"
Source string // host path (bind) or volume name (volume)
Destination string // container path
}
// Mount type constants.
const (
MountTypeBind = "bind"
MountTypeVolume = "volume"
)
// WorktreeMountDir is the fixed container path where a task's worktree is
// bind-mounted. archie-agent uses this path directly rather than the host
// path archied's worktree.Manager reports — the two processes see the same
// files at different paths.
const WorktreeMountDir = "/data/worktree"
// Backend prepares container storage. Each container runtime backend
// (Docker, future containerd, etc.) implements this interface.
type Backend interface {
// Setup returns the mount specs for a task container. Must include
// at minimum a bind mount for the worktree at /data/worktree.
Setup(ctx context.Context, task TaskRef) ([]Mount, error)
// Teardown cleans up ephemeral storage. Cache volumes survive.
Teardown(ctx context.Context, task TaskRef) error
// CleanupExpired removes persistent per-repo storage older than ttl.
// Shared ecosystem caches and storage not owned by Archie survive.
CleanupExpired(ctx context.Context, ttl time.Duration) (int, error)
}
// ── cache mounts per ecosystem ─────────────────────────────────────────
// cacheVolume describes a named Docker volume that is shared across tasks.
type cacheVolume struct {
Name string // Docker volume name
MountPath string // container destination path
}
// cacheVolumesByEcosystem maps ecosystem names to their shared cache volumes.
// Volumes are created once by the pool and never deleted.
var cacheVolumesByEcosystem = map[string][]cacheVolume{
"go": {
{Name: "archie-cache-go", MountPath: "/data/cache/go"},
},
"node": {
{Name: "archie-cache-node", MountPath: "/data/cache/node"},
{Name: "archie-cache-pnpm", MountPath: "/data/cache/pnpm"},
},
"typescript": {
{Name: "archie-cache-node", MountPath: "/data/cache/node"},
{Name: "archie-cache-pnpm", MountPath: "/data/cache/pnpm"},
},
"deno": {
{Name: "archie-cache-deno", MountPath: "/data/cache/deno"},
},
"bun": {
{Name: "archie-cache-bun", MountPath: "/data/cache/bun"},
},
"python": {
{Name: "archie-cache-pip", MountPath: "/data/cache/pip"},
},
"rust": {
{Name: "archie-cache-cargo", MountPath: "/data/cache/cargo"},
},
}
// cacheMounts returns the cache mount specs for an ecosystem, sorted by
// destination path for deterministic container configuration.
// Ecosystem is case-insensitive — "Python" and "python" are equivalent.
func cacheMounts(ecosystem string) []Mount {
vols, ok := cacheVolumesByEcosystem[strings.ToLower(ecosystem)]
if !ok {
return nil
}
mounts := make([]Mount, len(vols))
for i, v := range vols {
mounts[i] = Mount{
Type: MountTypeVolume,
Source: v.Name,
Destination: v.MountPath,
}
}
sort.Slice(mounts, func(i, j int) bool {
return mounts[i].Destination < mounts[j].Destination
})
return mounts
}
// ── error types ────────────────────────────────────────────────────────
// ErrVolumeCreate is returned when a Docker volume cannot be created.
type ErrVolumeCreate struct {
Volume string
Cause error
}
func (e *ErrVolumeCreate) Error() string {
return "create volume " + e.Volume + ": " + e.Cause.Error()
}
func (e *ErrVolumeCreate) Unwrap() error { return e.Cause }
// ── Docker backend ─────────────────────────────────────────────────────
// DockerBackend implements Backend for Docker via the moby client.
type DockerBackend struct {
cli *client.Client
now func() time.Time
}
const (
storageLabel = "com.samcharles93.archie.storage"
storageKindRepo = "repo"
storageKindCache = "cache"
)
// NewDockerBackend creates a Docker storage backend.
func NewDockerBackend(cli *client.Client) *DockerBackend {
return &DockerBackend{cli: cli}
}
// ensureVolume creates a Docker volume if it doesn't already exist.
// It is idempotent: concurrent callers racing to create the same volume
// will not see an error — "already exists" is treated as success.
//
// When d.cli is nil (unit tests), ensureVolume returns nil without
// creating a volume. The returned mounts will fail at container create
// time if Docker cannot find the volume. Production code always sets
// cli via NewDockerBackend.
func (d *DockerBackend) ensureVolume(ctx context.Context, name string, labels map[string]string) error {
if d.cli == nil {
return nil // nil client for testing — volumes must be pre-created
}
// VolumeInspectOptions{} is the empty struct form (requires moby v25+).
// The go.mod pins a compatible version; zero value is always valid.
_, err := d.cli.VolumeInspect(ctx, name, client.VolumeInspectOptions{})
if err == nil {
return nil // already exists
}
_, err = d.cli.VolumeCreate(ctx, client.VolumeCreateOptions{
Name: name,
Driver: "local",
Labels: labels,
})
if err != nil {
// TOCTOU: a concurrent caller may have created the volume between
// our inspect and create calls. Docker returns an error for
// duplicate volumes — treat that as success.
if strings.Contains(err.Error(), "already exists") || strings.Contains(err.Error(), "already in use") {
return nil
}
return &ErrVolumeCreate{Volume: name, Cause: err}
}
return nil
}
// repoVolumeName returns the Docker volume name for a repo's persistent storage.
func repoVolumeName(owner, repo string) string {
return fmt.Sprintf("archie-repo-%s-%s", owner, repo)
}
// Setup returns the mount list for a task container. Mounts are ordered:
// 1. /data/worktree bind mount (always first)
// 2. /data/repo volume mount (only when PersistentStorage is true)
// 3. /data/cache/<ecosystem> volume mounts (sorted by destination)
func (d *DockerBackend) Setup(ctx context.Context, task TaskRef) ([]Mount, error) {
mounts := []Mount{
{
Type: MountTypeBind,
Source: task.WorktreeDir,
Destination: WorktreeMountDir,
},
}
// Per-repo persistent volume.
if task.PersistentStorage && task.Owner != "" && task.Repo != "" {
volName := repoVolumeName(task.Owner, task.Repo)
if err := d.ensureVolume(ctx, volName, map[string]string{storageLabel: storageKindRepo}); err != nil {
return nil, err
}
mounts = append(mounts, Mount{
Type: MountTypeVolume,
Source: volName,
Destination: "/data/repo",
})
}
caches := cacheMounts(task.Ecosystem)
for _, m := range caches {
if err := d.ensureVolume(ctx, m.Source, map[string]string{storageLabel: storageKindCache}); err != nil {
return nil, err
}
}
mounts = append(mounts, caches...)
return mounts, nil
}
// Teardown is a no-op for Docker backend. Cache volumes survive task
// completion so subsequent tasks benefit from warmed caches.
func (d *DockerBackend) Teardown(ctx context.Context, task TaskRef) error {
return nil
}
// CleanupExpired removes Archie-owned per-repo volumes whose creation time is
// at least ttl old. Docker volume labels are immutable, so the TTL is a hard
// maximum age rather than an idle lease. Removal is non-forced: a volume still
// attached to a running container is retained and retried on the next sweep.
func (d *DockerBackend) CleanupExpired(ctx context.Context, ttl time.Duration) (int, error) {
if d.cli == nil || ttl <= 0 {
return 0, nil
}
result, err := d.cli.VolumeList(ctx, client.VolumeListOptions{
Filters: client.Filters{}.Add("label", storageLabel+"="+storageKindRepo),
})
if err != nil {
return 0, fmt.Errorf("list persistent volumes: %w", err)
}
now := time.Now()
if d.now != nil {
now = d.now()
}
var (
removed int
errs []error
)
for _, vol := range result.Items {
// Defend against Docker implementations that ignore label filters.
if vol.Labels[storageLabel] != storageKindRepo {
continue
}
created, err := time.Parse(time.RFC3339Nano, vol.CreatedAt)
if err != nil {
errs = append(errs, fmt.Errorf("persistent volume %s created_at %q: %w", vol.Name, vol.CreatedAt, err))
continue
}
if now.Sub(created) < ttl {
continue
}
if _, err := d.cli.VolumeRemove(ctx, vol.Name, client.VolumeRemoveOptions{}); err != nil {
errs = append(errs, fmt.Errorf("remove persistent volume %s: %w", vol.Name, err))
continue
}
removed++
}
return removed, errors.Join(errs...)
}
// ConvertMounts converts []Mount to moby mount.Mount for container creation.
func ConvertMounts(mounts []Mount) []mount.Mount {
out := make([]mount.Mount, len(mounts))
for i, m := range mounts {
out[i] = mount.Mount{
Type: mount.Type(m.Type),
Source: m.Source,
Target: m.Destination,
}
}
return out
}