Publish outputs to checked destinations and preserve failure evidence

This commit is contained in:
2026-11-16 03:52:35 +00:00
parent cea7e44232
commit b63c8af467
11 changed files with 656 additions and 336 deletions

View File

@@ -1,6 +1,7 @@
package diagnostics
import (
"context"
"errors"
"fmt"
"io"
@@ -45,80 +46,123 @@ func (f FileFailure) Unwrap() error { return f.Err }
// OutputSession owns checked destinations and per-file publication. Filesystem
// failures remain typed so CLI can present contextual diagnostics.
type OutputSession struct {
transcript string
reports [3]string
enabled bool
replace func(string, []byte) error
temp *os.File
tempPath string
tempDir string
publishPath string
direct bool
stdout io.Writer
transcript string
reports [3]string
reportDestinations [3]string
enabled bool
replace func(context.Context, string, []byte) error
transcriptFile stagedFile
pendingCleanup []*stagedFile
publishPath string
direct bool
stdout io.Writer
}
// SelectOutput checks active destinations before any output resources are opened.
func SelectOutput(selection OutputSelection) (*OutputSession, error) {
session := &OutputSession{enabled: selection.ReportingEnabled, replace: atomicReplace, stdout: selection.Stdout}
active := make([]string, 0, 4)
if selection.TranscriptPath != "" {
session.transcript = selection.TranscriptPath
active = append(active, session.transcript)
session := &OutputSession{enabled: selection.ReportingEnabled, stdout: selection.Stdout}
session.replace = session.replaceReport
type destination struct {
display string
path string
info os.FileInfo
}
check := func(path string) (destination, error) {
resolved, err := canonicalDestination(path)
if err != nil {
return destination{}, err
}
info, err := os.Stat(resolved)
if err != nil && !errors.Is(err, os.ErrNotExist) {
return destination{}, err
}
return destination{display: path, path: resolved, info: info}, nil
}
var resolvedDir string
if session.enabled {
if strings.TrimSpace(selection.ReportDir) == "" {
return nil, fmt.Errorf("report directory is required")
}
info, err := os.Stat(selection.ReportDir)
var err error
resolvedDir, err = filepath.EvalSymlinks(selection.ReportDir)
if err != nil {
return nil, fmt.Errorf("report directory: %w", err)
}
info, err := os.Stat(resolvedDir)
if err != nil {
return nil, fmt.Errorf("report directory: %w", err)
}
if !info.IsDir() {
return nil, fmt.Errorf("report destination is not a directory")
}
session.reports = [3]string{
filepath.Join(selection.ReportDir, ErrorsFile),
filepath.Join(selection.ReportDir, RecoveriesFile),
filepath.Join(selection.ReportDir, MarkdownFile),
}
active = append(active, session.reports[:]...)
}
protected := make([]string, 0, len(selection.ProtectedPaths))
var active []destination
if selection.TranscriptPath != "" {
target, err := check(selection.TranscriptPath)
if err != nil {
return nil, fmt.Errorf("prepare transcript output %q: %w", selection.TranscriptPath, err)
}
if target.info != nil && target.info.IsDir() {
return nil, fmt.Errorf("transcript output %q is a directory", target.display)
}
session.transcript, session.publishPath = target.display, target.path
session.direct = target.info != nil && !target.info.Mode().IsRegular()
active = append(active, target)
}
if session.enabled {
label := selection.ReportDir
if !os.IsPathSeparator(label[len(label)-1]) {
label += string(filepath.Separator)
}
for i, name := range [...]string{ErrorsFile, RecoveriesFile, MarkdownFile} {
target, err := check(filepath.Join(resolvedDir, name))
if err != nil {
return nil, fmt.Errorf("report output %q: %w", label+name, err)
}
target.display = label + name
if target.info != nil && !target.info.Mode().IsRegular() {
return nil, fmt.Errorf("report output %q is not a regular file", target.display)
}
session.reports[i], session.reportDestinations[i] = target.display, target.path
active = append(active, target)
}
}
same := func(a, b destination) bool {
return a.path == b.path || (a.info != nil && b.info != nil && os.SameFile(a.info, b.info))
}
if len(active) == 0 {
return session, nil
}
var protected []destination
for _, path := range selection.ProtectedPaths {
if path != "" {
protected = append(protected, path)
source, err := check(path)
if err != nil {
return nil, fmt.Errorf("protected source %q: %w", path, err)
}
protected = append(protected, source)
}
}
for i, path := range active {
if path != session.transcript {
if info, err := os.Stat(path); err == nil {
if !info.Mode().IsRegular() {
return nil, fmt.Errorf("report output %q is not a regular file", path)
}
} else if !errors.Is(err, os.ErrNotExist) {
return nil, fmt.Errorf("report output %q: %w", path, err)
var input destination
if session.enabled && selection.InputTranscriptPath != "" {
var err error
input, err = check(selection.InputTranscriptPath)
if err != nil {
return nil, fmt.Errorf("transcript input %q: %w", selection.InputTranscriptPath, err)
}
}
for i, target := range active {
for _, source := range protected {
if same(target, source) {
return nil, fmt.Errorf("output destination %q conflicts with input %q", target.display, source.display)
}
}
sources := protected
if path != session.transcript && selection.InputTranscriptPath != "" {
sources = append(append([]string(nil), protected...), selection.InputTranscriptPath)
}
for _, source := range sources {
collision, err := sameDestination(path, source)
if err != nil {
return nil, err
}
if collision {
return nil, fmt.Errorf("output destination %q conflicts with input %q", path, source)
}
if (session.transcript == "" || i > 0) && input.path != "" && same(target, input) {
return nil, fmt.Errorf("output destination %q conflicts with input %q", target.display, input.display)
}
for _, prior := range active[:i] {
collision, err := sameDestination(path, prior)
if err != nil {
return nil, err
}
if collision {
return nil, fmt.Errorf("output destinations %q and %q conflict", path, prior)
if same(target, prior) {
return nil, fmt.Errorf("output destinations %q and %q conflict", target.display, prior.display)
}
}
}
@@ -142,40 +186,17 @@ func (s *OutputSession) Prepare() error {
if s == nil {
return fmt.Errorf("output session is required")
}
if s.transcript == "" || s.temp != nil || s.direct {
if s.transcript == "" || s.transcriptFile.file != nil || s.direct {
return nil
}
info, err := os.Stat(s.transcript)
if err == nil && info.IsDir() {
return fmt.Errorf("transcript output %q is a directory", s.transcript)
}
if err == nil && !info.Mode().IsRegular() {
s.direct = true
return nil
}
if err != nil && !errors.Is(err, os.ErrNotExist) {
return fmt.Errorf("transcript output %q: %w", s.transcript, err)
}
s.publishPath, err = canonicalDestination(s.transcript)
if err != nil {
return err
}
s.tempDir, err = os.MkdirTemp(filepath.Dir(s.publishPath), ".audita-output-*")
if err != nil {
return fmt.Errorf("prepare transcript output %q: %w", s.transcript, err)
}
s.tempPath = filepath.Join(s.tempDir, "payload")
s.temp, err = os.OpenFile(s.tempPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
if err != nil {
_ = s.Close()
return fmt.Errorf("prepare transcript output %q: %w", s.transcript, err)
}
if info != nil {
if err := s.temp.Chmod(info.Mode().Perm()); err != nil {
_ = s.Close()
return err
if s.transcriptFile.dir != "" {
if err := s.Close(); err != nil {
return fmt.Errorf("clean unpublished transcript output %q: %w", s.transcript, err)
}
}
if err := s.transcriptFile.prepare(s.publishPath); err != nil {
return fmt.Errorf("prepare transcript output %q: %w", s.transcript, errors.Join(err, s.Close()))
}
return nil
}
@@ -184,23 +205,20 @@ func (s *OutputSession) Close() error {
if s == nil {
return nil
}
return errors.Join(s.transcriptFile.close(), s.cleanupReports())
}
func (s *OutputSession) cleanupReports() error {
var errs []error
if s.temp != nil {
errs = append(errs, s.temp.Close())
s.temp = nil
}
if s.tempPath != "" {
if err := os.Remove(s.tempPath); err != nil && !errors.Is(err, os.ErrNotExist) {
errs = append(errs, err)
remaining := s.pendingCleanup[:0]
for _, file := range s.pendingCleanup {
errs = append(errs, file.close())
if file.dir != "" {
remaining = append(remaining, file)
}
s.tempPath = ""
}
if s.tempDir != "" {
if err := os.Remove(s.tempDir); err != nil && !errors.Is(err, os.ErrNotExist) {
errs = append(errs, err)
}
s.tempDir = ""
}
clear(s.pendingCleanup[len(remaining):])
s.pendingCleanup = remaining
return errors.Join(errs...)
}
@@ -218,39 +236,20 @@ func (s *OutputSession) TranscriptPath() string {
return s.transcript
}
// Initialize publishes each initial report and attempts failed-status reports if any fail.
func (s *OutputSession) Initialize(initial ReportBundle, failed func([]FileFailure) ReportBundle) error {
// ReportRenderer receives the processing cause and known delivery failures.
type ReportRenderer func(error, []FileFailure) (ReportBundle, error)
// Initialize publishes reports before model work can start.
func (s *OutputSession) Initialize(ctx context.Context, initial ReportBundle, render ReportRenderer) error {
if s == nil || !s.enabled {
return nil
}
var failures []FileFailure
for i, payload := range bundleParts(initial) {
if err := s.replace(s.reports[i], payload); err != nil {
failures = append(failures, FileFailure{Path: s.reports[i], Kind: "report initialization", Err: err})
}
}
if len(failures) == 0 {
return nil
}
if err := s.Close(); err != nil {
failures = append(failures, FileFailure{Path: s.transcript, Kind: "output cleanup", Err: err})
}
if failed != nil {
for i, payload := range bundleParts(failed(failures)) {
if err := s.replace(s.reports[i], payload); err != nil {
failures = append(failures, FileFailure{Path: s.reports[i], Kind: "failed report initialization", Err: err})
}
}
}
errs := make([]error, 0, len(failures))
for _, failure := range failures {
errs = append(errs, failure)
}
return errors.Join(errs...)
failures := s.publishReports(ctx, initial, nil, nil, "report initialization", render)
return includeCancellation(ctx, joinOutputFailures(nil, failures))
}
// PrepareDebug creates optional initial diagnostics and returns any nonfatal problems.
func (s *OutputSession) PrepareDebug(workDir, runID string, metadata InvocationMetadata, effective []byte) (*RunDirectory, []error) {
func PrepareDebug(workDir, runID string, metadata InvocationMetadata, effective []byte) (*RunDirectory, []error) {
run, err := NewRunDirectory(workDir, runID)
if err != nil {
return nil, []error{err}
@@ -267,180 +266,307 @@ func (s *OutputSession) PrepareDebug(workDir, runID string, metadata InvocationM
return run, problems
}
// Finalize publishes the transcript first, then errors, recoveries, and Markdown.
// An empty transcript payload means processing failed and no transcript is written.
// Every enabled report is attempted even after an earlier write failure.
func (s *OutputSession) Finalize(transcript []byte, reports ReportBundle, failed func([]FileFailure) ReportBundle) []FileFailure {
// Finish publishes a completed transcript before rendering final reports.
func (s *OutputSession) Finish(ctx context.Context, primary error, transcript []byte, render ReportRenderer) error {
return includeCancellation(ctx, joinOutputFailures(primary, s.finalize(ctx, primary, transcript, render)))
}
func (s *OutputSession) finalize(ctx context.Context, primary error, transcript []byte, render ReportRenderer) []FileFailure {
if s == nil {
return []FileFailure{{Kind: "output finalization", Err: fmt.Errorf("output session is required")}}
}
failures := make([]FileFailure, 0)
if transcript != nil {
if err := s.writeTranscript(transcript); err != nil {
var failures []FileFailure
if primary == nil && ctx.Err() == nil && transcript != nil {
if err := s.writeTranscript(ctx, transcript); err != nil {
failures = append(failures, FileFailure{Path: s.transcript, Kind: "transcript write", Err: err})
}
}
if err := s.Close(); err != nil {
failures = append(failures, FileFailure{Path: s.transcript, Kind: "output cleanup", Err: err})
}
if s.enabled {
for i, payload := range bundleParts(reports) {
if err := s.replace(s.reports[i], payload); err != nil {
failures = append(failures, FileFailure{Path: s.reports[i], Kind: "report write", Err: err})
if !s.enabled || render == nil {
return failures
}
primary = includeCancellation(ctx, primary)
if primary != nil || len(failures) != 0 {
return s.publishReports(ctx, ReportBundle{}, primary, failures, "report write", render)
}
reports, err := render(nil, nil)
if err != nil {
failures = append(failures, FileFailure{Kind: "report rendering", Err: err})
}
return s.publishReports(ctx, reports, primary, failures, "report write", render)
}
func (s *OutputSession) publishReports(ctx context.Context, reports ReportBundle, primary error, failures []FileFailure, action string, render ReportRenderer) (result []FileFailure) {
defer func() {
if err := s.cleanupReports(); err != nil {
result = append(result, FileFailure{Kind: "output cleanup", Err: err})
}
}()
primary = includeCancellation(ctx, primary)
failed := false
var failedWritten [3]bool
write := func(i int, payload []byte) {
writeCtx := ctx
kind := action
if failed {
writeCtx = context.WithoutCancel(ctx)
kind = "failed " + action
}
if err := s.replace(writeCtx, s.reportDestinations[i], payload); err != nil {
failures = append(failures, FileFailure{Path: s.reports[i], Kind: kind, Err: err})
} else if failed {
failedWritten[i] = true
}
}
renderFailed := func() bool {
if action == "report initialization" {
if err := s.Close(); err != nil {
failures = append(failures, FileFailure{Path: s.transcript, Kind: "output cleanup", Err: err})
}
}
if len(failures) > 0 && failed != nil {
for i, payload := range bundleParts(failed(failures)) {
if err := s.replace(s.reports[i], payload); err != nil {
failures = append(failures, FileFailure{Path: s.reports[i], Kind: "failed report write", Err: err})
}
if render == nil {
return false
}
var err error
reports, err = render(includeCancellation(ctx, primary), failures)
if err != nil {
failures = append(failures, FileFailure{Kind: "failed report rendering", Err: err})
return false
}
failed = true
return true
}
knownFailure := primary != nil || len(failures) != 0
if knownFailure && !renderFailed() {
return failures
}
for i := range s.reports {
if !failed && (len(failures) != 0 || ctx.Err() != nil) && !renderFailed() {
return failures
}
write(i, bundleParts(reports)[i])
}
if !knownFailure && (failed || len(failures) != 0 || ctx.Err() != nil) {
if !failed && !renderFailed() {
return failures
}
for i, payload := range bundleParts(reports) {
if !failedWritten[i] {
write(i, payload)
}
}
}
return failures
}
// Stream destinations are opened only when delivering the transcript.
// Finish retains an earlier processing error while reporting delivery failures.
func (s *OutputSession) Finish(primary error, transcript []byte, reports ReportBundle, failed func([]FileFailure) ReportBundle) error {
if primary != nil {
transcript = nil
}
failures := s.Finalize(transcript, reports, failed)
errs := make([]error, 0, len(failures)+1)
errs = append(errs, primary)
func joinOutputFailures(primary error, failures []FileFailure) error {
errs := []error{primary}
for _, failure := range failures {
errs = append(errs, failure)
}
return errors.Join(errs...)
}
func (s *OutputSession) writeTranscript(payload []byte) error {
func includeCancellation(ctx context.Context, err error) error {
if canceled := ctx.Err(); canceled != nil && !errors.Is(err, canceled) {
return errors.Join(err, canceled)
}
return err
}
func (s *OutputSession) writeTranscript(ctx context.Context, payload []byte) error {
if err := ctx.Err(); err != nil {
return err
}
if s.transcript == "" {
if s.stdout == nil {
return fmt.Errorf("transcript stdout writer is required")
}
n, err := s.stdout.Write(payload)
if err == nil && n != len(payload) {
return io.ErrShortWrite
err = io.ErrShortWrite
}
return err
return includeCancellation(ctx, err)
}
if s.direct {
info, err := os.Stat(s.transcript)
info, err := os.Stat(s.publishPath)
if err != nil {
return err
}
if info.IsDir() || info.Mode().IsRegular() {
return fmt.Errorf("transcript output is no longer a stream destination")
}
file, err := os.OpenFile(s.transcript, os.O_WRONLY, 0)
if err := ctx.Err(); err != nil {
return err
}
file, err := os.OpenFile(s.publishPath, os.O_WRONLY, 0)
if err != nil {
return err
}
if err := ctx.Err(); err != nil {
return errors.Join(err, file.Close())
}
n, writeErr := file.Write(payload)
if writeErr == nil && n != len(payload) {
writeErr = io.ErrShortWrite
}
return errors.Join(writeErr, file.Close())
return includeCancellation(ctx, errors.Join(writeErr, file.Close()))
}
if s.temp == nil {
return fmt.Errorf("transcript output is not prepared")
}
n, writeErr := s.temp.Write(payload)
if writeErr == nil && n != len(payload) {
writeErr = io.ErrShortWrite
}
closeErr := s.temp.Close()
s.temp = nil
if err := errors.Join(writeErr, closeErr); err != nil {
return err
}
info, err := os.Stat(s.publishPath)
if err == nil && !info.Mode().IsRegular() {
return fmt.Errorf("transcript output changed type after preparation")
}
if err != nil && !errors.Is(err, os.ErrNotExist) {
return err
}
if err := os.Rename(s.tempPath, s.publishPath); err != nil {
return err
}
s.tempPath = ""
return nil
return s.transcriptFile.publish(ctx, s.publishPath, payload)
}
func bundleParts(bundle ReportBundle) [3][]byte {
return [3][]byte{bundle.Errors, bundle.Recoveries, bundle.Markdown}
}
func sameDestination(a, b string) (bool, error) {
ca, err := canonicalDestination(a)
if err != nil {
return false, err
}
cb, err := canonicalDestination(b)
if err != nil {
return false, err
}
if ca == cb {
return true, nil
}
ai, ae := os.Stat(a)
bi, be := os.Stat(b)
return ae == nil && be == nil && os.SameFile(ai, bi), nil
}
// Resolve the supplied path before making it absolute so a symlink followed by
// ".." uses the symlink target's parent. A missing leaf uses its resolved parent.
func canonicalDestination(path string) (string, error) {
abs, err := filepath.Abs(path)
resolved, err := filepath.EvalSymlinks(path)
if err == nil {
return filepath.Abs(resolved)
}
if !errors.Is(err, os.ErrNotExist) {
return "", err
}
parent, leaf := filepath.Split(path)
if leaf == "" {
return "", err
}
if parent == "" {
parent = "."
}
resolved, err = filepath.EvalSymlinks(parent)
if err != nil {
return "", err
}
abs = filepath.Clean(abs)
if resolved, err := filepath.EvalSymlinks(abs); err == nil {
return resolved, nil
resolved, err = filepath.Abs(resolved)
if err != nil {
return "", err
}
parent, err := filepath.EvalSymlinks(filepath.Dir(abs))
candidate := filepath.Join(resolved, leaf)
// A stream such as a descriptor alias can have a kernel-resolved referent
// without a regular filesystem path to that referent.
if info, statErr := os.Stat(candidate); statErr == nil && !info.IsDir() && !info.Mode().IsRegular() {
return candidate, nil
}
link, err := os.Readlink(candidate)
if err == nil {
return filepath.Join(parent, filepath.Base(abs)), nil
if !filepath.IsAbs(link) {
link = resolved + string(filepath.Separator) + link
}
return canonicalDestination(link)
}
return abs, nil
return candidate, nil
}
func atomicReplace(path string, payload []byte) error {
publishPath, err := canonicalDestination(path)
if err != nil {
return err
}
// A private temporary directory lets ordinary file creation apply the umask
// without reading or changing process-global state. Rename stays on the same
// filesystem, and the incomplete payload is not accessible through the parent.
dir, err := os.MkdirTemp(filepath.Dir(publishPath), ".audita-write-*")
if err != nil {
return err
}
defer os.Remove(dir)
name := filepath.Join(dir, "payload")
temp, err := os.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
if err != nil {
return err
}
defer os.Remove(name)
if info, err := os.Stat(publishPath); err == nil {
if err := temp.Chmod(info.Mode().Perm()); err != nil {
_ = temp.Close()
return err
}
} else if !errors.Is(err, os.ErrNotExist) {
_ = temp.Close()
return err
}
if _, err := temp.Write(payload); err != nil {
_ = temp.Close()
return err
}
if err := temp.Close(); err != nil {
return err
}
return os.Rename(name, publishPath)
// stagedFile is a regular file staged beside its checked destination.
type stagedFile struct {
file *os.File
path string
dir string
}
func (f *stagedFile) prepare(target string) error {
info, err := regularFileInfo(target)
if err != nil {
return err
}
// The private directory keeps the incomplete payload inaccessible while
// allowing ordinary creation to apply the umask without changing it.
f.dir, err = os.MkdirTemp(filepath.Dir(target), ".audita-output-*")
if err != nil {
return err
}
f.path = filepath.Join(f.dir, "payload")
f.file, err = os.OpenFile(f.path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
if err != nil {
return err
}
if info != nil {
return f.file.Chmod(info.Mode().Perm())
}
return nil
}
func (f *stagedFile) publish(ctx context.Context, target string, payload []byte) error {
if err := ctx.Err(); err != nil {
return err
}
if f.file == nil {
return fmt.Errorf("output is not prepared")
}
n, writeErr := f.file.Write(payload)
if writeErr == nil && n != len(payload) {
writeErr = io.ErrShortWrite
}
closeErr := f.file.Close()
f.file = nil
if err := errors.Join(writeErr, closeErr); err != nil {
return err
}
if _, err := regularFileInfo(target); err != nil {
return err
}
if err := ctx.Err(); err != nil {
return err
}
if err := os.Rename(f.path, target); err != nil {
return err
}
f.path = ""
return nil
}
func regularFileInfo(path string) (os.FileInfo, error) {
info, err := os.Lstat(path)
if errors.Is(err, os.ErrNotExist) {
return nil, nil
}
if err != nil {
return nil, err
}
if !info.Mode().IsRegular() {
return nil, fmt.Errorf("output changed type after selection")
}
return info, nil
}
func (f *stagedFile) close() error {
var failures []error
if f.file != nil {
failures = append(failures, f.file.Close())
f.file = nil
}
if f.path != "" {
if err := os.Remove(f.path); err != nil && !errors.Is(err, os.ErrNotExist) {
return errors.Join(append(failures, err)...)
}
f.path = ""
}
if f.dir != "" {
if err := os.Remove(f.dir); err != nil && !errors.Is(err, os.ErrNotExist) {
return errors.Join(append(failures, err)...)
}
f.dir = ""
}
return errors.Join(failures...)
}
func (s *OutputSession) replaceReport(ctx context.Context, target string, payload []byte) error {
if err := ctx.Err(); err != nil {
return err
}
file := new(stagedFile)
err := file.prepare(target)
if err == nil {
err = file.publish(ctx, target, payload)
}
cleanup := file.close()
if file.dir != "" {
s.pendingCleanup = append(s.pendingCleanup, file)
}
return errors.Join(err, cleanup)
}