Node-engine: a hold of the composition carries its wait, step compose (A-453)

A module not composed for want of its entry (entry-asked, entry-missing) and a want
whose parts differ write their have with a Wait of step compose and that reason, as
the kept data's holds do; the hold for a failed backup carries none.

Builds: design 47 G A-453 (ADR 0539 §16, §541)
This commit is contained in:
2026-11-17 00:39:39 +01:00
parent 72385fd84a
commit 1b9f9355b5
3 changed files with 32 additions and 8 deletions
+11 -2
View File
@@ -660,13 +660,16 @@ func (a *Agent) NotComposedEach(ctx context.Context, why string, held map[string
a.notComposed[module] = mark
a.mu.Unlock()
phase, detail := string(nodeengineclient.PhaseFailed), NotComposedDetail+why
var wait *nodeengine.Wait
if heldForEntry(why) {
// The entry its want names is not held: the phase held, its detail opening entry-asked: or entry-missing: and
// naming the fingerprint (design 47 G section 421).
phase, detail = string(nodeengineclient.PhaseHeld), why
// The hold says what it waits on, as every hold but a failed backup does (design 47 G A-453, section 541).
wait = a.composeWait(strings.TrimSuffix(heldReason(why), ":"), why)
}
a.writeHave(ctx, Have{Module: module, FP: mark.prior.FP, Composed: mark.prior.Composed, Sealed: mark.prior.Sealed,
Phase: phase, Detail: detail})
Phase: phase, Detail: detail, Wait: wait})
}
}
@@ -678,6 +681,12 @@ func (a *Agent) NotComposedEach(ctx context.Context, why string, held map[string
// module since its start: held by a failed backup, waiting for a yes, not composed) keeps what the module's last have
// said runs, its fingerprint, digest and sealed values, rather than a have naming nothing: what runs is not lost, and
// the boxes the composer reuses after a restart stay (review of L2, rounds 2 and 3).
// composeWait is the wait a hold of the composition carries in its have: step compose, with its reason and its words (design 47 G
// A-453, section 541). Only a hold for a failed backup carries none.
func (a *Agent) composeWait(reason, words string) *nodeengine.Wait {
return &nodeengine.Wait{Owner: nodeengine.Seat, Step: nodeengine.WaitStepCompose, Reason: reason, Since: a.now(), Words: words}
}
func (a *Agent) writeHave(ctx context.Context, h Have) {
if h.Module != NodeModule {
a.mu.Lock()
@@ -1634,7 +1643,7 @@ func (a *Agent) apply(ctx context.Context, module string, w wantNow, comp compNo
}
a.env.Say(fmt.Sprintf("%s is held: %s", module, words))
a.writeHave(ctx, Have{Module: module, FP: prev.Fp, Composed: prev.Composed, Phase: string(nodeengineclient.PhaseHeld),
Detail: words})
Detail: words, Wait: a.composeWait("parts-differ", words)})
return
}
+13 -6
View File
@@ -357,8 +357,9 @@ func TestAWantAndItsCompositionApplyTheModuleAndTheHaveNamesBoth(t *testing.T) {
if got := len(b.appliedList()) - before; (got == 1) != row.applies {
t.Fatalf("parts %q: applied %d times, want applies=%v", row.name, got, row.applies)
}
if h := b.haves.last("web"); !row.applies && (h.Phase != string(nodeengineclient.PhaseHeld) || h.Detail != row.detail) {
t.Fatalf("parts %q: the have is %s %q, want held %q", row.name, h.Phase, h.Detail, row.detail)
if h := b.haves.last("web"); !row.applies && (h.Phase != string(nodeengineclient.PhaseHeld) || h.Detail != row.detail ||
h.Wait == nil || h.Wait.Step != nodeengine.WaitStepCompose || h.Wait.Reason != "parts-differ" || h.Wait.Words != row.detail) {
t.Fatalf("parts %q: the have is %s %q wait %+v, want held %q waiting on parts-differ (A-453)", row.name, h.Phase, h.Detail, h.Wait, row.detail)
}
}
// A container's digest is the one after its image's @.
@@ -754,7 +755,8 @@ func TestADataModuleIsBackedUpFirstAndHeldWhenItFails(t *testing.T) {
})
eventually(t, "the have does not say held", func() bool {
h := b.haves.last("db")
return h.Phase == string(nodeengineclient.PhaseHeld) && strings.Contains(h.Detail, "repository is locked") && h.FP == fp1
// A hold for a failed backup carries no wait: the operator is asked about it (A-453).
return h.Phase == string(nodeengineclient.PhaseHeld) && strings.Contains(h.Detail, "repository is locked") && h.FP == fp1 && h.Wait == nil
})
if got := b.appliedList(); len(got) != 0 {
t.Fatalf("something was applied behind a failed backup: %v", got)
@@ -1784,9 +1786,14 @@ func TestTheNodesOwnCompositionIsAppliedWhenItDiffersAndARecordMoveWaitsForAYes(
}
// Design 47 G §421: a module whose want's entry the catalog half holds none of is the phase held, its detail opening
// entry-missing: and naming the fingerprint; composed again, its have is what it runs.
b.ag.NotComposedEach(context.Background(), "", map[string]string{"idle": EntryMissing + " the catalog half holds no entry of the build src2:x"})
if h := b.haves.last("idle"); h.Phase != string(nodeengineclient.PhaseHeld) || h.Composed != idleDig || h.Detail != EntryMissing+" the catalog half holds no entry of the build src2:x" {
t.Errorf("idle's have while its entry is missing: %+v", h)
// A-453: the hold carries its wait, step compose with the reason, as every hold but a failed backup does.
for _, row := range []struct{ opening, reason string }{{EntryMissing, "entry-missing"}, {EntryAsked, "entry-asked"}} {
words := row.opening + " the catalog half holds no entry of the build src2:x"
b.ag.NotComposedEach(context.Background(), "", map[string]string{"idle": words})
if h := b.haves.last("idle"); h.Phase != string(nodeengineclient.PhaseHeld) || h.Composed != idleDig || h.Detail != words ||
h.Wait == nil || h.Wait.Step != nodeengine.WaitStepCompose || h.Wait.Reason != row.reason || h.Wait.Words != words || h.Wait.Since.IsZero() {
t.Errorf("idle's have while its entry is %s: %+v", row.reason, h)
}
}
b.ag.NotComposedEach(context.Background(), "", nil)
if h := b.haves.last("idle"); h.Phase != string(nodeengineclient.PhaseRunning) || h.Composed != idleDig {
+8
View File
@@ -31,6 +31,14 @@ func judgedAgain(why string) bool {
}
// heldForEntry says whether why is a hold for the entry a want names.
// heldReason is the opening of a detail held for an entry: EntryAsked or EntryMissing.
func heldReason(why string) string {
if strings.HasPrefix(why, EntryAsked) {
return EntryAsked
}
return EntryMissing
}
func heldForEntry(why string) bool {
return strings.HasPrefix(why, EntryAsked) || strings.HasPrefix(why, EntryMissing)
}