Files
pipelines/internal/server/artifacts_test.go
T
alan 0f5a188c6a Record and serve per-stage artifacts
Every agent stage now writes into a per-run/step artifacts directory under
the data dir (<data>/artifacts/<run>/<step>), passed to Pi as
PIPELINES_ARTIFACTS_DIR, exposed on the OpenCode client env seam, and stated
in the agent prompt boilerplate so agents save images, screenshots, reports
and logs there.

After each step the server scans that directory with a bounded, symlink- and
traversal-safe inventory (os.OpenRoot + Lstat + O_NOFOLLOW) recording name,
size_bytes, content type (extension then 512-byte sniff fallback) and URL,
enforcing max files, per-file bytes and total bytes while counting skipped
and truncated entries. A missing, unreadable or oversized directory yields
only a best-effort diagnostic and never changes the step outcome.

The list is carried on protocol.RunStep as Artifacts []StageArtifact plus
skipped/truncated counters (omitempty, backwards compatible), persisted in a
new step_artifacts table keyed (run_id, sequence) alongside the
notifications/file-changes tables and loaded by GetRun.

GET /artifacts/{run}/{step}/{name} on the existing handler serves the bytes
with http.ServeContent, so Content-Type, Content-Length, HEAD and Range
(206/416) come from the stdlib; unknown runs/steps, absolute paths,
traversal, symlink escapes and non-regular files are refused.

The TUI lists each selected step's artifacts (name + human size) in the
retained-evidence section and adds an artifacts summary in the style of the
file-changes summary. Adds docs/stage-artifacts.md linked from README and an
artifacts subsection to the packaged operations skill reference.

Tests cover the scan records and caps, missing/oversized directories,
HTTP HEAD/Range/traversal/symlink/unknown refusals and protocol round-trips.
2026-10-15 17:51:18 +01:00

279 lines
9.1 KiB
Go

package server
import (
"bytes"
"context"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
"git.a-wan.net/alan/pipelines/internal/stage"
)
func artifactNamed(files []protocol.StageArtifact, name string) (protocol.StageArtifact, bool) {
for _, file := range files {
if file.Name == name {
return file, true
}
}
return protocol.StageArtifact{}, false
}
func TestArtifactsScanRecordsSizesTypesAndSkips(t *testing.T) {
root := t.TempDir()
stepDir := filepath.Join(root, "4", "2")
if err := os.MkdirAll(filepath.Join(stepDir, "reports"), 0700); err != nil {
t.Fatal(err)
}
png := []byte("\x89PNG\r\n\x1a\n...png bytes...")
if err := os.WriteFile(filepath.Join(stepDir, "shot.png"), png, 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(stepDir, "notes"), []byte("hello artifacts"), 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(stepDir, "reports", "out.txt"), []byte("report"), 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(stepDir, "big.bin"), make([]byte, maxArtifactFileBytes+1), 0600); err != nil {
t.Fatal(err)
}
if err := os.Symlink(filepath.Join(stepDir, "shot.png"), filepath.Join(stepDir, "alias.png")); err != nil {
t.Fatal(err)
}
r := &runner{artifactsRoot: root}
files, skipped, truncated := r.scanArtifacts(4, 2, stepDir)
if truncated != 0 {
t.Fatalf("unexpected truncation: %d", truncated)
}
if skipped < 2 {
t.Fatalf("oversized file and symlink must be skipped: %d", skipped)
}
shot, ok := artifactNamed(files, "shot.png")
if !ok || shot.SizeBytes != int64(len(png)) || shot.ContentType != "image/png" || shot.URL != "/artifacts/4/2/shot.png" {
t.Fatalf("png artifact wrong: %+v", shot)
}
notes, ok := artifactNamed(files, "notes")
if !ok || !strings.HasPrefix(notes.ContentType, "text/plain") {
t.Fatalf("extensionless artifact not sniffed: %+v", notes)
}
if nested, ok := artifactNamed(files, "reports/out.txt"); !ok || nested.SizeBytes != int64(len("report")) {
t.Fatalf("nested artifact missing: %+v", files)
}
if _, ok := artifactNamed(files, "alias.png"); ok {
t.Fatal("symlink must not be recorded")
}
if _, ok := artifactNamed(files, "big.bin"); ok {
t.Fatal("oversized artifact must not be recorded")
}
}
func TestArtifactsScanBoundsFileCount(t *testing.T) {
root := t.TempDir()
stepDir := filepath.Join(root, "1", "1")
if err := os.MkdirAll(stepDir, 0700); err != nil {
t.Fatal(err)
}
for i := 0; i < maxArtifactFiles+5; i++ {
name := filepath.Join(stepDir, fmt.Sprintf("f%04d", i))
if err := os.WriteFile(name, []byte("x"), 0600); err != nil {
t.Fatal(err)
}
}
r := &runner{artifactsRoot: root}
files, skipped, _ := r.scanArtifacts(1, 1, stepDir)
if len(files) != maxArtifactFiles {
t.Fatalf("file cap not enforced: %d", len(files))
}
if skipped == 0 {
t.Fatal("over-cap files were not counted as skipped")
}
}
func TestArtifactsScanMissingDirectoryIsEmpty(t *testing.T) {
r := &runner{artifactsRoot: t.TempDir()}
files, skipped, truncated := r.scanArtifacts(1, 1, filepath.Join(t.TempDir(), "absent"))
if len(files) != 0 || skipped != 0 || truncated != 0 {
t.Fatalf("missing directory must be empty: %+v %d %d", files, skipped, truncated)
}
}
// runWithArtifact executes one real run whose stage writes a file into the
// runner-provided artifacts directory. It returns the live handler and the
// recorded step so tests can serve the artifact over the real HTTP endpoint.
func runWithArtifact(t *testing.T) (*runHandler, protocol.RunStep) {
t.Helper()
ctx, cancel := context.WithCancel(context.Background())
t.Cleanup(cancel)
store, err := pipeline.Open(filepath.Join(t.TempDir(), "artifacts.db"))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { store.Close() })
if _, err := store.Submit(ctx, "artifacts", pipeline.Template([]string{"one"}, true)); err != nil {
t.Fatal(err)
}
items, err := store.List(ctx)
if err != nil {
t.Fatal(err)
}
handler := Handler(ctx, store).(*runHandler)
t.Cleanup(func() { cancel(); WaitRuns(handler) })
handler.runner.artifactsRoot = t.TempDir()
handler.runner.execute = func(_ context.Context, def stage.Definition, _ stage.Values) (stage.Result, error) {
if def.ArtifactsDir == "" {
t.Error("runner did not provide an artifacts directory")
return stage.Result{Outcome: "success"}, nil
}
if err := os.WriteFile(filepath.Join(def.ArtifactsDir, "report.txt"), []byte("artifact bytes"), 0600); err != nil {
return stage.Result{}, err
}
return stage.Result{Outcome: "success", Output: stage.Values{"summary": "done"}}, nil
}
dir := t.TempDir()
run, err := handler.runner.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "artifact", Workspace: dir, Input: map[string]any{"prompt": "task"}})
if err != nil {
t.Fatal(err)
}
handler.runner.wg.Wait()
detail, err := store.GetRun(ctx, run.ID)
if err != nil {
t.Fatal(err)
}
if detail.Status != "succeeded" || len(detail.Steps) != 1 {
t.Fatalf("unexpected run: %+v", detail)
}
step := detail.Steps[0]
if len(step.Artifacts) != 1 {
t.Fatalf("artifact not retained: %+v", step.Artifacts)
}
artifact := step.Artifacts[0]
if artifact.Name != "report.txt" || artifact.SizeBytes != int64(len("artifact bytes")) ||
!strings.HasPrefix(artifact.ContentType, "text/plain") || artifact.URL == "" {
t.Fatalf("recorded artifact wrong: %+v", artifact)
}
return handler, step
}
func TestArtifactHTTPGetHeadRangeAndRefusals(t *testing.T) {
handler, step := runWithArtifact(t)
srv := httptest.NewServer(handler)
defer srv.Close()
base := srv.URL + step.Artifacts[0].URL
payload := []byte("artifact bytes")
resp, err := http.Get(base)
if err != nil {
t.Fatal(err)
}
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
if resp.StatusCode != http.StatusOK || !bytes.Equal(body, payload) {
t.Fatalf("GET wrong: %d %q", resp.StatusCode, body)
}
if ct := resp.Header.Get("Content-Type"); !strings.HasPrefix(ct, "text/plain") {
t.Fatalf("GET content type wrong: %q", ct)
}
if cl := resp.Header.Get("Content-Length"); cl != fmt.Sprint(len(payload)) {
t.Fatalf("GET content length wrong: %q", cl)
}
head, err := http.Head(base)
if err != nil {
t.Fatal(err)
}
headBody, _ := io.ReadAll(head.Body)
head.Body.Close()
if head.StatusCode != http.StatusOK || len(headBody) != 0 {
t.Fatalf("HEAD wrong: %d %q", head.StatusCode, headBody)
}
if head.Header.Get("Content-Length") != fmt.Sprint(len(payload)) {
t.Fatalf("HEAD lost content length: %q", head.Header.Get("Content-Length"))
}
rangeReq, _ := http.NewRequest(http.MethodGet, base, nil)
rangeReq.Header.Set("Range", "bytes=0-3")
rangeResp, err := http.DefaultClient.Do(rangeReq)
if err != nil {
t.Fatal(err)
}
rangeBody, _ := io.ReadAll(rangeResp.Body)
rangeResp.Body.Close()
if rangeResp.StatusCode != http.StatusPartialContent || !bytes.Equal(rangeBody, payload[:4]) {
t.Fatalf("Range wrong: %d %q", rangeResp.StatusCode, rangeBody)
}
if got := rangeResp.Header.Get("Content-Range"); got != fmt.Sprintf("bytes 0-3/%d", len(payload)) {
t.Fatalf("Content-Range wrong: %q", got)
}
unsatReq, _ := http.NewRequest(http.MethodGet, base, nil)
unsatReq.Header.Set("Range", "bytes=9999-10000")
unsatResp, err := http.DefaultClient.Do(unsatReq)
if err != nil {
t.Fatal(err)
}
unsatResp.Body.Close()
if unsatResp.StatusCode != http.StatusRequestedRangeNotSatisfiable {
t.Fatalf("unsatisfiable Range wrong: %d", unsatResp.StatusCode)
}
// Unknown run and unknown step must not serve bytes.
for _, path := range []string{"/artifacts/999999/1/report.txt", fmt.Sprintf("/artifacts/%d/99/report.txt", runIDFromURL(step.Artifacts[0].URL))} {
resp, err := http.Get(srv.URL + path)
if err != nil {
t.Fatal(err)
}
resp.Body.Close()
if resp.StatusCode != http.StatusNotFound {
t.Fatalf("%s expected 404, got %d", path, resp.StatusCode)
}
}
}
func runIDFromURL(url string) int64 {
var id int64
fmt.Sscanf(url, "/artifacts/%d/", &id)
return id
}
func TestArtifactHTTPRefusesEscapes(t *testing.T) {
handler, step := runWithArtifact(t)
runID := runIDFromURL(step.Artifacts[0].URL)
root := handler.runner.artifactsRoot
// A symlink inside the step directory must never be followed.
stepDir := filepath.Join(root, fmt.Sprint(runID), "1")
secret := filepath.Join(t.TempDir(), "secret.txt")
if err := os.WriteFile(secret, []byte("secret"), 0600); err != nil {
t.Fatal(err)
}
if err := os.Symlink(secret, filepath.Join(stepDir, "escape.txt")); err != nil {
t.Fatal(err)
}
srv := httptest.NewServer(handler)
defer srv.Close()
for _, path := range []string{
fmt.Sprintf("/artifacts/%d/1/escape.txt", runID),
fmt.Sprintf("/artifacts/%d/1/%%2e%%2e/%%2e%%2e/secret.txt", runID),
fmt.Sprintf("/artifacts/%d/1/%%2Fetc%%2Fpasswd", runID),
} {
resp, err := http.Get(srv.URL + path)
if err != nil {
t.Fatal(err)
}
body, _ := io.ReadAll(resp.Body)
resp.Body.Close()
if resp.StatusCode == http.StatusOK || bytes.Contains(body, []byte("secret")) {
t.Fatalf("%s served forbidden bytes: %d %q", path, resp.StatusCode, body)
}
}
}