Documentation
¶
Overview ¶
Package crashinject provides a subprocess-based crash-injection harness for deterministic crash-safety testing of WAL, snapshot, and checkpoint write paths.
Architecture ¶
Crash-injection tests use a parent–child model:
- The test parent calls Run with a named scenario.
- Run spawns cmd/crashinject-helper as a child process, passing GOGRAPH_CRASH_AT=<scenario> and GOGRAPH_CRASH_DIR=<dir>.
- The helper runs the scenario and calls Breakpoint at a precisely chosen execution point.
- Breakpoint sends SIGKILL to itself, terminating the child abruptly at that exact state.
- Run returns an Out value describing how the child exited, and the caller inspects the artefacts left in dir.
Breakpoint registration ¶
Library code (e.g. store/wal, store/snapshot) calls Breakpoint at any point where a crash should be injected. A typical call site:
crashinject.Breakpoint("wal.mid-frame")
This is a no-op in production (GOGRAPH_CRASH_AT is not set) and self-kills the process when running under the crash harness.
Concurrency ¶
Breakpoint reads an environment variable set once at process startup — it is safe to call concurrently with no locking. Run is safe to call from multiple goroutines (each invocation spawns an independent child process); the package-level binary cache is guarded by a sync.Once.
Index ¶
Constants ¶
const EnvCrashAt = crashpoint.EnvCrashAt
EnvCrashAt is the environment variable read by Breakpoint to decide which named point should trigger a crash. It is an alias for crashpoint.EnvCrashAt; the canonical definition lives in the dependency-light crashpoint package so production code can embed breakpoints without importing this test-harness package.
const EnvCrashDir = crashpoint.EnvCrashDir
EnvCrashDir is the environment variable that tells the helper binary where to place its artefacts (WAL files, temp data). Alias for crashpoint.EnvCrashDir.
Variables ¶
This section is empty.
Functions ¶
func Breakpoint ¶
func Breakpoint(name string)
Breakpoint is a thin re-export of crashpoint.Breakpoint so existing callers of crashinject.Breakpoint keep working. New production call sites should import internal/crashpoint directly to avoid pulling the testing package into their binaries.
Types ¶
type Opts ¶
type Opts struct {
// Dir is the crash artefact directory forwarded to the helper via
// GOGRAPH_CRASH_DIR. If empty, [Run] creates a fresh t.TempDir()
// and the caller finds artefacts there after Run returns.
Dir string
// Timeout caps the child execution. Zero defaults to 30 s.
Timeout time.Duration
// Env holds additional KEY=VALUE pairs appended to the child
// environment (after GOGRAPH_CRASH_AT and GOGRAPH_CRASH_DIR).
Env []string
}
Opts configures a Run invocation.
type Out ¶
type Out struct {
// Stdout and Stderr hold the child's captured output streams.
Stdout []byte
Stderr []byte
// ExitCode is the numeric exit status. Meaningful only when
// Killed is false and the child exited voluntarily.
ExitCode int
// Signal is the signal that terminated the child, or nil.
Signal os.Signal
// Killed reports whether the child was terminated by SIGKILL.
Killed bool
// Dir is the crash artefact directory used by the child. Callers
// inspect artefacts left there after Run returns.
Dir string
}
Out captures the observable outcome of a helper child process spawned by Run.
func Run ¶
Run builds (lazily) and spawns the cmd/crashinject-helper binary with GOGRAPH_CRASH_AT=scenario. It waits for the child to exit and returns the captured output and exit status.
The caller should inspect Out.Killed to confirm the child was terminated by SIGKILL, and then examine the artefacts in Out.Dir.
Source Files