Files
mesh-delivery/modules/mesh-delivery-builder/internal/build/revisionwait.go
T
jschoubben 0f41b405ba Builder: a step ask naming a package with no pin waits for its release (H-A-165)
An entry keeps a mesh package with no released version unpinned
(H-A-161). Its step ask now waits, in the wait of H-A-155, for the
release of the module holding the package, heard or kept in the
builder's record of releases, and builds with that release as the pin;
past the bound the step fails naming the package and builds nothing.

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

211 lines
7.2 KiB
Go

package build
import (
"context"
"fmt"
"maps"
"slices"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
)
// **A build waits for its revision; a build with no version is never made** (design 47 H H-A-155, H-A-156; H-A-141): a step
// ask names its branch and source revision, and the builder reserves the version before it builds. When the builder's picture
// of that branch does not hold that source revision yet, or holds it but has not taken in the entry of the asked fingerprint
// from it, the ask waits for the picture to take it in, woken by each entry the picture takes in (take, EntryGone) and each
// revision its view holds (PictureHeld, H-A-162), never a
// timer or a poll, up to RevisionWait (the setting revision-wait-minutes); past it the ask fails, naming the revision and the
// branch, and nothing is built. A step ask with no source (a run on request) does not wait.
// DefaultRevisionWait is the bound of a step ask's wait for its revision, its setting revision-wait-minutes' default (H-A-156).
const DefaultRevisionWait = 2 * time.Minute
func (b *Builder) revisionWait() time.Duration {
if b.RevisionWait > 0 {
return b.RevisionWait
}
return DefaultRevisionWait
}
// PictureHeld is told each revision a branch's view takes in whole, whether or not an entry changed (H-A-162): every step
// ask waiting for its revision looks again.
func (b *Builder) PictureHeld() {
b.init()
b.pictureMoved()
}
// pictureMoved wakes every step ask waiting for the picture: an entry was taken in or went, or a revision was held.
func (b *Builder) pictureMoved() {
b.mu.Lock()
moved := b.moved
b.moved = make(chan struct{})
b.mu.Unlock()
close(moved)
}
// holdsRevision says whether the builder's picture of branch holds the source revision and has taken in every entry of the
// ask from that branch.
func (b *Builder) holdsRevision(branch string, source int64, entries []meshbuilds.BuildEntry) bool {
held, ok := b.Picture(branch)
if !ok || held < source {
return false
}
b.mu.Lock()
defer b.mu.Unlock()
for _, e := range entries {
key, err := builds.BuilderBuildKey(e.Module, e.Fingerprint)
if err != nil {
return true // the build key is refused where the entry is built, with why
}
if b.origin[key].Branch != branch && b.heard[branch+"\x00"+e.Module].Fp2 != e.Fingerprint {
return false
}
}
return true
}
// awaitRevision returns no outcome once the builder's picture of the ask's branch holds its source revision; past the bound the
// step's outcome failed, at the builder's stop could not run, each with its words.
func (b *Builder) awaitRevision(ctx context.Context, run meshbuilds.StepRun) (outcome, said string) {
if b.Picture == nil || run.Source <= 0 || run.Branch == "" {
return "", ""
}
bound := b.revisionWait()
notHeld := fmt.Sprintf("revision %d of %s not in the builder's picture", run.Source, run.Branch)
wait, stop := context.WithTimeout(ctx, bound) // a context's bound, no timer (ADR 0437 §8)
defer stop()
told := false
for {
b.mu.Lock()
moved := b.moved
b.mu.Unlock()
if b.holdsRevision(run.Branch, run.Source, run.Entries) {
if told {
b.logf("%s: revision %d of %s is in the builder's picture: the build goes on", run.Pipeline, run.Source, run.Branch)
}
return "", ""
}
if !told {
b.logf("%s: %s yet: the ask waits for it, at most %s", run.Pipeline, notHeld, bound)
told = true
}
select {
case <-moved:
case <-wait.Done():
if ctx.Err() != nil {
return meshbuilds.StepEndedOutcomeCouldNotRun, notHeld + ": the builder stopped before it was"
}
b.logf("%s: %s within %s: the step fails, nothing is built", run.Pipeline, notHeld, bound)
return meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s within %s", notHeld, bound)
}
}
}
// **A package with no pin waits for its release** (design 47 H H-A-165, H-A-161): an entry keeps a mesh package none of
// whose versions is released with an empty version. Its step ask waits, as for its revision, for the release of the module
// that holds the package (the catalog's version-released, VersionReleased), up to PackageWait (the setting
// package-wait-minutes), then builds with that release as the package's pin (v<version>); past the bound the step fails,
// naming the package, and nothing is built.
// DefaultPackageWait is the bound of a step ask's wait for a package's release, its setting package-wait-minutes' default.
const DefaultPackageWait = 10 * time.Minute
func (b *Builder) packageWait() time.Duration {
if b.PackageWait > 0 {
return b.PackageWait
}
return DefaultPackageWait
}
// VersionReleased takes the catalog's version-released of module in: a step ask waiting for a package of it wakes.
func (b *Builder) VersionReleased(module, version string) {
b.init()
b.mu.Lock()
b.releases[module] = version
b.mu.Unlock()
b.pictureMoved()
}
// releaseOf is the pin a package is built against: the release of the module holding it, as Go names it; "" for none yet.
func (b *Builder) releaseOf(ctx context.Context, pkg string) string {
if b.Members == nil {
return ""
}
module, _, found, err := b.Members(ctx, pkg)
if err != nil || !found {
return ""
}
b.mu.Lock()
v := b.releases[module]
b.mu.Unlock()
if v == "" && b.NewestReleased != nil {
if kept, ok, err := b.NewestReleased(ctx, module); err == nil && ok {
v = kept
}
}
if v == "" {
return ""
}
return "v" + v
}
// awaitPins fills each package entry names with no pin from its release, waiting for one; no outcome once every package has
// a pin, failed past the bound, could not run at the builder's stop.
func (b *Builder) awaitPins(ctx context.Context, entry *meshcatalog.CatalogEntry) (outcome, said string) {
var unpinned []string
for p, v := range entry.Packages {
if v == "" {
unpinned = append(unpinned, p)
}
}
if len(unpinned) == 0 {
return "", ""
}
slices.Sort(unpinned)
bound := b.packageWait()
wait, stop := context.WithTimeout(ctx, bound) // a context's bound, no timer (ADR 0437 §8)
defer stop()
pins := map[string]string{}
told := false
for {
b.mu.Lock()
moved := b.moved
b.mu.Unlock()
missing := ""
for _, p := range unpinned {
if pins[p] == "" {
pins[p] = b.releaseOf(ctx, p)
}
if pins[p] == "" && missing == "" {
missing = p
}
}
if missing == "" {
packages := maps.Clone(entry.Packages)
maps.Copy(packages, pins)
entry.Packages = packages
if told {
b.logf("%s at %s: every package it names has a released version: built with %v", entry.Module, entry.Fp, pins)
}
return "", ""
}
notReleased := fmt.Sprintf("package %s has no released version", missing)
if !told {
b.logf("%s at %s: %s yet: the ask waits for its release, at most %s", entry.Module, entry.Fp, notReleased, bound)
told = true
}
select {
case <-moved:
case <-wait.Done():
if ctx.Err() != nil {
return meshbuilds.StepEndedOutcomeCouldNotRun, notReleased + ": the builder stopped before it was"
}
b.logf("%s at %s: %s within %s: the step fails, nothing is built", entry.Module, entry.Fp, notReleased, bound)
return meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s within %s", notReleased, bound)
}
}
}