605 lines
18 KiB
Go
605 lines
18 KiB
Go
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
|
|
failureIndexes := [3]int{-1, -1, -1}
|
|
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 {
|
|
// A retry adds a cause to the same delivery failure. Reports count
|
|
// the failed destination, so the rendered facts stay current.
|
|
if previous := failureIndexes[i]; previous >= 0 {
|
|
failures[previous].Err = errors.Join(failures[previous].Err, err)
|
|
} else {
|
|
failureIndexes[i] = len(failures)
|
|
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)
|
|
}
|