Files
mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/entry.go
T
jschoubben fd68792614 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
2026-11-20 04:56:28 +01:00

207 lines
8.2 KiB
Go

package meshcatalogclient
import (
"context"
"fmt"
"strings"
"time"
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"
)
// Ready is nil once every watched branch has its first view (`none-yet` counting as one), else says what it waits for
// (design 47 G §614, A-103): a part acts on nothing until then. On a fresh mesh, where the registrations and the gate's source are both
// answered and name no branch, it is nil too: the trunk is `none-yet` (A-368).
func (b *Branches) Ready() error {
followed := b.Followed()
if len(followed) == 0 {
// A fresh mesh: the registrations and the gate's source are both answered and name no branch, so the trunk is `none-yet`
// and the view is empty (design 47 G, A-368).
if b.namesNoBranch() {
return nil
}
return fmt.Errorf("the catalog half names no watched branch yet (the registrations of the seat %s are asked until they answer)", seat.Seat)
}
var waiting []string
for _, branch := range followed {
if c, ok := b.Catalog(branch); ok {
select {
case <-c.Ready():
default:
waiting = append(waiting, branch)
}
}
}
if len(waiting) > 0 {
return fmt.Errorf("the catalog half has no first view of %s yet", strings.Join(waiting, ", "))
}
return nil
}
// namesNoBranch says the first view of the registrations is in and, while the gate's source is followed, so is its, and
// neither names a branch (none is followed).
func (b *Branches) namesNoBranch() bool {
select {
case <-b.Registrations.Ready():
default:
return false
}
// A first view closes before the follower's change is taken into the branches followed, so what the views hold is read too.
for _, reg := range b.Registrations.All() {
if len(reg.Branches) > 0 {
return false
}
}
b.mu.Lock()
s := b.source
b.mu.Unlock()
if s == nil {
return true
}
select {
case <-s.Follower.Ready():
default:
return false
}
return len(s.Branches()) == 0
}
// FirstViews is closed once the first views of the registrations and, while it is followed, of the gate's source are in: a part
// that waits for the catalog half to settle looks at Followed and Ready once it is closed (design 47 G, A-372).
func (b *Branches) FirstViews(ctx context.Context) <-chan struct{} {
done := make(chan struct{})
go func() {
select {
case <-b.Registrations.Ready():
case <-ctx.Done():
return
}
b.mu.Lock()
s := b.source
b.mu.Unlock()
if s != nil {
select {
case <-s.Follower.Ready():
case <-ctx.Done():
return
}
}
close(done)
}()
return done
}
// Entry is a module's entry at the trunk: the module's own registration decides, so the branch followed first, which lists
// the module, is the one read (design 47 G A-103). An error says a watched branch has no first view yet, never "no module".
func (b *Branches) Entry(module string) (seat.CatalogEntry, bool, error) {
if err := b.Ready(); err != nil {
return seat.CatalogEntry{}, false, err
}
for _, branch := range b.Followed() {
if c, ok := b.Catalog(branch); ok {
if e, ok := c.Entry(module); ok {
return e, true, nil
}
}
}
return seat.CatalogEntry{}, false, nil
}
// EntryStatus is one entry kept by fingerprint as a part's `<module>_first_views` says it: its state and since when.
type EntryStatus struct {
Fingerprint string `json:"fingerprint"`
State EntryState `json:"state"`
Since time.Time `json:"since"`
Detail string `json:"detail,omitempty"`
}
// EntryStatuses are the entries kept by fingerprint, as `<module>_first_views` lists them (design 47 G §614, A-103).
func (b *Branches) EntryStatuses() []EntryStatus {
rows := b.Entries.Rows()
out := make([]EntryStatus, 0, len(rows))
for _, r := range rows {
out = append(out, EntryStatus{Fingerprint: r.Fingerprint, State: r.State, Since: r.Since, Detail: r.Detail})
}
return out
}
// WriteEntryFindings makes the part write the finding `entry-not-found` through w for each entry the holder answered it does not
// 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 {
case EntryNotFound:
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)
_ = 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
// again now, as a hand act recorded first through handAct (what, why, cause), and answers where the entry stands.
func (b *Branches) EntryAgainTool(module string, handAct func(what, why, cause string) error) stdio.Tool {
name := module + "_entry_again"
return stdio.Tool{Name: name,
Description: "Ask the catalog's entry of one build, by its fingerprint, again now, whatever its state: a hand act, for an entry the part holds as asked or not found. Answers where it stands after. (a)",
Input: map[string]any{"type": "object", "required": []string{"fingerprint", "why"}, "properties": map[string]any{
"fingerprint": map[string]any{"type": "string"}, "why": map[string]any{"type": "string"}}},
Run: func(a map[string]any) (any, error) {
fingerprint, _ := a["fingerprint"].(string)
why, _ := a["why"].(string)
if fingerprint = strings.TrimSpace(fingerprint); fingerprint == "" {
return nil, fmt.Errorf("name the fingerprint of the entry")
}
if strings.TrimSpace(why) == "" {
return nil, fmt.Errorf("say why: a hand act keeps its why")
}
if err := handAct(name+" "+fingerprint, strings.TrimSpace(why), name); err != nil {
return nil, fmt.Errorf("the hand-act log does not hold it, so nothing is asked: %w", err)
}
if err := b.Entries.Again(context.Background(), fingerprint); err != nil {
return nil, err
}
return map[string]any{"entries": b.EntryStatuses()}, nil
}}
}