Files
pipelines/internal/server/artifacts.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

226 lines
6.2 KiB
Go

package server
import (
"errors"
"io"
"io/fs"
"log"
"mime"
"net/http"
"net/url"
"os"
"path"
"path/filepath"
"strconv"
"strings"
"syscall"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// Artifact capture is deliberately small and best-effort. A stage's artifacts
// directory is evidence, never a gate: every scan error is swallowed and never
// changes the step's outcome.
const (
maxArtifactFiles = 200
maxArtifactFileBytes = 8 << 20
maxArtifactTotalBytes = 64 << 20
artifactSniffBytes = 512
)
// scanArtifacts returns a bounded inventory of one step's artifacts directory.
// The directory path is supplied by the caller because it was created next to
// the step; runID and sequence name the served URL. A missing, unreadable,
// symlinked or oversized directory yields no entries and a zero count.
func (r *runner) scanArtifacts(runID int64, sequence int, directory string) ([]protocol.StageArtifact, int, int) {
if directory == "" || r.artifactsRoot == "" {
return nil, 0, 0
}
root, err := os.OpenRoot(r.artifactsRoot)
if err != nil {
log.Printf("stage artifacts root unavailable: %v", err)
return nil, 0, 0
}
defer root.Close()
rel := path.Join(strconv.FormatInt(runID, 10), strconv.Itoa(sequence))
if !containedDirectory(root, rel) {
return nil, 0, 0
}
files := []protocol.StageArtifact{}
skipped, truncated := 0, 0
used := int64(0)
walkErr := fs.WalkDir(root.FS(), rel, func(name string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
// A single unreadable entry must not abort the whole inventory.
return nil
}
if name == rel || entry.IsDir() {
return nil
}
if entry.Type()&fs.ModeSymlink != 0 || !entry.Type().IsRegular() {
skipped++
return nil
}
info, infoErr := entry.Info()
if infoErr != nil || !info.Mode().IsRegular() {
skipped++
return nil
}
if len(files) >= maxArtifactFiles {
skipped++
return fs.SkipAll
}
if info.Size() > maxArtifactFileBytes {
skipped++
return nil
}
if used+info.Size() > maxArtifactTotalBytes {
truncated++
return fs.SkipAll
}
artifactName := strings.TrimPrefix(name, rel+"/")
full := path.Join(rel, artifactName)
contentType := mime.TypeByExtension(filepath.Ext(artifactName))
if contentType == "" {
contentType = sniffArtifact(root, full)
if contentType == "" {
skipped++
return nil
}
}
used += info.Size()
files = append(files, protocol.StageArtifact{
Name: artifactName,
SizeBytes: info.Size(),
ContentType: contentType,
URL: artifactURL(runID, sequence, artifactName),
})
return nil
})
if walkErr != nil {
log.Printf("stage artifacts inventory run=%d step=%d: %v", runID, sequence, walkErr)
return nil, 0, 0
}
if len(files) == 0 {
files = nil
}
return files, skipped, truncated
}
// containedDirectory reports whether rel names a real directory below root with
// no symlink in any component.
func containedDirectory(root *os.Root, rel string) bool {
if rel == "" || !fs.ValidPath(rel) || rel == "." {
return false
}
parts := strings.Split(rel, "/")
for i := range parts {
info, err := root.Lstat(strings.Join(parts[:i+1], "/"))
if err != nil || info.Mode()&os.ModeSymlink != 0 {
return false
}
if i == len(parts)-1 {
return info.IsDir()
}
}
return false
}
// sniffArtifact opens one regular file without following a final symlink and
// returns the detected content type from at most the first 512 bytes.
func sniffArtifact(root *os.Root, rel string) string {
file, err := root.OpenFile(rel, os.O_RDONLY|syscall.O_NOFOLLOW, 0)
if err != nil {
return ""
}
defer file.Close()
buffer := make([]byte, artifactSniffBytes)
n, err := io.ReadFull(file, buffer)
if err != nil && !errors.Is(err, io.EOF) && !errors.Is(err, io.ErrUnexpectedEOF) {
return ""
}
return http.DetectContentType(buffer[:n])
}
// artifactURL builds the server-relative URL for one artifact, escaping each
// path segment so a name cannot forge path structure.
func artifactURL(runID int64, sequence int, name string) string {
parts := strings.Split(name, "/")
for i, part := range parts {
parts[i] = url.PathEscape(part)
}
return "/artifacts/" + strconv.FormatInt(runID, 10) + "/" + strconv.Itoa(sequence) + "/" + strings.Join(parts, "/")
}
// serveArtifact serves one recorded step artifact. It refuses unknown runs or
// steps and any name that is absolute, non-local, symlinked in any component or
// not a regular file, so nothing outside <artifactsRoot>/<run>/<step> is served.
// http.ServeContent supplies Content-Type (extension then sniff), Content-Length,
// HEAD and Range handling from the opened *os.File.
func (r *runner) serveArtifact(w http.ResponseWriter, req *http.Request) {
name := req.PathValue("name")
runID, runErr := strconv.ParseInt(req.PathValue("run"), 10, 64)
sequence, stepErr := strconv.Atoi(req.PathValue("step"))
if runErr != nil || stepErr != nil || runID <= 0 || sequence <= 0 {
http.NotFound(w, req)
return
}
if name == "" || name == "." || !fs.ValidPath(name) || path.IsAbs(name) {
http.NotFound(w, req)
return
}
detail, err := r.store.GetRun(req.Context(), runID)
if err != nil {
http.NotFound(w, req)
return
}
known := false
for _, step := range detail.Steps {
if step.Sequence == sequence {
known = true
break
}
}
if !known {
http.NotFound(w, req)
return
}
root, err := os.OpenRoot(r.artifactsRoot)
if err != nil {
http.NotFound(w, req)
return
}
defer root.Close()
rel := path.Join(strconv.FormatInt(runID, 10), strconv.Itoa(sequence))
if !containedDirectory(root, rel) {
http.NotFound(w, req)
return
}
full := path.Join(rel, name)
parts := strings.Split(full, "/")
for i := range parts {
info, lerr := root.Lstat(strings.Join(parts[:i+1], "/"))
if lerr != nil || info.Mode()&os.ModeSymlink != 0 {
http.NotFound(w, req)
return
}
}
info, err := root.Lstat(full)
if err != nil || !info.Mode().IsRegular() {
http.NotFound(w, req)
return
}
file, err := root.OpenFile(full, os.O_RDONLY|syscall.O_NOFOLLOW, 0)
if err != nil {
http.NotFound(w, req)
return
}
defer file.Close()
opened, err := file.Stat()
if err != nil || !opened.Mode().IsRegular() {
http.NotFound(w, req)
return
}
http.ServeContent(w, req, path.Base(name), opened.ModTime(), file)
}