builder: know a registry seat's holder from the seat-holders view from the start, not from running heard

builder_publish_again for mesh-delivery-pipeline 0.1.6 queued nothing after a restart: the holder was learnt only
from node-engine running events heard since the builder started. The Republisher now reads each registry seat's
holder from the catalog's SeatHolders, the holder function the builder's FollowSeat of the assignments takes;
publish again and a node's returned queue at it. A running still queues the versions waiting on its module.
A seat with no holder is logged by name.

Builds: design 47 G §588, A-416, A-416a
This commit is contained in:
2026-11-15 02:18:38 +01:00
parent f89f34ce7b
commit e75112baec
3 changed files with 52 additions and 54 deletions
@@ -242,7 +242,8 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
actedKV := process.AwaitBucket(ctx, js, conn, own.acted, "no version is published again on an event or by builder_publish_again", logger.Printf)
republish := &versions.Republisher{Reserved: reserved.r, Queue: awaitedQueue{awaitedReserved{awaitedVersions{b: queueKV, bucket: own.queue}}},
Acted: awaitedReserved{awaitedVersions{b: actedKV, bucket: own.acted}}, Entry: entryVia(calls.Call), Send: sendVia(calls.Call),
Unreleased: reserved.unreleasedWords, Max: republishMax, Logf: logger.Printf}
Unreleased: reserved.unreleasedWords, Max: republishMax, Logf: logger.Printf,
Holders: holders} // a registry seat's holder from the seat-holders view, from the start (design 47 G A-416, A-416a)
acts.Republish = republish.Republish
again := &republishing{rp: republish}
// The operator is asked once a key's event builds are spent (design 47 G §568): the builder's asker on the seat operator-channel.
@@ -17,8 +17,8 @@ import (
// **A reserved version left unpublished is published again by the builder, on an event or by a person's tool** (design 47
// G §588, ADR 0674): on the node-engine seat's `running` of a module whose catalog graph entry claims the registry seat
// of the missing artifacts' kind, and on its `manifest-reads-changed` with `why` `returned` of the node such a holder
// runs on. Each message is acted on once, by its stream sequence (state `acted`); each holder has one queue of versions,
// of the missing artifacts' kind, and on its `manifest-reads-changed` with `why` `returned`, at each registry seat's holder
// the seat-holders view names (A-416, A-416a: known from the start, not from the running heard). Each message is acted on once, by its stream sequence (state `acted`); each holder has one queue of versions,
// kept in the state `publish-queue`, sent one at a time. A send is the registry seat's `publish` with the digest and no
// parts (A-73): the holder takes the bytes from the artifact store by digest, and refuses what no store holds.
@@ -112,9 +112,11 @@ type Republisher struct {
Logf func(string, ...any)
// Go starts the sending of a holder's queue; nil starts a goroutine.
Go func(func())
// Holders answers a registry seat's holders: the catalog's SeatHolders, the part's one holder function that its FollowSeat
// of the assignments takes too, read from the builder's start (design 47 G A-416, A-416a); nil answers none.
Holders func(seat string) []string
mu sync.Mutex
runs map[string]map[string][]string // node -> holder module -> the registry seats it claims
busy map[string]bool
// lastQueued is the newest time a version was queued at: a clock that has not moved between two versions (a coarse clock,
// or a fixed one) must not make the queue's order the order of its keys, so each is queued after the last.
@@ -205,8 +207,8 @@ func (r *Republisher) registrySeatsOf(ctx context.Context, fingerprint string) (
return out, nil
}
// running takes a running in: a module stopped is forgotten; one running whose entry claims a registry seat is a holder on
// its node, and its versions are queued.
// running takes a running in: one of a module whose entry claims a registry seat queues the versions waiting on it (§588). It
// is not how a holder is known: Holders answers that (design 47 G A-416).
func (r *Republisher) running(ctx context.Context, data []byte) error {
var ev nodeengine.Running
if err := json.Unmarshal(data, &ev); err != nil || ev.Module == "" || ev.Node == "" {
@@ -214,28 +216,12 @@ func (r *Republisher) running(ctx context.Context, data []byte) error {
return nil
}
if ev.Stopped || ev.Fingerprint == "" {
r.mu.Lock()
delete(r.runs[ev.Node], ev.Module)
r.mu.Unlock()
return nil
}
seats, err := r.registrySeatsOf(ctx, ev.Fingerprint)
if err != nil {
return fmt.Errorf("the catalog entry %s of %s cannot be read: %w", ev.Fingerprint, ev.Module, err)
}
r.mu.Lock()
if r.runs == nil {
r.runs = map[string]map[string][]string{}
}
if r.runs[ev.Node] == nil {
r.runs[ev.Node] = map[string][]string{}
}
if len(seats) == 0 {
delete(r.runs[ev.Node], ev.Module)
} else {
r.runs[ev.Node][ev.Module] = seats
}
r.mu.Unlock()
if len(seats) == 0 {
return nil
}
@@ -243,7 +229,30 @@ func (r *Republisher) running(ctx context.Context, data []byte) error {
return err
}
// returned takes a manifest-reads-changed in: only one with why returned acts, for every holder known to run on its node.
// heldSeats are the registry seats' holders as Holders answers them: holder module -> the registry seats it holds.
func (r *Republisher) heldSeats() map[string][]string {
held := map[string][]string{}
if r.Holders == nil {
return held
}
for _, seat := range RegistrySeats {
for _, h := range r.Holders(seat) {
held[h] = append(held[h], seat)
}
}
return held
}
// holdersFn answers a seat's holders from Holders.
func (r *Republisher) holdersFn(seat string) []string {
if r.Holders == nil {
return nil
}
return r.Holders(seat)
}
// returned takes a manifest-reads-changed in: only one with why returned acts, for every registry seat's holder Holders
// answers (design 47 G A-416a); a version queued at a holder already is not queued again.
func (r *Republisher) returned(ctx context.Context, data []byte) error {
var ev nodeengine.ManifestReadsChanged
if err := json.Unmarshal(data, &ev); err != nil || ev.Node == "" {
@@ -253,12 +262,7 @@ func (r *Republisher) returned(ctx context.Context, data []byte) error {
if ev.Why != nodeengine.ManifestReadsChangedWhyReturned {
return nil
}
r.mu.Lock()
holders := map[string][]string{}
for m, seats := range r.runs[ev.Node] {
holders[m] = seats
}
r.mu.Unlock()
holders := r.heldSeats()
if len(holders) == 0 {
return nil
}
@@ -337,7 +341,7 @@ func (r *Republisher) queue(ctx context.Context, vs []ReservedVersion, holdersOf
}
byHolder[hs[0]][ref] = v.Artifacts[ref]
} else {
r.logf("publish again: %s %s: %s is not queued: no module running that claims the registry seat %s is known to the builder since its start", v.Module, v.Version, ref, seat)
r.logf("publish again: %s %s: %s is not queued: the registry seat %s has no holder in the seat-holders view", v.Module, v.Version, ref, seat)
}
}
if !found {
@@ -396,8 +400,8 @@ func (r *Republisher) enqueue(ctx context.Context, v ReservedVersion, holder str
// Republish is builder_publish_again: with module and version, that reserved version's missing artifacts; with module
// alone, each reserved version of it whose artifacts are not all published; with neither, every version the finding
// version-unreleased names. It queues as the events do (no limit but the cap), for the holders known to run, and answers
// the versions it queued.
// version-unreleased names. It queues as the events do (no limit but the cap), at the holders Holders answers (design 47 G
// A-416), and answers the versions it queued.
func (r *Republisher) Republish(ctx context.Context, module, version string) ([]string, error) {
var vs []ReservedVersion
if module == "" {
@@ -424,15 +428,7 @@ func (r *Republisher) Republish(ctx context.Context, module, version string) ([]
return nil, fmt.Errorf("%s holds no reserved version%s with an artifact unpublished", module, map[bool]string{true: " " + version, false: ""}[version != ""])
}
}
r.mu.Lock()
known := map[string][]string{}
for _, mods := range r.runs {
for m, seats := range mods {
known[m] = seats
}
}
r.mu.Unlock()
return r.queue(ctx, vs, func(seat string) []string { return holdersOf(known, seat) }, 0)
return r.queue(ctx, vs, r.holdersFn, 0)
}
// Queued are the queued versions, per holder in the order they are sent, and the acted keys with their sequences:
@@ -31,6 +31,8 @@ type republishBed struct {
sent []Publish
said []string
refuse string // the words Send fails with, empty for none
// holders are the registry seats' holders the seat-holders view names (design 47 G A-416).
holders map[string][]string
}
func newRepublishBed(t *testing.T, max int) *republishBed {
@@ -58,6 +60,7 @@ func newRepublishBed(t *testing.T, max int) *republishBed {
b.said = append(b.said, v.Module+" "+v.Version+": "+why)
},
Logf: t.Logf}
b.Holders = func(seat string) []string { return b.holders[seat] }
return b
}
@@ -115,14 +118,10 @@ func TestRepublish(t *testing.T) {
t.Errorf("a key stays in the queue after its outcome: %v", keys)
}
})
t.Run("returned acts, started does not", func(t *testing.T) {
t.Run("returned acts at the seat's holder, started does not", func(t *testing.T) {
b := newRepublishBed(t, 50)
b.reserve(t, "m")
subject, data := running("n1", "oci", "src2:holder", true) // stopped: not a holder yet
_, _ = b.Heard(ctx, subject, data, 1)
subject, data = running("n1", "oci", "src2:holder", false)
_, _ = b.Heard(ctx, subject, data, 2)
b.sent = nil
b.holders = map[string][]string{SeatArtifacts: {"oci"}}
for i, why := range []string{nodeengine.ManifestReadsChangedWhyStarted, "", nodeengine.ManifestReadsChangedWhyReturned} {
ev, _ := json.Marshal(nodeengine.ManifestReadsChanged{Node: "n1", Why: why})
handled, err := b.Heard(ctx, nodeengine.SubjectManifestReadsChanged("n1"), ev, uint64(10+i))
@@ -194,23 +193,25 @@ func TestRepublish(t *testing.T) {
t.Errorf("resume sent %d (%v), want the begun version sent anew", len(b.sent), err)
}
})
t.Run("the tool queues for a holder known to run", func(t *testing.T) {
t.Run("after a fresh start the tool queues at the seat's holder, no running heard", func(t *testing.T) {
// Design 47 G A-416, A-416a: the holder is the one the seat-holders view names from the start, not one learnt from a
// running heard since; a seat with no holder queues nothing.
b := newRepublishBed(t, 1)
b.reserve(t, "m1")
b.reserve(t, "m2")
if q, err := b.Republish(ctx, "", ""); err != nil || len(q) != 0 {
t.Errorf("no holder known: queued %v (%v), want none", q, err)
t.Errorf("no holder named: queued %v (%v), want none", q, err)
}
subject, data := running("n1", "oci", "src2:holder", false)
_, _ = b.Heard(ctx, subject, data, 1) // Max 1: only m2 sent
b.sent = nil
b.holders = map[string][]string{SeatArtifacts: {"oci"}}
q, err := b.Republish(ctx, "", "")
if err != nil || fmt.Sprint(q) != "[m2 0.1.0 m1 0.1.0]" || len(b.sent) != 2 {
t.Errorf("the tool with neither queued %v (%v), sent %d: want both versions, with no limit", q, err, len(b.sent))
if err != nil || fmt.Sprint(q) != "[m2 0.1.0 m1 0.1.0]" || len(b.sent) != 2 || b.sent[0].Seat != SeatArtifacts {
t.Errorf("the tool with neither queued %v (%v), sent %+v: want both versions at oci, with no limit", q, err, b.sent)
}
if _, err := b.Republish(ctx, "m1", "0.1.9"); err == nil {
t.Error("a version no reservation holds is not refused")
}
subject, data := running("n1", "oci", "src2:holder", false)
_, _ = b.Heard(ctx, subject, data, 1)
answer, err := AnswerQueue(Reader{Keys: func() ([]string, error) { return nil, nil }}, Reader{Keys: func() ([]string, error) { return b.acted.KeysOf(ctx, AllFilter) },
Get: func(k string) (json.RawMessage, bool, error) { v, _, ok, err := b.acted.Get(ctx, k); return v, ok, err }})
if err != nil || answer.Acted[ActedKey(subject)] != 1 {