Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can β€” learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company πŸ‘‡

chore(khaos): comments that state the constraint, not how it was found

CarterPerez-devac2310f83987
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.go b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.go
index fe04e0ce..9f2f4ace 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main.go
@@ -52,16 +52,12 @@ func main() {
os.Exit(guarded(execute))
}
-// guarded is the boundary that makes CodeInternal reachable. The taxonomy
-// published code 70 as "a recovered panic" and nothing in khaos recovered
-// one, so a bug crashed with a Go stack trace and whatever exit status the
-// runtime chose -- indistinguishable to CI from a tool that could not parse
-// its flags.
+// guarded is the boundary that makes CodeInternal reachable, so a bug exits
+// 70 rather than with whatever status the runtime chose.
//
// Recovering HERE and nowhere deeper is deliberate: the panic still unwinds
// every frame below, so every deferred revert, lease release and lock
-// handoff runs exactly as it does on any other error path. khaos only
-// decides what to say about it.
+// handoff runs as it does on any other error path.
func guarded(run func() int) (code int) {
defer func() {
recovered := recover()
@@ -143,10 +139,9 @@ func noColorRequested(args []string) bool {
// verdict outcomes is decided once where the run ends rather than re-derived
// by a chain here that grows with every epistemic value. The checks below it
// are for errors that never reached a verdict at all.
-// fail decides what the operator READS. What the process RETURNS is decided by
-// cli.ExitCode, which is the same classification the run record carries, so
-// the status and the artifact cannot disagree. This function used to carry its
-// own table, and a rollback failure exited 6 while run.json said 1.
+// fail decides what the operator READS. What the process RETURNS is decided
+// by cli.ExitCode, the same classification the run record carries, so the
+// status and the artifact cannot disagree.
func fail(err error) int {
code := cli.ExitCode(err)
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.go b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.go
index d19c13fc..42f519c5 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/cmd/khaos/main_test.go
@@ -206,16 +206,9 @@ func TestRollbackFailureOutranksEveryOtherExitCode(t *testing.T) {
}
}
-// Exit code 70 was published in the taxonomy as "a recovered panic" and
-// nothing in khaos recovered one: `CodeInternal` appeared in its own
-// declaration and in a numeric assertion, and in no production path at all.
-// A bug therefore crashed with a Go stack trace and whatever status the
-// runtime chose, which CI cannot tell from a tool that could not parse its
-// flags.
-//
-// The deferred cleanup below is the half that matters more than the code: the
-// panic still unwinds every frame, so a fault khaos had applied is still
-// reverted on the way out.
+// A bug has to exit 70 rather than with whatever status the runtime chose.
+// The deferred cleanup matters more than the code: the panic still unwinds
+// every frame, so an applied fault is still reverted on the way out.
func TestAPanicBecomesTheInternalCodeWithCleanupIntact(t *testing.T) {
reverted := false
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.go
index 7517540d..da9510b4 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit.go
@@ -126,10 +126,9 @@ func emitRecord(
return outcome
}
- // A verdict khaos reached outranks a file it could not write. The warning
- // goes to the DIAGNOSTIC stream: writing it to out appended prose to the
- // JSON document under --output json, which breaks that contract on the one
- // path where CI needs machine-readable evidence.
+ // A verdict khaos reached outranks a file it could not write, and the
+ // warning goes to the DIAGNOSTIC stream so --output json stays one
+ // decodable document.
if outcome != nil {
fmt.Fprintf(emit.diagnostic(), warnRecordWrite, writeErr)
@@ -170,18 +169,15 @@ func writeProjections(rec record.Record, into Projections) error {
// exitDetail reads the code and the outcome name back off a finished run, so
// the record can carry what khaos is about to return to the shell.
//
-// It is the SAME classification the process boundary uses, because these were
-// two lists: this one mapped anything without a typed Exit to usage code 1
-// while the boundary recognised the rollback and cancellation sentinels on its
-// own, so a real rollback failure wrote exit.code 1 into run.json and exited 6.
+// It is the SAME classification the process boundary uses, so the status and
+// the artifact cannot disagree.
func exitDetail(outcome error) (int, string) {
if outcome == nil {
return CodeOK, ""
}
- // Matched on the sentinels BEFORE any carried code, because these are the
- // outcomes nothing may suppress and they must not depend on some other
- // layer having wrapped them correctly.
+ // Matched on the sentinels BEFORE any carried code: nothing may suppress
+ // these, so they cannot depend on another layer having wrapped them.
if errors.Is(outcome, run.ErrRevertFailed) ||
errors.Is(outcome, ErrNotRecovered) {
return CodeRollback, string(outcomeRollback)
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.go
index 85dfdf8e..b4bee752 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/emit_test.go
@@ -414,12 +414,9 @@ func TestAProjectionThatCannotBeWrittenIsNotSilent(t *testing.T) {
}
// pflag advertises a flag's value by the FIRST backquoted word in its usage
-// string, so that placeholder is prose maintained like a signature. Three of
-// these were wrong on arrival: `--record` takes a DIRECTORY and advertised
-// `run.json`, so an operator reads the help and passes a filename; `--junit`
-// advertised `skipped`, which is a JUnit element and not a value at all; and
-// `--metrics-out` advertised nothing and fell back to `string` beside two
-// neighbours that did not.
+// string, so the placeholder is prose maintained like a signature. --record
+// takes a DIRECTORY, and advertising a filename sends an operator to the
+// wrong shape.
func TestTheReportingFlagsAdvertiseWhatTheyTake(t *testing.T) {
definition := outage(t)
sub := experimentCmdFor(t, newRunCmd(), definition)
@@ -448,12 +445,8 @@ func TestTheReportingFlagsAdvertiseWhatTheyTake(t *testing.T) {
}
// --output json promises stdout carries the record and nothing else, so
-// `khaos run x --output json | jq .verdict` works. A write failure broke that
-// promise on exactly the path CI needs most: the JSON went to `out`, and so
-// did the prose warning about the artifact khaos could not write, so a defect
-// plus an invalid --record destination produced a JSON document followed by a
-// sentence. Diagnostics belong on stderr; the machine format gets the stream
-// it was asked for.
+// `khaos run x --output json | jq .verdict` works. A defect plus an
+// unwritable --record must not append prose to that document.
func TestAnArtifactFailureNeverContaminatesTheJSONStream(t *testing.T) {
result, definition := emitted(t)
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.go
index 309c42b0..dc012263 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/exit_test.go
@@ -447,15 +447,9 @@ func TestTheExitCodesAreTheirPublishedNumbers(t *testing.T) {
}
// The code in the record and the code the process returns are the SAME
-// contract, and they were computed by two different lists.
-//
-// exitFor returned an execution error unclassified, exitDetail mapped anything
-// without a typed Exit to usage code 1, and the process boundary separately
-// recognised the rollback and cancellation sentinels. So a real rollback
-// failure wrote `exit.code: 1` into run.json while the process exited 6 -- the
-// artifact disagreeing with the status about the one outcome no --fail-on value
-// may suppress. The unit census never caught it because it called exitFor with
-// a nil execution error.
+// contract. Computed by two lists, they disagreed: a rollback failure wrote
+// exit.code 1 into run.json while the process exited 6, about the one
+// outcome no --fail-on value may suppress.
func TestTheRecordedCodeIsTheCodeTheProcessReturns(t *testing.T) {
for name, tc := range map[string]struct {
err error
@@ -522,10 +516,9 @@ func TestTheRecordedCodeIsTheCodeTheProcessReturns(t *testing.T) {
}
}
-// `reap --interval 0` reached time.NewTicker(0), which panics, and it got
-// there AFTER the workspace was opened and its lock taken -- so the operator
-// paid for a refusal that arrived as a Go stack trace. Validated before
-// anything is opened.
+// A non-positive reap interval reaches time.NewTicker, which panics, and it
+// got there after the workspace lock was taken. Refused before anything
+// opens.
func TestANonPositiveReapIntervalIsRefusedBeforeAnythingOpens(t *testing.T) {
for _, interval := range []time.Duration{
0,
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.go
index fe133e63..7bb65e42 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/experiment.go
@@ -652,11 +652,10 @@ type Output struct {
Record string
Projections Projections
- // Diagnostic is where a failure that is NOT the verdict goes. It is
- // separate from the report stream because a warning on stdout turns the
- // --output json contract into a JSON document followed by a sentence, and
- // it is separate from the report because under json the report is
- // discarded while this must still be seen.
+ // Diagnostic is where a failure that is NOT the verdict goes: separate
+ // from stdout so --output json stays one decodable document, and
+ // separate from the report because json discards the report while this
+ // still has to be seen.
Diagnostic io.Writer
}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.go
index 5a91887e..dadfde4f 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/cli/reclaim.go
@@ -58,9 +58,8 @@ every other fault on the machine.`
errIntervalUsage = "%w: %s"
)
-// A non-positive interval reached time.NewTicker, which panics, AFTER the
-// workspace had been opened and its lock taken. Refused by name instead, and
-// before anything is opened.
+// A non-positive interval reaches time.NewTicker, which panics. Refused by
+// name instead, before the workspace is opened and its lock taken.
var ErrIntervalNotPositive = errors.New(
"the reap interval has to be longer than zero, or there is no tick to check the journal on",
)
@@ -135,8 +134,8 @@ func runReclaim(ctx context.Context, out io.Writer, expiredOnly bool) error {
}
func runReap(ctx context.Context, out io.Writer, interval time.Duration) error {
- // Before the workspace, because a refusal that has already taken the lock
- // is a refusal that cost the operator something.
+ // Before the workspace: a refusal that already took the lock cost the
+ // operator something.
if interval <= 0 {
return fmt.Errorf(errIntervalUsage, ErrIntervalNotPositive, interval)
}
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.go
index 495ea0e9..09028ac2 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/dockerx/recreate.go
@@ -140,12 +140,9 @@ func (c *Client) Capture(
}
// Identify resolves a name to the IMMUTABLE container id behind it, or
-// ErrContainerGone when nothing answers to that name.
-//
-// A name is a label the daemon lets any container hold, and this tier hands
-// one container's name to another on purpose. Anything destructive therefore
-// has to ask which container a name currently means before acting on it, and
-// then act on the id rather than on the name it came from.
+// ErrContainerGone when nothing answers to it. A name is a label the daemon
+// lets any container hold, and the environment tier hands one container's
+// name to another on purpose, so anything destructive resolves first.
func (c *Client) Identify(ctx context.Context, ref string) (string, error) {
result, err := c.api.ContainerInspect(
ctx,
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.go
index 782dd8bb..e33325c0 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/forgery_verdict_test.go
@@ -617,17 +617,10 @@ func TestARequiredForgedStreamWithNoDecisionsCannotReportHeld(t *testing.T) {
}
}
-// The guard that requires this experiment's own stream to have been MEASURED
-// counted transport observations as decisions.
-//
-// `Countable()` excludes only khaos's own failures, so a timeout, an
-// unreachable target and a throttle all satisfied a check whose own name and
-// comment say "the target actually decided about it". Thirty forged probes that
-// timed out therefore cleared the floor, and a healthy valid/invalid pair then
-// produced a CONCLUSIVE hold about a credential the target was never observed
-// to judge. `Answered()` is the discriminator -- the same one that split
-// `Unavailable` from `Unreachable` -- and this was the fourth site reading the
-// wrong one.
+// The guard requiring this experiment's own stream to have been MEASURED
+// must count DECISIONS, not transport: Countable() excludes only khaos's own
+// failures, so a stream of timeouts would clear the floor and produce a hold
+// about a credential the target was never observed to judge.
func TestATimedOutForgedStreamIsNotEvidenceTheTargetDecided(t *testing.T) {
for _, disposition := range []probe.Disposition{
probe.Unreachable,
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go
index 258a2cfc..ddac4b58 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict.go
@@ -776,10 +776,8 @@ func requiredStreamThin(observation Observation) (string, bool) {
return "", false
}
- // Answered(), not Countable(): a timeout or an unreachable target is a
- // transport observation and not a decision about the credential, and
- // Countable() excludes only khaos's own failures. This is the same
- // discriminator that splits Unavailable from Unreachable.
+ // Answered(), not Countable(): a timeout is a transport observation and
+ // not a decision about the credential.
if decided := observation.Fault.Forged.Answered(); decided < MinimumPaired {
return sprintf(reasonThinForged, decided, MinimumPaired), true
}
@@ -1169,17 +1167,12 @@ func unanswered(
// transition declared on one lucky sample is how a flaky recovery reads as a
// clean one. An empty window is UNOBSERVED, never recovered.
//
-// The whole window is read, because this used to return the moment it found a
-// qualifying run: two healthy pairs followed by twenty broken ones was
-// RECOVERED, and a run whose last observed state was broken could exit 0.
-//
-// Recovery therefore needs two things -- it has to have been ESTABLISHED, and
-// it must not have collapsed for a sustained stretch afterwards. The same run
-// length governs both, because the reason a single healthy pair cannot declare
-// recovery is the reason a single failed one cannot withdraw it. A window of
-// fifteen pairs whose last sample happens to be a blip is still a recovery;
-// this verdict maps to the one exit code no --fail-on value can suppress, so
-// the cost of declaring it on noise lands on every later job.
+// Recovery needs two things: it has to have been ESTABLISHED, and it must
+// not have collapsed for a sustained stretch afterwards. The same run length
+// governs both, because the reason a single healthy pair cannot declare
+// recovery is the reason a single failed one cannot withdraw it -- and this
+// verdict maps to the one exit code no --fail-on value can suppress, so
+// declaring it on one noisy sample costs every later job on the runner.
func recoveryOf(recovery probe.Window, closed []probe.Disposition) Recovery {
if recovery.Paired() == 0 {
return Unobserved
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.go
index a6f88c3c..ade4d37b 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/experiment/verdict_test.go
@@ -547,15 +547,8 @@ func TestADeclaredClosureNeverHidesARefusal(t *testing.T) {
}
}
-// recoveryOf returned the moment it found its run of consecutive healthy pairs
-// and never looked at the rest of the window, so a recovery that collapsed
-// after two good samples was reported RECOVERED. A run whose last observed
-// state was broken could then exit 0.
-//
-// The criterion is now the END of the window rather than the first qualifying
-// run: recovery has to still be established when khaos stops looking. A late
-// recovery still counts, because a window that ends with a full healthy run
-// ends healthy however it started.
+// Recovery is judged over the WHOLE window: a run that collapses after two
+// good pairs is not recovered, and a late recovery still counts.
func TestRecoveryIsJudgedAtTheEndOfTheWindowNotTheFirstGoodRun(t *testing.T) {
healthy := func(n int) []probe.Disposition {
out := make([]probe.Disposition, n)
@@ -613,10 +606,8 @@ func TestRecoveryIsJudgedAtTheEndOfTheWindowNotTheFirstGoodRun(t *testing.T) {
},
want: Degraded,
},
- // The brittleness guard. A single trailing blip in a long healthy
- // window must NOT withdraw a recovery: this verdict maps to the one
- // exit code no --fail-on value can suppress, and declaring it on one
- // unlucky last sample makes every later job on that runner suspect.
+ // A single trailing blip must NOT withdraw a recovery: this verdict
+ // maps to the one exit code no --fail-on value can suppress.
"one trailing blip after a long healthy run": {
valid: append(healthy(12), probe.Unreachable),
want: Recovered,
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.go
index 3c74a1c9..98557856 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault.go
@@ -340,10 +340,7 @@ func (m envMutator) Revert(
original := strings.TrimSuffix(plan.Held, dockerx.HeldSuffix)
- // A cold start finds the replacement by NAME, because the original's name
- // is what it took and the id was never journaled until it existed. That
- // name is the ORIGINAL's, so it has to be resolved before anything
- // destructive happens to it -- see removeReplacement.
+ // A cold start has only the NAME, and that name is the original's.
replaced := plan.ReplacedID
if replaced == "" {
replaced = original
@@ -353,10 +350,8 @@ func (m envMutator) Revert(
failures = append(failures, err)
}
- // Already restored: the held name is gone and the original's name is the
- // original. A revert that completed and failed only to append REVERTED is
- // replayed from the journal, and replay must be a no-op rather than a
- // second attempt at a state that already holds.
+ // A revert that completed and failed only to append REVERTED is replayed,
+ // and replay has to be a no-op rather than a second attempt.
if restored, err := m.alreadyRestored(
ctx,
env,
@@ -418,18 +413,10 @@ func ValidEnvKind(kind EnvKind) error {
func (envMutator) Prefix() string { return KindEnvPrefix }
// removeReplacement deletes the container khaos created, and NOTHING else.
-//
-// The name it is given is the original's own name whenever ReplacedID was
-// never journaled, which is every cold start: ReplacedID is written to the
-// in-memory plan after Recreate and the journal payload is never updated. So
-// a Remove on that name took the operator's container -- with its anonymous
-// volume and every log line -- in two reachable states: khaos dying between
-// the PENDING record and the rename, and a replay after a revert that already
-// succeeded. OriginalID was in the payload the whole time.
-//
-// The id is resolved first and the removal is addressed to the ID, not the
-// name, because the name can move between the two calls and this tier moves
-// names on purpose.
+// On a cold start the only handle is a NAME, and that name is the original's
+// own, so the id behind it decides: it is resolved first, compared against
+// OriginalID, and the removal is addressed to the id rather than the name,
+// which can move between the two calls.
func (m envMutator) removeReplacement(
ctx context.Context,
env Env,
@@ -444,8 +431,6 @@ func (m envMutator) removeReplacement(
case err != nil:
return err
case id == plan.OriginalID:
- // That name is the ORIGINAL. Nothing to remove, and removing it is
- // the one thing this tier must never do.
return nil
}
@@ -458,8 +443,7 @@ func (m envMutator) removeReplacement(
}
// alreadyRestored reports that the original is back under its own name, by
-// IDENTITY rather than by the name being taken: a replacement still holding
-// that name would otherwise read as a completed revert.
+// IDENTITY: a replacement still holding that name reads the same otherwise.
func (m envMutator) alreadyRestored(
ctx context.Context,
env Env,
@@ -471,8 +455,6 @@ func (m envMutator) alreadyRestored(
}
if _, err := env.Docker.Identify(ctx, plan.Held); err == nil {
- // The original is still aside under its held name, so the revert has
- // work to do.
return false, nil
} else if !errors.Is(err, dockerx.ErrContainerGone) {
return false, err
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.go
index b26af887..83a1667c 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/inject/envfault_recovery_test.go
@@ -67,20 +67,10 @@ func alive(name string) bool {
// THE one outcome this tier must never produce: khaos destroying the
// operator's own container.
//
-// The revert removed the replacement by NAME, derived as Held minus the held
-// suffix -- which is the ORIGINAL's name. On a cold start ReplacedID is empty
-// because it is only ever written to the in-memory plan, never to the
-// journal, so that name is all the revert had. It is the original's name
-// whenever khaos died in either of two windows:
-//
-// - after the journal recorded PENDING and before the rename, so the
-// original is still sitting under its own name, or
-// - after a revert already succeeded and only the final journal append
-// failed, so the restored original is under its own name again.
-//
-// In both, a Remove(Force) took the operator's container, its anonymous
-// volume and every log line with it. OriginalID was in the payload the whole
-// time and the revert never read it.
+// On a cold start the revert has only a NAME to find the replacement by, and
+// that name is the original's. It resolves to the original in two windows:
+// khaos dying after the PENDING record and before the rename, and a replay
+// after a revert that already succeeded.
func TestARevertNeverRemovesTheOriginalContainer(t *testing.T) {
client := dockerOrSkip(t)
defer func() { _ = client.Close() }()
@@ -141,11 +131,9 @@ func TestARevertNeverRemovesTheOriginalContainer(t *testing.T) {
}
}
-// The NEGATIVE CONTROL on the guard above. A removeReplacement that simply
-// never removed anything would satisfy every assertion in that test, so this
-// one drives the state the fault actually produces -- the original renamed
-// aside, a replacement holding its name -- and requires the revert to remove
-// the replacement and put the original back.
+// The NEGATIVE CONTROL: a removeReplacement that never removed anything
+// would satisfy the test above, so this drives the state the fault really
+// produces and requires the replacement to go and the original to come back.
func TestARevertStillRemovesAGenuineReplacement(t *testing.T) {
client := dockerOrSkip(t)
defer func() { _ = client.Close() }()
@@ -154,8 +142,8 @@ func TestARevertStillRemovesAGenuineReplacement(t *testing.T) {
originalID := seedOriginal(t, fixtureName)
- // The fault's own sequence: the original goes aside under the held name,
- // and a DIFFERENT container takes the name it vacated.
+ // The fault's own sequence: original aside, a different container on the
+ // name it vacated.
if err := exec.Command("docker", "rename", fixtureName, held).
Run(); err != nil {
t.Skipf("could not rename the fixture aside: %v", err)
@@ -174,9 +162,8 @@ func TestARevertStillRemovesAGenuineReplacement(t *testing.T) {
Variable: "A_SECRET",
Held: held,
OriginalID: originalID,
- // Deliberately empty: this is the cold-start shape, where the revert
- // has only the name to go on. That is the dangerous path, so it is
- // the one the control exercises.
+ // ReplacedID deliberately empty: the cold-start shape, which is the
+ // dangerous path.
})
if err != nil {
t.Fatalf("marshal: %v", err)
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.go
index fceb86d1..93794a00 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record.go
@@ -197,15 +197,9 @@ type Phase struct {
}
// Phases is the ONE enumeration of the measured windows, in the order the
-// engine measures them. The aggregate serializer and the raw-event serializer
-// each used to carry their own list and each listed four of the five: `shift`,
-// the second fault window the authorization tier needs and the verdict reads
-// at three sites, was in neither. A defect established from it was written to
-// a record that did not contain the observations establishing it, with an
-// events hash and count that were internally consistent about the wrong set.
-//
-// Both serializers read this, so a phase added to the engine cannot go missing
-// from one of them.
+// engine measures them. Both serializers read it, so a phase added to the
+// engine cannot go missing from one of them and leave a verdict resting on
+// observations the record does not carry.
func Phases(observation experiment.Observation) []Phase {
return []Phase{
{"baseline", observation.Baseline},
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.go
index 97c4c2c1..d0b91ea4 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/record/record_test.go
@@ -64,11 +64,9 @@ func finished() experiment.Result {
Baseline: window(0, probe.Rejected),
Fault: window(10*time.Second, probe.Accepted),
- // Shift and Resumed are the two windows this fixture used to
- // claim it carried and did not. Both are real measured phases --
- // shift is the second fault window the authorization tier needs,
- // and resumed is what the idleness discriminator reads -- and
- // leaving them empty is why a serializer that dropped one passed.
+ // Shift is the authorization tier's second fault window and
+ // Resumed is what the idleness discriminator reads. A fixture
+ // missing either lets a serializer drop it unnoticed.
Shift: window(15*time.Second, probe.Accepted),
Shifted: true,
Resumed: window(18*time.Second, probe.Rejected),
@@ -225,9 +223,8 @@ func TestEveryObservationReachesTheEventsFile(t *testing.T) {
// two requests. Counting pairs here would have asserted half the
// observations reached the file and called that complete.
//
- // Summed over Phases rather than over a list written here, because a
- // hardcoded list of three windows is what let the shift window go
- // unnoticed in both serializers.
+ // Summed over Phases rather than a list written here, so a new phase
+ // cannot go uncounted.
want := 0
for _, phase := range Phases(result.Observation) {
want += phase.Window.Requests()
@@ -531,13 +528,9 @@ var errNoInode = errors.New(
"this platform does not expose an inode, so the rename cannot be distinguished from a truncation here",
)
-// The record is canonical and every other output is a projection of it, so a
-// window the VERDICT reads must survive serialization. The shift window did
-// not: both the aggregate and the raw-event serializers enumerated their
-// phases separately and both listed four of the five, so a defect established
-// from the second fault window was saved without the observations that
-// established it -- with an events hash and count that were internally
-// consistent about the wrong set.
+// Every window the VERDICT reads has to survive serialization, or a defect
+// is saved without the observations that established it -- with an events
+// hash and count internally consistent about the wrong set.
func TestEveryMeasuredPhaseSurvivesTheRecord(t *testing.T) {
result := finished()
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.go
index 026ddf72..8d2f53c9 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile.go
@@ -205,8 +205,7 @@ func (m Mutation) Apply() error {
//
// The backup is PUBLISHED atomically, so its existence means it is complete.
// Restore cannot tell a truncated backup from a genuinely short secret by
-// looking at it, and a 5-byte secret is a legitimate secret, so the guarantee
-// has to be structural rather than validated.
+// looking at it, so the guarantee is structural rather than validated.
func (m Mutation) hold(info os.FileInfo) error {
if err := publishCopy(m.Path, m.Aside, info.Mode()); err != nil {
return err
@@ -269,10 +268,9 @@ func (m Mutation) Restore() error {
return os.Remove(m.Aside)
}
-// publishCopy writes the copy to a temporary file in the destination's own
-// directory, flushes it, and renames it into place. A failed copy leaves
-// NOTHING at the destination, which is what lets a later Restore treat the
-// backup's existence as proof that the whole original is in it.
+// publishCopy writes to a temporary file in the destination's own directory,
+// flushes it, and renames it into place, so a failed copy leaves NOTHING a
+// later Restore could mistake for a complete original.
//
// Same directory because rename is only atomic within a filesystem, and the
// flush before it because a rename that beats the data to disk publishes a
@@ -332,11 +330,9 @@ func publishCopy(from, to string, mode os.FileMode) error {
return nil
}
-// copyInto overwrites the destination IN PLACE, keeping its inode. The secret
-// is restored this way rather than by rename because the whole reason this
-// tier runs in a helper container is that unlink-and-recreate is invisible to
-// a target holding the file open, and a restore that swapped the inode would
-// leave that target reading the fault forever.
+// copyInto overwrites the destination IN PLACE, keeping its inode. A rename
+// here would swap the inode, and a target holding the file open would read
+// the fault forever.
func copyInto(from, to string, mode os.FileMode) error {
//nolint:gosec // the path is the fault's subject, guarded by the nonce
source, err := os.Open(from)
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.go b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.go
index d3618268..20496549 100644
--- a/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.go
+++ b/PROJECTS/intermediate/chaos-engineering-tool/internal/secretfile/secretfile_test.go
@@ -347,18 +347,9 @@ func TestVerifyRefusesAMalformedCredential(t *testing.T) {
// The one outcome this package must never produce: khaos destroying the secret
// it was asked to preserve.
//
-// The backup used to be written at its FINAL path, so a copy that failed
-// partway left a short file where a complete original was expected, and a read
-// error left a zero-byte one. Restore read existence as proof of a complete
-// original, opened the untouched secret with O_TRUNC, and copied the stub over
-// it. A short write or a full filesystem was enough, and truncating the
-// original could itself free the space that let the destructive restore finish
-// and report success.
-//
// Restore cannot tell a truncated backup from a genuinely short secret by
-// looking at it -- a 5-byte secret is a legitimate secret -- so the fix is
-// structural: the backup is published atomically, and a failed hold leaves
-// nothing behind for Restore to trust.
+// looking at it, so the guarantee is structural: the backup is published
+// atomically, and a failed hold leaves nothing behind to trust.
func TestAFailedHoldLeavesTheOriginalIntactAndUnrestorable(t *testing.T) {
path, aside := seeded(t)
diff --git a/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.sh b/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.sh
index 87362b58..7d4c9067 100755
--- a/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.sh
+++ b/PROJECTS/intermediate/chaos-engineering-tool/scripts/report.sh
@@ -303,22 +303,12 @@ echo "== the codes this gate cannot reach, named rather than implied =="
# 9 UNSUPPORTED driven by scripts/dns.sh and scripts/tls.sh, against the
# targets whose question genuinely does not apply.
# 70 INTERNAL a recovered panic, recovered at the process boundary in
-# cmd/khaos. This comment used to say there was "nothing
-# honest to assert" about it, which was itself the dishonest
-# part: no production path returned the code at all, and no
-# recover() existed anywhere, so the gate described a
-# mechanism khaos did not have. It is driven by a unit test
-# that panics through the real boundary and asserts both the
-# code and that deferred reverts still ran.
+# cmd/khaos and driven by a unit test that panics through
+# it, asserting the code AND that deferred reverts ran.
#
-# A CENSUS rather than a comment. The paragraph above was an unconditional
-# `pass`, which is documentation wearing an assertion's clothes: it could not
-# fail, so it could not notice a thirteenth code arriving with nothing
-# covering it. This counts the taxonomy in the source and holds it to the
-# number this gate and the unit census between them account for.
-# [[:space:]] rather than \t: grep -E treats a backslash-t as a literal
-# `t`, so the tab form matched nothing and this census reported 0 under
-# bash while appearing to work when the same line was pasted into zsh.
+# A CENSUS rather than a comment, so a thirteenth code cannot arrive with
+# nothing covering it. [[:space:]] rather than \t, which grep -E reads as a
+# literal `t`.
declared="$(grep -cE '^[[:space:]]+Code[A-Za-z]+ += ' internal/cli/exit.go || true)"
if [[ "$declared" == 12 ]]; then
@@ -335,10 +325,8 @@ else
fail "the unit census is gone, so the codes this gate cannot drive are unverified"
fi
-# A code with no producer is a published contract khaos does not honour, which
-# is what 70 was: declared, counted by the census above, asserted by number,
-# and returned from nowhere. The census cannot see that, because counting
-# constants proves declaration and never reachability.
+# Counting constants proves DECLARATION and never REACHABILITY, so the code
+# needs a producer too.
if grep -q 'code = cli.CodeInternal' cmd/khaos/main.go &&
grep -q 'func TestAPanicBecomesTheInternalCodeWithCleanupIntact' cmd/khaos/main_test.go; then
pass "the internal code has a producer and a test that panics through it"
@@ -346,8 +334,7 @@ else
fail "exit 70 is declared with no production path, so the taxonomy publishes a code khaos never returns"
fi
-# The refusal that used to be a panic: a non-positive interval reached
-# time.NewTicker AFTER the workspace lock was taken.
+# A non-positive interval reaches time.NewTicker, after the workspace lock.
if ! out="$("$BIN" reap --interval 0 --no-color 2>&1)"; then
if grep -q "longer than zero" <<<"$out"; then
pass "a non-positive reap interval is refused by name instead of panicking"