package diagnostics import ( "context" "errors" "fmt" "io" "os" "path/filepath" "strings" ) const ( ErrorsFile = "errors.yml" RecoveriesFile = "recoveries.yml" MarkdownFile = "report.md" ) // OutputSelection contains only active destinations. ProtectedPaths are inputs // and loaded configuration/profile sources that must never be overwritten. // InputTranscriptPath may be replaced by final transcript publication, but not reports. type OutputSelection struct { InputTranscriptPath string TranscriptPath string ReportDir string ReportingEnabled bool ProtectedPaths []string Stdout io.Writer } type ReportBundle struct { Errors []byte Recoveries []byte Markdown []byte } type OutputPhase string const ( OutputInitialization OutputPhase = "initialization" OutputTranscriptWrite OutputPhase = "transcript_write" OutputReportWrite OutputPhase = "report_write" OutputCleanup OutputPhase = "output_cleanup" ) type FileFailure struct { Phase OutputPhase Path string Kind string Err error } func (f FileFailure) Error() string { return fmt.Sprintf("%s %q: %v", f.Kind, f.Path, f.Err) } 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 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, 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") } 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") } } 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 != "" { source, err := check(path) if err != nil { return nil, fmt.Errorf("protected source %q: %w", path, err) } protected = append(protected, source) } } 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) } } 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] { if same(target, prior) { return nil, fmt.Errorf("output destinations %q and %q conflict", target.display, prior.display) } } } return session, nil } // PrepareOutput validates destinations and acquires the transcript resource. func PrepareOutput(selection OutputSelection) (*OutputSession, error) { session, err := SelectOutput(selection) if err != nil { return nil, err } if err := session.Prepare(); err != nil { return nil, err } return session, nil } // Prepare opens a sibling temporary file for regular transcript output. func (s *OutputSession) Prepare() error { if s == nil { return fmt.Errorf("output session is required") } if s.transcript == "" || s.transcriptFile.file != nil || s.direct { return nil } 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 } // Close releases unpublished output resources; caller-owned streams remain open. 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 remaining := s.pendingCleanup[:0] for _, file := range s.pendingCleanup { errs = append(errs, file.close()) if file.dir != "" { remaining = append(remaining, file) } } clear(s.pendingCleanup[len(remaining):]) s.pendingCleanup = remaining return errors.Join(errs...) } func (s *OutputSession) ReportPaths() []string { if s == nil || !s.enabled { return nil } return []string{s.reports[0], s.reports[1], s.reports[2]} } func (s *OutputSession) TranscriptPath() string { if s == nil { return "" } return s.transcript } // 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 } 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 PrepareDebug(workDir, runID string, metadata InvocationMetadata, effective []byte) (*RunDirectory, []error) { run, err := NewRunDirectory(workDir, runID) if err != nil { return nil, []error{err} } var problems []error if err := run.WriteInvocationMetadata(metadata); err != nil { problems = append(problems, err) } if effective != nil { if err := run.WriteEffectiveConfig(effective); err != nil { problems = append(problems, err) } } return run, problems } // 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{{Phase: OutputCleanup, Kind: "output finalization", Err: fmt.Errorf("output session is required")}} } 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, Phase: OutputTranscriptWrite, Kind: "transcript write", Err: err}) } } if err := s.Close(); err != nil { failures = append(failures, FileFailure{Path: s.transcript, Phase: OutputCleanup, Kind: "output cleanup", 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{Phase: OutputReportWrite, 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{Phase: OutputCleanup, Kind: "output cleanup", Err: err}) } }() phase := OutputReportWrite if action == "report initialization" { phase = OutputInitialization } type reportState struct { failed, canceled bool failureCount int } observed := func() reportState { canceled := ctx.Err() != nil return reportState{primary != nil || canceled || len(failures) > 0, canceled, len(failures)} } var rendered reportState var written [3]reportState var attemptedFailed [3]bool refresh := func() bool { state := observed() if state == rendered { return true } if phase == OutputInitialization && !rendered.failed { if err := s.Close(); err != nil { failures = append(failures, FileFailure{Path: s.transcript, Phase: OutputCleanup, Kind: "output cleanup", Err: err}) } state = observed() } if render == nil { return false } var err error reports, err = render(includeCancellation(ctx, primary), failures) if err != nil { failures = append(failures, FileFailure{Phase: phase, Kind: "failed report rendering", Err: err}) return false } rendered = state return true } write := func(i int) { writeCtx, kind := ctx, action if rendered.failed { writeCtx, kind = context.WithoutCancel(ctx), "failed "+action attemptedFailed[i] = true } if err := s.replace(writeCtx, s.reportDestinations[i], bundleParts(reports)[i]); err != nil { failures = append(failures, FileFailure{Path: s.reports[i], Phase: phase, Kind: kind, Err: err}) } else { written[i] = rendered } } for i := range s.reports { if !refresh() { return failures } write(i) } // Refresh stale publications once and give any report that failed before // the switch to failed status an attempt with the failed bundle. for i := range s.reports { state := observed() if !state.failed || written[i] == state || (attemptedFailed[i] && !written[i].failed) { continue } if !refresh() { return failures } write(i) } return failures } func joinOutputFailures(primary error, failures []FileFailure) error { errs := []error{primary} for _, failure := range failures { errs = append(errs, failure) } return errors.Join(errs...) } 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) { err = io.ErrShortWrite } return includeCancellation(ctx, err) } if s.direct { 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") } 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 includeCancellation(ctx, errors.Join(writeErr, file.Close())) } return s.transcriptFile.publish(ctx, s.publishPath, payload) } func bundleParts(bundle ReportBundle) [3][]byte { return [3][]byte{bundle.Errors, bundle.Recoveries, bundle.Markdown} } // 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) { 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 } resolved, err = filepath.Abs(resolved) if err != nil { return "", err } 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 { if !filepath.IsAbs(link) { link = resolved + string(filepath.Separator) + link } return canonicalDestination(link) } return candidate, nil } // 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) }