From 5e76fdf725f557f4ca29e670b74596535cd37896 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 21:25:03 +0100 Subject: [PATCH] H-A-328: the seat mesh-builds answers published; the builder serves it A package published before a pipeline existed is in no record of the runner, so the builder, which owns publishes, answers whether an artifact built at a fingerprint is published, from its reservations (marked from the registries' record) and its releases. Builds: design 47 H H-A-328, H-A-326 (1), H-A-274 --- .../cmd/mesh-delivery-builder/main.go | 8 +-- .../cmd/mesh-delivery-builder/reservedverb.go | 12 +++++ .../internal/versions/reserve.go | 40 ++++++++++++++ .../internal/versions/reserve_test.go | 48 +++++++++++++++++ .../mesh-delivery-builder/manifest_test.go | 10 ++-- modules/mesh-delivery-builder/module.json | 6 ++- .../go/seats/meshbuilds/contract.go | 27 +++++++++- .../go/seats/meshbuilds/contract_test.go | 6 +++ .../seats/mesh-builds/fixtures/verbs.json | 26 ++++++++++ .../seats/mesh-builds/seat.json | 52 +++++++++++++++++++ .../ts/seats/meshbuilds/index.d.ts | 23 ++++++++ .../ts/seats/meshbuilds/index.js | 1 + 12 files changed, 247 insertions(+), 12 deletions(-) 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 2bfff2677..2f50c05af 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/main.go @@ -473,13 +473,15 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro // modules again (design 47 G A-82, §204). // The runner's build step ask, the builder's one entry point for a candidate (design 47 G A-97). b.StepEntry = newEntryWaits(branches, half.manifests).entry - // The seat mesh-builds' verb reserved, answered here (A-115, A-127): the reservations, the catalog half's carriers and the seat - // mesh-catalog's versions. + // The seat mesh-builds' verbs reserved, answered here (A-115, A-127): the reservations, the catalog half's carriers and the seat + // mesh-catalog's versions; and published, from the reservations and releases (H-A-328). stopReserved, err := calls.AnswerSeat(meshbuilds.Seat, seatlist.Definition(seatGate.Reader, meshbuilds.Seat), map[string]process.SeatHandler{ meshbuilds.VerbReserved: reservedVerb(ctx, reservedReader(ctx, reserved.r.Store), versions.CarriersFrom(versions.EntriesOf(branches)), catalogReleased(calls.Call), func(name string) { logger.Printf("reserved: no entry carries the name %s; the entries looked at: %s", name, versions.LookedAt(versions.EntriesOf(branches))) - })}) + }), + // published (H-A-328): whether a package built at a fingerprint is published, asked by the runner writing a wait on it. + meshbuilds.VerbPublished: publishedVerb(ctx, reserved.r.PublishedOf)}) if err != nil { return fmt.Errorf("answering the verb reserved: %w", err) } diff --git a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reservedverb.go b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reservedverb.go index b45a29056..eca2412a7 100644 --- a/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reservedverb.go +++ b/modules/mesh-delivery-builder/cmd/mesh-delivery-builder/reservedverb.go @@ -49,6 +49,18 @@ func reservedVerb(ctx context.Context, rr versions.Reader, carriers func(context } } +// publishedVerb is the handler of the verb published (design 47 H-A-328): whether an artifact built at a fingerprint is +// published, from the reservations and the releases the builder keeps. +func publishedVerb(ctx context.Context, of func(ctx context.Context, module, artifact, fingerprint string) (meshbuilds.PublishedAnswer, error)) process.SeatHandler { + return func(_ string, body json.RawMessage) (any, error) { + var in meshbuilds.PublishedInput + if err := json.Unmarshal(body, &in); err != nil { + return nil, fmt.Errorf("the arguments do not fit the verb published: %w", err) + } + return of(ctx, in.Module, in.Artifact, in.Fingerprint) + } +} + // catalogReleased are a module's released versions, asked of the seat mesh-catalog's verb versions through call. func catalogReleased(call toolCaller) versions.CatalogVersions { return func(_ context.Context, module string) ([]meshcatalog.VersionEntry, error) { diff --git a/modules/mesh-delivery-builder/internal/versions/reserve.go b/modules/mesh-delivery-builder/internal/versions/reserve.go index 8b819733c..1bf8b15b8 100644 --- a/modules/mesh-delivery-builder/internal/versions/reserve.go +++ b/modules/mesh-delivery-builder/internal/versions/reserve.go @@ -419,6 +419,46 @@ func (r *Reserver) ReleasedFor(ctx context.Context, module, fingerprint string) return false, nil } +// PublishedOf answers the seat mesh-builds' verb published (design 47 H-A-328): whether artifact of module built at fingerprint +// is published. A reservation of that fingerprint whose artifact a registry seat said published at the built digest (marked +// from the registry's record too, H-A-274) answers its version and digest; a release of that fingerprint among the module's +// last releases answers published at its version, every artifact of a release being published; otherwise not published. +func (r *Reserver) PublishedOf(ctx context.Context, module, artifact, fingerprint string) (meshbuilds.PublishedAnswer, error) { + module, artifact, fingerprint = strings.TrimSpace(module), strings.TrimSpace(artifact), strings.TrimSpace(fingerprint) + if module == "" || artifact == "" || fingerprint == "" { + return meshbuilds.PublishedAnswer{}, errors.New("module, artifact and fingerprint are required") + } + keys, err := r.Store.KeysOf(ctx, NameFilter(module)) + if err != nil { + return meshbuilds.PublishedAnswer{}, fmt.Errorf("the reservations of %s cannot be listed: %w", module, err) + } + sort.Strings(keys) + for _, k := range keys { + cur, _, found, err := r.get(ctx, k) + if err != nil { + return meshbuilds.PublishedAnswer{}, err + } + if found && cur.Module == module && cur.Fingerprint == fingerprint && cur.Published[artifact] { + return meshbuilds.PublishedAnswer{Published: true, Version: cur.Version, Digest: cur.Artifacts[artifact]}, nil + } + } + if r.Releases != nil { + raw, _, found, err := r.Releases.Get(ctx, ReleasedKey(module)) + if err != nil { + return meshbuilds.PublishedAnswer{}, fmt.Errorf("the releases of %s cannot be read: %w", module, err) + } + var rec ReleasedRecord + if found && json.Unmarshal(raw, &rec) == nil { + for i := len(rec.Kept) - 1; i >= 0; i-- { + if rec.Kept[i].Fingerprint == fingerprint { + return meshbuilds.PublishedAnswer{Published: true, Version: rec.Kept[i].Version}, nil + } + } + } + } + return meshbuilds.PublishedAnswer{Published: false}, nil +} + // keepRelease adds a release to the module's record, dropping the oldest past ReleasedKept. func (r *Reserver) keepRelease(ctx context.Context, module, fingerprint, version string) error { n := r.ReleasedKept diff --git a/modules/mesh-delivery-builder/internal/versions/reserve_test.go b/modules/mesh-delivery-builder/internal/versions/reserve_test.go index dbe5b5ba2..a78f2fe0a 100644 --- a/modules/mesh-delivery-builder/internal/versions/reserve_test.go +++ b/modules/mesh-delivery-builder/internal/versions/reserve_test.go @@ -221,6 +221,54 @@ func TestAReleaseIsRecordedByFingerprintBeforeItsReservationGoes(t *testing.T) { } } +// TestPublishedAnswersByTheBuildFingerprint: design 47 H-A-328 — the verb published answers published for a reservation of the +// fingerprint whose artifact a registry's record marked published, with its version and digest, and for a release of it; an +// artifact not yet marked, and another fingerprint, are not published. +func TestPublishedAnswersByTheBuildFingerprint(t *testing.T) { + ctx := context.Background() + r := &Reserver{Store: &reserveMem{mem: newMem()}, Releases: &reserveMem{mem: newMem()}, ReleasedKept: 2, Filled: func() bool { return true }, + ReleasedOf: func(context.Context, string) ([]string, error) { return nil, nil }} + v, err := r.Reserve(ctx, "mesh-grants", "0.1", []string{"mesh-grants:busgrants", "mesh-grants:grantsstate"}, Source{Fingerprint: "src2:aa"}) + if err != nil { + t.Fatal(err) + } + if _, err := r.Built(ctx, "mesh-grants", v.Version, "mesh-grants:busgrants", "sha256:bb", nil); err != nil { + t.Fatal(err) + } + ask := func(artifact, fp string) meshbuilds.PublishedAnswer { + t.Helper() + a, err := r.PublishedOf(ctx, "mesh-grants", artifact, fp) + if err != nil { + t.Fatal(err) + } + return a + } + if a := ask("mesh-grants:busgrants", "src2:aa"); a.Published { + t.Errorf("a built artifact no registry holds is answered %+v, want not published", a) + } + if marked, _, err := r.Published(ctx, "mesh-grants-busgrants", v.Version, "sha256:bb"); err != nil || len(marked) != 1 { + t.Fatalf("the registry's published marked %v (%v)", marked, err) + } + if a := ask("mesh-grants:busgrants", "src2:aa"); !a.Published || a.Version != v.Version || a.Digest != "sha256:bb" { + t.Errorf("published answered %+v, want %s at sha256:bb", a, v.Version) + } + if a := ask("mesh-grants:grantsstate", "src2:aa"); a.Published { + t.Errorf("an artifact not marked is answered %+v", a) + } + if a := ask("mesh-grants:busgrants", "src2:other"); a.Published { + t.Errorf("another fingerprint is answered %+v", a) + } + if _, err := r.Released(ctx, "mesh-grants", v.Version); err != nil { + t.Fatal(err) + } + if a := ask("mesh-grants:grantsstate", "src2:aa"); !a.Published || a.Version != v.Version { + t.Errorf("after its release the fingerprint's artifact is answered %+v, want published at %s", a, v.Version) + } + if _, err := r.PublishedOf(ctx, "mesh-grants", "", "src2:aa"); err == nil { + t.Error("an ask naming no artifact is answered") + } +} + // TestTheWithdrawnVersionsAreDroppedOnceReleasedPast: design 47 H H-A-225, H-A-226, H-A-244 — a dropped number stays a gap, kept in // the series key's Withdrawn while it is above the catalog's highest released; at each write those at or below it go, so the // map never grows without end. diff --git a/modules/mesh-delivery-builder/manifest_test.go b/modules/mesh-delivery-builder/manifest_test.go index cdec75a2a..2574b54d4 100644 --- a/modules/mesh-delivery-builder/manifest_test.go +++ b/modules/mesh-delivery-builder/manifest_test.go @@ -198,9 +198,9 @@ func TestManifestDeclarations(t *testing.T) { // 1607/AC1 if len(m.Logs) != 1 || m.Logs[0].Name != builds.BuilderLog || m.Logs[0].MaxAgeDays != builds.BuilderLogDays || m.Logs[0].MaxMiB != builds.BuilderLogMiB { t.Errorf("logs = %+v, want %s kept %d days in %d MiB", m.Logs, builds.BuilderLog, builds.BuilderLogDays, builds.BuilderLogMiB) } - // Design 47 G §52, §369: the seat mesh-builds, held once for the mesh, serving reserved. - if len(m.Claims) != 1 || m.Claims[0].Name != "mesh-builds" || m.Claims[0].Scope != "mesh" || !reflect.DeepEqual(m.Claims[0].Serves, []string{"reserved"}) { - t.Errorf("claims = %+v, want mesh-builds, scope mesh, serving reserved", m.Claims) + // Design 47 G §52, §369, H-A-328: the seat mesh-builds, held once for the mesh, serving reserved and published. + if len(m.Claims) != 1 || m.Claims[0].Name != "mesh-builds" || m.Claims[0].Scope != "mesh" || !reflect.DeepEqual(m.Claims[0].Serves, []string{"reserved", "published"}) { + t.Errorf("claims = %+v, want mesh-builds, scope mesh, serving reserved and published", m.Claims) } // A-115: the process answers the verb itself and says so in `serves` beside its process, with no `bus`; the bundle serves no tool named so. var resources []map[string]any @@ -208,8 +208,8 @@ func TestManifestDeclarations(t *testing.T) { // 1607/AC1 t.Fatal(err) } for _, r := range resources { - if r["type"] == "process" && !reflect.DeepEqual(r["serves"], []any{"seat:mesh-builds.reserved"}) { - t.Errorf("the process serves %v, want seat:mesh-builds.reserved (A-115)", r["serves"]) + if r["type"] == "process" && !reflect.DeepEqual(r["serves"], []any{"seat:mesh-builds.reserved", "seat:mesh-builds.published"}) { + t.Errorf("the process serves %v, want seat:mesh-builds.reserved and published (A-115, H-A-328)", r["serves"]) } } if slices.Contains(m.Tools, "reserved") { diff --git a/modules/mesh-delivery-builder/module.json b/modules/mesh-delivery-builder/module.json index 7419cf8d1..f58f40c88 100644 --- a/modules/mesh-delivery-builder/module.json +++ b/modules/mesh-delivery-builder/module.json @@ -7,7 +7,8 @@ "name": "mesh-builds", "scope": "mesh", "serves": [ - "reserved" + "reserved", + "published" ] } ], @@ -293,7 +294,8 @@ "name": "mesh-delivery-builder", "artifact": "program", "serves": [ - "seat:mesh-builds.reserved" + "seat:mesh-builds.reserved", + "seat:mesh-builds.published" ], "run": [ "./mesh-delivery-builder" diff --git a/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go b/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go index 179a6890b..6a3ad819c 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go @@ -9,7 +9,8 @@ import "time" const Seat = "mesh-builds" const ( - VerbReserved = "reserved" + VerbReserved = "reserved" + VerbPublished = "published" ) const ( @@ -24,7 +25,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbReserved} + return []string{VerbReserved, VerbPublished} } // Events is every event published on the seat's subject: a new copy each call. @@ -217,6 +218,28 @@ type ReservedAnswer struct { Version string `json:"version,omitempty"` } +// PublishedInput is what published takes. +type PublishedInput struct { + // the package's artifact reference, : + Artifact string `json:"artifact"` + // the build fingerprint the package is built at, which the answer is matched by + Fingerprint string `json:"fingerprint"` + // the module that builds the package + Module string `json:"module"` +} + +// PublishedAnswer is what published answers. +type PublishedAnswer struct { + // when it was published, when published + At *time.Time `json:"at,omitempty"` + // the published artifact's digest, when published + Digest string `json:"digest,omitempty"` + // true when the artifact built at the fingerprint is published + Published bool `json:"published"` + // the version it is published at, MAJOR.MINOR.PATCH, when published + Version string `json:"version,omitempty"` +} + // StepAccept is the body of step. type StepAccept = StepRun diff --git a/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract_test.go b/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract_test.go index bb9c06804..47673e2f8 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract_test.go @@ -35,6 +35,12 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v ReservedAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "reserved answers an error alone, naming the name or the version", subject: "", given: "{\"error\":\"no entry carries the name example.org/none\"}", wire: "{\"error\":\"no entry carries the name example.org/none\"}", decode: func(b []byte) (any, error) { var v ReservedAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "published asks an artifact at its build fingerprint", subject: "", given: "{\"artifact\":\"mesh-grants:busgrants\",\"fingerprint\":\"src2:aa\",\"module\":\"mesh-grants\"}", wire: "{\"artifact\":\"mesh-grants:busgrants\",\"fingerprint\":\"src2:aa\",\"module\":\"mesh-grants\"}", + decode: func(b []byte) (any, error) { var v PublishedInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "published answers the version, digest and time of a published artifact", subject: "", given: "{\"at\":\"2026-11-21T19:00:00Z\",\"digest\":\"sha256:aa\",\"published\":true,\"version\":\"0.1.4\"}", wire: "{\"at\":\"2026-11-21T19:00:00Z\",\"digest\":\"sha256:aa\",\"published\":true,\"version\":\"0.1.4\"}", + decode: func(b []byte) (any, error) { var v PublishedAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "published answers an artifact not published", subject: "", given: "{\"published\":false}", wire: "{\"published\":false}", + decode: func(b []byte) (any, error) { var v PublishedAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/modules/mesh-delivery-contracts/seats/mesh-builds/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/mesh-builds/fixtures/verbs.json index 2ebcc767e..a9df904d5 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-builds/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/mesh-builds/fixtures/verbs.json @@ -52,5 +52,31 @@ "given": { "error": "no entry carries the name example.org/none" } + }, + { + "name": "published asks an artifact at its build fingerprint", + "of": "verb:published.input", + "given": { + "module": "mesh-grants", + "artifact": "mesh-grants:busgrants", + "fingerprint": "src2:aa" + } + }, + { + "name": "published answers the version, digest and time of a published artifact", + "of": "verb:published.answer", + "given": { + "published": true, + "version": "0.1.4", + "digest": "sha256:aa", + "at": "2026-11-21T19:00:00Z" + } + }, + { + "name": "published answers an artifact not published", + "of": "verb:published.answer", + "given": { + "published": false + } } ] diff --git a/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json b/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json index e100e48c7..bf2764921 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json @@ -70,6 +70,58 @@ }, "description": "the reservation or release, or the error; module, version and artifacts are present whenever error is not (design 47 G 679)" } + }, + { + "name": "published", + "class": "read", + "description": "Whether an artifact built at a build fingerprint is published, from the builder's reservations and the registries' record, for the pipeline runner writing a mover's wait on a package: a package published before the wait was written is read, not waited for (design 47 H-A-326, H-A-328, H-A-274).", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module that builds the package" + }, + "artifact": { + "type": "string", + "description": "the package's artifact reference, :" + }, + "fingerprint": { + "type": "string", + "description": "the build fingerprint the package is built at, which the answer is matched by" + } + }, + "required": [ + "module", + "artifact", + "fingerprint" + ] + }, + "answer": { + "type": "object", + "properties": { + "published": { + "type": "boolean", + "description": "true when the artifact built at the fingerprint is published" + }, + "version": { + "type": "string", + "description": "the version it is published at, MAJOR.MINOR.PATCH, when published" + }, + "digest": { + "type": "string", + "description": "the published artifact's digest, when published" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was published, when published" + } + }, + "required": [ + "published" + ] + } } ], "accepts": [ diff --git a/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.d.ts index bf8e68c77..86b89ad15 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.d.ts @@ -6,6 +6,7 @@ export declare const seat: "mesh-builds"; export declare const verbs: { readonly reserved: "reserved"; + readonly published: "published"; }; export declare const accepts: { @@ -171,6 +172,28 @@ export interface ReservedAnswer { "version"?: string; } +/** is what published takes. */ +export interface PublishedInput { + /** the package's artifact reference, : */ + "artifact": string; + /** the build fingerprint the package is built at, which the answer is matched by */ + "fingerprint": string; + /** the module that builds the package */ + "module": string; +} + +/** is what published answers. */ +export interface PublishedAnswer { + /** when it was published, when published */ + "at"?: string; + /** the published artifact's digest, when published */ + "digest"?: string; + /** true when the artifact built at the fingerprint is published */ + "published": boolean; + /** the version it is published at, MAJOR.MINOR.PATCH, when published */ + "version"?: string; +} + /** is the body of step. */ export type StepAccept = StepRun; diff --git a/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.js b/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.js index 31cc6f7c3..6710b83b9 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/meshbuilds/index.js @@ -6,6 +6,7 @@ export const seat = "mesh-builds"; export const verbs = { reserved: "reserved", + published: "published", }; export const accepts = {