diff --git a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go index e09db687..bd8a8fe3 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go @@ -239,6 +239,8 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro // and version-released heard; nothing is reserved before the fill. reservedKV := process.AwaitBucket(ctx, js, conn, own.reserved, "no version is reserved: builds are made unreserved", logger.Printf) reserved := newReservations(awaitedReserved{awaitedVersions{b: reservedKV, bucket: own.reserved}}, calls.Call, pubBoundsKV.KV, found, b.Reconsider, logger.Printf) + // The index by digest and by version beside the reservations is written again once the state is bound (H-A-269 (1), H-A-271). + reservedKV.Ready(func(jetstream.KeyValue) { reserved.reindex(ctx) }) // Each artifact the holder says published at a reserved version is said as the seat mesh-builds' package-published (design 47 G §52). reserved.say = func(ctx context.Context, p meshbuilds.PackagePublished) error { return emitSeatEvent(context.WithoutCancel(ctx), js, cred, meshbuilds.SubjectPackagePublished, "package-published-"+p.Module+"-"+p.Version+"-"+p.Artifact, p) @@ -260,6 +262,26 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro Entry: entryVia(calls.Call), Send: sendVia(calls.Call), Unreleased: reserved.unreleasedWords, 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) + // A number a registry seat already holds is never reserved (H-A-275): read before reserving, through the seats' verb versions. + reserved.r.HeldNumbers = func(ctx context.Context, module, fp string, refs []string) ([]string, error) { + return republish.HeldNumbers(ctx, module, fp, refs, registryVersionsVia(calls.Call)) + } + // A done build whose number a registry holds elsewhere is built again at the next free number (H-A-279), on the builder's context. + reserved.rebuild = func(_ context.Context, module, fp, why string) error { + res := b.BuildAgain(ctx, module, fp, why, "the builder", buildAgainBound) + switch { + case res.Refused != "": + return errors.New(res.Refused) + case res.Failed != "": + return errors.New(res.Failed) + case res.Pending != "": + logger.Printf("%s at %s is built again: %s", module, fp, res.Pending) + } + return nil + } + reserved.r.HeldElsewhere = func(ctx context.Context, module string, skipped []string) { + reserved.heldElsewhere(ctx, module, "the registries hold "+strings.Join(skipped, ", ")+", so the reserve skipped them") + } publishSet, err := publishSettingsOf(getenv) if err != nil { return err @@ -275,6 +297,12 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro return reserved.r.Of(ctx, module, version) }, republish: republish.Republish, endedWith: reserved.unreleased, + // A publish is asked again only while no published of it may be unheard and the registry's record lacks it (H-A-269 (2), H-A-272). + unheard: unheardVia(js, process.EventsStream, cred.EventConsumerName()), + judge: func(ctx context.Context, v versions.ReservedVersion) (versions.Judged, error) { + return republish.Held(ctx, v, registryVersionsVia(calls.Call)) + }, + markHeld: reserved.markHeld, moveElsewhere: reserved.movedElsewhere, allDone: func(ctx context.Context) ([]versions.ReservedVersion, error) { all, err := reserved.r.All(ctx) return builtOf(all), err diff --git a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem.go b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem.go index ea2de17e..f61ac764 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem.go @@ -47,10 +47,20 @@ type publishItems struct { republish func(ctx context.Context, module, version string) ([]string, error) endedWith func(ctx context.Context, v versions.ReservedVersion, why string) // raises the finding version-unreleased allDone func(ctx context.Context) ([]versions.ReservedVersion, error) - set publishSettings - now func() time.Time - after func(time.Duration) <-chan time.Time - logf func(string, ...any) + // unheard is how many messages the builder's durable on the events stream holds pending and unacknowledged, read before each + // try (design 47 H H-A-269 (2), H-A-272); nil reads none. + unheard func(ctx context.Context) (int, error) + // judge is what the registries' own record says of a version's missing artifacts (H-A-272, H-A-274, H-A-275); nil judges none. + judge func(ctx context.Context, v versions.ReservedVersion) (versions.Judged, error) + // markHeld marks the artifacts the registries hold with the built digest published from their record, as their published heard + // would (H-A-274); moveElsewhere moves a version a registry holds at another digest to the next free number and asks its + // publish there (H-A-275). Nil does neither. + markHeld func(ctx context.Context, v versions.ReservedVersion, held []versions.HeldArtifact) + moveElsewhere func(ctx context.Context, v versions.ReservedVersion, j versions.Judged) error + set publishSettings + now func() time.Time + after func(time.Duration) <-chan time.Time + logf func(string, ...any) } func (p *publishItems) wait(ctx context.Context, d time.Duration) bool { @@ -138,6 +148,12 @@ func (p *publishItems) Try(ctx context.Context, kv jetstream.KeyValue, e jetstre if p.endedWith != nil { p.endedWith(ctx, v, "the publish ended after "+fmt.Sprint(r.Tries)+" tries") } + } else if why, gone := p.notAgain(ctx, v); gone { + return // moved to another number, whose own item is asked (H-A-275) + } else if why != "" { + // A published of the version may be unheard, or the registry's record ended it: no ask, and no try spent (H-A-272, H-A-274). + p.logf("%s %s: the publish is not asked again: %s; tried again after %s", r.Module, r.Version, why, p.set.pauseAfter(r.Tries)) + r.NextTry = p.now().UTC().Add(p.set.pauseAfter(r.Tries)) } else { r.Tries++ if _, err := p.republish(ctx, r.Module, r.Version); err != nil { @@ -154,6 +170,85 @@ func (p *publishItems) Try(ctx context.Context, kv jetstream.KeyValue, e jetstre } } +// notAgain says why a version's publish is not asked again now, empty when it is (design 47 H H-A-269 (2), H-A-272, H-A-274, +// H-A-275): the builder's durable holds UnheardBound messages or more not yet heard, so a published of it may be among them; or the +// registries' own record holds every missing artifact at its version with its built digest, which marks them published from that +// record; or a registry holds the version at another digest, which moves the build to the next free number (gone: this item is +// ended with the old number). A count or a record that cannot be read is said, and does not hold the ask. +func (p *publishItems) notAgain(ctx context.Context, v versions.ReservedVersion) (why string, gone bool) { + if p.unheard != nil { + n, err := p.unheard(ctx) + switch { + case err != nil: + p.logf("%s %s: the builder's events consumer cannot be read, so the publish is asked again as it stands: %v", v.Module, v.Version, err) + case n >= versions.UnheardBound: + return fmt.Sprintf("the builder's events consumer holds %d messages not yet heard (the bound is %d), a published of it may be among them", n, versions.UnheardBound), false + } + } + if p.judge == nil { + return "", false + } + j, err := p.judge(ctx, v) + switch { + case err != nil: + p.logf("%s %s: the registries' record cannot be read, so the publish is asked again: %v", v.Module, v.Version, err) + case len(j.Elsewhere) > 0 && p.moveElsewhere != nil: + if err := p.moveElsewhere(ctx, v, j); err != nil { + p.logf("%s %s: a registry holds the number at another digest, and the build is not moved: %v", v.Module, v.Version, err) + return "a registry holds " + v.Version + " at another digest", false + } + return "", true + case j.All: + if p.markHeld != nil { + p.markHeld(ctx, v, j.Held) + } + return "the registries hold every missing artifact at " + v.Version + " with its built digest: marked published from their record", false + default: + p.logf("%s %s: asked again: %s", v.Module, v.Version, j.Lacks) + } + return "", false +} + +// unheardVia reads the builder's durable on the events stream: its messages pending and those given and not yet acknowledged +// (design 47 H H-A-272), what it has not yet heard. +func unheardVia(js jetstream.JetStream, stream, durable string) func(context.Context) (int, error) { + return func(ctx context.Context) (int, error) { + c, err := js.Consumer(ctx, stream, durable) + if err != nil { + return 0, err + } + info, err := c.Info(ctx) + if err != nil { + return 0, err + } + return int(info.NumPending) + info.NumAckPending, nil + } +} + +// registryVersionsVia asks a registry seat's verb versions for a name (H-A-272): each version it holds with its digest. +func registryVersionsVia(call toolCaller) func(context.Context, string, string) ([]versions.HeldVersion, error) { + return func(_ context.Context, seat, name string) ([]versions.HeldVersion, error) { + raw, err := call("seat:"+seat+"."+versions.VerbVersions, map[string]any{"name": name}) + if err != nil { + return nil, err + } + var a struct { // the four registry seats answer versions alike: each version with its digest + Versions []struct { + Version string `json:"version"` + Digest string `json:"digest"` + } `json:"versions"` + } + if err := json.Unmarshal(raw, &a); err != nil { + return nil, fmt.Errorf("%s's versions answered what is no list of versions: %w", seat, err) + } + out := make([]versions.HeldVersion, 0, len(a.Versions)) + for _, v := range a.Versions { + out = append(out, versions.HeldVersion{Version: v.Version, Digest: v.Digest}) + } + return out, nil + } +} + // numberFile reads a setting's number from the file the manifest declares: no file or an empty one is def; a content that is no // number of at least one is an error naming the file. func numberFile(path string, def int) (int, error) { diff --git a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem_test.go b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem_test.go index f0a41838..1feffe0c 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem_test.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/publishitem_test.go @@ -274,3 +274,76 @@ func TestThePublishItemsAreWiredToTheReservationsAndTheReAskWatch(t *testing.T) t.Errorf("a dropped reservation kept its item") } } + +// TestAPublishIsNotAskedAgainWhileItsPublishedMayBeUnheard: design 47 H H-A-269 (2), H-A-272, H-A-274, H-A-275 — a try asks the +// publish again only while the builder's durable holds fewer than a hundred messages not yet heard and the registries' record lacks +// an artifact; a record holding every missing artifact with the built digest marks them published from it; a record holding the +// version at another digest moves the build to the next free number and ends this item; a skipped try spends no try and is written +// again with its pause; a count that cannot be read holds no ask. +func TestAPublishIsNotAskedAgainWhileItsPublishedMayBeUnheard(t *testing.T) { + ctx := context.Background() + now := time.Date(2026, 11, 21, 15, 21, 0, 0, time.UTC) + v := versions.ReservedVersion{Module: "node-tools", Version: "0.1.37", Artifacts: map[string]string{"node-tools:program": "sha256:7c9b10"}, BuiltAt: now} + at := versions.HeldArtifact{Ref: "node-tools:program", Seat: versions.SeatArtifacts, Name: "node-tools/program", Version: "0.1.37", Digest: "sha256:7c9b10"} + other := at + other.Digest = "sha256:83bec1" + for _, c := range []struct { + name string + unheard int + countErr error + judged versions.Judged + wantAsked, wantMark, wantMov bool + }{ + {name: "thousands behind: no ask, the registry not read", unheard: 2944}, + {name: "at the bound: no ask", unheard: versions.UnheardBound}, + {name: "heard up, the registry holds it: marked from its record, no ask", unheard: versions.UnheardBound - 1, judged: versions.Judged{All: true, Held: []versions.HeldArtifact{at}}, wantMark: true}, + {name: "the registry holds the number at another digest: moved, no ask", unheard: 3, judged: versions.Judged{Elsewhere: []versions.HeldArtifact{other}}, wantMov: true}, + {name: "heard up, the registry lacks it: asked", unheard: 3, judged: versions.Judged{Lacks: "none"}, wantAsked: true}, + {name: "the count unreadable, the registry lacks it: asked", countErr: errors.New("no consumer"), judged: versions.Judged{Lacks: "none"}, wantAsked: true}, + } { + t.Run(c.name, func(t *testing.T) { + kv := &itemKV{vals: map[string][]byte{}, revs: map[string]uint64{}} + asked, judged, marked, moved := 0, 0, 0, 0 + p := &publishItems{reasks: func() jetstream.KeyValue { return kv }, set: defaultPublishSettings, now: func() time.Time { return now }, logf: t.Logf, + reserved: func(context.Context, string, string) (versions.ReservedVersion, bool, error) { return v, true, nil }, + republish: func(context.Context, string, string) ([]string, error) { asked++; return nil, nil }, + unheard: func(context.Context) (int, error) { return c.unheard, c.countErr }, + judge: func(context.Context, versions.ReservedVersion) (versions.Judged, error) { + judged++ + return c.judged, nil + }, + markHeld: func(_ context.Context, _ versions.ReservedVersion, h []versions.HeldArtifact) { + if len(h) == 1 && h[0].Digest == "sha256:7c9b10" { + marked++ + } + }, + moveElsewhere: func(context.Context, versions.ReservedVersion, versions.Judged) error { + moved++ + delete(kv.vals, versions.PublishItemKey(v.Module, v.Version)) // the takeover ends the old item + return nil + }} + if err := p.Ask(ctx, v.Module, v.Version); err != nil { + t.Fatal(err) + } + key := versions.PublishItemKey(v.Module, v.Version) + e, _ := kv.Get(ctx, key) + p.Try(ctx, kv, e, decodeItem(t, e.Value())) + if (asked == 1) != c.wantAsked || (marked == 1) != c.wantMark || (moved == 1) != c.wantMov { + t.Fatalf("asked %d, marked %d, moved %d; want asked %v, marked %v, moved %v", asked, marked, moved, c.wantAsked, c.wantMark, c.wantMov) + } + if c.wantMov { + if _, ok := kv.vals[key]; ok { + t.Error("the moved version's old item is written again") + } + return + } + got := decodeItem(t, kv.vals[key]) + if got.Tries != map[bool]int{true: 1, false: 0}[c.wantAsked] || !got.NextTry.After(now) { + t.Errorf("tries %d, next try %s: want a try spent only when asked, and the item written again with its pause", got.Tries, got.NextTry) + } + if c.unheard >= versions.UnheardBound && judged != 0 { + t.Error("the registry is read while a published may be unheard") + } + }) + } +} diff --git a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/refused_test.go b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/refused_test.go index 7d0d4f77..87f09a7a 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/refused_test.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/refused_test.go @@ -549,8 +549,14 @@ func (m memVersions) Update(_ context.Context, key string, v []byte, _ uint64) ( m[key] = v return 2, nil } -func (m memVersions) KeysOf(context.Context, string) ([]string, error) { - return slices.Collect(maps.Keys(m)), nil +func (m memVersions) KeysOf(_ context.Context, filter string) ([]string, error) { + var out []string + for k := range m { + if versions.FilterMatches(filter, k) { // as the bus reads a filter + out = append(out, k) + } + } + return out, nil } // memBuilds is the builder's builds in memory. diff --git a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve.go b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve.go index 867af03e..1e3bbd28 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve.go @@ -54,6 +54,8 @@ type reservations struct { withdraw func(module, fingerprint, why string) // call asks a seat's verb: the git seat's tag (design 47 G §370). call toolCaller + // rebuild builds a done key of module at fp again (the build-again path, A-490; H-A-279); nil builds none. + rebuild func(ctx context.Context, module, fp, why string) error // say says package-published on the seat mesh-builds; nil says none. say func(context.Context, meshbuilds.PackagePublished) error } @@ -77,10 +79,21 @@ func newReservations(store versions.ReserveStore, call toolCaller, bounds func() } return out, nil }} - rv.r.Took = rv.took + rv.r.Took, rv.r.Logf = rv.took, logf return rv } +// reindex writes the reservations' index again from the reservations, once at the builder's start (H-A-269 (1), H-A-271), and +// says so. +func (rv *reservations) reindex(ctx context.Context) { + n, err := rv.r.Reindex(ctx) + if err != nil { + rv.logf("the reservations' index is written again from %d reservations, not whole: %v", n, err) + return + } + rv.logf("the reservations' index is written again from %d reservations", n) +} + // took is a build's takeover of the reservation of an older build never released (design 47 G A-455): the older version is // dropped, its bound ended and its finding cleared (the newer build's reservation has its own), and the builder's log says so. func (rv *reservations) took(ctx context.Context, older, newer versions.ReservedVersion) { @@ -265,6 +278,7 @@ func (rv *reservations) heard(ctx context.Context, m jetstream.Msg) bool { rv.released(ctx, ev.Module, ev.Version) } rv.found.clear(ctx, versions.VersionUnreleased, meshconditionsclient.ScopeModule, ev.Module) + rv.found.clear(ctx, versions.VersionHeldElsewhere, meshconditionsclient.ScopeModule, ev.Module) default: return false } @@ -349,21 +363,19 @@ func (rv *reservations) tagged(ctx context.Context, ev meshcatalog.VersionReleas return nil } -// noMark says why a published marked nothing: which reservation holds that version, and what it holds of digests. +// noMark says why a published marked nothing: which reservation holds that version, and what it holds of digests, read through the +// index by version (H-A-269 (1), H-A-271). func (rv *reservations) noMark(ctx context.Context, o versions.Outcome) string { version := strings.TrimPrefix(o.Version, "v") if version == "" || o.Digest == "" { return "it names no version or no digest (a by-digest publish)" } - all, err := rv.r.All(ctx) + at, err := rv.r.AtVersion(ctx, version) // the index by version, never every reservation (H-A-271) if err != nil { - return "the reservations cannot be read: " + err.Error() + return "the reservations at " + version + " cannot be read: " + err.Error() } var out []string - for _, v := range all { - if v.Version != version { - continue - } + for _, v := range at { out = append(out, fmt.Sprintf("%s holds %d built digests %v, published %v (a published heard before the build recorded its digests is kept until it does)", v.Module, len(v.Artifacts), v.Artifacts, v.Published)) } if len(out) == 0 { @@ -395,3 +407,49 @@ func reserveDoneAct(reserve func(ctx context.Context, module, fp string) (versio func (rv *reservations) ReleasedFor(ctx context.Context, module, fingerprint string) (bool, error) { return rv.r.ReleasedFor(ctx, module, fingerprint) } + +// markHeld marks the artifacts the registries' record holds at their version with the built digest published, as their published +// heard would, and says package-published of each (design 47 H H-A-274): a published heard and lost never leaves the publish +// asked for ever. The version's release follows from the catalog as for any published. +func (rv *reservations) markHeld(ctx context.Context, v versions.ReservedVersion, held []versions.HeldArtifact) { + for _, h := range held { + rv.logf("%s %s: %s holds %s %s with the built digest %s: marked published from its record", v.Module, v.Version, h.Seat, h.Name, h.Version, h.Digest) + rv.published(ctx, versions.Outcome{Name: h.Name, Version: h.Version, Digest: h.Digest, Holder: h.Seat}) + } +} + +// heldElsewhere raises version-held-elsewhere about module (design 47 H H-A-275): numbers a registry holds were skipped or moved +// from, said with why. +func (rv *reservations) heldElsewhere(ctx context.Context, module, why string) { + rv.logf("%s: %s", module, why) + rv.found.raise(ctx, finding{kind: versions.VersionHeldElsewhere, scope: meshconditionsclient.ScopeModule, id: module, + summary: module + ": " + why, + headline: "A number a registry already holds is not used", + explanation: "A registry seat holds a version of " + module + " the builder did not publish there: " + why + ".", + resolved: "The catalog says version-released for " + module + ".", + needs: "builder_reserved shows the reservation and its withdrawn numbers; the registry seat's versions shows what it holds."}) +} + +// movedElsewhere takes a done build whose number a registry holds at another digest off that number (design 47 H H-A-275, +// H-A-279): every artifact carries its version from its build, so no digest survives a move. The number is withdrawn as a gap +// (H-A-226), the finding raised naming both digests, and the build of the same fingerprint asked again (the build-again path of a +// done key whose version is not released, A-490): its reserve takes the next number no registry holds, it records fresh digests +// and its own publish runs; the takeover of the withdrawn reservation ends its publish item and bound. +func (rv *reservations) movedElsewhere(ctx context.Context, v versions.ReservedVersion, j versions.Judged) error { + if rv.rebuild == nil { + return errors.New("no build again is wired") + } + if _, ok, err := rv.r.Withdraw(ctx, v.Module, v.Version); err != nil || !ok { + if err == nil { + err = fmt.Errorf("no reservation of %s stands at %s", v.Module, v.Version) + } + return err + } + var at []string + for _, h := range j.Elsewhere { + at = append(at, fmt.Sprintf("%s holds %s %s at %s, built %s", h.Seat, h.Name, h.Version, h.Digest, v.Artifacts[h.Ref])) + } + why := fmt.Sprintf("%s is withdrawn and the build of %s is built again at the next free number: %s", v.Version, v.Fingerprint, strings.Join(at, "; ")) + rv.heldElsewhere(ctx, v.Module, why) + return rv.rebuild(ctx, v.Module, v.Fingerprint, why) +} diff --git a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve_test.go b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve_test.go index 6051e802..84beb089 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve_test.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve_test.go @@ -48,7 +48,7 @@ func (m *memReserve) Update(_ context.Context, key string, v []byte, rev uint64) func (m *memReserve) KeysOf(_ context.Context, filter string) ([]string, error) { var out []string for k := range m.vals { - if filter == versions.AllFilter || strings.HasPrefix(k, strings.TrimSuffix(filter, "*")) { + if versions.FilterMatches(filter, k) { // as the bus reads a filter out = append(out, k) } } @@ -393,3 +393,87 @@ func TestAReserveDoneIsAnsweredWithTheVersionAndItsQueuedPublish(t *testing.T) { t.Errorf("the reserving by hand is not said in the log: %q", logged) } } + +// TestARegistrysRecordEndsOrMovesAPublish: design 47 H H-A-274 — the artifacts a registry's record holds with the built digest are +// marked published from it and package-published is said, as a heard published would; H-A-275 — a done build whose number a +// registry holds at another digest (H-A-279) has its number withdrawn, raises version-held-elsewhere naming both digests, and is +// built again: at the next number no registry holds, with a fresh digest, published there; the old number's item ends. +func TestARegistrysRecordEndsOrMovesAPublish(t *testing.T) { + ctx := context.Background() + fs := &memFindings{vals: map[string][]byte{}} + none := func(string, any) (json.RawMessage, error) { + return json.Marshal(meshcatalog.VersionsAnswer{Module: "node-tools"}) + } + bounds := &boundsKV{keys: map[string]bool{}} + rv := newReservations(&memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}, none, func() jetstream.KeyValue { return bounds }, + &findings{module: builds.BuilderModule, w: fs, logf: t.Logf, now: time.Now}, nil, t.Logf) + var said []meshbuilds.PackagePublished + rv.say = func(_ context.Context, p meshbuilds.PackagePublished) error { said = append(said, p); return nil } + var asked, ended []string + rv.built = func(_ context.Context, m, v string) error { asked = append(asked, m+" "+v); return nil } + rv.released = func(_ context.Context, m, v string) { ended = append(ended, m+" "+v) } + registry := []string{"0.1.37"} + rv.r.HeldNumbers = func(context.Context, string, string, []string) ([]string, error) { return registry, nil } + rv.filled.Store(true) + res, err := rv.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, versions.Source{Fingerprint: "fp1"}) + if err != nil || res.Version != "0.1.0" { + t.Fatalf("reserved %q (%v)", res.Version, err) + } + if err := rv.Built(ctx, "node-tools", res.Version, map[string]string{"node-tools:program": "sha256:7c9b10"}, nil); err != nil { + t.Fatal(err) + } + cur, _, _ := rv.r.Of(ctx, "node-tools", res.Version) + held := versions.HeldArtifact{Ref: "node-tools:program", Seat: versions.SeatArtifacts, Name: "node-tools/program", Version: res.Version, Digest: "sha256:7c9b10"} + rv.markHeld(ctx, cur, []versions.HeldArtifact{held}) + if len(said) != 1 || said[0].Artifact != "node-tools:program" || said[0].Version != res.Version { + t.Fatalf("package-published said %+v, want node-tools:program at %s from the registry's record", said, res.Version) + } + if cur, _, _ = rv.r.Of(ctx, "node-tools", res.Version); len(cur.Missing()) != 0 { + t.Errorf("the record marked nothing: missing %v", cur.Missing()) + } + // Another reservation of the module, done, whose number the registry holds at another digest: withdrawn, built again at the + // next free number with a fresh digest, and published there (H-A-279). + if _, err := rv.r.Released(ctx, "node-tools", res.Version); err != nil { + t.Fatal(err) + } + asked, ended, said, registry = nil, nil, nil, []string{"0.1.0", "0.1.1", "0.1.2"} + raw, _ := json.Marshal(versions.ReservedVersion{V: 1, Module: "node-tools", Series: "0.1", Version: "0.1.1", Fingerprint: "fp2", + Artifacts: map[string]string{"node-tools:program": "sha256:7c9b10"}, BuiltAt: time.Now()}) + if _, err := rv.r.Store.Create(ctx, versions.ReservedKey("node-tools", "0.1"), raw); err != nil { + t.Fatal(err) + } + rv.rebuild = func(ctx context.Context, module, fp, _ string) error { + again, err := rv.Reserve(ctx, module, "0.1", []string{"node-tools:program"}, versions.Source{Fingerprint: fp, Rebuild: true}) + if err != nil { + return err + } + if err := rv.Built(ctx, module, again.Version, map[string]string{"node-tools:program": "sha256:fresh"}, nil); err != nil { + return err + } + rv.published(ctx, versions.Outcome{Name: "node-tools/program", Version: again.Version, Digest: "sha256:fresh"}) + return nil + } + cur, _, _ = rv.r.Of(ctx, "node-tools", "0.1.1") + elsewhere := held + elsewhere.Version, elsewhere.Digest = "0.1.1", "sha256:83bec1" + if err := rv.movedElsewhere(ctx, cur, versions.Judged{Elsewhere: []versions.HeldArtifact{elsewhere}}); err != nil { + t.Fatal(err) + } + again, ok, _ := rv.r.Of(ctx, "node-tools", "") + if !ok || again.Version != "0.1.3" || again.Withdrawn["0.1.1"] != "fp2" || again.Artifacts["node-tools:program"] != "sha256:fresh" { + t.Fatalf("built again as %+v, want 0.1.3 with a fresh digest and 0.1.1 withdrawn", again) + } + if len(said) != 1 || said[0].Version != "0.1.3" || said[0].Digest != "sha256:fresh" { + t.Errorf("package-published said %+v, want the fresh build at 0.1.3", said) + } + if len(asked) != 1 || asked[0] != "node-tools 0.1.3" || len(ended) != 1 || ended[0] != "node-tools 0.1.1" { + t.Errorf("asked %v, ended %v: want the new number's publish asked and the old one's item ended", asked, ended) + } + raised := "" + for _, v := range fs.vals { + raised += string(v) + } + if !strings.Contains(raised, versions.VersionHeldElsewhere) || !strings.Contains(raised, "sha256:83bec1") || !strings.Contains(raised, "sha256:7c9b10") { + t.Errorf("no version-held-elsewhere naming both digests: %s", raised) + } +} diff --git a/modules/mesh-delivery-builder/internal/build/reserve_test.go b/modules/mesh-delivery-builder/internal/build/reserve_test.go index 5d7e5009..871eede0 100644 --- a/modules/mesh-delivery-builder/internal/build/reserve_test.go +++ b/modules/mesh-delivery-builder/internal/build/reserve_test.go @@ -360,7 +360,10 @@ func (r *realReserve) Built(ctx context.Context, module, version string, digests type reserveMap struct{ *memStore } -func (m reserveMap) KeysOf(ctx context.Context, _ string) ([]string, error) { return m.Keys(ctx) } +func (m reserveMap) KeysOf(ctx context.Context, filter string) ([]string, error) { + all, err := m.Keys(ctx) + return slices.DeleteFunc(all, func(k string) bool { return !versions.FilterMatches(filter, k) }), err // as the bus reads a filter +} func (m reserveMap) Delete(_ context.Context, key string) error { m.mu.Lock() defer m.mu.Unlock() diff --git a/modules/mesh-delivery-builder/internal/versions/index.go b/modules/mesh-delivery-builder/internal/versions/index.go new file mode 100644 index 00000000..937048c5 --- /dev/null +++ b/modules/mesh-delivery-builder/internal/versions/index.go @@ -0,0 +1,190 @@ +package versions + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "slices" + "sort" +) + +// **The reservations' index by digest and by version** (design 47 H H-A-269 (1), H-A-271): beside the reservations, in the same +// state, the builder keeps which reservation keys hold a built digest and which stand at a version, so a registry seat's published +// finds its reservation in one read and a published whose digest no reservation holds is judged from its version's keys in one +// more, never a scan of every reservation. The index keys have three tokens, so the reservations' filter (two tokens) never lists +// them. It is maintained at reserve, at a digest recorded, at release and at drop; an entry left behind by a write that ended +// halfway is harmless (every read checks the reservation it names), and a missing one is written again by Reindex at the start. + +const ( + indexDigestPrefix = "index.digest." + indexVersionPrefix = "index.version." + // IndexDigestFilter and IndexVersionFilter are the filters of the index's two halves. + IndexDigestFilter = indexDigestPrefix + "*" + IndexVersionFilter = indexVersionPrefix + "*" +) + +// IndexDigestKey is the index key of the reservations holding digest as a built artifact's. +func IndexDigestKey(digest string) string { return indexDigestPrefix + EscapeToken(digest) } + +// IndexVersionKey is the index key of the reservations standing at version (MAJOR.MINOR.PATCH). +func IndexVersionKey(version string) string { return indexVersionPrefix + EscapeToken(version) } + +// IndexEntry is an index key's value: the reservation keys, sorted. +type IndexEntry struct { + Keys []string `json:"keys"` +} + +// indexed reads an index key's reservation keys. +func (r *Reserver) indexed(ctx context.Context, key string) ([]string, error) { + raw, _, found, err := r.Store.Get(ctx, key) + if err != nil || !found { + return nil, err + } + var e IndexEntry + if err := json.Unmarshal(raw, &e); err != nil { + return nil, fmt.Errorf("%s holds what is no index entry: %w", key, err) + } + return e.Keys, nil +} + +// index adds (or, with add false, removes) reserved under the index key key, by compare-and-set; an entry left empty is deleted. +func (r *Reserver) index(ctx context.Context, key, reserved string, add bool) error { + for { + raw, rev, found, err := r.Store.Get(ctx, key) + if err != nil { + return err + } + var e IndexEntry + if found { + _ = json.Unmarshal(raw, &e) + } + has := slices.Contains(e.Keys, reserved) + if has == add { + return nil + } + if add { + e.Keys = append(e.Keys, reserved) + sort.Strings(e.Keys) + } else { + e.Keys = slices.DeleteFunc(e.Keys, func(k string) bool { return k == reserved }) + } + if len(e.Keys) == 0 { + return r.Store.Delete(ctx, key) + } + out, _ := json.Marshal(e) + if found { + _, err = r.Store.Update(ctx, key, out, rev) + } else { + _, err = r.Store.Create(ctx, key, out) + } + if errors.Is(err, ErrConflict) { + continue + } + return err + } +} + +// indexKeys are the index keys a reservation stands under: its version's and each built digest's. +func indexKeys(v ReservedVersion) []string { + out := []string{} + if v.Version != "" { + out = append(out, IndexVersionKey(v.Version)) + } + for _, d := range v.Artifacts { + if d != "" && !slices.Contains(out, IndexDigestKey(d)) { + out = append(out, IndexDigestKey(d)) + } + } + return out +} + +// reindex moves reservation key from the index keys of was (its value before, zero when there was none) to those of now (zero when +// it is gone). +func (r *Reserver) reindex(ctx context.Context, key string, was, now ReservedVersion) error { + add, drop := indexKeys(now), indexKeys(was) + var errs []error + for _, k := range add { + if err := r.index(ctx, k, key, true); err != nil { + errs = append(errs, err) + } + } + for _, k := range drop { + if !slices.Contains(add, k) { + if err := r.index(ctx, k, key, false); err != nil { + errs = append(errs, err) + } + } + } + if err := errors.Join(errs...); err != nil { + return fmt.Errorf("the index of %s is not written (Reindex writes it at the start): %w", key, err) + } + return nil +} + +// AtVersion are the reservations standing at version, read through the index by version (H-A-271): one read of the index and +// one of each reservation it names. +func (r *Reserver) AtVersion(ctx context.Context, version string) ([]ReservedVersion, error) { + keys, err := r.indexed(ctx, IndexVersionKey(version)) + if err != nil { + return nil, err + } + var out []ReservedVersion + for _, k := range keys { + cur, _, found, err := r.get(ctx, k) + if err != nil { + return out, err + } + if found && cur.Version == version { + out = append(out, cur) + } + } + return out, nil +} + +// Reindex writes the index again from the reservations, once at the builder's start (H-A-269 (1), H-A-271): each reservation is +// added under its keys, and a reservation an index key names that does not stand under it (read again) is removed from it. Both +// are the same compare-and-set as every other index write, so a reservation written meanwhile keeps its entries. It answers how +// many reservations it read. +func (r *Reserver) Reindex(ctx context.Context) (int, error) { + all, err := r.All(ctx) + if err != nil { + return 0, err + } + var errs []error + for _, v := range all { + key := ReservedKey(v.Module, v.Series) + for _, k := range indexKeys(v) { + if err := r.index(ctx, k, key, true); err != nil { + errs = append(errs, err) + } + } + } + for _, filter := range []string{IndexDigestFilter, IndexVersionFilter} { + keys, err := r.Store.KeysOf(ctx, filter) + if err != nil { + return len(all), fmt.Errorf("the index cannot be listed: %w", err) + } + for _, k := range keys { + named, err := r.indexed(ctx, k) + if err != nil { + errs = append(errs, err) + continue + } + for _, rk := range named { + cur, _, found, err := r.get(ctx, rk) + if err != nil { + errs = append(errs, err) + continue + } + if found && slices.Contains(indexKeys(cur), k) { + continue + } + if err := r.index(ctx, k, rk, false); err != nil { + errs = append(errs, err) + } + } + } + } + return len(all), errors.Join(errs...) +} diff --git a/modules/mesh-delivery-builder/internal/versions/index_test.go b/modules/mesh-delivery-builder/internal/versions/index_test.go new file mode 100644 index 00000000..c31d3425 --- /dev/null +++ b/modules/mesh-delivery-builder/internal/versions/index_test.go @@ -0,0 +1,128 @@ +package versions + +import ( + "context" + "encoding/json" + "fmt" + "strings" + "sync/atomic" + "testing" +) + +// countingReserve counts the listings of the reservations and the reads of a reservation key (two tokens), so a test sees that +// a published reads its reservation and no other. +type countingReserve struct { + *reserveMem + lists, reads atomic.Int64 +} + +func (c *countingReserve) KeysOf(ctx context.Context, filter string) ([]string, error) { + c.lists.Add(1) + return c.reserveMem.KeysOf(ctx, filter) +} + +func (c *countingReserve) Get(ctx context.Context, key string) ([]byte, uint64, bool, error) { + if !strings.HasPrefix(key, "index.") { + c.reads.Add(1) + } + return c.reserveMem.Get(ctx, key) +} + +// TestTheIndexFindsAPublishedReservationInOneRead: design 47 H H-A-269 (1), H-A-271 — a registry seat's published finds its +// reservation through the index by digest, reading that reservation alone and listing none; a published whose digest no +// reservation holds is judged from its version's keys (kept on a build that recorded no digest yet, A-415), never a scan; the +// index goes with a release and a drop, and is written again at the start from reservations written before it existed. +func TestTheIndexFindsAPublishedReservationInOneRead(t *testing.T) { + ctx := context.Background() + fill := func(t *testing.T) (*Reserver, *countingReserve) { + store := &countingReserve{reserveMem: &reserveMem{mem: newMem()}} + r := &Reserver{Store: store, ReleasedOf: func(context.Context, string) ([]string, error) { return nil, nil }} + for i := range 40 { + m := fmt.Sprintf("m%02d", i) + if _, err := r.Reserve(ctx, m, "0.1", []string{m + ":a"}, Source{Fingerprint: "fp" + m}); err != nil { + t.Fatal(err) + } + if i%2 == 0 { // half are built, each with its own digest + if _, err := r.Built(ctx, m, "0.1.0", m+":a", "sha256:"+m, nil); err != nil { + t.Fatal(err) + } + } + } + store.lists.Store(0) + store.reads.Store(0) + return r, store + } + t.Run("a published by digest reads its one reservation", func(t *testing.T) { + r, store := fill(t) + marked, _, err := r.Published(ctx, "m10-a", "v0.1.0", "sha256:m10") + if err != nil || len(marked) != 1 || marked[0].Reserved.Module != "m10" || marked[0].Artifact != "m10:a" { + t.Fatalf("the published marked %+v (%v), want m10:a", marked, err) + } + if l, n := store.lists.Load(), store.reads.Load(); l != 0 || n != 1 { + t.Errorf("the published listed %d times and read %d reservations, want none listed and one read", l, n) + } + }) + t.Run("a digest no reservation holds is judged from its version's keys", func(t *testing.T) { + r, store := fill(t) + marked, kept, err := r.Published(ctx, "m11-a", "0.1.0", "sha256:early") + if err != nil || len(marked) != 0 { + t.Fatalf("an unbuilt digest marked %v (%v)", marked, err) + } + // The 20 unbuilt reservations at 0.1.0 keep it as heard (A-415); the built ones are read and left. + if len(kept) != 20 || store.lists.Load() != 0 || store.reads.Load() != 40 { + t.Errorf("kept on %d (want 20), listed %d (want 0), read %d (want the 40 at 0.1.0)", len(kept), store.lists.Load(), store.reads.Load()) + } + at, err := r.AtVersion(ctx, "0.9.9") + if err != nil || len(at) != 0 || store.lists.Load() != 0 { + t.Errorf("a version no reservation stands at answered %v (%v), listed %d", at, err, store.lists.Load()) + } + }) + t.Run("a release and a drop take the reservation out of the index", func(t *testing.T) { + r, store := fill(t) + if _, err := r.Released(ctx, "m10", "0.1.0"); err != nil { + t.Fatal(err) + } + if _, err := r.Drop(ctx, "m12", "0.1"); err != nil { + t.Fatal(err) + } + for _, k := range []string{IndexDigestKey("sha256:m10"), IndexDigestKey("sha256:m12")} { + if _, _, found, _ := store.Get(ctx, k); found { + t.Errorf("%s stands after its reservation went", k) + } + } + keys, _ := r.indexed(ctx, IndexVersionKey("0.1.0")) + for _, k := range keys { + if k == ReservedKey("m10", "0.1") || k == ReservedKey("m12", "0.1") { + t.Errorf("the version's index still names %s", k) + } + } + }) + t.Run("the index is written again at the start from the reservations", func(t *testing.T) { + store := &countingReserve{reserveMem: &reserveMem{mem: newMem()}} + r := &Reserver{Store: store} + // A reservation written before the index existed, and an index entry naming a reservation that is gone. + raw, _ := json.Marshal(ReservedVersion{V: 1, Module: "old", Series: "0.2", Version: "0.2.4", Artifacts: map[string]string{"old:a": "sha256:old"}}) + if _, err := store.Create(ctx, ReservedKey("old", "0.2"), raw); err != nil { + t.Fatal(err) + } + stale, _ := json.Marshal(IndexEntry{Keys: []string{ReservedKey("gone", "0.1")}}) + if _, err := store.Create(ctx, IndexDigestKey("sha256:gone"), stale); err != nil { + t.Fatal(err) + } + if n, err := r.Reindex(ctx); err != nil || n != 1 { + t.Fatalf("the reindex read %d reservations (%v), want 1", n, err) + } + if _, _, found, _ := store.Get(ctx, IndexDigestKey("sha256:gone")); found { + t.Error("the index entry of a reservation that is gone stands after the reindex") + } + if keys, _ := store.KeysOf(ctx, AllFilter); len(keys) != 1 { + t.Errorf("the reservations list %v: the index keys are listed among them", keys) + } + store.lists.Store(0) + store.reads.Store(0) + marked, _, err := r.Published(ctx, "old-a", "0.2.4", "sha256:old") + if err != nil || len(marked) != 1 || store.lists.Load() != 0 || store.reads.Load() != 1 { + t.Errorf("after the reindex the published marked %v (%v), listed %d, read %d", marked, err, store.lists.Load(), store.reads.Load()) + } + }) +} diff --git a/modules/mesh-delivery-builder/internal/versions/republish.go b/modules/mesh-delivery-builder/internal/versions/republish.go index bf68e038..99ba763d 100644 --- a/modules/mesh-delivery-builder/internal/versions/republish.go +++ b/modules/mesh-delivery-builder/internal/versions/republish.go @@ -5,6 +5,7 @@ import ( "encoding/json" "errors" "fmt" + "slices" "sort" "strings" "sync" @@ -33,8 +34,10 @@ const ( QueueFull = "queue full" // NotStoredWords opens what a refused artifact is said as. NotStoredWords = "not stored: " - // VerbPublish is the registry seats' verb a publish again sends. - VerbPublish = "publish" + // VerbPublish is the registry seats' verb a publish again sends, VerbVersions the one whose record says what a seat holds + // (H-A-272). + VerbPublish = "publish" + VerbVersions = "versions" ) // RepublishTransfer is a publish again's transfer name, the builder's own (the registry part's publish: the caller names its @@ -77,6 +80,9 @@ type QueuedPublish struct { Begun bool `json:"begun,omitempty"` } +// QueueFilter is the filter of every queued version: a queue key has three tokens, which AllFilter (two) never lists on the bus. +const QueueFilter = "*.*.*" + // QueueKey is the key of holder's queued version of module. func QueueKey(holder, module, version string) string { return EscapeToken(holder) + "." + EscapeToken(module) + "." + EscapeToken(version) @@ -402,7 +408,7 @@ const PublishAgainDescription = "Publish reserved versions again (design 47 G se // Resume takes up, at the builder's start, every queued version again, a begun one sent anew (§588). func (r *Republisher) Resume(ctx context.Context) error { - keys, err := r.Queue.KeysOf(ctx, AllFilter) + keys, err := r.Queue.KeysOf(ctx, QueueFilter) if err != nil { return fmt.Errorf("the state %s cannot be listed: %w", PublishQueueState, err) } @@ -501,25 +507,11 @@ func (r *Republisher) send(ctx context.Context, q QueuedPublish) { } sort.Strings(refs) for _, ref := range refs { - var art *meshcatalog.Artifact - for i := range e.Artifacts { - if e.Artifacts[i].Ref == ref { - art = &e.Artifacts[i] - } - } - seat, ok := "", false - if art != nil { - seat, ok = SeatOfArtifact(*art) - } + seat, name, kind, ok := publishTarget(e, q.Module, ref) if !ok { r.say(ctx, v, ref+": the catalog entry names no registry seat for it") return } - name := NameOf(q.Module, strings.TrimPrefix(ref, q.Module+":")) - if art.Package != nil && art.Package.Name != "" { - name = art.Package.Name - } - kind := art.Kind bound, cancel := context.WithTimeout(ctx, UnreleasedBound) // a context's bound, no timer (ADR 0437 §8) err := r.Send(bound, Publish{Seat: seat, Kind: kind, Name: name, Version: v.Version, Digest: q.Artifacts[ref], Fingerprint: v.Fingerprint, Commit: v.Commit, Transfer: RepublishTransfer(q.Module, v.Version, strings.TrimPrefix(ref, q.Module+":"))}) @@ -543,6 +535,28 @@ func (r *Republisher) send(ctx context.Context, q QueuedPublish) { } } +// publishTarget is the registry seat, the name and the kind module's artifact ref is published as, from its catalog entry; ok is +// false when the entry names no registry seat for it. +func publishTarget(e meshcatalog.CatalogEntry, module, ref string) (seat, name, kind string, ok bool) { + var art *meshcatalog.Artifact + for i := range e.Artifacts { + if e.Artifacts[i].Ref == ref { + art = &e.Artifacts[i] + } + } + if art == nil { + return "", "", "", false + } + if seat, ok = SeatOfArtifact(*art); !ok { + return "", "", "", false + } + name = NameOf(module, strings.TrimPrefix(ref, module+":")) + if art.Package != nil && art.Package.Name != "" { + name = art.Package.Name + } + return seat, name, art.Kind, true +} + func (r *Republisher) say(ctx context.Context, v ReservedVersion, why string) { r.logf("%s %s is not published again: %s", v.Module, v.Version, why) if r.Unreleased != nil { @@ -579,3 +593,105 @@ func (r *Reserver) MarkUnstored(ctx context.Context, module, version, artifact, return true, nil } } + +// UnheardBound is how many messages the builder's durable on the events stream may hold pending and unacknowledged while a +// publish is asked again (design 47 H H-A-269 (2), H-A-272): at or above it a published of the version may still be unheard, so +// the try is skipped. A constant of the builder, no setting. +const UnheardBound = 100 + +// HeldVersion is one version a registry seat's verb versions answers of a name, with its digest. +type HeldVersion struct { + Version, Digest string +} + +// HeldArtifact is an artifact of a reservation as a registry seat's record holds it at the reservation's version: its reference, +// the seat and the name it is published as, the version and the digest the seat holds. +type HeldArtifact struct { + Ref, Seat, Name, Version, Digest string +} + +// Judged is what the registries' record says of a reserved version's missing artifacts (design 47 H H-A-272, H-A-274, H-A-275): +// those held at the version with the built digest (Held), those held at the version with another digest (Elsewhere), and, when an +// artifact is held at neither, the first one lacking (Lacks). All says every missing artifact is held with its built digest. +type Judged struct { + Held, Elsewhere []HeldArtifact + Lacks string + All bool +} + +// Held judges v's missing artifacts against the registries' record (design 47 H H-A-269 (2), H-A-272, H-A-274, H-A-275): each +// artifact's registry seat and name as a publish again sends them, its record read through the seat's verb versions (versionsOf). +// A version with no missing artifact is All. +func (r *Republisher) Held(ctx context.Context, v ReservedVersion, versionsOf func(ctx context.Context, seat, name string) ([]HeldVersion, error)) (Judged, error) { + missing := v.Missing() + if len(missing) == 0 { + return Judged{All: true}, nil + } + e, err := r.Entry(ctx, v.Fingerprint) + if err != nil { + return Judged{}, fmt.Errorf("the catalog entry %s of %s %s cannot be read: %w", v.Fingerprint, v.Module, v.Version, err) + } + var out Judged + for _, ref := range missing { + seat, name, _, ok := publishTarget(e, v.Module, ref) + if !ok { + if out.Lacks == "" { + out.Lacks = ref + ": the catalog entry names no registry seat for it" + } + continue + } + held, err := versionsOf(ctx, seat, name) + if err != nil { + return Judged{}, fmt.Errorf("%s's versions of %s cannot be read: %w", seat, name, err) + } + at, found := HeldArtifact{}, false + for _, h := range held { + if strings.TrimPrefix(h.Version, "v") != v.Version { + continue + } + at, found = HeldArtifact{Ref: ref, Seat: seat, Name: name, Version: h.Version, Digest: h.Digest}, true + if h.Digest == v.Artifacts[ref] { + break + } + } + switch { + case !found: + if out.Lacks == "" { + out.Lacks = fmt.Sprintf("%s holds no %s %s", seat, name, v.Version) + } + case at.Digest == v.Artifacts[ref]: + out.Held = append(out.Held, at) + default: + out.Elsewhere = append(out.Elsewhere, at) + } + } + out.All = len(out.Held) == len(missing) + return out, nil +} + +// HeldNumbers are the versions (MAJOR.MINOR.PATCH) a registry seat's record holds of any of module's artifacts refs, as the catalog +// entry of fingerprint names their seats and names (design 47 H H-A-275): a number one holds is never reserved. An artifact the +// entry names no registry seat for is read nowhere. +func (r *Republisher) HeldNumbers(ctx context.Context, module, fingerprint string, refs []string, versionsOf func(ctx context.Context, seat, name string) ([]HeldVersion, error)) ([]string, error) { + e, err := r.Entry(ctx, fingerprint) + if err != nil { + return nil, fmt.Errorf("the catalog entry %s of %s cannot be read: %w", fingerprint, module, err) + } + var out []string + for _, ref := range refs { + seat, name, _, ok := publishTarget(e, module, ref) + if !ok { + continue + } + held, err := versionsOf(ctx, seat, name) + if err != nil { + return out, fmt.Errorf("%s's versions of %s cannot be read: %w", seat, name, err) + } + for _, h := range held { + if v := strings.TrimPrefix(h.Version, "v"); v != "" && !slices.Contains(out, v) { + out = append(out, v) + } + } + } + return out, nil +} diff --git a/modules/mesh-delivery-builder/internal/versions/republish_test.go b/modules/mesh-delivery-builder/internal/versions/republish_test.go index 72541453..642be137 100644 --- a/modules/mesh-delivery-builder/internal/versions/republish_test.go +++ b/modules/mesh-delivery-builder/internal/versions/republish_test.go @@ -196,3 +196,42 @@ func TestRepublish(t *testing.T) { } }) } + +// TestTheRegistriesRecordSaysWhetherAVersionIsHeld: design 47 H H-A-272, H-A-274, H-A-275 — a missing artifact its registry seat +// holds at the version (the Go form too) with the built digest is held; at the version with another digest it is held elsewhere; +// a version the seat lacks is said by name. The numbers a registry holds of the module's artifacts are what reserving skips. +func TestTheRegistriesRecordSaysWhetherAVersionIsHeld(t *testing.T) { + ctx := context.Background() + entry := meshcatalog.CatalogEntry{Artifacts: []meshcatalog.Artifact{{Ref: "m:lib", Kind: "package", Language: "go", Package: &meshcatalog.ArtifactPackage{Ecosystem: "go", Name: "git.example/m"}}}} + r := &Republisher{Entry: func(context.Context, string) (meshcatalog.CatalogEntry, error) { return entry, nil }} + v := ReservedVersion{Module: "m", Version: "0.1.37", Fingerprint: "fp", Artifacts: map[string]string{"m:lib": "sha256:a"}} + for _, c := range []struct { + name string + holds []HeldVersion + all, elsewhere, lacks bool + }{ + {name: "held in the Go form with the built digest", holds: []HeldVersion{{Version: "v0.1.36", Digest: "sha256:z"}, {Version: "v0.1.37", Digest: "sha256:a"}}, all: true}, + {name: "another digest at the version", holds: []HeldVersion{{Version: "0.1.37", Digest: "sha256:b"}}, elsewhere: true}, + {name: "the version lacked", holds: []HeldVersion{{Version: "0.1.36", Digest: "sha256:a"}}, lacks: true}, + } { + t.Run(c.name, func(t *testing.T) { + var seat, name string + versionsOf := func(_ context.Context, s, n string) ([]HeldVersion, error) { seat, name = s, n; return c.holds, nil } + j, err := r.Held(ctx, v, versionsOf) + if err != nil || j.All != c.all || (len(j.Elsewhere) == 1) != c.elsewhere || (j.Lacks != "") != c.lacks || seat != SeatGoPackages || name != "git.example/m" { + t.Fatalf("judged %+v (%v) asking %s for %s, want all %v, elsewhere %v, lacks %v asking %s for git.example/m", j, err, seat, name, c.all, c.elsewhere, c.lacks, SeatGoPackages) + } + if c.lacks && !strings.Contains(j.Lacks, "0.1.37") { + t.Errorf("what the registry lacks is said as %q", j.Lacks) + } + nums, err := r.HeldNumbers(ctx, "m", "fp", []string{"m:lib"}, versionsOf) + if err != nil || len(nums) != len(c.holds) { + t.Errorf("the held numbers are %v (%v), want one per version the seat holds", nums, err) + } + }) + } + v.Published = map[string]bool{"m:lib": true} + if j, err := r.Held(ctx, v, nil); err != nil || !j.All { + t.Errorf("a version with no missing artifact is judged %+v (%v), want all held without a read", j, err) + } +} diff --git a/modules/mesh-delivery-builder/internal/versions/reserve.go b/modules/mesh-delivery-builder/internal/versions/reserve.go index fcae79ec..7fcbaf71 100644 --- a/modules/mesh-delivery-builder/internal/versions/reserve.go +++ b/modules/mesh-delivery-builder/internal/versions/reserve.go @@ -37,6 +37,9 @@ const ( UnreleasedBound = 10 * time.Minute // VersionUnreleased is that finding. VersionUnreleased = "version-unreleased" + // VersionHeldElsewhere is the finding of a number a registry seat already holds, skipped at reserving or moved from (design 47 + // H H-A-275), scope module. + VersionHeldElsewhere = "version-held-elsewhere" ) // ReservedVersion is the value of a reservation key. @@ -135,6 +138,50 @@ type Reserver struct { // DefaultReleasedKept. ReleasedKept int Now func() time.Time + // Logf says an index write that failed (H-A-269 (1)): the reservation stands, and Reindex writes its index at the next + // start. Nil says nothing. + Logf func(string, ...any) + // HeldNumbers are the versions a registry seat's record holds of any of module's artifacts (design 47 H H-A-275), read before a + // number is reserved: a number one holds is skipped. Nil reads none; a read that fails is said and the reserve proceeds. + HeldNumbers func(ctx context.Context, module, fingerprint string, refs []string) ([]string, error) + // HeldElsewhere is told the numbers of module a reserve skipped because a registry holds them (H-A-275); nil is told none. + HeldElsewhere func(ctx context.Context, module string, skipped []string) +} + +// heldNumbers are the patches of series a registry holds of module's artifacts (H-A-275); a read that fails is said, and none. +func (r *Reserver) heldNumbers(ctx context.Context, module, series, fingerprint string, refs []string) map[int]bool { + if r.HeldNumbers == nil { + return nil + } + vs, err := r.HeldNumbers(ctx, module, fingerprint, refs) + if err != nil { + r.said(fmt.Errorf("%s: the registries' versions are not read before reserving, so a number they hold is not skipped: %w", module, err)) + } + out := map[int]bool{} + for _, v := range vs { + if s, p, err := SplitVersion(v); err == nil && s == series { + out[p] = true + } + } + return out +} + +// nextFree is the first patch after after that no registry holds, and the held numbers it skipped (H-A-275). +func nextFree(series string, after int, held map[int]bool) (int, []string) { + var skipped []string + p := after + 1 + for held[p] { + skipped = append(skipped, fmt.Sprintf("%s.%d", series, p)) + p++ + } + return p, skipped +} + +// said is told the outcome of a reindex: a failure is said, the reservation's own write stands. +func (r *Reserver) said(err error) { + if err != nil && r.Logf != nil { + r.Logf("%v", err) + } } func (r *Reserver) now() time.Time { @@ -178,23 +225,26 @@ func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts } } key := ReservedKey(module, series) + held := r.heldNumbers(ctx, module, series, src.Fingerprint, artifacts) for { cur, rev, found, err := r.get(ctx, key) if err != nil { return ReservedVersion{}, err } - if found && cur.Fingerprint == src.Fingerprint && cur.Fingerprint != "" && !slices.Contains(released, cur.Version) { + withdrawn := found && hasKey(cur.Withdrawn, cur.Version) // a number a registry holds elsewhere (H-A-279) + if found && !withdrawn && cur.Fingerprint == src.Fingerprint && cur.Fingerprint != "" && !slices.Contains(released, cur.Version) { if _, p, err := SplitVersion(cur.Version); err == nil && p > high { return cur, nil // kept until released (H-A-225); one at or below the catalog's highest can never be released } } next := high - if found && !(src.Rebuild && cur.Fingerprint == src.Fingerprint) { + if found && (withdrawn || !(src.Rebuild && cur.Fingerprint == src.Fingerprint)) { // a withdrawn number is never taken again (H-A-226) if _, p, err := SplitVersion(cur.Version); err == nil && p > next { next = p } } - out := ReservedVersion{V: 1, Module: module, Series: series, Version: fmt.Sprintf("%s.%d", series, next+1), Artifacts: map[string]string{}, At: r.now(), + patch, skipped := nextFree(series, next, held) + out := ReservedVersion{V: 1, Module: module, Series: series, Version: fmt.Sprintf("%s.%d", series, patch), Artifacts: map[string]string{}, At: r.now(), Repository: src.Repository, Commit: src.Commit, Fingerprint: src.Fingerprint, Branch: src.Branch, Source: src.Revision, Revision: src.CatalogRevision} if src.GoPackage { out.Tag = GoTagOf(out.Version) @@ -231,6 +281,10 @@ func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts if err != nil { return ReservedVersion{}, fmt.Errorf("%s cannot be reserved: %w", key, err) } + r.said(r.reindex(ctx, key, cur, out)) // cur is zero when there was none + if len(skipped) > 0 && r.HeldElsewhere != nil { + r.HeldElsewhere(ctx, module, skipped) + } if found && r.Took != nil { r.Took(ctx, cur, out) } @@ -250,6 +304,38 @@ func (r *Reserver) get(ctx context.Context, key string) (ReservedVersion, uint64 return v, rev, true, nil } +// Withdraw withdraws module's reservation of version for the build of its fingerprint, whose number a registry holds at another +// digest (design 47 H H-A-275, H-A-279): the number is kept in Withdrawn and stays a gap (H-A-226), so the build again of that +// fingerprint reserves the next number no registry holds, with fresh digests. It answers the reservation as withdrawn, and false +// when none stands at version. +func (r *Reserver) Withdraw(ctx context.Context, module, version string) (ReservedVersion, bool, error) { + series, _, err := SplitVersion(version) + if err != nil { + return ReservedVersion{}, false, err + } + key := ReservedKey(module, series) + for { + cur, rev, found, err := r.get(ctx, key) + if err != nil || !found || cur.Version != version { + return cur, false, err + } + if hasKey(cur.Withdrawn, version) { + return cur, true, nil + } + if cur.Withdrawn == nil { + cur.Withdrawn = map[string]string{} + } + cur.Withdrawn[version] = cur.Fingerprint + raw, _ := json.Marshal(cur) + if _, err := r.Store.Update(ctx, key, raw, rev); errors.Is(err, ErrConflict) { + continue + } else if err != nil { + return cur, false, fmt.Errorf("%s cannot be withdrawn: %w", key, err) + } + return cur, true, nil + } +} + // Built records artifact's digest under the reserved version of module's series; once every artifact has one the build is // ended (BuiltAt). A reservation moved on to another version (a newer build took the next) is left alone and answers false. func (r *Reserver) Built(ctx context.Context, module, version, artifact, digest string, deps []meshbuilds.Dependency) (bool, error) { @@ -263,6 +349,8 @@ func (r *Reserver) Built(ctx context.Context, module, version, artifact, digest if err != nil || !found || cur.Version != version { return false, err } + was := cur + was.Artifacts = maps.Clone(cur.Artifacts) cur.Artifacts[artifact] = digest if len(deps) > 0 { if cur.Dependencies == nil { @@ -279,6 +367,7 @@ func (r *Reserver) Built(ctx context.Context, module, version, artifact, digest } else if err != nil { return false, fmt.Errorf("%s cannot be written: %w", key, err) } + r.said(r.reindex(ctx, key, was, cur)) return true, nil } } @@ -397,6 +486,7 @@ func (r *Reserver) Released(ctx context.Context, module, version string) ([]stri if err := r.Store.Delete(ctx, k); err != nil { return gone, fmt.Errorf("%s cannot be deleted: %w", k, err) } + r.said(r.reindex(ctx, k, cur, ReservedVersion{})) gone = append(gone, k) } sort.Strings(gone) @@ -484,11 +574,15 @@ func (r *Reserver) TakenOver(ctx context.Context, module, fingerprint string) (R // log. It answers whether there was one. func (r *Reserver) Drop(ctx context.Context, module, series string) (bool, error) { key := ReservedKey(module, series) - _, _, found, err := r.get(ctx, key) + cur, _, found, err := r.get(ctx, key) if err != nil || !found { return false, err } - return true, r.Store.Delete(ctx, key) + if err := r.Store.Delete(ctx, key); err != nil { + return true, err + } + r.said(r.reindex(ctx, key, cur, ReservedVersion{})) + return true, nil } // Marked is an artifact of a reservation a registry seat's published newly marked: the reservation as it stands then. @@ -511,29 +605,47 @@ func (m Marked) PackagePublished(digest string, at time.Time) meshbuilds.Package // whose built digest it names are marked published. It answers each artifact it newly marked, with the reservation as marked. // A published that marks no artifact of a reservation at version whose build has not recorded every digest is kept on that // reservation as heard (name, version, digest), and the keys it is kept on are answered too (design 47 G A-415): Kept marks -// it when the build records its digests. +// it when the build records its digests. The reservation is found through the index (H-A-269 (1), H-A-271): the reservations +// holding the digest in one read, and only when none holds it at version, those standing at the version in one more; never a +// scan of every reservation. func (r *Reserver) Published(ctx context.Context, name, version, digest string) ([]Marked, []string, error) { version = strings.TrimPrefix(version, "v") if version == "" || digest == "" { return nil, nil, nil } - keys, err := r.Store.KeysOf(ctx, AllFilter) + keys, err := r.indexed(ctx, IndexDigestKey(digest)) if err != nil { - return nil, nil, fmt.Errorf("the reservations cannot be listed: %w", err) + return nil, nil, fmt.Errorf("the index of digest %s cannot be read: %w", digest, err) } - sort.Strings(keys) + marked, kept, matched, err := r.publishedOn(ctx, keys, name, version, digest, false) + if err != nil || matched { + return marked, kept, err + } + keys, err = r.indexed(ctx, IndexVersionKey(version)) + if err != nil { + return marked, kept, fmt.Errorf("the index of version %s cannot be read: %w", version, err) + } + m, k, _, err := r.publishedOn(ctx, keys, name, version, digest, true) + return append(marked, m...), append(kept, k...), err +} + +// publishedOn takes a published in on the reservations under keys: an artifact whose built digest it names is marked; with keep, +// a reservation at version whose build has not recorded every digest and that it matches nothing of keeps it (A-415). It also +// answers whether a reservation at version holds the digest. +func (r *Reserver) publishedOn(ctx context.Context, keys []string, name, version, digest string, keep bool) ([]Marked, []string, bool, error) { var marked []Marked var kept []string + anyMatched := false for _, k := range keys { again: cur, rev, found, err := r.get(ctx, k) if err != nil { - return marked, kept, err + return marked, kept, anyMatched, err } if !found || cur.Version != version { continue } - changed, matched, keep := false, false, false + changed, matched, keepIt := false, false, false var arts []string for a, d := range cur.Artifacts { if d != digest { @@ -548,10 +660,11 @@ func (r *Reserver) Published(ctx context.Context, name, version, digest string) arts = append(arts, a) } } + anyMatched = anyMatched || matched sort.Strings(arts) - if !matched && cur.BuiltAt.IsZero() && !cur.keeps(name, digest) { + if keep && !matched && cur.BuiltAt.IsZero() && !cur.keeps(name, digest) { cur.Kept = append(cur.Kept, KeptPublished{Name: name, Version: version, Digest: digest}) - changed, keep = true, true + changed, keepIt = true, true } if !changed { continue @@ -560,16 +673,16 @@ func (r *Reserver) Published(ctx context.Context, name, version, digest string) if _, err := r.Store.Update(ctx, k, raw, rev); errors.Is(err, ErrConflict) { goto again } else if err != nil { - return marked, kept, fmt.Errorf("%s cannot be written: %w", k, err) + return marked, kept, anyMatched, fmt.Errorf("%s cannot be written: %w", k, err) } for _, a := range arts { marked = append(marked, Marked{Reserved: cur, Artifact: a}) } - if keep { + if keepIt { kept = append(kept, k) } } - return marked, kept, nil + return marked, kept, anyMatched, nil } func (v ReservedVersion) keeps(name, digest string) bool { diff --git a/modules/mesh-delivery-builder/internal/versions/reserve_test.go b/modules/mesh-delivery-builder/internal/versions/reserve_test.go index e6d41e02..dbe5b5ba 100644 --- a/modules/mesh-delivery-builder/internal/versions/reserve_test.go +++ b/modules/mesh-delivery-builder/internal/versions/reserve_test.go @@ -297,3 +297,52 @@ func TestARebuildReservesAboveTheCatalogsHighestWhateverItsStandingNumberWas(t * }) } } + +// TestANumberARegistryHoldsIsNeverReserved: design 47 H H-A-275 (the rule of H-A-245 for a registry's record) — a reserve skips +// every number a registry seat holds of the module's artifacts and says the skipped ones; a read that fails lets it proceed; a +// done build whose number a registry holds at another digest has it withdrawn as a gap (H-A-226), and its build again reserves the +// next free number with fresh digests (H-A-279), the index following it. +func TestANumberARegistryHoldsIsNeverReserved(t *testing.T) { + ctx := context.Background() + store := &reserveMem{mem: newMem()} + held := []string{"0.1.37", "0.1.38", "0.2.0"} + var readErr error + var skipped []string + r := &Reserver{Store: store, ReleasedOf: func(context.Context, string) ([]string, error) { return []string{"0.1.36"}, nil }, + HeldNumbers: func(_ context.Context, module, fp string, refs []string) ([]string, error) { + if module != "node-tools" || fp != "fp1" || len(refs) != 1 { + t.Errorf("the registries are read for %s %s %v", module, fp, refs) + } + return held, readErr + }, + HeldElsewhere: func(_ context.Context, _ string, s []string) { skipped = append(skipped, s...) }} + v, err := r.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, Source{Fingerprint: "fp1", GoPackage: true}) + if err != nil || v.Version != "0.1.39" || len(skipped) != 2 { + t.Fatalf("reserved %q (%v), skipped %v: want 0.1.39 past the two numbers the registry holds", v.Version, err, skipped) + } + // The build ends; the registry holds 0.1.39 at another digest meanwhile: the number is withdrawn, and the build again of the same + // fingerprint reserves the next number no registry holds, with no digest yet (H-A-279). + if _, err := r.Built(ctx, "node-tools", "0.1.39", "node-tools:program", "sha256:7c9b10", nil); err != nil { + t.Fatal(err) + } + if w, ok, err := r.Withdraw(ctx, "node-tools", "0.1.39"); err != nil || !ok || w.Withdrawn["0.1.39"] != "fp1" { + t.Fatalf("withdrew %+v (%v %v), want 0.1.39 withdrawn for fp1", w, ok, err) + } + held = []string{"0.1.37", "0.1.38", "0.1.39", "0.1.40", "0.2.0"} + // The build again of a done key reserves as a rebuild (A-490b): a withdrawn number is never its floor's to reuse. + again, err := r.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, Source{Fingerprint: "fp1", GoPackage: true, Rebuild: true}) + if err != nil || again.Version != "0.1.41" || again.Artifacts["node-tools:program"] != "" || again.Withdrawn["0.1.39"] != "fp1" || again.Tag != GoTagOf("0.1.41") { + t.Fatalf("the build again reserved %+v (%v), want 0.1.41 with no digest and 0.1.39 kept withdrawn", again, err) + } + if at, _ := r.AtVersion(ctx, "0.1.39"); len(at) != 0 { + t.Errorf("the index by version still names the withdrawn number: %v", at) + } + if _, ok, _ := r.Withdraw(ctx, "node-tools", "0.1.39"); ok { + t.Error("a number no reservation stands at any more was withdrawn") + } + // A registry that cannot be read lets the reserve proceed. + readErr, skipped = errors.New("registry down"), nil + if v, err := r.Reserve(ctx, "node-tools", "0.2", []string{"node-tools:program"}, Source{Fingerprint: "fp1"}); err != nil || v.Version != "0.2.1" { + t.Errorf("with the registry down reserved %q (%v), want 0.2.1 (what it answered still skipped)", v.Version, err) + } +} diff --git a/modules/mesh-delivery-builder/internal/versions/store.go b/modules/mesh-delivery-builder/internal/versions/store.go index 66fb89fe..5cdb30ca 100644 --- a/modules/mesh-delivery-builder/internal/versions/store.go +++ b/modules/mesh-delivery-builder/internal/versions/store.go @@ -4,12 +4,28 @@ import ( "context" "errors" "fmt" + "strings" "time" ) // AllFilter is the key filter of every version of every name: two tokens. const AllFilter = "*.*" +// FilterMatches says whether key is under filter as the bus reads a key filter: token by token, a `*` any one token, so AllFilter +// lists the two-token keys alone and never the index's three-token keys (H-A-269 (1)). +func FilterMatches(filter, key string) bool { + ft, kt := strings.Split(filter, "."), strings.Split(key, ".") + if len(ft) != len(kt) { + return false + } + for i := range ft { + if ft[i] != "*" && ft[i] != kt[i] { + return false + } + } + return true +} + // ErrConflict is what a Store answers when a Create finds the key or an Update finds another revision. var ErrConflict = errors.New("the key exists or changed") diff --git a/modules/mesh-delivery-builder/internal/versions/tools.go b/modules/mesh-delivery-builder/internal/versions/tools.go index 09ef4f7a..990dacbc 100644 --- a/modules/mesh-delivery-builder/internal/versions/tools.go +++ b/modules/mesh-delivery-builder/internal/versions/tools.go @@ -45,13 +45,9 @@ func (s readStore) KeysOf(_ context.Context, filter string) ([]string, error) { if err != nil { return nil, err } - if filter == AllFilter { - return all, nil - } - prefix := strings.TrimSuffix(filter, "*") var out []string for _, k := range all { - if strings.HasPrefix(k, prefix) && !strings.Contains(k[len(prefix):], ".") { + if FilterMatches(filter, k) { out = append(out, k) } } diff --git a/modules/mesh-delivery-builder/internal/versions/versions_test.go b/modules/mesh-delivery-builder/internal/versions/versions_test.go index 4999f0b6..5d464da2 100644 --- a/modules/mesh-delivery-builder/internal/versions/versions_test.go +++ b/modules/mesh-delivery-builder/internal/versions/versions_test.go @@ -66,21 +66,9 @@ func (m *mem) KeysOf(_ context.Context, filter string) ([]string, error) { if m.down != nil { return nil, m.down } - prefix := strings.TrimSuffix(filter, "*") var out []string for k := range m.vals { - if filter == AllFilter { - out = append(out, k) - continue - } - if strings.Count(filter, ".") == 2 { // a three-token filter, `a.*.*` as the bus reads it - ft, kt := strings.Split(filter, "."), strings.Split(k, ".") - if len(kt) == 3 && kt[0] == ft[0] { - out = append(out, k) - } - continue - } - if strings.HasPrefix(k, prefix) && !strings.Contains(k[len(prefix):], ".") { + if FilterMatches(filter, k) { // token by token, as the bus reads a filter out = append(out, k) } }