Files
alan 14175eba70 retention: explicit run-history and artifact retention
Add `pipelines retention report` (strictly read-only) and
`pipelines retention apply` (explicit, approval-gated removal) with an age
and/or count policy, protected-run rules, atomic single-transaction removal
and honest database space reclaim. Nothing prunes automatically.
2026-10-17 15:45:46 +01:00

219 lines
7.3 KiB
Go

package cli
import (
"context"
"fmt"
"os"
"path/filepath"
"strconv"
"strings"
"time"
"git.a-wan.net/alan/pipelines/internal/paths"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/tui"
)
// retention implements the local maintenance command: `report` describes what a
// policy would remove without touching anything, and `apply` removes it after
// explicit approval. It is dispatched before server URL resolution, so it works
// against a local database without a running server and never mutates the
// deployed server's configuration or definitions.
func (a App) retention(ctx context.Context, o *options, pos []string) error {
if len(pos) != 1 {
return fmt.Errorf("retention requires a subcommand: report or apply; use pipelines help retention")
}
sub := pos[0]
if sub != "report" && sub != "apply" {
return fmt.Errorf("unknown retention subcommand %q; use report or apply", sub)
}
policy, err := o.retentionPolicy()
if err != nil {
return err
}
db := strings.TrimSpace(o.db)
if db == "" {
db, err = paths.Database()
if err != nil {
return err
}
}
if _, err := os.Stat(db); err != nil {
return fmt.Errorf("retention database %s is unavailable: %w", db, err)
}
artifacts := strings.TrimSpace(o.artifacts)
if artifacts == "" {
artifacts = filepath.Join(filepath.Dir(db), "artifacts")
}
now := time.Now().UTC()
if sub == "report" {
store, err := pipeline.OpenReadOnly(db)
if err != nil {
return err
}
defer store.Close()
report, err := store.RetentionReport(ctx, policy, artifacts, now)
if err != nil {
return err
}
return a.printRetentionReport(report, o.json)
}
store, err := pipeline.OpenMaintenance(db)
if err != nil {
return err
}
defer store.Close()
if !o.yes {
preview, err := store.RetentionReport(ctx, policy, artifacts, now)
if err != nil {
return err
}
question := fmt.Sprintf("Permanently remove %d run(s) and %s of artifacts? Definitions and versions are never touched.",
len(preview.WouldRemove), tui.HumanBytes(preview.ArtifactBytes))
if err := a.confirmAction(question, false); err != nil {
if printErr := a.printRetentionReport(preview, o.json); printErr != nil {
return printErr
}
return err
}
}
result, err := store.ApplyRetention(ctx, policy, artifacts, now)
if result != nil {
// Print the report even on a refusal, cleanup or vacuum error so the
// selection and reasons stay visible.
if printErr := a.printRetentionResult(result, o.json); printErr != nil {
return printErr
}
}
return err
}
// retentionPolicy converts the parsed flags into a validated policy. An unset
// --keep is -1 (no count bound) so it is distinguishable from --keep 0.
func (o *options) retentionPolicy() (pipeline.RetentionPolicy, error) {
policy := pipeline.RetentionPolicy{Keep: -1}
if raw := strings.TrimSpace(o.olderThan); raw != "" {
duration, err := parseRetentionDuration(raw)
if err != nil {
return policy, err
}
if duration <= 0 {
return policy, fmt.Errorf("--older-than must be a positive duration")
}
policy.OlderThan = duration
}
if o.keepSet {
if o.keep < 0 {
return policy, fmt.Errorf("--keep must be nonnegative")
}
policy.Keep = o.keep
}
if err := policy.Validate(); err != nil {
return policy, err
}
return policy, nil
}
// parseRetentionDuration accepts Go durations plus a count of days or weeks,
// so an operator can write 720h, 30d or 12w. The result is a rolling duration,
// never a calendar-day boundary.
func parseRetentionDuration(value string) (time.Duration, error) {
value = strings.TrimSpace(value)
if value == "" {
return 0, fmt.Errorf("duration is empty")
}
unit, number := time.Duration(0), value
switch {
case strings.HasSuffix(value, "d"):
unit, number = 24*time.Hour, strings.TrimSuffix(value, "d")
case strings.HasSuffix(value, "w"):
unit, number = 7*24*time.Hour, strings.TrimSuffix(value, "w")
}
if unit != 0 {
count, err := strconv.ParseFloat(number, 64)
if err != nil {
return 0, fmt.Errorf("invalid duration %q: use Go durations or a count of d/w", value)
}
return time.Duration(count * float64(unit)), nil
}
duration, err := time.ParseDuration(value)
if err != nil {
return 0, fmt.Errorf("invalid duration %q: %w", value, err)
}
return duration, nil
}
func (a App) printRetentionReport(report *pipeline.RetentionReport, jsonOutput bool) error {
if jsonOutput {
return a.output(report)
}
writeRetention(a.Out, report)
fmt.Fprintln(a.Out, "\nNo changes made.")
return nil
}
func (a App) printRetentionResult(result *pipeline.RetentionApplyResult, jsonOutput bool) error {
if jsonOutput {
return a.output(result)
}
writeRetention(a.Out, &result.RetentionReport)
fmt.Fprintf(a.Out, "\nRemoved %d run(s) · %d files · %s\n", result.RemovedRunCount, result.RemovedArtifactFiles, tui.HumanBytes(result.RemovedArtifactBytes))
if result.Vacuumed {
fmt.Fprintf(a.Out, "Database reclaimed: %s · now %s · free %s\n", tui.HumanBytes(result.DatabaseBytesReclaimed), tui.HumanBytes(result.DatabaseBytesAfter), tui.HumanBytes(result.DatabaseFreeBytesAfter))
}
if result.VacuumError != "" {
fmt.Fprintf(a.Out, "Database reclaim failed: %s\n", result.VacuumError)
}
fmt.Fprintf(a.Out, "Total space reclaimed: %s\n", tui.HumanBytes(result.SpaceReclaimedBytes))
if result.StagingPath != "" {
fmt.Fprintf(a.Out, "Staging cleanup incomplete: %s · %d files · %s remain and are not reclaimed\n", result.StagingPath, result.StagingRemainingFiles, tui.HumanBytes(result.StagingRemainingBytes))
}
return nil
}
// writeRetention renders the shared report body used by both report and apply
// output, so the selection, sizes and reasons are presented identically.
func writeRetention(w interface{ Write([]byte) (int, error) }, report *pipeline.RetentionReport) {
fmt.Fprintf(w, "Retention · %s\n", report.Database)
fmt.Fprintf(w, "Artifacts root: %s\n", report.ArtifactsRoot)
fmt.Fprintf(w, "Policy: older-than %s · keep newest %s\n", retentionAge(report.Policy), retentionKeep(report.Policy))
fmt.Fprintf(w, "Runs: %d total · %d would remove · %d protected · %d retained\n", report.TotalRuns, len(report.WouldRemove), len(report.Protected), report.RetainedRuns)
fmt.Fprintf(w, "Artifacts: %d files · %s\n", report.ArtifactFiles, tui.HumanBytes(report.ArtifactBytes))
fmt.Fprintf(w, "Database: %s · free %s\n", tui.HumanBytes(report.DatabaseBytes), tui.HumanBytes(report.DatabaseFreeBytes))
fmt.Fprintf(w, "Reclaimable: %s\n", tui.HumanBytes(report.ReclaimableBytes))
if len(report.WouldRemove) > 0 {
fmt.Fprintln(w, "\nWould remove:")
for _, run := range report.WouldRemove {
fmt.Fprintf(w, " #%d %s %s %d files %s\n", run.ID, run.Status, run.CreatedAt, run.Artifacts.Files, tui.HumanBytes(run.Artifacts.Bytes))
}
}
if len(report.Protected) > 0 {
fmt.Fprintln(w, "\nProtected:")
for _, run := range report.Protected {
fmt.Fprintf(w, " #%d %s\n", run.ID, run.Reason)
}
}
if report.ArtifactsPartial {
fmt.Fprintln(w, "\nArtifact sizes are partial; some directories could not be fully walked:")
for _, err := range report.ArtifactWalkErrors {
fmt.Fprintf(w, " %s\n", err)
}
}
}
func retentionAge(policy pipeline.RetentionPolicy) string {
if policy.OlderThan <= 0 {
return "unset"
}
return policy.OlderThan.String()
}
func retentionKeep(policy pipeline.RetentionPolicy) string {
if policy.Keep < 0 {
return "unset"
}
return strconv.Itoa(policy.Keep)
}