Files
archie/internal/container/pool.go
T
sam fd360fcc0b fix: resolve 8 remaining design-decision audit items
Fixes (4 items):
  S4 — Add TypeScript, Deno, Bun cache ecosystems to
       cacheVolumesByEcosystem. TypeScript shares node+pnpm volumes;
       Deno and Bun get dedicated cache volumes.
  R4 — Share single Docker client between container.Pool and
       storage.DockerBackend. NewPool now accepts an optional
       DockerClient in Config; if nil, creates its own. Pool
       tracks ownership (ownCli) and only closes its own client.
  S2 — Wire Storage.Teardown() call in daemon.process() after
       workflow.Run(). Docker backend is a no-op; this closes the
       interface contract for future backends.
  R5 — Emit observability event on AugmentRegistry failure.
       Previously only logged a warning; now emits a
       'registry_augment_failed' event with error detail.
       Promoted log level to Error.

Documentation (4 items):
  D1 — Document PluginRegistry as reserved for future daemon
       extension points (forge resolvers, storage backends, etc.)
  S1 — Fix /data/ layout comment to reflect actual task.json path
       (/data/worktree/task.json, not /data/task.json)
  S3 — Add TODO(PRD §3) for session.jsonl, memory.jsonl, plugins/
       volume — these need agent-side implementation first
  N6 — Document that VolumeInspectOptions{} requires moby v25+
       (go.mod pins compatible version)
  N7 — Document that _Plugin.IValue is required by Yaegi interface
       bridging; warn that go generate strips nil-guards

Test: TestCacheMountsForTypeScript verifies typescript ecosystem
returns node+pnpm volumes sorted by destination.

Verification: single client.New(client.FromEnv) in main.go;
all 21 storage tests pass; full suite green.
2026-07-22 05:00:37 +10:00

276 lines
8.3 KiB
Go

// Package container manages Docker containers running archie-agent.
// A Pool acquires and releases containers per task, handling image pull,
// creation, startup, health check, and teardown. The daemon's existing
// NATSRunner handles agent communication unchanged.
package container
import (
"context"
"encoding/json"
"fmt"
"io"
"log/slog"
"os"
"path/filepath"
"sync"
"time"
"github.com/moby/moby/api/types/container"
"github.com/moby/moby/client"
"github.com/samcharles93/archie-core/internal/storage"
)
// Container wraps a running Docker container.
type Container struct {
ID string
}
// TaskPayload is the boot-time brief written to /data/task.json before
// the container starts, per PRD section 3.
type TaskPayload struct {
ID int64 `json:"id"`
Owner string `json:"owner"`
Repo string `json:"repo"`
Number int `json:"issue_number"`
Title string `json:"title"`
Body string `json:"body"`
Labels []string `json:"labels"`
Workflow string `json:"workflow"`
Branch string `json:"branch,omitempty"`
Plan string `json:"plan,omitempty"`
}
// WriteTaskJSON writes the task payload to <workspace>/task.json.
func WriteTaskJSON(workspace string, payload TaskPayload) error {
if err := os.MkdirAll(workspace, 0o755); err != nil {
return fmt.Errorf("task.json dir: %w", err)
}
data, err := json.Marshal(payload)
if err != nil {
return err
}
return os.WriteFile(filepath.Join(workspace, "task.json"), data, 0o644)
}
// Pool manages a set of Docker containers running archie-agent.
type Pool struct {
cli *client.Client
ownCli bool // true when the pool created the client (owns Close)
cfg Config
log *slog.Logger
natsURL string
mu sync.Mutex
active int
}
// Config is the subset of daemon container configuration the pool needs.
type Config struct {
Image string
MaxConcurrency int
// MaxUptime is the total container lifetime cap from creation. When
// exceeded, the container is killed regardless of task state. PRD §4.
MaxUptime time.Duration
// GracePeriod is the idle time after task completion before the
// container is killed. The agent stays alive to handle follow-ups
// (gate re-runs, human replies) during this window. PRD §1.
GracePeriod time.Duration
PullPolicy string
// DockerClient is an optional pre-connected Docker client. When nil,
// NewPool creates its own via client.New(client.FromEnv). Pass a
// shared client to avoid multiple independent connections.
DockerClient *client.Client
}
// NewPool connects to the Docker daemon, optionally pulls the image,
// and cleans up orphaned containers from a previous daemon crash.
//
// If cfg.DockerClient is set, it is reused (caller owns Close).
// Otherwise a new client is created via client.FromEnv (pool owns Close).
func NewPool(ctx context.Context, cfg Config, natsURL string, log *slog.Logger) (*Pool, error) {
cli := cfg.DockerClient
if cli == nil {
var err error
cli, err = client.New(client.FromEnv)
if err != nil {
return nil, fmt.Errorf("docker client: %w", err)
}
}
p := &Pool{
cli: cli,
cfg: cfg,
log: log,
natsURL: natsURL,
ownCli: cfg.DockerClient == nil,
}
// Pull image if needed.
if cfg.PullPolicy == "always" || cfg.PullPolicy == "missing" {
if err := p.pullImage(ctx); err != nil {
cli.Close()
return nil, err
}
}
// Recover orphaned containers from a previous daemon crash.
p.recoverOrphans(ctx)
return p, nil
}
// Acquire creates and starts a container with the given mounts and
// environment variables. Mounts are provided by the caller (typically
// from a storage.Backend). If MaxUptime is set, the container is
// created with a deadline — Docker kills it when the time elapses.
func (p *Pool) Acquire(ctx context.Context, mounts []storage.Mount, env []string) (*Container, error) {
p.mu.Lock()
if p.cfg.MaxConcurrency > 0 && p.active >= p.cfg.MaxConcurrency {
p.mu.Unlock()
return nil, fmt.Errorf("max concurrency %d reached", p.cfg.MaxConcurrency)
}
p.active++
p.mu.Unlock()
// Enforce MaxUptime via container-level timeout.
if p.cfg.MaxUptime > 0 {
var cancel context.CancelFunc
ctx, cancel = context.WithTimeout(ctx, p.cfg.MaxUptime)
defer cancel()
}
name := fmt.Sprintf("archie-agent-%d", time.Now().UnixNano())
resp, err := p.cli.ContainerCreate(ctx, client.ContainerCreateOptions{
Name: name,
Config: &container.Config{
Image: p.cfg.Image,
Env: env,
Labels: map[string]string{
"archie-daemon": "true",
},
},
HostConfig: &container.HostConfig{
Mounts: storage.ConvertMounts(mounts),
AutoRemove: true,
},
})
if err != nil {
p.mu.Lock()
p.active--
p.mu.Unlock()
return nil, fmt.Errorf("container create: %w", err)
}
if _, err := p.cli.ContainerStart(ctx, resp.ID, client.ContainerStartOptions{}); err != nil {
// Best-effort cleanup.
p.cli.ContainerRemove(context.Background(), resp.ID, client.ContainerRemoveOptions{Force: true})
p.mu.Lock()
p.active--
p.mu.Unlock()
return nil, fmt.Errorf("container start: %w", err)
}
p.log.Info("container started", "id", resp.ID[:12], "name", name)
return &Container{ID: resp.ID}, nil
}
// Release stops and removes a container after a task completes. If
// GracePeriod is configured, the container stays alive for that duration
// before being killed — the agent can handle follow-ups (gate re-runs,
// human replies) during this window. PRD section 1.
func (p *Pool) Release(c *Container) {
if c == nil {
return
}
// Honour the post-completion grace period.
if p.cfg.GracePeriod > 0 {
p.log.Info("container keeping alive for grace period", "id", c.ID[:12], "grace", p.cfg.GracePeriod)
time.Sleep(p.cfg.GracePeriod)
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if _, err := p.cli.ContainerStop(ctx, c.ID, client.ContainerStopOptions{}); err != nil {
p.log.Warn("container stop failed", "id", c.ID[:12], "err", err)
}
p.cli.ContainerRemove(context.Background(), c.ID, client.ContainerRemoveOptions{Force: true})
p.mu.Lock()
p.active--
p.mu.Unlock()
p.log.Info("container released", "id", c.ID[:12])
}
// Close stops and removes all active containers. If the pool created its
// own Docker client, it is closed. Shared clients are not closed.
func (p *Pool) Close() error {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
list, err := p.cli.ContainerList(ctx, client.ContainerListOptions{
All: true,
Filters: client.Filters{}.Add("label", "archie-daemon=true"),
})
if err != nil {
p.log.Warn("container list failed during close", "err", err)
} else {
for _, c := range list.Items {
p.log.Info("cleaning up container", "id", c.ID[:12])
p.cli.ContainerStop(ctx, c.ID, client.ContainerStopOptions{})
p.cli.ContainerRemove(ctx, c.ID, client.ContainerRemoveOptions{Force: true})
}
}
if p.ownCli {
return p.cli.Close()
}
return nil
}
// ── helpers ──────────────────────────────────────────────────────────
// pullImage pulls the configured image. On "missing" policy, skips if
// the image already exists locally.
func (p *Pool) pullImage(ctx context.Context) error {
ref := p.cfg.Image
if p.cfg.PullPolicy == "missing" {
_, err := p.cli.ImageInspect(ctx, ref)
if err == nil {
p.log.Info("image already present", "image", ref)
return nil
}
}
p.log.Info("pulling image", "image", ref)
rc, err := p.cli.ImagePull(ctx, ref, client.ImagePullOptions{})
if err != nil {
return fmt.Errorf("pull %s: %w", ref, err)
}
defer rc.Close()
io.Copy(io.Discard, rc)
p.log.Info("image pulled", "image", ref)
return nil
}
// recoverOrphans stops and removes containers left by a previous daemon.
func (p *Pool) recoverOrphans(ctx context.Context) {
list, err := p.cli.ContainerList(ctx, client.ContainerListOptions{
All: true,
Filters: client.Filters{}.Add("label", "archie-daemon=true"),
})
if err != nil {
return
}
for _, c := range list.Items {
p.log.Info("recovering orphaned container", "id", c.ID[:12])
p.cli.ContainerStop(ctx, c.ID, client.ContainerStopOptions{})
p.cli.ContainerRemove(ctx, c.ID, client.ContainerRemoveOptions{Force: true})
}
if len(list.Items) > 0 {
p.log.Info("orphan recovery complete", "count", len(list.Items))
}
}