meshcatalogclient: an unreached entry is asked again, at most entry-asks times

An entry whose ask failed in transport is asked again when the followed branch says
catalog-revision and when the part's link opens again (AskAgain), at most Asks times (the
part's setting entry-asks, default 5); one more failure makes it unanswered, and
WriteEntryFindings writes the finding entry-unanswered, cleared by its answer or its release.

Builds: design 47 H (H-A-60, the entry asked again)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 04:56:28 +01:00
parent 4611f263f3
commit fd68792614
3 changed files with 159 additions and 9 deletions
@@ -253,7 +253,13 @@ func (b *Branches) reconcile() {
b.Changed(branch, module, entry, deleted, at)
}
}
if err := b.w.Adopt(c.Follower, seat.Seat, seat.EventCatalogRevision, c.Hear); err != nil {
// A catalog-revision also asks again each entry whose ask failed in transport (design 47 H, H-A-60).
hear := func(ctx context.Context, data []byte) error {
err := c.Hear(ctx, data)
b.Entries.AskAgain(ctx)
return err
}
if err := b.w.Adopt(c.Follower, seat.Seat, seat.EventCatalogRevision, hear); err != nil {
b.logf("meshcatalogclient: the view of the branch %q is not adopted: %v", want[e], err)
continue
}
@@ -296,8 +302,18 @@ const (
EntryAsked EntryState = "asked"
EntryAnswered EntryState = "answered"
EntryNotFound EntryState = "not-found"
// EntryUnanswered is an entry whose ask failed in transport and was asked again as often as the bound allows
// (design 47 H, H-A-60): the part writes the finding EntryUnansweredKind; the part's `<module>_entry_again` asks it anew.
EntryUnanswered EntryState = "unanswered"
)
// DefaultEntryAsks is the default of the part's setting `entry-asks`: how often an entry whose ask failed in transport
// is asked again before it is unanswered (design 47 H, H-A-60).
const DefaultEntryAsks = 5
// EntryUnansweredKind is a part's finding of an entry left unanswered (EntryUnanswered): scope the part, id the fingerprint.
const EntryUnansweredKind = "entry-unanswered"
// EntryRow is one entry kept by fingerprint: its state, since when, and the entry once answered.
type EntryRow struct {
Fingerprint string
@@ -305,7 +321,11 @@ type EntryRow struct {
Since time.Time
// Detail says why an ask is still out when its last try failed.
Detail string
Entry *seat.CatalogEntry
// Asks is how often the entry was asked again after an ask that failed in transport.
Asks int
Entry *seat.CatalogEntry
// failed says the last ask failed in transport, so AskAgain asks it again.
failed bool
}
// Entries keeps, beside a part's views, the entries by fingerprint it asked of `entry` (design 47 G §614): each is
@@ -318,6 +338,9 @@ type Entries struct {
Released func(fingerprint string)
// Now is the clock, time.Now when nil.
Now func() time.Time
// Asks is the part's setting `entry-asks`: how often an entry whose ask failed in transport is asked again before it
// is unanswered; DefaultEntryAsks when 0 (design 47 H, H-A-60).
Asks int
call Call
mu sync.Mutex
@@ -367,6 +390,32 @@ func (e *Entries) Again(ctx context.Context, fingerprint string) error {
return nil
}
// AskAgain asks again, each on its own goroutine, every entry whose last ask failed in transport (design 47 H, H-A-60):
// Branches calls it when the catalog half says `catalog-revision`, and the part calls it when its link to the bus opens
// again. An entry asked again as often as Asks allows that fails once more is unanswered, and Changed is told.
func (e *Entries) AskAgain(ctx context.Context) {
e.mu.Lock()
var again []string
for fp, row := range e.rows {
if row.State == EntryAsked && row.failed {
row.failed = false
row.Asks++
again = append(again, fp)
}
}
e.mu.Unlock()
for _, fp := range again {
go e.ask(ctx, fp)
}
}
func (e *Entries) bound() int {
if e.Asks > 0 {
return e.Asks
}
return DefaultEntryAsks
}
// Release removes fingerprint's entry: no `running` or `wanted` the part holds names it any more.
func (e *Entries) Release(fingerprint string) {
e.mu.Lock()
@@ -398,7 +447,8 @@ func (e *Entries) Rows() []EntryRow {
return out
}
// ask reads fingerprint's entry once. A call that failed to reach the holder leaves the entry asked, with its reason;
// ask reads fingerprint's entry once. A call that failed to reach the holder leaves the entry asked, with its reason, to be
// asked again (AskAgain), and unanswered once it was asked again as often as the bound allows;
// the holder's own answer that it holds none is `not-found`, whether the call gives it in the reply or, as a process's
// call does, as its error (busretry.Answered).
func (e *Entries) ask(_ context.Context, fingerprint string) {
@@ -416,9 +466,12 @@ func (e *Entries) ask(_ context.Context, fingerprint string) {
// A process's call gives the holder's own answer as its error: it holds none.
cur.State, cur.Since, cur.Detail = EntryNotFound, e.now(), holderSaid.Words
case err != nil:
cur.Detail = err.Error()
e.mu.Unlock()
return
cur.Detail, cur.failed = err.Error(), true
if cur.Asks < e.bound() {
e.mu.Unlock()
return
}
cur.State, cur.Since, cur.failed = EntryUnanswered, e.now(), false
default:
answer, said, ok := buscalls.Unwrap(raw)
var a seat.EntryAnswer
@@ -94,6 +94,9 @@ type fakeSeats struct {
version int64
entries map[string]seat.CatalogEntry
entryAsk int
// unreached, when above 0, is how many entry calls more fail in transport; asked, when set, is told after each entry call.
unreached int
asked chan string
// trunk, when set, is the revision answered for every branch.
trunk *seat.RevisionAnswer
}
@@ -117,6 +120,13 @@ func (f *fakeSeats) call(key string, body any) (json.RawMessage, error) {
return json.Marshal(seat.RevisionAnswer{NoneYet: true})
case EntryVerb:
f.entryAsk++
if f.asked != nil {
defer func() { f.asked <- body.(seat.EntryInput).Fingerprint }()
}
if f.unreached > 0 {
f.unreached--
return nil, errors.New("nats: no responders available for request")
}
e, ok := f.entries[body.(seat.EntryInput).Fingerprint]
if !ok {
return json.RawMessage(`{"error":"no such entry"}`), nil
@@ -173,6 +183,31 @@ func TestBranchesFollowSourceThenRegistrations(t *testing.T) {
t.Fatal(err)
}
want("mesh-catalog.catalog-revisions.main", "mesh-catalog.registrations", "mesh-delivery.source")
// Design 47 H (H-A-60): an entry whose ask failed in transport is asked again when the followed branch says catalog-revision.
seats.mu.Lock()
seats.unreached, seats.asked, seats.entries = 1, make(chan string, 4), map[string]seat.CatalogEntry{"src2:u": {Module: "u", Fp: "src2:u"}}
seats.mu.Unlock()
answered := make(chan EntryRow, 2)
b.Entries.Changed = func(r EntryRow) { answered <- r }
b.Entries.Need(ctx, "src2:u")
<-seats.asked
_, hearMain := w.get("mesh-catalog.catalog-revisions.main")
if err := hearMain(ctx, []byte(`{"revision":1,"kind":"trunk","branch":"main"}`)); err != nil {
t.Fatal(err)
}
select {
case r := <-answered:
if r.State != EntryAnswered || r.Asks != 1 {
t.Fatalf("after a catalog-revision the entry is %+v, want answered at its first ask again", r)
}
case <-ctx.Done():
t.Fatal("a catalog-revision asked the unreached entry not again")
}
b.Entries.Changed = nil
seats.mu.Lock()
seats.asked = nil
seats.mu.Unlock()
seats.mu.Lock()
seats.source = []string{"main", "feat/x"}
seats.mu.Unlock()
@@ -298,6 +333,37 @@ func TestEntriesAreAskedOnceAnsweredOrNotFound(t *testing.T) {
}
}
// Design 47 H (H-A-60): an entry whose ask failed in transport is asked again on each AskAgain, at most Asks times; one
// more failure makes it unanswered and tells the part, after which nothing asks it again but the hand's Again.
func TestAnUnreachedEntryIsAskedAgainToItsBoundThenUnanswered(t *testing.T) {
ctx := context.Background()
seats := &fakeSeats{unreached: 99, asked: make(chan string, 8)}
e := NewEntries(seats.call)
e.Asks = 2
told := make(chan EntryRow, 2)
e.Changed = func(r EntryRow) { told <- r }
e.AskAgain(ctx) // nothing is kept yet: nothing is asked
e.Need(ctx, "src2:u")
<-seats.asked
e.AskAgain(ctx)
<-seats.asked
if rows := e.Rows(); len(rows) != 1 || rows[0].State != EntryAsked || rows[0].Asks != 1 || len(told) != 0 {
t.Fatalf("after one ask again: rows %+v, told %d", rows, len(told))
}
e.AskAgain(ctx)
<-seats.asked
if r := <-told; r.State != EntryUnanswered || r.Asks != 2 || r.Detail == "" {
t.Fatalf("past the bound: told %+v, want unanswered", r)
}
e.AskAgain(ctx)
if seats.entryAsk != 3 {
t.Fatalf("entry asked %d times, want 3: an unanswered entry is not asked again", seats.entryAsk)
}
if e := NewEntries(seats.call); e.bound() != DefaultEntryAsks || DefaultEntryAsks != 5 {
t.Fatalf("the default bound is %d, want 5", e.bound())
}
}
// A-298 (§717, A-295): the part's holder function follows the seat-holders view of the module the trunk's half names as the
// claimant of mesh-module-assigner, asked of its tool seat-holders; a revision naming another claimant drops it and follows the
// new one's; nothing is followed while no claimant is named.
@@ -8,6 +8,7 @@ import (
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
)
@@ -128,8 +129,9 @@ func (b *Branches) EntryStatuses() []EntryStatus {
}
// WriteEntryFindings makes the part write the finding `entry-not-found` through w for each entry the holder answered it does not
// hold, and clear it when a later ask answers it or the part releases the entry (design 47 G §614, A-15, A-103). then, when not
// nil, is told of each change after, so the part starts a new pass. The kind `entry-not-found` is one of w's kinds.
// hold, and `entry-unanswered` for each entry asked again as often as the bound allows (design 47 H, H-A-60), and clear them
// when a later ask answers it or the part releases the entry (design 47 G §614, A-15, A-103). then, when not nil, is told of
// each change after, so the part starts a new pass. The kinds `entry-not-found` and `entry-unanswered` are two of w's kinds.
func (b *Branches) WriteEntryFindings(w views.WireWriter, then func(EntryRow)) {
b.Entries.Changed = func(row EntryRow) {
switch row.State {
@@ -137,14 +139,43 @@ func (b *Branches) WriteEntryFindings(w views.WireWriter, then func(EntryRow)) {
if err := views.WriteEntryNotFound(w, row.Fingerprint, row.Since, time.Now()); err != nil && b.Logf != nil {
b.Logf("the finding entry-not-found of %s is not kept: %v", row.Fingerprint, err)
}
case EntryUnanswered:
if err := writeEntryUnanswered(w, row); err != nil && b.Logf != nil {
b.Logf("the finding %s of %s is not kept: %v", EntryUnansweredKind, row.Fingerprint, err)
}
case EntryAnswered:
_ = views.ClearEntryNotFound(w, row.Fingerprint)
_ = clearEntryUnanswered(w, row.Fingerprint)
}
if then != nil {
then(row)
}
}
b.Entries.Released = func(fingerprint string) { _ = views.ClearEntryNotFound(w, fingerprint) }
b.Entries.Released = func(fingerprint string) {
_ = views.ClearEntryNotFound(w, fingerprint)
_ = clearEntryUnanswered(w, fingerprint)
}
}
// writeEntryUnanswered writes the part's finding that fingerprint's entry was asked again as often as the bound allows and
// never reached the holder, in the wire form of a views part's finding (mesh-sdk views): scope the part's module, id the
// fingerprint escaped as a key's name is, severity warning.
func writeEntryUnanswered(w views.WireWriter, row EntryRow) error {
module, node := w.ModuleNode()
subject := map[string]any{"scope": views.FindingScope, "id": module}
if node != "" {
subject["machine"] = node
}
return w.WriteWire(context.Background(), map[string]any{"kind": EntryUnansweredKind, "scope": views.FindingScope,
"id": keys.EscapeName(row.Fingerprint), "severity": "warning", "source": "views", "subject": subject,
"summary": fmt.Sprintf("%s asked the catalog's entry of fingerprint %s %d times more after its ask failed and never reached the holder (%s); unanswered since %s: what it needs of the entry stands still until the entry is asked again by hand",
module, row.Fingerprint, row.Asks, row.Detail, row.Since.UTC().Format(time.RFC3339)),
"headline": fmt.Sprintf("%s cannot reach the catalog entry of a build", module), "at": time.Now().UTC()})
}
// clearEntryUnanswered clears the finding writeEntryUnanswered wrote for fingerprint.
func clearEntryUnanswered(w views.WireWriter, fingerprint string) error {
return w.Clear(context.Background(), views.FindingScope, keys.EscapeName(fingerprint), EntryUnansweredKind, "the part no longer observes it")
}
// EntryAgainTool is the part's tool `<module>_entry_again` (design 47 G A-103; class act): it asks one entry by fingerprint