Files
mesh-delivery/modules/mesh-delivery-indexer/internal/index/runs_tools.go
T
jschoubben c2950e332f A-194: indexer_runs reads the state runs and the run candidates, indexer_run_drop drops one by hand
The drop is a hand act recorded through mesh-hand-acts before it is asked; the indexer, the state's owner, drops the
run's candidate and its key.

Builds: design 47 G §64; A-194

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 05:57:11 +01:00

180 lines
7.3 KiB
Go

package index
// The tools of the state runs and the run candidates (design 47 G §64; A-174, A-194): indexer_runs reads every run the indexer
// holds a candidate for, and indexer_run_drop drops one by hand, its hand act written first.
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
)
const (
// RunsTool reads the runs; RunDropTool drops one by hand.
RunsTool = "indexer_runs"
RunDropTool = "indexer_run_drop"
)
// RunRead is one run of the state runs as indexer_runs lists it.
type RunRead struct {
// Run is the run's id as the runner says it, Group the candidate's group and the key of the state (run-<id>).
Run string `json:"run"`
Group string `json:"group"`
Members []meshpipelinerunner.Member `json:"members,omitempty"`
// Ended are the modules whose pipeline of the run has ended, Waiting the members whose has not.
Ended []string `json:"ended,omitempty"`
Waiting []string `json:"waiting,omitempty"`
At time.Time `json:"at"`
// Candidate says the run's candidate is in the state candidates.
Candidate bool `json:"candidate"`
}
// RunsRead is the answer of indexer_runs: the runs the state holds, and the run candidates no run of the state holds.
type RunsRead struct {
Runs []RunRead `json:"runs"`
// Orphans are the groups of the candidates that are a run's (run-<id>) while the state runs holds no such run.
Orphans []string `json:"orphans,omitempty"`
}
// ReadRuns reads the state runs and the run candidates of the state candidates; neither is written.
func ReadRuns(ctx context.Context, runs, candidates Store) (RunsRead, error) {
out := RunsRead{Runs: []RunRead{}}
if runs == nil {
return out, fmt.Errorf("the state %s is not bound", RunsState)
}
held := map[string]bool{} // the candidates' keys
if candidates != nil {
ks, err := candidates.Keys(ctx)
if err != nil {
return out, fmt.Errorf("listing %s: %w", CandidatesState, err)
}
for _, k := range ks {
held[k] = true
}
}
names, err := runs.Keys(ctx)
if err != nil {
return out, fmt.Errorf("listing %s: %w", RunsState, err)
}
slices.Sort(names)
known := map[string]bool{}
for _, name := range names {
value, _, found, err := runs.Get(ctx, name)
if err != nil {
return out, fmt.Errorf("%s.%s: %w", RunsState, name, err)
}
var r Run
if !found || json.Unmarshal(value, &r) != nil {
continue
}
key, _ := meshcatalogclient.CandidatesKey(name)
known[key] = true
read := RunRead{Run: r.Run, Group: name, Members: r.Members, Ended: r.Ended, At: r.At, Candidate: held[key]}
for _, m := range r.Members {
if !slices.Contains(r.Ended, m.Module) {
read.Waiting = append(read.Waiting, m.Module)
}
}
out.Runs = append(out.Runs, read)
}
for k := range held {
if group, err := meshcatalogclient.ParseCandidatesKey(k); err == nil && strings.HasPrefix(group, "run-") && !known[k] {
out.Orphans = append(out.Orphans, group)
}
}
slices.Sort(out.Orphans)
return out, nil
}
// runGroupOf is the group of a run the tool names: the runner's id, or run-<id> as indexer_runs lists it.
func runGroupOf(run string) (string, error) {
return RunGroup(strings.TrimPrefix(strings.TrimSpace(run), "run-"))
}
// DropRunByHand is indexer_run_drop answered: the run's candidate and its key in the state runs are removed, as they are when
// every member's pipeline has ended. A run no state or candidate holds drops nothing.
func (ix *Indexer) DropRunByHand(ctx context.Context, run, by, why string) TakenIn {
r := TakenIn{Module: "run " + run}
group, err := runGroupOf(run)
if err != nil {
r.Answer = err.Error() + ": nothing dropped"
return r
}
if ix.Runs == nil {
r.Answer = "the indexer keeps no state " + RunsState + ": nothing dropped"
return r
}
ix.runMu.Lock()
defer ix.runMu.Unlock()
read, err := ReadRuns(ctx, ix.Runs, ix.Store)
if err != nil {
r.Answer = "the runs are not read: " + err.Error()
return r
}
if !slices.ContainsFunc(read.Runs, func(x RunRead) bool { return x.Group == group }) && !slices.Contains(read.Orphans, group) {
r.Answer = "no run " + group + " is held by the state " + RunsState + " or the candidates: nothing dropped"
return r
}
if err := ix.dropRun(ctx, group); err != nil {
r.Answer = group + " could not be dropped: " + err.Error()
ix.logf("%s", r.Answer)
return r
}
r.Stored = true
r.Answer = fmt.Sprintf("the run %s and its candidate are dropped by %s (%s)", group, by, why)
ix.logf("%s", r.Answer)
return r
}
// RunsTools are indexer_runs and indexer_run_drop (class act): the tools bundle reads the states and writes an ask in takeins,
// and the indexer, the state's owner, drops the run; record says the hand act in the hand-act log before it is asked.
func RunsTools(runs, candidates Store, ask func(key string, value []byte) (TakeInAsk, error), now func() time.Time, record func(what, why string) error) []stdio.Tool {
return []stdio.Tool{
{Name: RunsTool,
Description: "Every run on request the indexer holds a candidate for, from its state runs (design 47 G §64, A-174): the run's id and " +
"group, its members (module, commit, branch), the modules whose pipeline of the run has ended and those still waiting, " +
"when it was last written, and whether its candidate is in the state candidates; and the run candidates no run of the state " +
"holds (orphans). indexer_run_drop drops one.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) {
return ReadRuns(context.Background(), runs, candidates)
}},
{Name: RunDropTool,
Description: "Drop one run on request of the indexer: its candidate and its key in the state runs, as the end of its last member's " +
"pipeline does (design 47 G §64, A-194), for a run whose pipelines never end. A hand act, recorded through mesh-hand-acts " +
"before it is asked. indexer_runs names the runs.",
Input: map[string]any{"type": "object", "required": []string{"run", "why"}, "properties": map[string]any{
"run": map[string]any{"type": "string", "description": "the run's id, or its group run-<id>, as indexer_runs names it"},
"why": map[string]any{"type": "string", "description": "why it is dropped, in plain words"}}},
Run: func(args map[string]any) (any, error) {
str := func(k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) }
run, why := str("run"), str("why")
group, err := runGroupOf(run)
if err != nil || why == "" {
return nil, errors.New("name the run as indexer_runs names it (run) and say why (why): a drop is a hand act, recorded through mesh-hand-acts")
}
data, err := json.Marshal(TakeInAsk{V: 1, RunDrop: group, Why: why, By: stdio.CallerOf(args), At: now().UTC()})
if err != nil {
return nil, err
}
if err := record("dropped the run "+group+" and its candidate by hand", why); err != nil {
return nil, fmt.Errorf("the hand act was not recorded through mesh-hand-acts, so nothing was dropped: %w", err)
}
a, err := ask("run-drop."+keys.EscapeName(group), data)
if err != nil {
return nil, err
}
return a.Result, nil
}},
}
}