From fd6879261447d72dd82d5f578cf84947340ddf84 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 04:10:38 +0100 Subject: [PATCH] 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 --- .../go/clients/meshcatalogclient/branches.go | 65 ++++++++++++++++-- .../meshcatalogclient/branches_test.go | 66 +++++++++++++++++++ .../go/clients/meshcatalogclient/entry.go | 37 ++++++++++- 3 files changed, 159 insertions(+), 9 deletions(-) diff --git a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches.go b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches.go index 55a222bb..7aa1ea1a 100644 --- a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches.go +++ b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches.go @@ -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 `_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 diff --git a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches_test.go b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches_test.go index 48173ebf..eb60df6d 100644 --- a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches_test.go +++ b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/branches_test.go @@ -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. diff --git a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/entry.go b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/entry.go index 362b9448..6e9aaec0 100644 --- a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/entry.go +++ b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/entry.go @@ -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 `_entry_again` (design 47 G A-103; class act): it asks one entry by fingerprint