Node-engine: a want naming its version is resolved to its digests through the registry seats (A-430a)

A want of a released build names the module's version and no parts. Each artifact of the build's entry is
resolved at that version through the verb versions of its kind's registry seat: oci-artifact-registry for a
bundle or an archive, container-image-registry for an image, under <module>/<artifact> or a package's own
name. An upstream copy, which is not numbered, takes the digest its manifest pins. partsMissing, buildOf and
KeptBuildOf (and the shadow's added modules) read those digests; a want with parts is read as before.

A lookup that fails is said in the journal, naming the module, the version and the seat, and holds the module
whole: nothing of it is composed. It is asked again after a minute. The manifest invokes both verbs.

Builds: design 47 G A-430, A-430a; lead answer A-430b
This commit is contained in:
2026-11-15 16:52:59 +01:00
parent a00cccfe0d
commit 8a0c39280d
8 changed files with 373 additions and 21 deletions
+8 -16
View File
@@ -433,7 +433,7 @@ func (c *Composer) entryHolds() map[string]string {
out[module] = fmt.Sprintf("%s the catalog half holds no entry of the build %s, so the node composes nothing new of %s",
agent.EntryMissing, w.Fp, module)
default:
if missing := partsMissing(e, w); missing != "" {
if _, missing := c.partsOf(module, e, w); missing != "" {
out[module] = fmt.Sprintf("the want of %s names no digest for %s, so the node composes nothing new of it", module, missing)
}
}
@@ -441,19 +441,7 @@ func (c *Composer) entryHolds() map[string]string {
return out
}
// partsMissing names the artifacts of e whose digest w's parts do not give; "" when each has one.
func partsMissing(e meshcatalog.CatalogEntry, w meshwants.WantsByWantNodeModuleValue) string {
var out []string
for _, a := range e.Artifacts {
if w.Parts[a.Ref] == "" {
out = append(out, a.Ref)
}
}
sort.Strings(out)
return strings.Join(out, ", ")
}
// referenceOf is an artifact's reference made from the digest its want's part names, in the form the artifact store is
// referenceOf is an artifact's reference made from the digest its want's part names, or its version resolves (A-430a), in the form the artifact store is
// addressed by (the lead's answer A-50): artifact-store://<module>/<artifact>/blobs/<digest>.
func referenceOf(module, artifact, digest string) string {
return "artifact-store://" + module + "/" + artifact + "/blobs/" + digest
@@ -468,7 +456,11 @@ func (c *Composer) buildOf(module, fp string) *builds.BuilderBuild {
w, wanted := c.wants[module]
k, ok := c.keptEnt[fp]
c.mu.Unlock()
if !wanted || w.Fp != fp || !ok || partsMissing(k.entry, w) != "" {
if !wanted || w.Fp != fp || !ok {
return nil
}
parts, missing := c.partsOf(module, k.entry, w)
if missing != "" {
return nil
}
digest, raw, err := entryManifest(k.entry)
@@ -481,7 +473,7 @@ func (c *Composer) buildOf(module, fp string) *builds.BuilderBuild {
b := builds.BuilderBuild{State: builds.BuildDone, Manifest: digest}
for _, a := range k.entry.Artifacts {
_, name, _ := strings.Cut(a.Ref, ":")
digest := w.Parts[a.Ref]
digest := parts[a.Ref]
b.Artifacts = append(b.Artifacts, builds.BuiltArtifact{Name: name, Kind: a.Kind, Digest: digest,
Reference: referenceOf(module, name, digest)})
}
+13 -2
View File
@@ -16,9 +16,20 @@ func (c *Composer) KeptBuildOf(_ context.Context, module, digest string) (node,
if !ok || w.Fp == "" || w.KeptOn == "" {
return "", "", false, nil
}
if len(w.Parts) > 0 {
parts := w.Parts
if len(parts) == 0 && w.Version != "" {
// A want naming its version names its digests through the registry seats (A-430a): the resolution the composing made.
c.mu.Lock()
r := c.resolved[resolvedKey{module, w.Fp, w.Version}]
c.mu.Unlock()
if r.parts == nil {
return "", "", false, nil
}
parts = r.parts
}
if len(parts) > 0 {
named := false
for _, d := range w.Parts {
for _, d := range parts {
if strings.TrimPrefix(d, "sha256:") == strings.TrimPrefix(digest, "sha256:") {
named = true
}
+6 -1
View File
@@ -136,6 +136,9 @@ type Env struct {
// Set, the composer reads the catalog half by the fingerprints its wants and the runnings it heard name and nothing else of
// the indexer's or the builder's states (design 47 G §421, §628); a composer is made with it.
Entry meshcatalogclient.Call
// Registry asks the registry seats' verb versions (oci-artifact-registry, container-image-registry) in the engine's own
// name: a want naming its version is resolved to its artifacts' digests through it (design 47 G A-430a).
Registry meshcatalogclient.Call
}
// ManifestOf is the digest of the manifest of the build a module runs at fp, from the composer's picture of the catalog half;
@@ -193,7 +196,9 @@ type Composer struct {
entries *meshcatalogclient.Entries
keptEnt map[string]keptEntry
// notFound is each fingerprint whose entry-not-found the composer told, so it is told once and cleared once.
notFound map[string]bool
notFound map[string]bool
// resolved is each wanted build's digests as its version resolved them through the registry seats (versions.go, A-430a).
resolved map[resolvedKey]versionParts
keptWantVal map[string]keptWant
keptWants map[string]bool
keptWrite sync.Mutex
+1 -1
View File
@@ -630,7 +630,7 @@ func (s *Shadow) answerProposal(ctx context.Context, proposal string) (nodeengin
}
// The module is built from its entry and the parts the candidate gives (A-316); an artifact it gives no part for holds it.
w := meshwants.WantsByWantNodeModuleValue{Fp: fp, Parts: own.c.Added[pm.Module].Parts, Version: own.c.Added[pm.Module].Version}
if missing := partsMissing(entry, w); missing != "" {
if _, missing := c.partsOf(pm.Module, entry, w); missing != "" {
heldAdded[pm.Module] = fmt.Sprintf("the candidate gives no part for %s of %s's build %s, so the node composes nothing new of it", missing, pm.Module, fp)
continue
}
+217
View File
@@ -0,0 +1,217 @@
package selfcompose
import (
"encoding/json"
"fmt"
"sort"
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/containerimageregistry"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/ociartifactregistry"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/catalogue"
)
// **A want names its version; the node-engine resolves the digests** (design 47 G A-430, A-430a, the lead's answer A-430b).
// A want of a released build names the module's version and no parts: each artifact of the build's entry is looked up at that
// version through the verb `versions` of the registry seat of its kind (oci-artifact-registry for a bundle or an archive,
// container-image-registry for an image), under the name the builder numbered it by: `<module>/<artifact>`, or the entry's
// package name for a package. An upstream copy is not numbered (it is mirrored by its pinned digest): its digest is the one its
// manifest's `from` pins. A want that names parts (a build no version is known of) is read by its parts as before. A lookup that
// fails is said in the journal, naming the module, the version and the seat, and the module is held whole: never composed partly.
// resolveAgain is how long a failed lookup stands before it is asked again; a pass is asked then.
const resolveAgain = time.Minute
// versionsVerb is the verb a lookup asks.
const versionsVerb = "versions"
// resolvedKey names one resolution: a module's build at a version.
type resolvedKey struct{ module, fp, version string }
// versionParts is a module's build at a version as resolved: its digests by artifact reference, or why not, and when that was found.
type versionParts struct {
parts map[string]string
failed string
at time.Time
}
// registryVersions is the answer of either seat's verb `versions`: the two seats answer the same shape.
type registryVersions struct {
Versions []struct {
Digest string `json:"digest"`
Tag string `json:"tag,omitempty"`
Version string `json:"version,omitempty"`
} `json:"versions"`
}
// seatOfKind is the registry seat an artifact of kind is numbered in, and whether one is (design 51 *The seats*).
func seatOfKind(kind string) (string, bool) {
switch kind {
case catalogue.ArtifactImage:
return containerimageregistry.Seat, true
case catalogue.ArtifactBundle, catalogue.ArtifactArchive:
return ociartifactregistry.Seat, true
}
return "", false
}
// registryName is the name an artifact of module is numbered under: `<module>/<artifact>`, or a package's name in its
// ecosystem as the entry gives it.
func registryName(module string, a meshcatalog.Artifact) string {
_, artifact, _ := strings.Cut(a.Ref, ":")
if a.Kind == catalogue.ArtifactPackage && a.Package != nil && a.Package.Name != "" {
return a.Package.Name
}
return module + "/" + artifact
}
// partsOf is the digest of each artifact of e for want w, by artifact reference, and the artifacts it names no digest for ("" when
// each has one). A want with parts gives them; a want with a version and no parts is resolved through the registry seats.
func (c *Composer) partsOf(module string, e meshcatalog.CatalogEntry, w meshwants.WantsByWantNodeModuleValue) (map[string]string, string) {
parts := w.Parts
if len(parts) == 0 && w.Version != "" && len(e.Artifacts) > 0 {
var why string
if parts, why = c.resolve(module, e, w); why != "" {
return nil, why
}
}
return parts, partsMissing(e, parts)
}
// partsMissing names the artifacts of e whose digest parts does not give; "" when each has one.
func partsMissing(e meshcatalog.CatalogEntry, parts map[string]string) string {
var out []string
for _, a := range e.Artifacts {
if parts[a.Ref] == "" {
out = append(out, a.Ref)
}
}
sort.Strings(out)
return strings.Join(out, ", ")
}
// resolve is the digests of module's build at w's version, from what is resolved already or asked of the seats now. why names
// what failed; a failure stands resolveAgain, then is asked again.
func (c *Composer) resolve(module string, e meshcatalog.CatalogEntry, w meshwants.WantsByWantNodeModuleValue) (map[string]string, string) {
key := resolvedKey{module, w.Fp, w.Version}
now := c.now()
c.mu.Lock()
r, ok := c.resolved[key]
c.mu.Unlock()
if ok && (r.failed == "" || now.Sub(r.at) < resolveAgain) {
return r.parts, r.failed
}
parts, failed := c.lookUp(module, e, w)
c.mu.Lock()
if c.resolved == nil {
c.resolved = map[resolvedKey]versionParts{}
}
// Only the resolutions of the builds a want names now are kept.
for k := range c.resolved {
if cur, wanted := c.wants[k.module]; k.module != module && (!wanted || cur.Fp != k.fp || cur.Version != k.version) {
delete(c.resolved, k)
}
}
c.resolved[key] = versionParts{parts: parts, failed: failed, at: now}
c.mu.Unlock()
if failed != "" {
time.AfterFunc(resolveAgain, c.askRehand)
return nil, failed
}
return parts, ""
}
// lookUp asks each artifact's digest at w's version of the seat of its kind. Every failure is said, naming the module, the version
// and the seat; any failure resolves nothing of the build.
func (c *Composer) lookUp(module string, e meshcatalog.CatalogEntry, w meshwants.WantsByWantNodeModuleValue) (map[string]string, string) {
parts := map[string]string{}
var failed []string
fail := func(seat, ref, why string) {
line := fmt.Sprintf("%s at version %s: the seat %s's verb versions resolves no digest of %s: %s, so the node holds %s and composes nothing of it",
module, w.Version, seat, ref, why, module)
c.sayOnceEach(line)
failed = append(failed, fmt.Sprintf("%s (seat %s: %s)", ref, seat, why))
}
var manifest *catalogue.Manifest
for _, a := range e.Artifacts {
_, artifact, _ := strings.Cut(a.Ref, ":")
if a.Kind == catalogue.ArtifactUpstream {
if manifest == nil {
_, raw, err := entryManifest(e)
m, derr := catalogue.Decode(raw)
if err != nil || derr != nil {
fail("(none)", a.Ref, "the entry's manifest cannot be read for the digest its upstream copy pins")
continue
}
manifest = &m
}
if d := pinnedDigest(*manifest, artifact); d != "" {
parts[a.Ref] = d
} else {
fail("(none)", a.Ref, "the manifest pins no digest of the upstream copy")
}
continue
}
seat, numbered := seatOfKind(a.Kind)
if !numbered {
fail("(none)", a.Ref, "no registry seat the node-engine reads numbers an artifact of kind "+a.Kind)
continue
}
digest, why := c.versionDigest(seat, registryName(module, a), w)
if why != "" {
fail(seat, a.Ref, why)
continue
}
parts[a.Ref] = digest
}
if len(failed) > 0 {
sort.Strings(failed)
return nil, "no digest is resolved at version " + w.Version + " for " + strings.Join(failed, ", ")
}
return parts, ""
}
// versionDigest is the digest the seat's verb versions answers for name at w's version (its version or its tag), the newest
// first: a version names one build (A-430a), so the version alone is matched.
func (c *Composer) versionDigest(seat, name string, w meshwants.WantsByWantNodeModuleValue) (string, string) {
if c.env.Registry == nil {
return "", "this node-engine reads no registry seat"
}
raw, err := c.env.Registry("seat:"+seat+"."+versionsVerb, map[string]string{"name": name})
if err != nil {
return "", fmt.Sprintf("the call for %s failed: %v", name, err)
}
answer, said, ok := buscalls.Unwrap(raw)
if !ok {
return "", fmt.Sprintf("the seat refused %s: %s", name, said)
}
var v registryVersions
if err := json.Unmarshal(answer, &v); err != nil {
return "", fmt.Sprintf("its answer for %s cannot be read: %v", name, err)
}
for _, a := range v.Versions {
if (a.Version == w.Version || a.Tag == w.Version) && a.Digest != "" {
return a.Digest, ""
}
}
return "", fmt.Sprintf("it holds no version %s of %s", w.Version, name)
}
// pinnedDigest is the digest the manifest's upstream artifact pins in its from (`<image>@sha256:<hex>`); "" when none.
func pinnedDigest(m catalogue.Manifest, artifact string) string {
if m.Build == nil {
return ""
}
for _, a := range m.Build.Artifacts {
if a.Name == artifact {
if _, d, ok := strings.Cut(a.From, "@"); ok && strings.HasPrefix(d, "sha256:") {
return d
}
}
}
return ""
}
+123
View File
@@ -0,0 +1,123 @@
package selfcompose
import (
"context"
"encoding/json"
"errors"
"strings"
"sync"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// Design 47 G A-430, A-430a (the lead's answer A-430b): a want naming its version and no parts is resolved to its artifacts'
// digests through the verb versions of the registry seat of each artifact's kind, under `<module>/<artifact>`; an upstream copy
// by the digest its manifest pins. The build is made from those digests. A lookup that fails is said, naming the module, the
// version and the seat, and holds the module whole; a want with parts is read by its parts as before.
func TestAWantNamingItsVersionIsResolvedThroughTheRegistrySeats(t *testing.T) {
fp := meshcatalogclient.SourcePrefix2 + strings.Repeat("a", 64)
d := func(c string) string { return "sha256:" + strings.Repeat(c, 64) }
manifest := map[string]any{"module": "mail", "version": "1", "build": map[string]any{"artifacts": []any{
map[string]any{"name": "server", "kind": "upstream", "from": "alpine@" + d("9")},
map[string]any{"name": "files", "kind": "archive", "from": "files"},
map[string]any{"name": "web", "kind": "image", "from": "Dockerfile"},
}}}
entry := meshcatalog.CatalogEntry{Module: "mail", Fp: fp, Manifest: manifest, Artifacts: []meshcatalog.Artifact{
{Ref: "mail:server", Kind: "upstream"}, {Ref: "mail:files", Kind: "archive"}, {Ref: "mail:web", Kind: "image"}}}
// The seats hold mail/files and mail/web; versions newest first.
held := map[string]string{
"oci-artifact-registry.mail/files": `{"name":"mail/files","versions":[{"name":"mail/files","kind":"archive","digest":"` + d("2") + `","version":"1.3.0"},{"name":"mail/files","kind":"archive","digest":"` + d("1") + `","version":"1.2.3"}]}`,
"container-image-registry.mail/web": `{"name":"mail/web","versions":[{"name":"mail/web","kind":"image","digest":"` + d("3") + `","version":"1.2.3"}]}`,
"container-image-registry.mail/other": `{"name":"mail/other","versions":[]}`,
}
for name, row := range map[string]struct {
want meshwants.WantsByWantNodeModuleValue
down string // a seat whose call fails
parts map[string]string
missing string // a word the reason holds
said []string
}{
"resolved": {want: meshwants.WantsByWantNodeModuleValue{Fp: fp, Version: "1.2.3", Self: true},
parts: map[string]string{"mail:server": d("9"), "mail:files": d("1"), "mail:web": d("3")}},
"a version a seat does not hold": {want: meshwants.WantsByWantNodeModuleValue{Fp: fp, Version: "2.0.0", Self: true},
missing: "2.0.0", said: []string{"mail at version 2.0.0", "oci-artifact-registry", "container-image-registry"}},
"a seat that does not answer": {want: meshwants.WantsByWantNodeModuleValue{Fp: fp, Version: "1.2.3", Self: true}, down: "container-image-registry",
missing: "mail:web", said: []string{"mail at version 1.2.3: the seat container-image-registry"}},
"parts as before": {want: meshwants.WantsByWantNodeModuleValue{Fp: fp, Version: "1.2.3", Self: true,
Parts: map[string]string{"mail:server": d("9"), "mail:files": d("5"), "mail:web": d("6")}},
parts: map[string]string{"mail:server": d("9"), "mail:files": d("5"), "mail:web": d("6")}},
} {
var mu sync.Mutex
var said []string
env := Env{Say: func(line string) { mu.Lock(); said = append(said, line); mu.Unlock() }}
calls := 0
env.Registry = EntryCall(func(_ context.Context, seat, verb string, args any) (json.RawMessage, error) {
calls++
if verb != "versions" {
t.Errorf("%s: asked %s.%s", name, seat, verb)
}
if seat == row.down {
return nil, errors.New("no responders")
}
answer, ok := held[seat+"."+args.(map[string]string)["name"]]
if !ok {
return nil, errors.New("not held")
}
return json.RawMessage(answer), nil
})
env.Entry = EntryCall(func(context.Context, string, string, any) (json.RawMessage, error) {
return nil, errors.New("not asked")
})
c := New(env)
c.wants["mail"] = row.want
c.keptEnt[fp] = keptEntry{entry: entry}
parts, missing := c.partsOf("mail", entry, row.want)
b := c.buildOf("mail", fp)
if row.missing != "" {
if parts != nil || b != nil || !strings.Contains(missing, row.missing) {
t.Errorf("%s: parts %v, build %v, missing %q: want the module held whole, naming %s", name, parts, b, missing, row.missing)
}
if c.entryHolds()["mail"] == "" {
t.Errorf("%s: the module is not held", name)
}
for _, w := range row.said {
if !strings.Contains(strings.Join(said, "\n"), w) {
t.Errorf("%s: said %q, want a line naming %q", name, said, w)
}
}
continue
}
if missing != "" || len(parts) != len(row.parts) {
t.Fatalf("%s: parts %v, missing %q", name, parts, missing)
}
for ref, digest := range row.parts {
if parts[ref] != digest {
t.Errorf("%s: %s at %s, want %s", name, ref, parts[ref], digest)
}
}
if b == nil || len(b.Artifacts) != 3 {
t.Fatalf("%s: build %+v", name, b)
}
for _, a := range b.Artifacts {
if a.Digest != row.parts["mail:"+a.Name] || a.Reference != referenceOf("mail", a.Name, a.Digest) {
t.Errorf("%s: artifact %+v", name, a)
}
}
// A resolution is asked once, and it names the node keeping the build its digests are of.
before := calls
c.partsOf("mail", entry, row.want)
if calls != before {
t.Errorf("%s: resolved again: %d calls, then %d", name, before, calls)
}
c.wants["mail"] = meshwants.WantsByWantNodeModuleValue{Fp: fp, Version: row.want.Version, Parts: row.want.Parts, KeptOn: "g14", Self: true}
if node, _, kept, _ := c.KeptBuildOf(context.Background(), "mail", row.parts["mail:files"]); !kept || node != "g14" {
t.Errorf("%s: kept on %q %v, want g14", name, node, kept)
}
if _, _, kept, _ := c.KeptBuildOf(context.Background(), "mail", d("7")); kept {
t.Errorf("%s: a digest the want does not resolve to is said kept", name)
}
}
}