The seat's bodies hold TakeInTaken (branch, source, entries with repository and pull) and TakeInPending (branch); revision's answer gains none-yet and its revision is optional; meshcatalogclient reads the field, never the error's words. The holders' and readers' uses of the answer follow (a pointer revision). Builds: design 47 G §476, §493, §530, §454, §648 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
243 lines
9.7 KiB
Go
243 lines
9.7 KiB
Go
package meshcatalogclient
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"maps"
|
|
"strconv"
|
|
"sync"
|
|
"time"
|
|
|
|
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog"
|
|
"git.novox.be/novox/mesh-sdk/go/buscalls"
|
|
"git.novox.be/novox/mesh-sdk/go/keys"
|
|
"git.novox.be/novox/mesh-sdk/go/views"
|
|
)
|
|
|
|
// RevisionVerb is the seat verb a part takes its first view of the catalog half by, as its manifest's invokes names it.
|
|
const RevisionVerb = "seat:" + seat.Seat + "." + seat.VerbRevision
|
|
|
|
// The kinds a catalog graph revision is of.
|
|
const (
|
|
KindTrunk = "trunk"
|
|
KindCandidate = "candidate"
|
|
)
|
|
|
|
// Half is one catalog graph revision whole: the revision with its entries by module.
|
|
type Half struct {
|
|
Revision seat.CatalogRevision
|
|
Entries map[string]seat.CatalogEntry
|
|
}
|
|
|
|
// ViewName is how the catalog half's revision is named in a part's first-view status (views.Status.View, WaitsFor).
|
|
func ViewName(revision int64) string { return strconv.FormatInt(revision, 10) }
|
|
|
|
// catalogCreated stands for the view's Created in its follower: a revision view is never made again, so one fixed time,
|
|
// never zero, lets the follower tell a revision heard from one it holds.
|
|
var catalogCreated = time.Unix(0, 0).UTC()
|
|
|
|
// Catalog is a part's view of the catalog half of one watched branch (design 47 G §358, §479): a first view of the
|
|
// branch's newest trunk revision asked of the seat's verb `revision`, then kept from its event `catalog-revision` of that
|
|
// branch, built on go/views' Follower, so the runtime's tools `<module>_first_views` and `<module>_first_view_again` read
|
|
// and steer it as every first view. The view is named `mesh-catalog.catalog-revisions.<branch>`, so a part that watches two
|
|
// branches makes two Catalogs, two views. A `catalog-revision` the view missed (a revision heard that it does not hold)
|
|
// asks `revision` once more, said in the log (§196, ADR 0615 §5), and is waited for, said in the status and past
|
|
// views.WaitsBound raised as view-waits.
|
|
type Catalog struct {
|
|
Follower *views.Follower
|
|
// Branch is the watched branch the view is of, as the caller names it.
|
|
Branch string
|
|
|
|
call Call
|
|
mu sync.Mutex
|
|
// held is the half the view holds; paging the one being read, page by page, of one revision.
|
|
held *Half
|
|
paging *Half
|
|
// waits is the revision waited for, 0 when none.
|
|
waits int64
|
|
}
|
|
|
|
// NewCatalog is a Catalog of branch asking the seat through call. Nothing is asked before Start.
|
|
func NewCatalog(call Call, branch string) (*Catalog, error) {
|
|
if err := keys.CheckName("branch", branch); err != nil {
|
|
return nil, err
|
|
}
|
|
c := &Catalog{call: call, Branch: branch}
|
|
c.Follower = &views.Follower{Owner: seat.Seat, Tool: RevisionVerb, State: views.BranchState(seat.StateCatalogRevisions, branch), Ask: c.ask}
|
|
return c, nil
|
|
}
|
|
|
|
// WireCatalog is a Catalog of branch adopted by a stdio part's views.Reader: the reader writes its conditions and its
|
|
// view-waits finding, reads it as `mesh-catalog.catalog-revisions.<branch>` (a key a module, its value the module's
|
|
// entry), lists and asks it again in its first-view tools, and at its Start subscribes the seat's event catalog-revision
|
|
// (the part's manifest consumes it) into Hear and asks the first view. changed, when not nil, is the Follower's Changed.
|
|
// The part declares the seat's verb revision in invokes. Call it once per watched branch.
|
|
func WireCatalog(r *views.Reader, call Call, branch string, changed func(module string, entry json.RawMessage, deleted bool, at time.Time)) (*Catalog, error) {
|
|
c, err := NewCatalog(call, branch)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
c.Follower.Changed = changed
|
|
if err := r.Adopt(c.Follower, seat.Seat, seat.EventCatalogRevision, c.Hear); err != nil {
|
|
return nil, err
|
|
}
|
|
return c, nil
|
|
}
|
|
|
|
// WireCatalogProcess is WireCatalog for a process's views.ProcessReader: its picture
|
|
// (`mesh-catalog_catalog-revisions.<branch>`) reads the half as a read-only bucket, and the seat's event catalog-revision
|
|
// on the module's durable consumer goes to Hear.
|
|
func WireCatalogProcess(r *views.ProcessReader, call Call, branch string, changed func(module string, entry json.RawMessage, deleted bool, at time.Time)) (*Catalog, *views.Picture, error) {
|
|
c, err := NewCatalog(call, branch)
|
|
if err != nil {
|
|
return nil, nil, err
|
|
}
|
|
c.Follower.Changed = changed
|
|
p, err := r.Adopt(c.Follower, seat.Seat, seat.EventCatalogRevision, c.Hear)
|
|
if err != nil {
|
|
return nil, nil, err
|
|
}
|
|
return c, p, nil
|
|
}
|
|
|
|
// Start asks the first view, the branch's newest trunk revision, until it is answered or ctx ends.
|
|
func (c *Catalog) Start(ctx context.Context) error { return c.Follower.Start(ctx) }
|
|
|
|
// Ready is closed once the first view is answered.
|
|
func (c *Catalog) Ready() <-chan struct{} { return c.Follower.Ready() }
|
|
|
|
// View is the half the view holds; false while it has none, when the part acts on nothing new.
|
|
func (c *Catalog) View() (Half, bool) {
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
if c.held == nil {
|
|
return Half{}, false
|
|
}
|
|
return Half{Revision: c.held.Revision, Entries: maps.Clone(c.held.Entries)}, true
|
|
}
|
|
|
|
// Entry is one module's entry in the half the view holds.
|
|
func (c *Catalog) Entry(module string) (seat.CatalogEntry, bool) {
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
if c.held == nil {
|
|
return seat.CatalogEntry{}, false
|
|
}
|
|
e, ok := c.held.Entries[module]
|
|
return e, ok
|
|
}
|
|
|
|
// Hear takes one `catalog-revision` event, as the part's durable consumer of the seat's events hands it. A candidate's
|
|
// revision and another branch's move nothing here; a trunk revision of this branch the view holds, or one older, is passed
|
|
// over; a newer one is a revision the view missed: waited for, said in the log, and asked again on its own goroutine, so
|
|
// the consumer is never held while the holder is away. Data that is no such event is an error.
|
|
func (c *Catalog) Hear(ctx context.Context, data []byte) error {
|
|
var ev seat.CatalogRevisionEvent
|
|
if err := json.Unmarshal(data, &ev); err != nil || ev.Revision <= 0 {
|
|
return fmt.Errorf("meshcatalogclient: not a %s event: %s", seat.EventCatalogRevision, clipBytes(data))
|
|
}
|
|
if ev.Kind != KindTrunk || ev.Branch != keys.EscapeName(c.Branch) {
|
|
return nil
|
|
}
|
|
c.mu.Lock()
|
|
held := int64(0)
|
|
if c.held != nil {
|
|
held = c.held.Revision.Revision
|
|
}
|
|
if ev.Revision > c.waits {
|
|
c.waits = ev.Revision
|
|
}
|
|
c.mu.Unlock()
|
|
if ev.Revision <= held {
|
|
return nil
|
|
}
|
|
// The follower keeps the newest revision heard, so an ask that was running when it was heard is asked once more.
|
|
c.Follower.Apply(views.Event{Owner: seat.Seat, State: c.Follower.State, Revision: uint64(ev.Revision), Created: catalogCreated, Gap: true})
|
|
c.Follower.WaitFor(ctx, ViewName(ev.Revision))
|
|
if c.Follower.Logf != nil {
|
|
c.Follower.Logf("meshcatalogclient: catalog revision %d of %s said, the view holds %d: %s is asked once more", ev.Revision, c.Branch, held, RevisionVerb)
|
|
}
|
|
go func() {
|
|
_ = c.Follower.Gap(ctx, fmt.Sprintf("catalog revision %d of %s said, the view holds %d", ev.Revision, c.Branch, held))
|
|
}()
|
|
return nil
|
|
}
|
|
|
|
// ask is the Follower's Ask: one page of the branch's newest trunk revision, the next pages of the same revision; once
|
|
// whole, it is the half the view holds.
|
|
func (c *Catalog) ask(_ context.Context, after string) (views.Answer, error) {
|
|
in := seat.RevisionInput{After: after, Branch: keys.EscapeName(c.Branch)}
|
|
c.mu.Lock()
|
|
if after != "" && c.paging != nil {
|
|
in.Revision = c.paging.Revision.Revision
|
|
}
|
|
c.mu.Unlock()
|
|
a, err := askRevision(c.call, in)
|
|
if errors.Is(err, errNoneYet) {
|
|
// A branch with no revision yet is ready and empty, and nothing waits for it (§479, §495).
|
|
return views.Answer{V: 1, Owner: seat.Seat, State: c.Follower.State, Created: catalogCreated, Values: map[string]json.RawMessage{}, At: time.Now()}, nil
|
|
}
|
|
if err != nil {
|
|
return views.Answer{}, err
|
|
}
|
|
if a.Revision.Kind != KindTrunk {
|
|
return views.Answer{}, fmt.Errorf("%s answered a %s revision for the trunk", RevisionVerb, a.Revision.Kind)
|
|
}
|
|
c.mu.Lock()
|
|
if after == "" || c.paging == nil {
|
|
c.paging = &Half{Revision: *a.Revision, Entries: map[string]seat.CatalogEntry{}}
|
|
} else if c.paging.Revision.Revision != a.Revision.Revision {
|
|
was := c.paging.Revision.Revision
|
|
c.paging = nil
|
|
c.mu.Unlock()
|
|
return views.Answer{}, fmt.Errorf("%s answered revision %d for a page of revision %d", RevisionVerb, a.Revision.Revision, was)
|
|
}
|
|
values := map[string]json.RawMessage{}
|
|
for _, e := range a.Entries {
|
|
c.paging.Entries[e.Module] = e
|
|
raw, _ := json.Marshal(e)
|
|
values[e.Module] = raw
|
|
}
|
|
rev := a.Revision.Revision
|
|
holds := false
|
|
if a.Next == "" {
|
|
c.held, c.paging = c.paging, nil
|
|
if c.waits <= rev {
|
|
c.waits, holds = 0, true
|
|
}
|
|
}
|
|
c.mu.Unlock()
|
|
if holds {
|
|
c.Follower.Holds(ViewName(rev))
|
|
}
|
|
return views.Answer{V: 1, Owner: seat.Seat, State: c.Follower.State, Revision: uint64(rev), Created: catalogCreated, Values: values, Next: a.Next, At: time.Now()}, nil
|
|
}
|
|
|
|
// errNoneYet is the seat's answer `none-yet`: the branch has no revision yet (design 47 G §530).
|
|
var errNoneYet = errors.New("none yet")
|
|
|
|
func askRevision(call Call, in seat.RevisionInput) (seat.RevisionAnswer, error) {
|
|
raw, err := call(RevisionVerb, in)
|
|
if err != nil {
|
|
return seat.RevisionAnswer{}, err
|
|
}
|
|
answer, said, ok := buscalls.Unwrap(raw)
|
|
if !ok {
|
|
return seat.RevisionAnswer{}, fmt.Errorf("%s answered: %s", RevisionVerb, said)
|
|
}
|
|
var a seat.RevisionAnswer
|
|
if err := json.Unmarshal(answer, &a); err != nil {
|
|
return seat.RevisionAnswer{}, fmt.Errorf("%s answered no revision: %s", RevisionVerb, clipBytes(answer))
|
|
}
|
|
// An answer is told by its fields, never by its words (§530): `none-yet` is a ready, empty view.
|
|
if a.NoneYet {
|
|
return seat.RevisionAnswer{}, errNoneYet
|
|
}
|
|
if a.Revision == nil || a.Revision.Revision <= 0 {
|
|
return seat.RevisionAnswer{}, fmt.Errorf("%s answered no revision: %s", RevisionVerb, clipBytes(answer))
|
|
}
|
|
return a, nil
|
|
}
|