Files
mesh-delivery/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reserve.go
T
jschoubben 744204c5ab Builder: releases heard wake the package wait; its setting package-wait-minutes (H-A-165)
The process tells the builder each version-released it takes in and
gives it the newest release its record keeps, so an unpinned package's
step ask wakes on the event and pins the release; the wait's bound is
the setting package-wait-minutes (default 10), carried as a file under
the state dir like revision-wait-minutes.

Builds: design 47 H H-A-165, H-A-156, H-A-155
2026-11-20 17:37:25 +01:00

392 lines
18 KiB
Go

package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds"
"strings"
"sync/atomic"
"time"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/git"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"mesh-delivery-builder/internal/build"
"mesh-delivery-builder/internal/versions"
)
// The reservations (design 47 G §369): the builder's state reserved, the catalog's versions it numbers from, and the
// catalog's version-released and versions-filled it hears.
// awaitedReserved is the state reserved as versions.ReserveStore: bound once the bus holds it.
type awaitedReserved struct{ awaitedVersions }
func (s awaitedReserved) Delete(ctx context.Context, key string) error {
kv, err := s.kv()
if err != nil {
return err
}
if err := kv.Delete(ctx, key); err != nil && !errors.Is(err, jetstream.ErrKeyNotFound) {
return err
}
return nil
}
// reservations is the builder's reserving: the Reserver, the fill the catalog said, the bounds of a built reservation's
// publish and the findings.
type reservations struct {
r *versions.Reserver
// built asks a done build's publish (design 47 G A-457a), released ends its item; nil are none.
built func(ctx context.Context, module, version string) error
released func(ctx context.Context, module, version string)
// heardReleased is told each version-released taken in (design 47 H H-A-165): a step ask waiting for a package of the
// module wakes. Nil tells nobody.
heardReleased func(module, version string)
filled atomic.Bool
bounds func() jetstream.KeyValue
found *findings
bound time.Duration
wake func(context.Context)
logf func(string, ...any)
// call asks a seat's verb: the git seat's tag (design 47 G §370).
call toolCaller
// say says package-published on the seat mesh-builds; nil says none.
say func(context.Context, meshbuilds.PackagePublished) error
}
// newReservations makes the reserving over store; the released versions of a module are asked of the seat mesh-catalog's
// verb versions through call (design 47 G §348), the only source numbering reads them from.
func newReservations(store versions.ReserveStore, call toolCaller, bounds func() jetstream.KeyValue, found *findings, wake func(context.Context), logf func(string, ...any)) *reservations {
rv := &reservations{call: call, bounds: bounds, found: found, bound: versions.UnreleasedBound, wake: wake, logf: logf}
rv.r = &versions.Reserver{Store: store, Filled: rv.filled.Load, ReleasedOf: func(_ context.Context, module string) ([]string, error) {
raw, err := call("seat:"+meshcatalog.Seat+".versions", meshcatalog.VersionsInput{Module: module})
if err != nil {
return nil, err
}
var a meshcatalog.VersionsAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return nil, fmt.Errorf("the catalog's versions of %s answered what is no list of versions: %w", module, err)
}
var out []string
for _, v := range a.Versions {
out = append(out, v.Version)
}
return out, nil
}}
rv.r.Took = rv.took
return rv
}
// 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) {
if older.Fingerprint == newer.Fingerprint {
rv.logf("%s: the build of %s reserves again: %s takes the place of %s", newer.Module, newer.Fingerprint, newer.Version, older.Version)
} else {
rv.logf("%s: the reservation of %s (build of %s, never released) is dropped: the build of %s takes the series over and reserves %s", newer.Module, older.Version, older.Fingerprint, newer.Fingerprint, newer.Version)
}
if rv.released != nil {
rv.released(ctx, older.Module, older.Version) // its publish item goes with its reservation (A-456b)
}
rv.dropBound(ctx, versions.ReservedKey(older.Module, older.Series))
rv.found.clear(ctx, versions.VersionUnreleased, meshconditionsclient.ScopeModule, older.Module)
}
var _ build.Reservations = (*reservations)(nil)
// ReservedFor is the reservation made for the build of fingerprint.
func (rv *reservations) ReservedFor(ctx context.Context, module, fingerprint string) (versions.ReservedVersion, bool, error) {
all, err := rv.r.All(ctx)
if err != nil {
return versions.ReservedVersion{}, false, err
}
for _, v := range all {
if v.Module == module && v.Fingerprint == fingerprint {
return v, true, nil
}
}
return versions.ReservedVersion{}, false, nil
}
func (rv *reservations) Filled() bool { return rv.filled.Load() }
func (rv *reservations) Reserve(ctx context.Context, module, series string, artifacts []string, src versions.Source) (versions.ReservedVersion, error) {
return rv.r.Reserve(ctx, module, series, artifacts, src)
}
// Built records the digests; once every artifact has one, the publish's bound starts (a key of the state bounds with its
// own time to live): its end with the reservation standing is version-unreleased.
func (rv *reservations) Built(ctx context.Context, module, version string, digests map[string]string, deps map[string][]meshbuilds.Dependency) error {
for ref, d := range digests {
if _, err := rv.r.Built(ctx, module, version, ref, d, deps[ref]); err != nil {
return err
}
}
cur, found, err := rv.r.Of(ctx, module, version)
if err != nil || !found || cur.BuiltAt.IsZero() {
return err
}
rv.arm(ctx, cur)
if rv.built != nil {
if err := rv.built(ctx, module, version); err != nil {
rv.logf("%v", err)
}
}
// A published heard before the digests were recorded marks its artifact now, said as one heard after (design 47 G A-415).
marked, unmatched, err := rv.r.Kept(ctx, module, version)
if err != nil {
rv.logf("the published kept on %s %s are not taken in: %v", module, version, err)
}
for _, h := range unmatched {
rv.logf("a published of %s@%s kept on %s %s marks no artifact: its digest %s is none of the built digests %v", h.Name, h.Version, module, version, h.Digest, cur.Artifacts)
// A build whose recorded digest differs from what the holder holds at its version fails loudly at once: the version is taken
// and no artifact is marked for it, so it is never released (design 47 G A-490j).
rv.unreleased(ctx, cur, fmt.Sprintf("the holder holds %s@%s under digest %s, which no artifact of the build carries (%v): the version is taken and is never released",
h.Name, h.Version, h.Digest, cur.Artifacts))
}
for _, m := range marked {
rv.sayPublished(ctx, m, m.Reserved.Artifacts[m.Artifact])
}
return nil
}
func (rv *reservations) arm(ctx context.Context, v versions.ReservedVersion) {
kv := rv.bounds()
var err error
if kv == nil {
err = fmt.Errorf("%s is not on the bus yet", versions.BoundsState)
} else if _, err = kv.Create(ctx, versions.ReservedBoundKey(v.Module, v.Series), versions.EncodeBound("the release of "+v.Module+" "+v.Version, time.Now().Add(rv.bound)), jetstream.KeyTTL(rv.bound)); errors.Is(err, jetstream.ErrKeyExists) {
err = nil
}
if err != nil {
rv.logf("the release bound of %s %s is not written, so it is raised unreleased now: %v", v.Module, v.Version, err)
rv.unreleased(ctx, v, fmt.Sprintf("its bound could not be written (%v)", err))
}
}
// unreleased raises version-unreleased about the module, naming the version and the artifacts missing.
func (rv *reservations) unreleased(ctx context.Context, v versions.ReservedVersion, why string) {
missing := v.Missing()
what := "an artifact is unpublished"
if len(missing) > 0 {
what = strings.Join(missing, ", ") + " unpublished"
}
rv.found.raise(ctx, finding{kind: versions.VersionUnreleased, scope: meshconditionsclient.ScopeModule, id: v.Module,
summary: fmt.Sprintf("%s %s is built and not released: %s (%s)", v.Module, v.Version, what, why),
headline: "A built version is not released",
explanation: "The builder reserved " + v.Module + " " + v.Version + " and its build ended, and the catalog has not said version-released: " + what + ".",
resolved: "The catalog says version-released for " + v.Module + " " + v.Version + ".",
needs: "builder_reserved shows the reservation; builder_publish_again publishes the missing artifacts under it; builder_reserved_drop drops it."})
}
// unreleasedWords raises version-unreleased about a version with the words of a publish again that ended badly.
func (rv *reservations) unreleasedWords(ctx context.Context, v versions.ReservedVersion, why string) {
rv.unreleased(ctx, v, why)
}
// ended is told each change of the state bounds: a reservation's bound whose time ended raises version-unreleased while
// the reservation stands built.
func (rv *reservations) ended(ctx context.Context, e jetstream.KeyValueEntry) bool {
key, ok := versions.ReservedBoundOf(e.Key())
if !ok {
return false
}
if e.Operation() != jetstream.KeyValuePurge {
return true
}
v, found, err := rv.r.At(ctx, key)
if err != nil || !found || v.BuiltAt.IsZero() {
return true
}
rv.unreleased(ctx, v, fmt.Sprintf("nothing within %s of its build", rv.bound))
return true
}
// dropBound ends a reservation's bound.
func (rv *reservations) dropBound(ctx context.Context, key string) {
if kv := rv.bounds(); kv != nil {
if err := kv.Delete(ctx, versions.ReservedBoundFor(key)); err != nil && !errors.Is(err, jetstream.ErrKeyNotFound) {
rv.logf("the release bound of %s is not ended: %v", key, err)
}
}
}
// heard takes the catalog's version-released and versions-filled in, and a registry seat's published (published): a
// message that is none of them is left to the others. A state that cannot take one leaves it for the bus to give again.
func (rv *reservations) heard(ctx context.Context, m jetstream.Msg) bool {
switch m.Subject() {
case meshcatalog.SubjectVersionsFilled:
rv.filled.Store(true)
rv.logf("the catalog said versions-filled: versions are reserved from now on")
if rv.wake != nil {
rv.wake(ctx)
}
case meshcatalog.SubjectVersionReleased:
var ev meshcatalog.VersionReleasedEvent
if err := json.Unmarshal(m.Data(), &ev); err != nil || ev.Module == "" || ev.Version == "" {
rv.logf("%s holds what is no version-released, left: %v", m.Subject(), err)
break
}
if err := rv.tagged(ctx, ev); err != nil {
rv.logf("%v; heard again", err)
if nakErr := m.Nak(); nakErr != nil {
rv.logf("leaving %s for the bus to give again: %v", m.Subject(), nakErr)
}
givenUp(m, "the version-released of "+ev.Module+" "+ev.Version, err, rv.logf)
return true
}
gone, err := rv.r.Released(ctx, ev.Module, ev.Version)
if err != nil {
rv.logf("%v; heard again", err)
if nakErr := m.Nak(); nakErr != nil {
rv.logf("leaving %s for the bus to give again: %v", m.Subject(), nakErr)
}
givenUp(m, "the version-released of "+ev.Module+" "+ev.Version, err, rv.logf)
return true
}
for _, k := range gone {
rv.dropBound(ctx, k)
}
if rv.released != nil {
rv.released(ctx, ev.Module, ev.Version)
}
if rv.heardReleased != nil {
rv.heardReleased(ev.Module, ev.Version)
}
rv.found.clear(ctx, versions.VersionUnreleased, meshconditionsclient.ScopeModule, ev.Module)
default:
return false
}
if err := m.Ack(); err != nil {
rv.logf("acknowledging %s: %v", m.Subject(), err)
}
return true
}
// published marks the artifacts of the reservation a registry seat's published names (its version and digest).
func (rv *reservations) published(ctx context.Context, o versions.Outcome) {
marked, kept, err := rv.r.Published(ctx, o.Name, o.Version, o.Digest)
if err != nil {
rv.logf("a published of %s@%s is not recorded in the reservations: %v", o.Name, o.Version, err)
}
if len(kept) > 0 {
rv.logf("the published of %s@%s (digest %s, holder %s) is kept on %s until the build records its digests", o.Name, o.Version, o.Digest, o.Holder, strings.Join(kept, ", "))
} else if len(marked) == 0 {
rv.logf("package-published not said: the published of %s@%s (digest %s, holder %s) marks no artifact of a reservation: %s", o.Name, o.Version, o.Digest, o.Holder, rv.noMark(ctx, o))
}
// Each artifact the holder's published newly marked is said as the seat mesh-builds' package-published (design 47 G §52, §334).
for _, m := range marked {
rv.sayPublished(ctx, m, o.Digest)
}
}
// sayPublished says the seat mesh-builds' package-published of an artifact a published marked.
func (rv *reservations) sayPublished(ctx context.Context, m versions.Marked, digest string) {
if rv.say == nil {
rv.logf("package-published of %s at %s not said: no seat to say it on", m.Artifact, m.Reserved.Version)
return
}
if err := rv.say(ctx, m.PackagePublished(digest, time.Now())); err != nil {
rv.logf("the package-published of %s at %s is not said: %v", m.Artifact, m.Reserved.Version, err)
} else {
rv.logf("package-published said: %s at %s, digest %s", m.Artifact, m.Reserved.Version, digest)
}
}
// dropped is builder_reserved_drop: the reservation is deleted and its bound ended.
func (rv *reservations) dropped(ctx context.Context, module, series, by, why string, at time.Time) (string, error) {
cur, held, _ := rv.r.At(ctx, versions.ReservedKey(module, series))
ok, err := rv.r.Drop(ctx, module, series)
if err != nil {
return "", err
}
if ok && held && rv.released != nil {
rv.released(ctx, module, cur.Version) // its publish item goes with its reservation (A-456b)
}
if !ok {
return "", fmt.Errorf("%s holds no reservation of %s", module, series)
}
rv.dropBound(ctx, versions.ReservedKey(module, series))
rv.found.clear(ctx, versions.VersionUnreleased, meshconditionsclient.ScopeModule, module)
return fmt.Sprintf("the reservation of %s %s is dropped (%s, %s)", module, series, by, why), nil
}
// tagged writes the git tag of a released version (design 47 G §370): on the catalog's version-released, through the seat
// git's verb tag, at the commit the reservation of that version was made from. A version with no reservation (a superseded
// build's version is never released, and the key of a version released by another builder is gone) or one that names no
// tag (a module with no Go package) is tagged nowhere. A tag the forge could not write is an error, the message heard again.
func (rv *reservations) tagged(ctx context.Context, ev meshcatalog.VersionReleasedEvent) error {
res, found, err := rv.r.Of(ctx, ev.Module, ev.Version)
if err != nil {
return fmt.Errorf("the reservation of %s %s cannot be read to tag it: %w", ev.Module, ev.Version, err)
}
if !found || res.Tag == "" || res.Commit == "" {
return nil
}
raw, err := rv.call("seat:"+git.Seat+".tag", git.TagInput{Repository: res.Repository, Commit: res.Commit, Tag: res.Tag})
if err != nil {
return fmt.Errorf("the tag %s of %s is not written: %w", res.Tag, ev.Module, err)
}
var a git.TagAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return fmt.Errorf("the git seat answered what is no tag answer for %s: %w", res.Tag, err)
}
if a.Error != "" || !a.Performed {
return fmt.Errorf("the tag %s of %s is not written: %s (%s)", res.Tag, ev.Module, a.Error, a.ErrorKind)
}
rv.logf("%s is tagged %s at %s", ev.Module, res.Tag, res.Commit)
return nil
}
// noMark says why a published marked nothing: which reservation holds that version, and what it holds of digests.
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)
if err != nil {
return "the reservations cannot be read: " + err.Error()
}
var out []string
for _, v := range all {
if v.Version != version {
continue
}
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 {
return "no reservation holds version " + version
}
return strings.Join(out, "; ")
}
// reserveDoneAct is builder_reserve_done's act (design 47 G A-455): the next version of the series is reserved for a done trunk build
// that reserved none, and its publish is queued as builder_publish_again queues it. Its answer says the version and the queued
// publishes; a reservation whose publish could not be queued is said so, with the tool that queues it.
func reserveDoneAct(reserve func(ctx context.Context, module, fp string) (versions.ReservedVersion, error),
republish func(ctx context.Context, module, version string) ([]string, error), logf func(string, ...any)) func(ctx context.Context, module, fp, by, why string, at time.Time) (string, error) {
return func(ctx context.Context, module, fp, by, why string, at time.Time) (string, error) {
res, err := reserve(ctx, module, fp)
if err != nil {
return "", err
}
logf("%s at %s: version %s is reserved by hand (%s, %s) for the done build", module, fp, res.Version, by, why)
queued, err := republish(ctx, module, res.Version)
if err != nil {
return "", fmt.Errorf("%s is reserved for %s at %s, but its publish is not queued (builder_publish_again queues it): %w", res.Version, module, fp, err)
}
return fmt.Sprintf("reserved %s for %s at %s and queued %d versions to publish: %s; builder_publish_queue shows them", res.Version, module, fp, len(queued), strings.Join(queued, ", ")), nil
}
}
// ReleasedFor says whether a version was released for the build of fingerprint (design 47 G A-456a).
func (rv *reservations) ReleasedFor(ctx context.Context, module, fingerprint string) (bool, error) {
return rv.r.ReleasedFor(ctx, module, fingerprint)
}