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
This commit is contained in:
2026-11-21 21:25:03 +01:00
parent 438c8740a6
commit 5e76fdf725
12 changed files with 247 additions and 12 deletions
@@ -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)
}
@@ -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) {
@@ -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
@@ -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.
@@ -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") {
+4 -2
View File
@@ -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"
@@ -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, <module>:<artifact>
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
@@ -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))
@@ -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
}
}
]
@@ -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, <module>:<artifact>"
},
"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": [
@@ -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, <module>:<artifact> */
"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;
@@ -6,6 +6,7 @@ export const seat = "mesh-builds";
export const verbs = {
reserved: "reserved",
published: "published",
};
export const accepts = {