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
207 lines
8.2 KiB
Go
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
|
|
}}
|
|
}
|