H-A-487: a module's builds are read without every key's history

builder_build read every key's whole history to learn when its entry was
written, one more round trip per key of the module; on nats's hundreds of keys
the read crawled. Each entry's own write time now comes with the key's read,
the history is read only for the one key a fingerprint names when its entry
says no time, and a listing cut at the 20 newest says so in its note.

Builds: design 47 H2 H-A-487
This commit is contained in:
2026-11-22 19:30:59 +01:00
parent 564fd5e0bb
commit db899d8ad4
4 changed files with 57 additions and 7 deletions
@@ -5,9 +5,12 @@ import (
"errors"
"strings"
"testing"
"time"
"mesh-delivery-builder/internal/build"
stdio "git.novox.be/novox/mesh-sdk/go"
"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/meshcatalog"
)
@@ -54,3 +57,14 @@ func TestABuildSeatsStepsAreReadInItsHoldersState(t *testing.T) {
t.Errorf("a seat with no holder reads %v; want an error naming it", err)
}
}
// H-A-487: a build key's time is its entry's own write time, read with the key and no history.
func TestABuildKeysTimeIsItsEntrysOwnWriteTime(t *testing.T) {
at := time.Date(2026, 11, 22, 20, 45, 0, 0, time.UTC)
raw, rev, got, err := entryOf(func(key string) (*stdio.StateEntry, error) {
return &stdio.StateEntry{Key: key, Value: json.RawMessage(`{}`), Revision: 4, At: at}, nil
})("k")
if err != nil || string(raw) != "{}" || rev != 4 || !got.Equal(at) {
t.Errorf("entry = %s rev %d at %v (%v); want the entry's own write time %v", raw, rev, got, err, at)
}
}
@@ -430,7 +430,7 @@ func main() {
return a, json.Unmarshal(raw, &a)
}
tools := Tools(r, put, askQueue(stdio.State(build.QueuesState), 25*time.Second), buildAgain, stdio.Log(builds.BuilderLog).Since, time.Now, vr, fr, ofr, reserve)
tools = append(tools, buildTool(&build.BuildReader{Builds: read(stdio.State("builds")), Entry: entryOf(stdio.State("builds")), Asked: read(stdio.State("asked")),
tools = append(tools, buildTool(&build.BuildReader{Builds: read(stdio.State("builds")), Entry: entryOf(stdio.State("builds").Get), Asked: read(stdio.State("asked")),
Newest: newestVia(stdio.Ask), Steps: r}))
tools = append(tools, reservedTools(rr, buildAgain, time.Now, meshhandactsclient.Recorder{Ask: stdio.Ask})...)
as := stdio.State(versions.ActedState)
@@ -481,13 +481,14 @@ func main() {
}
}
// entryOf reads a key with its revision and when it was written.
func entryOf(s stdio.KeptState) func(key string) (json.RawMessage, uint64, time.Time, error) {
// entryOf reads a key with its revision and when it was written, the entry's own write time: no key's history is read
// (design 47 H2 H-A-487).
func entryOf(get func(key string) (*stdio.StateEntry, error)) func(key string) (json.RawMessage, uint64, time.Time, error) {
return func(key string) (json.RawMessage, uint64, time.Time, error) {
e, err := s.Get(key)
e, err := get(key)
if err != nil || e == nil {
return nil, 0, time.Time{}, err
}
return e.Value, e.Revision, written(s, key, e.Revision), nil
return e.Value, e.Revision, e.At, nil
}
}
@@ -19,6 +19,8 @@ import (
// `module` alone the module's keys newest first, at most MostBuilds, each with its fingerprint whole, its state, revision and
// since when, its step and node, its error whole, event-builds and the open ask (§568), and `newest` naming each watched branch
// whose newest catalog graph entry of the module names that fingerprint, read from the catalog half by the tools bundle.
// **Each key's time is its entry's own write time** (design 47 H2 H-A-487): the history of a key is read only for the one key a
// fingerprint names, when its entry does not say when it was written, and a listing cut at MostBuilds says so in its note.
// BuildTool is the builder's read tool of a module's build keys.
const BuildTool = "builder_build"
@@ -56,14 +58,16 @@ type BuildAnswer struct {
Builds []BuildRow `json:"builds"`
// Newest is the fingerprint of the module's newest catalog graph entry on each watched branch.
Newest map[string]string `json:"newest-entries,omitempty"`
// Note says what no key shows: that none of the keys is the newest entry's, naming its fingerprint.
// Note says what no key shows: that none of the keys is the newest entry's, naming its fingerprint, and that the listing
// was cut at MostBuilds (H-A-487).
Note string `json:"note,omitempty"`
}
// BuildReader reads what builder_build answers.
type BuildReader struct {
Builds StateRead
// Entry is a key's value with its revision and when it was written; nil leaves both out.
// Entry is a key's value with its revision and when it was written, the entry's own write time (H-A-487); nil leaves both
// out. Builds.Written, the key's history, is read only for the key a fingerprint names when Entry says no time.
Entry func(key string) (json.RawMessage, uint64, time.Time, error)
// Asked is the builder's state asked, which holds the asks the operator was asked.
Asked StateRead
@@ -96,6 +100,9 @@ func (r *BuildReader) Build(module, fingerprint string) (BuildAnswer, error) {
if raw == nil {
continue
}
if at.IsZero() && fingerprint != "" && r.Builds.Written != nil {
at = r.Builds.Written(key) // one key's history, never every key's (H-A-487)
}
v, err := builds.DecodeBuilderBuild(raw)
if err != nil {
return out, fmt.Errorf("%s holds what is not a build: %w", key, err)
@@ -118,7 +125,9 @@ func (r *BuildReader) Build(module, fingerprint string) (BuildAnswer, error) {
}
return rows[i].Key > rows[j].Key
})
var cut string
if len(rows) > MostBuilds {
cut = fmt.Sprintf("%d of %s's %d build keys are answered, the newest by write time; name a fingerprint for another", MostBuilds, module, len(rows))
rows = rows[:MostBuilds]
}
asks := r.openAsks()
@@ -149,6 +158,9 @@ func (r *BuildReader) Build(module, fingerprint string) (BuildAnswer, error) {
out.Note = "no build key of " + module + " is the newest entry's: " + strings.Join(says, "; ")
}
}
if cut != "" {
out.Note = strings.TrimPrefix(out.Note+"; "+cut, "; ")
}
out.Builds = append(out.Builds, rows...)
return out, nil
}
@@ -2,6 +2,7 @@ package build
import (
"encoding/json"
"fmt"
"sort"
"strings"
"testing"
@@ -66,6 +67,28 @@ func TestBuilderBuildAnswersAModulesKeysWhole(t *testing.T) {
if n, err := r.Build("m", ""); err != nil || !strings.Contains(n.Note, "no build key of m is the newest entry's") || !strings.Contains(n.Note, "main names src2:"+strings.Repeat("c", 64)) {
t.Errorf("a module none of whose keys the newest entry names: %+v, %v", n, err)
}
// H-A-487: a module of 100 keys is read by each entry's own write time, no key's history read, and the listing is cut at the
// 20 newest, saying so; a fingerprint's key with no time in its entry has its one history read.
many, at := map[string][]byte{}, map[string]time.Time{}
base := time.Date(2026, 11, 22, 20, 0, 0, 0, time.UTC)
for i := range 100 {
k, _ := builds.BuilderBuildKey("big", fmt.Sprintf("src2:%064x", i))
many[k], at[k] = done, base.Add(time.Duration(i)*time.Minute)
}
histories := 0
st := stateOf(many)
st.Written = func(string) time.Time { histories++; return base }
big := &BuildReader{Builds: st, Entry: func(k string) (json.RawMessage, uint64, time.Time, error) { return many[k], 1, at[k], nil }}
a, err = big.Build("big", "")
if err != nil || len(a.Builds) != MostBuilds || !a.Builds[0].Since.Equal(base.Add(99*time.Minute)) || histories != 0 ||
!strings.Contains(a.Note, "20 of big's 100 build keys are answered") {
t.Fatalf("100 keys: %d rows, newest %v, %d histories read, note %q; want the 20 newest, no history, the cut said", len(a.Builds), a.Builds[0].Since, histories, a.Note)
}
big.Entry = func(k string) (json.RawMessage, uint64, time.Time, error) { return many[k], 1, time.Time{}, nil }
if one, err := big.Build("big", fmt.Sprintf("src2:%064x", 7)); err != nil || len(one.Builds) != 1 || !one.Builds[0].Since.Equal(base) || histories != 1 {
t.Errorf("one fingerprint with no time in its entry: %+v (%v), %d histories; want its one history read", one, err, histories)
}
}
// Design 47 G §589: builder_stuck answers each key's fingerprint whole, as the build-input fingerprint the catalog graph entry carries it.