cmd/dst is the replay command for deterministic simulation testing (DST). Give it a seed and it runs one simulation with simtest.Run. It prints a one-line result summary and every invariant violation that the run found. The command adds no simulation logic of its own. The scenario, the fault model, and the invariant checks live in internal/simtest.
Triage loop, from the doc comment in main.go:
go run ./cmd/dst -seed <seed> [-steps N] [-v] [-keep]-
[main.go:main]Entry point. It parses flags, builds asimtest.Config, and callssimtest.Run(cfg). It reads no positional arguments. -
Flags:
Flag Type Default Meaning -seed[main.go:flag -seed]uint64 0Simulation seed ( DST_SEEDin the DST tests). SetsConfig.Seed.-steps[main.go:flag -steps]int 0Scheduler steps. 0uses the simtest default (150,[../../internal/simtest/scenario.go:withDefaults]).-nodes[main.go:flag -nodes]int 0Simulated nodes. 0uses the simtest default (3).-backend[main.go:flag -backend]string ""Authority-store lane: sqliteors3wal(DST_REF_BACKEND). Empty meanssqlite(simtest.RefBackendSQLite).-v[main.go:flag -v]bool falseSets Config.Trace = os.Stdout, so the trace prints while the run executes.-keep[main.go:flag -keep]bool falseCreates a run directory, sets Config.DirandConfig.KeepDir, and printsrun dir: <path>. -
Output on stdout
[main.go:main]:- One summary line:
seed=… backend=… steps=… trace=<TraceHash> transitions=… deliveries=… faults=… cas-faults=… steals=… crash-steals=… push-steals=… push-crash-steals=… push-forced-rescues=…. VIOLATION: <msg>for each entry inResult.Violations, orok: no invariant violationswhen there are none.
- One summary line:
-
Exit codes
[main.go:main]:0clean run,1at least one invariant violation,2infrastructure failure (simtest.Runreturned an error, oros.MkdirTempfailed). -
[main.go:main]flag.Parseuses the defaultflag.ExitOnErrorset. An unknown or malformed flag prints the usage message and exits2, and-hexits0.
[main.go:main]Exit code1means only "invariant violation".simtest.Runreports invariant breaches inResult.Violations, not as an error[../../internal/simtest/scenario.go:Run].[main.go:main]Exit code2does not mean only "infrastructure failure". A flag parse error also exits2. An unrecovered panic, such as a failed simtestassertf[../../internal/simtest/fault.go:assertf], also exits2with a Go panic trace on stderr.[../../internal/simtest/scenario.go:withDefaults]-backendmust be empty,sqlite, ors3wal. Any other value fails anassertfin simtest and the process panics.maindoes not validate the value itself.[../../internal/simtest/scenario.go:withDefaults]Steps and nodes must be positive after defaults. A negative-stepsor-nodespanics throughassertf.[main.go:main]The same seed, steps, nodes, and backend replay the same op trace as the DST tests (doc comment inmain.go). Compare the printedtrace=hash to confirm a replay.
[main.go:main]Writes the summary, the violation oroklines, and therun dir:line to stdout. With-v, simtest also writes trace lines to stdout.[main.go:main]Writesdst: infrastructure failure: <err>ordst: <err>to stderr beforeos.Exit(2).[main.go:flag -keep]Creates a temporary directory withos.MkdirTemp("", "dst-seed<seed>-*"). Nothing removes it. Delete it by hand after inspection.[../../internal/simtest/scenario.go:Run]Without-keep, simtest creates a run-scoped scratch directory and removes it after the run.
- Run:
go test ./cmd/dst/... -tags=openstorage_viewcheck -count=1 -race -timeout=30m(this package has no test files, so this only compiles the package) - Replay one seed (docs/reference/testing.md):
go run ./cmd/dst -seed <seed> [-steps N] [-nodes N] [-v] [-keep]