// Package debug records explicitly requested application evidence. package debug import ( "errors" "fmt" "sync" "time" "gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle" "gitea.maximumdirect.net/eric/notarius/internal/core/fileio" ) // Recorder writes evidence incrementally. It retains only lifecycle information // and the first recording error, not the pipeline's content. type Recorder struct { bundle *debugbundle.Bundle mu sync.Mutex recordingErr error finalized bool finalErr error } func Start(parent, runID string, startedAt time.Time) (*Recorder, error) { bundle, err := debugbundle.Allocate(parent, runID, startedAt) if bundle == nil { return nil, err } recorder := &Recorder{bundle: bundle} if err != nil { recorder.RecordError(err) return recorder, err } if err := recorder.WriteJSON("run.json", struct { RunID string `json:"run_id"` StartedAt time.Time `json:"started_at"` }{runID, startedAt}); err != nil { return recorder, err } if err := recorder.WriteBytes("overview.txt", []byte(fmt.Sprintf("Run: %s\nStarted: %s\nCapture: %s\nStatus: running\n", runID, startedAt.Format(time.RFC3339Nano), recorder.Path()))); err != nil { return recorder, err } return recorder, nil } func (r *Recorder) Enabled() bool { return r != nil && r.bundle != nil } func (r *Recorder) Path() string { if r == nil { return "" } return r.bundle.Path() } // RecordError retains callback failures for a boundary that can return errors. func (r *Recorder) RecordError(err error) { if !r.Enabled() || err == nil { return } r.mu.Lock() defer r.mu.Unlock() r.remember(err) } func (r *Recorder) remember(err error) { if r.recordingErr == nil { r.recordingErr = err } } func (r *Recorder) Err() error { if !r.Enabled() { return nil } r.mu.Lock() defer r.mu.Unlock() return r.recordingErr } func (r *Recorder) WriteJSON(name string, payload any) error { if !r.Enabled() { return nil } r.mu.Lock() defer r.mu.Unlock() if r.finalized { return fmt.Errorf("debug capture %q is finalized", r.Path()) } if err := fileio.WriteJSON(r.Path(), name, payload, 0o700, 0o600); err != nil { r.remember(fmt.Errorf("record debug %q in %q: %w", name, r.Path(), err)) } return r.recordingErr } func (r *Recorder) WriteBytes(name string, content []byte) error { if !r.Enabled() { return nil } r.mu.Lock() defer r.mu.Unlock() if r.finalized { return fmt.Errorf("debug capture %q is finalized", r.Path()) } if err := fileio.WriteBytes(r.Path(), name, content, 0o700, 0o600); err != nil { r.remember(fmt.Errorf("record debug %q in %q: %w", name, r.Path(), err)) } return r.recordingErr } // Finalize writes one terminal outcome, retaining a primary operation failure // before additional capture failures. Repeated calls neither write nor retarget // latest. An additional primary error is preserved alongside the original // finalization result, including when presentation fails after capture finishes. func (r *Recorder) Finalize(outcome any, primaryErr error) error { if !r.Enabled() { return primaryErr } r.mu.Lock() defer r.mu.Unlock() if r.finalized { if primaryErr == nil { return r.finalErr } if errors.Is(primaryErr, r.finalErr) { return primaryErr } return errors.Join(primaryErr, r.finalErr) } r.finalized = true completedAt := time.Now().UTC() terminal := struct { CompletedAt time.Time `json:"completed_at"` Outcome any `json:"outcome,omitempty"` Error string `json:"error,omitempty"` CaptureError string `json:"capture_error,omitempty"` }{CompletedAt: completedAt, Outcome: outcome} if primaryErr != nil { terminal.Error = primaryErr.Error() } if r.recordingErr != nil { terminal.CaptureError = r.recordingErr.Error() } outcomeErr := fileio.WriteJSON(r.Path(), "outcome.json", terminal, 0o700, 0o600) if outcomeErr != nil { outcomeErr = fmt.Errorf("finalize debug outcome in %q: %w", r.Path(), outcomeErr) } status := "completed" if primaryErr != nil || r.recordingErr != nil || outcomeErr != nil { status = "failed" } overview := fmt.Sprintf("Run: %s\nStarted: %s\nCompleted: %s\nCapture: %s\nStatus: %s\n", r.bundle.RunID(), r.bundle.CreatedAt().Format(time.RFC3339Nano), completedAt.Format(time.RFC3339Nano), r.Path(), status) if primaryErr != nil { overview += "Error: " + primaryErr.Error() + "\n" } if r.recordingErr != nil { overview += "Capture error: " + r.recordingErr.Error() + "\n" } if outcomeErr != nil { overview += "Capture error: " + outcomeErr.Error() + "\n" } overviewErr := fileio.WriteBytes(r.Path(), "overview.txt", []byte(overview), 0o700, 0o600) if overviewErr != nil { overviewErr = fmt.Errorf("finalize debug overview in %q: %w", r.Path(), overviewErr) } captureErr := r.recordingErr if primaryErr != nil && errors.Is(primaryErr, captureErr) { captureErr = nil } r.finalErr = errors.Join(primaryErr, captureErr, outcomeErr, overviewErr) return r.finalErr }