diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/heads_test.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/heads_test.go index 714052180..314ae747e 100644 --- a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/heads_test.go +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/heads_test.go @@ -3,6 +3,7 @@ package main import ( "context" "encoding/json" + "errors" "os" "strings" "testing" @@ -115,6 +116,41 @@ func TestAHeadNoMergeCallDeliveredIsAnUntakenHead(t *testing.T) { t.Fatalf("after the merge call: held %+v, findings %+v", heads, fw.held) } }) + // GATE-7 (§742): gate_heads reads each held head with since and finding; gate_head_take writes one revision of its own + // call, opens its record marked by hand, writes the hand-act log first and clears the finding. + t.Run("gate_heads reads the held heads; gate_head_take takes one in after the log and clears head-untaken", func(t *testing.T) { + h, heads, fw, now := setup() + h.Records = &Records{Ledger: newLedgerFake(t), Now: h.Now} + if err := h.HeadMoved(moved(c2)); err != nil { + t.Fatal(err) + } + *now = at.Add(DefaultUntakenBound) + h.React() + out, err := h.HeadsHeld() + lines, _ := out["heads"].([]HeadLine) + if err != nil || len(lines) != 1 || lines[0].Repository != "novox/app" || lines[0].Branch != "main" || lines[0].Head != c2 || + !strings.Contains(lines[0].Finding, WordsUntaken) || lines[0].Since == "" { + t.Fatalf("gate_heads %+v %v", out, err) + } + acts := &handActsFake{refuse: errors.New("log down")} + if _, err := h.HeadTake("novox/app", "main", "pushed by hand", "lead@shanks", acts); err == nil || len(heads) != 1 { + t.Fatalf("taken without the log: %v", err) + } + acts.refuse = nil + if _, err := h.HeadTake("novox/other", "main", "x", "lead@shanks", acts); err == nil { + t.Fatal("a head the gate does not hold is taken") + } + got, err := h.HeadTake("novox/app", "main", "pushed by hand", "lead@shanks", acts) + if err != nil || got["source"] != int64(5) || len(acts.took) != 1 || acts.took[0].Cause != "gate_head_take" { + t.Fatalf("take %+v %v, log %+v", got, err, acts.took) + } + src, _, _ := h.Source.Read("main") + kept, _ := h.Records.Kept() + if src.Heads["novox/app"] != c2 || len(heads) != 0 || len(fw.held) != 0 || len(kept) != 1 || kept[0].Trace == nil || + !kept[0].Trace.Hand || kept[0].Trace.By != "lead@shanks" || kept[0].Heads["novox/app@222222222222"] != c2 { + t.Fatalf("source %+v, held %+v, findings %+v, records %+v", src, heads, fw.held, kept) + } + }) t.Run("the setting untaken-bound, at least one minute", func(t *testing.T) { h, _, _, _ := setup() n := 3 diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/headtools.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/headtools.go new file mode 100644 index 000000000..9af28caae --- /dev/null +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/headtools.go @@ -0,0 +1,119 @@ +package main + +// Taking an untaken head in by hand (design 47 H §742; ADR 0682 §3; H-A-24, H-A-48): gate_heads reads the state heads with +// each head's since and finding; gate_head_take, with repository, branch and why, written in the hand-act log first, names +// that head a source revision as a merge call does (§737), its call one of its own and its trace marked by hand with who and +// when, its record's member `@`, and the chain follows. Nothing else delivers an untaken head. + +import ( + "errors" + "fmt" + "sort" + "strings" + + "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient" + seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery" + stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/keys" +) + +// HeadLine is one held head as gate_heads reads it. +type HeadLine struct { + Repository string `json:"repository"` + Branch string `json:"branch"` + Head string `json:"head"` + Since string `json:"since"` + // Finding is head-untaken's summary when it is raised. + Finding string `json:"finding,omitempty"` +} + +// HeadsHeld is gate_heads: every held head, ordered by key. +func (h *Holder) HeadsHeld() (map[string]any, error) { + if h.Heads == nil { + return nil, errors.New("this gate watches no heads") + } + held, err := h.Heads.All() + if err != nil { + return nil, err + } + raised := map[string]string{} + if h.Findings != nil { + for _, f := range h.Findings.Held() { + if f.Scope == FindingScope && f.Kind == HeadUntaken { + raised[f.ID] = f.Summary + } + } + } + lines := []HeadLine{} + for key, v := range held { + repository, escaped, ok := seat.ParseHeadsByRepositoryBranchKey(key) + branch, err := keys.UnescapeName(escaped) + if !ok || err != nil { + continue + } + lines = append(lines, HeadLine{Repository: repository, Branch: branch, Head: v.Head, Since: timeText(&v.Since), Finding: raised[key]}) + } + sort.Slice(lines, func(i, j int) bool { return headKey(lines[i].Repository, lines[i].Branch) < headKey(lines[j].Repository, lines[j].Branch) }) + return map[string]any{"heads": lines}, nil +} + +// HeadTake is gate_head_take: the held head of a repository on a branch named one source revision, after the hand-act log took it. +func (h *Holder) HeadTake(repository, branch, why, by string, acts handActs) (map[string]any, error) { + if strings.TrimSpace(repository) == "" || strings.TrimSpace(branch) == "" || strings.TrimSpace(why) == "" { + return nil, errors.New("say the repository, the branch and why its head is taken in by hand") + } + if h.Heads == nil || h.Source == nil { + return nil, errors.New("this gate watches no heads or keeps no source") + } + held, err := h.Heads.Get(headKey(repository, branch)) + if err != nil { + return nil, err + } + if held == nil { + return nil, fmt.Errorf("the gate holds no untaken head of %s on %s: gate_heads lists them", repository, branch) + } + if acts == nil { + return nil, errors.New("the hand-act log cannot be reached here, so nothing was taken in") + } + at := h.Now().UTC() + if _, err := acts.Record(meshhandactsclient.Request{What: fmt.Sprintf("took the head %s of %s on %s in by hand (hand by %s at %s)", + shortOf(held.Head, 12), repository, branch, by, at.Format("2006-01-02T15:04:05Z")), Why: why, Cause: "gate_head_take", + Verb: "head-take"}); err != nil { + return nil, fmt.Errorf("the hand act was not recorded through mesh-hand-acts, so nothing was taken in: %w", err) + } + call, err := newCall() + if err != nil { + return nil, err + } + member := IDOf(repository, held.Head) + trace := RecordTrace{Call: call, By: by, Hand: true, At: at, Pulls: []string{member}, Commits: []string{held.Head}} + if err := h.deliverRevision(branch, call, []revisionHead{{Repository: repository, Commit: held.Head}}, + map[string]string{member: held.Head}, trace); err != nil { + return nil, err + } + named, _, err := h.Source.Read(branch) + if err != nil || named == nil { + return nil, fmt.Errorf("the head is taken in and source.%s cannot be read back: %v", branch, err) + } + return map[string]any{"repository": repository, "branch": branch, "head": held.Head, "source": named.Source, "call": call, "by": by}, nil +} + +// headTools are the watchdog's tools; acts is the hand-act log. +func headTools(h *Holder, acts handActs) []stdio.Tool { + return []stdio.Tool{ + {Name: "gate_heads", + Description: "Every watched branch's head the gate holds as untaken (design 47 H §740, §742): moved, and named by no source " + + "revision yet, each with its repository, branch, head, since when, and head-untaken's summary once raised. Read, never written.", + Run: func(map[string]any) (any, error) { return h.HeadsHeld() }}, + {Name: "gate_head_take", + Description: "Take one untaken head in by hand (design 47 H §742): the head the gate holds for the repository on the branch is " + + "named one source revision as a merge call does, with its record, and the chain follows; recorded in the hand-act log of " + + "the seat mesh-hand-acts first. Nothing else delivers a head moved outside the mesh.", + Input: map[string]any{"type": "object", "properties": map[string]any{"repository": str("owner/repository"), + "branch": str("the watched branch"), "why": str("why it is taken in by hand, in plain words")}, + "required": []string{"repository", "branch", "why"}}, + Run: func(a map[string]any) (any, error) { + return h.HeadTake(strArg(a, "repository"), strArg(a, "branch"), strArg(a, "why"), stdio.CallerOf(a), acts) + }}, + } +} diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go index ed8d1c7cb..62f8c4d8b 100644 --- a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go @@ -249,6 +249,7 @@ func tools(h *Holder, l *listening) []stdio.Tool { } list = append(list, recordTools(h, meshhandactsclient.Recorder{Ask: stdio.Ask})...) list = append(list, sourceTools(h, meshhandactsclient.Recorder{Ask: stdio.Ask})...) + list = append(list, headTools(h, meshhandactsclient.Recorder{Ask: stdio.Ask})...) // A verb that changes a delivery asks for a look at what it makes possible (react.go). for i := range list { run := list[i].Run diff --git a/modules/mesh-delivery-gate/module.json b/modules/mesh-delivery-gate/module.json index 694495e92..0351d0b12 100644 --- a/modules/mesh-delivery-gate/module.json +++ b/modules/mesh-delivery-gate/module.json @@ -306,6 +306,8 @@ "tools": [ "delivery_status", "gate_consumer", + "gate_head_take", + "gate_heads", "gate_record", "gate_record_end", "gate_record_repair",