Record debug evidence in one run-scoped capture session
This commit is contained in:
@@ -1389,6 +1389,31 @@ counting, and evidence source order/window behavior.
|
||||
|
||||
## Stage 30: Build The Debug Recorder And Session Lifecycle
|
||||
|
||||
**Status:** Complete. Replaced summary/trace allocation and separate terminal
|
||||
writers with one run-scoped recorder for incremental JSON/text evidence and one
|
||||
terminal outcome. Allocation creates the absolute run directory and atomically
|
||||
updates a relative latest link at start; completion never retargets it. Failed
|
||||
starts retain an available directory rather than deleting captured data.
|
||||
The recorder is concurrency-safe, retains callback errors for boundary checks,
|
||||
preserves primary causes alongside capture failures, and finalizes once without
|
||||
rewriting evidence on repeated calls. Finalization failures are errors, including
|
||||
after artifact publication; a later presentation failure remains reportable.
|
||||
Added reusable native debug/debug-dir input binding and selection, preserving
|
||||
quiet/debug ordering, explicit false/empty values, configured/default roots,
|
||||
invocation-relative overrides, and nonempty overrides over empty configuration.
|
||||
Disabled capture performs no allocation or latest update. Removed the legacy
|
||||
summary/terminal factories and routed run-path allocation/finalization through
|
||||
the new lifecycle before engine/preflight and before successful presentation.
|
||||
Real-filesystem lifecycle/concurrency/failure tests, isolated real-CommandKit
|
||||
flag/selection tests, focused pipeline tests, selected vet/race checks, production
|
||||
debug/bundle/pipeline/config builds, and git diff checks pass. Full CLI/pipeline
|
||||
package checks remain blocked at setup by unmigrated imports of the removed
|
||||
reporting package and old ConfigKit's YAML plugin/limit dependency; their results
|
||||
are not claimed passing. Full native evidence/observation wiring remains Stage 31,
|
||||
native run-handler composition remains Stage 33, and final publication/report
|
||||
outcome integration remains Stage 34. Remaining obsolete fixtures are Stage 35
|
||||
cleanup, not a reason to restore the old writers.
|
||||
|
||||
**Goal:** requested capture has one simple recorder and explicit failure semantics.
|
||||
|
||||
**Inspect/change:** `internal/core/debugbundle`, `internal/framework/debug`,
|
||||
|
||||
@@ -18,7 +18,6 @@ import (
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/buildinfo"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/config"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/fileio"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/artifactcache"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
|
||||
@@ -31,18 +30,16 @@ import (
|
||||
)
|
||||
|
||||
type Options struct {
|
||||
LLMClient promptkit.LLMClient
|
||||
LLMRuntime promptkit.RuntimeConfig
|
||||
Catalog pipeline.ModuleCatalog
|
||||
Registries pipeline.Registries
|
||||
LLMClientFactory LLMClientFactory
|
||||
RunIDGenerator RunIDGenerator
|
||||
LookupEnv func(string) (string, bool)
|
||||
Now func() time.Time
|
||||
UserCacheDir func() (string, error)
|
||||
DebugRecorderFactory func(string) (pipeline.DebugRecorder, error)
|
||||
DebugTerminalFactory func(*debugbundle.SummaryWriter) DebugTerminalWriter
|
||||
promptKitAssets *frameworkllm.AssetRegistry
|
||||
LLMClient promptkit.LLMClient
|
||||
LLMRuntime promptkit.RuntimeConfig
|
||||
Catalog pipeline.ModuleCatalog
|
||||
Registries pipeline.Registries
|
||||
LLMClientFactory LLMClientFactory
|
||||
RunIDGenerator RunIDGenerator
|
||||
LookupEnv func(string) (string, bool)
|
||||
Now func() time.Time
|
||||
UserCacheDir func() (string, error)
|
||||
promptKitAssets *frameworkllm.AssetRegistry
|
||||
}
|
||||
|
||||
type LLMRuntimeOverrides struct {
|
||||
@@ -83,12 +80,6 @@ func normalizeOptions(opts Options) (Options, error) {
|
||||
if opts.UserCacheDir == nil {
|
||||
opts.UserCacheDir = os.UserCacheDir
|
||||
}
|
||||
if opts.DebugRecorderFactory == nil {
|
||||
opts.DebugRecorderFactory = frameworkdebug.NewFilesystemRecorder
|
||||
}
|
||||
if opts.DebugTerminalFactory == nil {
|
||||
opts.DebugTerminalFactory = func(writer *debugbundle.SummaryWriter) DebugTerminalWriter { return writer }
|
||||
}
|
||||
if isEmptyCatalog(opts.Catalog) && isEmptyRegistries(opts.Registries) {
|
||||
components, err := newProductionComponents()
|
||||
if err != nil {
|
||||
@@ -158,18 +149,10 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i
|
||||
fmt.Fprintln(stderr, "notarius: run requires --input")
|
||||
return 2
|
||||
}
|
||||
if strings.TrimSpace(*debugDir) != "" && !*debug {
|
||||
fmt.Fprintln(stderr, "notarius: --debug-dir requires --debug")
|
||||
return 2
|
||||
}
|
||||
if strings.TrimSpace(*outputDir) == "" && flagWasProvided(args, "--output-dir") {
|
||||
fmt.Fprintln(stderr, "notarius: --output-dir must not be empty")
|
||||
return 2
|
||||
}
|
||||
if strings.TrimSpace(*debugDir) == "" && flagWasProvided(args, "--debug-dir") {
|
||||
fmt.Fprintln(stderr, "notarius: --debug-dir must not be empty")
|
||||
return 2
|
||||
}
|
||||
if requestedSessionID.set && strings.TrimSpace(requestedSessionID.value) == "" {
|
||||
fmt.Fprintln(stderr, "notarius: --session-id must not be empty")
|
||||
return 2
|
||||
@@ -210,7 +193,7 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i
|
||||
return 2
|
||||
}
|
||||
|
||||
loaded, loadedConfigPath, err := loadConfigKit(*configPath, *configOverlay, runConfigurationOverrides(*outputDir, *debugDir), opts)
|
||||
loaded, loadedConfigPath, err := loadConfigKit(*configPath, *configOverlay, runConfigurationOverrides(*outputDir), opts)
|
||||
if err != nil {
|
||||
writeConfigLoadError(stderr, err)
|
||||
return 1
|
||||
@@ -231,52 +214,48 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i
|
||||
return 1
|
||||
}
|
||||
runOutputDir := filepath.Join(cfg.Output.Directory, runID)
|
||||
commandState := newPipelineCommandState(runID, pipelineID, runOutputDir)
|
||||
var summary *debugbundle.SummaryWriter
|
||||
var terminalWriter DebugTerminalWriter
|
||||
debugPath := ""
|
||||
debugRecorder := pipeline.NoopDebugRecorder()
|
||||
if *debug {
|
||||
bundle, err := debugbundle.Allocate(cfg.Debug.Directory, runID, startedAt)
|
||||
if err != nil {
|
||||
fmt.Fprintf(stderr, "notarius: %v\n", err)
|
||||
return 1
|
||||
}
|
||||
debugPath, summary = bundle.Path(), bundle.Summary()
|
||||
commandState.setDebugPath(debugPath)
|
||||
terminalWriter = opts.DebugTerminalFactory(summary)
|
||||
if terminalWriter == nil {
|
||||
terminalWriter = summary
|
||||
}
|
||||
debugRecorder, err = opts.DebugRecorderFactory(bundle.TraceRoot())
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("create debug recorder: %w", err))
|
||||
}
|
||||
debugRecorder = pipeline.SynchronizedDebugRecorder(debugRecorder)
|
||||
|
||||
var capture *frameworkdebug.Recorder
|
||||
var output pipeline.RunOutput
|
||||
published := false
|
||||
captureOutcome := func() any {
|
||||
return map[string]any{"pipeline": pipelineID, "output_directory": runOutputDir, "artifact_count": output.ArtifactCount(), "fallback_count": output.FallbackCount, "published": published}
|
||||
}
|
||||
invocation := debugbundle.Invocation{
|
||||
Operation: "run",
|
||||
PipelineID: pipelineID,
|
||||
InputPath: strings.TrimSpace(*inputPath),
|
||||
ConfigPath: loadedConfigPath,
|
||||
ConfigSource: configSource(*configPath),
|
||||
ConfigOverlay: effectiveConfigOverlay(*configOverlay),
|
||||
OnlyLanes: append([]string(nil), only...),
|
||||
ReasoningEffortOverride: runtimeOverrides.ReasoningEffort,
|
||||
RunID: runID,
|
||||
StartedAt: startedAt,
|
||||
fail := func(primary error, extra ...error) int {
|
||||
cause := errors.Join(append([]error{primary}, extra...)...)
|
||||
cause = capture.Finalize(captureOutcome(), cause)
|
||||
fmt.Fprintf(stderr, "notarius: %v\n", cause)
|
||||
if published {
|
||||
fmt.Fprintf(stderr, "notarius: artifacts=%s\n", runOutputDir)
|
||||
}
|
||||
if capture.Path() != "" {
|
||||
fmt.Fprintf(stderr, "notarius: debug=%s\n", capture.Path())
|
||||
}
|
||||
return 1
|
||||
}
|
||||
if err := writeSummary(summary, func() error { return summary.WriteInvocation(invocation) }); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug invocation metadata: %w", err))
|
||||
capture, err = startRunDebug(runDebugInput{
|
||||
Enabled: commandkit.Supplied[bool]{Value: *debug, Set: flagWasProvided(args, "--debug")},
|
||||
Directory: commandkit.Supplied[string]{Value: *debugDir, Set: flagWasProvided(args, "--debug-dir")},
|
||||
}, cfg.Debug.Directory, runID, startedAt)
|
||||
if err != nil {
|
||||
return fail(err)
|
||||
}
|
||||
debugPath := capture.Path()
|
||||
var debugRecorder pipeline.DebugRecorder = pipeline.NoopDebugRecorder()
|
||||
if capture.Enabled() {
|
||||
debugRecorder = capture
|
||||
}
|
||||
if err := capture.WriteJSON("context.json", map[string]any{"pipeline": pipelineID, "input_path": *inputPath, "config_path": loadedConfigPath, "run_id": runID, "started_at": startedAt}); err != nil {
|
||||
return fail(err)
|
||||
}
|
||||
|
||||
catalog, err := effectiveCatalog(opts)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
referenceOverrides, referenceUnbinds, err := resolveCLIReferenceRequests(cfg, pipelineID, only, catalog, referenceRequests, referenceUnbindRequests)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
effective, err := cfg.Resolve(config.ResolveInput{
|
||||
PipelineID: pipelineID,
|
||||
@@ -287,43 +266,28 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i
|
||||
ReferenceUnbinds: referenceUnbinds,
|
||||
})
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
profileIDs := effectiveLLMProfileIDs(effective.ResolvedPipeline)
|
||||
if err := validateExplicitPromptKitProfiles(context.Background(), effective.Config, profileIDs, opts.promptKitAssets); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
workingDir, err := os.Getwd()
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("resolve working directory: %w", err))
|
||||
return fail(fmt.Errorf("resolve working directory: %w", err))
|
||||
}
|
||||
materialized, referenceDiagnostics, err := pipeline.MaterializeReferences(effective.ResolvedPipeline, catalog, pipeline.ReferenceMaterializationOptions{
|
||||
ConfigPath: loadedConfigPath,
|
||||
WorkingDir: workingDir,
|
||||
})
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
effective.ResolvedPipeline = materialized
|
||||
invocation.PipelineDigest = effective.ResolvedPipeline.Digest
|
||||
if err := writeSummary(summary, func() error { return summary.WriteInvocation(invocation) }); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug invocation metadata: %w", err))
|
||||
}
|
||||
if err := writeSummary(summary, func() error { return summary.WriteEffectiveConfig(loaded) }); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug effective config: %w", err))
|
||||
}
|
||||
if err := writeSummary(summary, func() error { return summary.WriteResolvedPipeline(effective) }); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug resolved pipeline: %w", err))
|
||||
}
|
||||
if err := writeSummary(summary, func() error {
|
||||
return summary.WriteResolvedReferences(pipeline.ReferenceProvenance(effective.ResolvedPipeline))
|
||||
}); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug resolved references: %w", err))
|
||||
}
|
||||
|
||||
registries, err := effectiveRegistries(opts)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
|
||||
ctx := context.Background()
|
||||
@@ -333,31 +297,27 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i
|
||||
}
|
||||
llmClient, llmProfiles, err := opts.LLMClientFactory(ctx, effective.Config, factoryProfileID, runtimeOverrides)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("create LLM client for profile %q: %w", factoryProfileID, err))
|
||||
return fail(fmt.Errorf("create LLM client for profile %q: %w", factoryProfileID, err))
|
||||
}
|
||||
llmClient = pipeline.WithDebugLLMRecording(llmClient, debugRecorder)
|
||||
prepared, err := pipeline.Prepare(effective.ResolvedPipeline, registries, pipeline.ModuleDependencies{LLM: llmClient})
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("prepare pipeline %q: %w", pipelineID, err))
|
||||
return fail(fmt.Errorf("prepare pipeline %q: %w", pipelineID, err))
|
||||
}
|
||||
rawInput, err := os.ReadFile(strings.TrimSpace(*inputPath))
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("read input %q: %w", strings.TrimSpace(*inputPath), err))
|
||||
return fail(fmt.Errorf("read input %q: %w", strings.TrimSpace(*inputPath), err))
|
||||
}
|
||||
effectiveSessionID, err := resolvePromptSessionID(requestedSessionID.value, effective.ResolvedPipeline.Input.Module, rawInput)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
}
|
||||
invocation.SessionID = effectiveSessionID
|
||||
if err := writeSummary(summary, func() error { return summary.WriteInvocation(invocation) }); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug invocation metadata: %w", err))
|
||||
return fail(err)
|
||||
}
|
||||
cache, err := artifactcache.NewFilesystemStore(effective.Config.CacheDirectory)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
|
||||
output, err := pipeline.New().Run(ctx, pipeline.RunInput{
|
||||
output, err = pipeline.New().Run(ctx, pipeline.RunInput{
|
||||
Prepared: prepared,
|
||||
Path: strings.TrimSpace(*inputPath),
|
||||
RawInput: rawInput,
|
||||
@@ -372,52 +332,42 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i
|
||||
Workers: cfg.Concurrency.Workers,
|
||||
})
|
||||
diagnosticProjection, diagnosticErr := contracts.ProjectDiagnosticCollection(output.Diagnostics)
|
||||
if diagnosticErr == nil {
|
||||
commandState.observeOutput(output, diagnosticProjection)
|
||||
}
|
||||
if err != nil {
|
||||
primaryErr := fmt.Errorf("run pipeline %q: %w", pipelineID, err)
|
||||
if output.Manifest.PipelineID != "" {
|
||||
if summaryErr := writePartialSummary(summary, output); summaryErr != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, primaryErr, fmt.Errorf("write debug summary: %w", summaryErr))
|
||||
}
|
||||
}
|
||||
if diagnosticErr != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, primaryErr, fmt.Errorf("summarize run diagnostics: %w", diagnosticErr))
|
||||
return fail(primaryErr, fmt.Errorf("summarize run diagnostics: %w", diagnosticErr))
|
||||
}
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, primaryErr)
|
||||
return fail(primaryErr)
|
||||
}
|
||||
if diagnosticErr != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("summarize run diagnostics: %w", diagnosticErr))
|
||||
return fail(fmt.Errorf("summarize run diagnostics: %w", diagnosticErr))
|
||||
}
|
||||
|
||||
if err := writePartialSummary(summary, output); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug summary: %w", err))
|
||||
}
|
||||
var encodedResult []byte
|
||||
if *machineOutput {
|
||||
result, err := newRunResultWithDiagnostics(effective.ResolvedPipeline, output, runOutputDir, debugPath, diagnosticProjection)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
encodedResult, err = encodeRunResult(result)
|
||||
if err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
}
|
||||
if err := writeOutputFiles(runOutputDir, output.OutputFiles); err != nil {
|
||||
return failPipelineCommand(stderr, commandState, terminalWriter, err)
|
||||
return fail(err)
|
||||
}
|
||||
if primaryErr, persistenceErr := commandState.terminalize(terminalWriter, nil); primaryErr != nil {
|
||||
return writePipelineCommandFailure(stderr, commandState, primaryErr, persistenceErr)
|
||||
published = true
|
||||
if err := capture.Finalize(captureOutcome(), nil); err != nil {
|
||||
return fail(err)
|
||||
}
|
||||
|
||||
if *machineOutput {
|
||||
if err := writeRunResult(stdout, encodedResult); err != nil {
|
||||
return writePipelineCommandFailure(stderr, commandState, errors.New("write run result"), nil)
|
||||
return fail(errors.New("write run result"))
|
||||
}
|
||||
} else {
|
||||
fmt.Fprintf(stdout, "pipeline %q complete: outputs=%d rejected=%d output=%s\n", effective.PipelineID, len(output.NormalizeOutputs), len(output.Rejected), runOutputDir)
|
||||
fmt.Fprintf(stdout, "pipeline %q complete: artifacts=%d output=%s\n", effective.PipelineID, output.ArtifactCount(), runOutputDir)
|
||||
if debugPath != "" {
|
||||
fmt.Fprintf(stdout, "debug=%s\n", debugPath)
|
||||
}
|
||||
@@ -441,26 +391,6 @@ func logicalOutputFile(files []contracts.OutputFile, name string) (string, bool)
|
||||
return "", false
|
||||
}
|
||||
|
||||
func writeSummary(summary *debugbundle.SummaryWriter, write func() error) error {
|
||||
if summary == nil {
|
||||
return nil
|
||||
}
|
||||
return write()
|
||||
}
|
||||
|
||||
func writePartialSummary(summary *debugbundle.SummaryWriter, output pipeline.RunOutput) error {
|
||||
if summary == nil {
|
||||
return nil
|
||||
}
|
||||
if err := summary.WriteRunManifest(output.Manifest); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := summary.WriteDiagnostics(output.Diagnostics); err != nil {
|
||||
return err
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func rawInputDigest(data []byte) string {
|
||||
sum := sha256.Sum256(data)
|
||||
return "sha256:" + hex.EncodeToString(sum[:])
|
||||
@@ -566,7 +496,7 @@ func runFlagTakesValue(arg string) bool {
|
||||
}
|
||||
}
|
||||
|
||||
func runConfigurationOverrides(outputDir, debugDir string) []configkit.Override {
|
||||
func runConfigurationOverrides(outputDir string) []configkit.Override {
|
||||
overrides := make([]configkit.Override, 0, 3)
|
||||
if outputDir = strings.TrimSpace(outputDir); outputDir != "" {
|
||||
overrides = append(overrides, configkit.Override{
|
||||
@@ -575,13 +505,6 @@ func runConfigurationOverrides(outputDir, debugDir string) []configkit.Override
|
||||
Flag: "--output-dir",
|
||||
})
|
||||
}
|
||||
if debugDir = strings.TrimSpace(debugDir); debugDir != "" {
|
||||
overrides = append(overrides, configkit.Override{
|
||||
Path: configkit.Keys("debug", "directory"),
|
||||
Value: debugDir,
|
||||
Flag: "--debug-dir",
|
||||
})
|
||||
}
|
||||
return overrides
|
||||
}
|
||||
|
||||
|
||||
51
internal/cli/run_debug.go
Normal file
51
internal/cli/run_debug.go
Normal file
@@ -0,0 +1,51 @@
|
||||
package cli
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
frameworkdebug "gitea.maximumdirect.net/eric/notarius/internal/framework/debug"
|
||||
"go.maximumdirect.net/commandkit"
|
||||
)
|
||||
|
||||
type runDebugInput struct {
|
||||
Enabled commandkit.Supplied[bool]
|
||||
Directory commandkit.Supplied[string]
|
||||
}
|
||||
|
||||
func runDebugFlags[I any](selectInput func(*I) *runDebugInput) []commandkit.Flag[I] {
|
||||
return []commandkit.Flag[I]{
|
||||
commandkit.BoolFlag(commandkit.FlagMeta{Name: "debug", Usage: "Capture run evidence."}, false, func(input *I, value commandkit.Supplied[bool]) { selectInput(input).Enabled = value }),
|
||||
commandkit.ValueFlag(commandkit.FlagMeta{Name: "debug-dir", Usage: "Debug capture directory; empty disables capture."}, (*string)(nil), func(value string) (string, error) {
|
||||
if strings.ContainsRune(value, '\x00') {
|
||||
return "", fmt.Errorf("debug directory must not contain NUL")
|
||||
}
|
||||
return value, nil
|
||||
}, func(input *I, value commandkit.Supplied[string]) { selectInput(input).Directory = value }),
|
||||
}
|
||||
}
|
||||
|
||||
// The configured directory has already been resolved against its source by the
|
||||
// application load. CLI paths instead belong to the invocation directory.
|
||||
func (input runDebugInput) directory(configuredDirectory string) (string, error) {
|
||||
directory := configuredDirectory
|
||||
if input.Directory.Set {
|
||||
directory = input.Directory.Value
|
||||
}
|
||||
if !input.Enabled.Value || directory == "" {
|
||||
return "", nil
|
||||
}
|
||||
return filepath.Abs(directory)
|
||||
}
|
||||
|
||||
// Only the run handler calls this, after configuration/run identity and before
|
||||
// engine construction or pipeline preflight. Shared loaders never allocate.
|
||||
func startRunDebug(input runDebugInput, configuredDirectory, runID string, startedAt time.Time) (*frameworkdebug.Recorder, error) {
|
||||
directory, err := input.directory(configuredDirectory)
|
||||
if err != nil || directory == "" {
|
||||
return nil, err
|
||||
}
|
||||
return frameworkdebug.Start(directory, runID, startedAt)
|
||||
}
|
||||
119
internal/cli/run_debug_test.go
Normal file
119
internal/cli/run_debug_test.go
Normal file
@@ -0,0 +1,119 @@
|
||||
package cli
|
||||
|
||||
import (
|
||||
"context"
|
||||
"io"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/config"
|
||||
"go.maximumdirect.net/commandkit"
|
||||
)
|
||||
|
||||
func TestRunDebugSelectionRetainsNativeBooleanAndSuppliedEmptyDirectory(t *testing.T) {
|
||||
t.Chdir(t.TempDir())
|
||||
configured := filepath.Join(t.TempDir(), "configured")
|
||||
for _, test := range []struct {
|
||||
name string
|
||||
args []string
|
||||
configured, want string
|
||||
enabled bool
|
||||
mode commandkit.ReportingMode
|
||||
}{
|
||||
{"omitted", nil, configured, "", false, commandkit.ReportingModeOrdinary},
|
||||
{"directory alone", []string{"--debug-dir", "override"}, configured, "", false, commandkit.ReportingModeOrdinary},
|
||||
{"configured directory", []string{"--debug"}, configured, configured, true, commandkit.ReportingModeDebug},
|
||||
{"native debug then quiet", []string{"--debug", "--quiet"}, configured, configured, true, commandkit.ReportingModeQuiet},
|
||||
{"native quiet then debug", []string{"--quiet", "--debug"}, configured, configured, true, commandkit.ReportingModeDebug},
|
||||
{"native debug false", []string{"--debug", "--debug=false"}, configured, "", false, commandkit.ReportingModeOrdinary},
|
||||
{"empty configured", []string{"--debug"}, "", "", true, commandkit.ReportingModeDebug},
|
||||
{"explicit empty override", []string{"--debug", "--debug-dir", ""}, configured, "", true, commandkit.ReportingModeDebug},
|
||||
{"relative override", []string{"--debug", "--debug-dir", "override"}, configured, "override", true, commandkit.ReportingModeDebug},
|
||||
{"override reenables empty configured", []string{"--debug", "--debug-dir", "override"}, "", "override", true, commandkit.ReportingModeDebug},
|
||||
{"default", []string{"--debug"}, config.Default().Debug.Directory, "/tmp/notarius-debug", true, commandkit.ReportingModeDebug},
|
||||
} {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
called := false
|
||||
command := commandkit.NewCommand(commandkit.CommandSpec[runDebugInput]{
|
||||
Name: "run", Flags: runDebugFlags(func(input *runDebugInput) *runDebugInput { return input }),
|
||||
Run: func(inv commandkit.Invocation, input runDebugInput) commandkit.Outcome {
|
||||
called = true
|
||||
directory, err := input.directory(test.configured)
|
||||
want := test.want
|
||||
if want != "" {
|
||||
want, _ = filepath.Abs(want)
|
||||
}
|
||||
if err != nil || directory != want || input.Enabled.Value != test.enabled || inv.ReportingMode() != test.mode {
|
||||
t.Errorf("directory=%q error=%v input=%#v mode=%v", directory, err, input, inv.ReportingMode())
|
||||
}
|
||||
return commandkit.Success()
|
||||
},
|
||||
})
|
||||
app, err := commandkit.New(commandkit.Identity{Name: "test"}, command)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
result := app.Execute(context.Background(), append([]string{"run"}, test.args...), commandkit.Streams{Out: io.Discard, Err: io.Discard})
|
||||
if result.Status != 0 || !called {
|
||||
t.Fatalf("native run input=%#v called=%v", result, called)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunDebugStartFailureRetainsAvailablePath(t *testing.T) {
|
||||
parent := t.TempDir()
|
||||
if err := os.Mkdir(filepath.Join(parent, "latest"), 0o700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
enabled := runDebugInput{Enabled: commandkit.Supplied[bool]{Value: true, Set: true}}
|
||||
capture, err := startRunDebug(enabled, parent, "run", time.Now())
|
||||
if err == nil || capture == nil || capture.Path() != filepath.Join(parent, "run") {
|
||||
t.Fatalf("start=%#v %v", capture, err)
|
||||
}
|
||||
// The run handler must stop here; the partially allocated capture can still
|
||||
// finalize and report the start failure without engine/provider construction.
|
||||
if finalErr := capture.Finalize(nil, err); finalErr == nil {
|
||||
t.Fatal("start failure hidden")
|
||||
}
|
||||
if _, err := os.Stat(filepath.Join(capture.Path(), "outcome.json")); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDisabledRunDebugDoesNotAllocateOrChangeLatest(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
unallocated := filepath.Join(root, "unallocated")
|
||||
if capture, err := startRunDebug(runDebugInput{}, unallocated, "run", time.Now()); err != nil || capture != nil {
|
||||
t.Fatalf("disabled capture=%#v %v", capture, err)
|
||||
}
|
||||
if _, err := os.Stat(unallocated); !os.IsNotExist(err) {
|
||||
t.Fatalf("disabled capture created its root: %v", err)
|
||||
}
|
||||
first, err := startRunDebug(runDebugInput{Enabled: commandkit.Supplied[bool]{Value: true}}, root, "first", time.Now())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, input := range []runDebugInput{
|
||||
{},
|
||||
{Directory: commandkit.Supplied[string]{Value: root, Set: true}},
|
||||
{Enabled: commandkit.Supplied[bool]{Value: true}, Directory: commandkit.Supplied[string]{Set: true}},
|
||||
} {
|
||||
capture, err := startRunDebug(input, root, "disabled", time.Now())
|
||||
if err != nil || capture != nil {
|
||||
t.Fatalf("disabled start=%#v %v", capture, err)
|
||||
}
|
||||
}
|
||||
target, err := os.Readlink(filepath.Join(root, "latest"))
|
||||
if err != nil || target != "first" {
|
||||
t.Fatalf("disabled run changed latest=%q %v", target, err)
|
||||
}
|
||||
if _, err := os.Stat(filepath.Join(root, "disabled")); !os.IsNotExist(err) {
|
||||
t.Fatalf("disabled capture allocated: %v", err)
|
||||
}
|
||||
if err := first.Finalize(nil, nil); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
@@ -1,95 +0,0 @@
|
||||
package cli
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
||||
)
|
||||
|
||||
type DebugTerminalWriter interface {
|
||||
WriteRunReport(debugbundle.RunReport) error
|
||||
WriteError(string) error
|
||||
}
|
||||
|
||||
type pipelineCommandState struct {
|
||||
report debugbundle.RunReport
|
||||
terminalized bool
|
||||
}
|
||||
|
||||
func newPipelineCommandState(runID, pipelineID, outputPath string) *pipelineCommandState {
|
||||
return &pipelineCommandState{report: debugbundle.RunReport{
|
||||
RunID: runID,
|
||||
PipelineID: pipelineID,
|
||||
OutputPath: outputPath,
|
||||
}}
|
||||
}
|
||||
|
||||
func (s *pipelineCommandState) setDebugPath(debugPath string) {
|
||||
if s != nil {
|
||||
s.report.DebugPath = debugPath
|
||||
}
|
||||
}
|
||||
|
||||
func (s *pipelineCommandState) observeOutput(output pipeline.RunOutput, diagnostics contracts.DiagnosticProjection) {
|
||||
if s == nil {
|
||||
return
|
||||
}
|
||||
s.report.OutputCount = len(output.NormalizeOutputs)
|
||||
s.report.RejectedCount = len(output.Rejected)
|
||||
s.report.WarningGroupCount = len(diagnostics.Warnings)
|
||||
s.report.WarningOccurrenceCount = diagnostics.WarningOccurrenceCount
|
||||
s.report.DiagnosticGroupCount = len(diagnostics.Diagnostics)
|
||||
s.report.DiagnosticOccurrenceCount = diagnostics.DiagnosticOccurrenceCount
|
||||
s.report.DiagnosticsTruncated = output.Diagnostics.Truncated
|
||||
s.report.ValidationStatus = output.Manifest.ValidationStatus
|
||||
}
|
||||
|
||||
func (s *pipelineCommandState) terminalize(writer DebugTerminalWriter, primaryErr error) (error, error) {
|
||||
if s == nil || s.terminalized {
|
||||
return primaryErr, nil
|
||||
}
|
||||
s.terminalized = true
|
||||
if writer == nil {
|
||||
return primaryErr, nil
|
||||
}
|
||||
|
||||
report := s.report
|
||||
report.Succeeded = primaryErr == nil
|
||||
reportErr := writer.WriteRunReport(report)
|
||||
if reportErr != nil {
|
||||
reportErr = fmt.Errorf("write debug run report: %w", reportErr)
|
||||
if primaryErr == nil {
|
||||
primaryErr = reportErr
|
||||
reportErr = nil
|
||||
}
|
||||
}
|
||||
|
||||
var errorLogErr error
|
||||
if primaryErr != nil {
|
||||
if err := writer.WriteError(primaryErr.Error()); err != nil {
|
||||
errorLogErr = fmt.Errorf("write debug error log: %w", err)
|
||||
}
|
||||
}
|
||||
return primaryErr, errors.Join(reportErr, errorLogErr)
|
||||
}
|
||||
|
||||
func failPipelineCommand(stderr io.Writer, state *pipelineCommandState, writer DebugTerminalWriter, primaryErr error, persistenceErrs ...error) int {
|
||||
primaryErr, terminalErr := state.terminalize(writer, primaryErr)
|
||||
persistenceErrs = append(persistenceErrs, terminalErr)
|
||||
return writePipelineCommandFailure(stderr, state, primaryErr, errors.Join(persistenceErrs...))
|
||||
}
|
||||
|
||||
func writePipelineCommandFailure(stderr io.Writer, state *pipelineCommandState, primaryErr, persistenceErr error) int {
|
||||
fmt.Fprintf(stderr, "notarius: %v\n", primaryErr)
|
||||
if persistenceErr != nil {
|
||||
fmt.Fprintf(stderr, "notarius: %v\n", persistenceErr)
|
||||
}
|
||||
if state != nil && state.report.DebugPath != "" {
|
||||
fmt.Fprintf(stderr, "notarius: debug=%s\n", state.report.DebugPath)
|
||||
}
|
||||
return 1
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
// Package debugbundle owns explicitly requested per-run debug bundles.
|
||||
// Package debugbundle allocates explicitly requested per-run debug directories.
|
||||
package debugbundle
|
||||
|
||||
import (
|
||||
@@ -10,38 +10,54 @@ import (
|
||||
)
|
||||
|
||||
type Bundle struct {
|
||||
path, summaryRoot, traceRoot string
|
||||
createdAt time.Time
|
||||
path string
|
||||
createdAt time.Time
|
||||
}
|
||||
|
||||
// Allocate starts a capture session. A link failure returns the already-created
|
||||
// bundle as well as the error so callers can identify and retain available data.
|
||||
func Allocate(parent, runID string, startedAt time.Time) (*Bundle, error) {
|
||||
parent = strings.TrimSpace(parent)
|
||||
if parent == "" {
|
||||
return nil, fmt.Errorf("debug parent must not be empty")
|
||||
}
|
||||
if err := validateRunID(runID); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
parent, err := filepath.Abs(parent)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("resolve debug parent: %w", err)
|
||||
}
|
||||
if err := os.MkdirAll(parent, 0o700); err != nil {
|
||||
return nil, fmt.Errorf("create debug parent %q: %w", parent, err)
|
||||
}
|
||||
path := filepath.Join(parent, runID)
|
||||
if err := os.Mkdir(path, 0o700); err != nil {
|
||||
if os.IsExist(err) {
|
||||
return nil, fmt.Errorf("debug bundle %q already exists", path)
|
||||
}
|
||||
return nil, fmt.Errorf("create debug bundle %q: %w", path, err)
|
||||
directory := filepath.Join(parent, runID)
|
||||
if err := os.Mkdir(directory, 0o700); err != nil {
|
||||
return nil, fmt.Errorf("create debug bundle %q: %w", directory, err)
|
||||
}
|
||||
summary, trace := filepath.Join(path, "summary"), filepath.Join(path, "trace")
|
||||
if err := os.Mkdir(summary, 0o700); err != nil {
|
||||
_ = os.Remove(path)
|
||||
return nil, fmt.Errorf("create debug summary %q: %w", summary, err)
|
||||
bundle := &Bundle{path: directory, createdAt: startedAt}
|
||||
if err := updateLatest(parent, runID); err != nil {
|
||||
return bundle, fmt.Errorf("update debug latest for %q: %w", directory, err)
|
||||
}
|
||||
if err := os.Mkdir(trace, 0o700); err != nil {
|
||||
_ = os.RemoveAll(path)
|
||||
return nil, fmt.Errorf("create debug trace %q: %w", trace, err)
|
||||
return bundle, nil
|
||||
}
|
||||
|
||||
func updateLatest(parent, runID string) error {
|
||||
temporary, err := os.CreateTemp(parent, ".latest-*")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return &Bundle{path: path, summaryRoot: summary, traceRoot: trace, createdAt: startedAt}, nil
|
||||
name := temporary.Name()
|
||||
defer os.Remove(name)
|
||||
if err := temporary.Close(); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := os.Remove(name); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := os.Symlink(runID, name); err != nil {
|
||||
return err
|
||||
}
|
||||
return os.Rename(name, filepath.Join(parent, "latest"))
|
||||
}
|
||||
|
||||
func validateRunID(runID string) error {
|
||||
@@ -59,18 +75,6 @@ func (b *Bundle) Path() string {
|
||||
}
|
||||
return b.path
|
||||
}
|
||||
func (b *Bundle) SummaryRoot() string {
|
||||
if b == nil {
|
||||
return ""
|
||||
}
|
||||
return b.summaryRoot
|
||||
}
|
||||
func (b *Bundle) TraceRoot() string {
|
||||
if b == nil {
|
||||
return ""
|
||||
}
|
||||
return b.traceRoot
|
||||
}
|
||||
func (b *Bundle) RunID() string {
|
||||
if b == nil {
|
||||
return ""
|
||||
@@ -83,9 +87,3 @@ func (b *Bundle) CreatedAt() time.Time {
|
||||
}
|
||||
return b.createdAt
|
||||
}
|
||||
func (b *Bundle) Summary() *SummaryWriter {
|
||||
if b == nil {
|
||||
return nil
|
||||
}
|
||||
return &SummaryWriter{root: b.summaryRoot, runID: b.RunID(), createdAt: b.createdAt}
|
||||
}
|
||||
|
||||
@@ -1,252 +1,140 @@
|
||||
package debugbundle
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"io"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"sync"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
||||
)
|
||||
|
||||
const testBundleRunID = "run-42-00000000000000000000000000000001"
|
||||
|
||||
func TestAllocateCreatesRestrictiveSummaryAndTrace(t *testing.T) {
|
||||
parent := t.TempDir()
|
||||
fixed := time.Unix(0, 42).UTC()
|
||||
bundle, err := Allocate(parent, testBundleRunID, fixed)
|
||||
func TestAllocateStartsOneDirectoryWithRelativeLatest(t *testing.T) {
|
||||
t.Chdir(t.TempDir())
|
||||
started := time.Unix(42, 0).UTC()
|
||||
bundle, err := Allocate("debug root ", "run-first", started)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if bundle.RunID() != testBundleRunID || bundle.CreatedAt() != fixed || bundle.SummaryRoot() != filepath.Join(bundle.Path(), "summary") || bundle.TraceRoot() != filepath.Join(bundle.Path(), "trace") {
|
||||
if !filepath.IsAbs(bundle.Path()) || bundle.RunID() != "run-first" || bundle.CreatedAt() != started {
|
||||
t.Fatalf("bundle=%#v", bundle)
|
||||
}
|
||||
for _, path := range []string{bundle.Path(), bundle.SummaryRoot(), bundle.TraceRoot()} {
|
||||
info, err := os.Stat(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if info.Mode().Perm() != 0o700 {
|
||||
t.Fatalf("%s mode=%#o", path, info.Mode().Perm())
|
||||
}
|
||||
names, err := os.ReadDir(bundle.Path())
|
||||
if err != nil || len(names) != 0 {
|
||||
t.Fatalf("unexpected summary/trace hierarchy: %v %v", names, err)
|
||||
}
|
||||
if err := bundle.Summary().WriteError("failed"); err != nil {
|
||||
t.Fatal(err)
|
||||
target, err := os.Readlink(filepath.Join(filepath.Dir(bundle.Path()), "latest"))
|
||||
if err != nil || target != bundle.RunID() || filepath.IsAbs(target) {
|
||||
t.Fatalf("latest=%q %v", target, err)
|
||||
}
|
||||
info, err := os.Stat(filepath.Join(bundle.SummaryRoot(), ArtifactErrorLog))
|
||||
}
|
||||
|
||||
func TestAllocateRetainsExistingBundleOnCollision(t *testing.T) {
|
||||
parent := t.TempDir()
|
||||
bundle, err := Allocate(parent, "first", time.Now())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if info.Mode().Perm() != 0o600 {
|
||||
t.Fatalf("file mode=%#o", info.Mode().Perm())
|
||||
}
|
||||
}
|
||||
func TestAllocateRejectsExistingBundleWithoutChangingIt(t *testing.T) {
|
||||
parent := t.TempDir()
|
||||
bundlePath := filepath.Join(parent, testBundleRunID)
|
||||
if err := os.Mkdir(bundlePath, 0o700); err != nil {
|
||||
sentinel := filepath.Join(bundle.Path(), "sentinel")
|
||||
if err := os.WriteFile(sentinel, []byte("existing evidence"), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
sentinelPath := filepath.Join(bundlePath, "sentinel")
|
||||
sentinel := []byte("existing bundle")
|
||||
if err := os.WriteFile(sentinelPath, sentinel, 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
if _, err := Allocate(parent, "first", time.Now()); !errors.Is(err, os.ErrExist) {
|
||||
t.Fatalf("collision=%v", err)
|
||||
}
|
||||
|
||||
if _, err := Allocate(parent, testBundleRunID, time.Unix(0, 42)); err == nil || !strings.Contains(err.Error(), "already exists") {
|
||||
t.Fatalf("Allocate() error = %v, want collision", err)
|
||||
got, err := os.ReadFile(sentinel)
|
||||
if err != nil || string(got) != "existing evidence" {
|
||||
t.Fatalf("evidence=%q %v", got, err)
|
||||
}
|
||||
if got, err := os.ReadFile(sentinelPath); err != nil || !bytes.Equal(got, sentinel) {
|
||||
t.Fatalf("sentinel = %q, %v", got, err)
|
||||
target, err := os.Readlink(filepath.Join(parent, "latest"))
|
||||
if err != nil || target != "first" {
|
||||
t.Fatalf("collision changed latest: %q %v", target, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAllocateRejectsUnsafeRunIDsBeforeCreatingParent(t *testing.T) {
|
||||
for _, runID := range []string{"", ".", "..", "../escape", `..\\escape`, "/absolute", " trailing "} {
|
||||
t.Run(runID, func(t *testing.T) {
|
||||
for _, id := range []string{"", ".", "..", "../escape", "/absolute", " spaced ", string([]byte{'a', 92, 'b'})} {
|
||||
t.Run(id, func(t *testing.T) {
|
||||
parent := filepath.Join(t.TempDir(), "debug")
|
||||
if _, err := Allocate(parent, runID, time.Time{}); err == nil {
|
||||
t.Fatalf("Allocate(%q) succeeded", runID)
|
||||
if _, err := Allocate(parent, id, time.Now()); err == nil {
|
||||
t.Fatal("unsafe run ID accepted")
|
||||
}
|
||||
if _, err := os.Stat(parent); !os.IsNotExist(err) {
|
||||
t.Fatalf("debug parent exists or stat failed: %v", err)
|
||||
t.Fatalf("parent exists: %v", err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestSummaryWriterWritesEverySummaryArtifact(t *testing.T) {
|
||||
bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
summary := bundle.Summary()
|
||||
if err := summary.WriteInvocation(Invocation{Operation: "run"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteEffectiveConfig(testEffectiveConfigWriter{content: "version: 5\n"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteResolvedPipeline(testRedactedResolvedPipelinePayload{}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteResolvedReferences(nil); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteCheckpointEvents(nil); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteRunManifest(artifacts.RunManifest{RunID: bundle.RunID()}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteChunkPlan(artifacts.ChunkPlanSummary{}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteRunReport(RunReport{RunID: bundle.RunID(), PipelineID: "test"}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteDiagnostics(contracts.DiagnosticCollection{}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := summary.WriteError("failed"); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
for _, name := range []string{
|
||||
ArtifactInvocationMetadata,
|
||||
ArtifactEffectiveConfigYAML,
|
||||
ArtifactResolvedPipeline,
|
||||
ArtifactResolvedReferences,
|
||||
ArtifactCheckpointEvents,
|
||||
ArtifactRunManifest,
|
||||
ArtifactChunkPlan,
|
||||
ArtifactRunReport,
|
||||
ArtifactDiagnostics,
|
||||
ArtifactErrorLog,
|
||||
} {
|
||||
info, err := os.Stat(filepath.Join(bundle.SummaryRoot(), name))
|
||||
if err != nil {
|
||||
t.Fatalf("summary artifact %q: %v", name, err)
|
||||
func TestAllocateFailureLeavesAvailableDataWithoutFallbackOrDeletion(t *testing.T) {
|
||||
t.Run("parent is a file", func(t *testing.T) {
|
||||
parent := filepath.Join(t.TempDir(), "debug")
|
||||
if err := os.WriteFile(parent, []byte("existing"), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if info.Mode().Perm() != 0o600 {
|
||||
t.Fatalf("summary artifact %q mode=%#o", name, info.Mode().Perm())
|
||||
if bundle, err := Allocate(parent, "run", time.Now()); err == nil || bundle != nil {
|
||||
t.Fatalf("bundle=%#v error=%v", bundle, err)
|
||||
}
|
||||
}
|
||||
got, err := os.ReadFile(parent)
|
||||
if err != nil || string(got) != "existing" {
|
||||
t.Fatalf("parent changed: %q %v", got, err)
|
||||
}
|
||||
})
|
||||
t.Run("latest cannot be replaced", func(t *testing.T) {
|
||||
parent := t.TempDir()
|
||||
latest := filepath.Join(parent, "latest")
|
||||
if err := os.Mkdir(latest, 0o700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(latest, "sentinel"), []byte("existing"), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
bundle, err := Allocate(parent, "run", time.Now())
|
||||
if err == nil || bundle == nil {
|
||||
t.Fatalf("available bundle lost: %#v %v", bundle, err)
|
||||
}
|
||||
if _, err := os.Stat(bundle.Path()); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got, err := os.ReadFile(filepath.Join(latest, "sentinel")); err != nil || string(got) != "existing" {
|
||||
t.Fatalf("latest directory changed: %q %v", got, err)
|
||||
}
|
||||
names, err := os.ReadDir(parent)
|
||||
if err != nil || len(names) != 2 {
|
||||
t.Fatalf("temporary link left behind: %v %v", names, err)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
func TestWriteEffectiveConfigDoesNotPublishPartialRendering(t *testing.T) {
|
||||
bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
func TestConcurrentAllocationLeavesAllSessionsAndAValidLatestLink(t *testing.T) {
|
||||
parent := t.TempDir()
|
||||
const sessions = 8
|
||||
var wg sync.WaitGroup
|
||||
failures := make(chan error, sessions)
|
||||
for i := range sessions {
|
||||
wg.Add(1)
|
||||
go func(i int) {
|
||||
defer wg.Done()
|
||||
_, err := Allocate(parent, time.Unix(int64(i), 0).Format("150405"), time.Now())
|
||||
failures <- err
|
||||
}(i)
|
||||
}
|
||||
if err := bundle.Summary().WriteEffectiveConfig(testEffectiveConfigWriter{err: errors.New("render failed")}); err == nil {
|
||||
t.Fatal("WriteEffectiveConfig() error = nil, want render failure")
|
||||
}
|
||||
path := filepath.Join(bundle.SummaryRoot(), ArtifactEffectiveConfigYAML)
|
||||
if _, err := os.Stat(path); !os.IsNotExist(err) {
|
||||
t.Fatalf("effective configuration artifact exists after rendering failure: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestWriteInvocationPreservesReasoningEffortOverrideStates(t *testing.T) {
|
||||
replacement := "focused"
|
||||
cleared := ""
|
||||
tests := []struct {
|
||||
name string
|
||||
override *string
|
||||
wantValue string
|
||||
wantSet bool
|
||||
}{
|
||||
{name: "inherit"},
|
||||
{name: "replace", override: &replacement, wantValue: "focused", wantSet: true},
|
||||
{name: "clear", override: &cleared, wantSet: true},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := bundle.Summary().WriteInvocation(Invocation{
|
||||
Operation: "run",
|
||||
ReasoningEffortOverride: tt.override,
|
||||
}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
data, err := os.ReadFile(filepath.Join(bundle.SummaryRoot(), ArtifactInvocationMetadata))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var payload map[string]any
|
||||
if err := json.Unmarshal(data, &payload); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
value, found := payload["reasoning_effort_override"]
|
||||
if found != tt.wantSet || (found && value != tt.wantValue) {
|
||||
t.Fatalf("reasoning override found=%t value=%#v, want found=%t value=%q; JSON=%s", found, value, tt.wantSet, tt.wantValue, data)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestWriteInvocationOmitsEmptySessionID(t *testing.T) {
|
||||
for _, sessionID := range []string{"", "session-123"} {
|
||||
bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42))
|
||||
wg.Wait()
|
||||
close(failures)
|
||||
for err := range failures {
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := bundle.Summary().WriteInvocation(Invocation{Operation: "run", SessionID: sessionID}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
data, err := os.ReadFile(filepath.Join(bundle.SummaryRoot(), ArtifactInvocationMetadata))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var payload map[string]any
|
||||
if err := json.Unmarshal(data, &payload); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
value, found := payload["session_id"]
|
||||
if found != (sessionID != "") || (found && value != sessionID) {
|
||||
t.Fatalf("session found=%t value=%#v, want found=%t value=%q; JSON=%s", found, value, sessionID != "", sessionID, data)
|
||||
}
|
||||
}
|
||||
names, err := os.ReadDir(parent)
|
||||
if err != nil || len(names) != sessions+1 {
|
||||
t.Fatalf("sessions=%v %v", names, err)
|
||||
}
|
||||
target, err := os.Readlink(filepath.Join(parent, "latest"))
|
||||
if err != nil || filepath.IsAbs(target) {
|
||||
t.Fatalf("latest=%q %v", target, err)
|
||||
}
|
||||
if info, err := os.Stat(filepath.Join(parent, target)); err != nil || !info.IsDir() {
|
||||
t.Fatalf("latest target unavailable: %v", err)
|
||||
}
|
||||
}
|
||||
func TestSummaryWriterInternalWritesConfineArtifacts(t *testing.T) {
|
||||
bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := bundle.Summary().writeJSON("../outside.json", map[string]any{}); err == nil {
|
||||
t.Fatal("accepted traversal")
|
||||
}
|
||||
if err := bundle.Summary().writeBytes(`trace\\x`, []byte("x")); err == nil {
|
||||
t.Fatal("accepted backslash")
|
||||
}
|
||||
}
|
||||
|
||||
type testEffectiveConfigWriter struct {
|
||||
content string
|
||||
err error
|
||||
}
|
||||
|
||||
func (writer testEffectiveConfigWriter) WriteEffective(output io.Writer) error {
|
||||
if writer.err != nil {
|
||||
return writer.err
|
||||
}
|
||||
_, err := io.WriteString(output, writer.content)
|
||||
return err
|
||||
}
|
||||
|
||||
type testRedactedResolvedPipelinePayload struct{}
|
||||
|
||||
func (testRedactedResolvedPipelinePayload) RedactedResolvedPipelinePayload() pipeline.ResolvedPipeline {
|
||||
return pipeline.ResolvedPipeline{ID: "redacted"}
|
||||
}
|
||||
|
||||
@@ -1,145 +0,0 @@
|
||||
package debugbundle
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"fmt"
|
||||
"io"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/fileio"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
||||
)
|
||||
|
||||
const (
|
||||
ArtifactInvocationMetadata = "invocation.json"
|
||||
ArtifactEffectiveConfigYAML = "effective-config.yml"
|
||||
ArtifactResolvedPipeline = "resolved-pipeline.json"
|
||||
ArtifactResolvedReferences = "resolved-references.json"
|
||||
ArtifactCheckpointEvents = "checkpoint-events.json"
|
||||
ArtifactRunManifest = "run-manifest.json"
|
||||
ArtifactChunkPlan = "chunk-plan.json"
|
||||
ArtifactRunReport = "run-report.json"
|
||||
ArtifactDiagnostics = "final-diagnostics.json"
|
||||
ArtifactErrorLog = "error.log"
|
||||
)
|
||||
|
||||
type EffectiveConfigWriter interface{ WriteEffective(io.Writer) error }
|
||||
type RedactedResolvedPipelinePayload interface {
|
||||
RedactedResolvedPipelinePayload() pipeline.ResolvedPipeline
|
||||
}
|
||||
type Invocation struct {
|
||||
Operation string `json:"operation"`
|
||||
PipelineID string `json:"pipeline_id,omitempty"`
|
||||
PipelineDigest string `json:"pipeline_digest,omitempty"`
|
||||
Resume bool `json:"resume,omitempty"`
|
||||
RecomputeStep string `json:"recompute_step,omitempty"`
|
||||
InputPath string `json:"input_path,omitempty"`
|
||||
ConfigPath string `json:"config_path,omitempty"`
|
||||
ConfigSource string `json:"config_source,omitempty"`
|
||||
ConfigOverlay string `json:"config_overlay,omitempty"`
|
||||
OnlyLanes []string `json:"only_lanes,omitempty"`
|
||||
ChunkCacheOverride string `json:"chunk_cache_override,omitempty"`
|
||||
ReasoningEffortOverride *string `json:"reasoning_effort_override,omitempty"`
|
||||
SessionID string `json:"session_id,omitempty"`
|
||||
RunID string `json:"run_id"`
|
||||
StartedAt time.Time `json:"started_at"`
|
||||
}
|
||||
type RunReport struct {
|
||||
RunID string `json:"run_id"`
|
||||
PipelineID string `json:"pipeline_id"`
|
||||
OutputPath string `json:"output_path,omitempty"`
|
||||
DebugPath string `json:"debug_path,omitempty"`
|
||||
Succeeded bool `json:"succeeded"`
|
||||
OutputCount int `json:"output_count"`
|
||||
RejectedCount int `json:"rejected_count"`
|
||||
WarningGroupCount int `json:"warning_group_count"`
|
||||
WarningOccurrenceCount int `json:"warning_occurrence_count"`
|
||||
DiagnosticGroupCount int `json:"diagnostic_group_count"`
|
||||
DiagnosticOccurrenceCount int `json:"diagnostic_occurrence_count"`
|
||||
DiagnosticsTruncated bool `json:"diagnostics_truncated"`
|
||||
ValidationStatus string `json:"validation_status,omitempty"`
|
||||
}
|
||||
type SummaryWriter struct {
|
||||
root, runID string
|
||||
createdAt time.Time
|
||||
}
|
||||
|
||||
func (w *SummaryWriter) WriteInvocation(payload Invocation) error {
|
||||
if w == nil {
|
||||
return fmt.Errorf("debug summary writer must not be nil")
|
||||
}
|
||||
if payload.RunID == "" {
|
||||
payload.RunID = w.runID
|
||||
}
|
||||
if payload.StartedAt.IsZero() {
|
||||
payload.StartedAt = w.createdAt
|
||||
}
|
||||
if payload.ReasoningEffortOverride != nil {
|
||||
value := *payload.ReasoningEffortOverride
|
||||
payload.ReasoningEffortOverride = &value
|
||||
}
|
||||
return w.writeJSON(ArtifactInvocationMetadata, payload)
|
||||
}
|
||||
func (w *SummaryWriter) WriteEffectiveConfig(payload EffectiveConfigWriter) error {
|
||||
if payload == nil {
|
||||
return fmt.Errorf("effective configuration writer must not be nil")
|
||||
}
|
||||
var rendered bytes.Buffer
|
||||
if err := payload.WriteEffective(&rendered); err != nil {
|
||||
return fmt.Errorf("render effective configuration: %w", err)
|
||||
}
|
||||
return w.writeBytes(ArtifactEffectiveConfigYAML, rendered.Bytes())
|
||||
}
|
||||
func (w *SummaryWriter) WriteResolvedPipeline(payload RedactedResolvedPipelinePayload) error {
|
||||
if payload == nil {
|
||||
return fmt.Errorf("redacted resolved pipeline payload must not be nil")
|
||||
}
|
||||
return w.writeJSON(ArtifactResolvedPipeline, payload.RedactedResolvedPipelinePayload())
|
||||
}
|
||||
func (w *SummaryWriter) WriteResolvedReferences(v []artifacts.ReferenceProvenance) error {
|
||||
return w.writeJSON(ArtifactResolvedReferences, v)
|
||||
}
|
||||
func (w *SummaryWriter) WriteCheckpointEvents(v []pipeline.CheckpointEvent) error {
|
||||
return w.writeJSON(ArtifactCheckpointEvents, v)
|
||||
}
|
||||
func (w *SummaryWriter) WriteRunManifest(v artifacts.RunManifest) error {
|
||||
return w.writeJSON(ArtifactRunManifest, v)
|
||||
}
|
||||
func (w *SummaryWriter) WriteChunkPlan(v artifacts.ChunkPlanSummary) error {
|
||||
return w.writeJSON(ArtifactChunkPlan, v)
|
||||
}
|
||||
func (w *SummaryWriter) WriteRunReport(v RunReport) error { return w.writeJSON(ArtifactRunReport, v) }
|
||||
func (w *SummaryWriter) WriteDiagnostics(v contracts.DiagnosticCollection) error {
|
||||
return w.writeJSON(ArtifactDiagnostics, contracts.CloneDiagnosticCollection(v))
|
||||
}
|
||||
func (w *SummaryWriter) WriteError(message string) error {
|
||||
return w.writeBytes(ArtifactErrorLog, []byte(message+"\n"))
|
||||
}
|
||||
func (w *SummaryWriter) writeJSON(name string, v any) error {
|
||||
if w == nil {
|
||||
return fmt.Errorf("debug summary writer must not be nil")
|
||||
}
|
||||
if err := fileio.WriteJSON(w.root, summaryName(name), v, 0o700, 0o600); err != nil {
|
||||
return fmt.Errorf("write debug summary artifact %q: %w", name, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
func (w *SummaryWriter) writeBytes(name string, v []byte) error {
|
||||
if w == nil {
|
||||
return fmt.Errorf("debug summary writer must not be nil")
|
||||
}
|
||||
if err := fileio.WriteBytes(w.root, summaryName(name), v, 0o700, 0o600); err != nil {
|
||||
return fmt.Errorf("write debug summary artifact %q: %w", name, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
func summaryName(name string) string {
|
||||
name = strings.TrimSpace(name)
|
||||
if name == "" || strings.ContainsAny(name, "/\\") {
|
||||
return "../invalid"
|
||||
}
|
||||
return name
|
||||
}
|
||||
@@ -1,38 +1,167 @@
|
||||
// Package debug records explicitly requested application evidence.
|
||||
package debug
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"errors"
|
||||
"fmt"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/core/fileio"
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
||||
)
|
||||
|
||||
type FilesystemRecorder struct {
|
||||
root string
|
||||
// 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 NewFilesystemRecorder(root string) (pipeline.DebugRecorder, error) {
|
||||
root = strings.TrimSpace(root)
|
||||
if strings.TrimSpace(root) == "" {
|
||||
return pipeline.NoopDebugRecorder(), nil
|
||||
func Start(parent, runID string, startedAt time.Time) (*Recorder, error) {
|
||||
bundle, err := debugbundle.Allocate(parent, runID, startedAt)
|
||||
if bundle == nil {
|
||||
return nil, err
|
||||
}
|
||||
return &FilesystemRecorder{root: root}, nil
|
||||
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 *FilesystemRecorder) Enabled() bool {
|
||||
return r != nil && strings.TrimSpace(r.root) != ""
|
||||
func (r *Recorder) Enabled() bool { return r != nil && r.bundle != nil }
|
||||
func (r *Recorder) Path() string {
|
||||
if r == nil {
|
||||
return ""
|
||||
}
|
||||
return r.bundle.Path()
|
||||
}
|
||||
|
||||
func (r *FilesystemRecorder) WriteJSON(name string, payload any) error {
|
||||
// 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
|
||||
}
|
||||
return fileio.WriteJSON(r.root, name, payload, 0o700, 0o600)
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
return r.recordingErr
|
||||
}
|
||||
|
||||
func (r *FilesystemRecorder) WriteBytes(name string, data []byte) error {
|
||||
func (r *Recorder) WriteJSON(name string, payload any) error {
|
||||
if !r.Enabled() {
|
||||
return nil
|
||||
}
|
||||
return fileio.WriteBytes(r.root, name, data, 0o700, 0o600)
|
||||
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
|
||||
}
|
||||
|
||||
@@ -1,79 +1,210 @@
|
||||
package debug
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"sync"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline"
|
||||
)
|
||||
|
||||
func TestFilesystemRecorderWritesWithinTraceRoot(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
recorder, err := NewFilesystemRecorder(root)
|
||||
func startTestCapture(t *testing.T, parent, id string) *Recorder {
|
||||
t.Helper()
|
||||
recorder, err := Start(parent, id, time.Unix(42, 0).UTC())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := recorder.WriteBytes("attempt/data", []byte("payload")); err != nil {
|
||||
return recorder
|
||||
}
|
||||
|
||||
func TestRecorderPersistsIncrementallyAndFinalizesOnce(t *testing.T) {
|
||||
parent := t.TempDir()
|
||||
recorder := startTestCapture(t, parent, "first")
|
||||
var _ pipeline.DebugRecorder = recorder
|
||||
source := strings.Repeat("Source text and sk-ordinary-application-content. ", 400)
|
||||
if err := recorder.WriteBytes("operations/extract/source.txt", []byte(source)); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
info, err := os.Stat(filepath.Join(root, "attempt", "data"))
|
||||
if err != nil {
|
||||
if got, err := os.ReadFile(filepath.Join(recorder.Path(), "operations/extract/source.txt")); err != nil || string(got) != source {
|
||||
t.Fatalf("incremental evidence=%q %v", got, err)
|
||||
}
|
||||
second := startTestCapture(t, parent, "second")
|
||||
primary := errors.New("pipeline failed")
|
||||
result := struct {
|
||||
OutputDirectory string
|
||||
Published bool
|
||||
}{"/output/already-published", true}
|
||||
if err := recorder.Finalize(result, primary); !errors.Is(err, primary) {
|
||||
t.Fatalf("primary failure lost: %v", err)
|
||||
}
|
||||
before, err := os.ReadFile(filepath.Join(recorder.Path(), "outcome.json"))
|
||||
if err != nil || !strings.Contains(string(before), result.OutputDirectory) || !strings.Contains(string(before), primary.Error()) {
|
||||
t.Fatalf("terminal evidence=%s %v", before, err)
|
||||
}
|
||||
if err := recorder.Finalize("replacement", nil); !errors.Is(err, primary) {
|
||||
t.Fatalf("repeat finalization=%v", err)
|
||||
}
|
||||
after, err := os.ReadFile(filepath.Join(recorder.Path(), "outcome.json"))
|
||||
if err != nil || string(after) != string(before) {
|
||||
t.Fatalf("terminal outcome rewritten: %q %v", after, err)
|
||||
}
|
||||
if err := second.Finalize(map[string]any{"success": true}, nil); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if info.Mode().Perm() != 0o600 {
|
||||
t.Fatalf("mode=%#o", info.Mode().Perm())
|
||||
deliveryErr := errors.New("stdout delivery failed after publication")
|
||||
if err := second.Finalize(nil, deliveryErr); !errors.Is(err, deliveryErr) {
|
||||
t.Fatalf("post-capture delivery failure lost: %v", err)
|
||||
}
|
||||
if err := recorder.WriteBytes("../outside", nil); err == nil {
|
||||
t.Fatal("accepted traversal")
|
||||
target, err := os.Readlink(filepath.Join(parent, "latest"))
|
||||
if err != nil || target != "second" {
|
||||
t.Fatalf("completion retargeted latest: %q %v", target, err)
|
||||
}
|
||||
if err := recorder.WriteBytes("late.txt", nil); err == nil {
|
||||
t.Fatal("write after finalization succeeded")
|
||||
}
|
||||
info, err := os.Stat(filepath.Join(recorder.Path(), "outcome.json"))
|
||||
if err != nil || info.Mode().Perm() != 0o600 {
|
||||
t.Fatalf("capture file=%v %v", info, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestFilesystemRecorderPropagatesWriteFailures(t *testing.T) {
|
||||
root := filepath.Join(t.TempDir(), "trace")
|
||||
if err := os.WriteFile(root, []byte("not a directory"), 0o600); err != nil {
|
||||
func TestRecorderRetainsCallbackErrorAndExposesItAtBoundary(t *testing.T) {
|
||||
recorder := startTestCapture(t, t.TempDir(), "run")
|
||||
callbackErr := errors.New("observer recording failed")
|
||||
recorder.RecordError(callbackErr)
|
||||
if !errors.Is(recorder.Err(), callbackErr) {
|
||||
t.Fatal("callback failure not retained")
|
||||
}
|
||||
if err := recorder.WriteJSON("available.json", map[string]string{"available": "evidence"}); !errors.Is(err, callbackErr) {
|
||||
t.Fatalf("boundary hid callback error: %v", err)
|
||||
}
|
||||
if _, err := os.Stat(filepath.Join(recorder.Path(), "available.json")); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
recorder, err := NewFilesystemRecorder(root)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := recorder.WriteBytes("attempt/data", []byte("payload")); err == nil {
|
||||
t.Fatal("WriteBytes concealed a trace-root write failure")
|
||||
primary := errors.New("primary operation failed")
|
||||
err := recorder.Finalize(map[string]string{"output_directory": "/published"}, primary)
|
||||
if !errors.Is(err, primary) || !errors.Is(err, callbackErr) || !strings.HasPrefix(err.Error(), primary.Error()) {
|
||||
t.Fatalf("failure causes/order lost: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSynchronizedFilesystemRecorderSupportsConcurrentWrites(t *testing.T) {
|
||||
func TestRecorderWriteAndFinalizationFailuresPreserveEvidence(t *testing.T) {
|
||||
for _, defect := range []string{"incremental write", "outcome write", "overview write", "outcome encoding"} {
|
||||
t.Run(defect, func(t *testing.T) {
|
||||
recorder := startTestCapture(t, t.TempDir(), "run")
|
||||
if err := recorder.WriteBytes("available.txt", []byte("retained")); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var result any = map[string]any{"output_directory": "/published", "artifact_count": 2}
|
||||
switch defect {
|
||||
case "incremental write":
|
||||
if err := os.WriteFile(filepath.Join(recorder.Path(), "operations"), nil, 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := recorder.WriteJSON("operations/result.json", result); err == nil {
|
||||
t.Fatal("write failure hidden")
|
||||
}
|
||||
case "outcome write":
|
||||
if err := os.Mkdir(filepath.Join(recorder.Path(), "outcome.json"), 0o700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
case "overview write":
|
||||
// Replace only the initial overview file with a directory to make the
|
||||
// terminal write fail, without relying on effective UID permissions.
|
||||
filename := filepath.Join(recorder.Path(), "overview.txt")
|
||||
if err := os.Rename(filename, filepath.Join(recorder.Path(), "initial-overview.txt")); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.Mkdir(filename, 0o700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
case "outcome encoding":
|
||||
result = make(chan int)
|
||||
}
|
||||
finalErr := recorder.Finalize(result, nil)
|
||||
if finalErr == nil {
|
||||
t.Fatal("capture failure reported success")
|
||||
}
|
||||
if got, err := os.ReadFile(filepath.Join(recorder.Path(), "available.txt")); err != nil || string(got) != "retained" {
|
||||
t.Fatalf("evidence removed: %q %v", got, err)
|
||||
}
|
||||
primary := errors.New("new failure")
|
||||
if err := recorder.Finalize(nil, primary); !errors.Is(err, primary) || !errors.Is(err, finalErr) {
|
||||
t.Fatalf("additional primary error or original capture failure lost: %v", err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRecorderStartFailureProvidesAvailableDirectory(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
recorder, err := NewFilesystemRecorder(root)
|
||||
if err != nil {
|
||||
if err := os.Mkdir(filepath.Join(root, "latest"), 0o700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
recorder = pipeline.SynchronizedDebugRecorder(recorder)
|
||||
recorder, err := Start(root, "run", time.Now())
|
||||
if err == nil || recorder == nil || recorder.Path() != filepath.Join(root, "run") {
|
||||
t.Fatalf("start=%#v %v", recorder, err)
|
||||
}
|
||||
if err := recorder.Finalize(nil, err); err == nil {
|
||||
t.Fatal("start failure concealed")
|
||||
}
|
||||
if _, err := os.Stat(filepath.Join(recorder.Path(), "outcome.json")); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
|
||||
const writes = 16
|
||||
func TestRecorderConcurrentWritesAndBoundaryChecks(t *testing.T) {
|
||||
recorder := startTestCapture(t, t.TempDir(), "run")
|
||||
const count = 16
|
||||
var wg sync.WaitGroup
|
||||
errs := make(chan error, writes)
|
||||
for i := 0; i < writes; i++ {
|
||||
i := i
|
||||
failures := make(chan error, count)
|
||||
for i := range count {
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
go func(i int) {
|
||||
defer wg.Done()
|
||||
errs <- recorder.WriteBytes(fmt.Sprintf("attempt/%02d/data", i), []byte("payload"))
|
||||
}()
|
||||
failures <- recorder.WriteJSON(fmt.Sprintf("operations/%02d/result.json", i), map[string]int{"value": i})
|
||||
_ = recorder.Err()
|
||||
}(i)
|
||||
}
|
||||
wg.Wait()
|
||||
close(errs)
|
||||
for err := range errs {
|
||||
close(failures)
|
||||
for err := range failures {
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
for i := 0; i < writes; i++ {
|
||||
if _, err := os.Stat(filepath.Join(root, "attempt", fmt.Sprintf("%02d", i), "data")); err != nil {
|
||||
t.Fatalf("trace artifact %d: %v", i, err)
|
||||
if err := recorder.Finalize(map[string]int{"operations": count}, nil); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for i := range count {
|
||||
content, err := os.ReadFile(filepath.Join(recorder.Path(), fmt.Sprintf("operations/%02d/result.json", i)))
|
||||
var decoded map[string]int
|
||||
if err != nil || json.Unmarshal(content, &decoded) != nil || decoded["value"] != i {
|
||||
t.Fatalf("operation %d: %s %v", i, content, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestDisabledRecorderIsANoopAndPreservesPrimaryFailure(t *testing.T) {
|
||||
var recorder *Recorder
|
||||
primary := errors.New("operation failed")
|
||||
if recorder.Enabled() || recorder.Path() != "" || recorder.Err() != nil {
|
||||
t.Fatal("nil recorder enabled")
|
||||
}
|
||||
if err := recorder.WriteJSON("../ignored", make(chan int)); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := recorder.WriteBytes("../ignored", nil); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
recorder.RecordError(errors.New("ignored"))
|
||||
if err := recorder.Finalize(nil, primary); err != primary {
|
||||
t.Fatalf("primary=%v", err)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user