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 b7068896..bfcdee6f 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go @@ -277,6 +277,11 @@ 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()), + held: func(ctx context.Context, v versions.ReservedVersion) (bool, string, error) { + return republish.Held(ctx, v, registryVersionsVia(calls.Call)) + }, 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..11e7330b 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,16 @@ 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) + // held says whether the registries' own record holds every missing artifact of a version at it with its built digest, and + // when not, what one lacks (H-A-269 (2), H-A-272); nil holds none. + held func(ctx context.Context, v versions.ReservedVersion) (bool, string, 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 +144,10 @@ 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 := p.notAgain(ctx, v); why != "" { + // A published of the version may be unheard, or the registry holds it already: no ask, and no try spent (H-A-272). + 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 +164,74 @@ 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): 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, so its published is on its way. 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) string { + 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) + } + } + if p.held != nil { + held, lacks, err := p.held(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 held: + return "the registries hold every missing artifact at " + v.Version + " with its built digest, its published is on its way" + default: + p.logf("%s %s: asked again: %s", v.Module, v.Version, lacks) + } + } + return "" +} + +// 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..11717c6e 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,54 @@ func TestThePublishItemsAreWiredToTheReservationsAndTheReAskWatch(t *testing.T) t.Errorf("a dropped reservation kept its item") } } + +// TestAPublishIsNotAskedAgainWhileItsPublishedMayBeUnheard: design 47 H H-A-269 (2), H-A-272 — 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 +// skipped try asks nothing, 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:a"}, BuiltAt: now} + for _, c := range []struct { + name string + unheard int + countErr error + held bool + wantAsked 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: no ask", unheard: versions.UnheardBound - 1, held: true}, + {name: "heard up, the registry lacks it: asked", unheard: 3, wantAsked: true}, + {name: "the count unreadable, the registry lacks it: asked", countErr: errors.New("no consumer"), wantAsked: true}, + } { + t.Run(c.name, func(t *testing.T) { + kv := &itemKV{vals: map[string][]byte{}, revs: map[string]uint64{}} + asked, heldRead := 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 }, + held: func(context.Context, versions.ReservedVersion) (bool, string, error) { + heldRead++ + return c.held, "the registry holds no node-tools 0.1.37", 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())) + got := decodeItem(t, kv.vals[key]) + if (asked == 1) != c.wantAsked || got.Tries != map[bool]int{true: 1, false: 0}[c.wantAsked] { + t.Errorf("asked %d times, tries %d; want asked %v", asked, got.Tries, c.wantAsked) + } + if !got.NextTry.After(now) { + t.Errorf("the item's next try %s is not after now: it is not written again with its pause", got.NextTry) + } + if c.unheard >= versions.UnheardBound && heldRead != 0 { + t.Error("the registry is read while a published may be unheard") + } + }) + } +} diff --git a/modules/mesh-delivery-builder/internal/versions/republish.go b/modules/mesh-delivery-builder/internal/versions/republish.go index a04b963f..c07a82fe 100644 --- a/modules/mesh-delivery-builder/internal/versions/republish.go +++ b/modules/mesh-delivery-builder/internal/versions/republish.go @@ -33,8 +33,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 @@ -504,25 +506,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+":"))}) @@ -546,6 +534,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 { @@ -582,3 +592,49 @@ 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 +} + +// Held says whether the registries hold every artifact of v no published marked yet, at its version with its built digest +// (design 47 H H-A-269 (2), H-A-272): each artifact's registry seat and name as a publish again sends them, its record read +// through the seat's verb versions (versionsOf). It answers, when it does not, the first artifact the registry lacks. A +// version with no missing artifact is held. +func (r *Republisher) Held(ctx context.Context, v ReservedVersion, versionsOf func(ctx context.Context, seat, name string) ([]HeldVersion, error)) (bool, string, error) { + missing := v.Missing() + if len(missing) == 0 { + return true, "", nil + } + e, err := r.Entry(ctx, v.Fingerprint) + if err != nil { + return false, "", fmt.Errorf("the catalog entry %s of %s %s cannot be read: %w", v.Fingerprint, v.Module, v.Version, err) + } + for _, ref := range missing { + seat, name, _, ok := publishTarget(e, v.Module, ref) + if !ok { + return false, ref + ": the catalog entry names no registry seat for it", nil + } + held, err := versionsOf(ctx, seat, name) + if err != nil { + return false, "", fmt.Errorf("%s's versions of %s cannot be read: %w", seat, name, err) + } + found := false + for _, h := range held { + if strings.TrimPrefix(h.Version, "v") == v.Version && h.Digest == v.Artifacts[ref] { + found = true + break + } + } + if !found { + return false, fmt.Sprintf("%s holds no %s %s with digest %s", seat, name, v.Version, v.Artifacts[ref]), nil + } + } + return true, "", 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..96533a4a 100644 --- a/modules/mesh-delivery-builder/internal/versions/republish_test.go +++ b/modules/mesh-delivery-builder/internal/versions/republish_test.go @@ -196,3 +196,37 @@ func TestRepublish(t *testing.T) { } }) } + +// TestTheRegistriesRecordSaysWhetherAVersionIsHeld: design 47 H H-A-272 — every missing artifact held by its registry seat at the +// version (the Go form too) with the built digest is held; another digest, or a version the seat lacks, is not, said by name. +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 + want bool + asked string + }{ + {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"}}, want: true}, + {name: "another digest at the version", holds: []HeldVersion{{Version: "0.1.37", Digest: "sha256:b"}}}, + {name: "the version lacked", holds: []HeldVersion{{Version: "0.1.36", Digest: "sha256:a"}}}, + } { + t.Run(c.name, func(t *testing.T) { + var seat, name string + held, lacks, err := r.Held(ctx, v, func(_ context.Context, s, n string) ([]HeldVersion, error) { seat, name = s, n; return c.holds, nil }) + if err != nil || held != c.want || seat != SeatGoPackages || name != "git.example/m" { + t.Fatalf("held %v (%v) asking %s for %s, want %v asking %s for git.example/m", held, err, seat, name, c.want, SeatGoPackages) + } + if !held && !strings.Contains(lacks, "0.1.37") { + t.Errorf("what the registry lacks is said as %q", lacks) + } + }) + } + v.Published = map[string]bool{"m:lib": true} + if held, _, err := r.Held(ctx, v, nil); err != nil || !held { + t.Errorf("a version with no missing artifact is held %v (%v), want held without a read", held, err) + } +}