A run on request copied its pipeline's source onto its build step ask, so the builder waited for the run's candidate fingerprints in its picture of the branch, where they never come, and failed every run past the bound. The seat mesh-builds' contract leaves a run's source absent: the runner now does. A revision the builder's view takes in whole that changes no entry now also wakes a waiting ask, told by the catalog client's new Held. Builds: design 47 H H-A-162, H-A-155
503 lines
18 KiB
Go
503 lines
18 KiB
Go
package meshcatalogclient
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"slices"
|
|
"sync"
|
|
"sync/atomic"
|
|
"time"
|
|
|
|
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
|
|
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/sourcebranches"
|
|
"git.novox.be/novox/mesh-sdk/go/buscalls"
|
|
"git.novox.be/novox/mesh-sdk/go/busretry"
|
|
"git.novox.be/novox/mesh-sdk/go/keys"
|
|
"git.novox.be/novox/mesh-sdk/go/views"
|
|
)
|
|
|
|
// SourceVerb is the gate's verb a part reads the branches the gate keeps a source revision of by, before the first
|
|
// registrations, as its manifest's invokes names it (design 47 G §614); the follower is the SDK's sourcebranches.
|
|
const SourceVerb = sourcebranches.SourceVerb
|
|
|
|
// EntryVerb is the seat verb a part reads an entry by its fingerprint by, as its manifest's invokes names it.
|
|
const EntryVerb = "seat:" + seat.Seat + "." + seat.VerbEntry
|
|
|
|
// Wiring is how Branches puts a view on its part's one reader and takes it off: ReaderWiring for a bundle's
|
|
// views.Reader, ProcessWiring for a process's views.ProcessReader. Adopt is the reader's Adopt, so a view adopted after
|
|
// the reader's Start takes its first view at once; Drop is its Drop, which clears every finding the view raised.
|
|
type Wiring interface {
|
|
Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error
|
|
Drop(owner, state string) error
|
|
}
|
|
|
|
type readerWiring struct{ r *views.Reader }
|
|
|
|
func (w readerWiring) Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error {
|
|
return w.r.Adopt(f, seat, event, hear)
|
|
}
|
|
func (w readerWiring) Drop(owner, state string) error { return w.r.Drop(owner + "." + state) }
|
|
|
|
type processWiring struct{ r *views.ProcessReader }
|
|
|
|
func (w processWiring) Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error {
|
|
_, err := w.r.Adopt(f, seat, event, hear)
|
|
return err
|
|
}
|
|
func (w processWiring) Drop(owner, state string) error { return w.r.Drop(owner, state) }
|
|
|
|
// ReaderWiring wires Branches on a bundle's reader.
|
|
func ReaderWiring(r *views.Reader) Wiring { return readerWiring{r} }
|
|
|
|
// Rows adds the list to the reader's `<module>_first_views`.
|
|
func (w readerWiring) Rows(name string, rows func() any) { w.r.Rows(name, rows) }
|
|
|
|
// ProcessWiring wires Branches on a process's reader.
|
|
func ProcessWiring(r *views.ProcessReader) Wiring { return processWiring{r} }
|
|
|
|
// Branches is the one branch follower of design 47 G §614, built once and used by every part that reads the catalog half:
|
|
// it follows the watched branches of the registrations (the first view of `registrations` at the start, then each
|
|
// `registration-changed`); before the first registration, the branches the gate's `source` answers (its first view at
|
|
// the start, then each `source-moved`), which it stops following at the first `registration-changed`; it adopts a Catalog
|
|
// view on the part's reader for each branch that comes and drops the view of each that goes, and keeps the entries by
|
|
// fingerprint a part asks of the verb `entry` (Entries). The part declares what §614 says in `consumes` and `invokes`.
|
|
type Branches struct {
|
|
// Registrations is the follower of the registrations, also the part's own reading of them.
|
|
Registrations *Registrations
|
|
// Entries is the cache of the entries read by fingerprint.
|
|
Entries *Entries
|
|
// claims are the seats each manifest digest claims (Claimant), holders the part's follow of the seat-holders view (SeatHolders).
|
|
claimsMu sync.Mutex
|
|
claims map[string][]string
|
|
holders atomic.Pointer[seatHolders]
|
|
// Changed, when not nil, is told of each change to a branch's view (module, its entry, deleted), set before Wire.
|
|
Changed func(branch, module string, entry json.RawMessage, deleted bool, at time.Time)
|
|
// Held, when not nil, is told of each revision a branch's view takes in whole (Catalog.Held; H-A-162), set before Wire.
|
|
Held func(branch string, revision seat.CatalogRevision)
|
|
// Adopted, when not nil, is told on a goroutine of its own of each branch whose view was adopted, with that view (a part that waits for
|
|
// its first branch's first view, design 47 G §507), set before Wire.
|
|
Adopted func(branch string, c *Catalog)
|
|
// Logf, when not nil, says each view adopted and dropped.
|
|
Logf func(format string, args ...any)
|
|
|
|
call Call
|
|
w Wiring
|
|
|
|
mu sync.Mutex
|
|
source *sourcebranches.SourceBranches
|
|
left []string // the source's branches when it was left, kept until the registrations hold one
|
|
catalogs map[string]*Catalog
|
|
order []string
|
|
}
|
|
|
|
// NewBranches adopts the registrations and the gate's source on w, so the reader's Start asks them, and then adopts a
|
|
// Catalog per branch as the picture says. call asks the seat verbs.
|
|
func NewBranches(w Wiring, call Call) (*Branches, error) {
|
|
b := &Branches{call: call, w: w, catalogs: map[string]*Catalog{}, Entries: NewEntries(call)}
|
|
b.Registrations = NewRegistrations(call)
|
|
b.Registrations.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { b.reconcile() }
|
|
b.source = sourcebranches.New(sourcebranches.Call(call))
|
|
b.source.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { b.reconcile() }
|
|
if err := w.Adopt(b.Registrations.Follower, seat.Seat, seat.EventRegistrationChanged, b.hearRegistration); err != nil {
|
|
return nil, err
|
|
}
|
|
if err := w.Adopt(b.source.Follower, sourcebranches.Seat, sourcebranches.EventSourceMoved, b.source.Hear); err != nil {
|
|
return nil, err
|
|
}
|
|
if rw, ok := w.(interface {
|
|
Rows(name string, rows func() any)
|
|
}); ok { // the entries by fingerprint are said in the part's `<module>_first_views` (design 47 G A-103)
|
|
rw.Rows("entries", func() any { return b.EntryStatuses() })
|
|
}
|
|
return b, nil
|
|
}
|
|
|
|
// FollowBranches is NewBranches on a bundle's reader.
|
|
func FollowBranches(r *views.Reader, call Call) (*Branches, error) {
|
|
return NewBranches(ReaderWiring(r), call)
|
|
}
|
|
|
|
// FollowBranchesProcess is NewBranches on a process's reader.
|
|
func FollowBranchesProcess(r *views.ProcessReader, call Call) (*Branches, error) {
|
|
return NewBranches(ProcessWiring(r), call)
|
|
}
|
|
|
|
func (b *Branches) logf(format string, args ...any) {
|
|
if b.Logf != nil {
|
|
b.Logf(format, args...)
|
|
}
|
|
}
|
|
|
|
// hearRegistration is the handler of `registration-changed`: the first one ends the following of the gate's source.
|
|
func (b *Branches) hearRegistration(ctx context.Context, data []byte) error {
|
|
err := b.Registrations.Hear(ctx, data)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
b.mu.Lock()
|
|
s := b.source
|
|
if s != nil {
|
|
b.left, b.source = s.Branches(), nil
|
|
}
|
|
b.mu.Unlock()
|
|
if s != nil {
|
|
if err := b.w.Drop(sourcebranches.Seat, sourcebranches.StateSourceBranches); err != nil {
|
|
b.logf("meshcatalogclient: the gate's source is not dropped: %v", err)
|
|
} else {
|
|
b.logf("meshcatalogclient: the first registration-changed is heard: the gate's source is followed no more")
|
|
}
|
|
b.reconcile()
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Followed is the branches (as named) whose views are adopted, in the order they came.
|
|
func (b *Branches) Followed() []string {
|
|
b.mu.Lock()
|
|
defer b.mu.Unlock()
|
|
out := make([]string, 0, len(b.order))
|
|
for _, e := range b.order {
|
|
out = append(out, b.catalogs[e].Branch)
|
|
}
|
|
return out
|
|
}
|
|
|
|
// Catalog is the view of one branch, as named; false when it is not followed.
|
|
func (b *Branches) Catalog(branch string) (*Catalog, bool) {
|
|
b.mu.Lock()
|
|
defer b.mu.Unlock()
|
|
c, ok := b.catalogs[keys.EscapeName(branch)]
|
|
return c, ok
|
|
}
|
|
|
|
// Resolve reads an entry by its fingerprint: from a branch's held half when one lists it, else from the entries kept
|
|
// by fingerprint, asked of `entry` once when none is kept. The state is `answered` for an entry at hand, `asked` while the
|
|
// ask is out, `not-found` once the holder said it holds none.
|
|
func (b *Branches) Resolve(ctx context.Context, fingerprint string) (seat.CatalogEntry, EntryState) {
|
|
b.mu.Lock()
|
|
cs := make([]*Catalog, 0, len(b.order))
|
|
for _, e := range b.order {
|
|
cs = append(cs, b.catalogs[e])
|
|
}
|
|
b.mu.Unlock()
|
|
for _, c := range cs {
|
|
if half, ok := c.View(); ok {
|
|
for _, e := range half.Entries {
|
|
if e.Fp == fingerprint {
|
|
return e, EntryAnswered
|
|
}
|
|
}
|
|
}
|
|
}
|
|
return b.Entries.Need(ctx, fingerprint)
|
|
}
|
|
|
|
// Listed says whether a branch's held half lists fingerprint.
|
|
func (b *Branches) Listed(fingerprint string) bool {
|
|
b.mu.Lock()
|
|
cs := make([]*Catalog, 0, len(b.order))
|
|
for _, e := range b.order {
|
|
cs = append(cs, b.catalogs[e])
|
|
}
|
|
b.mu.Unlock()
|
|
for _, c := range cs {
|
|
if half, ok := c.View(); ok {
|
|
for _, e := range half.Entries {
|
|
if e.Fp == fingerprint {
|
|
return true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
return false
|
|
}
|
|
|
|
// reconcile adopts the view of each branch that is wanted and drops the view of each that is not: the registrations'
|
|
// branches, and the gate's source's while it is followed (and, once left, until the registrations hold a branch).
|
|
func (b *Branches) reconcile() {
|
|
b.mu.Lock()
|
|
defer b.mu.Unlock()
|
|
want := map[string]string{} // escaped -> as named
|
|
for _, reg := range b.Registrations.All() {
|
|
for _, br := range reg.Branches {
|
|
want[keys.EscapeName(br)] = br
|
|
}
|
|
}
|
|
var from []string
|
|
switch {
|
|
case b.source != nil:
|
|
from = b.source.Branches()
|
|
case len(want) == 0:
|
|
from = b.left
|
|
default:
|
|
b.left = nil
|
|
}
|
|
for _, e := range from {
|
|
if name, err := keys.UnescapeName(e); err == nil {
|
|
want[e] = name
|
|
}
|
|
}
|
|
for _, e := range slices.Sorted(mapsKeys(want)) {
|
|
if b.catalogs[e] != nil {
|
|
continue
|
|
}
|
|
c, err := NewCatalog(b.call, want[e])
|
|
if err != nil {
|
|
b.logf("meshcatalogclient: the branch %q is not followed: %v", want[e], err)
|
|
continue
|
|
}
|
|
branch := want[e]
|
|
c.Follower.Changed = func(module string, entry json.RawMessage, deleted bool, at time.Time) {
|
|
b.holders.Load().changed()
|
|
if b.Changed != nil {
|
|
b.Changed(branch, module, entry, deleted, at)
|
|
}
|
|
}
|
|
c.Held = func(r seat.CatalogRevision) {
|
|
if b.Held != nil {
|
|
b.Held(branch, r)
|
|
}
|
|
}
|
|
// 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
|
|
}
|
|
b.catalogs[e] = c
|
|
b.order = append(b.order, e)
|
|
b.logf("meshcatalogclient: the branch %q is followed", want[e])
|
|
if b.Adopted != nil {
|
|
go b.Adopted(branch, c)
|
|
}
|
|
}
|
|
for _, e := range slices.Clone(b.order) {
|
|
if _, ok := want[e]; ok {
|
|
continue
|
|
}
|
|
c := b.catalogs[e]
|
|
if err := b.w.Drop(seat.Seat, c.Follower.State); err != nil {
|
|
b.logf("meshcatalogclient: the view of the branch %q is not dropped: %v", c.Branch, err)
|
|
}
|
|
delete(b.catalogs, e)
|
|
b.order = slices.DeleteFunc(b.order, func(o string) bool { return o == e })
|
|
b.logf("meshcatalogclient: the branch %q is followed no more", c.Branch)
|
|
}
|
|
}
|
|
|
|
func mapsKeys(m map[string]string) func(func(string) bool) {
|
|
return func(yield func(string) bool) {
|
|
for k := range m {
|
|
if !yield(k) {
|
|
return
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// EntryState is where an entry read by fingerprint stands.
|
|
type EntryState string
|
|
|
|
// The states of an entry kept by fingerprint (design 47 G §614, An older build's entry).
|
|
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
|
|
State EntryState
|
|
Since time.Time
|
|
// Detail says why an ask is still out when its last try failed.
|
|
Detail string
|
|
// 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
|
|
// asked, answered or not found. The reader a part passes to a pure function answers from the views and these alone.
|
|
type Entries struct {
|
|
// Changed, when not nil, is told of each entry that was answered or found missing, so the part starts a new pass at
|
|
// once, or writes the finding `entry-not-found`.
|
|
Changed func(row EntryRow)
|
|
// Released, when not nil, is told of each entry removed by Release.
|
|
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
|
|
rows map[string]*EntryRow
|
|
}
|
|
|
|
// NewEntries is an Entries asking the seat through call.
|
|
func NewEntries(call Call) *Entries { return &Entries{call: call, rows: map[string]*EntryRow{}} }
|
|
|
|
func (e *Entries) now() time.Time {
|
|
if e.Now != nil {
|
|
return e.Now()
|
|
}
|
|
return time.Now()
|
|
}
|
|
|
|
// Need reads fingerprint's entry: one kept is answered as it stands (`asked` as pending, a state apart from none); one
|
|
// not kept is asked of `entry` once, on its own goroutine, and answered as `asked`.
|
|
func (e *Entries) Need(ctx context.Context, fingerprint string) (seat.CatalogEntry, EntryState) {
|
|
e.mu.Lock()
|
|
row := e.rows[fingerprint]
|
|
if row == nil {
|
|
row = &EntryRow{Fingerprint: fingerprint, State: EntryAsked, Since: e.now()}
|
|
e.rows[fingerprint] = row
|
|
e.mu.Unlock()
|
|
go e.ask(ctx, fingerprint)
|
|
return seat.CatalogEntry{}, EntryAsked
|
|
}
|
|
defer e.mu.Unlock()
|
|
if row.Entry != nil {
|
|
return *row.Entry, row.State
|
|
}
|
|
return seat.CatalogEntry{}, row.State
|
|
}
|
|
|
|
// Again asks fingerprint's entry now, whatever its state (the part's tool `<module>_entry_again`). It waits for the answer.
|
|
func (e *Entries) Again(ctx context.Context, fingerprint string) error {
|
|
e.mu.Lock()
|
|
row := e.rows[fingerprint]
|
|
if row == nil {
|
|
e.mu.Unlock()
|
|
return fmt.Errorf("meshcatalogclient: no entry of %s is kept", fingerprint)
|
|
}
|
|
*row = EntryRow{Fingerprint: fingerprint, State: EntryAsked, Since: e.now()}
|
|
e.mu.Unlock()
|
|
e.ask(ctx, fingerprint)
|
|
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()
|
|
delete(e.rows, fingerprint)
|
|
e.mu.Unlock()
|
|
if e.Released != nil {
|
|
e.Released(fingerprint)
|
|
}
|
|
}
|
|
|
|
// Rows lists the entries kept, by fingerprint (the part's tool `<module>_first_views` lists them with their state and
|
|
// since when).
|
|
func (e *Entries) Rows() []EntryRow {
|
|
e.mu.Lock()
|
|
defer e.mu.Unlock()
|
|
out := make([]EntryRow, 0, len(e.rows))
|
|
for _, r := range e.rows {
|
|
out = append(out, *r)
|
|
}
|
|
slices.SortFunc(out, func(a, b EntryRow) int {
|
|
switch {
|
|
case a.Fingerprint < b.Fingerprint:
|
|
return -1
|
|
case a.Fingerprint > b.Fingerprint:
|
|
return 1
|
|
}
|
|
return 0
|
|
})
|
|
return out
|
|
}
|
|
|
|
// 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) {
|
|
raw, err := e.call(EntryVerb, seat.EntryInput{Fingerprint: fingerprint})
|
|
var row EntryRow
|
|
e.mu.Lock()
|
|
cur := e.rows[fingerprint]
|
|
if cur == nil {
|
|
e.mu.Unlock()
|
|
return
|
|
}
|
|
var holderSaid *busretry.Answered
|
|
switch {
|
|
case errors.As(err, &holderSaid):
|
|
// 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, 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
|
|
switch {
|
|
case !ok:
|
|
cur.State, cur.Since, cur.Detail = EntryNotFound, e.now(), said
|
|
case json.Unmarshal(answer, &a) != nil || a.Entry.Module == "":
|
|
cur.Detail = errors.New("answered no entry: " + clipBytes(answer)).Error()
|
|
e.mu.Unlock()
|
|
return
|
|
default:
|
|
entry := a.Entry
|
|
cur.State, cur.Since, cur.Detail, cur.Entry = EntryAnswered, e.now(), "", &entry
|
|
}
|
|
}
|
|
row = *cur
|
|
e.mu.Unlock()
|
|
if e.Changed != nil {
|
|
e.Changed(row)
|
|
}
|
|
}
|