Compare commits

..
156 Commits
Author SHA1 Message Date
mesh-tools e196064e51 Merge pull request 'Design 47 H: the builder's publish queue: live asks first, newest per series, one listing per pass (H-A-290..293)' (#316) from fix/47-H1-builder-publish-queue into main 2026-11-21 18:00:25 +00:00
jschoubben 2eaa41a420 H-A-292, H-A-293: builder_publish_queue reads one page; a build is retired only within its series
The review found two faults. The tool paged on through a state of any size, one replay of the bucket per page; it now
reads one page of each of its own states and, when the state holds more, answers that page capped, with the keys read
and the state's size from its info, never asking a second page and never refusing. And the retiring of superseded done
builds keyed the newest reservation and release by module alone, so a standing 0.2 would retire a done 0.1.x; both are
now found per module and series (MAJOR.MINOR).

Builds: design 47 H H-A-292, H-A-293, H-A-291 (1), H-A-290 (5)
2026-11-21 18:59:58 +01:00
jschoubben 90ff867e7a lock the test fakes' maps
Two tests failed under -race on main too: the re-ask state fake's maps were written by a try on the watch's goroutine while
the test read and deleted them, and the operator-ask test read the build store unlocked and waited on the builder while
the build its answer starts could still be counting itself in. The fake's maps are locked and read through it, the store
is read under its lock, and the builder is waited on only once that build has claimed its key.

Builds: design 47 H H-A-290 (the module's tests pass with -race, as its checks ask)
2026-11-21 18:59:58 +01:00
jschoubben 77fb6c4ab1 H-A-291: a start publishes only each module's newest done build; a live enqueue cuts a start list short
A start asked a publish again for every unreleased done build, older ones whose digests a newer reservation or release
of the same module made dead included, and a live publish queued during a long start pass waited for its end. A done
build a newer reservation or release (the builder's own record) supersedes is now retired at the start and at the pass:
its key dropped, its publish item ended, said in the journal; the start asks only each module's newest. A live enqueue
marks its holder, and a pass about to send a start-class item stops there, lets the sends in flight end and lists again,
so the live one goes next; a start-class enqueue never does.

Builds: design 47 H H-A-291 (1), (2), H-A-290, H-A-275
2026-11-21 18:59:58 +01:00
jschoubben bda61ae64c H-A-290: the builder's publish queue sends live publishes first, in passes, never a withdrawn build
The tool runner's release waited forty minutes behind old versions: every start asked a publish again for every done
build, and each send relisted and reread the whole queue. A publish whose build ended in this run now goes before any
asked again at a start (the class kept on the key's value, a live key of a build before the start made a start key at
the start); a pass lists a holder's keys once and sends them four at a time; a withdrawn or taken-over build is dropped
with its publish item ended at enqueue, at the pass and at the start; a send that returns unsent says why, and every call
it makes honours its one bound; builder_publish_queue reads its states in pages and answers counts per holder and class,
the oldest and newest queue time, a list capped at fifty and one module's items with their class.

Builds: design 47 H H-A-290 (1)-(5), H-A-269, H-A-271, H-A-275
2026-11-21 18:59:58 +01:00
mesh-tools 5547fd028e Merge pull request 'Design 47 H: a pipeline with nothing open ends at once; the end's reads are made once (H-A-288, H-A-289)' (#315) from fix/47-H1-runner-end-when-empty into main 2026-11-21 17:22:44 +00:00
jschoubben d51d389c1b Runner: a pipeline with nothing open ends at once (47-H1-runner-end-when-empty)
main.117 judged its end at 17:45:19 and never wrote it: every mover's widens
was read inside the end's compare-and-set loop, 126 movers each cut on
grants-for, so each try took about eleven minutes and every write was refused
as changed until the restart, whose start pass judged no end.

The reads an end needs are made once, before the compare-and-set, shared by
every mover and every retry; the runner's start pass ends each running
pipeline with nothing open before the queue is placed; every end says its
outcome in the journal.

Builds: design 47 H H-A-288, H-A-289, H-A-223, H-A-243
2026-11-21 18:18:32 +01:00
mesh-tools c6edd5987f Merge pull request 'Design 47 H: a re-pin of the same source keeps a mover in its pipeline (H-A-283..286)' (#314) from fix/47-H1-runner-same-source-repin into main 2026-11-21 17:00:58 +00:00
jschoubben 9a49b0f4f7 Give a kept mover's asks ids of its kept revision and place it from that revision (H-A-286)
Review round 1: a kept mover's ask ids still came from the pipeline's start
time, so a pin-held ask or a composition took the id of an ask the runner
had just dropped for the old fingerprint, and a restart never matched the
steps placed again; and a kept mover placed later read the branch's held
view, so a lagging view gave the new fingerprint the old pins. Every ask id
of a kept mover's steps (build, tests, validate, pin-held asks,
composition, rerun, restart) now mixes its kept revision into the id's
sum, and every placing of a kept mover (at once, later, at a restart, a
rerun) reads its entries at its kept revision by number, waiting while
that revision cannot be read. The test's starter gets a clock that moves.

Builds: design 47 H H-A-286 (amending H-A-284; with H-A-283, H-A-285)
2026-11-21 17:58:07 +01:00
jschoubben 47f81051be Keep a same-source re-pin's mover in its pipeline and build it again there (H-A-283)
A module importing packages its own pipeline releases was re-pinned at
each publish; each re-pin revision of the same source took it out of the
running pipeline, and each newer build withdrew the older reservation, so
nothing ever published. A revision of the same source now moves no mover
out of the open pipeline of that source: the pipeline keeps it at its new
fingerprint, ends every step of it superseded (said at the old
fingerprint, its asks dropped, its runs left) and places them again from
the re-pin revision's entry under new asks, the build first, still naming
the pipeline's revision. The revision the mover is kept at rides in the
record's kept-revisions, beside the movers, where the pin check reads its
entry. A revision whose every mover is kept starts no pipeline; one of a
new source moves movers as before.

Builds: design 47 H H-A-283, H-A-284, H-A-285 (with H-A-223, H-A-244, ADR 0682)
2026-11-21 17:47:54 +01:00
mesh-tools 769d701e2b Merge pull request 'Design 47 H1: a published event reads each reservation once, only the unbuilt ones on a miss (H-A-280)' (#313) from fix/47-H1-builder-published-read-once into main 2026-11-21 15:47:49 +00:00
jschoubben ece9d6b18f Builder: a published reads each reservation once, and only the unbuilt ones on a miss
Live, a published at a version fourteen reservations share cost three seconds:
the fallback by version read every reservation there, and the journal line
read them all again, so the backlog drained at fifty a minute.

The published now hands the reservations it read (each once, a second pass
taking what the first read) to its journal line. The fallback reads the new
index key of the reservations at a version whose build has not recorded every
digest (kept at reserve and where a digest is recorded, written again at the
start), the only ones a published can be kept on; the line counts the rest from
the index by version without reading them. Before that pass the handler says
in progress to the bus.

Builds: design 47 H H-A-280, H-A-271
2026-11-21 16:45:25 +01:00
mesh-tools 93495203b5 Merge pull request 'Design 47 H1: the builder hears a published once by digest; no publish asked again while one is unheard; a held number is never reserved (H-A-269)' (#312) from fix/47-H1-builder-published-once into main 2026-11-21 14:59:17 +00:00
jschoubben 5628ca2919 Builder: a build whose number a registry holds elsewhere is built again, never moved
Every artifact carries its version from its build (a Go module zip's paths, a
program's stamped version, an image's and a bundle's build environment), so
no digest survives a change of number: the move that kept digests would have
published a binary saying 0.1.37 under another number.

The try, on a number a registry holds at another digest, withdraws it on the
reservation (a gap) and raises version-held-elsewhere naming both digests,
then asks the build of the same fingerprint again through the build-again
path of a done key whose version is not released. Its reserve never takes a
withdrawn number again, skips every number a registry holds, and the build
records fresh digests and runs its own publish; the takeover ends the old
number's publish item and bound.

Builds: design 47 H H-A-275, H-A-279, H-A-226
2026-11-21 15:56:04 +01:00
jschoubben 05c59ae000 Builder: the registry's record ends a publish or moves a number it holds elsewhere
A publish item skipped while the registry held the version would stay skipped
for ever once its published event was lost; and node-tools 0.1.37, held by the
artifact registry at another digest than the build's, was asked again for ever
and never released.

When every missing artifact is held at its version with the built digest the
builder marks it published from the registry's record and says
package-published, as a heard published would; the release follows from the
catalog. Before reserving, the registry seats' versions of the module's
artifacts are read and every number one holds is skipped (version-held-elsewhere,
scope module); a read that fails lets the reserve proceed. A done build whose
number a registry holds at another digest moves to the next free number, its
digests kept, the old number withdrawn as a gap; its old item and bound end and
its publish is asked under the new number. The finding clears at the module's
version-released.

Builds: design 47 H H-A-274, H-A-275, H-A-245, H-A-226
2026-11-21 15:51:21 +01:00
jschoubben e1630b57c6 Builder: no publish asked again while its published may be unheard or the registry holds it
The publish item's try asked the registry to publish node-tools 0.1.37 again
every few minutes while the registry had published it and the builder's own
consumer stood thousands of messages behind, adding events to the backlog.
Before each try the builder reads its durable on the events stream (pending
plus unacknowledged): at a hundred or more the try asks nothing. Below it the
registry seats' own record (their verb versions) is read: every missing
artifact held at the version with its built digest asks nothing either. A
skipped try is said in the journal, written again with its pause and spends
no try; a count or record that cannot be read holds no ask.

Builds: design 47 H H-A-269 (2), H-A-272
2026-11-21 15:40:19 +01:00
jschoubben 5c4c4bc821 Builder: a published finds its reservation through an index by digest and by version
The builder's consumer of the registry seats' published stood thousands behind:
each published, and each one that marked nothing, read every reservation.
An index beside the reservations (three-token keys in the same state, which the
reservations' two-token filter never lists) names the reservation keys holding
a built digest and those standing at a version; it is kept at reserve, at a
digest recorded, at release and at drop, and written again once at the start.
A published reads its digest's entry and that reservation; a digest no
reservation holds is judged from its version's entry, never a scan.

The test stores and the tools' read store now read a key filter token by token
as the bus does, which showed the publish queue's resume listing three-token
keys with the two-token filter: it lists them with its own filter now.

Builds: design 47 H H-A-269 (1), H-A-271
2026-11-21 15:37:44 +01:00
mesh-tools 599bf62d23 Merge pull request 'Design 47 H1: a module entering the trunk's graph is registered at its take-in; the runner says registration-missing (H-A-262)' (#311) from fix/47-H1-indexer-register-at-take-in into main 2026-11-21 12:22:04 +00:00
jschoubben 0de195c5aa Design 47 H1: test that a module entering the graph watches its siblings' alike branch
Review round 2. The siblings watched main, which is also the default
branch, so no test held the alike rule; they now watch stable and the
entering module is asserted to watch it.

Builds: design 47 H H-A-265, H-A-266
2026-11-21 13:20:54 +01:00
jschoubben 3160bb1fb8 Design 47 H1: registration-missing clears when no running pipeline waits on the registration
Review round 1. A pipeline that ended (failed, cancelled) with a mover
still waiting left the finding for ever. It is now judged at every
pipeline's end and in Waiting: cleared when the registration is held, or
when no running pipeline still has an unplaced mover of the module.

Builds: design 47 H H-A-262, H-A-265
2026-11-21 13:18:41 +01:00
jschoubben 93efda5db3 Design 47 H1: the graph skips a pending register, the seed's left-out, and reads the branch
Review round 1. A module with a register proposal pending is skipped (the
operator's Approve registers it); a module the seed left out keeps
seed-left-out and is not registered; the branch is the first watched
branch the repository's registered modules hold alike, else its default
branch read through the seat git, and a module whose default branch is not
read is skipped and said, registered at the next kept trunk revision. One
listing of the registrations finds the modules with none, so a revision
whose modules are all registered reads no registration.

Builds: design 47 H H-A-262, H-A-263, H-A-264, H-A-265, H-A-266
2026-11-21 13:18:41 +01:00
jschoubben f01731fd4e Design 47 H1: the runner raises registration-missing while a mover waits on its registration
A mover with no registration had its wait said only in the journal. The
runner now raises the finding registration-missing (scope module, id the
module) through its finding writer as it places a pipeline whose mover has
no registration, and clears it when the module's registration arrives or
the registrations held name it.

Builds: design 47 H H-A-262, G A-327, ADR 0666 §2
2026-11-21 13:09:23 +01:00
jschoubben 251745f859 Design 47 H1: the indexer registers a module that enters the trunk's module graph
Four modules added to a repository after the registrations' seed were never
registered, so a pipeline's steps for them waited on a registration nobody
asked. A kept trunk revision of any kind now registers each of its modules
with no registration, before the revision is said, with no ask: origin its
repository, path its manifest's, the first watched branch, the steps its
repository's other modules hold alike (else the seed's) and a per-artifact
status only where every sibling naming that artifact holds it identically,
said registration-changed. The start does the same once for the current
trunk graph. With no registration held the seed stays the only writer; a
module that leaves the graph keeps its registration.

Builds: design 47 H H-A-262, H-A-263, H-A-264, G A-327, ADR 0666 §2
2026-11-21 13:09:23 +01:00
mesh-tools d1ec9d9072 Merge pull request 'Design 47 H1: the assigner's pass never waits on the keeping of revisions; no want before a revision is kept (H-A-259)' (#310) from fix/47-H1-assigner-pass-on-ended into main 2026-11-21 11:40:59 +00:00
jschoubben 14254dd0ba Assigner: no want before a revision is kept; the full-store verdict stays the pass's
Review round 1: the start handed a removal-only keeping to the background
while passes wrote wants with no revision kept, so their wanted was never
said. A pass now writes no want until the first keeping keeps a revision
(that keeping wakes the pass), the start's removal folds into the first
pass's keeping, and the pass judges the store's fill itself, through a
handle of its own, before it writes. The integration bed makes the
revisions' object store, as the grants part does from the manifest.

Builds: design 47 H H-A-259, H-A-261; ADR 0682
2026-11-21 12:40:15 +01:00
jschoubben 1e50642e3c Assigner: the pass never waits on the keeping of revisions (H-A-259)
A pass that kept a fresh assignment graph revision sat six to eight minutes
keeping it and removing the revisions not current, so the wakes of
pipeline-ended and running waited for it. The keeping now runs off the pass
loop, one at a time and folded; the removal takes each entry's module and
fingerprint from the store's listing instead of reading every entry object;
each pass and each keeping says its duration.

Builds: design 47 H H-A-259; ADR 0682
2026-11-21 12:40:15 +01:00
mesh-tools b0082ec04f Merge pull request 'Design 47 H1: every ask the runner makes is bounded; a shared validate ask is never read as one mover's; a moved mover leaves a waiting pipeline (H-A-235)' (#309) from fix/47-H1-runner-asks-bounded into main 2026-11-21 11:02:21 +00:00
jschoubben 6b6e4c81f0 Judge a missed first bound by the first read's own entries (H-A-238)
The start read the second bound with a get, which says not found both
for a key never armed and for one the holder's ask-taken deleted, so
every later start asked an answered step once more. The first read
keeps each key's last entry; a first bound's expiry is taken only when
its second bound left no entry at all, and with both passed only the
second is taken, ending the step without asking it again.

Builds: design 47 H H-A-238 (5)
2026-11-21 12:02:02 +01:00
jschoubben 374d060cc0 Take an ask's bound that expired while the runner was down (H-A-238)
The bounds were watched for updates only, so an expiry marker written
while the runner was down was never heard and that ask had no bound.
At the start each ask key's last entry is read; an expiry marker is
taken then. A running heard before the seat-holders view is read is
heard again after a delay instead of at once.

Builds: design 47 H H-A-238 (5), H-A-243 (1)
2026-11-21 12:02:02 +01:00
jschoubben 1f878eec58 A validate rerun moves every mover's validate and reopens its compositions (H-A-236)
The rerun put only the named mover's validate under the new ask; the
others stayed failed under the old one, so the pipeline failed again
and a second rerun made a second validate ask, breaking the pipeline's
one validate ask. The compositions its failed validate ended not asked
now wait again, asked once validate passes as at the placing.

Builds: design 47 H H-A-51, H-A-236
2026-11-21 12:02:02 +01:00
jschoubben c9515da86f Take a validate end by its ask alone, ending every mover's validate (H-A-252)
The pipeline's one validate ask names no mover, but its end names the
mover whose body the holder took; the runner compared that mover with
the first step carrying the ask and dropped a passed validate, so the
pipeline held its slot (main.88).

Builds: design 47 H H-A-236, H-A-252
2026-11-21 12:02:02 +01:00
jschoubben 5f7137e676 A moved mover leaves an older waiting pipeline whenever a newer one starts (H-A-244)
Only a newer pipeline that waited took movers out of older waiting ones;
one placed at once left them, so main.84 was placed nine hours later
with a mover a newer revision had moved and built a stale fingerprint.

Builds: design 47 H H-A-223, H-A-244 (1)
2026-11-21 12:02:02 +01:00
jschoubben 902947a044 Bound a silent seat's ask once; put it again when its holder starts (H-A-243)
mesh-builds and mesh-wants say nothing before a step's end, so asking
them again at the short bound would double a running build. Their ask
has one bound, ask-silent-bound, and is put again when the node-engine
says the holder running, since the holder takes asks on a plain
subscription and loses those put while it is down. An ask asked again
on a build seat carries a second id derived in the accepted form.

Builds: design 47 H H-A-235, H-A-238, H-A-241, H-A-243
2026-11-21 12:02:02 +01:00
jschoubben b95b3ef989 Bound every ask the runner puts on a seat (H-A-235)
An ask whose holder lost it (the seat mesh-wants' holder restarted) held
its pipeline's turn for nine hours. Every ask but a test run's now arms
a key of the state bounds before it is put; its expiry asks once more,
said in the journal, and the second ends the step could not run with
the finding call-unanswered, so the pipeline ends and its turn frees.

Builds: design 47 H H-A-235, H-A-238 (1)-(5)
2026-11-21 12:02:02 +01:00
jschoubben 0f167db73d Rerun of validate or composition asks the shared ask (H-A-236)
The rerun verb looked a step's ask up by the mover's id, but the validate
ask is one per pipeline and names no mover, so every validate rerun, and
a composition rerun, was refused "placed no ask now".

Builds: design 47 H H-A-236
2026-11-21 12:02:02 +01:00
mesh-tools e5f54c5cdb Merge pull request 'Design 47 H1: the indexer declares the finding kinds it raises; its unanswered calls get a kind of its own (H-A-247)' (#308) from fix/47-H1-indexer-finding-kinds into main 2026-11-21 10:57:52 +00:00
jschoubben bdb4edd820 Design 47 H1: the indexer's retired call-unanswered names scope call
The tool runner's approval findings of call-unanswered are of scope machine;
the indexer's entry now names scope call, so no approval key is cleared even
where an id form would match. The test's negative ids take the approval form.

Builds: design 47 H H-A-249, G §580
2026-11-21 11:50:27 +01:00
jschoubben 31c2c5c7fe Design 47 H1: the indexer retires call-unanswered by the ids it wrote under it
The daemon's call-unanswered keys from before the rename would be seeded and
stated by the tool runner's writer, which owns that kind, and never cleared.
The retired list now names call-unanswered with the indexer's own id forms
(the seed's node-build-<kind>.steps, the floor's
mesh-catalog.versions-floor.<module>, the versions fill's
mesh-delivery-builder.builder_versions), so those keys clear once and the
tool runner's approval findings stay.

Builds: design 47 H H-A-247 (3), H-A-249, G §580
2026-11-21 11:50:27 +01:00
jschoubben ad0052c6f5 Design 47 H1: the indexer owns the SDK parts' kinds, its own unanswered-call kind and a retired list
The daemon's writer is handed to the process reader (event-unhandled) and the
heard writer (family-not-heard), kinds its list lacked; and call-unanswered
belongs to the tool runner's writer over the same state. The daemon's
unanswered calls are now indexer-call-unanswered (same scope and id), its list
holds the SDK parts' kinds, and merge-untaken is retired, so its live key and
condition clear at the next start. The test reads the SDK parts handed the
writer and refuses a retired kind still raised.

Builds: design 47 H H-A-242, H-A-247 (1) (2) (3), H-A-82, G §580
2026-11-21 11:50:27 +01:00
jschoubben aef8632d95 Design 47 H1: the indexer's writer owns the kinds its code raises, held by a test
The daemon's writer owned every kind while the tool runner's writer shares the
state `findings`; under G §580 each bundle states only its own kinds. The
daemon's writer is now made with FindingKinds, the ten kinds its code raises,
and a unit test reads the daemon's code for every kind it gives the writer and
fails on one the list does not declare.

Builds: design 47 H H-A-240, H-A-242 (2), H-A-233, G §580
2026-11-21 11:50:27 +01:00
mesh-tools dedcc3ead7 Merge pull request 'Design 47 H1: a done build whose series moved says stale, not 'no version is reserved' (H-A-244)' (#307) from fix/47-H1-builder-stale-and-tag into main 2026-11-21 10:37:56 +00:00
jschoubben a40bbec44a Builder: a done build whose series was taken over fails stale, naming the newer build
A pipeline placed long after its take-in found its old build done but holding no
number, and was told to reserve one; the series had moved to a newer fingerprint.
The step now says it is stale and names that fingerprint and its version.

Builds: design 47 H H-A-244 (2), H-A-226
2026-11-21 11:34:25 +01:00
mesh-tools fe6c5961ae Merge pull request 'Design 47 H1: a repository's packages are those in the merge's tree (H-A-232)' (#306) from fix/47-H1-indexer-gone-packages into main 2026-11-21 02:09:12 +00:00
jschoubben 588a6ff8d5 Design 47 H1: only the trunk's merge drops a gone package; a commit's tree tells an all-gone repository (H-A-232, H-A-233)
Review round 1. A branch's take-in runs through the dry indexer, which
shares the live packages state, so a branch cut before main added a
module would have deleted main's key: publish drops a kept key only on
the real indexer at the trunk's merge. And a repository whose every
asked directory is gone (one key, or all gone) returned the whole error
and raised packages-not-published at every take-in: the seat's trees of
the commit now tell a gone directory from a commit with no tree.

Builds: design 47 H H-A-232, H-A-233, H-A-234; issue 1585
2026-11-21 03:07:02 +01:00
jschoubben ced27928d9 Design 47 H1: the indexer publishes a repository's packages in the merge's tree (H-A-232, H-A-233, H-A-234)
A Go module mesh-catalog removed stayed in the packages state, so every
publish of mesh-catalog asked the forge for its directory, the seat git
answered not-found, and the one-directory fallback (issue 1585) ran only
on an answer without the directory: nothing of the repository was
published and its packages' digests froze unsaid.

filesVia takes the seat's not-found as a failure of the tree, so the
fallback runs; publish drops the kept key of a package whose directory
the trunk's merge no longer holds, said in the journal; a listing that
fails for another reason raises the finding packages-not-published
(scope merge, id the repository), cleared at the next publish that lists.

Builds: design 47 H H-A-232, H-A-233, H-A-234; issue 1585
2026-11-21 02:54:58 +01:00
mesh-tools 2cb6971194 Merge pull request 'Design 47 H1: a receiver reads its store's fill once per transfer (H-A-227, H-A-228)' (#305) from fix/47-H1-receiver-fill-once into main 2026-11-21 01:12:32 +00:00
jschoubben 6a730c33e6 H-A-227, H-A-228: the receiver reads its objects' fill once per transfer
A fill read on every chunk made the tool runner list the registry's
incoming store per chunk. The kept transfer now holds the fill read at its
open and the bytes taken since; each chunk tells their sum, written with
the put already made per chunk, and the store is read again only at the
finish, a drop, or when a part's chunks are dropped.

Builds: design 47 H H-A-227, H-A-228
2026-11-21 02:11:39 +01:00
mesh-tools d1aab1d08d Merge pull request 'Design 47 H1: the validate and composition run asks carry their entry's pins (H-A-203)' (#304) from fix/47-H1-runner-validate-pins into main 2026-11-21 01:09:03 +00:00
jschoubben c6b4b6054b Design 47 H1: the validator's and the composer's run asks are built against their entry's pins (H-A-203)
The validate step's run ask built the manifest validator from the indexer's
tree with no pins, so the Go build module refused it for a requirement of
another repository (main.74's feh validate, main.67's mesh-sdk validate);
the composition step's run ask built the composer from the node-engine's
tree the same way. The seat mesh-wants' holder builds both asks: each now
carries the pins of the entry its program is built from, the indexer's
entry at the step's own revision and the node-engine entry chosen per
machine, those with a version, in the form the entry keeps and the
builder sends.

Builds: design 47 H H-A-203, H-A-192, H-A-205
2026-11-21 02:03:18 +01:00
mesh-tools 4df45a3793 Merge pull request 'Design 47 H1: the builder keeps a reservation for its fingerprint and withdraws a taken-over build (H-A-225, H-A-226)' (#303) from fix/47-H1-builder-reservation-kept into main 2026-11-21 00:41:48 +00:00
jschoubben e2e13ddd29 Drop withdrawn versions the catalog released past; a dropped number stays a gap (H-A-226)
The series key's Withdrawn grew at every take-over and was never pruned. At each write it now keeps only the
withdrawn versions above the catalog's highest released (those at or below it are refused by the plain rule anyway),
carried across a renumbering of the same fingerprint too; a dropped number is never reused (H-A-226 withdraws
H-A-225's freeing). The comment of the rebuild's reservation now states A-490b as H-A-225 amends it.

Builds: design 47 H H-A-225, H-A-226
2026-11-21 01:40:18 +01:00
jschoubben dcf5b7fa8f Keep a reservation for its fingerprint until released; withdraw a taken-over build (H-A-225)
After a builder restart, the run already building a module carried its reserved number while a re-run of the same
fingerprint reserved the next, so its publish was refused "has no version reserved or released" (main.61: the builder
0.1.111 vs 0.1.112, mesh-grants 0.1.52 vs 0.1.54, and others reserved twice within seconds). A take-over by another
fingerprint dropped the older reservation but let the older build run on and publish a number that no longer existed.

Reserve now answers the standing reservation of the same fingerprint while it is unreleased and above the catalog's
highest, a build again or a re-run alike (A-490b amended so). A take-over keeps the dropped version in Withdrawn and
withdraws the older build (ended superseded, ADR 0664 §4); a late publish of it is refused as withdrawn, naming the
fingerprint that took it over.

Builds: design 47 H H-A-225; G A-490b as amended; ADR 0664 §4
2026-11-21 01:36:32 +01:00
mesh-tools 1fe6ade359 Merge pull request 'Design 47 H1: a same-repository module named only by a replace is a requirement of the module graph (H-A-224)' (#302) from fix/47-H1-indexer-replace-required into main 2026-11-21 00:30:50 +00:00
jschoubben 9e09767a4b Indexer: a same-repository module named only by a replace is a requirement
The watchman's go.mod names buildrun in a replace directive with no require
line, and the walk of the module graph followed require lines only, so
buildrun's requirement of the module assigner's client was never pinned and
every test step of the watchman failed "no pin". The walk now takes the
same-repository modules a go.mod replaces by a directory as required, with
the same same-repository test, so their go.mod files are read and their
other-repository requirements pinned, transitively.

Builds: design 47 H-A-224, H-A-201
2026-11-21 01:26:29 +01:00
mesh-tools 59443ab3f7 Merge pull request 'Design 47 H1: a mover a newer revision moved leaves a running pipeline too (H-A-223)' (#301) from fix/47-H1-runner-moved-leaves into main 2026-11-21 00:24:57 +00:00
mesh-tools 92d0ab8602 Merge pull request 'Design 47 H1: the indexer's test fakes answer what the SDK's pull guard reads (H-A-196)' (#300) from fix/47-H1-indexer-fake-consumer into main 2026-11-21 00:24:55 +00:00
jschoubben 3a31331ad3 Design 47 H1: a mover leaving a running pipeline has its build-node asks dropped (H-A-223)
A moved mover's steps ended superseded, but their asks kept running on the
build nodes. Each such step holding its own ask on a node-build seat, one
reading no shared run, now has the seat's drop asked with the newer
pipeline's why, through the drop the runner already bounds and keeps. The
seat mesh-builds serves no drop, so a build ask there runs to its end,
which the runner ignores: the step is no longer open.

Builds: design 47 H H-A-223
2026-11-21 01:22:10 +01:00
jschoubben d1581666d2 Design 47 H1: the start of a newer pipeline is held to take moved movers out, and reads its branch alone (H-A-223)
No test failed when Start stopped calling the supersede of running
pipelines, the path the live runner takes. Two rows now start a newer
pipeline through Start, a take-in's and a release revision's, with the
supersede wired to a hearer over the same store, and hold that the older
running pipeline's moved mover left it. The supersede lists only the keys
of the newer pipeline's branch instead of every pipeline's.

Builds: design 47 H H-A-223
2026-11-21 01:18:55 +01:00
jschoubben d4d7895392 Indexer: the branch consumer fake answers its CachedInfo and ends when stopped
With the SDK's guard of one pull per durable (pullOnce reads the consumer's
CachedInfo and releases on the consume's Closed), the fake of a branch's
durable embedded a nil consumer and a nil consume context, so
TestABranchDurableNotThereIsMadeAndHeard panicked. The fake now answers a
ConsumerInfo with its stream, name and a created time of its own, and its
consume context closes when stopped. No other fake in mesh-delivery embeds
jetstream.Consumer; the assigner's, runner's, builder's, watchman's and
grants' unit suites pass with the new SDK unchanged.

Builds: design 47 H-A-196, H §774
2026-11-21 01:18:22 +01:00
mesh-tools d6c209a10c Merge pull request 'Design 47 H1: the catalog seat's revision verb answers the store; the builder's picture holds a kept revision by number (H-A-222)' (#299) from fix/47-H1-revision-verb-store into main 2026-11-21 00:14:44 +00:00
mesh-tools 51ac838732 Merge pull request 'Design 47 H1: the indexer decodes every hand tool's ask (H-A-208, H-A-210)' (#298) from fix/47-H1-indexer-again-decode into main 2026-11-21 00:14:40 +00:00
jschoubben 06a52a10e0 Design 47 H1: a moved mover leaves a running pipeline too (H-A-223)
A release re-pinned node-tools while main.54 still built it at its old
fingerprint; the build failed and failed the pipeline for its other 119
movers, because supersession took movers out of waiting pipelines only.
Every start of a newer revision's pipeline now also walks the older running
pipelines of its branch: each mover whose fingerprint it moved leaves, its
open steps ending superseded with a why naming the newer pipeline, a step
reading a test run leaving it as a cancel's does, and the mover kept in the
pipeline's superseded. The end judgement counts a left mover's steps as
neither holding nor failed, so the pipeline ends by its other movers alone;
one every mover left ends superseded. A run on request's pipeline is never
touched.

Builds: design 47 H H-A-223, H-A-163, H-A-213
2026-11-21 01:13:57 +01:00
jschoubben 773e2e33a1 Builder: a kept revision of another source or fingerprint fails the ask at once
Review round 1: an ask names the revision and the source of one revision, so a
kept revision read by number whose source differs from the ask's is not the
ask's; the check is restored, naming both sources. And a kept revision naming
another source or other fingerprints is a mismatch no wait can mend: the step
fails at once, loud, instead of waiting out revision-wait-minutes; only a
revision the catalog does not answer is waited for.

Builds: design 47 H-A-222 (2), H-A-218
2026-11-21 01:10:37 +01:00
jschoubben d817d85fca Builder: an ask naming a revision is held by that revision read by number
An ask of the very source the picture holds, whose entries the picture no
longer names (a re-pin keeps a later revision of the same source), waited for
the picture and failed past its bound, because the kept revision was read by
number only for a source below the picture's. Now an ask naming a revision is
read by number whenever the picture does not name its entries, and is built
when the catalog keeps it and it names every fingerprint asked, whatever the
source says; the source is compared only for an ask naming no revision.

Builds: design 47 H-A-222 (2), H-A-205, H-A-213
2026-11-21 01:07:18 +01:00
jschoubben 6d5000871d Indexer: the revision verb answers the newest kept revision from the store
The tools bundle answered the catalog seat's revision verb from its view of the
trunk in memory, which ran one or more revisions behind what the indexer kept
until it heard the event, so the runner and the builder waited on revisions the
bus held all along. The verb now reads which revision is newest from the store
at the time of the ask (a listing and one object) and takes the view's entries
only when the view holds that very revision.

Builds: design 47 H-A-222 (1), H-A-205, H-A-213
2026-11-21 01:05:55 +01:00
jschoubben 5c7648744d Indexer: read a takeins value's hand acts from TakeInAsk's tags, not a hand-kept list
indexer_take_in_again wrote TakeInAsk{Again} and DecodeTakeIn refused it: its
hand-kept list of act fields lacked Again, so the handler never reached its
Again branch. Every field of TakeInAsk now says by its tag takein whether it is
an act, an argument or of the ask; DecodeTakeIn reads the acts from the tags,
and a table test builds every hand tool's value by its own Run path, decodes it
and acts on it through takenIn, and refuses a field left unclassed.

Builds: design 47 H §774, H-A-208, H-A-210
2026-11-21 01:03:32 +01:00
mesh-tools 8802f16019 Merge pull request 'Design 47 H1: the pin rule whole: revisions numbered by the indexer with their call, a re-pin or recompute keeps a revision, pins carried in every ask, pipelines keyed by revision (H-A-203 to H-A-221)' (#297) from fix/47-H1-pin-kind-join into main 2026-11-20 23:49:57 +00:00
jschoubben 6087306dfd Design 47 H1: the pipelines store guards its shared maps, so the runner's start no longer crashes (H-A-187)
The runner crashed at every start on a live bus with "concurrent map
writes" in MoverStore.Get: the waiting pipelines of each branch are placed
from goroutines of their own, and the store's last reads and inline marks
were written under each pipeline's own lock alone. The store's mutex now
guards the lock table, the last reads and the inline marks; behaviour is
unchanged. The run test starts the runner over six kept pipelines in the
old form, one of 437 steps, so the start path runs under the race detector.

Builds: design 47 H H-A-187, H §774
2026-11-21 00:43:16 +01:00
jschoubben 667aa87611 Join fix/47-H1-builder-revision-picture 2026-11-21 00:27:10 +01:00
jschoubben 0f2fd1a171 Join fix/47-H1-runner-published-revision
# Conflicts:
#	modules/mesh-delivery-indexer/internal/index/catalog_revisions.go
#	modules/mesh-delivery-pipeline/internal/pipeline/start.go
2026-11-21 00:27:04 +01:00
jschoubben e1ce5cc8ed Join fix/47-H1-indexer-take-in-again 2026-11-21 00:26:46 +01:00
jschoubben 7794ee9d2d Join fix/47-H1-sdk-empty-pin 2026-11-21 00:26:46 +01:00
jschoubben 396893dcac Design 47 H1: the pipeline-runner seat names a pipeline's key and its subjects by revision
The seat's key form of a pipeline is <branch>.<revision>, and its four per-pipeline
subjects are said on <branch>.<revision> (the definition and generated contracts the
same as the runner branch's). The indexer pins a revision for the pipeline keyed
PipelinesByBranchRevisionKey, and this branch's runner copy follows the renamed
generated functions; the wire form is unchanged.

Builds: design 47 H H-A-213 (4), H-A-219, H-A-221
2026-11-21 00:25:58 +01:00
jschoubben 626a6fb358 Design 47 H1: the pipeline-runner seat names a pipeline's key and its subjects by revision
A pipeline is keyed by its catalog revision's number, so the seat's key form is
<branch>.<revision> (the generated PipelinesByBranchRevisionKey and its siblings; the
fixtures follow), and pipeline-started, pipeline-ended, wait-held and wait-ended are
said on <branch>.<revision>, carrying the same number as the key; every reader takes
the body. The client's SourceSubject is RevisionSubject. The published key form, under
which pipelines were kept before, stays.

Builds: design 47 H H-A-213 (4), H-A-219, H-A-221
2026-11-21 00:25:08 +01:00
jschoubben 20ee1cae7b Merge the runner branch into the builder branch, so both merge into main as one
The builder's step end reports the pins it built with (H-A-207, from the runner
branch) and names the run's catalog revision on its origin (H-A-218, H-A-220); step.go
keeps both. The seat mesh-builds carries packages on step-ended and revision on
package-published once each; seatgen -check is clean.

Builds: design 47 H H-A-207, H-A-218, H-A-220
2026-11-21 00:22:19 +01:00
jschoubben 671dc5a963 Design 47 H1 (5c): the runner takes a publish into the pipeline of the revision it names
One source now has several catalog revisions, so the publishing pipeline is found by
the branch and revision the package-published names. A publish naming no revision,
from a reservation made before the field, goes to its source's lowest-numbered
revision, the take-in's. The seat mesh-builds' package-published gains its optional
revision here too, identical to the builder branch's, so this branch compiles alone.

Builds: design 47 H H-A-218, H-A-220
2026-11-21 00:17:55 +01:00
jschoubben 3f62410c22 Design 47 H1 (5c): a package-published names the catalog revision its build was made from
One source now has several catalog revisions, so a publish naming branch and source
alone does not say which pipeline published it. The seat mesh-builds'
package-published gains an optional revision (seatgen regenerated). The version
reserved for a build keeps the catalog revision number: from the picture's half when
the picture starts the build (the same revision its source comes from), from the step
ask's run when the ask reaches the build first. Its package-published says it. A
reservation from before the field says none.

Builds: design 47 H H-A-218, H-A-220
2026-11-21 00:17:17 +01:00
jschoubben 4af1ba99cf Design 47 H1 (5a): the runner's integration tests key a pipeline by its catalog revision
The queue's and the test runs' integration tests took several sources in at one
catalog revision, which now are one key. Each take-in has its own revision; the
test runs' test also checks that a test ask names revision and source. A replaced
reader of another pipeline's run stays the unit tests' (one revision is one pipeline).

Builds: design 47 H H-A-213 (4), H-A-219
2026-11-21 00:12:36 +01:00
jschoubben 91b5e8d086 Design 47 H1 (5b): a release, take-in again or recompute revision starts one pipeline, read by its number
A re-pin on a module's release, a take-in again and a recompute that moves a
fingerprint each keep a catalog revision of their own. The runner hears a trunk
catalog-revision of those kinds, reads that revision by its number through the catalog
seat's revision verb, and starts one pipeline keyed <branch>.<revision> with the
revision's movers. A package-published no longer starts per-artifact pipelines: it
only places the movers waiting for it. A branch's newest pipeline for a mover is the
one of the highest revision number.

Builds: design 47 H H-A-212, H-A-213 (2) and (4), H-A-217
2026-11-21 00:07:55 +01:00
jschoubben 189d75ad40 Design 47 H1 (5a): a pipeline is keyed by its catalog revision, and every step ask names revision and source
One source now has several catalog revisions, so a pipeline keyed by its source could
not tell them apart. A pipeline is keyed <branch>.<revision>; one of a source (a
publish's, a version-released's) is found by the source it names, never by its key, so
pipelines kept under their source are read as they are. The Go, Node and image step
asks name the catalog revision in revision and the gate's source in a new optional
source (the build-step part of the seats node-build-go, node-build-node and
node-build-image, seatgen regenerated).

Builds: design 47 H H-A-211, H-A-213 (4), H-A-219
2026-11-21 00:02:48 +01:00
jschoubben 595510ef38 Design 47 H1 (9): a recompute that moves a fingerprint keeps a revision of kind recompute
Every whole recompute of the modules state (a toolchain reported, the toolchains read, the assignments of a build module, the indexer's start, a hand act) moved fingerprints with no kept catalog revision. It now runs as a re-pin does: when at least one fingerprint moved against the trunk's newest revision, it keeps the trunk's next revision of the same source, its movers the moved modules, its call-kind recompute (the seat mesh-catalog's enumeration gains it, seatgen regenerated) and its call naming the reason; one that moves none keeps nothing.

Builds: design 47 H H-A-211, H-A-213 (2), H-A-217
2026-11-20 23:50:50 +01:00
jschoubben 04f54d7773 Design 47 H1 (7): a registry's published recomputes no module
The indexer kept a registry's published in its series and then recomputed every module, moving fingerprints with no kept catalog revision beside the re-pin a release's package-published starts. It keeps the version in its series and recomputes nothing: a fingerprint moves only with a kept revision, one per module release, kept by the re-pin. The seat mesh-wants' pipeline-wanted subject names its last token revision, the number of the runner's key (its form unchanged).

Builds: design 47 H H-A-211, H-A-213 (2), H-A-213 (4) (the subject's token), H-pins-spec-and-gaps leftover L3
2026-11-20 23:48:08 +01:00
jschoubben 07dc14bf53 Design 47 H1 (6): pipeline-wanted names the pipeline's revision, and the indexer frees that revision's pins
The seat mesh-wants' pipeline-wanted gains revision, the pipeline's catalog revision number (seatgen regenerated, additive). The assigner keeps the source the pipeline-ended names in its tier progress and says it beside the revision, the number of the pipeline's key; a progress kept before the field says the key's number as both. The indexer frees the pins of the revision the event names, not of another revision of the same source, and for an event naming none takes the source's lowest-numbered revision, the take-in's.

Builds: design 47 H H-A-213 (4), H-A-214, H-A-216
2026-11-20 23:46:25 +01:00
jschoubben 9b3a728f9e Design 47 H1 (8): a catalog revision's call names its kind, one of three constants
The seat mesh-catalog's CatalogRevision and catalog-revision gain call-kind, an enumeration the seat's schema validates (take-in, release, take-in-again), with module and version for a release and repository for a take-in again, beside call, the words for a person (regenerated by seatgen, additive). The indexer's three writers set them: a take-in's from the gate's call, a re-pin's on a module's release, a take-in again's; no reader parses the words.

Builds: design 47 H H-A-213 (3), H-A-214, H-A-215
2026-11-20 23:43:33 +01:00
jschoubben 83e4470757 Design 47 H1 (1), review round 1: a source answers its take-in's revision
The revision verb's source input, and the pipeline-wanted that frees pins by it, answer the lowest-numbered revision of a source (the take-in's), never a later re-pin's of the same source. TestIndexerWhole asks the exact first number: the bed seeds main.1 of source 0, so source 10's is 2 (no source is kept twice).

Builds: design 47 H-A-213 (1), (4), H-A-211
2026-11-20 23:39:53 +01:00
jschoubben 1b1fd9a711 Design 47 H1 (2): a take-in again keeps the trunk's next catalog revision of the same source
The take-in again keeps what it recomputed as a re-pin does: the trunk's next revision of the newest's source, its call 'take-in again of <repository>', its movers every module whose fingerprint moved, pinned for its pipeline, said as catalog-revision.

Builds: design 47 H-A-208, H-A-210 as H-A-211 and H-A-212 amend it, H-A-213 (1), (3)
2026-11-20 23:36:39 +01:00
jschoubben 47ea130332 Design 47 H1 (1): a release re-pin keeps the next catalog revision of the same source on every watched branch
A branch's revision number is the indexer's own count (the newest + 1); the gate's source is the revision's field source, which the take-in's dedupe and source-to-take read. A catalog revision carries its call (the seat mesh-catalog's CatalogRevision and catalog-revision gain call, regenerated by seatgen). A re-pin on a module's release runs on every watched branch holding a module that names its package (the first on the modules state, another on its newest revision's picture), and keeps, where a fingerprint moved, the branch's next revision of the same source with the call 'release of <module> <version>' and the moved modules as its movers, pinned for the release's pipeline, and says catalog-revision; no take-in.taken.

Builds: design 47 H S11, S12, S13, S14 (H-pins-spec-and-gaps item 1), H-A-211, H-A-212, H-A-213 (1)-(4: the pin of every revision a pipeline runs on), H-A-147
2026-11-20 23:36:39 +01:00
jschoubben 52f7a5b6f6 Design 47 H1 (4): a candidate's entry may name a package with no version yet
An entry names an unpublished package with an empty version, never left out, so a run on request's candidate checks its packages as an entry's (CheckEntry), not as an ask's. Built against the SDK head aee7e4c2 (fix/47-H1-sdk-empty-pin), which goes in the same merge call.

Builds: design 47 H S8 (H-pins-spec-and-gaps item 4, L10), H-A-204
2026-11-20 23:25:24 +01:00
jschoubben aee7e4c26c mesh-delivery-sdk: an entry's packages may name an empty version (H item 4, the SDK's half)
The indexer names a package of another repository with no version published yet by an empty
version, which waits for its publish; PackageVersions.Check refused it, so a run on request of such a
module failed its candidate check. CheckEntry is the entry form, allowing an empty version, while
Check (an ask's pins) still refuses one.

Builds: design 47 H S8, S9, L10 (H-pins-spec-and-gaps section 8 item 4); H-A-204, H-A-165
2026-11-20 23:24:16 +01:00
jschoubben 64d5490ea2 Design 47 H1 (3): a publish whose recompute fails is not acknowledged
The registry's published is offered again when the recompute of its users fails, as a failed series write already was.

Builds: design 47 H S15 (H-pins-spec-and-gaps item 3), H-A-167
2026-11-20 23:21:23 +01:00
jschoubben 7199824e9d Design 47 H1: indexer_take_in_again re-reads a repository at its kept merge
A repository with no merge since the walk of the module graph keeps its
modules' direct requirements only, and no tool took it in again. The tool
asks the indexer, through the state takeins, to read the repository's trees
at the merge its taken key keeps and apply them as a take-in does, whose
recompute of the modules state is the one a publish re-pin runs; kept
requirements and pins gain the transitive packages. An unknown repository,
or one never taken in, is refused in the answer and as the tool's error.
It keeps no catalog revision yet: H-A-211's revision follows with the
re-pin's.

Builds: design 47 H H-A-208, H-A-210, H-A-201 (hq a7b876c1, d7d18ef0)
2026-11-20 23:16:25 +01:00
jschoubben c418f49038 Design 47 H1: held test steps are asked from the pipeline's own catalog revision (H-A-205, H-A-207)
The runner built the asks of the steps that waited for their pins from the
branch's newest catalog half, so a newer revision that moved the module
changed what a passed build's tests fetched. The entry is now read at the
pipeline's own revision through the runner's revision reader, which keeps
what it read; a revision that cannot be read, or whose entry is of another
fingerprint than the mover's, ends the held steps could not run, naming
why.

Builds: design 47 H H-A-205, H-A-207, H-A-203
2026-11-20 23:13:47 +01:00
jschoubben e29aa8aca9 Design 47 H1: a done build key keeps the pins it was built with, and its step's end reports those (H-A-207)
A build step whose key was done before reported the pins it resolved at
that moment, so a publish since would have the runner ask the waiting
test steps against a version the build was never built with. The done
key's record keeps the versions its Go ask was built with, beside its
digests, and the step's end reports the record's; a done key keeping none
reports none, so the runner ends those steps could not run, loud.

Builds: design 47 H H-A-207, H-A-203
2026-11-20 23:12:29 +01:00
jschoubben 64cba95a10 Design 47 H1: a held test step is asked with the pins its build passed with (H-A-207)
When the build of an entry with an empty pin passed, its held lint, unit
and integration steps had no pin to run with and nothing ended them, so a
pipeline stood running and, one pipeline at a time, the queue stopped. The
runner reads the pins the build's end names and, when the build passed,
asks each held step with them, its fetch the entry's as placed; a passed
build whose end names no pins ends the held steps could not run, naming
why, as does an artifact the branch's half no longer names.

Builds: design 47 H H-A-207, H-A-206, H-A-203
2026-11-20 23:07:33 +01:00
jschoubben cb26645614 Design 47 H1: the build step's end reports the pins it was built with (H-A-207)
A test step held for an entry's empty pin had nothing to run with once the
build passed: the builder took the pin from the registry and kept it to
itself. The seat mesh-builds' step end gains packages, and the builder sets
it from the pins each entry was built with, the registry's included, so the
runner asks the held steps with what the build was built against. The
seat's definition changes: its Go and TypeScript contracts are generated
again.

Builds: design 47 H H-A-207
2026-11-20 23:05:08 +01:00
jschoubben b0d2d22002 Design 47 H1: indexer_entry reads one entry's pins and paths at a revision
A reader twice could not read one entry's pins because the whole revision
(1.3 MB) exceeds what the bus carries; the tool answers one module's
packages, paths per artifact, fingerprint and manifest digest, at the
newest trunk revision (read as entryOf reads it) or at a given one from
its kept list and that one entry object.

Builds: design 47 H H-A-204 (hq f977c0e2); tools-are-how-a-module-is-spoken-to
2026-11-20 23:04:07 +01:00
jschoubben 014f7b7c2f Reserve the version of an ask admitted by its kept revision (H-A-205)
An ask of an older kept revision was admitted, but after a builder restart its fingerprint had never been heard on
the branch, so its build neither reserved a version nor was checked against one and passed silently. Each asked
fingerprint is now recorded as the branch's (its source revision, and first as the module's registration says),
without moving what the picture heard, so the newer fingerprint's build is not superseded.

Builds: design 47 H H-A-205, H-A-155
2026-11-20 23:03:45 +01:00
jschoubben 0fcc614e25 Build an ask of an older kept revision by reading it by number, never waiting (H-A-205)
Two pipelines of consecutive revisions ran at once (main.45, 22:5x CET): the picture held source revision 46, whose
entries had moved on, so the older pipeline's builds waited for a picture that only moves forward and failed "revision
45 of main not in the builder's picture within 2m0s". An ask of a source revision below the newest the picture holds
now reads its catalog revision by number through the catalog seat's verb revision (kept while its pipeline runs,
H-A-147) and is built when that revision is of its source and names every entry it asks; only a revision above the
newest is waited for (H-A-155).

Builds: design 47 H H-A-205, H-A-147, H-A-155
2026-11-20 22:59:31 +01:00
jschoubben e3fed77515 Design 47 H1: a Go step waits for its entry's pins as the build does (H-A-206)
An entry may name a package with no version yet, and the runner cannot pin
it from a publish it does not hear, so a step asked then is refused by the
Go build module. The placing now asks a Go artifact's lint, unit and
integration steps only when every pin of the entry has a version; until
then each stands waiting, its why "waits on the publish of <path>" as the
build's wait reads, said in the journal and read by show. When the mover's
build ends without passing, the held steps end as it ended; the publish
re-pins the entry and moves the mover, whose pipeline runs them. A held
step still counts in the judgement of a seat with no holder.

Builds: design 47 H H-A-206, H-A-203, H-A-165
2026-11-20 22:58:30 +01:00
jschoubben 94202fb651 Design 47 H1: a release re-pins every entry naming its package
A release re-pinned only the entries whose pins already named one of its
packages, so an entry whose module did not change and whose pins left the
package out was never re-pinned. Every kept entry whose pins or kept
requirements name a package of the released module is now re-pinned, of
any repository and changed or not; its fingerprint moves with the pin.

Builds: design 47 H H-A-204, H-A-165, H-A-167, H-A-201
2026-11-20 22:58:06 +01:00
jschoubben 0418a2b94b Design 47 H1: an entry's packages never leave out a requirement
Build asks were refused for a requirement with no pin: the import form's
versions name only what the last build imported, and the version line
leaves out a package none publishes, so the pins kept only those. The pins
now name every other-repository package of the module's go.mod graph (its
kept packages), at the newest published version of its accepted series, or
with no version while none is published, so the builder waits for it.

Builds: design 47 H H-A-204, H-A-201, H-A-165, H-A-167
2026-11-20 22:57:26 +01:00
jschoubben a926a40eed Design 47 H1: every step ask fetches with the entry's pins, as the build does (H-A-203)
The runner's lint, unit and integration asks carried no pins, only the
build ask did, so the Go build module, which refuses a requirement of
another repository with no pin, could not run twelve test steps of the
contracts mover (main.45). stepAsk now puts the entry's packages into the
fetch in the form the entry keeps and the builder sends, so a test runs
against what the build was built against; a package the entry names with
no pin yet is left out.

Builds: design 47 H H-A-203, H-A-192, H-A-183
2026-11-20 22:55:36 +01:00
mesh-tools b9cc97470b Merge pull request 'Design 47 H1: the entry pins every requirement of the module graph; same-repository directories move the fingerprint (H-A-201, H-A-202)' (#296) from fix/47-H1-package-tree-paths into main 2026-11-20 21:37:24 +00:00
mesh-tools ae91f91e88 Merge pull request 'Design 47 H1: the catalog seat's hand-written digest helpers live in its client (H-A-200)' (#295) from fix/47-H1-contracts-steps into main 2026-11-20 21:37:22 +00:00
jschoubben 4664eb1b00 Design 47 H1: the entry pins every requirement of the module graph
The Go build module borrowed a sibling's version for a mesh package the
entry did not pin (a transitive requirement), and given no pin it now
refuses. The indexer now pins, in the entry's packages, every mesh package
of another repository that the go.mod of the module's directory, of each
Go package artifact's directory and of every same-repository module they
require transitively names. A module of the module's own repository is
never pinned, whatever a build reported: it is built from the tree.

Builds: design 47 H H-A-201, H-A-183, H-A-157, H-A-202
2026-11-20 22:30:45 +01:00
jschoubben d9a3458927 Design 47 H1: a Go build's same-repository modules move its fingerprint
A Go build resolves the same-repository modules its go.mod files require at
the zero version, transitively, from the fetched tree; a change in one of
them must move the fingerprint, whatever the module's form. The indexer
walks the go.mod graph of the module's directory and its Go package
artifacts at the take-in and appends a line per derived directory and its
git object to the tree input; the entry's paths keep the manifest's form,
and the Go build module derives the same directories itself.

Builds: design 47 H H-A-202, H-A-172, H-A-157, H-A-198
2026-11-20 22:29:15 +01:00
jschoubben b058389d46 Contracts: the catalog seat's manifest-digest helpers move to its client, out of the generated root (H-A-200)
The seat generator's check failed every unit step of the contracts mover (pipeline main.43): manifestdigest.go was
written by hand under go/seats/meshcatalog (598125a1), a generated root every file of which is the generator's. The two
helpers move to the seat's hand-written client meshcatalogclient and their callers in the builder and the indexer
follow; the generator then writes the contract as the module holds it. steprun's generator test now also holds this
repository's own contracts module in step under both roots.

Builds: design 47 G §370, G §578, H §774, H-A-200 (ADR 0608 §5)
2026-11-20 22:18:00 +01:00
jschoubben 6c65e82926 Design 47 H1: a step's named path may leave the module's directory, never the repository
A package artifact's tree names same-repository siblings its go.mod requires
as "../<module>/<dir>"; the fetch request's check and the narrowing refused
them as leaving the module. They are now accepted when their join with the
module's directory stays inside the repository, narrowed from the root, and
refused when they leave the repository.

Builds: design 47 H H-A-198, H-A-199, H-A-157, H-A-172
2026-11-20 22:14:53 +01:00
mesh-tools d40f314e52 Merge pull request 'Design 47 H1: the grants holder keeps the catalog revisions it read and learns the newest from the event (H-A-193, H-A-195)' (#294) from fix/47-H1-grants-for-cache into main 2026-11-20 20:56:03 +00:00
mesh-tools fc85f7b936 Merge pull request 'Design 47 H1: the assigner's test helper holds its map writes under a lock (H §774)' (#293) from fix/47-H1-assigner-test-race into main 2026-11-20 20:52:56 +00:00
mesh-tools 37a8f7a83e Merge pull request 'Design 47 H1: a pipeline's steps and unlogged entries live under one key per mover (H-A-187, H-A-189, H-A-190, H-A-191)' (#292) from fix/47-H1-runner-steps-per-mover into main 2026-11-20 20:52:51 +00:00
mesh-tools 9ef830d224 Merge pull request 'Design 47 H1: the builder fetches a module whole and never computes a pin (H-A-186, H-A-192, H-A-194)' (#291) from 47-H1-builder-program-paths into main 2026-11-20 20:52:45 +00:00
jschoubben 120a0554d6 mesh-grants: grants-for keeps a bounded cache of the followed branches
The kept catalog revisions had no design line and their bound stood in
the code. They are now bounded per branch by the module's setting
grants-for-revisions-per-branch (default 4, oldest dropped, a run's
candidate counted within its branch's), read at the start from the file
the manifest writes, and kept only for the watched branches the part's
branch follower follows: a branch that leaves them is freed at the next
grants-for or catalog-revision event. A kept revision is a cache of the
catalog seat's own truth, never a state of the mesh.

Builds: design 47 G §441, §401; H H-A-195, H-A-193
2026-11-20 21:51:43 +01:00
jschoubben d8a900dac0 Read what the registry seat holds before a build waits for an unpinned package (H-A-194)
The publishes the builder heard lived only in its memory, so a build waiting for a package published before a
restart waited the whole bound and failed although the registry held the version. Before it waits, the build asks
the Go package registry seat's versions once for each unpinned path and takes the newest in the accepted series
through PackagePublished; a failed read is said and the wait goes on by the published events.

Builds: design 47 H H-A-194, H-A-192, H-A-165
2026-11-20 21:48:40 +01:00
jschoubben a62f7b40c1 mesh-grants: grants-for learns the newest revision from the event
A grants-for call still read the first page of each revision (up to
768 KB) only to learn its number. The grants holder already hears the
seat mesh-catalog's catalog-revision event, which names each branch's
newest trunk revision and the source revision it was taken in from; the
part now records both from the event and asks the revision verb only for
a revision it does not hold, by its number. Before the first event after
a start the first ask's answer names the newest once. An event below the
newest held is the numbering started again: what is kept of the branch
is dropped.

Builds: design 47 G §441, §401; H H-A-193
2026-11-20 21:44:06 +01:00
jschoubben 429f03d4cf Pin an unpinned package only at the version its registry publish carries (H-A-192)
A step ask waiting for a package the entry names with no pin took the release number of the module holding it
("v" + release), and the lane of an entry taken in dropped the empty pin and asked its build without one, so the Go
build module took another package's version: both built against versions never published (main.41, v0.1.25,
v0.1.97, v0.1.103 of the builder's builds). The builder now hears each package registry seat's published (the
package path and the version it carries) and keeps the newest per series; a build, the step's and the lane's alike,
waits for one in the series its module's manifest accepts (packages, else the default) up to package-wait-minutes,
and past it fails naming the package. The release-number pin (VersionReleased, NewestReleased) is gone.

Builds: design 47 H H-A-192, H-A-183, H-A-184, H-A-185, H-A-165
2026-11-20 21:42:33 +01:00
jschoubben 20d59ff4f0 mesh-grants: grants-for keeps the catalog revisions it read
grants-for read two whole catalog revisions page by page on every call
(about 1.4 MB each) and answered in 3.4 to 5.0 s, so the pipeline
runner's 5 s read bound cut it and every widening touching the vault
said "could not run". A revision never changes, so the part now keeps
each revision it read whole, by branch, kind, group, heads and number,
the newest four per branch for the process's life (as the runner keeps
its revisionCache); once a first page names a kept revision the pages
after it are not read. The branch's newest is read on by the number its
first page names, and a revision whose pages name another is not kept.

Quick fix (not chosen): raise the runner's widens read bound, a catalog
merge that hides the cost. Thorough fix (chosen): the cache here. The
compose of every account twice is kept whole: narrowing it to the
candidate's modules would stop a refused principal elsewhere from
failing grants-for, which is not obviously safe.

Builds: design 47 G §441, §401; H §774
2026-11-20 21:40:15 +01:00
jschoubben 12b18721b9 Build a module with a program naming no paths from its whole directory (H-A-186)
Since #290 the builder's manifest declares its packages builds and buildrun with paths beside the program and
tools, which name none. ModuleOf took the entry's named paths of any artifact as the module's, so the lane's one
fetch was narrowed to builds/ and buildrun/: the module's go.mod and cmd/ were removed and the program's build
failed with "go: cannot find main module" (main.42, 21:10 and 21:13 CET). An artifact without paths keeps its
module's directory as its build source (ADR 0499 clause 1); only a module whose every artifact names its paths is
built from those alone (clauses 2 and 4), as the indexer's own value already has it.

Builds: design 47 H H-A-186, H-A-188; ADR 0499 clauses 1, 2, 4
2026-11-20 21:28:39 +01:00
jschoubben 3183e0e056 Design 47 H1: a mover's unlogged entries live under its mover key, each entry names its mover, and list answers records with counts (H-A-189, H-A-190, H-A-191)
The record still kept every ended step's unlogged step-log entry, so a step
log outage across a large pipeline grew the record as its steps had. A
mover key now holds its steps and its unlogged entries, written in the same
compare-and-set; the record keeps neither. An entry of the step log names
its mover's module, set where an entry is made, so two movers' approvals
ending at one moment are filed under their own keys and told apart when
read back; an older entry naming none goes under the one mover whose step it
matches, else stays in the record. list answers each pipeline's record with
its movers and steps counted and its steps empty; show keeps the steps. The
seat's definition changes: its Go and TypeScript contracts are generated
again.

Builds: design 47 H H-A-187, H-A-189, H-A-190, H-A-191
2026-11-20 21:22:09 +01:00
jschoubben 30ccad4edc Assigner tests: hold putInto's writes one at a time
The composition step starts its machines' runs side by side, and each may
raise assignment-unlisted into the test's map: unguarded, the unit suite
crashed now and then with concurrent map writes. Only the test raced; the
running module writes the bus's findings state.

Builds: design 47 H §774
2026-11-20 21:15:50 +01:00
jschoubben 4e585f02b1 Design 47 H1: the runner keeps each mover's steps under its own key, so a record never grows with the catalog (H-A-187)
The runner's state pipelines held a pipeline's every step in its record, and
a record of 112 or 129 movers exceeded the bus's 1 MiB message limit (ADR
0486), so main.26 and main.30 placed no step. One MoverStore per process now
reads and writes the state: the record keeps the movers, tiers, call, source
and outcome with its own steps empty, each mover's steps are written under
steps.<pipeline>.<mover> by compare-and-set as the record is, and nothing is
written when the record or a mover key changed since the read. Every read
and judgement of steps goes through it, so the placing, the step ends, the
end judgement, the hand acts and the ageing see one composed pipeline; show,
list, stands and why-carried compose from the mover keys, and show naming a
mover answers its steps alone. A record still carrying its steps inline is
read whole, said once in the journal, and split at its next write, its
mover keys written before the record.

Builds: design 47 H H-A-187
2026-11-20 21:11:59 +01:00
jschoubben f2d3172eac Design 47 H1: the seat mesh-pipeline-runner keeps a mover's steps under its own key, and show names a mover (H-A-187)
A pipeline record of 112 or 129 movers exceeded the bus's message limit once
its steps were placed (main.26, main.30), so its steps could never be
written. The state pipelines gains the key form steps.<pipeline>.<mover>,
one mover's steps, and show takes an optional mover whose steps it answers
alone. The seat's definition changes: its Go and TypeScript contracts are
generated again.

Builds: design 47 H H-A-187
2026-11-20 21:11:59 +01:00
mesh-tools e4781edcd6 Merge pull request 'Design 47 H1: the Go packages other modules import are declared artifacts of their modules (H-A-186, H-A-188)' (#290) from fix/47-H1-declare-package-artifacts into main 2026-11-20 20:08:40 +00:00
jschoubben 1db38fcc72 Declare asks in the assigner's version series, and have the teller and the view accept it there (H-A-188)
The builder numbers every artifact of a release in its module's version, so the assigner's package asks is
published in 0.3, not the 0.1 eba4309b declared: asks now names series 0.3, and the teller and the view, which
import it, accept it at 0.3 in their manifests' packages. The other eight packages' modules are all at 0.1, so
their series stand. The gate in mesh-catalog, which imports asks too, follows with the catalog's next change.

Builds: design 47 G §370, H-A-186, H-A-188
2026-11-20 21:05:39 +01:00
jschoubben eba4309b19 Declare every Go package another module imports as a package artifact of its module (H-A-186)
mesh-build-go and other modules import packages of this repository that no manifest declared, so no release
published them and the registry holds no version: their importers stay unpinned and fail past the bound. Each
module now declares its imported packages in the form they had before issue 1966's bootstrap took them out:
asks (assigner), builds and buildrun (builder), forgemsg (forge bridge), takein (indexer), tellerevents
(teller), viewstate (view), grantsstate and busgrants (grants), each a Go package of series 0.1. Each
module's manifest test asserts its packages again.

Builds: design 47 G §370, H-A-186
2026-11-20 20:58:06 +01:00
mesh-tools a7fc37561e Merge pull request 'Design 47 H1: a pin is the version the registry published for the package path within the module's accepted series (H-A-183, H-A-184, H-A-185)' (#287) from fix/47-H1-pins-by-package-path into main 2026-11-20 19:15:04 +00:00
jschoubben e93575ffe7 mesh-delivery-indexer: the accepted series is the manifest's, contents or none
The pin fell back to the path's newest publish while no series value
held contents, which live none does, so a publish in a series a module
does not accept pinned it. The series a module accepts is the one its
manifest names, or the default; the pin is the newest version published
for the package path within it.

Builds: design 47 H H-A-185, H-A-184
2026-11-20 20:13:15 +01:00
jschoubben 859f88b2f0 mesh-delivery-indexer: a pin stays within the series the module accepts
A pin by the package path across every series moved a module to a
series it does not accept while its contents came from the accepted
one. The pin is the accepted series' newest published version where
that series gives the contents; only where none does yet is it the
newest published of the path. A publish in another series pins nothing
and moves nothing.

Builds: design 47 H H-A-184, H-A-183
2026-11-20 20:07:46 +01:00
jschoubben 517a4b3cf1 mesh-delivery-indexer: a pin is the version the registry published for the package's path
At main.39 every importer of a nested package was pinned to the release
number of the module holding it (v0.1.97 of the builder for its package
builds), and the Go seat found no tag <package dir>/v0.1.97. A Go
package's version is its tag: the pin is now the newest version the
registry published for that package path (the seats' published, kept in
the package's series), never a module's release; a package the
registry never published stays unpinned.

Builds: design 47 H H-A-183, H-A-167, G §370
2026-11-20 20:05:52 +01:00
mesh-tools 7f88916863 Merge pull request 'Design 47 H1: the forge bridge keeps only an act's outcome and pull request; the act stays in the gate's stream (H-A-181, H-A-182)' (#286) from fix/47-H1-bridge-performed-cap into main 2026-11-20 18:46:57 +00:00
jschoubben 5dee4cb263 mesh-delivery-forge-bridge: owed again refuses a performed value of the old form
A value kept before this change names no pull request, so bridge_owed_again read the subject owed..0 and said the
stream no longer held the act while it did. Every act the bridge decodes names its repository, so a value without
one is the old form: refused with what is true, never read again; it expires with the state's TTL.

Builds: design 47 G §163; H-A-182
2026-11-20 19:45:38 +01:00
jschoubben 77b683c1c1 mesh-delivery-forge-bridge: performed keeps the outcome and the pull request, not the act
The state performed filled to 77% of its template's 64 MiB (19,530 keys, 2.6 KB each): the bridge kept every owed
event whole beside its outcome. performed's value is now the outcome said as owed.ended, with when, and the
repository and number the act names (groups.Performed); bridge_owed_again reads the act from the gate's stream owed
on its pull request's subject through an ordered consumer, the stream being the act's one copy; bridge_owed reads
one act or one pull request's acts, never the whole state, whose answer had grown past what the bus carries.

Builds: design 47 G §163, §162, §168; H-A-181, H-A-182
2026-11-20 19:38:34 +01:00
mesh-tools 60e32772a5 Merge pull request 'Design 47 H1: the composition step of a module no machine holds ends nothing to run (H-A-179)' (#285) from fix/47-H1-composition-nothing-to-run into main 2026-11-20 18:08:15 +00:00
jschoubben fd2ef6c7e8 assigner: a mover no machine holds has nothing to compose (H-A-179)
A package module with a required composition step and no node placing
it ended could not run, so its pipeline could never pass. A step with
nothing to judge ends nothing to run, which counts as passed, saying why.

Builds: design 47 H H-A-179
2026-11-20 19:05:49 +01:00
mesh-tools 71371df160 Merge pull request 'Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7)' (#284) from proof/47-H1-two-modules-2 into main 2026-11-20 17:55:44 +00:00
jschoubben b2d5644c34 Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7) 2026-11-20 18:55:12 +01:00
mesh-tools 9598b92c39 Merge pull request 'Design 47 H1: the runner's integration tests make the module's findings stream (H §743)' (#283) from fix/47-H1-runner-queue-test into main 2026-11-20 17:37:22 +00:00
mesh-tools f00d34673f Merge pull request 'Design 47 H1: the indexer's runs-candidate test is folded into TestIndexerWhole and waits for the run-started's acknowledgement (H §743)' (#282) from fix/47-H1-indexer-runs-test into main 2026-11-20 17:35:17 +00:00
jschoubben 87357d84bd mesh-delivery-pipeline: the queue and run tests make the module's findings stream
Built against mesh-sdk at its pin (H-A-166, H-A-169), the runner counts every
event no handler takes as a finding; with no stream for its finding events each
write waited its 3 s for the bus, holding the event loop, so the queue test ran
into its 90 s bound. The tests now make the stream the manifest asks for.

Builds: design 47 H H-A-176, H-A-175 (the tests of the runner's placing), H-A-166, H-A-169
2026-11-20 18:31:59 +01:00
jschoubben 08dde53e33 mesh-delivery-indexer: the run on request's bed lives in TestIndexerWhole, its restart after the run-started's acknowledgement
TestIndexerBuildsARunsCandidateAndDropsItWhenEveryMembersPipelineEnded failed on the build node
under load (pipelines main.29 and main.31). It restarted the indexer as soon as the candidate was
written, before the run-started was acknowledged (the write comes first), and it polled both
waits with sleeps: the same kind as the toolchains bed's restart fixed in 20a7bd0f. A stop
between the write and the acknowledgement leaves the run-started for redelivery after its
acknowledgement wait, which writes the candidate again once its run has ended.

The run is now one more step of TestIndexerWhole around its restart: run-started of run 9 writes
candidates.run-9 and the run's key (watched, not polled), the restart waits for the run-started's
acknowledgement beside the source-moved's, and the member's pipeline-ended after the restart drops
both. The separate test is removed: the module's integration tests go from 541 to 540; no test
added.

Builds: design 47 H §743
2026-11-20 18:30:27 +01:00
mesh-tools c772eb0683 Merge pull request 'Design 47 H1: a build module's inputs do not wait for its toolchain; a cycle among unplaced movers ends loud (H-A-175, H-A-176)' (#281) from fix/47-H1-runner-order-cycle into main 2026-11-20 17:17:28 +00:00
jschoubben a7b2fb0ffa mesh-delivery-pipeline: a cycle ends only its own steps; the end judgement ends the pipeline
A cycle ended every open step of the pipeline at once and named edges outside
it. It now ends not asked only the steps of the movers without steps, names
the edges inside a strongly connected group alone, and leaves the pipeline's
end to the end judgement, so running steps run to their end.

Builds: design 47 H H-A-176, H-A-175, H-A-163, G §270, G-22 A-326
2026-11-20 18:15:47 +01:00
jschoubben ef086e0b75 mesh-delivery-pipeline: a cycle among unplaced movers ends the pipeline failed
A cycle the running build module does not break left a pipeline running with
journal lines only, since validate is asked only for a placed mover. The
placing now ends it failed, its why naming each artifact and edge kind.

Builds: design 47 H H-A-175, G §270, G-22 A-326, H-A-101 (2)
2026-11-20 18:12:04 +01:00
jschoubben a8adda1a8c mesh-delivery-pipeline: a build module's own inputs await not its toolchain edge
A pipeline moving the Go build module with a package it imports (mesh-sdk,
mesh-delivery-contracts) placed nothing: the package's build awaited the new
build module's files, the build module awaited the package. What a build
module's new version is built from is built by its running version.

Builds: design 47 G §270, G-22 A-326, H §746, H-A-83 (2)
2026-11-20 18:09:07 +01:00
mesh-tools e1f0c1a1cc Merge pull request 'Design 47 H1: a release pins the revision its entry lives in; freed by the module's next release (H-A-168, H-A-170, H-A-173, H-A-174)' (#280) from fix/47-H1-release-pins into main 2026-11-20 17:03:27 +00:00
jschoubben bf24bb9740 mesh-delivery-indexer: a tier-late pipeline-wanted frees no release
A tier-late pipeline's later-tier movers released a version, so the newer revision holds their
release record, yet their wants were not written: freeing their older release on the tier-late
event would remove the revision their want names. HeardPipelineWanted now reads the event's outcome:
tier-late frees nothing, and the same pipeline's later pipeline-wanted with outcome running frees as
before. The pins test's freeing sequence says a tier-late event first (nothing freed), then the
running one (the older release freed); the events test's row hands the outcome on. No test added.

Builds: design 47 H-A-174 (hq design/47-H1-answers-59 84e2514d), H-A-173
2026-11-20 18:01:56 +01:00
jschoubben 814244fd5a mesh-delivery-indexer: a release pin only for a released mover, freed only by a newer release of it
A passed pipeline's movers include ones the assigner never takes (superseded, no version released,
a tier-late pipeline's later tiers); freeing their older release on the newer pipeline-wanted would
remove the revision their want still names, and a mover releasing nothing would pin a revision per
pipeline for good. The release record is now written only for a mover that released a version in
the pipeline, and pipeline-wanted frees a module's older record only where the newer pipeline's own
revision holds that module's release record.

Tests: a pins table row (a passed mover with no version pins nothing), the freeing sequence (a
passed pipeline releasing no version frees no older release, the next one that releases does), and
TestIndexerWhole now says a pipeline-wanted on the bus after main.12's passed end and waits for
main.11's release to be freed and main.11 removed, so the indexer's hearing of pipeline-wanted is
tested end to end (review round 1). No test added.

Builds: design 47 H-A-173 (hq design/47-H1-answers-59 21297155), H-A-170, H-A-168
2026-11-20 17:58:45 +01:00
mesh-tools 442b03f61d Merge pull request 'Design 47 H1: package edges from go.mod; a pin is the newest released version, in every form's fingerprint; a release re-pins its importers (H-A-157, H-A-161, H-A-165, H-A-167, H-A-172)' (#279) from fix/47-H1-package-edges-from-gomod into main 2026-11-20 16:53:25 +00:00
jschoubben 9083287d57 mesh-delivery-indexer: a passed pipeline's release pins its revision until a newer one is the want
The pin judge removed main.23 and its entries when main.24 became current, while the assigner had
just written main.23's builder as the want: the node-engine asked its entry and was told none is
kept, holding the want for good. A passed pipeline-ended now pins the pipeline's kept revision
under a record release.<branch>.<module>, one per mover, beside the pipeline's own pin; the seat
mesh-wants' pipeline-wanted of a newer pipeline on that branch (its wants written to the end,
tier-late included) frees that record from every revision below the newer one, for each module the
newer revision's movers name. The indexer consumes pipeline-wanted (its manifest says so). A
revision a release pin holds keeps its entries, as removeUnlisted already does for any kept revision.

Tests: rows in the pins table (a passed pipeline's revision kept once no longer current; a failed
one's goes), the freeing in the pins test (a release past a failed pipeline, freed by the next
passed one's pipeline-wanted, twice changing nothing), and a pipeline-wanted row in the events
test. TestIndexerWhole now reads main.11's release beside its validate base, and waits for the held
source-moved's acknowledgement before it reads the consumer (the write comes first). No test added.

Builds: design 47 H-A-168, H-A-170 (hq design/47-H1-answers-59 87b43ec8), H-A-147, H §749
2026-11-20 17:50:08 +01:00
jschoubben d0436bb38c mesh-delivery-indexer: pins are in every form's fingerprint
The import form's fingerprint left the pins out, so an importer whose
trunk build reported its imports never moved on a re-pin and was never
built again against the release. Every form now takes its sorted pins;
a build that stands keeps its fingerprint while its pins are the ones
it was built with, and a fingerprint with no pin stays as it was.

Builds: design 47 H H-A-172, H-A-167
2026-11-20 17:46:53 +01:00
jschoubben fe51379ee2 mesh-delivery-indexer: a release re-pins or is not acknowledged; pins enter the version line's fingerprint
A re-pin that left the fingerprint as it was left the build made
against the older pin as the one the mesh runs. The version line's
fingerprint now takes the pins, so a re-pin moves the importer, which
becomes a mover built against the release. An accepted series' older
version no longer stands over a newer release. A re-pin that fails
returns its error before the heard artifacts are forgotten, and a
package-published heard again for a released version re-pins, so the
redelivery recovers it. The release path and the seed's pins carry
tests that fail without them (review round 2).

Builds: design 47 H H-A-165, H-A-167, H-A-161
2026-11-20 17:46:53 +01:00
jschoubben 037cb9555e mesh-delivery-indexer: a version-released re-pins the modules holding the package
Pins moved to a new released version only at the next merge, toolchain
report or hand recompute. The release now starts the pass of H-A-161
for the modules whose packages hold a package of the released module
alone; every other module stands as held.

Builds: design 47 H H-A-165 (the indexer's part), H-A-161
2026-11-20 17:46:53 +01:00
jschoubben 5c5136d6d1 mesh-delivery-indexer: the requirements state reads the go.sum whatever packages the reader carried
With the go.mod's mesh requires carried at every take-in, requirementsOf
returned early for every module requiring a mesh package: its go.sum was
never read and keepRequirements never cleared an old version it named
(indexer_requirements for mesh-sdk still names v0.1.13). The go.sum is
read whenever its hash moved or this process has not kept it yet.

Builds: design 47 H H-A-157 (review round 1)
2026-11-20 17:46:53 +01:00
jschoubben c43e7a5d1c mesh-delivery-indexer, mesh-delivery-builder: a package is pinned by its released version, never by a commit
The indexer filled a module's packages with the commit of a module value
it holds, which Go turned into a pseudo-version of whatever that tree
was (mesh-delivery-sdk at an 11-19 commit, nodeengine pre-H1). A pin is
now the newest released version of the module holding the package (the
versions state version-released says), an accepted series' version
stands, and a package with none released is kept with no version: its
kind-1 edge stands and the builder asks no pin for it. A commit of
another repository moves a module only through a package of it the
module imports (A-476a), now that pins name no commit.

Builds: design 47 H H-A-161, G §370, H §746, H-A-157 (kind-1 edges)
2026-11-20 17:46:53 +01:00
jschoubben e04321acae mesh-delivery-indexer: a build's reported imports refine the go.mod's packages, never empty them
An import form whose imports name no package of another repository, or a
build that stands with versions held empty from the go.sum era, wrote an
empty package set while the go.mod requires a mesh package: no kind-1
edge. The version line's versions of the go.mod's set stand then.

Builds: design 47 H H-A-157, G §47 (kind 1)
2026-11-20 17:46:53 +01:00
jschoubben 4c2914194b mesh-delivery-indexer: a module's mesh packages are what its go.mod requires
At main's revision 21, 64 of 82 Go modules carried no package edge: the
version line read the mesh packages go.sum names, and go.sum names none
required at the zero version (ADR 0573 §2). The take-in now reads them
from the go.mod's require lines, at any version, with no build needed;
the go.sum is read only for the requirements state. The sibling rule
(replaces by a directory) stands.

Builds: design 47 H H-A-157, H-A-136 (sibling rule), G §47 (kind 1)
2026-11-20 17:46:53 +01:00
239 changed files with 13226 additions and 1664 deletions
@@ -95,15 +95,17 @@ type machineEnd struct {
// run runs one composition step and answers what it came to: per machine not away it joins or starts the candidate's
// composition run (§718), waits for each run's end in its key, and judges each machine from it; failed when a machine does not
// compose, could not run when a machine could not be composed or was not judged, else passed with a warning per machine away.
// compose, could not run when a machine could not be composed or was not judged, nothing to run when no node places the module on
// the branch (H-A-179), else passed with a warning per machine away.
func (r *compositionRun) run(ctx context.Context, id string, step meshwants.StepRun) stepOutcome {
candidate, err := candidateKeyOf(step)
if err != nil {
return couldNotRun(err.Error())
}
nodes := r.inputs.machines(step.Module, step.Branch)
if len(nodes) == 0 {
return couldNotRun(fmt.Sprintf("no node places %s on the branch %q, so the composition step has no machine to compose", step.Module, step.Branch))
if len(nodes) == 0 { // a mover no machine holds on the branch has nothing to judge: nothing to run, passed (H-A-179, ADR 0682 §8)
return stepOutcome{Outcome: meshwants.StepEndedOutcomeNothingToRun,
Said: fmt.Sprintf("no node places %s on the branch %q, so the composition step has no machine to compose", step.Module, step.Branch)}
}
reader := readerOf(id, step)
prep := &runPrep{r: r, step: step}
@@ -214,7 +216,7 @@ type runPrep struct {
seats []json.RawMessage
manifests map[string]composer.Manifest
none map[string]string
programOf func(node string) (buildstep.RunProgram, string, error)
programOf func(node string) (buildstep.RunProgram, string, map[string]string, error)
err error
}
@@ -272,7 +274,7 @@ func (r *compositionRun) start(ctx context.Context, key string, run meshwants.Co
end(node + " gave no composition input: " + in.Why)
return
}
program, engineFp, err := prep.programOf(node)
program, engineFp, pins, err := prep.programOf(node)
if err != nil {
end(node + ": " + err.Error())
return
@@ -315,7 +317,8 @@ func (r *compositionRun) start(ctx context.Context, key string, run meshwants.Co
return
}
a := buildstep.StepAsk{ID: ask, Kind: buildstep.AskCheck, Language: buildstep.AskGo, Asker: runAsker, At: r.now().UTC(),
Run: &buildstep.RunJob{Program: program, Heads: []buildstep.RunHead{}, Input: ref, Reader: "the composition of " + node + " by the node-engine at " + program.Commit}}
Run: &buildstep.RunJob{Program: program, Heads: []buildstep.RunHead{}, Input: ref, Reader: "the composition of " + node + " by the node-engine at " + program.Commit},
Packages: pins} // the composer is built against its entry's pins, as every build (H-A-203, H-A-192)
if err := r.put(ctx, a); err != nil {
end(node + ": its run ask " + ask + " is not put: " + err.Error())
}
@@ -730,53 +733,76 @@ func programOfEntry(e meshcatalog.CatalogEntry) (buildstep.RunProgram, error) {
return buildstep.RunProgram{Repository: e.Repository, Commit: e.Commit, Dir: dir, Package: composer.Package}, nil
}
// pinsOfEntry are the mesh packages' versions an entry pins, the ones it names with a version (H-A-203, H-A-183): the pins
// a run's program is built against, in the form the entry keeps and the builder sends. nil when it pins none.
func pinsOfEntry(e meshcatalog.CatalogEntry) map[string]string {
var out map[string]string
for path, version := range e.Packages {
if version == "" {
continue
}
if out == nil {
out = map[string]string{}
}
out[path] = version
}
return out
}
// programs answers, per machine, the composer its run builds and the node-engine fingerprint it was chosen from (A-226, A-243,
// A-252, §719): where the revision's node-engine entry differs from the trunk's, that build for every machine; else the build the
// machine's node-engine runs, as its `running` says, its entry read through mesh-catalog's `entry`; a machine whose node-engine's
// `running` is not heard gets the revision's entry, said (A-451).
func (r *compositionRun) programs(ctx context.Context, half mcc.Half) (func(node string) (buildstep.RunProgram, string, error), error) {
func (r *compositionRun) programs(ctx context.Context, half mcc.Half) (func(node string) (buildstep.RunProgram, string, map[string]string, error), error) {
engine, ok := nodeEngineEntry(half.Entries)
if !ok {
return nil, fmt.Errorf("the catalog revision %d holds no module claiming the seat %s", half.Revision.Revision, ne.Seat)
}
if trunk, ok := r.trunk(); !ok || func() bool { t, ok := nodeEngineEntry(trunk.Entries); return !ok || t.Fp != engine.Fp }() {
p, err := programOfEntry(engine)
return func(string) (buildstep.RunProgram, string, error) { return p, engine.Fp, err }, nil
return func(string) (buildstep.RunProgram, string, map[string]string, error) {
return p, engine.Fp, pinsOfEntry(engine), err
}, nil
}
var mu sync.Mutex
byFp := map[string]buildstep.RunProgram{}
return func(node string) (buildstep.RunProgram, string, error) {
type built struct {
program buildstep.RunProgram
pins map[string]string
}
byFp := map[string]built{}
return func(node string) (buildstep.RunProgram, string, map[string]string, error) {
running, ok := r.running(node, engine.Module)
if !ok || running.Fingerprint == "" {
r.logf("%s: no build of %s is heard running there, so its composer is the catalog revision's entry %s (A-451)", node,
engine.Module, engine.Fp)
p, err := programOfEntry(engine)
return p, engine.Fp, err
return p, engine.Fp, pinsOfEntry(engine), err
}
fp := running.Fingerprint
mu.Lock()
p, ok := byFp[fp]
b, ok := byFp[fp]
mu.Unlock()
if ok {
return p, fp, nil
return b.program, fp, b.pins, nil
}
what := "the entry of the node-engine's build " + fp + " is not read"
body, said, err := r.callRetry(ctx, entryVerbKey, meshcatalog.EntryInput{Fingerprint: fp})
if err != nil || body == nil {
return buildstep.RunProgram{}, fp, unreadErr(what, err, said)
return buildstep.RunProgram{}, fp, nil, unreadErr(what, err, said)
}
var a meshcatalog.EntryAnswer
if err := json.Unmarshal(body, &a); err != nil {
return buildstep.RunProgram{}, fp, fmt.Errorf("%s: %w", what, err)
return buildstep.RunProgram{}, fp, nil, fmt.Errorf("%s: %w", what, err)
}
p, err = programOfEntry(a.Entry)
p, err := programOfEntry(a.Entry)
if err != nil {
return p, fp, err
return p, fp, nil, err
}
pins := pinsOfEntry(a.Entry)
mu.Lock()
byFp[fp] = p
byFp[fp] = built{program: p, pins: pins}
mu.Unlock()
return p, fp, nil
return p, fp, pins, nil
}, nil
}
@@ -53,7 +53,7 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
s := &runStand{asks: map[string]buildstep.StepAsk{}, requests: map[string]composer.Request{}}
engine := func(fp, commit string) meshcatalog.CatalogEntry {
return meshcatalog.CatalogEntry{Module: "engine", Fp: fp, Repository: "novox/mesh-host", Commit: commit, Path: ".", Serves: []string{ne.Seat + ".composition"},
Manifest: map[string]any{"module": "engine"}}
Manifest: map[string]any{"module": "engine"}, Packages: map[string]string{"git.novox.be/novox/mesh-sdk/go": "v0.1.25-" + fp, "git.novox.be/novox/x/go": ""}}
}
revisionCommit := commitE1
if revisionEngine != "src2:e1" {
@@ -186,6 +186,13 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
if s.asks["g14"].Run.Program.Commit != commitE2 {
t.Errorf("g14's composer is built at %s, want the build its node-engine runs", s.asks["g14"].Run.Program.Commit)
}
// Each composer is built against the pins of the node-engine entry it is built from, a pin with no version left out
// (H-A-203, H-A-192).
for node, fp := range map[string]string{"ace": "src2:e1", "g14": "src2:e2"} {
if got := s.asks[node].Packages; len(got) != 1 || got["git.novox.be/novox/mesh-sdk/go"] != "v0.1.25-"+fp {
t.Errorf("%s's composer is built against the pins %v; want its entry's", node, got)
}
}
if req.Depth != composer.DepthCompose || req.BlameTries != 20 || len(req.Machines) != 1 || req.Machines[0] != "ace" || len(req.Cases) != 1 || req.Cases[0].Name != changeCase ||
string(req.Input) != `{"node":"ace"}` || len(req.Seats) != 1 || string(req.Seats[0]) != `{"seat":"s1"}` {
t.Errorf("the request of ace %+v", req)
@@ -259,7 +266,11 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
}
none := newRunStand(t, "src2:e1", "src2:e1", "d1")
none.r.inputs.machines = func(string, string) []string { return machines }
if out := none.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeCouldNotRun ||
outcome := meshwants.StepEndedOutcomeCouldNotRun
if len(machines) == 0 { // a mover no machine holds: nothing to run, saying why (H-A-179)
outcome = meshwants.StepEndedOutcomeNothingToRun
}
if out := none.r.run(context.Background(), "ask-step", step); out.Outcome != outcome ||
!strings.Contains(out.Said, want) || (len(machines) > 0 && !strings.Contains(out.Said, "shanks is away")) || len(none.asks) != 0 {
t.Errorf("%s came to %+v, %d asks", name, out, len(none.asks))
}
@@ -15,7 +15,21 @@ import (
// fillOf is the store's fill now: its bytes and cap, when the bucket says them and has a cap.
func (g *graphKeeper) fillOf(ctx context.Context) (used, capacity int64, ok bool) {
f, is := g.objects.(assigngraph.Filler)
return fillIn(ctx, g.objects)
}
// passObjects is the store as the pass reads its fill: a handle of its own where one is given, so the pass's read never shares one
// with a keeping that runs beside it (design 47 H-A-261).
func (g *graphKeeper) passObjects() assigngraph.Objects {
if g.reads != nil {
return g.reads
}
return g.objects
}
// fillIn is the fill of the bucket o, when it says one and has a cap.
func fillIn(ctx context.Context, o assigngraph.Objects) (used, capacity int64, ok bool) {
f, is := o.(assigngraph.Filler)
if !is {
return 0, 0, false
}
@@ -35,13 +49,13 @@ func (p *passer) sayFill(event, about string, used, capacity int64, refused stri
// its cap), so a fill reached while the process was down is said too.
func (p *passer) fillAtStart(ctx context.Context) {
g := p.graph
used, capacity, ok := g.fillOf(ctx)
used, capacity, ok := fillIn(ctx, g.passObjects())
if !ok {
return
}
switch {
case used >= capacity:
g.full = true
g.setFull(true)
p.sayFill(meshwants.EventFull, "start", used, capacity, "the next revision")
case used*5 >= capacity*4:
p.sayFill(meshwants.EventFilling, "start", used, capacity, "")
@@ -52,20 +66,20 @@ func (p *passer) fillAtStart(ctx context.Context) {
// 80 % again. It answers true while the store is full.
func (p *passer) fullBefore(ctx context.Context, c assigngraph.Computed) bool {
g := p.graph
used, capacity, ok := g.fillOf(ctx)
used, capacity, ok := fillIn(ctx, g.passObjects())
if !ok {
return false
}
if g.full && used*5 < capacity*4 {
g.full = false
if g.isFull() && used*5 < capacity*4 {
g.setFull(false)
p.sayFill(meshwants.EventRoom, fmt.Sprint(used), used, capacity, "")
}
if used+assigngraph.NewBytes(ctx, g.objects, c) <= capacity {
g.full = false
if used+assigngraph.NewBytes(ctx, g.passObjects(), c) <= capacity {
g.setFull(false)
return false
}
if !g.full {
g.full = true
if !g.isFull() {
g.setFull(true)
p.sayFill(meshwants.EventFull, fmt.Sprint(used), used, capacity, "the next revision")
}
p.logf("the assignment graph revision is not kept: %s is full (%d of %d bytes), the last revision stays and no want is written until there is room", assigngraph.RevisionsObjects, used, capacity)
@@ -61,14 +61,14 @@ func TestTheAssignmentGraphStoreSaysFillingFullAndRoom(t *testing.T) {
if len(events) != 0 {
t.Fatalf("events %v", events)
}
o.base = 700
o.base, o.cap = 8500, 10000 // past 80 %, with room for the next revision, which the pass judges itself (H-A-261)
p.graph.started = false
p.keepGraph(ctx)
p.keepGraph(ctx) // a start again: its first pass judges the fill
if len(events) != 1 || events[0] != meshwants.EventFilling {
t.Fatalf("at the start past 80 %%: %v", events)
}
c := assigngraph.Computed{Revision: meshwants.AssignmentRevision{Entries: []meshwants.NodeEntryRef{}}}
o.base = 990
o.base, o.cap = 990, 1000
if !p.fullBefore(ctx, c) || !p.graph.full || events[len(events)-1] != meshwants.EventFull {
t.Fatalf("a revision that does not fit: events %v", events)
}
@@ -76,8 +76,15 @@ func TestTheAssignmentGraphStoreSaysFillingFullAndRoom(t *testing.T) {
if n := len(events); n != 2 {
t.Errorf("full is said once: %v", events)
}
// H-A-261: the verdict is the pass's own: with the store full the pass writes no want, though a revision is kept.
if held := p.keepGraph(ctx); held != heldFull {
t.Errorf("a pass with the store full answers %q, want %q", held, heldFull)
}
o.base = 100
if p.fullBefore(ctx, c) || p.graph.full || events[len(events)-1] != meshwants.EventRoom {
t.Errorf("room: events %v", events)
}
if held := p.keepGraph(ctx); held != "" {
t.Errorf("a pass with room and a revision kept answers %q, want the wants written", held)
}
}
@@ -8,6 +8,7 @@ import (
"fmt"
"slices"
"strings"
"sync"
"time"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
@@ -24,11 +25,18 @@ import (
// that follows are written from the revision it holds.
type graphKeeper struct {
objects assigngraph.Objects
// reads is the same store through a handle of the pass's own, for the pass's read of its fill (graphfill.go); nil reads objects.
reads assigngraph.Objects
// halves is every followed branch's catalog graph revision held now.
halves func() map[string]mcc.Half
// last is the revision last computed, so a pass whose inputs did not change keeps and says nothing.
last meshwants.AssignmentRevision
has bool
// mu guards what the keeping writes and the pass reads: the revision kept, full, and the need handed over (design 47 H-A-259).
mu sync.Mutex
// handedRev is the revision last handed to the keeping, so a pass whose inputs did not change hands nothing; handed is false
// until one is, and again when its keeping failed or found the store full, so the next pass hands it again.
handedRev meshwants.AssignmentRevision
handed bool
// handedOnce says a revision was handed: the first carries the start's removal (H-A-261).
handedOnce bool
// kept is the revision the wants follow, and kept's source the trunk's source revision it carries; ok is false until one is kept.
kept meshwants.AssignmentRevision
source int64
@@ -40,13 +48,55 @@ type graphKeeper struct {
revisions *revisionRemover
// computed is the revision computed by the last pass, with its entries: its edges.
computed assigngraph.Computed
// The keeping off the pass loop (H-A-259): need is what waits to be kept, keeping says one runs; background runs it (nil: at
// once, in the caller), and wake makes a pass once a keeping changed what the pass reads.
need *keepNeed
keeping bool
background func(func())
wake func()
}
// keepGraph computes the revision of this pass and keeps it when the pass's inputs differ from the last computed.
func (p *passer) keepGraph(ctx context.Context) {
// keepNeed is one need of the keeping: a computed revision to keep (nil: none), and whether the revisions not current are judged.
type keepNeed struct {
c *assigngraph.Computed
judge bool
}
// keptNow is the revision the wants follow, with its trunk source, and whether one is kept.
func (g *graphKeeper) keptNow() (meshwants.AssignmentRevision, int64, bool) {
g.mu.Lock()
defer g.mu.Unlock()
return g.kept, g.source, g.ok
}
// isFull says the store did not hold the last revision handed over, so no want is written (design 47 G §181).
func (g *graphKeeper) isFull() bool {
g.mu.Lock()
defer g.mu.Unlock()
return g.full
}
func (g *graphKeeper) setFull(full bool) {
g.mu.Lock()
g.full = full
g.mu.Unlock()
}
// heldNoRevision is the pass's words while no assignment graph revision is kept: it writes no want (design 47 H-A-261).
const heldNoRevision = "held: no assignment graph revision is kept yet, so no want is written until the first keeping ends (H-A-261)"
// heldFull is the pass's words while the next revision does not fit its store (design 47 G §181).
const heldFull = "the assignment graph store is full: no want is written (design 47 G §181)"
// keepGraph computes the revision of this pass, judges the store's fill itself, and hands the revision to the keeping when the
// pass's inputs differ from the last handed. The keeping and the removing of revisions run off the pass loop, one at a time, and the
// pass never waits on them: it judges and writes the wants from the graph it holds (design 47 H-A-259). It answers why the pass
// writes no want, or "" when it writes them: none while the next revision does not fit the store (G §181), and none while no
// revision is kept (H-A-261), whose keeping wakes a pass when it ends.
func (p *passer) keepGraph(ctx context.Context) string {
g := p.graph
if g == nil || g.objects == nil || g.halves == nil {
return
return ""
}
c := assigngraph.Compute(p.graphInputs())
g.computed = c
@@ -56,40 +106,130 @@ func (p *passer) keepGraph(ctx context.Context) {
p.logf("the assignment graph leaves out %s", u)
}
}
if !g.started {
if !g.started { // the first pass judges the fill once (graphfill.go)
g.started = true
p.fillAtStart(ctx)
}
if g.has && g.ok && assigngraph.Same(g.last, c.Revision) {
if p.fullBefore(ctx, c) {
g.mu.Lock()
g.handed = false // handed once it fits
g.mu.Unlock()
return heldFull
}
g.mu.Lock()
same := g.handed && assigngraph.Same(g.handedRev, c.Revision)
first := !g.handedOnce
if !same {
g.handedRev, g.handed, g.handedOnce = c.Revision, true, true
}
g.mu.Unlock()
if !same {
// The start's removal of the revisions not current folds into the first keeping: it keeps the first pass's revision, then
// removes (H-A-261).
p.needKeeping(ctx, keepNeed{c: &c, judge: first})
}
if _, _, ok := g.keptNow(); !ok {
return heldNoRevision
}
return ""
}
// needKeeping hands a need to the keeping: one keeping runs at a time, and a need that comes while one runs is folded into the one
// that waits (the newest revision, and a judging asked by either), so it runs once more (design 47 H-A-259).
func (p *passer) needKeeping(ctx context.Context, n keepNeed) {
g := p.graph
g.mu.Lock()
if w := g.need; w != nil {
n.judge = n.judge || w.judge
if n.c == nil {
n.c = w.c
}
}
g.need = &n
if g.keeping {
g.mu.Unlock()
return
}
g.keeping = true
g.mu.Unlock()
run := func() {
for {
g.mu.Lock()
next := g.need
g.need = nil
if next == nil {
g.keeping = false
g.mu.Unlock()
return
}
g.mu.Unlock()
p.keepOne(ctx, *next)
}
}
if g.background != nil {
g.background(run)
return
}
run()
}
// keepOne keeps one computed revision, says assignment-revision for a revision kept now and removes the
// revisions that ceased to be current; it says its duration in the journal, and wakes a pass when it changed what the pass reads.
func (p *passer) keepOne(ctx context.Context, n keepNeed) {
g := p.graph
start := time.Now()
changed := false
defer func() {
p.logf("the keeping of the assignment graph took %s", time.Since(start).Round(time.Millisecond))
if changed && g.background != nil && g.wake != nil {
g.wake()
}
}()
if n.c != nil {
_, _, had := g.keptNow()
fresh := p.keepRevision(ctx, *n.c)
_, _, has := g.keptNow()
n.judge = n.judge || fresh
changed = fresh || had != has // the first revision kept: the pass writes the wants it held (H-A-261)
}
if n.judge && g.revisions != nil {
g.revisions.judge() // the revision before ceased to be current
}
}
// keepRevision keeps c when the store holds it, and says whether a revision was kept now.
func (p *passer) keepRevision(ctx context.Context, c assigngraph.Computed) bool {
g := p.graph
again := func() { // the next pass hands this revision again
g.mu.Lock()
g.handed = false
g.mu.Unlock()
}
used, _, _ := g.fillOf(ctx)
if p.fullBefore(ctx, c) {
return
}
rev, fresh, err := assigngraph.Keep(ctx, g.objects, c, meshwants.EventAssignmentRevision, p.clock())
if err != nil {
p.logf("the assignment graph revision is not kept, so no want is said as wanted until it is: %v", err)
return
again()
return false
}
g.last, g.has, g.kept, g.ok = c.Revision, true, rev, true
g.source = 0
var source int64
for _, cat := range rev.Catalogs {
if cat.Branch == p.w.trunkName() {
g.source = cat.Source
source = cat.Source
}
}
g.mu.Lock()
g.kept, g.ok, g.source = rev, true, source
g.mu.Unlock()
if !fresh {
return
return false
}
p.fillingAfter(ctx, used)
if g.revisions != nil {
g.revisions.judge() // the revision before ceased to be current
}
id := fmt.Sprintf("%s-%s-%d", meshwants.EventAssignmentRevision, rev.Kind, rev.Revision)
if err := p.wantsSay(meshwants.EventAssignmentRevision, assigngraph.Event(rev), id); err != nil {
p.logf("the assignment revision %d is kept but not said: %v", rev.Revision, err)
}
return true
}
// graphInputs are what the pass's assignment graph is computed from: every followed branch's catalog half, the placements, each
@@ -147,14 +287,20 @@ func (p *passer) sayWanted(node, module, fp, pipeline string, removed bool) {
return
}
g := p.graph
if g == nil || !g.ok {
var kept meshwants.AssignmentRevision
var source int64
ok := false
if g != nil {
kept, source, ok = g.keptNow()
}
if !ok {
p.logf("the want of %s on %s is written, but no assignment graph revision is kept, so wanted is not said", module, node)
return
}
at := p.clock().UTC()
body := meshwants.WantedEvent{V: keys.Version, Node: node, Module: module, Fp: fp, Pipeline: pipeline, Removed: removed, Revision: g.kept.Revision, Source: g.source, At: &at}
body := meshwants.WantedEvent{V: keys.Version, Node: node, Module: module, Fp: fp, Pipeline: pipeline, Removed: removed, Revision: kept.Revision, Source: source, At: &at}
event := strings.TrimPrefix(meshwants.SubjectWanted(keys.EscapeName(node), keys.EscapeName(module)), "mesh.seat."+meshwants.Seat+".event.")
id := fmt.Sprintf("wanted.%s.%s.%s.%t.%d.%s", keys.EscapeName(node), keys.EscapeName(module), fp, removed, g.kept.Revision, at.Format(time.RFC3339Nano))
id := fmt.Sprintf("wanted.%s.%s.%s.%t.%d.%s", keys.EscapeName(node), keys.EscapeName(module), fp, removed, kept.Revision, at.Format(time.RFC3339Nano))
if err := p.wantsSay(event, body, id); err != nil {
p.logf("wanted of %s on %s is not said: %v", module, node, err)
}
@@ -185,7 +331,7 @@ func (p *passer) namedBuild(module, trunkFP string, unreleased ...bool) func(fp
// the mesh-sdk merge moved its fingerprint).
return p.w.released.withParts(module, p.w.ends.madeOf(module, fp))
}
if p.graph == nil || !p.graph.ok {
if _, _, kept := p.graphKept(); !kept {
p.unheardRelease(module, fp, "no assignment graph revision is kept yet, so no release is looked up")
return assign.KeptBuild{}, false
}
@@ -212,3 +358,11 @@ func (p *passer) unheardRelease(module, fp, why string) {
p.logf("the release of %s at fingerprint %s is not heard: %s; its wants and candidates carry no version and no parts", module, fp, why)
}
}
// graphKept is the revision the wants follow, with its trunk source, and whether one is kept; with no graph kept, none is.
func (p *passer) graphKept() (meshwants.AssignmentRevision, int64, bool) {
if p.graph == nil {
return meshwants.AssignmentRevision{}, 0, false
}
return p.graph.keptNow()
}
@@ -3,8 +3,10 @@ package main
import (
"context"
"encoding/json"
"fmt"
"slices"
"strings"
"sync"
"testing"
"time"
@@ -12,7 +14,9 @@ import (
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/buckets"
@@ -132,3 +136,141 @@ func TestTheWantsAreSaidWantedFromTheKeptAssignmentGraphRevision(t *testing.T) {
t.Errorf("dropping the run's candidate dropped trunk: %v", err)
}
}
// blockedObjects is an object bucket whose listing waits while a gate stands: a keeping that does not end until it is opened.
type blockedObjects struct {
memObjects
mu sync.Mutex
gate chan struct{}
}
func (b *blockedObjects) Names(ctx context.Context) ([]string, error) {
b.mu.Lock()
gate := b.gate
b.mu.Unlock()
if gate != nil {
<-gate
}
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Names(ctx)
}
func (b *blockedObjects) Put(ctx context.Context, name string, data []byte) error {
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Put(ctx, name, data)
}
func (b *blockedObjects) Get(ctx context.Context, name string) ([]byte, error) {
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Get(ctx, name)
}
// block stands a gate, opened by the function it answers.
func (b *blockedObjects) block() func() {
gate := make(chan struct{})
b.mu.Lock()
b.gate = gate
b.mu.Unlock()
return func() {
b.mu.Lock()
b.gate = nil
b.mu.Unlock()
close(gate)
}
}
// Design 47 H-A-259, H-A-261: the keeping of the assignment graph runs off the pass loop. At the start, while the first keeping is
// blocked, a pass returns and writes no want; the keeping's end wakes a pass, which writes the passed pipeline's want. Later, while a
// keeping of new inputs is blocked, a pass writes the wants from the revision it holds, and a pass of the same inputs hands nothing
// more. Each pass and each keeping says its duration.
func TestAPassWritesWantsWhileAKeepingIsBlocked(t *testing.T) {
fp := mcc.SourcePrefix2 + strings.Repeat("a", 64)
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, time.Now())
var mu sync.Mutex
var journal strings.Builder
p.logf = func(f string, a ...any) { mu.Lock(); fmt.Fprintf(&journal, f+"\n", a...); mu.Unlock() }
said := func(words string) bool {
mu.Lock()
defer mu.Unlock()
return strings.Contains(journal.String(), words)
}
mdigest := strings.Repeat("e", 64)
mod, _ := mcc.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fp, Manifest: mdigest, Repository: "novox/web", Commit: strings.Repeat("1", 40), Path: mcc.RootPath})
putModuleRaw(p.w, trunkBranch, "web", mod)
p.w.manifests[mdigest] = parsed{module: "web", manifest: catalogue.Manifest{Module: "web"}}
placeOn(t, p.w, "ace", "web")
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk = p.w.trunkName
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "0.1.2", 1, mpr.StepResultOutcomePassed)))
objects := &blockedObjects{memObjects: memObjects{}}
var kept sync.WaitGroup
woke := make(chan struct{}, 8)
half := mcc.Half{Revision: meshcatalog.CatalogRevision{Branch: trunkBranch, Kind: "trunk", Revision: 4, Source: 9,
Entries: []meshcatalog.EntryRef{{Module: "web", Digest: "sha256:" + strings.Repeat("a", 64)}}},
Entries: map[string]meshcatalog.CatalogEntry{"web": {Module: "web", Fp: fp}}}
p.graph = &graphKeeper{objects: objects, halves: func() map[string]mcc.Half { return map[string]mcc.Half{trunkBranch: half} },
background: func(f func()) { kept.Go(f) }, wake: func() { woke <- struct{}{} }}
pass := func() {
t.Helper()
done := make(chan struct{})
go func() { p.pass(context.Background()); close(done) }()
select {
case <-done:
case <-time.After(10 * time.Second):
t.Fatal("the pass waits on the keeping of the assignment graph")
}
}
wantOf := func(node string) (mwc.Want, error) {
key, _ := mwc.WantKey(node, "web")
return mwc.DecodeWant(wantsKV.values[key])
}
open := objects.block()
t.Cleanup(func() { // the keeping ends before the test does, and says its duration
objects.mu.Lock()
standing := objects.gate != nil
objects.mu.Unlock()
if standing {
open()
}
kept.Wait()
if !said("the keeping of the assignment graph took ") {
t.Error("the keeping does not say its duration")
}
})
pass() // the start: the first keeping is blocked
if _, err := wantOf("ace"); err == nil {
t.Error("a pass at the start wrote a want before an assignment graph revision is kept")
}
open()
select {
case <-woke:
case <-time.After(10 * time.Second):
t.Fatal("the first keeping's end wakes no pass")
}
pass()
if w, err := wantOf("ace"); err != nil || w.Fp != fp || w.Version != "0.1.2" {
t.Errorf("the want of web on ace = %+v (%v), want the passed version once a revision is kept", w, err)
}
open = objects.block() // a keeping of new inputs is blocked
placeOn(t, p.w, "g14", "web")
pass()
pass() // the same inputs again
if w, err := wantOf("g14"); err != nil || w.Fp != fp || w.Version != "0.1.2" {
t.Errorf("the want of web on g14 = %+v (%v), want the passed version while a keeping is blocked", w, err)
}
p.graph.mu.Lock()
keeping, waiting := p.graph.keeping, p.graph.need
p.graph.mu.Unlock()
if !keeping || waiting != nil {
t.Errorf("keeping %v, need waiting %+v: the pass of the same inputs handed its revision again", keeping, waiting)
}
if !said("the pass took ") {
t.Error("the pass does not say its duration")
}
}
@@ -12,6 +12,7 @@ import (
"git.novox.be/novox/mesh-sdk/go/keys"
"io"
"maps"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
"mesh-delivery-assigner/internal/puts"
@@ -190,6 +191,11 @@ func startBed(t *testing.T, leaveOut string) *bed {
if _, err := js.CreateObjectStore(ctx, jetstream.ObjectStoreConfig{Bucket: catalogue.BusName("mesh-delivery-assigner", catalogue.StateObjectsName(buckets.InputsState))}); err != nil {
t.Fatal(err)
}
// The assignment graph revisions' object store, which the grants part makes from the manifest's objects: no want is written
// before a revision is kept in it (design 47 H-A-261).
if _, err := js.CreateObjectStore(ctx, jetstream.ObjectStoreConfig{Bucket: catalogue.ObjectsBucket("mesh-delivery-assigner", assigngraph.RevisionsObjects)}); err != nil {
t.Fatal(err)
}
// The builder's module log, as the runtime raises it (ADR 0297): the running commits are read from it (ADR 0571 clause 1).
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: buscompose.LogStreamName(builds.BuilderModule, builds.BuilderLog),
Subjects: []string{buscompose.LogSubject(builds.BuilderModule, builds.BuilderLog) + ".>"}, AllowDirect: true}); err != nil {
@@ -613,7 +613,10 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
p.publishWants = wantsPublisher(ctx, js, thisNode)
if iv != nil && iv.h != nil {
objects := newBusObjects(js, process.Account{Node: thisNode, Module: assignment.Module()}, assigngraph.RevisionsObjects)
p.graph = &graphKeeper{objects: objects, halves: iv.h.views}
// The keeping and removing of revisions runs off the pass loop, and a keeping that changed what the pass reads wakes
// one (design 47 H-A-259).
p.graph = &graphKeeper{objects: objects, halves: iv.h.views, background: func(f func()) { go f() }, wake: wake,
reads: newBusObjects(js, process.Account{Node: thisNode, Module: assignment.Module()}, assigngraph.RevisionsObjects)}
keep := func(ctx context.Context, ev meshcatalog.CatalogRevisionEvent) error {
return p.keepCandidate(ctx, iv.call, ev)
}
@@ -628,7 +631,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
// The revisions that are not current are removed when one ceases to be current and once now (revisions.go,
// design 47 H §764, H-A-86).
p.graph.revisions = &revisionRemover{ctx: ctx, objects: objects, inUse: inUseOf(w), logf: logger.Printf}
p.graph.revisions.judge()
// The start's removal of the revisions not current folds into the first pass's keeping (H-A-261).
}
}
// The node-engine seat's manifest-reads-changed, for one node (design 47 H-A-104): its words are written into the state
@@ -19,6 +19,7 @@ import (
"runtime"
"slices"
"strings"
"sync"
"testing"
"time"
@@ -203,11 +204,17 @@ func (w *watchKV) Keys(context.Context, ...jetstream.WatchOpt) ([]string, error)
return nil, jetstream.ErrNoKeysFound
}
// putIntoMu holds putInto's writes one at a time: the composition step starts its machines' runs side by side, and each may
// raise a finding into the same map.
var putIntoMu sync.Mutex
// putInto is an assign.Findings Put that keeps each finding in into, as the finding writer would, by its key and its words.
func putInto(into map[string][]byte) func(mcseat.Finding) error {
return func(f mcseat.Finding) error {
raw, err := json.Marshal(f)
putIntoMu.Lock()
into[views.FindingKey(f.Scope, f.ID, f.Kind)] = raw
putIntoMu.Unlock()
return err
}
}
@@ -88,6 +88,43 @@ func (b *busObjects) Names(ctx context.Context) ([]string, error) {
return names, nil
}
// PutDescribed stores data under name with the entry's module and fingerprint in its metadata, which the listing says (assigngraph.Describer,
// design 47 H-A-259).
func (b *busObjects) PutDescribed(ctx context.Context, name string, data []byte, module, fp string) error {
o, err := b.open(ctx)
if err != nil {
return err
}
_, err = o.Put(ctx, jetstream.ObjectMeta{Name: name, Metadata: map[string]string{entryModuleMeta: module, entryFpMeta: fp}}, bytes.NewReader(data))
return err
}
// Described is every object with the module and fingerprint its metadata says, in one listing.
func (b *busObjects) Described(ctx context.Context) ([]assigngraph.Described, error) {
o, err := b.open(ctx)
if err != nil {
return nil, err
}
infos, err := o.List(ctx)
if errors.Is(err, jetstream.ErrNoObjectsFound) {
return []assigngraph.Described{}, nil
}
if err != nil {
return nil, err
}
out := make([]assigngraph.Described, 0, len(infos))
for _, i := range infos {
out = append(out, assigngraph.Described{Name: i.Name, Module: i.Metadata[entryModuleMeta], Fp: i.Metadata[entryFpMeta]})
}
return out, nil
}
// The metadata keys of an entry object's module and fingerprint.
const (
entryModuleMeta = "module"
entryFpMeta = "fp"
)
// Delete removes the object of that name; one not held is no error (design 47 G §579: a revision nothing pins is removed).
func (b *busObjects) Delete(ctx context.Context, name string) error {
o, err := b.open(ctx)
@@ -141,13 +141,14 @@ func (p *passer) clock() time.Time {
}
func (p *passer) pass(ctx context.Context) {
start := time.Now()
defer func() { p.logf("the pass took %s", time.Since(start).Round(time.Millisecond)) }() // design 47 H-A-259
p.assignmentsSeat(ctx)
p.keepGraph(ctx)
if p.graph == nil || !p.graph.full { // a full assignment graph store keeps the last revision and writes no new want (design 47 G §181)
if held := p.keepGraph(ctx); held == "" {
p.wants(ctx)
p.sayPass(ctx, "judged")
} else {
p.sayPass(ctx, "the assignment graph store is full: no want is written (design 47 G §181)")
p.sayPass(ctx, held) // a full store keeps the last revision (design 47 G §181); none kept yet writes no want (H-A-261)
}
p.puts(ctx)
p.nodeWants(ctx)
@@ -169,7 +169,7 @@ func (e *pipelineEnds) take(p mpr.PipelineEnded) (bool, error) {
changed := false
var kept []tierMover
defer func() {
if err := e.startTiers(p.Pipeline, kept); err != nil {
if err := e.startTiers(p.Pipeline, p.Source, kept); err != nil {
e.logf("the tier progress of %s is not written: %v", p.Pipeline, err)
}
}()
@@ -2,6 +2,7 @@ package main
import (
"context"
"encoding/json"
"fmt"
"slices"
"strconv"
@@ -53,7 +54,7 @@ func trunkRevision(name string) (int64, bool) {
// remove removes each kept revision that is not current, and then the entries no kept revision or candidate lists and no want or
// running build names (design 47 G §179).
func (k *revisionRemover) remove() error {
names, err := k.objects.Names(k.ctx)
names, described, err := k.listing()
if err != nil {
return err
}
@@ -107,7 +108,7 @@ func (k *revisionRemover) remove() error {
if !ok || listed[digest] {
continue
}
e, err := assigngraph.ReadEntry(k.ctx, k.objects, digest)
e, err := k.entryOf(n, digest, described)
if err != nil {
return err
}
@@ -138,3 +139,46 @@ func inUseOf(w *world) func(module, fp string) bool {
return false
}
}
// listing is every object's name in one read and, where the bucket says them, each entry object's module and fingerprint by name
// (design 47 H-A-259); nil described where the bucket says none.
func (k *revisionRemover) listing() ([]string, map[string]assigngraph.Described, error) {
d, ok := k.objects.(assigngraph.Describer)
if !ok {
names, err := k.objects.Names(k.ctx)
return names, nil, err
}
listed, err := d.Described(k.ctx)
if err != nil {
return nil, nil, err
}
names := make([]string, 0, len(listed))
described := make(map[string]assigngraph.Described, len(listed))
for _, l := range listed {
names = append(names, l.Name)
described[l.Name] = l
}
return names, described, nil
}
// entryOf is the module and fingerprint of the entry object name: as the listing says them, with no read; an entry put before the
// listing said them is read once and put again with them, so no later judging reads it (design 47 H-A-259).
func (k *revisionRemover) entryOf(name, digest string, described map[string]assigngraph.Described) (meshwants.AssignmentEntry, error) {
if l, ok := described[name]; ok && l.Module != "" && l.Fp != "" {
return meshwants.AssignmentEntry{Module: l.Module, Fp: l.Fp}, nil
}
data, err := k.objects.Get(k.ctx, name)
if err != nil {
return meshwants.AssignmentEntry{}, fmt.Errorf("the entry %s: %w", digest, err)
}
var e meshwants.AssignmentEntry
if err := json.Unmarshal(data, &e); err != nil {
return e, fmt.Errorf("the entry %s: %w", digest, err)
}
if described != nil {
if err := assigngraph.PutEntry(k.ctx, k.objects, name, data, e); err != nil {
k.logf("the entry %s is not put again with its module and fingerprint, so the next judging reads it again: %v", digest, err)
}
}
return e, nil
}
@@ -3,6 +3,7 @@ package main
import (
"context"
"encoding/json"
"strings"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
@@ -12,42 +13,98 @@ import (
func (m memObjects) Delete(_ context.Context, name string) error { delete(m, name); return nil }
// describedObjects is memObjects whose listing says each entry's module and fingerprint (assigngraph.Describer), counting the
// entry objects read.
type describedObjects struct {
memObjects
meta map[string][2]string
reads int
}
func (d *describedObjects) Get(ctx context.Context, name string) ([]byte, error) {
if strings.HasPrefix(name, "entry.") {
d.reads++
}
return d.memObjects.Get(ctx, name)
}
func (d *describedObjects) PutDescribed(_ context.Context, name string, data []byte, module, fp string) error {
d.memObjects[name], d.meta[name] = data, [2]string{module, fp}
return nil
}
func (d *describedObjects) Described(context.Context) ([]assigngraph.Described, error) {
var out []assigngraph.Described
for n := range d.memObjects {
out = append(out, assigngraph.Described{Name: n, Module: d.meta[n][0], Fp: d.meta[n][1]})
}
return out, nil
}
// Design 47 H §764, H-A-86: with the gate's pins gone, an assignment graph revision that is not current is removed, with the
// entries no kept revision or candidate lists and no want or running build names; the current revision, the entries it lists,
// a running build's entry and a run's kept candidate with its entries stay.
// H-A-259: where the listing says each entry's module and fingerprint, the judging reads no entry object; an entry put before it
// said them is read once and put again with them.
func TestARevisionNotCurrentIsRemoved(t *testing.T) {
objects := memObjects{}
entry := func(module, fp string) string {
e := meshwants.AssignmentEntry{Node: "n1", Module: module, Fp: fp}
d := assigngraph.EntryDigest(e)
raw, _ := json.Marshal(e)
objects[assigngraph.EntryObject(d)] = raw
return d
}
shared, old, running, cand := entry("a", "fp-a"), entry("b", "fp-b1"), entry("c", "fp-c1"), entry("d", "fp-d2")
revision := func(n int64, digests ...string) {
rev := meshwants.AssignmentRevision{Revision: n}
for _, d := range digests {
rev.Entries = append(rev.Entries, meshwants.NodeEntryRef{Node: "n1", Digest: d})
for _, listed := range []string{"plain", "described", "described-later"} {
objects := memObjects{}
described := &describedObjects{memObjects: objects, meta: map[string][2]string{}}
entry := func(module, fp string) string {
e := meshwants.AssignmentEntry{Node: "n1", Module: module, Fp: fp}
d := assigngraph.EntryDigest(e)
raw, _ := json.Marshal(e)
objects[assigngraph.EntryObject(d)] = raw
if listed == "described" {
described.meta[assigngraph.EntryObject(d)] = [2]string{module, fp}
}
return d
}
raw, _ := json.Marshal(rev)
objects[assigngraph.TrunkObject(n)] = raw
}
candRaw, _ := json.Marshal(meshwants.AssignmentRevision{Revision: 1, Kind: "candidate", Group: "run-7", Heads: "h1",
Entries: []meshwants.NodeEntryRef{{Node: "n1", Module: "d", Digest: cand}}})
objects[assigngraph.CandidateObject("run-7", "h1")] = candRaw
revision(1, shared, old, running)
revision(2, shared, old)
revision(3, shared)
k := &revisionRemover{ctx: context.Background(), objects: objects, logf: t.Logf,
inUse: func(module, fp string) bool { return module == "c" && fp == "fp-c1" }}
k.judge()
has := func(name string) bool { _, ok := objects[name]; return ok }
for name, want := range map[string]bool{assigngraph.TrunkObject(1): false, assigngraph.TrunkObject(2): false, assigngraph.TrunkObject(3): true,
assigngraph.EntryObject(old): false, assigngraph.EntryObject(running): true, assigngraph.EntryObject(shared): true,
assigngraph.EntryObject(cand): true, assigngraph.CandidateObject("run-7", "h1"): true} {
if has(name) != want {
t.Errorf("%s kept = %v, want %v", name, has(name), want)
shared, old, running, cand := entry("a", "fp-a"), entry("b", "fp-b1"), entry("c", "fp-c1"), entry("d", "fp-d2")
revision := func(n int64, digests ...string) {
rev := meshwants.AssignmentRevision{Revision: n}
for _, d := range digests {
rev.Entries = append(rev.Entries, meshwants.NodeEntryRef{Node: "n1", Digest: d})
}
raw, _ := json.Marshal(rev)
objects[assigngraph.TrunkObject(n)] = raw
}
candRaw, _ := json.Marshal(meshwants.AssignmentRevision{Revision: 1, Kind: "candidate", Group: "run-7", Heads: "h1",
Entries: []meshwants.NodeEntryRef{{Node: "n1", Module: "d", Digest: cand}}})
objects[assigngraph.CandidateObject("run-7", "h1")] = candRaw
revision(1, shared, old, running)
revision(2, shared, old)
revision(3, shared)
var o revisionObjects = objects
if listed != "plain" {
o = described
}
k := &revisionRemover{ctx: context.Background(), objects: o, logf: t.Logf,
inUse: func(module, fp string) bool { return module == "c" && fp == "fp-c1" }}
k.judge()
has := func(name string) bool { _, ok := objects[name]; return ok }
for name, want := range map[string]bool{assigngraph.TrunkObject(1): false, assigngraph.TrunkObject(2): false, assigngraph.TrunkObject(3): true,
assigngraph.EntryObject(old): false, assigngraph.EntryObject(running): true, assigngraph.EntryObject(shared): true,
assigngraph.EntryObject(cand): true, assigngraph.CandidateObject("run-7", "h1"): true} {
if has(name) != want {
t.Errorf("%s: %s kept = %v, want %v", listed, name, has(name), want)
}
}
switch listed {
case "described":
if described.reads != 0 {
t.Errorf("described: the judging read %d entry objects, want none", described.reads)
}
case "described-later":
if described.meta[assigngraph.EntryObject(running)] != [2]string{"c", "fp-c1"} {
t.Errorf("described-later: the entry in use is not put again with its module and fingerprint: %v", described.meta)
}
reads := described.reads
revision(4, shared)
k.judge()
if described.reads != reads {
t.Errorf("described-later: a second judging read %d entry objects again", described.reads-reads)
}
}
}
}
@@ -42,11 +42,14 @@ type tierMover struct {
Tier int64 `json:"tier"`
}
// tierProgress is a pipeline's tier progress (H-A-56): the tier whose wants are written, since when, and the movers.
// tierProgress is a pipeline's tier progress (H-A-56): the tier whose wants are written, since when, the movers, and the source
// revision its pipeline-ended names, said in pipeline-wanted beside the key's revision (design 47 H-A-214, H-A-216); zero in a
// value kept before the field, read as the key's number.
type tierProgress struct {
Tier int64 `json:"tier"`
Since time.Time `json:"since"`
Movers []tierMover `json:"movers"`
Source int64 `json:"source,omitempty"`
}
// tierKey is the key of pipeline's tier progress; pipeline is the runner's key `<branch>.<source>`, its branch escaped.
@@ -60,7 +63,7 @@ func isTierKey(key string) bool {
// startTiers writes the tier progress of a passed pipeline whose movers' versions are now kept, its first tier the lowest of
// theirs, since now. A pipeline heard again writes nothing.
func (e *pipelineEnds) startTiers(pipeline string, movers []tierMover) error {
func (e *pipelineEnds) startTiers(pipeline string, source int64, movers []tierMover) error {
if len(movers) == 0 {
return nil
}
@@ -68,7 +71,7 @@ func (e *pipelineEnds) startTiers(pipeline string, movers []tierMover) error {
for _, m := range movers {
first = min(first, m.Tier)
}
value, err := json.Marshal(tierProgress{Tier: first, Since: e.clock().UTC(), Movers: movers})
value, err := json.Marshal(tierProgress{Tier: first, Since: e.clock().UTC(), Movers: movers, Source: source})
if err != nil {
return err
}
@@ -131,7 +134,7 @@ func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []st
continue
}
pipeline := strings.TrimPrefix(key, tierPrefix)
branchEsc, source, _ := strings.Cut(pipeline, ".")
branchEsc, number, _ := strings.Cut(pipeline, ".")
branch, err := keys.UnescapeName(branchEsc)
if err != nil {
continue
@@ -144,7 +147,7 @@ func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []st
notRunning := p.notRunning(n, placedOn, pipeline, branch, t, t.Tier)
late := !now.Before(t.Since.Add(bound))
if late {
p.tierLate(pipeline, branch, source, t, notRunning)
p.tierLate(pipeline, branch, number, t, notRunning)
break
}
if len(notRunning) > 0 {
@@ -165,10 +168,10 @@ func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []st
p.logf("the tier progress %s is not deleted: %v", key, err)
break
}
p.sayPipelineWanted(pipeline, branch, source, meshwants.PipelineWantedOutcomeRunning, nil)
p.sayPipelineWanted(pipeline, branch, number, t.Source, meshwants.PipelineWantedOutcomeRunning, nil)
break
}
value, err := json.Marshal(tierProgress{Tier: later, Since: now, Movers: t.Movers})
value, err := json.Marshal(tierProgress{Tier: later, Since: now, Movers: t.Movers, Source: t.Source})
if err == nil {
err = p.ends.st.swap(key, value, rev)
}
@@ -217,7 +220,7 @@ func (p *passer) notRunning(n assign.Nodes, placedOn func(module, branch string)
// tierLate ends a pipeline's delivery at a tier past tier-bound: the finding tier-late is raised and pipeline-wanted says tier-late,
// once each; the finding clears once the late movers run or a later pipeline moved them. The progress stays, so no later tier is
// written, until no later tier's mover is kept at this pipeline any more.
func (p *passer) tierLate(pipeline, branch, source string, t tierProgress, notRunning []meshwants.NotRunning) {
func (p *passer) tierLate(pipeline, branch, number string, t tierProgress, notRunning []meshwants.NotRunning) {
o := tierLateFinding(pipeline, t.Tier, notRunning)
key := views.FindingKey(o.Scope, assign.KeyID(o.ID), o.Kind)
if len(notRunning) > 0 {
@@ -231,7 +234,7 @@ func (p *passer) tierLate(pipeline, branch, source string, t tierProgress, notRu
p.said[key+".raised"] = true
delete(p.said, key+".cleared")
p.logf("pipeline %s: tier %d is late (tier-bound %s): %s; no later tier is written", pipeline, t.Tier, p.tierBoundOf(), o.Summary)
p.sayPipelineWanted(pipeline, branch, source, meshwants.PipelineWantedOutcomeTierLate, notRunning)
p.sayPipelineWanted(pipeline, branch, number, t.Source, meshwants.PipelineWantedOutcomeTierLate, notRunning)
}
} else if !p.said[key+".cleared"] {
if p.findings.Delete != nil {
@@ -271,11 +274,16 @@ func tierLateFinding(pipeline string, tier int64, notRunning []meshwants.NotRunn
Source: "assigner." + kindTierLate}
}
// sayPipelineWanted says the seat mesh-wants' pipeline-wanted of pipeline, once (its id the pipeline and the outcome).
func (p *passer) sayPipelineWanted(pipeline, branch, source, outcome string, notRunning []meshwants.NotRunning) {
var src int64
_, _ = fmt.Sscan(source, &src)
body := meshwants.PipelineWantedEvent{V: keys.Version, Pipeline: pipeline, Branch: branch, Source: src, Outcome: outcome, NotRunning: notRunning}
// sayPipelineWanted says the seat mesh-wants' pipeline-wanted of pipeline, once (its id the pipeline and the outcome): its
// revision the number of the pipeline's key `<branch>.<revision>`, its source the one the pipeline-ended named (design 47
// H-A-214, H-A-216), the key's number for a progress kept before it held one.
func (p *passer) sayPipelineWanted(pipeline, branch, number string, source int64, outcome string, notRunning []meshwants.NotRunning) {
var revision int64
_, _ = fmt.Sscan(number, &revision)
if source <= 0 {
source = revision
}
body := meshwants.PipelineWantedEvent{V: keys.Version, Pipeline: pipeline, Branch: branch, Source: source, Revision: revision, Outcome: outcome, NotRunning: notRunning}
event := meshwants.EventPipelineWanted + "." + pipeline
if err := p.wantsSay(event, body, "pipeline-wanted."+pipeline+"."+outcome); err != nil {
p.logf("pipeline-wanted of %s is not said: %v", pipeline, err)
@@ -62,8 +62,11 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
p.w.mu.Unlock()
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk, p.ends.now = p.w.trunkName, func() time.Time { return now }
if _, err := p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("db", db, "0.2.0", 1, mpr.StepResultOutcomePassed),
mover("web", web, "0.1.2", 2, mpr.StepResultOutcomePassed))); err != nil {
// The pipeline of revision 5 (its key's number) of source 4: a re-pin's revision (H-A-213, H-A-216).
e := ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("db", db, "0.2.0", 1, mpr.StepResultOutcomePassed),
mover("web", web, "0.1.2", 2, mpr.StepResultOutcomePassed))
e.Source = 4
if _, err := p.ends.take(e); err != nil {
t.Fatal(err)
}
wanted := func(node, module string) bool {
@@ -88,7 +91,7 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
raw, _ = json.Marshal(nodeengine.Running{Node: "g14", Module: "web", Fingerprint: web})
_ = p.w.hearRunning("running.g14.web", raw)
p.wants(context.Background())
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeRunning || len(findings) != 0 {
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeRunning || said[0].Revision != 5 || said[0].Source != 4 || len(findings) != 0 {
t.Errorf("every tier runs: said %+v, findings %v", said, findings)
}
if _, _, ok := p.ends.tiersOf(trunkBranch + ".5"); ok {
@@ -108,8 +111,14 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
if !ok || !strings.Contains(f.Summary, "db on g14") || strings.Contains(f.Summary, "ace") {
t.Errorf("tier-late is not raised naming db on g14 alone: %v", findings)
}
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeTierLate || len(said[0].NotRunning) != 1 || said[0].NotRunning[0].Module != "db" {
t.Errorf("pipeline-wanted tier-late is not said once: %+v", said)
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeTierLate || len(said[0].NotRunning) != 1 || said[0].NotRunning[0].Module != "db" ||
said[0].Revision != 5 || said[0].Source != 4 {
t.Errorf("pipeline-wanted tier-late is not said once, naming revision 5 of source 4: %+v", said)
}
// A tier progress kept before it held its source says the key's number as both (H-A-216).
p.sayPipelineWanted(trunkBranch+".5", trunkBranch, "5", 0, meshwants.PipelineWantedOutcomeRunning, nil)
if len(said) != 2 || said[1].Revision != 5 || said[1].Source != 5 {
t.Errorf("a progress with no source: said %+v, want revision and source 5", said)
}
if wanted("g14", "web") || wanted("ace", "web") {
t.Error("a consumer's want is written after its provider's tier was late")
@@ -345,7 +345,8 @@ func (r *compositionRun) startValidate(ctx context.Context, key string, run mesh
return
}
a := buildstep.StepAsk{ID: ask, Kind: buildstep.AskCheck, Language: buildstep.AskGo, Asker: runAsker, At: r.now().UTC(),
Run: &buildstep.RunJob{Program: program, Heads: []buildstep.RunHead{}, Input: ref, Reader: "the manifest validator of " + step.Pipeline + " at " + program.Commit}}
Run: &buildstep.RunJob{Program: program, Heads: []buildstep.RunHead{}, Input: ref, Reader: "the manifest validator of " + step.Pipeline + " at " + program.Commit},
Packages: pinsOfEntry(entry)} // the validator is built against its entry's pins at the step's revision (H-A-203, H-A-192, H-A-205)
if err := r.put(ctx, a); err != nil {
couldNot("its run ask " + ask + " is not put: " + err.Error())
}
@@ -25,7 +25,8 @@ import (
// is judged against an empty case before, said in its end, and no revision below it is asked.
func TestTheValidateStepRefusesAManifestProblemAndACycle(t *testing.T) {
indexer := meshcatalog.CatalogEntry{Module: "indexer", Repository: "novox/mesh-delivery", Commit: commitE3, Path: "modules/mesh-delivery-indexer",
Fp: "src2:ix", Serves: []string{"seat:" + meshcatalog.Seat + ".revision"}, Manifest: map[string]any{"module": "indexer"}, ManifestDigest: "d-ix"}
Fp: "src2:ix", Serves: []string{"seat:" + meshcatalog.Seat + ".revision"}, Manifest: map[string]any{"module": "indexer"}, ManifestDigest: "d-ix",
Packages: map[string]string{"git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient": "v0.1.4"}}
entry := func(module, digest string, edges ...meshcatalog.Edge) meshcatalog.CatalogEntry {
return meshcatalog.CatalogEntry{Module: module, Manifest: map[string]any{"module": module, "d": digest}, ManifestDigest: digest, Edges: edges}
}
@@ -124,6 +125,10 @@ func TestTheValidateStepRefusesAManifestProblemAndACycle(t *testing.T) {
if p := asks[0].Run.Program; p.Commit != commitE3 || p.Dir != "modules/mesh-delivery-indexer" || p.Package != validatorPackage || len(asks[0].Run.Heads) != 0 {
t.Errorf("the validator is built from %+v", asks[0].Run)
}
// The validator is built against the indexer entry's pins at the step's revision (H-A-203, H-A-192, H-A-205).
if got := asks[0].Packages; len(got) != 1 || got["git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"] != "v0.1.4" {
t.Errorf("the validator is built against the pins %v; want its entry's", got)
}
if c := requests[0].Cases; len(c) != 2 || c[0].Name != changeCase || c[1].Name != beforeCase || len(c[1].Manifests) != 3 || requests[0].Predefined != nil || requests[0].Packages != nil {
t.Errorf("the validator's request is %+v", requests[0])
}
@@ -30,6 +30,29 @@ type Objects interface {
Names(ctx context.Context) ([]string, error)
}
// Described is one object as the bucket's listing says it: its name, and for an entry object the module and fingerprint put beside
// its bytes (empty for one put before them).
type Described struct {
Name, Module, Fp string
}
// Describer is an object bucket whose listing says, in one read, each entry object's module and fingerprint, so the removal of the
// revisions not current reads no object per entry (design 47 H-A-259).
type Describer interface {
// PutDescribed stores data whole under name, with module and fp beside it in the listing.
PutDescribed(ctx context.Context, name string, data []byte, module, fp string) error
// Described is every object, as the listing says it.
Described(ctx context.Context) ([]Described, error)
}
// PutEntry stores the entry object e under name, with its module and fingerprint beside it where the bucket says them.
func PutEntry(ctx context.Context, o Objects, name string, data []byte, e meshwants.AssignmentEntry) error {
if d, ok := o.(Describer); ok {
return d.PutDescribed(ctx, name, data, e.Module, e.Fp)
}
return o.Put(ctx, name, data)
}
// EntryObject is the object name of the entry of that digest (the seat's key form entry.<digest>).
func EntryObject(digest string) string { return "entry." + digest }
@@ -144,7 +167,7 @@ func writeEntries(ctx context.Context, o Objects, c Computed, rev meshwants.Assi
if err != nil {
return err
}
if err := o.Put(ctx, name, data); err != nil {
if err := PutEntry(ctx, o, name, data, e); err != nil {
return fmt.Errorf("the entry of %s/%s in %s: %w", ref.Node, ref.Module, RevisionsObjects, err)
}
held[name] = true
@@ -119,6 +119,13 @@ func TestManifest(t *testing.T) {
}
}
}
// H-A-186 (design 47 G §370): asks, which the gate, the teller and the view import, is a declared Go package of the
// module, so every release publishes it; H-A-188: in the module's version series, 0.3.
if !slices.ContainsFunc(m.Build.Artifacts, func(a catalogue.Artifact) bool {
return a.Name == "asks" && a.Kind == catalogue.ArtifactPackage && a.Language == "go" && slices.Equal(a.Paths, []string{"asks"}) && a.Series == m.Version && m.Version == "0.3"
}) {
t.Errorf("artifacts = %+v, want the Go package asks of series 0.3, the module's", m.Build.Artifacts)
}
// ADR 0635 §5: its views family is its ordinary events, `views.<state>` among its emits, on no stream of its own.
// The seat's four events are said on the seat's own subject (the seat's family), so the module keeps no stream for them
// and lists none among its emits.
@@ -370,6 +370,15 @@
"loads": [
"mesh-delivery-assigner"
]
},
{
"name": "asks",
"kind": "package",
"language": "go",
"paths": [
"asks"
],
"series": "0.3"
}
]
}
@@ -242,6 +242,11 @@ type BuilderBuild struct {
// Imports are, on a done key, the mesh packages the built programs import, as the build module answered them
// (BuildAnswer.Imports; novox/hq ADR 0593 §2): the builder carries them onto the build's end (BuildLogEntry.Imports).
Imports []string `json:"imports,omitempty"`
// Packages are, on a done key only, the mesh packages' versions its Go build was built with, by module path, the ones
// the registry gave a package the entry named with none included (H-A-207): the build step's end reports them, so the
// runner asks the steps that waited for the pins with what the build was built against. A reader that does not know
// the field reads the build as reporting none.
Packages map[string]string `json:"packages,omitempty"`
// Needs are, on a done key only, the reader capabilities (`form:<name>`) the build's reference forms need of a
// node-engine, beside the ones its manifest needs (novox/hq ADR 0618 §1). A reader that does not know the field
// reads the build as needing none.
@@ -14,7 +14,8 @@ import (
"mesh-delivery-builder/internal/versions"
)
// readerOf is a kept state as the versions package's reader.
// readerOf is a kept state as the versions package's reader: its values read in one page, one request for many (design 47 H
// H-A-290 (5), H-A-292), where a key-by-key read of a queue of two thousand keys outlasts the tool's call.
func readerOf(s stdio.KeptState) versions.Reader {
return versions.Reader{Keys: s.Keys, Get: func(key string) (json.RawMessage, bool, error) {
e, err := s.Get(key)
@@ -22,7 +23,34 @@ func readerOf(s stdio.KeptState) versions.Reader {
return nil, false, err
}
return e.Value, true, nil
}}
}, All: func() (versions.StatePage, error) { return onePage(s.Page, s.Info) }}
}
// statePageBytes and statePageBudget bound the one page of a state read, so its answer fits one bus message and its time.
const (
statePageBytes = 768 * 1024
statePageBudget = 10 * time.Second
)
// onePage is the first page of a state's values, and never a second (H-A-292, H-A-293): when the state holds more, the page says
// so with the state's size from its info. A runtime that answers no page says errors.ErrUnsupported.
func onePage(page func(after string, maxBytes int, budget time.Duration) (stdio.StatePage, error), info func() (*stdio.StateInfo, error)) (versions.StatePage, error) {
pg, err := page("", statePageBytes, statePageBudget)
if err != nil {
return versions.StatePage{}, err
}
out := versions.StatePage{Values: make(map[string]json.RawMessage, len(pg.Entries)), More: pg.Next != ""}
for _, e := range pg.Entries {
out.Values[e.Key] = e.Value
}
if out.More {
if in, err := info(); err != nil || in == nil {
out.InfoWords = fmt.Sprintf("the state's info cannot be read: %v", err)
} else {
out.Keys, out.Bytes = in.Keys, in.Bytes
}
}
return out, nil
}
// republishTools are builder_publish_again and builder_publish_queue (design 47 G §588). The publish again is a hand act:
@@ -59,7 +87,11 @@ func republishTools(queue, acted, reasks versions.Reader, ask queueAsker, now fu
return map[string]any{"key": key, "queued": a.Queued, "answer": a.Answer}, nil
}},
{Name: versions.PublishQueueTool, Description: versions.PublishQueueDescription,
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) { return versions.AnswerQueue(queue, acted, reasks) }},
Input: map[string]any{"type": "object", "properties": map[string]any{
"module": map[string]any{"type": "string", "description": "list only this module's queued versions, each with its class"},
"version": map[string]any{"type": "string", "description": "with module: only this version, MAJOR.MINOR.PATCH"}}},
Run: func(args map[string]any) (any, error) {
return versions.AnswerQueue(queue, acted, reasks, str(args, "module"), str(args, "version"))
}},
}
}
@@ -0,0 +1,44 @@
package main
import (
"encoding/json"
"errors"
"testing"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// TestAStateIsReadInOnePage: design 47 H H-A-292, H-A-293 — builder_publish_queue reads each of its own states in one page and
// never asks a second: a state past the page answers that page with More and the state's size from its info; one the page holds
// answers whole without reading the info.
func TestAStateIsReadInOnePage(t *testing.T) {
for _, c := range []struct {
name string
next string
}{{"past one page", "k1"}, {"held by one page", ""}} {
t.Run(c.name, func(t *testing.T) {
var asked []string
infos := 0
page := func(after string, maxBytes int, budget time.Duration) (stdio.StatePage, error) {
asked = append(asked, after)
if after != "" {
return stdio.StatePage{Entries: []stdio.StateEntry{{Key: "k2", Value: json.RawMessage(`2`)}}}, nil
}
return stdio.StatePage{Entries: []stdio.StateEntry{{Key: "k1", Value: json.RawMessage(`1`)}}, Next: c.next}, nil
}
info := func() (*stdio.StateInfo, error) { infos++; return &stdio.StateInfo{Keys: 2, Bytes: 640}, nil }
pg, err := onePage(page, info)
more := c.next != ""
if err != nil || len(asked) != 1 || len(pg.Values) != 1 || pg.More != more || (more && (pg.Keys != 2 || pg.Bytes != 640 || infos != 1)) || (!more && infos != 0) {
t.Errorf("asked the pages after %q, read %v, more %v, size %d keys %d bytes, info read %d times (%v): want one page only, its rest said with the state's size", asked, pg.Values, pg.More, pg.Keys, pg.Bytes, infos, err)
}
})
}
unsupported := func(string, int, time.Duration) (stdio.StatePage, error) {
return stdio.StatePage{}, errors.ErrUnsupported
}
if _, err := onePage(unsupported, nil); !errors.Is(err, errors.ErrUnsupported) {
t.Errorf("a runtime with no pages answered %v, want ErrUnsupported so the reader reads key by key", err)
}
}
@@ -45,7 +45,7 @@ func (m *entryManifests) keep(e meshcatalog.CatalogEntry) error {
if m.byFp == nil {
m.byFp = map[string]catalogue.Manifest{}
}
m.byFp[meshcatalog.BareManifestDigest(e.ManifestDigest)] = mf
m.byFp[meshcatalogclient.BareManifestDigest(e.ManifestDigest)] = mf
return nil
}
@@ -101,9 +101,7 @@ func (c *catalogHalf) Changed(ctx context.Context) func(branch, module string, e
}
origin := build.Origin{Branch: branch, First: first}
if cat, ok := c.branches.Catalog(branch); ok {
if half, ok := cat.View(); ok {
origin.Source = half.Revision.Source
}
origin = pictureOrigin(origin, cat.View)
}
var e meshcatalog.CatalogEntry
if err := json.Unmarshal(entry, &e); err != nil || e.Module != module {
@@ -132,6 +130,16 @@ func (c *catalogHalf) Changed(ctx context.Context) func(branch, module string, e
}
}
// pictureOrigin is the origin of an entry the picture takes in: the source revision and the catalog revision number of the
// half the view holds, one revision for both (design 47 G §371, H-A-218, H-A-220), so a build the picture starts before any
// step ask reserves a version that names its revision; none while the view holds no half.
func pictureOrigin(o build.Origin, view func() (meshcatalogclient.Half, bool)) build.Origin {
if half, ok := view(); ok {
o.Source, o.Revision = half.Revision.Source, half.Revision.Revision
}
return o
}
// picture is build.Builder.Picture: the source revision the view of branch holds (design 47 H H-A-155), false while the branch
// is not followed or its view holds none.
func (c *catalogHalf) picture(branch string) (int64, bool) {
@@ -4,7 +4,9 @@ import (
"context"
"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"
"mesh-delivery-builder/internal/build"
)
// TestTheManifestOfAnEntryIsReadByItsDigest: the builder reads a manifest from the entry that holds it, by the entry's manifest
@@ -25,3 +27,18 @@ func TestTheManifestOfAnEntryIsReadByItsDigest(t *testing.T) {
t.Errorf("an entry with no manifest kept one: %v, %v", err, m.byFp)
}
}
// H-A-220: an entry the picture takes in has the source revision and the catalog revision number of the half its view holds,
// one revision for both; a view holding no half names neither.
func TestAnEntryThePictureTakesInNamesItsHalfsRevision(t *testing.T) {
o := build.Origin{Branch: "main", First: true}
got := pictureOrigin(o, func() (meshcatalogclient.Half, bool) {
return meshcatalogclient.Half{Revision: meshcatalog.CatalogRevision{Revision: 47, Source: 45}}, true
})
if got != (build.Origin{Branch: "main", First: true, Source: 45, Revision: 47}) {
t.Errorf("origin = %+v, want source 45 at revision 47", got)
}
if got := pictureOrigin(o, func() (meshcatalogclient.Half, bool) { return meshcatalogclient.Half{}, false }); got != o {
t.Errorf("origin with no half = %+v, want %+v", got, o)
}
}
@@ -0,0 +1,47 @@
package main
import (
"context"
"encoding/json"
"fmt"
"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-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// keptRevisionVia reads one kept revision of a branch by its number through the catalog seat's verb revision, page by page
// (design 47 H H-A-205, H-A-147): the source revision it was taken in from and the fingerprint of each module it names.
func keptRevisionVia(call toolCaller) func(context.Context, string, int64) (int64, map[string]string, error) {
return func(_ context.Context, branch string, revision int64) (int64, map[string]string, error) {
fps := map[string]string{}
var source int64
after := ""
for {
raw, err := call(meshcatalogclient.RevisionVerb, meshcatalog.RevisionInput{Branch: keys.EscapeName(branch), Revision: revision, After: after})
if err != nil {
return 0, nil, err
}
answer, said, ok := buscalls.Unwrap(raw)
if !ok {
return 0, nil, fmt.Errorf("%s answered: %s", meshcatalogclient.RevisionVerb, said)
}
var a meshcatalog.RevisionAnswer
if err := json.Unmarshal(answer, &a); err != nil {
return 0, nil, fmt.Errorf("%s answered no revision: %w", meshcatalogclient.RevisionVerb, err)
}
if a.NoneYet || a.Revision == nil || a.Revision.Revision != revision {
return 0, nil, fmt.Errorf("%s answered no revision %d of %s", meshcatalogclient.RevisionVerb, revision, branch)
}
source = a.Revision.Source
for _, e := range a.Entries {
fps[e.Module] = e.Fp
}
if a.Next == "" {
return source, fps, nil
}
after = a.Next
}
}
}
@@ -228,6 +228,8 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
return err
}
b.PackageWait = time.Duration(packageWait) * time.Minute
// Before it waits for an unpinned package, the build reads what the Go package registry seat holds of it (H-A-194).
b.PublishedVersions = publishedVersionsVia(calls.Call)
waitsBucket := process.AwaitBucket(ctx, js, conn, builds.StateBucket(cred.Module, build.WaitsState), "the toolchain waits are kept in memory only, and builder_waits shows none", logger.Printf)
b.Waits = newWaitsKept(waitsBucket, func(ctx context.Context, event, id string, body any) error {
return emitEvent(context.WithoutCancel(ctx), js, cred, event, id, body)
@@ -237,14 +239,15 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
// and version-released heard; nothing is reserved before the fill.
reservedKV := process.AwaitBucket(ctx, js, conn, own.reserved, "no version is reserved: builds are made unreserved", logger.Printf)
reserved := newReservations(awaitedReserved{awaitedVersions{b: reservedKV, bucket: own.reserved}}, calls.Call, pubBoundsKV.KV, found, b.Reconsider, logger.Printf)
// The index by digest and by version beside the reservations is written again once the state is bound (H-A-269 (1), H-A-271).
reservedKV.Ready(func(jetstream.KeyValue) { reserved.reindex(ctx) })
// Each artifact the holder says published at a reserved version is said as the seat mesh-builds' package-published (design 47 G §52).
reserved.say = func(ctx context.Context, p meshbuilds.PackagePublished) error {
return emitSeatEvent(context.WithoutCancel(ctx), js, cred, meshbuilds.SubjectPackagePublished, "package-published-"+p.Module+"-"+p.Version+"-"+p.Artifact, p)
}
b.Reserved = reserved
// A release heard, or the newest the builder's record keeps, pins a package an entry names with none (H-A-165).
reserved.heardReleased = b.VersionReleased
b.NewestReleased = reserved.r.NewestReleased
// A take-over of a series' reservation by another fingerprint withdraws the older build (H-A-225).
reserved.withdraw = b.Withdraw
// The last versions-filled the stream keeps is read at the start (design 47 G §369, §372): a restart does not lose it.
reserved.readFilled(ctx, lastKeptOf(js, cred, logger.Printf), sleeps)
// A state bound later numbers the builds looked at without it.
@@ -258,7 +261,28 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
republish := &versions.Republisher{Reserved: reserved.r, Queue: awaitedQueue{awaitedReserved{awaitedVersions{b: queueKV, bucket: own.queue}}},
Entry: entryVia(calls.Call), Send: sendVia(calls.Call),
Unreleased: reserved.unreleasedWords, Logf: logger.Printf,
Holders: holders} // a registry seat's holder from the seat-holders view, from the start (design 47 G A-416, A-416a)
Holders: holders, // a registry seat's holder from the seat-holders view, from the start (design 47 G A-416, A-416a)
Started: time.Now()} // a build ended from now on is of the live class, sent first (H-A-290 (1))
// A number a registry seat already holds is never reserved (H-A-275): read before reserving, through the seats' verb versions.
reserved.r.HeldNumbers = func(ctx context.Context, module, fp string, refs []string) ([]string, error) {
return republish.HeldNumbers(ctx, module, fp, refs, registryVersionsVia(calls.Call))
}
// A done build whose number a registry holds elsewhere is built again at the next free number (H-A-279), on the builder's context.
reserved.rebuild = func(_ context.Context, module, fp, why string) error {
res := b.BuildAgain(ctx, module, fp, why, "the builder", buildAgainBound)
switch {
case res.Refused != "":
return errors.New(res.Refused)
case res.Failed != "":
return errors.New(res.Failed)
case res.Pending != "":
logger.Printf("%s at %s is built again: %s", module, fp, res.Pending)
}
return nil
}
reserved.r.HeldElsewhere = func(ctx context.Context, module string, skipped []string) {
reserved.heldElsewhere(ctx, module, "the registries hold "+strings.Join(skipped, ", ")+", so the reserve skipped them")
}
publishSet, err := publishSettingsOf(getenv)
if err != nil {
return err
@@ -274,10 +298,16 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
return reserved.r.Of(ctx, module, version)
},
republish: republish.Republish, endedWith: reserved.unreleased,
allDone: func(ctx context.Context) ([]versions.ReservedVersion, error) {
all, err := reserved.r.All(ctx)
return builtOf(all), err
}}
// A publish is asked again only while no published of it may be unheard and the registry's record lacks it (H-A-269 (2), H-A-272).
unheard: unheardVia(js, process.EventsStream, cred.EventConsumerName()),
judge: func(ctx context.Context, v versions.ReservedVersion) (versions.Judged, error) {
return republish.Held(ctx, v, registryVersionsVia(calls.Call))
},
markHeld: reserved.markHeld, moveElsewhere: reserved.movedElsewhere,
allDone: func(ctx context.Context) ([]versions.ReservedVersion, error) { return reserved.r.All(ctx) },
retired: reserved.r.Retired} // only each module's newest done build is asked at the start (H-A-291 (1))
// A version that never publishes (withdrawn or taken over) has its publish item ended by the queue too (H-A-290 (2)).
republish.Ended = items.Done
reasksKV.Ready(func(jetstream.KeyValue) { items.AskAllDone(ctx) })
wirePublishItems(reserved, items, awaitedReserved{awaitedVersions{b: actedKV, bucket: own.acted}}, releasedKept)
acts.Republish = republish.Republish
@@ -470,6 +500,9 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
// a holder of the seat that is down holds no other part of it).
half.b = b
b.Picture = half.picture
// An ask of a revision below the newest the picture holds is read by number from the catalog seat (H-A-205).
b.KeptRevision = keptRevisionVia(calls.Call)
b.FirstBranch = half.first
branches.Held = func(string, meshcatalog.CatalogRevision) { b.PictureHeld() } // a revision held wakes a step ask's wait (H-A-162)
half.ready = func() {
if err := b.Sweep(ctx, half.pictured()...); err != nil {
@@ -46,11 +46,25 @@ type publishItems struct {
reserved func(ctx context.Context, module, version string) (versions.ReservedVersion, bool, error)
republish func(ctx context.Context, module, version string) ([]string, error)
endedWith func(ctx context.Context, v versions.ReservedVersion, why string) // raises the finding version-unreleased
allDone func(ctx context.Context) ([]versions.ReservedVersion, error)
set publishSettings
now func() time.Time
after func(time.Duration) <-chan time.Time
logf func(string, ...any)
// allDone are the reservations, done or not: those whose build is done are asked at the start (builtOf).
allDone func(ctx context.Context) ([]versions.ReservedVersion, error)
// retired are the done builds a newer reservation or release of the same module supersedes, with why (H-A-291 (1)); nil
// retires none.
retired func(ctx context.Context, all []versions.ReservedVersion) (map[string]string, error)
// unheard is how many messages the builder's durable on the events stream holds pending and unacknowledged, read before each
// try (design 47 H H-A-269 (2), H-A-272); nil reads none.
unheard func(ctx context.Context) (int, error)
// judge is what the registries' own record says of a version's missing artifacts (H-A-272, H-A-274, H-A-275); nil judges none.
judge func(ctx context.Context, v versions.ReservedVersion) (versions.Judged, error)
// markHeld marks the artifacts the registries hold with the built digest published from their record, as their published heard
// would (H-A-274); moveElsewhere moves a version a registry holds at another digest to the next free number and asks its
// publish there (H-A-275). Nil does neither.
markHeld func(ctx context.Context, v versions.ReservedVersion, held []versions.HeldArtifact)
moveElsewhere func(ctx context.Context, v versions.ReservedVersion, j versions.Judged) error
set publishSettings
now func() time.Time
after func(time.Duration) <-chan time.Time
logf func(string, ...any)
}
func (p *publishItems) wait(ctx context.Context, d time.Duration) bool {
@@ -88,12 +102,28 @@ func (p *publishItems) Ask(ctx context.Context, module, version string) error {
// AskAllDone asks the publish item of every reservation whose build is done and that has no release: at the builder's start, so
// what stood before this change moves too, whatever its artifacts.
func (p *publishItems) AskAllDone(ctx context.Context) {
vs, err := p.allDone(ctx)
all, err := p.allDone(ctx)
if err != nil {
p.logf("the reservations of done builds are not asked to publish at the start: %v", err)
return
}
for _, v := range vs {
var retired map[string]string
if p.retired != nil {
if retired, err = p.retired(ctx, all); err != nil {
p.logf("the superseded builds are not retired at the start: %v", err)
}
}
for _, v := range builtOf(all) {
if why := retired[v.Module+" "+v.Version]; why != "" { // only each module's newest is asked (H-A-291 (1), H-A-275)
p.logf("%s %s is not asked to publish at the start: %s; its publish item is ended", v.Module, v.Version, why)
p.Done(ctx, v.Module, v.Version)
continue
}
if why := versions.NotStanding(v, true); why != "" { // withdrawn: it never publishes (H-A-290 (2))
p.logf("%s %s is not asked to publish at the start: %s; its publish item is ended", v.Module, v.Version, why)
p.Done(ctx, v.Module, v.Version)
continue
}
if err := p.Ask(ctx, v.Module, v.Version); err != nil {
p.logf("%v", err)
}
@@ -127,7 +157,8 @@ func (p *publishItems) Try(ctx context.Context, kv jetstream.KeyValue, e jetstre
p.logf("%s %s: its reservation cannot be read, the publish item waits: %v", r.Module, r.Version, err)
return
}
if !held { // dropped, taken over or released: never because its artifacts are published (A-456b)
if why := versions.NotStanding(v, held); why != "" { // dropped, taken over, released or withdrawn: never because its artifacts are published (A-456b, H-A-290 (2))
p.logf("%s %s: the publish item is ended: %s", r.Module, r.Version, why)
_ = kv.Delete(ctx, e.Key())
return
}
@@ -138,6 +169,12 @@ func (p *publishItems) Try(ctx context.Context, kv jetstream.KeyValue, e jetstre
if p.endedWith != nil {
p.endedWith(ctx, v, "the publish ended after "+fmt.Sprint(r.Tries)+" tries")
}
} else if why, gone := p.notAgain(ctx, v); gone {
return // moved to another number, whose own item is asked (H-A-275)
} else if why != "" {
// A published of the version may be unheard, or the registry's record ended it: no ask, and no try spent (H-A-272, H-A-274).
p.logf("%s %s: the publish is not asked again: %s; tried again after %s", r.Module, r.Version, why, p.set.pauseAfter(r.Tries))
r.NextTry = p.now().UTC().Add(p.set.pauseAfter(r.Tries))
} else {
r.Tries++
if _, err := p.republish(ctx, r.Module, r.Version); err != nil {
@@ -154,6 +191,85 @@ func (p *publishItems) Try(ctx context.Context, kv jetstream.KeyValue, e jetstre
}
}
// notAgain says why a version's publish is not asked again now, empty when it is (design 47 H H-A-269 (2), H-A-272, H-A-274,
// H-A-275): the builder's durable holds UnheardBound messages or more not yet heard, so a published of it may be among them; or the
// registries' own record holds every missing artifact at its version with its built digest, which marks them published from that
// record; or a registry holds the version at another digest, which moves the build to the next free number (gone: this item is
// ended with the old number). A count or a record that cannot be read is said, and does not hold the ask.
func (p *publishItems) notAgain(ctx context.Context, v versions.ReservedVersion) (why string, gone bool) {
if p.unheard != nil {
n, err := p.unheard(ctx)
switch {
case err != nil:
p.logf("%s %s: the builder's events consumer cannot be read, so the publish is asked again as it stands: %v", v.Module, v.Version, err)
case n >= versions.UnheardBound:
return fmt.Sprintf("the builder's events consumer holds %d messages not yet heard (the bound is %d), a published of it may be among them", n, versions.UnheardBound), false
}
}
if p.judge == nil {
return "", false
}
j, err := p.judge(ctx, v)
switch {
case err != nil:
p.logf("%s %s: the registries' record cannot be read, so the publish is asked again: %v", v.Module, v.Version, err)
case len(j.Elsewhere) > 0 && p.moveElsewhere != nil:
if err := p.moveElsewhere(ctx, v, j); err != nil {
p.logf("%s %s: a registry holds the number at another digest, and the build is not moved: %v", v.Module, v.Version, err)
return "a registry holds " + v.Version + " at another digest", false
}
return "", true
case j.All:
if p.markHeld != nil {
p.markHeld(ctx, v, j.Held)
}
return "the registries hold every missing artifact at " + v.Version + " with its built digest: marked published from their record", false
default:
p.logf("%s %s: asked again: %s", v.Module, v.Version, j.Lacks)
}
return "", false
}
// unheardVia reads the builder's durable on the events stream: its messages pending and those given and not yet acknowledged
// (design 47 H H-A-272), what it has not yet heard.
func unheardVia(js jetstream.JetStream, stream, durable string) func(context.Context) (int, error) {
return func(ctx context.Context) (int, error) {
c, err := js.Consumer(ctx, stream, durable)
if err != nil {
return 0, err
}
info, err := c.Info(ctx)
if err != nil {
return 0, err
}
return int(info.NumPending) + info.NumAckPending, nil
}
}
// registryVersionsVia asks a registry seat's verb versions for a name (H-A-272): each version it holds with its digest.
func registryVersionsVia(call toolCaller) func(context.Context, string, string) ([]versions.HeldVersion, error) {
return func(_ context.Context, seat, name string) ([]versions.HeldVersion, error) {
raw, err := call("seat:"+seat+"."+versions.VerbVersions, map[string]any{"name": name})
if err != nil {
return nil, err
}
var a struct { // the four registry seats answer versions alike: each version with its digest
Versions []struct {
Version string `json:"version"`
Digest string `json:"digest"`
} `json:"versions"`
}
if err := json.Unmarshal(raw, &a); err != nil {
return nil, fmt.Errorf("%s's versions answered what is no list of versions: %w", seat, err)
}
out := make([]versions.HeldVersion, 0, len(a.Versions))
for _, v := range a.Versions {
out = append(out, versions.HeldVersion{Version: v.Version, Digest: v.Digest})
}
return out, nil
}
}
// numberFile reads a setting's number from the file the manifest declares: no file or an empty one is def; a content that is no
// number of at least one is an error naming the file.
func numberFile(path string, def int) (int, error) {
@@ -4,9 +4,12 @@ import (
"context"
"encoding/json"
"errors"
"maps"
"os"
"path/filepath"
"slices"
"strings"
"sync"
"testing"
"time"
@@ -19,9 +22,10 @@ import (
"mesh-delivery-builder/internal/versions"
)
// itemKV is the re-ask state in memory: one revision per key.
// itemKV is the re-ask state in memory: one revision per key, its maps locked (a try writes from the re-ask watch's goroutine).
type itemKV struct {
jetstream.KeyValue
mu sync.Mutex
vals map[string][]byte
revs map[string]uint64
rev uint64
@@ -42,13 +46,25 @@ func (e itemEntry) Operation() jetstream.KeyValueOp { return jetstream.KeyValueP
func (k *itemKV) entry(key string) jetstream.KeyValueEntry {
return itemEntry{key: key, value: k.vals[key], rev: k.revs[key]}
}
// has says whether key holds a value.
func (k *itemKV) has(key string) bool {
k.mu.Lock()
defer k.mu.Unlock()
_, ok := k.vals[key]
return ok
}
func (k *itemKV) Get(_ context.Context, key string) (jetstream.KeyValueEntry, error) {
k.mu.Lock()
defer k.mu.Unlock()
if _, ok := k.vals[key]; !ok {
return nil, jetstream.ErrKeyNotFound
}
return k.entry(key), nil
}
func (k *itemKV) Create(_ context.Context, key string, v []byte, _ ...jetstream.KVCreateOpt) (uint64, error) {
k.mu.Lock()
defer k.mu.Unlock()
if _, ok := k.vals[key]; ok {
return 0, jetstream.ErrKeyExists
}
@@ -57,6 +73,8 @@ func (k *itemKV) Create(_ context.Context, key string, v []byte, _ ...jetstream.
return k.rev, nil
}
func (k *itemKV) Update(_ context.Context, key string, v []byte, rev uint64) (uint64, error) {
k.mu.Lock()
defer k.mu.Unlock()
if k.revs[key] != rev {
return 0, jetstream.ErrKeyExists
}
@@ -65,6 +83,8 @@ func (k *itemKV) Update(_ context.Context, key string, v []byte, rev uint64) (ui
return k.rev, nil
}
func (k *itemKV) Delete(_ context.Context, key string, _ ...jetstream.KVDeleteOpt) error {
k.mu.Lock()
defer k.mu.Unlock()
delete(k.vals, key)
return nil
}
@@ -140,21 +160,49 @@ func TestAPublishItemIsTriedWithAGrowingPauseAndEndsLoudly(t *testing.T) {
kv.vals, kv.revs = map[string][]byte{}, map[string]uint64{}
p.allDone = func(context.Context) ([]versions.ReservedVersion, error) {
published := versions.ReservedVersion{Module: "n", Version: "0.2.0", Artifacts: map[string]string{"n:a": "sha256:a"}, Published: map[string]bool{"n:a": true}, BuiltAt: now}
return builtOf([]versions.ReservedVersion{v, published, {Module: "o", Version: "0.1.0"}}), nil // the last build has not ended
withdrawn := versions.ReservedVersion{Module: "w", Version: "0.4.0", BuiltAt: now, Withdrawn: map[string]string{"0.4.0": "fp"}}
return builtOf([]versions.ReservedVersion{v, published, withdrawn, {Module: "o", Version: "0.1.0"}}), nil // the last build has not ended
}
_ = p.Ask(ctx, "w", "0.4.0") // asked before its reservation was withdrawn
p.AskAllDone(ctx)
if len(kv.vals) != 2 {
t.Errorf("the start asked %d items, want one per done unreleased reservation", len(kv.vals))
if _, ok := kv.vals[versions.PublishItemKey("w", "0.4.0")]; len(kv.vals) != 2 || ok {
t.Errorf("the start left %d items (withdrawn's kept: %v), want one per done unreleased reservation and none for a withdrawn one (H-A-290 (2))", len(kv.vals), ok)
}
// A start with three unreleased done versions of one module asks only the newest and retires the two (H-A-291 (1), H-A-275).
kv.vals, kv.revs = map[string][]byte{}, map[string]uint64{}
_ = p.Ask(ctx, "s", "0.1.3") // asked in an earlier run
p.allDone = func(context.Context) ([]versions.ReservedVersion, error) {
var out []versions.ReservedVersion
for _, ver := range []string{"0.1.3", "0.1.10", "0.1.2"} { // one series (H-A-293)
out = append(out, versions.ReservedVersion{Module: "s", Version: ver, Artifacts: map[string]string{"s:a": "sha256:a"}, BuiltAt: now})
}
return out, nil
}
p.retired = (&versions.Reserver{}).Retired
p.AskAllDone(ctx)
if _, ok := kv.vals[versions.PublishItemKey("s", "0.1.10")]; len(kv.vals) != 1 || !ok {
t.Errorf("the start left the items %v, want only the newest, s 0.1.10, asked and the two older retired", slices.Collect(maps.Keys(kv.vals)))
}
kv.vals, kv.revs = map[string][]byte{}, map[string]uint64{}
// A released version's item is deleted; a version no longer reserved has it deleted at its next try.
p.Done(ctx, "m", "0.1.2")
p.Done(ctx, "n", "0.2.0")
if len(kv.vals) != 0 {
t.Errorf("the release left %v", kv.vals)
}
// A withdrawn reservation has its item ended at its try, nothing queued (H-A-290 (2)).
queued = nil
_ = p.Ask(ctx, "m", "0.1.2")
v.Withdrawn = map[string]string{"0.1.2": "fp"}
e, _ := kv.Get(ctx, key)
p.Try(ctx, kv, e, decodeItem(t, e.Value()))
if len(kv.vals) != 0 || len(queued) != 0 {
t.Errorf("a withdrawn reservation left its item %v, queued %v", kv.vals, queued)
}
v.Withdrawn = nil
_ = p.Ask(ctx, "m", "0.1.2")
reserved = false
e, _ := kv.Get(ctx, key)
e, _ = kv.Get(ctx, key)
p.Try(ctx, kv, e, decodeItem(t, e.Value()))
if len(kv.vals) != 0 {
t.Errorf("a dropped reservation left its item %v", kv.vals)
@@ -220,7 +268,7 @@ func TestThePublishItemsAreWiredToTheReservationsAndTheReAskWatch(t *testing.T)
}
first := done("src2:one")
key := versions.PublishItemKey("m", first.Version)
if _, ok := kv.vals[key]; !ok {
if !kv.has(key) {
t.Fatalf("a done build has no publish item: %v", kv.vals)
}
// A build whose artifacts are all published still gets its item, until its release is written (A-456b).
@@ -231,7 +279,7 @@ func TestThePublishItemsAreWiredToTheReservationsAndTheReAskWatch(t *testing.T)
if err := rv.Built(ctx, "m", first.Version, map[string]string{"m:a": "sha256:a"}, nil); err != nil {
t.Fatal(err)
}
if _, ok := kv.vals[key]; !ok {
if !kv.has(key) {
t.Fatalf("a build with every artifact published has no item: %v", kv.vals)
}
// The watch hands the item to its try, which queues the publish.
@@ -247,11 +295,11 @@ func TestThePublishItemsAreWiredToTheReservationsAndTheReAskWatch(t *testing.T)
}
// A takeover by another build deletes the older's item and asks the newer's.
second := done("src2:two")
if _, ok := kv.vals[key]; ok {
if kv.has(key) {
t.Errorf("the taken-over reservation kept its item")
}
secondKey := versions.PublishItemKey("m", second.Version)
if _, ok := kv.vals[secondKey]; !ok {
if !kv.has(secondKey) {
t.Fatalf("the newer build has no item: %v", kv.vals)
}
// version-released deletes the item and keeps the release.
@@ -259,7 +307,7 @@ func TestThePublishItemsAreWiredToTheReservationsAndTheReAskWatch(t *testing.T)
if !rv.heard(ctx, msg) || !msg.acked {
t.Fatal("version-released was not taken in")
}
if _, ok := kv.vals[secondKey]; ok {
if kv.has(secondKey) {
t.Errorf("a released version kept its publish item")
}
if ok, _ := rv.ReleasedFor(ctx, "m", "src2:two"); !ok {
@@ -270,7 +318,80 @@ func TestThePublishItemsAreWiredToTheReservationsAndTheReAskWatch(t *testing.T)
if _, err := rv.dropped(ctx, "m", "0.1", "op", "never", time.Unix(0, 0)); err != nil {
t.Fatal(err)
}
if _, ok := kv.vals[versions.PublishItemKey("m", third.Version)]; ok {
if kv.has(versions.PublishItemKey("m", third.Version)) {
t.Errorf("a dropped reservation kept its item")
}
}
// TestAPublishIsNotAskedAgainWhileItsPublishedMayBeUnheard: design 47 H H-A-269 (2), H-A-272, H-A-274, H-A-275 — a try asks the
// publish again only while the builder's durable holds fewer than a hundred messages not yet heard and the registries' record lacks
// an artifact; a record holding every missing artifact with the built digest marks them published from it; a record holding the
// version at another digest moves the build to the next free number and ends this item; a skipped try spends no try and is written
// again with its pause; a count that cannot be read holds no ask.
func TestAPublishIsNotAskedAgainWhileItsPublishedMayBeUnheard(t *testing.T) {
ctx := context.Background()
now := time.Date(2026, 11, 21, 15, 21, 0, 0, time.UTC)
v := versions.ReservedVersion{Module: "node-tools", Version: "0.1.37", Artifacts: map[string]string{"node-tools:program": "sha256:7c9b10"}, BuiltAt: now}
at := versions.HeldArtifact{Ref: "node-tools:program", Seat: versions.SeatArtifacts, Name: "node-tools/program", Version: "0.1.37", Digest: "sha256:7c9b10"}
other := at
other.Digest = "sha256:83bec1"
for _, c := range []struct {
name string
unheard int
countErr error
judged versions.Judged
wantAsked, wantMark, wantMov bool
}{
{name: "thousands behind: no ask, the registry not read", unheard: 2944},
{name: "at the bound: no ask", unheard: versions.UnheardBound},
{name: "heard up, the registry holds it: marked from its record, no ask", unheard: versions.UnheardBound - 1, judged: versions.Judged{All: true, Held: []versions.HeldArtifact{at}}, wantMark: true},
{name: "the registry holds the number at another digest: moved, no ask", unheard: 3, judged: versions.Judged{Elsewhere: []versions.HeldArtifact{other}}, wantMov: true},
{name: "heard up, the registry lacks it: asked", unheard: 3, judged: versions.Judged{Lacks: "none"}, wantAsked: true},
{name: "the count unreadable, the registry lacks it: asked", countErr: errors.New("no consumer"), judged: versions.Judged{Lacks: "none"}, wantAsked: true},
} {
t.Run(c.name, func(t *testing.T) {
kv := &itemKV{vals: map[string][]byte{}, revs: map[string]uint64{}}
asked, judged, marked, moved := 0, 0, 0, 0
p := &publishItems{reasks: func() jetstream.KeyValue { return kv }, set: defaultPublishSettings, now: func() time.Time { return now }, logf: t.Logf,
reserved: func(context.Context, string, string) (versions.ReservedVersion, bool, error) { return v, true, nil },
republish: func(context.Context, string, string) ([]string, error) { asked++; return nil, nil },
unheard: func(context.Context) (int, error) { return c.unheard, c.countErr },
judge: func(context.Context, versions.ReservedVersion) (versions.Judged, error) {
judged++
return c.judged, nil
},
markHeld: func(_ context.Context, _ versions.ReservedVersion, h []versions.HeldArtifact) {
if len(h) == 1 && h[0].Digest == "sha256:7c9b10" {
marked++
}
},
moveElsewhere: func(context.Context, versions.ReservedVersion, versions.Judged) error {
moved++
delete(kv.vals, versions.PublishItemKey(v.Module, v.Version)) // the takeover ends the old item
return nil
}}
if err := p.Ask(ctx, v.Module, v.Version); err != nil {
t.Fatal(err)
}
key := versions.PublishItemKey(v.Module, v.Version)
e, _ := kv.Get(ctx, key)
p.Try(ctx, kv, e, decodeItem(t, e.Value()))
if (asked == 1) != c.wantAsked || (marked == 1) != c.wantMark || (moved == 1) != c.wantMov {
t.Fatalf("asked %d, marked %d, moved %d; want asked %v, marked %v, moved %v", asked, marked, moved, c.wantAsked, c.wantMark, c.wantMov)
}
if c.wantMov {
if _, ok := kv.vals[key]; ok {
t.Error("the moved version's old item is written again")
}
return
}
got := decodeItem(t, kv.vals[key])
if got.Tries != map[bool]int{true: 1, false: 0}[c.wantAsked] || !got.NextTry.After(now) {
t.Errorf("tries %d, next try %s: want a try spent only when asked, and the item written again with its pause", got.Tries, got.NextTry)
}
if c.unheard >= versions.UnheardBound && judged != 0 {
t.Error("the registry is read while a published may be unheard")
}
})
}
}
@@ -549,8 +549,14 @@ func (m memVersions) Update(_ context.Context, key string, v []byte, _ uint64) (
m[key] = v
return 2, nil
}
func (m memVersions) KeysOf(context.Context, string) ([]string, error) {
return slices.Collect(maps.Keys(m)), nil
func (m memVersions) KeysOf(_ context.Context, filter string) ([]string, error) {
var out []string
for k := range m {
if versions.FilterMatches(filter, k) { // as the bus reads a filter
out = append(out, k)
}
}
return out, nil
}
// memBuilds is the builder's builds in memory.
@@ -33,8 +33,8 @@ func (s awaitedQueue) Bytes(ctx context.Context) (uint64, error) {
// entryVia reads a catalog graph entry by its fingerprint through the seat mesh-catalog's verb entry.
func entryVia(call toolCaller) func(ctx context.Context, fingerprint string) (meshcatalog.CatalogEntry, error) {
return func(_ context.Context, fingerprint string) (meshcatalog.CatalogEntry, error) {
raw, err := call("seat:"+meshcatalog.Seat+"."+meshcatalog.VerbEntry, meshcatalog.EntryInput{Fingerprint: fingerprint})
return func(ctx context.Context, fingerprint string) (meshcatalog.CatalogEntry, error) {
raw, err := callWithin(ctx, call, "seat:"+meshcatalog.Seat+"."+meshcatalog.VerbEntry, meshcatalog.EntryInput{Fingerprint: fingerprint})
if err != nil {
return meshcatalog.CatalogEntry{}, err
}
@@ -50,8 +50,8 @@ func entryVia(call toolCaller) func(ctx context.Context, fingerprint string) (me
// artifact store, addressed by digest. The four seats' publish take one wire form; an answer that lacks parts, or a fault of
// the call, is the holder's refusal, said in its words (not stored when the holder lacks the bytes).
func sendVia(call toolCaller) func(ctx context.Context, p versions.Publish) error {
return func(_ context.Context, p versions.Publish) error {
raw, err := call("seat:"+p.Seat+"."+versions.VerbPublish, publishBody(p))
return func(ctx context.Context, p versions.Publish) error {
raw, err := callWithin(ctx, call, "seat:"+p.Seat+"."+versions.VerbPublish, publishBody(p))
if err != nil {
return fmt.Errorf("%s's publish of %s %s: %w", p.Seat, p.Name, p.Version, err)
}
@@ -66,6 +66,29 @@ func sendVia(call toolCaller) func(ctx context.Context, p versions.Publish) erro
}
}
// callWithin is call within ctx's bound (design 47 H H-A-290 (4)): its answer, or, once the bound ends first, that it was not
// answered within it. The call itself ends by its own bound (the SDK's call timeout), its answer then dropped.
func callWithin(ctx context.Context, call toolCaller, key string, body any) (json.RawMessage, error) {
if err := ctx.Err(); err != nil {
return nil, fmt.Errorf("%s is not called: %w", key, context.Cause(ctx))
}
type answer struct {
raw json.RawMessage
err error
}
done := make(chan answer, 1)
go func() {
raw, err := call(key, body)
done <- answer{raw, err}
}()
select {
case a := <-done:
return a.raw, a.err
case <-ctx.Done():
return nil, fmt.Errorf("%s is not answered within its bound: %w", key, context.Cause(ctx))
}
}
// publishBody is the seat's publish input for p: the digest, its kind and name and version, no parts.
func publishBody(p versions.Publish) gopackageregistry.PublishInput {
return gopackageregistry.PublishInput{Commit: p.Commit, Digest: p.Digest, Fingerprint: p.Fingerprint, Kind: p.Kind, Name: p.Name, Transfer: p.Transfer, Version: p.Version}
@@ -57,6 +57,26 @@ func TestRepublishSend(t *testing.T) {
t.Errorf("%s: asked %q, error %v, want %q", name, asked, err, c.want)
}
}
// A send and its entry read honour the bound they are given (design 47 H H-A-290 (4)): a call still unanswered when it ends
// is said as not answered within it, and the send goes on.
release := make(chan struct{})
defer close(release)
called := make(chan struct{}, 2)
slow := func(string, any) (json.RawMessage, error) {
called <- struct{}{}
<-release
return json.RawMessage(`{}`), nil
}
for name, call := range map[string]func(context.Context) error{
"the publish": func(ctx context.Context) error { return sendVia(slow)(ctx, p) },
"the entry": func(ctx context.Context) error { _, err := entryVia(slow)(ctx, "fp"); return err },
} {
ctx, cancel := context.WithCancel(context.Background())
go func() { <-called; cancel() }()
if err := call(ctx); err == nil || !strings.Contains(err.Error(), "within its bound") {
t.Errorf("%s past its bound answered %v, want it not answered within its bound", name, err)
}
}
if _, _, err := build.NewRepublish("", "0.1.3", "why", "me", versionsNow()); err == nil {
t.Error("a version with no module is accepted")
}
@@ -44,17 +44,18 @@ type reservations struct {
// 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)
filled atomic.Bool
bounds func() jetstream.KeyValue
found *findings
bound time.Duration
wake func(context.Context)
logf func(string, ...any)
// withdraw ends the running build of a module's fingerprint, superseded, with why (H-A-225); nil ends none.
withdraw func(module, fingerprint, why string)
// call asks a seat's verb: the git seat's tag (design 47 G §370).
call toolCaller
// rebuild builds a done key of module at fp again (the build-again path, A-490; H-A-279); nil builds none.
rebuild func(ctx context.Context, module, fp, why string) error
// say says package-published on the seat mesh-builds; nil says none.
say func(context.Context, meshbuilds.PackagePublished) error
}
@@ -78,10 +79,21 @@ func newReservations(store versions.ReserveStore, call toolCaller, bounds func()
}
return out, nil
}}
rv.r.Took = rv.took
rv.r.Took, rv.r.Logf = rv.took, logf
return rv
}
// reindex writes the reservations' index again from the reservations, once at the builder's start (H-A-269 (1), H-A-271), and
// says so.
func (rv *reservations) reindex(ctx context.Context) {
n, err := rv.r.Reindex(ctx)
if err != nil {
rv.logf("the reservations' index is written again from %d reservations, not whole: %v", n, err)
return
}
rv.logf("the reservations' index is written again from %d reservations", n)
}
// 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) {
@@ -95,6 +107,11 @@ func (rv *reservations) took(ctx context.Context, older, newer versions.Reserved
}
rv.dropBound(ctx, versions.ReservedKey(older.Module, older.Series))
rv.found.clear(ctx, versions.VersionUnreleased, meshconditionsclient.ScopeModule, older.Module)
if older.Fingerprint != newer.Fingerprint && rv.withdraw != nil {
// The older build is ended superseded, as the picture's supersession ends one (H-A-225, ADR 0664 §4): nothing publishes
// under the dropped number.
rv.withdraw(older.Module, older.Fingerprint, "its reservation "+older.Version+" was taken over by the build of "+newer.Fingerprint+", which reserves "+newer.Version)
}
}
var _ build.Reservations = (*reservations)(nil)
@@ -113,6 +130,11 @@ func (rv *reservations) ReservedFor(ctx context.Context, module, fingerprint str
return versions.ReservedVersion{}, false, nil
}
// TakenOver is the reservation that took module's series over from the build of fingerprint (H-A-244).
func (rv *reservations) TakenOver(ctx context.Context, module, fingerprint string) (versions.ReservedVersion, bool, error) {
return rv.r.TakenOver(ctx, module, fingerprint)
}
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) {
@@ -255,10 +277,8 @@ func (rv *reservations) heard(ctx context.Context, m jetstream.Msg) bool {
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)
rv.found.clear(ctx, versions.VersionHeldElsewhere, meshconditionsclient.ScopeModule, ev.Module)
default:
return false
}
@@ -268,19 +288,21 @@ func (rv *reservations) heard(ctx context.Context, m jetstream.Msg) bool {
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)
// published marks the artifacts of the reservation a registry seat's published names (its version and digest). inProgress is told
// before a pass that may read many reservations, so the handler says in progress to the bus (design 47 H H-A-280); nil is told
// nothing.
func (rv *reservations) published(ctx context.Context, o versions.Outcome, inProgress func()) {
out, err := rv.r.PublishedRead(ctx, o.Name, o.Version, o.Digest, inProgress)
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))
if len(out.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(out.Kept, ", "))
} else if len(out.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, out.Read))
}
// 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 {
for _, m := range out.Marked {
rv.sayPublished(ctx, m, o.Digest)
}
}
@@ -343,27 +365,29 @@ func (rv *reservations) tagged(ctx context.Context, ev meshcatalog.VersionReleas
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 {
// noMark says why a published marked nothing, from the reservations the published read (design 47 H H-A-280: no second read):
// what each holds of digests, and how many stand at that version by the index by version (its one key, no reservation read).
func (rv *reservations) noMark(ctx context.Context, o versions.Outcome, read []versions.ReadReservation) 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 {
for _, r := range read {
v := r.Reserved
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))
out = append(out, fmt.Sprintf("%s holds %d built digests %v, published %v", v.Module, len(v.Artifacts), v.Artifacts, v.Published))
}
standing := "the number standing at it is not read"
if keys, err := rv.r.IndexedAt(ctx, version); err == nil {
standing = fmt.Sprintf("%d reservations stand at it, the built ones not read", len(keys))
}
if len(out) == 0 {
return "no reservation holds version " + version
return "no reservation read holds version " + version + " unbuilt or with that digest (" + standing + ")"
}
return strings.Join(out, "; ")
return strings.Join(out, "; ") + " (" + standing + "; a published heard before the build recorded its digests is kept until it does)"
}
// 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
@@ -389,3 +413,49 @@ func reserveDoneAct(reserve func(ctx context.Context, module, fp string) (versio
func (rv *reservations) ReleasedFor(ctx context.Context, module, fingerprint string) (bool, error) {
return rv.r.ReleasedFor(ctx, module, fingerprint)
}
// markHeld marks the artifacts the registries' record holds at their version with the built digest published, as their published
// heard would, and says package-published of each (design 47 H H-A-274): a published heard and lost never leaves the publish
// asked for ever. The version's release follows from the catalog as for any published.
func (rv *reservations) markHeld(ctx context.Context, v versions.ReservedVersion, held []versions.HeldArtifact) {
for _, h := range held {
rv.logf("%s %s: %s holds %s %s with the built digest %s: marked published from its record", v.Module, v.Version, h.Seat, h.Name, h.Version, h.Digest)
rv.published(ctx, versions.Outcome{Name: h.Name, Version: h.Version, Digest: h.Digest, Holder: h.Seat}, nil)
}
}
// heldElsewhere raises version-held-elsewhere about module (design 47 H H-A-275): numbers a registry holds were skipped or moved
// from, said with why.
func (rv *reservations) heldElsewhere(ctx context.Context, module, why string) {
rv.logf("%s: %s", module, why)
rv.found.raise(ctx, finding{kind: versions.VersionHeldElsewhere, scope: meshconditionsclient.ScopeModule, id: module,
summary: module + ": " + why,
headline: "A number a registry already holds is not used",
explanation: "A registry seat holds a version of " + module + " the builder did not publish there: " + why + ".",
resolved: "The catalog says version-released for " + module + ".",
needs: "builder_reserved shows the reservation and its withdrawn numbers; the registry seat's versions shows what it holds."})
}
// movedElsewhere takes a done build whose number a registry holds at another digest off that number (design 47 H H-A-275,
// H-A-279): every artifact carries its version from its build, so no digest survives a move. The number is withdrawn as a gap
// (H-A-226), the finding raised naming both digests, and the build of the same fingerprint asked again (the build-again path of a
// done key whose version is not released, A-490): its reserve takes the next number no registry holds, it records fresh digests
// and its own publish runs; the takeover of the withdrawn reservation ends its publish item and bound.
func (rv *reservations) movedElsewhere(ctx context.Context, v versions.ReservedVersion, j versions.Judged) error {
if rv.rebuild == nil {
return errors.New("no build again is wired")
}
if _, ok, err := rv.r.Withdraw(ctx, v.Module, v.Version); err != nil || !ok {
if err == nil {
err = fmt.Errorf("no reservation of %s stands at %s", v.Module, v.Version)
}
return err
}
var at []string
for _, h := range j.Elsewhere {
at = append(at, fmt.Sprintf("%s holds %s %s at %s, built %s", h.Seat, h.Name, h.Version, h.Digest, v.Artifacts[h.Ref]))
}
why := fmt.Sprintf("%s is withdrawn and the build of %s is built again at the next free number: %s", v.Version, v.Fingerprint, strings.Join(at, "; "))
rv.heldElsewhere(ctx, v.Module, why)
return rv.rebuild(ctx, v.Module, v.Fingerprint, why)
}
@@ -48,7 +48,7 @@ func (m *memReserve) Update(_ context.Context, key string, v []byte, rev uint64)
func (m *memReserve) KeysOf(_ context.Context, filter string) ([]string, error) {
var out []string
for k := range m.vals {
if filter == versions.AllFilter || strings.HasPrefix(k, strings.TrimSuffix(filter, "*")) {
if versions.FilterMatches(filter, k) { // as the bus reads a filter
out = append(out, k)
}
}
@@ -119,10 +119,10 @@ func TestTheCatalogsWordsMoveTheReservations(t *testing.T) {
if !bounds.keys[boundKey] {
t.Fatalf("the publish's bound is not armed: %v", bounds.keys)
}
rv.published(ctx, versions.Outcome{Name: "m-a", Version: "1.4.3", Digest: "sha256:a"})
rv.published(ctx, versions.Outcome{Name: "m-a", Version: "1.4.3", Digest: "sha256:a"}, nil)
// Design 47 G §52, A-57: the holder's published is said once, per artifact, as the seat mesh-builds' package-published with the
// branch and source revision of the reservation; a second published of the same artifact says nothing.
rv.published(ctx, versions.Outcome{Name: "m-a", Version: "1.4.3", Digest: "sha256:a"})
rv.published(ctx, versions.Outcome{Name: "m-a", Version: "1.4.3", Digest: "sha256:a"}, nil)
if len(said) != 1 || said[0].Artifact != "m:a" || said[0].Version != "1.4.3" || said[0].Digest != "sha256:a" || said[0].Branch != "main" || said[0].Source != 41 {
t.Fatalf("package-published said %+v, want one of m:a at 1.4.3 for main at source 41", said)
}
@@ -134,15 +134,10 @@ func TestTheCatalogsWordsMoveTheReservations(t *testing.T) {
if err != nil || !strings.Contains(got.Summary, "m:b unpublished") || strings.Contains(got.Summary, "m:a unpublished") || !strings.Contains(got.Summary, "1.4.3") {
t.Fatalf("finding = %+v (%v), want version-unreleased naming m:b of 1.4.3", got, err)
}
var heardReleases []string // H-A-165: a release heard wakes a step ask waiting for a package of the module
rv.heardReleased = func(m, v string) { heardReleases = append(heardReleases, m+" "+v) }
released := &wakeMsg{subject: meshcatalog.SubjectVersionReleased, data: []byte(`{"v":1,"module":"m","version":"1.4.3","source":1,"artifacts":[]}`)}
if !rv.heard(ctx, released) || !released.acked {
t.Fatalf("version-released was not taken in (acked %v)", released.acked)
}
if strings.Join(heardReleases, ", ") != "m 1.4.3" {
t.Errorf("the release heard was told %v, want m 1.4.3 (H-A-165)", heardReleases)
}
if strings.Join(items, ", ") != "asked m 1.4.3, ended m 1.4.3" {
t.Errorf("publish items %v, want the build's end to ask the publish and the release to end it", items)
}
@@ -241,8 +236,8 @@ func TestAPublishedHeardBeforeTheDigestsIsSaidWhenTheBuildRecordsThem(t *testing
if err != nil {
t.Fatal(err)
}
rv.published(ctx, versions.Outcome{Name: "m-a", Version: res.Version, Digest: "sha256:a"})
rv.published(ctx, versions.Outcome{Name: "m-x", Version: res.Version, Digest: "sha256:x"})
rv.published(ctx, versions.Outcome{Name: "m-a", Version: res.Version, Digest: "sha256:a"}, nil)
rv.published(ctx, versions.Outcome{Name: "m-x", Version: res.Version, Digest: "sha256:x"}, nil)
if len(said) != 0 {
t.Fatalf("package-published said before the digests are recorded: %+v", said)
}
@@ -264,14 +259,15 @@ func TestAPublishedHeardBeforeTheDigestsIsSaidWhenTheBuildRecordsThem(t *testing
t.Fatalf("no finding raised for the digest the holder holds: %s", raised)
}
// Taken in once: a published of m:a heard again says nothing more.
rv.published(ctx, versions.Outcome{Name: "m-a", Version: res.Version, Digest: "sha256:a"})
rv.published(ctx, versions.Outcome{Name: "m-a", Version: res.Version, Digest: "sha256:a"}, nil)
if len(said) != 1 {
t.Fatalf("package-published said again: %+v", said)
}
}
// TestABuildTakingOverAnOlderReservationDropsItsBoundAndSaysSo: design 47 G A-455 — a build that reserves while the series is
// reserved by an older build never released drops the older one's bound and finding and says so in the builder's journal.
// reserved by an older build never released drops the older one's bound and finding and says so in the builder's journal; and
// H-A-225 — the older build is withdrawn, so nothing publishes under the dropped number, while a re-run of the newer keeps it.
func TestABuildTakingOverAnOlderReservationDropsItsBoundAndSaysSo(t *testing.T) {
ctx := context.Background()
st := &memFindings{vals: map[string][]byte{}}
@@ -284,6 +280,8 @@ func TestABuildTakingOverAnOlderReservationDropsItsBoundAndSaysSo(t *testing.T)
rv := newReservations(&memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}, call, func() jetstream.KeyValue { return bounds }, found,
nil, func(f string, a ...any) { journal = append(journal, fmt.Sprintf(f, a...)) })
rv.filled.Store(true)
var withdrawn []string
rv.withdraw = func(module, fp, why string) { withdrawn = append(withdrawn, module+" "+fp+": "+why) }
older, err := rv.Reserve(ctx, "m", "0.1", []string{"m:a"}, versions.Source{Fingerprint: "fp-old"})
if err != nil {
t.Fatal(err)
@@ -310,6 +308,12 @@ func TestABuildTakingOverAnOlderReservationDropsItsBoundAndSaysSo(t *testing.T)
if got, ok, _ := rv.ReservedFor(ctx, "m", "fp-new"); !ok || got.Version != "0.1.1" {
t.Errorf("reserved for fp-new: %+v %v", got, ok)
}
if len(withdrawn) != 1 || withdrawn[0] != "m fp-old: its reservation 0.1.0 was taken over by the build of fp-new, which reserves 0.1.1" {
t.Errorf("withdrawn %q; want the build of fp-old withdrawn once", withdrawn)
}
if again, err := rv.Reserve(ctx, "m", "0.1", []string{"m:a"}, versions.Source{Fingerprint: "fp-new"}); err != nil || again.Version != "0.1.1" || len(withdrawn) != 1 {
t.Errorf("a re-run of fp-new reserved %q (%v), withdrew %q; want 0.1.1 kept, nothing withdrawn", again.Version, err, withdrawn)
}
}
// ansKV records the value versionActed writes back to a reasks key.
@@ -389,3 +393,142 @@ func TestAReserveDoneIsAnsweredWithTheVersionAndItsQueuedPublish(t *testing.T) {
t.Errorf("the reserving by hand is not said in the log: %q", logged)
}
}
// TestARegistrysRecordEndsOrMovesAPublish: design 47 H H-A-274 — the artifacts a registry's record holds with the built digest are
// marked published from it and package-published is said, as a heard published would; H-A-275 — a done build whose number a
// registry holds at another digest (H-A-279) has its number withdrawn, raises version-held-elsewhere naming both digests, and is
// built again: at the next number no registry holds, with a fresh digest, published there; the old number's item ends.
func TestARegistrysRecordEndsOrMovesAPublish(t *testing.T) {
ctx := context.Background()
fs := &memFindings{vals: map[string][]byte{}}
none := func(string, any) (json.RawMessage, error) {
return json.Marshal(meshcatalog.VersionsAnswer{Module: "node-tools"})
}
bounds := &boundsKV{keys: map[string]bool{}}
rv := newReservations(&memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}, none, func() jetstream.KeyValue { return bounds },
&findings{module: builds.BuilderModule, w: fs, logf: t.Logf, now: time.Now}, nil, t.Logf)
var said []meshbuilds.PackagePublished
rv.say = func(_ context.Context, p meshbuilds.PackagePublished) error { said = append(said, p); return nil }
var asked, ended []string
rv.built = func(_ context.Context, m, v string) error { asked = append(asked, m+" "+v); return nil }
rv.released = func(_ context.Context, m, v string) { ended = append(ended, m+" "+v) }
registry := []string{"0.1.37"}
rv.r.HeldNumbers = func(context.Context, string, string, []string) ([]string, error) { return registry, nil }
rv.filled.Store(true)
res, err := rv.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, versions.Source{Fingerprint: "fp1"})
if err != nil || res.Version != "0.1.0" {
t.Fatalf("reserved %q (%v)", res.Version, err)
}
if err := rv.Built(ctx, "node-tools", res.Version, map[string]string{"node-tools:program": "sha256:7c9b10"}, nil); err != nil {
t.Fatal(err)
}
cur, _, _ := rv.r.Of(ctx, "node-tools", res.Version)
held := versions.HeldArtifact{Ref: "node-tools:program", Seat: versions.SeatArtifacts, Name: "node-tools/program", Version: res.Version, Digest: "sha256:7c9b10"}
rv.markHeld(ctx, cur, []versions.HeldArtifact{held})
if len(said) != 1 || said[0].Artifact != "node-tools:program" || said[0].Version != res.Version {
t.Fatalf("package-published said %+v, want node-tools:program at %s from the registry's record", said, res.Version)
}
if cur, _, _ = rv.r.Of(ctx, "node-tools", res.Version); len(cur.Missing()) != 0 {
t.Errorf("the record marked nothing: missing %v", cur.Missing())
}
// Another reservation of the module, done, whose number the registry holds at another digest: withdrawn, built again at the
// next free number with a fresh digest, and published there (H-A-279).
if _, err := rv.r.Released(ctx, "node-tools", res.Version); err != nil {
t.Fatal(err)
}
asked, ended, said, registry = nil, nil, nil, []string{"0.1.0", "0.1.1", "0.1.2"}
raw, _ := json.Marshal(versions.ReservedVersion{V: 1, Module: "node-tools", Series: "0.1", Version: "0.1.1", Fingerprint: "fp2",
Artifacts: map[string]string{"node-tools:program": "sha256:7c9b10"}, BuiltAt: time.Now()})
if _, err := rv.r.Store.Create(ctx, versions.ReservedKey("node-tools", "0.1"), raw); err != nil {
t.Fatal(err)
}
rv.rebuild = func(ctx context.Context, module, fp, _ string) error {
again, err := rv.Reserve(ctx, module, "0.1", []string{"node-tools:program"}, versions.Source{Fingerprint: fp, Rebuild: true})
if err != nil {
return err
}
if err := rv.Built(ctx, module, again.Version, map[string]string{"node-tools:program": "sha256:fresh"}, nil); err != nil {
return err
}
rv.published(ctx, versions.Outcome{Name: "node-tools/program", Version: again.Version, Digest: "sha256:fresh"}, nil)
return nil
}
cur, _, _ = rv.r.Of(ctx, "node-tools", "0.1.1")
elsewhere := held
elsewhere.Version, elsewhere.Digest = "0.1.1", "sha256:83bec1"
if err := rv.movedElsewhere(ctx, cur, versions.Judged{Elsewhere: []versions.HeldArtifact{elsewhere}}); err != nil {
t.Fatal(err)
}
again, ok, _ := rv.r.Of(ctx, "node-tools", "")
if !ok || again.Version != "0.1.3" || again.Withdrawn["0.1.1"] != "fp2" || again.Artifacts["node-tools:program"] != "sha256:fresh" {
t.Fatalf("built again as %+v, want 0.1.3 with a fresh digest and 0.1.1 withdrawn", again)
}
if len(said) != 1 || said[0].Version != "0.1.3" || said[0].Digest != "sha256:fresh" {
t.Errorf("package-published said %+v, want the fresh build at 0.1.3", said)
}
if len(asked) != 1 || asked[0] != "node-tools 0.1.3" || len(ended) != 1 || ended[0] != "node-tools 0.1.1" {
t.Errorf("asked %v, ended %v: want the new number's publish asked and the old one's item ended", asked, ended)
}
raised := ""
for _, v := range fs.vals {
raised += string(v)
}
if !strings.Contains(raised, versions.VersionHeldElsewhere) || !strings.Contains(raised, "sha256:83bec1") || !strings.Contains(raised, "sha256:7c9b10") {
t.Errorf("no version-held-elsewhere naming both digests: %s", raised)
}
}
// countedReserve counts the reads of reservation keys (two tokens).
type countedReserve struct {
*memReserve
reads int
}
func (c *countedReserve) Get(ctx context.Context, key string) ([]byte, uint64, bool, error) {
if !strings.HasPrefix(key, "index.") {
c.reads++
}
return c.memReserve.Get(ctx, key)
}
// TestAPublishedThatMarksNothingIsSaidFromWhatItRead: design 47 H H-A-280 — a published whose digest no reservation holds, at a
// version many reservations share, reads only the unbuilt ones there, each once; its journal line is made from those reads with
// no second read; and the handler is told to say in progress before that pass.
func TestAPublishedThatMarksNothingIsSaidFromWhatItRead(t *testing.T) {
ctx := context.Background()
store := &countedReserve{memReserve: &memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}}
none := func(string, any) (json.RawMessage, error) { return json.Marshal(meshcatalog.VersionsAnswer{}) }
var logs []string
rv := newReservations(store, none, func() jetstream.KeyValue { return &boundsKV{keys: map[string]bool{}} },
&findings{module: builds.BuilderModule, w: &memFindings{vals: map[string][]byte{}}, logf: t.Logf, now: time.Now}, nil,
func(f string, a ...any) { logs = append(logs, fmt.Sprintf(f, a...)) })
rv.filled.Store(true)
for i := range 14 {
m := fmt.Sprintf("m%02d", i)
res, err := rv.Reserve(ctx, m, "0.1", []string{m + ":a"}, versions.Source{Fingerprint: "fp" + m})
if err != nil {
t.Fatal(err)
}
if i > 0 { // one stays unbuilt
if err := rv.Built(ctx, m, res.Version, map[string]string{m + ":a": "sha256:" + m}, nil); err != nil {
t.Fatal(err)
}
}
}
store.reads = 0
told := 0
rv.published(ctx, versions.Outcome{Name: "x", Version: "0.1.0", Digest: "sha256:none"}, func() { told++ })
if store.reads != 1 || told != 1 {
t.Errorf("%d reservation reads, in progress told %d times: want the one unbuilt read once, and in progress said before", store.reads, told)
}
if line := strings.Join(logs, "\n"); !strings.Contains(line, "kept on") {
t.Errorf("the journal says %q, want the published kept on the unbuilt reservation", line)
}
logs, store.reads = nil, 0
// A digest of a built one whose artifact is published already marks nothing: the line names it from the one read.
rv.published(ctx, versions.Outcome{Name: "m05-a", Version: "0.1.0", Digest: "sha256:m05"}, nil)
rv.published(ctx, versions.Outcome{Name: "m05-a", Version: "0.1.0", Digest: "sha256:m05"}, nil)
if store.reads != 2 || !strings.Contains(strings.Join(logs, "\n"), "m05 holds 1 built digests") || !strings.Contains(strings.Join(logs, "\n"), "14 reservations stand at it") {
t.Errorf("%d reads for two publisheds, journal %q: want one read each and the line made from it", store.reads, logs)
}
}
@@ -103,7 +103,16 @@ func (h *seatHearer) heard(ctx context.Context, m jetstream.Msg) bool {
h.pub.heard(ctx, se.seat, se.event, o)
}
if h.res != nil && se.event == versions.HeardPublished {
h.res.published(ctx, o)
// A pass over many reservations may outlast a third of the ack wait: the bus is told in progress before it (H-A-280).
h.res.published(ctx, o, func() {
if err := m.InProgress(); err != nil {
h.logf("in progress of %s not said: %v", m.Subject(), err)
}
})
}
if se.event == versions.HeardPublished && o.Kind == versions.KindPackage && h.b != nil {
// A package registry seat's published pins a package an entry names with none, at the version it carries (H-A-192).
h.b.PackagePublished(o.Name, o.Version)
}
h.ack(m)
if len(wake) > 0 {
@@ -13,6 +13,7 @@ import (
"git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
gitseat "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/gopackageregistry"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-builder/internal/build"
@@ -96,6 +97,28 @@ func (s awaitedVersions) KeysOf(ctx context.Context, filter string) ([]string, e
return out, nil
}
// publishedVersionsVia asks the Go package registry seat's verb versions for one package path (design 47 H H-A-194): its
// versions, newest first.
func publishedVersionsVia(call toolCaller) func(context.Context, string) ([]string, error) {
return func(_ context.Context, path string) ([]string, error) {
raw, err := call("seat:"+gopackageregistry.Seat+"."+gopackageregistry.VerbVersions, gopackageregistry.VersionsInput{Name: path})
if err != nil {
return nil, err
}
var a gopackageregistry.VersionsAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return nil, fmt.Errorf("%s's versions answered what is no list of versions: %w", gopackageregistry.Seat, err)
}
var out []string
for _, v := range a.Versions {
if v.Version != "" {
out = append(out, v.Version)
}
}
return out, nil
}
}
// floorVia is the floor's three sources as calls of the builder's own account (design 51 *The floor*): the seat's verb
// versions, the seat git's tags and the requirements the catalog half's entries name (A-119). A call that fails is that source
// silent.
@@ -102,7 +102,10 @@ func seed(t *testing.T, st *memStore, b builds.BuilderBuild) string {
func valueOf(t *testing.T, st *memStore, key string) builds.BuilderBuild {
t.Helper()
b, err := builds.DecodeBuilderBuild(st.vals[key])
st.mu.Lock()
raw := st.vals[key]
st.mu.Unlock()
b, err := builds.DecodeBuilderBuild(raw)
if err != nil {
t.Fatal(err)
}
@@ -13,6 +13,7 @@ import (
func TestAnEntryOfTheCatalogHalfIsTheFormTheBuilderBuildsBy(t *testing.T) {
e := meshcatalog.CatalogEntry{Module: "netcheck", Repository: "novox/mesh-catalog", Path: "modules/netcheck", Commit: "abc", Fp: "src2:f",
ManifestDigest: "sha256:m", Bases: []string{"base"}, Packages: map[string]string{"p": "1"}, Needs: []string{"n"},
Artifacts: []meshcatalog.Artifact{{Ref: "netcheck:lib", Kind: "package", Language: "go"}},
Inputs: &meshcatalog.EntryInputs{Toolchains: map[string]meshcatalog.ToolchainUsed{"go": {Version: "go1", Recipe: "1"}},
Paths: map[string][]string{"lib": {"a/b", "c"}}}}
got := ModuleOf(e)
@@ -30,4 +31,11 @@ func TestAnEntryOfTheCatalogHalfIsTheFormTheBuilderBuildsBy(t *testing.T) {
if bare := ModuleOf(meshcatalog.CatalogEntry{Module: "m"}); bare.Inputs2 != nil || bare.Fp2 != "" {
t.Errorf("ModuleOf of an entry with none = %+v, want nothing set", bare)
}
// A module with an artifact that names no paths (a Go program beside its packages) is built from its directory whole
// (ADR 0499 clauses 1 and 4): its fetch names no paths, so the program's go.mod and main package stay in the tree.
mixed := e
mixed.Artifacts = append([]meshcatalog.Artifact{{Ref: "netcheck:program", Kind: "bundle", Language: "go"}}, e.Artifacts...)
if got := ModuleOf(mixed); got.Inputs2 == nil || len(got.Inputs2.Paths) != 0 {
t.Errorf("ModuleOf of a module with a program naming no paths = %+v, want bases and no named paths", got.Inputs2)
}
}
@@ -149,6 +149,9 @@ type Reservations interface {
ReservedFor(ctx context.Context, module, fingerprint string) (versions.ReservedVersion, bool, error)
// ReleasedFor says whether a version was released for the build of fingerprint, read from the builder's own record (A-456a).
ReleasedFor(ctx context.Context, module, fingerprint string) (bool, error)
// TakenOver is the reservation of module's series that took the series over from the build of fingerprint, whose number
// it keeps withdrawn (design 47 H H-A-226), and whether one does (H-A-244).
TakenOver(ctx context.Context, module, fingerprint string) (versions.ReservedVersion, bool, error)
}
// reserves says whether a look at a trunk build is one that reserves: the build has a series of the form MAJOR.MINOR
@@ -194,7 +197,7 @@ func (b *Builder) reserve(ctx context.Context, module string, m meshcatalog.Modu
for _, t := range plan.Tasks {
refs = append(refs, module+":"+t.Artifact)
}
src := versions.Source{Repository: m.Repository, Commit: m.Commit, Fingerprint: m.Fp2, Branch: o.Branch, Revision: o.Source, Rebuild: rebuild}
src := versions.Source{Repository: m.Repository, Commit: m.Commit, Fingerprint: m.Fp2, Branch: o.Branch, Revision: o.Source, CatalogRevision: o.Revision, Rebuild: rebuild}
for _, t := range plan.Tasks {
src.GoPackage = src.GoPackage || (t.Kind == catalogue.ArtifactPackage && t.Language == "go")
}
@@ -29,8 +29,14 @@ type fakeReservations struct {
built map[string]string
sources []versions.Source
deps map[string][]meshbuilds.Dependency
next string // the version Reserve answers when set, else the series' .5
fail error // the reservation cannot be made (the catalog's versions cannot be read)
next string // the version Reserve answers when set, else the series' .5
fail error // the reservation cannot be made (the catalog's versions cannot be read)
tookBy map[string]versions.ReservedVersion // by fingerprint, the reservation that took its series over (H-A-244)
}
func (f *fakeReservations) TakenOver(_ context.Context, _, fp string) (versions.ReservedVersion, bool, error) {
v, ok := f.tookBy[fp]
return v, ok, nil
}
func (f *fakeReservations) ReleasedFor(_ context.Context, _, fp string) (bool, error) {
@@ -354,7 +360,10 @@ func (r *realReserve) Built(ctx context.Context, module, version string, digests
type reserveMap struct{ *memStore }
func (m reserveMap) KeysOf(ctx context.Context, _ string) ([]string, error) { return m.Keys(ctx) }
func (m reserveMap) KeysOf(ctx context.Context, filter string) ([]string, error) {
all, err := m.Keys(ctx)
return slices.DeleteFunc(all, func(k string) bool { return !versions.FilterMatches(filter, k) }), err // as the bus reads a filter
}
func (m reserveMap) Delete(_ context.Context, key string) error {
m.mu.Lock()
defer m.mu.Unlock()
@@ -362,10 +371,10 @@ func (m reserveMap) Delete(_ context.Context, key string) error {
return nil
}
// TestABuildAgainReservesAboveTheCatalogsHighestNotItsOwnStandingNumber: design 47 G A-490b, at the build, through the real
// reserver — a done key whose own fingerprint has an unreleased 0.1.30 standing, the catalog's highest 0.1.16, is built again
// under 0.1.17 (never 0.1.31), the standing reservation taken over.
func TestABuildAgainReservesAboveTheCatalogsHighestNotItsOwnStandingNumber(t *testing.T) {
// TestABuildAgainKeepsItsOwnStandingNumber: design 47 G A-490b as H-A-225 amends it, at the build, through the real reserver —
// a done key whose own fingerprint has an unreleased 0.1.30 standing, the catalog's highest 0.1.16, is built again under 0.1.30
// (never 0.1.31, never a new number): the run building carries the standing number until it is released.
func TestABuildAgainKeepsItsOwnStandingNumber(t *testing.T) {
r := newRig(t, goBundle)
r.mf.byDigest[mdigest('a')] = catalogue.Manifest{Module: "m", Version: "0.1", Build: &catalogue.Build{Artifacts: []catalogue.Artifact{goBundle}}}
if v := r.consider(t, "modules/m"); v.State != builds.BuildDone {
@@ -381,8 +390,8 @@ func TestABuildAgainReservesAboveTheCatalogsHighestNotItsOwnStandingNumber(t *te
r.b.Reserved = real
got := r.b.BuildAgain(context.Background(), "m", fp1, "its publish was refused", "shanks.lead", 2*time.Second)
r.b.Wait()
cur, ok, err := real.Of(context.Background(), "m", "0.1.17")
if got.Refused != "" || err != nil || !ok || cur.Fingerprint != fp1 {
t.Fatalf("answer %+v; reservation of 0.1.17 = %+v (%v, %v); want built again under 0.1.17, the catalog's highest 0.1.16 plus one", got, cur, ok, err)
cur, ok, err := real.Of(context.Background(), "m", "")
if got.Refused != "" || err != nil || !ok || cur.Fingerprint != fp1 || cur.Version != "0.1.30" {
t.Fatalf("answer %+v; reservation = %+v (%v, %v); want built again under its standing 0.1.30", got, cur, ok, err)
}
}
@@ -95,10 +95,14 @@ func theOperatorAnswers(t *testing.T, option string) {
if err != nil || h != occ.Acted {
t.Fatalf("%s: %v, %v", option, h, err)
}
for i := 0; i < 50 && option == OptionBuildOnceMore; i++ { // the build the answer starts runs on its own goroutine
r.b.Wait()
if valueOf(t, r.st, r.key).State == builds.BuildDone {
// The build the answer starts runs on its own goroutine: the builder is waited on only once that build has claimed the key
// (its start counted before its claim, read through the store's lock), never while its start may still be counted.
for i := 0; i < 50 && option == OptionBuildOnceMore; i++ {
if st := valueOf(t, r.st, r.key).State; st == builds.BuildDone {
break
} else if st != builds.BuildFailed {
r.b.Wait()
continue
}
time.Sleep(time.Millisecond)
}
@@ -5,11 +5,12 @@ import (
"fmt"
"maps"
"slices"
"strconv"
"strings"
"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
@@ -19,6 +20,17 @@ import (
// 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.
//
// **The picture holds every kept revision, not only the newest** (design 47 H H-A-205, H-A-147): an ask of a source revision
// below the newest the picture holds, whose entries the picture no longer names, asks the catalog seat's verb revision for
// its catalog revision by number, once, and is built when that kept revision is of its source and names every entry it
// asks; it never waits, since the picture only moves on. Only a revision above the newest is waited for.
//
// **An ask naming a revision is held by its number** (design 47 H H-A-222): when the picture does not name the ask's
// entries, the ask's catalog revision is read by number, and the ask is built when the catalog keeps it and it names every
// fingerprint asked, whatever the source the picture holds says (a re-pin keeps a later revision of the same source, H-A-211,
// H-A-213, so the source alone cannot say it). The source is compared only for an ask naming no revision; an ask whose
// revision the catalog does not answer and whose source is not below the picture's waits as before.
// 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
@@ -67,12 +79,68 @@ func (b *Builder) holdsRevision(branch string, source int64, entries []meshbuild
return true
}
// keptRevisionHolds answers no outcome when the catalog keeps the ask's revision (its catalog revision by number) and that
// revision names every entry of the ask (H-A-205, H-A-222); else failed or could not run, with its words.
func (b *Builder) keptRevisionHolds(ctx context.Context, run meshbuilds.StepRun, held int64) (outcome, said string) {
below := fmt.Sprintf("revision %d of %s is not named by the builder's picture, which holds source revision %d", run.Source, run.Branch, held)
if run.Source < held {
below = fmt.Sprintf("revision %d of %s is below the %d the builder's picture holds", run.Source, run.Branch, held)
}
if b.KeptRevision == nil || run.Revision <= 0 {
return meshbuilds.StepEndedOutcomeFailed, below + ", and the ask names no catalog revision to read it by"
}
source, fps, err := b.KeptRevision(ctx, run.Branch, run.Revision)
if err != nil {
b.logf("%s: %s, and the catalog's revision %d cannot be read: %v", run.Pipeline, below, run.Revision, err)
return meshbuilds.StepEndedOutcomeCouldNotRun, fmt.Sprintf("%s, and the catalog's revision %d cannot be read: %v", below, run.Revision, err)
}
// An ask names the revision and the source of one revision (H-A-218, H-A-219): a kept revision of another source is
// not the ask's.
if source != run.Source {
b.logf("%s: %s, and the catalog's revision %d is of source revision %d, the ask names %d: the step fails, nothing is built", run.Pipeline, below, run.Revision, source, run.Source)
return meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s, and the catalog's revision %d is of source revision %d, the ask names %d", below, run.Revision, source, run.Source)
}
for _, e := range run.Entries {
if fps[e.Module] != e.Fingerprint {
b.logf("%s: %s, and the catalog's revision %d names %s at %q, not %s: the step fails, nothing is built", run.Pipeline, below, run.Revision, e.Module, fps[e.Module], e.Fingerprint)
return meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s, and the catalog's revision %d names %s at %q, not %s", below, run.Revision, e.Module, fps[e.Module], e.Fingerprint)
}
}
// Each asked fingerprint is recorded as the branch's, so its build reserves its version (H-A-155) as one the picture
// took in does; what the picture heard stays as it is, so the newer fingerprint's build is not superseded.
b.mu.Lock()
for _, e := range run.Entries {
key, err := builds.BuilderBuildKey(e.Module, e.Fingerprint)
if err != nil || b.origin[key].Branch != "" {
continue
}
first := b.FirstBranch == nil || b.FirstBranch(run.Branch, e.Module)
b.trunkFP[key] = true
b.origin[key] = Origin{Branch: run.Branch, Source: run.Source, Revision: run.Revision, First: first}
}
b.mu.Unlock()
b.logf("%s: %s; the catalog keeps revision %d with its entries: the build goes on", run.Pipeline, below, run.Revision)
return "", ""
}
// 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 "", ""
}
if held, ok := b.Picture(run.Branch); !b.holdsRevision(run.Branch, run.Source, run.Entries) {
below := ok && run.Source < held
if (run.Revision > 0 && b.KeptRevision != nil) || below {
// By its number (H-A-222), whatever the source the picture holds; for an ask naming none, only below the
// picture (H-A-205). A kept revision of another source or naming other fingerprints is a mismatch the wait
// cannot mend: it fails at once; only a revision the catalog does not answer is waited for.
outcome, said := b.keptRevisionHolds(ctx, run, held)
if outcome == "" || below || outcome == meshbuilds.StepEndedOutcomeFailed {
return outcome, said
}
}
}
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)
@@ -104,13 +172,16 @@ func (b *Builder) awaitRevision(ctx context.Context, run meshbuilds.StepRun) (ou
}
}
// **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.
// **A package with no pin waits for its publish** (design 47 H H-A-192, H-A-165, H-A-183, H-A-184, H-A-185): an entry
// keeps a mesh package the registry has not published within the series its module accepts with an empty version. Its
// build, a step ask's or a lane's, first reads the versions the registry seat holds of the path (its verb versions,
// H-A-194), then waits for the registry seat's published of that package path in that series (the
// series the module's manifest names in `packages`, else the default; catalogue.Manifest.AcceptedSeries), up to
// PackageWait (the setting package-wait-minutes), and pins the version that event carries; the builder never derives a
// pin (no release number of the module that holds the package). Past the bound the build 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.
// DefaultPackageWait is the bound of a build's wait for a package's publish, its setting package-wait-minutes' default.
const DefaultPackageWait = 10 * time.Minute
func (b *Builder) packageWait() time.Duration {
@@ -120,91 +191,152 @@ func (b *Builder) packageWait() time.Duration {
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) {
// PackagePublished takes the Go package registry seat's published of one package path in (its name and the version the
// event carries, H-A-192): the newest published in the version's series is kept, and a build waiting for the package
// wakes. A version that is no MAJOR.MINOR.PATCH (a group's tagged version) pins nothing.
func (b *Builder) PackagePublished(path, version string) {
v := strings.TrimPrefix(version, "v")
series, ok := seriesOfVersion(v)
if path == "" || !ok {
return
}
b.init()
b.mu.Lock()
b.releases[module] = version
in := b.publishedPins[path]
if in == nil {
in = map[string]string{}
b.publishedPins[path] = in
}
if old := in[series]; old == "" || compareVersions(v, old) > 0 {
in[series] = v
}
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 ""
}
// publishedPin is the pin the registry seat's published gave the package path in the series, as Go names it; "" for none.
func (b *Builder) publishedPin(path, series string) string {
b.mu.Lock()
v := b.releases[module]
v := b.publishedPins[path][series]
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) {
// awaitPublished fills each package of packages with no pin from the published of its path within the series the manifest
// with this digest accepts, waiting for one (H-A-192, H-A-165). It answers the packages with every pin, or an outcome and
// its words: failed past the bound naming the package, could not run when the manifest cannot be read or the builder stops.
func (b *Builder) awaitPublished(ctx context.Context, module, fp, digest string, packages map[string]string) (map[string]string, string, string) {
var unpinned []string
for p, v := range entry.Packages {
for p, v := range packages {
if v == "" {
unpinned = append(unpinned, p)
}
}
if len(unpinned) == 0 {
return "", ""
return packages, "", ""
}
slices.Sort(unpinned)
if b.Manifests == nil {
return nil, meshbuilds.StepEndedOutcomeCouldNotRun, fmt.Sprintf("the series %s accepts of %s cannot be read: no manifests", module, unpinned[0])
}
man, err := b.Manifests.Manifest(ctx, digest)
if err != nil {
return nil, meshbuilds.StepEndedOutcomeCouldNotRun, fmt.Sprintf("the series %s accepts of %s cannot be read: its manifest %s: %v", module, unpinned[0], digest, err)
}
// What the registry seat holds is read once before the wait (H-A-194): the publishes heard are a cache of it.
for _, p := range unpinned {
if b.PublishedVersions == nil || b.publishedPin(p, man.AcceptedSeries(p)) != "" {
continue
}
vs, err := b.PublishedVersions(ctx, p)
if err != nil {
b.logf("%s at %s: the versions the registry seat holds of %s cannot be read, so the build waits for its publish: %v", module, fp, p, err)
continue
}
for _, v := range vs {
b.PackagePublished(p, v)
}
}
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 := ""
pins := map[string]string{}
missing, missingSeries := "", ""
for _, p := range unpinned {
if pins[p] == "" {
pins[p] = b.releaseOf(ctx, p)
}
series := man.AcceptedSeries(p)
pins[p] = b.publishedPin(p, series)
if pins[p] == "" && missing == "" {
missing = p
missing, missingSeries = p, series
}
}
if missing == "" {
packages := maps.Clone(entry.Packages)
maps.Copy(packages, pins)
entry.Packages = packages
out := maps.Clone(packages)
maps.Copy(out, pins)
if told {
b.logf("%s at %s: every package it names has a released version: built with %v", entry.Module, entry.Fp, pins)
b.logf("%s at %s: every package it names is published: built with %v", module, fp, pins)
}
return "", ""
return out, "", ""
}
notReleased := fmt.Sprintf("package %s has no released version", missing)
notReleased := fmt.Sprintf("package %s has no released version in the series %s", missing, missingSeries)
if !told {
b.logf("%s at %s: %s yet: the ask waits for its release, at most %s", entry.Module, entry.Fp, notReleased, bound)
b.logf("%s at %s: %s yet: the build waits for its publish, at most %s", module, 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"
return nil, 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)
b.logf("%s at %s: %s within %s: the build fails, nothing is built", module, fp, notReleased, bound)
return nil, meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s within %s", notReleased, bound)
}
}
}
// seriesOfVersion is a MAJOR.MINOR.PATCH version's series, MAJOR.MINOR; false for any other form.
func seriesOfVersion(v string) (string, bool) {
if _, ok := versionParts(v); !ok {
return "", false
}
major, rest, _ := strings.Cut(v, ".")
minor, _, _ := strings.Cut(rest, ".")
return major + "." + minor, true
}
// versionParts are a MAJOR.MINOR.PATCH version's numbers; false for any other form.
func versionParts(v string) ([3]int, bool) {
var out [3]int
parts := strings.Split(v, ".")
if len(parts) != 3 {
return out, false
}
for i, p := range parts {
n, err := strconv.Atoi(p)
if err != nil || n < 0 {
return out, false
}
out[i] = n
}
return out, true
}
// compareVersions orders two MAJOR.MINOR.PATCH versions numerically.
func compareVersions(a, b string) int {
x, _ := versionParts(a)
y, _ := versionParts(b)
for i := range x {
if x[i] != y[i] {
return x[i] - y[i]
}
}
return 0
}
@@ -110,14 +110,24 @@ type Builder struct {
// Picture answers the source revision the builder's picture of a watched branch holds, false while it holds none (design 47
// H H-A-155, H-A-141): a step ask naming a newer one waits for it. Nil waits for nothing.
Picture func(branch string) (source int64, held bool)
// KeptRevision asks the catalog seat's verb revision for one kept revision of a branch by its number (design 47 H
// H-A-205, H-A-147): the source revision it was taken in from and the fingerprint of each module it names. A step ask of
// a source revision below the newest the picture holds is built when that kept revision names its entries. Nil reads none.
KeptRevision func(ctx context.Context, branch string, revision int64) (source int64, fingerprints map[string]string, err error)
// FirstBranch says whether branch is the first watched branch of the module's registration, the one whose builds reserve
// a version (design 47 G §371): an ask admitted by its kept revision is recorded as that branch's (H-A-205, H-A-155). Nil
// takes every branch as the first, as an origin never heard is.
FirstBranch func(branch, module string) bool
// RevisionWait bounds a step ask's wait for its revision, its setting revision-wait-minutes (H-A-156); DefaultRevisionWait
// when 0.
RevisionWait time.Duration
// PackageWait bounds a step ask's wait for the release of a package its entry names with no pin, its setting
// package-wait-minutes (H-A-165); DefaultPackageWait when 0. NewestReleased reads the newest version the builder's
// record of releases keeps for a module; nil reads none, and only a release heard (VersionReleased) gives a pin.
PackageWait time.Duration
NewestReleased func(ctx context.Context, module string) (version string, found bool, err error)
// PackageWait bounds a build's wait for the publish of a package its entry names with no pin, its setting
// package-wait-minutes (H-A-165); DefaultPackageWait when 0. Only a registry seat's published heard (PackagePublished)
// gives a pin (H-A-192).
PackageWait time.Duration
// PublishedVersions asks the Go package registry seat's verb versions for one package path, its versions newest first
// (H-A-194): read once before a build waits for that package. Nil reads none.
PublishedVersions func(ctx context.Context, path string) ([]string, error)
// Forms answers what each node's engine states it reads (ADR 0618 §2, ADR 0624 §1): present, the nodes whose engine
// answered when last asked, and counted, every node the assignments names, present or away, a node with no statement
// stating nothing (the baseline's first forms). A done key names each artifact in the forms these keep, the oldest in
@@ -162,8 +172,9 @@ type Builder struct {
builds map[string]context.CancelCauseFunc
// moved is closed and made again at each entry the picture takes in or drops: the step asks waiting for a revision wake.
moved chan struct{}
// releases are the versions heard released, by module (VersionReleased): a package with no pin waits for one.
releases map[string]string
// publishedPins are the newest version a registry seat said published, by package path and series (PackagePublished):
// a package with no pin waits for one (H-A-192).
publishedPins map[string]map[string]string
}
type planned struct {
@@ -194,7 +205,7 @@ func (b *Builder) init() {
b.hands, b.events = map[string]*handWatch{}, map[string]bool{}
b.builds = map[string]context.CancelCauseFunc{}
b.moved = make(chan struct{})
b.releases = map[string]string{}
b.publishedPins = map[string]map[string]string{}
})
}
@@ -226,7 +237,9 @@ func (b *Builder) Module(ctx context.Context, key string, value []byte) {
type Origin struct {
Branch string
Source int64
First bool
// Revision is the catalog revision number a step ask of the build named (design 47 H H-A-218), 0 until one did.
Revision int64
First bool
}
// Entry takes the catalog graph entry of one module on one watched branch in (design 47 G §348, §614) and builds its
@@ -253,6 +266,23 @@ func (b *Builder) EntryGone(branch string, first bool, module string) {
}
}
// Withdraw ends the running build of module's fingerprint, superseded, with why (design 47 H H-A-225, ADR 0664 §4): its key
// fails "withdrawn" and its asks are withdrawn from the build seats. A fingerprint with no build running is left.
func (b *Builder) Withdraw(module, fingerprint, why string) {
key, err := builds.BuilderBuildKey(module, fingerprint)
if err != nil {
return
}
b.init()
b.mu.Lock()
withdraw := b.builds[key]
b.mu.Unlock()
if withdraw != nil {
b.logf("%s at %s: the build is withdrawn: %s", module, fingerprint, why)
withdraw(buildrun.Withdrawn{Why: why})
}
}
func (b *Builder) take(ctx context.Context, o Origin, key string, m meshcatalog.ModulesByModuleValue, e []meshcatalog.Edge) {
b.mu.Lock()
hk := o.Branch + "\x00" + key
@@ -285,16 +315,19 @@ func (b *Builder) take(ctx context.Context, o Origin, key string, m meshcatalog.
// ModuleOf is a catalog entry in the form the builder builds by: its fingerprint, manifest digest, source (repository,
// directory, commit; no source stamp, design 47 H H-A-48), the toolchains its fingerprint was computed with, the bases it is
// built against, its packages and needs, and the named paths of its artifacts.
// built against, its packages and needs, and the named paths of its artifacts when every artifact names them.
func ModuleOf(e meshcatalog.CatalogEntry) meshcatalog.ModulesByModuleValue {
m := meshcatalog.ModulesByModuleValue{Repository: e.Repository, Path: e.Path, Commit: e.Commit, Fp2: e.Fp, None2: e.None,
Manifest: meshcatalog.BareManifestDigest(e.ManifestDigest), Packages: e.Packages, Needs: e.Needs}
Manifest: meshcatalogclient.BareManifestDigest(e.ManifestDigest), Packages: e.Packages, Needs: e.Needs}
if len(e.Bases) > 0 {
m.Inputs2 = &meshcatalog.ModulesByModuleValueInputs2{Bases: e.Bases}
}
if in := e.Inputs; in != nil {
m.Toolchains, m.Problems = in.Toolchains, in.Problems
if len(in.Paths) > 0 {
// Only a module whose every artifact names its paths is built from those alone (ADR 0499 clauses 1, 2 and 4): an
// artifact without paths, such as a Go program, keeps its module's directory as its build source, so a module
// with one names no paths and its fetch keeps the directory whole.
if len(in.Paths) > 0 && everyArtifactNamesPaths(e) {
if m.Inputs2 == nil {
m.Inputs2 = &meshcatalog.ModulesByModuleValueInputs2{}
}
@@ -309,6 +342,20 @@ func ModuleOf(e meshcatalog.CatalogEntry) meshcatalog.ModulesByModuleValue {
return m
}
// everyArtifactNamesPaths is whether the entry names artifacts and the named paths of each, by its reference or its name.
func everyArtifactNamesPaths(e meshcatalog.CatalogEntry) bool {
if len(e.Artifacts) == 0 || e.Inputs == nil {
return false
}
for _, a := range e.Artifacts {
_, name, _ := strings.Cut(a.Ref, ":")
if len(e.Inputs.Paths[a.Ref]) == 0 && len(e.Inputs.Paths[name]) == 0 {
return false
}
}
return true
}
// originOf is the catalog revision the entry of a build key came from; a key no entry named is of the first branch, as a build
// of the trunk's value was before branches were watched.
func (b *Builder) originOf(key string) Origin {
@@ -677,8 +724,9 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
var reserved versions.ReservedVersion
hasReserved := false
if rebuild && cl.Build.State == builds.BuildBuilding {
// Reserved afresh, above the highest the catalog's versions answers, taking over the older unreleased reservation of this
// fingerprint (A-455), never its standing number kept (A-490b); the build's own publish then runs.
// Reserved as A-490b amended by H-A-225 has it: this fingerprint's standing reservation is kept while it is unreleased
// and above the highest the catalog's versions answers, else the next above that highest is taken (A-455); the build's
// own publish then runs.
if b.Reserved.Filled() {
reserved, hasReserved = b.reserve(ctx, module, m, plan, b.originOf(key), true)
}
@@ -813,6 +861,7 @@ type lane struct {
tcVersion string // and the version it ran
kept string // the digest of the artifact the build node kept instead of storing it (BuildAnswer.Kept), else empty
outOfStep []string // the generated files its build module's compare found out of step, passed or failed
pins map[string]string // the mesh packages' versions its Go ask was built with (H-A-207)
err error
}
@@ -962,7 +1011,7 @@ func (b *Builder) build(ctx context.Context, module string, m meshcatalog.Module
used = nil
}
done := builds.BuilderBuild{State: builds.BuildDone, By: b.Claimer.By, Manifest: m.Manifest, Step: step, Artifacts: artifacts, Toolchains: used,
Imports: importsOf(lanes), Needs: forms.Current.Needs(artifacts)} // the forms it is written in (ADR 0618 §1)
Imports: importsOf(lanes), Needs: forms.Current.Needs(artifacts), Packages: pinsOf(lanes)} // the forms it is written in (ADR 0618 §1)
for _, l := range lanes {
if l.kept != "" {
done.KeptOn = l.node // design 47 G §671: the build node that keeps the build
@@ -1112,11 +1161,19 @@ func (b *Builder) runLane(ctx context.Context, l *lane, repository string, m mes
ask := sdkstep.StepAsk{ID: sdkstep.NewID(), Kind: kind, Language: language, Asker: b.OwnModule, At: time.Now(), Version: l.version, Build: job}
if language == sdkstep.AskGo && job.Fetch != nil && len(m.Packages) > 0 {
// The versions of the mesh packages the fingerprint was computed with (novox/hq ADR 0573 §2): the build module writes
// them into the workspace, whatever the repository's go.mod names.
ask.Packages = maps.Clone(m.Packages)
// them into the workspace, whatever the repository's go.mod names. A package the entry names with no pin waits for
// its publish and is built with the version that publish carries; past the bound the lane fails naming it, and no
// ask is put (H-A-192, H-A-165).
pinned, outcome, said := b.awaitPublished(ctx, module, m.Fp2, m.Manifest, m.Packages)
if outcome != "" {
l.err = errors.New(said)
return
}
ask.Packages = maps.Clone(pinned)
for _, fb := range req.Builds {
delete(ask.Packages, fb.Package) // a package `builds` names is named in neither packages nor package (§465)
}
l.pins = maps.Clone(ask.Packages) // kept with the done key, so its step's end reports them (H-A-207)
}
if id := asked.resume(language); id != "" {
ask.ID = id // put before this builder started again: the stream holds it, or a node already ran it
@@ -1299,6 +1356,20 @@ func (b *Builder) takeOutOfStep(key string) []string {
// importsOf are the mesh packages the lanes' programs import, as their build modules answered them (novox/hq ADR 0593
// §2): sorted and each once; nil when none answered any. A lane kept from a prior build answered none, so a build that
// kept one reports only what it built.
// pinsOf is the mesh packages' versions the lanes were built with (H-A-207), nil when none was pinned.
func pinsOf(lanes []*lane) map[string]string {
var out map[string]string
for _, l := range lanes {
for p, v := range l.pins {
if out == nil {
out = map[string]string{}
}
out[p] = v
}
}
return out
}
func importsOf(lanes []*lane) []string {
seen := map[string]bool{}
for _, l := range lanes {
@@ -327,15 +327,50 @@ func TestABundleAndAnArchiveAreBuiltOnOneNodeAndDone(t *testing.T) { // 1607/AC7
}
}
// H-A-225 (ADR 0664 §4): a build withdrawn while it runs (its reservation taken over by another fingerprint) ends failed
// "withdrawn" with why, so it never publishes under the dropped number; a fingerprint with no build running is left.
func TestAWithdrawnBuildEndsWithdrawn(t *testing.T) {
r := newRig(t, goBundle)
asked, release := make(chan struct{}), make(chan struct{})
answer := r.answer
r.asks.Answer = func(a buildstep.StepAsk) buildstep.Step {
close(asked)
<-release
return answer(a)
}
r.b.Withdraw("m", fp1, "nothing runs yet") // left: no build of it runs
data, err := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Repository: "novox/mesh-catalog", Commit: "7a74cee83f88e6585a5511c3cc53bdf0f5303d20",
Fp2: fp1, Manifest: mdigest('a'), Path: "modules/m", Toolchains: CatalogToolchains(agreedToolchains)})
if err != nil {
t.Fatal(err)
}
r.b.Module(context.Background(), "m", data)
select {
case <-asked:
case <-time.After(5 * time.Second):
t.Fatal("no ask was put")
}
r.b.Withdraw("m", fp1, "its reservation 0.1.3 was taken over by the build of src2:b, which reserves 0.1.4")
close(release)
r.b.Wait()
if v := valueOf(t, r.st, r.key); v.State != builds.BuildFailed || !strings.Contains(v.Error, "withdrawn: its reservation 0.1.3 was taken over") {
t.Fatalf("the key = %+v, want failed withdrawn naming the take-over", v)
}
}
// 1887/AC1, AC2: a trunk fingerprint with no key is one ask on the Go seat's delivery stream, named in the building key
// before it is put, and the builder calls no node; the step a node wrote for it makes the key done naming its reference.
func TestATrunkFingerprintIsOneAskOnTheDeliveryStream(t *testing.T) {
r := newRig(t, goBundle)
r.asks.Answer = nil // no node has pulled it yet
// Issue 1585 (ADR 0573 §2): the ask carries the package versions the fingerprint was computed with.
sdk := buildstep.PackageVersions{"git.novox.be/novox/mesh-sdk/go": hex40('5')}
// Issue 1585 (ADR 0573 §2): the ask carries the module's pins; a package the entry keeps with no version (none
// published, design 47 H-A-161) is pinned at the version the registry seat's published carries (H-A-192), never
// asked without it.
r.b.PackagePublished("git.novox.be/novox/mesh-contracts/go/seats/x", "v0.1.7")
sdk := buildstep.PackageVersions{"git.novox.be/novox/mesh-sdk/go": "v0.1.20", "git.novox.be/novox/mesh-contracts/go/seats/x": "v0.1.7"}
data, err := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Repository: "novox/mesh-catalog", Commit: "7a74cee83f88e6585a5511c3cc53bdf0f5303d20",
Fp2: fp1, Manifest: mdigest('a'), Path: "modules/m", Toolchains: CatalogToolchains(agreedToolchains), Packages: sdk})
Fp2: fp1, Manifest: mdigest('a'), Path: "modules/m", Toolchains: CatalogToolchains(agreedToolchains),
Packages: map[string]string{"git.novox.be/novox/mesh-sdk/go": "v0.1.20", "git.novox.be/novox/mesh-contracts/go/seats/x": ""}})
if err != nil {
t.Fatal(err)
}
@@ -6,6 +6,7 @@ import (
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"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/meshbuilds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
)
@@ -38,9 +39,21 @@ func (b *Builder) BuildStep(ctx context.Context, run meshbuilds.StepRun) meshbui
if outcome, said := b.awaitRevision(ctx, run); outcome != "" {
return finish(outcome, said)
}
b.askedRevision(run)
var failed []string
for _, e := range run.Entries {
outcome, said := b.buildEntry(ctx, e)
var pins map[string]string
outcome, said := b.buildEntry(ctx, e, &pins)
// The end reports the pins each entry was built with, so the runner asks its held test steps with them (H-A-207).
for path, version := range pins {
if version == "" {
continue
}
if end.Packages == nil {
end.Packages = map[string]string{}
}
end.Packages[path] = version
}
switch outcome {
case meshbuilds.StepEndedOutcomeCouldNotRun:
return finish(outcome, said)
@@ -54,8 +67,30 @@ func (b *Builder) BuildStep(ctx context.Context, run meshbuilds.StepRun) meshbui
return finish(meshbuilds.StepEndedOutcomePassed, "")
}
// buildEntry builds one entry at its fingerprint and waits for its end.
func (b *Builder) buildEntry(ctx context.Context, e meshbuilds.BuildEntry) (outcome, said string) {
// askedRevision records on the origin of each entry of run the catalog revision the ask names (design 47 H H-A-218), where
// the origin is of the ask's branch and source revision: the version reserved for its build names it, and so does its
// package-published, so the runner finds the publishing pipeline by branch and revision.
func (b *Builder) askedRevision(run meshbuilds.StepRun) {
if run.Revision <= 0 {
return
}
b.mu.Lock()
defer b.mu.Unlock()
for _, e := range run.Entries {
key, err := builds.BuilderBuildKey(e.Module, e.Fingerprint)
if err != nil {
continue
}
if o, ok := b.origin[key]; ok && o.Branch == run.Branch && o.Source == run.Source {
o.Revision = run.Revision
b.origin[key] = o
}
}
}
// buildEntry builds one entry at its fingerprint and waits for its end; pins is set, when it is done, to the pins its
// done key keeps it was built with, the registry's included (H-A-207).
func (b *Builder) buildEntry(ctx context.Context, e meshbuilds.BuildEntry, pins *map[string]string) (outcome, said string) {
entry, err := b.StepEntry(ctx, e.Fingerprint)
if err != nil {
return meshbuilds.StepEndedOutcomeCouldNotRun, fmt.Sprintf("the entry %s at %s cannot be read: %v", e.Module, e.Fingerprint, err)
@@ -63,10 +98,12 @@ func (b *Builder) buildEntry(ctx context.Context, e meshbuilds.BuildEntry) (outc
if entry.Module != e.Module || (e.Commit != "" && entry.Commit != e.Commit) {
return meshbuilds.StepEndedOutcomeCouldNotRun, fmt.Sprintf("the entry of %s at %s is of %s at %s", e.Module, e.Fingerprint, entry.Module, entry.Commit)
}
// A package the entry names with no pin is built against its release, waited for (H-A-165).
if outcome, said := b.awaitPins(ctx, &entry); outcome != "" {
// A package the entry names with no pin is built against its publish, waited for (H-A-192, H-A-165).
pinned, outcome, said := b.awaitPublished(ctx, entry.Module, entry.Fp, meshcatalogclient.BareManifestDigest(entry.ManifestDigest), entry.Packages)
if outcome != "" {
return outcome, said
}
entry.Packages = pinned
key, err := builds.BuilderBuildKey(entry.Module, entry.Fp)
if err != nil {
return meshbuilds.StepEndedOutcomeCouldNotRun, err.Error()
@@ -75,16 +112,19 @@ func (b *Builder) buildEntry(ctx context.Context, e meshbuilds.BuildEntry) (outc
defer b.dropEnd(key, ended)
if done, failedWords, found := b.keyEnd(ctx, key); found {
if done {
// A key done before reports the pins it was built with, kept with it, never the ones a publish gives now.
*pins = b.keptPins(ctx, key)
return b.passedWithItsVersion(ctx, entry)
}
return meshbuilds.StepEndedOutcomeFailed, failedWords
}
m := meshcatalog.ModulesByModuleValue{Repository: entry.Repository, Commit: entry.Commit, Fp2: entry.Fp, Manifest: meshcatalog.BareManifestDigest(entry.ManifestDigest), Path: entry.Path,
Toolchains: CatalogToolchains(b.agreedFor(ctx, meshcatalog.BareManifestDigest(entry.ManifestDigest))), Packages: entry.Packages}
m := meshcatalog.ModulesByModuleValue{Repository: entry.Repository, Commit: entry.Commit, Fp2: entry.Fp, Manifest: meshcatalogclient.BareManifestDigest(entry.ManifestDigest), Path: entry.Path,
Toolchains: CatalogToolchains(b.agreedFor(ctx, meshcatalogclient.BareManifestDigest(entry.ManifestDigest))), Packages: entry.Packages}
b.consider(ctx, entry.Module, m)
select {
case log := <-ended:
if log.Outcome == builds.BuildDone {
*pins = b.keptPins(ctx, key)
return b.passedWithItsVersion(ctx, entry)
}
return meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s at %s: %s %s", log.Module, log.FP, log.Outcome, log.Error)
@@ -96,7 +136,8 @@ func (b *Builder) buildEntry(ctx context.Context, e meshbuilds.BuildEntry) (outc
// passedWithItsVersion is the verdict of a build that ended done (design 47 G A-456): a build that reserves a version (a build
// of the first watched branch's trunk, with a MAJOR.MINOR series and artifacts) passes only when a version is reserved for its
// fingerprint; one that ended done with none fails loudly, naming builder_reserve_done, so no pipeline says passed for a build
// that can never be released. A build that reserves none (a candidate's, a series of before G) passes as it did.
// that can never be released, and one whose series another fingerprint took over fails saying it is stale, naming that
// fingerprint and its version (design 47 H H-A-244). A build that reserves none (a candidate's, a series of before G) passes as it did.
func (b *Builder) passedWithItsVersion(ctx context.Context, entry meshcatalog.CatalogEntry) (outcome, said string) {
if b.Reserved == nil {
return meshbuilds.StepEndedOutcomePassed, ""
@@ -111,7 +152,7 @@ func (b *Builder) passedWithItsVersion(ctx context.Context, entry meshcatalog.Ca
if !reserving {
return meshbuilds.StepEndedOutcomePassed, ""
}
plan, planErr, _ := b.planOf(ctx, meshcatalog.BareManifestDigest(entry.ManifestDigest))
plan, planErr, _ := b.planOf(ctx, meshcatalogclient.BareManifestDigest(entry.ManifestDigest))
switch {
case planErr != nil:
return meshbuilds.StepEndedOutcomeCouldNotRun, fmt.Sprintf("%s at %s: the plan cannot be read to judge its version: %v", entry.Module, entry.Fp, planErr)
@@ -128,11 +169,31 @@ func (b *Builder) passedWithItsVersion(ctx context.Context, entry meshcatalog.Ca
} else if released {
return meshbuilds.StepEndedOutcomePassed, "" // a released build counts as reserved (A-456a)
}
if by, took, err := b.Reserved.TakenOver(ctx, entry.Module, entry.Fp); err != nil {
return meshbuilds.StepEndedOutcomeCouldNotRun, fmt.Sprintf("%s at %s: the reservations cannot be read: %v", entry.Module, entry.Fp, err)
} else if took {
// H-A-244 (2): the series was taken over by a newer fingerprint, whose number it carries now: the build is stale.
return meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s: built at %s but its series moved to %s %s: stale", entry.Module, entry.Fp, by.Fingerprint, by.Version)
}
return meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s: built at %s, but no version is reserved for it; builder_reserve_done reserves one for the done build", entry.Module, entry.Fp)
}
return meshbuilds.StepEndedOutcomePassed, ""
}
// keptPins are the pins a done key keeps it was built with (H-A-207); none when it keeps none or cannot be read, so the
// runner ends the steps that waited for them could not run, loud.
func (b *Builder) keptPins(ctx context.Context, key string) map[string]string {
raw, _, ok, err := b.Claimer.Store.Get(ctx, key)
if err != nil || !ok {
return nil
}
v, err := builds.DecodeBuilderBuild(raw)
if err != nil || v.State != builds.BuildDone {
return nil
}
return v.Packages
}
// keyEnd reads the build key: whether it is done, and its error when it failed for good; found only for a key that has ended.
func (b *Builder) keyEnd(ctx context.Context, key string) (done bool, failed string, found bool) {
raw, _, ok, err := b.Claimer.Store.Get(ctx, key)
@@ -3,9 +3,10 @@ package build
import (
"context"
"errors"
"fmt"
"reflect"
"slices"
"strings"
"sync"
"sync/atomic"
"testing"
"time"
@@ -88,18 +89,23 @@ func TestABuildStepPassesAReservingBuildOnlyWithItsReservedVersion(t *testing.T)
for _, c := range []struct {
name, version string
reserve, released, unreadable bool
takenOver bool
want, said string
}{
{"no version reserved", "0.1", false, false, false, meshbuilds.StepEndedOutcomeFailed, "built at " + fp1 + ", but no version is reserved for it"},
{"a version reserved", "0.1", true, false, false, meshbuilds.StepEndedOutcomePassed, ""},
{"a released build whose reservation is gone", "0.1", false, true, false, meshbuilds.StepEndedOutcomePassed, ""},
{"the plan cannot be read", "0.1", false, false, true, meshbuilds.StepEndedOutcomeCouldNotRun, "plan cannot be read"},
{"a series of before G", "1", false, false, false, meshbuilds.StepEndedOutcomePassed, ""},
{"no version reserved", "0.1", false, false, false, false, meshbuilds.StepEndedOutcomeFailed, "built at " + fp1 + ", but no version is reserved for it"},
{"H-A-244: its series was taken over by a newer fingerprint", "0.1", false, false, false, true, meshbuilds.StepEndedOutcomeFailed, "m: built at " + fp1 + " but its series moved to " + fp2 + " 0.1.7: stale"},
{"a version reserved", "0.1", true, false, false, false, meshbuilds.StepEndedOutcomePassed, ""},
{"a released build whose reservation is gone", "0.1", false, true, false, false, meshbuilds.StepEndedOutcomePassed, ""},
{"the plan cannot be read", "0.1", false, false, true, false, meshbuilds.StepEndedOutcomeCouldNotRun, "plan cannot be read"},
{"a series of before G", "1", false, false, false, false, meshbuilds.StepEndedOutcomePassed, ""},
} {
t.Run(c.name, func(t *testing.T) {
r := newRig(t, goBundle)
r.mf.byDigest[mdigest('a')] = catalogue.Manifest{Module: "m", Version: c.version, Build: &catalogue.Build{Artifacts: []catalogue.Artifact{goBundle}}}
res := &fakeReservations{filled: true, released: map[string]bool{fp1: c.released}}
if c.takenOver {
res.tookBy = map[string]versions.ReservedVersion{fp1: {Module: "m", Series: "0.1", Version: "0.1.7", Fingerprint: fp2}}
}
if v := r.consider(t, "modules/m"); v.State != builds.BuildDone { // built while the builder reserved nothing, as the live key was
t.Fatalf("build = %+v, want done", v)
}
@@ -111,86 +117,192 @@ func TestABuildStepPassesAReservingBuildOnlyWithItsReservedVersion(t *testing.T)
return meshcatalog.CatalogEntry{Module: "m", Repository: "novox/m", Commit: "c1", Fp: fp1, ManifestDigest: digestOf(c.unreadable), Path: "modules/m"}, nil
}
end := r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.1.m", Step: meshbuilds.StepRunStepBuild, Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}})
if end.Outcome != c.want || !strings.Contains(end.Said, c.said) || (c.want == meshbuilds.StepEndedOutcomeFailed && !strings.Contains(end.Said, "builder_reserve_done")) {
if end.Outcome != c.want || !strings.Contains(end.Said, c.said) || (c.want == meshbuilds.StepEndedOutcomeFailed && strings.Contains(end.Said, "builder_reserve_done") == c.takenOver) {
t.Errorf("end = %+v, want %s saying %q", end, c.want, c.said)
}
})
}
t.Run("H-A-155: an ask waits for the picture to take its revision in, then builds with its version reserved", aStepAskWaitsForItsRevision)
t.Run("H-A-155: past the bound the ask fails naming its revision, and nothing is built", aStepAskPastItsRevisionBoundFails)
t.Run("H-A-205: an ask of a revision below the picture's newest is read by number and built", anOlderKeptRevisionIsReadByNumber)
t.Run("H-A-162: a revision held that changes no entry wakes the ask", aRevisionHeldWakesTheAsk)
t.Run("H-A-165: a package with no pin waits for its release and is built with it", aPackageWithNoPinWaitsForItsRelease)
t.Run("H-A-165: past its bound a package with no release fails the step", aPackageWithNoReleaseFailsPastItsBound)
t.Run("H-A-192: a lane waits for an unpinned package's publish and fails past its bound", aLaneWaitsForAnUnpinnedPackage)
t.Run("H-A-194: what the registry seat holds pins the package before any wait", theSeatsVersionsPinBeforeTheWait)
}
// unpinnedRig is a rig whose step entry m names the package x with no version, built by the module contracts.
func unpinnedRig(t *testing.T) (*rig, *fakeReservations) {
// unpinnedRig is a rig whose step entry m names the package x with no version. Its manifest names no `packages`, so it
// accepts x in the default series 0.1. waiting is told when a build starts its wait for a package's publish.
func unpinnedRig(t *testing.T) (*rig, meshcatalog.CatalogEntry, <-chan struct{}) {
var held atomic.Int64
r, res, entry := revisionRig(t, &held, make(chan struct{}, 1))
r, _, entry := revisionRig(t, &held, make(chan struct{}, 1))
r.b.Picture = nil // no revision to wait for here
entry.Packages = map[string]string{"git.novox.be/novox/mesh-contracts/go/seats/x": "", "git.novox.be/novox/mesh-sdk/go": "v0.1.20"}
entry.Packages = map[string]string{unpinnedX: "", "git.novox.be/novox/mesh-sdk/go": "v0.1.20"}
r.b.StepEntry = func(context.Context, string) (meshcatalog.CatalogEntry, error) { return entry, nil }
r.b.Members = func(_ context.Context, pkg string) (string, string, bool, error) {
return "contracts", "contracts:x", pkg == "git.novox.be/novox/mesh-contracts/go/seats/x", nil
waiting := make(chan struct{}, 1)
r.b.Logf = func(format string, args ...any) {
t.Logf(format, args...)
if strings.Contains(fmt.Sprintf(format, args...), "waits for its publish") {
select {
case waiting <- struct{}{}:
default:
}
}
}
return r, res
return r, entry, waiting
}
func aPackageWithNoPinWaitsForItsRelease(t *testing.T) {
r, _ := unpinnedRig(t)
var once sync.Once
looked := make(chan struct{})
r.b.NewestReleased = func(context.Context, string) (string, bool, error) { // the record holds none yet
once.Do(func() { close(looked) })
return "", false, nil
const unpinnedX = "git.novox.be/novox/mesh-contracts/go/seats/x"
// awaitWaiting fails the test unless the build started its wait before ended said anything.
func awaitWaiting[T any](t *testing.T, waiting <-chan struct{}, ended <-chan T) {
t.Helper()
select {
case <-waiting:
case end := <-ended:
t.Fatalf("the build ended before the package was published: %+v", end)
case <-time.After(5 * time.Second):
t.Fatal("the build never waited for the package's publish")
}
}
// H-A-192: the pin is the version the registry seat's published carries for the path in the accepted series; a publish in
// another series and the module's release number pin nothing.
func aPackageWithNoPinWaitsForItsRelease(t *testing.T) {
r, _, waiting := unpinnedRig(t)
r.b.PackagePublished(unpinnedX, "v0.2.9") // another series than the 0.1 the module accepts: no pin
r.b.PackagePublished(unpinnedX, "0.1.4-feat-x.2") // a group's tagged version: no pin
ended := make(chan meshbuilds.StepEnded, 1)
go func() {
ended <- r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.9.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Source: 41,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}})
}()
select {
case <-looked:
case end := <-ended:
t.Fatalf("the ask ended before the package was released: %+v, asks %+v", end, r.asks.Asks())
case <-time.After(5 * time.Second):
t.Fatal("the ask never looked for the package's release")
}
awaitWaiting(t, waiting, ended)
if _, ok := r.st.vals[r.key]; ok {
t.Fatal("the build was made before the package had a release")
t.Fatal("the build was made before the package was published")
}
r.b.VersionReleased("contracts", "0.1.3")
r.b.PackagePublished(unpinnedX, "v0.1.3")
var end meshbuilds.StepEnded
select {
case end = <-ended:
case <-time.After(5 * time.Second):
t.Fatal("the release did not wake the ask")
t.Fatal("the publish did not wake the ask")
}
r.b.Wait()
asks := r.asks.Asks()
if end.Outcome != meshbuilds.StepEndedOutcomePassed || len(asks) == 0 ||
!reflect.DeepEqual(asks[0].Packages, buildstep.PackageVersions{"git.novox.be/novox/mesh-contracts/go/seats/x": "v0.1.3", "git.novox.be/novox/mesh-sdk/go": "v0.1.20"}) {
!reflect.DeepEqual(asks[0].Packages, buildstep.PackageVersions{unpinnedX: "v0.1.3", "git.novox.be/novox/mesh-sdk/go": "v0.1.20"}) {
t.Errorf("end = %+v, asks %+v; want passed, built with x at v0.1.3", end, asks)
}
// The end reports the pins the build was built with, the one the publish gave included (H-A-207).
if !reflect.DeepEqual(end.Packages, map[string]string{unpinnedX: "v0.1.3", "git.novox.be/novox/mesh-sdk/go": "v0.1.20"}) {
t.Errorf("the end reports the pins %v; want the ones it was built with", end.Packages)
}
// A done key reports the pins it keeps it was built with, never the newer one a publish gives now (H-A-207).
r.b.PackagePublished(unpinnedX, "v0.1.5")
again := r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.9.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Source: 41,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}})
if again.Outcome != meshbuilds.StepEndedOutcomePassed || again.Packages[unpinnedX] != "v0.1.3" {
t.Errorf("the done key's end = %+v; want passed reporting x at v0.1.3, as built", again)
}
// A done key that keeps no pins reports none, so the runner ends the waiting steps loud.
v, err := builds.DecodeBuilderBuild(r.st.vals[r.key])
if err != nil {
t.Fatal(err)
}
v.Packages = nil
raw, err := builds.EncodeBuilderBuild(v)
if err != nil {
t.Fatal(err)
}
r.st.vals[r.key] = raw
if bare := r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.9.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Source: 41,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}}); len(bare.Packages) != 0 {
t.Errorf("a done key keeping no pins reported %v; want none", bare.Packages)
}
}
func aPackageWithNoReleaseFailsPastItsBound(t *testing.T) {
r, _ := unpinnedRig(t)
r, _, _ := unpinnedRig(t)
r.b.PackageWait = time.Nanosecond
end := r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.9.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Source: 41,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}})
r.b.Wait()
if _, built := r.st.vals[r.key]; end.Outcome != meshbuilds.StepEndedOutcomeFailed || built ||
!strings.Contains(end.Said, "package git.novox.be/novox/mesh-contracts/go/seats/x has no released version") {
!strings.Contains(end.Said, "package "+unpinnedX+" has no released version in the series 0.1") {
t.Errorf("end = %+v, built %v; want failed naming the package, nothing built", end, built)
}
// A release the builder's own record keeps gives the pin at once.
r.b.NewestReleased = func(_ context.Context, module string) (string, bool, error) {
return "0.1.2", module == "contracts", nil
}
// A publish heard before gives the pin at once.
r.b.PackagePublished(unpinnedX, "v0.1.2")
if end := r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.9.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Source: 41,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}}); strings.Contains(end.Said, "no released version") {
t.Errorf("a release the record keeps did not pin the package: %+v", end)
t.Errorf("a publish heard did not pin the package: %+v", end)
}
}
// H-A-194: the build reads the registry seat's versions of the path once before it waits: a version in the accepted series
// pins the package with no event heard; one only in another series leaves the build waiting for a publish.
func theSeatsVersionsPinBeforeTheWait(t *testing.T) {
r, _, _ := unpinnedRig(t)
r.b.PackageWait = time.Nanosecond // no wait: the seat's answer alone gives the pin
var read []string
r.b.PublishedVersions = func(_ context.Context, path string) ([]string, error) {
read = append(read, path)
return []string{"0.2.1", "0.1.9", "0.1.8"}, nil // newest first
}
end := r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.9.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Source: 41,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}})
r.b.Wait()
asks := r.asks.Asks()
if end.Outcome != meshbuilds.StepEndedOutcomePassed || len(asks) == 0 || asks[0].Packages[unpinnedX] != "v0.1.9" || !slices.Equal(read, []string{unpinnedX}) {
t.Errorf("end = %+v, asks %+v, read %v; want passed, built with x at v0.1.9 read once from the seat", end, asks, read)
}
r2, _, waiting := unpinnedRig(t)
r2.b.PublishedVersions = func(context.Context, string) ([]string, error) { return []string{"0.2.1"}, nil }
ended := make(chan meshbuilds.StepEnded, 1)
go func() {
ended <- r2.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.9.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Source: 41,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}})
}()
awaitWaiting(t, waiting, ended)
r2.b.PackagePublished(unpinnedX, "0.1.10")
if end := <-ended; end.Outcome != meshbuilds.StepEndedOutcomePassed {
t.Errorf("end = %+v, want passed once x was published in its series", end)
}
r2.b.Wait()
}
// H-A-192, H-A-165: the lane of an entry taken in waits the same way, never asking a build without the pin, and fails the
// key past the bound naming the package.
func aLaneWaitsForAnUnpinnedPackage(t *testing.T) {
r, entry, waiting := unpinnedRig(t)
done := make(chan struct{})
go func() {
r.b.Entry(t.Context(), Origin{Branch: "main", Source: 41, First: true}, entry)
r.b.Wait()
close(done)
}()
awaitWaiting(t, waiting, done)
if asks := r.asks.Asks(); len(asks) != 0 {
t.Fatalf("a build was asked without the package's pin: %+v", asks)
}
r.b.PackagePublished(unpinnedX, "0.1.5")
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("the publish did not wake the lane")
}
if asks := r.asks.Asks(); len(asks) == 0 || asks[0].Packages[unpinnedX] != "v0.1.5" {
t.Errorf("asks %+v; want one asked with x at v0.1.5", asks)
}
// Past its bound the key fails naming the package, and nothing is asked.
r2, entry2, _ := unpinnedRig(t)
r2.b.PackageWait = time.Nanosecond
r2.b.Entry(t.Context(), Origin{Branch: "main", Source: 41, First: true}, entry2)
r2.b.Wait()
if asks := r2.asks.Asks(); len(asks) != 0 || !strings.Contains(string(r2.st.vals[r2.key]), "package "+unpinnedX+" has no released version") {
t.Errorf("asks %+v, key %s; want none asked and the key failed naming the package", asks, r2.st.vals[r2.key])
}
}
@@ -249,6 +361,11 @@ func aStepAskWaitsForItsRevision(t *testing.T) {
held.Store(40)
asked := make(chan struct{}, 1)
r, res, entry := revisionRig(t, &held, asked)
var keptReads atomic.Int64 // H-A-205, H-A-222: a revision above the newest is read by number once; not answered, it is waited for
r.b.KeptRevision = func(context.Context, string, int64) (int64, map[string]string, error) {
keptReads.Add(1)
return 0, nil, errors.New("not asked")
}
ended := make(chan meshbuilds.StepEnded, 1)
go func() {
ended <- r.b.BuildStep(t.Context(), meshbuilds.StepRun{Pipeline: "main.7.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Revision: 7, Source: 41,
@@ -273,8 +390,84 @@ func aStepAskWaitsForItsRevision(t *testing.T) {
t.Fatal("the ask was not woken by the entry the picture took in")
}
r.b.Wait()
if end.Outcome != meshbuilds.StepEndedOutcomePassed || len(res.sources) != 1 || res.sources[0].Revision != 41 {
t.Errorf("end = %+v, reserved from %+v; want passed with one version reserved from revision 41", end, res.sources)
if end.Outcome != meshbuilds.StepEndedOutcomePassed || len(res.sources) != 1 || res.sources[0].Revision != 41 || keptReads.Load() != 1 {
t.Errorf("end = %+v, reserved from %+v, kept revisions read %d; want passed with one version reserved from revision 41, read by number once", end, res.sources, keptReads.Load())
}
}
// H-A-205: two pipelines of consecutive revisions run at once; the picture holds source revision 46, whose entry of m moved
// on, while the older pipeline asks the build of revision 45. Its kept catalog revision is read by number and the build runs;
// a kept revision naming another fingerprint fails the step, naming it.
func anOlderKeptRevisionIsReadByNumber(t *testing.T) {
var held atomic.Int64
held.Store(46)
r, res, _ := revisionRig(t, &held, make(chan struct{}, 1)) // a picture at 46 that never heard 45 (a restart)
r.b.RevisionWait = time.Nanosecond // a wait would fail at once: the older revision is never waited for
r.b.FirstBranch = func(branch, module string) bool { return branch == "main" && module == "m" }
var read []string
r.b.KeptRevision = func(_ context.Context, branch string, revision int64) (int64, map[string]string, error) {
read = append(read, fmt.Sprintf("%s %d", branch, revision))
return 45, map[string]string{"m": fp1}, nil
}
run := meshbuilds.StepRun{Pipeline: "main.47.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Revision: 47, Source: 45,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}}
end := r.b.BuildStep(t.Context(), run)
r.b.Wait()
if end.Outcome != meshbuilds.StepEndedOutcomePassed || !slices.Equal(read, []string{"main 47"}) {
t.Errorf("end = %+v, kept revisions read %v; want passed, revision 47 of main read once", end, read)
}
// Its fingerprint is recorded as the branch's: its build reserves its version from source revision 45 (H-A-155).
// The version reserved names the catalog revision the ask named, which its package-published says (H-A-218).
if len(res.sources) != 1 || res.sources[0].Revision != 45 || res.sources[0].CatalogRevision != 47 {
t.Errorf("reserved from %+v; want one version reserved from source revision 45 at catalog revision 47 (H-A-218)", res.sources)
}
r2, _, _ := revisionRig(t, &held, make(chan struct{}, 1))
r2.b.RevisionWait = time.Nanosecond
r2.b.KeptRevision = func(context.Context, string, int64) (int64, map[string]string, error) {
return 45, map[string]string{"m": "src2:other"}, nil
}
if end := r2.b.BuildStep(t.Context(), run); end.Outcome != meshbuilds.StepEndedOutcomeFailed || !strings.Contains(end.Said, "names m at \"src2:other\"") {
t.Errorf("end = %+v; want failed naming the fingerprint the kept revision names", end)
}
// H-A-222: an ask of the very source the picture holds, whose entries the picture no longer names (a re-pin kept revision 48
// of the same source 46 and the picture took its entries in), is held by its revision read by number, never waited for.
r3, res3, _ := revisionRig(t, &held, make(chan struct{}, 1))
r3.b.RevisionWait = time.Nanosecond
r3.b.FirstBranch = func(branch, module string) bool { return branch == "main" && module == "m" }
var read3 []string
r3.b.KeptRevision = func(_ context.Context, branch string, revision int64) (int64, map[string]string, error) {
read3 = append(read3, fmt.Sprintf("%s %d", branch, revision))
return 46, map[string]string{"m": fp1}, nil
}
same := meshbuilds.StepRun{Pipeline: "main.48.m", Step: meshbuilds.StepRunStepBuild, Branch: "main", Revision: 48, Source: 46,
Entries: []meshbuilds.BuildEntry{{Module: "m", Fingerprint: fp1}}}
end3 := r3.b.BuildStep(t.Context(), same)
r3.b.Wait()
if end3.Outcome != meshbuilds.StepEndedOutcomePassed || !slices.Equal(read3, []string{"main 48"}) || len(res3.sources) != 1 || res3.sources[0].CatalogRevision != 48 {
t.Errorf("end = %+v, kept revisions read %v, reserved %+v; want passed, revision 48 of main read once and reserved at it", end3, read3, res3.sources)
}
// H-A-218, H-A-222: a kept revision of another source than the ask names, or naming another fingerprint, is a mismatch:
// the step fails at once naming it, never waiting out its bound (the bound here is long, the ask is not below the picture).
for _, c := range []struct {
name string
source int64
fp string
said string
}{
{"another source", 45, fp1, "the catalog's revision 48 is of source revision 45, the ask names 46"},
{"another fingerprint", 46, "src2:other", "names m at \"src2:other\""},
} {
rc, resc, _ := revisionRig(t, &held, make(chan struct{}, 1))
rc.b.RevisionWait = time.Hour
rc.b.KeptRevision = func(context.Context, string, int64) (int64, map[string]string, error) {
return c.source, map[string]string{"m": c.fp}, nil
}
end := rc.b.BuildStep(t.Context(), same)
rc.b.Wait()
if end.Outcome != meshbuilds.StepEndedOutcomeFailed || !strings.Contains(end.Said, c.said) || len(resc.sources) != 0 {
t.Errorf("%s: end = %+v, reserved %+v; want failed at once saying %q, nothing reserved", c.name, end, resc.sources, c.said)
}
}
}
@@ -0,0 +1,205 @@
package versions
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
)
// **The reservations' index by digest and by version** (design 47 H H-A-269 (1), H-A-271): beside the reservations, in the same
// state, the builder keeps which reservation keys hold a built digest and which stand at a version, so a registry seat's published
// finds its reservation in one read and a published whose digest no reservation holds is judged from its version's keys in one
// more, never a scan of every reservation. The index keys have three tokens, so the reservations' filter (two tokens) never lists
// them. It is maintained at reserve, at a digest recorded, at release and at drop; an entry left behind by a write that ended
// halfway is harmless (every read checks the reservation it names), and a missing one is written again by Reindex at the start.
const (
indexDigestPrefix = "index.digest."
indexVersionPrefix = "index.version."
indexUnbuiltPrefix = "index.unbuilt."
// IndexDigestFilter and IndexVersionFilter are the filters of the index's two halves.
IndexDigestFilter = indexDigestPrefix + "*"
IndexVersionFilter = indexVersionPrefix + "*"
// IndexUnbuiltFilter is the filter of the reservations at a version whose build has not recorded every digest (H-A-280).
IndexUnbuiltFilter = indexUnbuiltPrefix + "*"
)
// IndexDigestKey is the index key of the reservations holding digest as a built artifact's.
func IndexDigestKey(digest string) string { return indexDigestPrefix + EscapeToken(digest) }
// IndexVersionKey is the index key of the reservations standing at version (MAJOR.MINOR.PATCH).
func IndexVersionKey(version string) string { return indexVersionPrefix + EscapeToken(version) }
// IndexUnbuiltKey is the index key of the reservations at version whose build has not recorded every digest (design 47 H
// H-A-280): the only ones a published whose digest no reservation holds is kept on (A-415), kept apart from the built.
func IndexUnbuiltKey(version string) string { return indexUnbuiltPrefix + EscapeToken(version) }
// IndexEntry is an index key's value: the reservation keys, sorted.
type IndexEntry struct {
Keys []string `json:"keys"`
}
// indexed reads an index key's reservation keys.
func (r *Reserver) indexed(ctx context.Context, key string) ([]string, error) {
raw, _, found, err := r.Store.Get(ctx, key)
if err != nil || !found {
return nil, err
}
var e IndexEntry
if err := json.Unmarshal(raw, &e); err != nil {
return nil, fmt.Errorf("%s holds what is no index entry: %w", key, err)
}
return e.Keys, nil
}
// index adds (or, with add false, removes) reserved under the index key key, by compare-and-set; an entry left empty is deleted.
func (r *Reserver) index(ctx context.Context, key, reserved string, add bool) error {
for {
raw, rev, found, err := r.Store.Get(ctx, key)
if err != nil {
return err
}
var e IndexEntry
if found {
_ = json.Unmarshal(raw, &e)
}
has := slices.Contains(e.Keys, reserved)
if has == add {
return nil
}
if add {
e.Keys = append(e.Keys, reserved)
sort.Strings(e.Keys)
} else {
e.Keys = slices.DeleteFunc(e.Keys, func(k string) bool { return k == reserved })
}
if len(e.Keys) == 0 {
return r.Store.Delete(ctx, key)
}
out, _ := json.Marshal(e)
if found {
_, err = r.Store.Update(ctx, key, out, rev)
} else {
_, err = r.Store.Create(ctx, key, out)
}
if errors.Is(err, ErrConflict) {
continue
}
return err
}
}
// indexKeys are the index keys a reservation stands under: its version's and each built digest's.
func indexKeys(v ReservedVersion) []string {
out := []string{}
if v.Version != "" {
out = append(out, IndexVersionKey(v.Version))
if v.BuiltAt.IsZero() {
out = append(out, IndexUnbuiltKey(v.Version))
}
}
for _, d := range v.Artifacts {
if d != "" && !slices.Contains(out, IndexDigestKey(d)) {
out = append(out, IndexDigestKey(d))
}
}
return out
}
// reindex moves reservation key from the index keys of was (its value before, zero when there was none) to those of now (zero when
// it is gone).
func (r *Reserver) reindex(ctx context.Context, key string, was, now ReservedVersion) error {
add, drop := indexKeys(now), indexKeys(was)
var errs []error
for _, k := range add {
if err := r.index(ctx, k, key, true); err != nil {
errs = append(errs, err)
}
}
for _, k := range drop {
if !slices.Contains(add, k) {
if err := r.index(ctx, k, key, false); err != nil {
errs = append(errs, err)
}
}
}
if err := errors.Join(errs...); err != nil {
return fmt.Errorf("the index of %s is not written (Reindex writes it at the start): %w", key, err)
}
return nil
}
// IndexedAt are the keys of the reservations standing at version, by the index by version alone (H-A-280): no reservation read.
func (r *Reserver) IndexedAt(ctx context.Context, version string) ([]string, error) {
return r.indexed(ctx, IndexVersionKey(version))
}
// AtVersion are the reservations standing at version, read through the index by version (H-A-271): one read of the index and
// one of each reservation it names.
func (r *Reserver) AtVersion(ctx context.Context, version string) ([]ReservedVersion, error) {
keys, err := r.indexed(ctx, IndexVersionKey(version))
if err != nil {
return nil, err
}
var out []ReservedVersion
for _, k := range keys {
cur, _, found, err := r.get(ctx, k)
if err != nil {
return out, err
}
if found && cur.Version == version {
out = append(out, cur)
}
}
return out, nil
}
// Reindex writes the index again from the reservations, once at the builder's start (H-A-269 (1), H-A-271): each reservation is
// added under its keys, and a reservation an index key names that does not stand under it (read again) is removed from it. Both
// are the same compare-and-set as every other index write, so a reservation written meanwhile keeps its entries. It answers how
// many reservations it read.
func (r *Reserver) Reindex(ctx context.Context) (int, error) {
all, err := r.All(ctx)
if err != nil {
return 0, err
}
var errs []error
for _, v := range all {
key := ReservedKey(v.Module, v.Series)
for _, k := range indexKeys(v) {
if err := r.index(ctx, k, key, true); err != nil {
errs = append(errs, err)
}
}
}
for _, filter := range []string{IndexDigestFilter, IndexVersionFilter, IndexUnbuiltFilter} {
keys, err := r.Store.KeysOf(ctx, filter)
if err != nil {
return len(all), fmt.Errorf("the index cannot be listed: %w", err)
}
for _, k := range keys {
named, err := r.indexed(ctx, k)
if err != nil {
errs = append(errs, err)
continue
}
for _, rk := range named {
cur, _, found, err := r.get(ctx, rk)
if err != nil {
errs = append(errs, err)
continue
}
if found && slices.Contains(indexKeys(cur), k) {
continue
}
if err := r.index(ctx, k, rk, false); err != nil {
errs = append(errs, err)
}
}
}
}
return len(all), errors.Join(errs...)
}
@@ -0,0 +1,144 @@
package versions
import (
"context"
"encoding/json"
"fmt"
"strings"
"sync/atomic"
"testing"
)
// countingReserve counts the listings of the reservations and the reads of a reservation key (two tokens), so a test sees that
// a published reads its reservation and no other.
type countingReserve struct {
*reserveMem
lists, reads atomic.Int64
}
func (c *countingReserve) KeysOf(ctx context.Context, filter string) ([]string, error) {
c.lists.Add(1)
return c.reserveMem.KeysOf(ctx, filter)
}
func (c *countingReserve) Get(ctx context.Context, key string) ([]byte, uint64, bool, error) {
if !strings.HasPrefix(key, "index.") {
c.reads.Add(1)
}
return c.reserveMem.Get(ctx, key)
}
// TestTheIndexFindsAPublishedReservationInOneRead: design 47 H H-A-269 (1), H-A-271 — a registry seat's published finds its
// reservation through the index by digest, reading that reservation alone and listing none; a published whose digest no
// reservation holds is judged from its version's keys (kept on a build that recorded no digest yet, A-415), never a scan; the
// index goes with a release and a drop, and is written again at the start from reservations written before it existed.
func TestTheIndexFindsAPublishedReservationInOneRead(t *testing.T) {
ctx := context.Background()
fill := func(t *testing.T) (*Reserver, *countingReserve) {
store := &countingReserve{reserveMem: &reserveMem{mem: newMem()}}
r := &Reserver{Store: store, ReleasedOf: func(context.Context, string) ([]string, error) { return nil, nil }}
for i := range 40 {
m := fmt.Sprintf("m%02d", i)
if _, err := r.Reserve(ctx, m, "0.1", []string{m + ":a"}, Source{Fingerprint: "fp" + m}); err != nil {
t.Fatal(err)
}
if i%2 == 0 { // half are built, each with its own digest
if _, err := r.Built(ctx, m, "0.1.0", m+":a", "sha256:"+m, nil); err != nil {
t.Fatal(err)
}
}
}
store.lists.Store(0)
store.reads.Store(0)
return r, store
}
t.Run("a published by digest reads its one reservation", func(t *testing.T) {
r, store := fill(t)
marked, _, err := r.Published(ctx, "m10-a", "v0.1.0", "sha256:m10")
if err != nil || len(marked) != 1 || marked[0].Reserved.Module != "m10" || marked[0].Artifact != "m10:a" {
t.Fatalf("the published marked %+v (%v), want m10:a", marked, err)
}
if l, n := store.lists.Load(), store.reads.Load(); l != 0 || n != 1 {
t.Errorf("the published listed %d times and read %d reservations, want none listed and one read", l, n)
}
})
t.Run("a digest no reservation holds is judged from its version's unbuilt keys", func(t *testing.T) {
r, store := fill(t)
marked, kept, err := r.Published(ctx, "m11-a", "0.1.0", "sha256:early")
if err != nil || len(marked) != 0 {
t.Fatalf("an unbuilt digest marked %v (%v)", marked, err)
}
// The 20 unbuilt reservations at 0.1.0 keep it as heard (A-415); the 20 built ones are not read at all (H-A-280).
if len(kept) != 20 || store.lists.Load() != 0 || store.reads.Load() != 20 {
t.Errorf("kept on %d (want 20), listed %d (want 0), read %d (want only the 20 unbuilt at 0.1.0)", len(kept), store.lists.Load(), store.reads.Load())
}
at, err := r.AtVersion(ctx, "0.9.9")
if err != nil || len(at) != 0 || store.lists.Load() != 0 {
t.Errorf("a version no reservation stands at answered %v (%v), listed %d", at, err, store.lists.Load())
}
})
t.Run("a published at a version many share reads each reservation once and hands them on", func(t *testing.T) {
r, store := fill(t)
// A stale digest entry naming unbuilt reservations too: the second pass takes them as the first read them.
stale, _ := json.Marshal(IndexEntry{Keys: []string{ReservedKey("m01", "0.1"), ReservedKey("m03", "0.1")}})
if _, err := store.Create(ctx, IndexDigestKey("sha256:stale"), stale); err != nil {
t.Fatal(err)
}
slow := 0
out, err := r.PublishedRead(ctx, "x", "0.1.0", "sha256:stale", func() { slow++ })
if err != nil || len(out.Kept) != 20 || len(out.Read) != 20 || slow != 1 {
t.Fatalf("kept %d, read %d, told slow %d (%v): want 20 kept, 20 read and handed on, slow told once", len(out.Kept), len(out.Read), slow, err)
}
if n := store.reads.Load(); n != 20 {
t.Errorf("%d reservation reads, want each of the 20 read once", n)
}
})
t.Run("a release and a drop take the reservation out of the index", func(t *testing.T) {
r, store := fill(t)
if _, err := r.Released(ctx, "m10", "0.1.0"); err != nil {
t.Fatal(err)
}
if _, err := r.Drop(ctx, "m12", "0.1"); err != nil {
t.Fatal(err)
}
for _, k := range []string{IndexDigestKey("sha256:m10"), IndexDigestKey("sha256:m12")} {
if _, _, found, _ := store.Get(ctx, k); found {
t.Errorf("%s stands after its reservation went", k)
}
}
keys, _ := r.indexed(ctx, IndexVersionKey("0.1.0"))
for _, k := range keys {
if k == ReservedKey("m10", "0.1") || k == ReservedKey("m12", "0.1") {
t.Errorf("the version's index still names %s", k)
}
}
})
t.Run("the index is written again at the start from the reservations", func(t *testing.T) {
store := &countingReserve{reserveMem: &reserveMem{mem: newMem()}}
r := &Reserver{Store: store}
// A reservation written before the index existed, and an index entry naming a reservation that is gone.
raw, _ := json.Marshal(ReservedVersion{V: 1, Module: "old", Series: "0.2", Version: "0.2.4", Artifacts: map[string]string{"old:a": "sha256:old"}})
if _, err := store.Create(ctx, ReservedKey("old", "0.2"), raw); err != nil {
t.Fatal(err)
}
stale, _ := json.Marshal(IndexEntry{Keys: []string{ReservedKey("gone", "0.1")}})
if _, err := store.Create(ctx, IndexDigestKey("sha256:gone"), stale); err != nil {
t.Fatal(err)
}
if n, err := r.Reindex(ctx); err != nil || n != 1 {
t.Fatalf("the reindex read %d reservations (%v), want 1", n, err)
}
if _, _, found, _ := store.Get(ctx, IndexDigestKey("sha256:gone")); found {
t.Error("the index entry of a reservation that is gone stands after the reindex")
}
if keys, _ := store.KeysOf(ctx, AllFilter); len(keys) != 1 {
t.Errorf("the reservations list %v: the index keys are listed among them", keys)
}
store.lists.Store(0)
store.reads.Store(0)
marked, _, err := r.Published(ctx, "old-a", "0.2.4", "sha256:old")
if err != nil || len(marked) != 1 || store.lists.Load() != 0 || store.reads.Load() != 1 {
t.Errorf("after the reindex the published marked %v (%v), listed %d, read %d", marked, err, store.lists.Load(), store.reads.Load())
}
})
}
@@ -5,7 +5,9 @@ import (
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strconv"
"strings"
"sync"
"time"
@@ -33,8 +35,19 @@ const (
QueueFull = "queue full"
// NotStoredWords opens what a refused artifact is said as.
NotStoredWords = "not stored: "
// VerbPublish is the registry seats' verb a publish again sends.
VerbPublish = "publish"
// VerbPublish is the registry seats' verb a publish again sends, VerbVersions the one whose record says what a seat holds
// (H-A-272).
VerbPublish = "publish"
VerbVersions = "versions"
// PublishClassLive is the class of a publish whose build ended in this run, which a pipeline's build step waits on;
// PublishClassStart that of a publish asked again at a start, of a build that ended before it. A holder's queue sends every
// live one before any of the start, each class oldest first (design 47 H H-A-290 (1)).
PublishClassLive = "build-ended-this-run"
PublishClassStart = "asked-again-at-start"
// PublishSendsAtOnce bounds the sends of one holder's queue that run at once (H-A-290 (3)).
PublishSendsAtOnce = 4
// PublishQueueListCap caps the queued versions and the publish items builder_publish_queue lists (H-A-290 (5)).
PublishQueueListCap = 50
)
// RepublishTransfer is a publish again's transfer name, the builder's own (the registry part's publish: the caller names its
@@ -75,8 +88,31 @@ type QueuedPublish struct {
Artifacts map[string]string `json:"artifacts"`
Queued time.Time `json:"queued"`
Begun bool `json:"begun,omitempty"`
// Class is PublishClassLive or PublishClassStart (H-A-290 (1)); a value written before it had one is of the start.
Class string `json:"class,omitempty"`
}
// rank is the place of q's class in a holder's queue: the live first.
func (q QueuedPublish) rank() int {
if q.Class == PublishClassLive {
return 0
}
return 1
}
// sortQueued sorts a holder's queued versions in the order they are sent: the live class first, each class oldest first.
func sortQueued(qs []QueuedPublish) {
sort.SliceStable(qs, func(i, j int) bool {
if a, b := qs[i].rank(), qs[j].rank(); a != b {
return a < b
}
return qs[i].Queued.Before(qs[j].Queued)
})
}
// QueueFilter is the filter of every queued version: a queue key has three tokens, which AllFilter (two) never lists on the bus.
const QueueFilter = "*.*.*"
// QueueKey is the key of holder's queued version of module.
func QueueKey(holder, module, version string) string {
return EscapeToken(holder) + "." + EscapeToken(module) + "." + EscapeToken(version)
@@ -115,9 +151,18 @@ type Republisher struct {
// Holders answers a registry seat's holders: the catalog's SeatHolders, the part's one holder function that its FollowSeat
// of the assignments takes too, read from the builder's start (design 47 G A-416, A-416a); nil answers none.
Holders func(seat string) []string
// Started is when this run of the builder started: a version whose build ended at or after it is of the live class, one
// that ended before it of the start's (H-A-290 (1)). Zero makes every version live.
Started time.Time
// Ended ends the publish item of a version that never publishes, its reservation withdrawn or taken over (H-A-290 (2));
// nil ends none.
Ended func(ctx context.Context, module, version string)
mu sync.Mutex
busy map[string]bool
// relist marks a holder whose pass lists again before its next start-class send: a live publish was queued meanwhile
// (H-A-291 (2)).
relist map[string]bool
// lastQueued is the newest time a version was queued at: a clock that has not moved between two versions (a coarse clock,
// or a fixed one) must not make the queue's order the order of its keys, so each is queued after the last.
lastQueued time.Time
@@ -149,6 +194,127 @@ func (r *Republisher) logf(f string, a ...any) {
}
}
// classOf is the class of v's publish: live when its build ended in this run (H-A-290 (1)).
func (r *Republisher) classOf(v ReservedVersion) string {
if v.BuiltAt.Before(r.Started) {
return PublishClassStart
}
return PublishClassLive
}
// NotStanding says why the reservation of a version, as Of answers it (found), never publishes: it stands no more at the
// version (released, dropped or taken over by a newer build), or it was withdrawn (design 47 H H-A-225, H-A-279). Empty when it
// stands (H-A-290 (2)).
func NotStanding(v ReservedVersion, found bool) string {
switch {
case !found:
return "its reservation stands no more at the version (released, dropped or taken over)"
case hasKey(v.Withdrawn, v.Version):
return "its reservation was withdrawn"
}
return ""
}
// newerVersion says whether MAJOR.MINOR.PATCH a is above b, number by number.
func newerVersion(a, b string) bool {
pa, pb := strings.Split(a, "."), strings.Split(b, ".")
if len(pa) != 3 || len(pb) != 3 {
return false
}
for i := range 3 {
x, errx := strconv.Atoi(pa[i])
y, erry := strconv.Atoi(pb[i])
if errx != nil || erry != nil {
return false
}
if x != y {
return x > y
}
}
return false
}
// Retired are the done builds without a release among all that a newer reservation or a newer release of the same module and
// series (MAJOR.MINOR) supersedes, each with why (design 47 H H-A-291 (1), H-A-293; H-A-275: the older digest is dead): keyed
// `<module> <version>`. A standing newer series never retires an older one's build. The releases are the builder's own record
// of them (Releases), read once per module.
func (r *Reserver) Retired(ctx context.Context, all []ReservedVersion) (map[string]string, error) {
seriesOf := func(v ReservedVersion) string {
s, _, err := SplitVersion(v.Version)
if err != nil {
return ""
}
return v.Module + " " + s
}
newest := map[string]string{} // module and series -> its newest reserved version
for _, v := range all {
k := seriesOf(v)
if n, ok := newest[k]; k != "" && (!ok || newerVersion(v.Version, n)) {
newest[k] = v.Version
}
}
kept := map[string][]string{} // module -> the releases the record keeps
read := map[string]bool{}
out := map[string]string{}
for _, v := range all {
k := seriesOf(v)
if v.BuiltAt.IsZero() || k == "" {
continue
}
if n := newest[k]; newerVersion(n, v.Version) {
out[v.Module+" "+v.Version] = "the newer reservation " + n + " of " + v.Module + " supersedes it"
continue
}
if !read[v.Module] && r.Releases != nil {
read[v.Module] = true
raw, _, found, err := r.Releases.Get(ctx, ReleasedKey(v.Module))
if err != nil {
return out, fmt.Errorf("the releases of %s cannot be read: %w", v.Module, err)
}
var rec ReleasedRecord
if found && json.Unmarshal(raw, &rec) == nil {
for _, rb := range rec.Kept {
kept[v.Module] = append(kept[v.Module], rb.Version)
}
}
}
series, _, _ := SplitVersion(v.Version)
rel := ""
for _, kv := range kept[v.Module] {
if s, _, err := SplitVersion(kv); err == nil && s == series && newerVersion(kv, v.Version) && (rel == "" || newerVersion(kv, rel)) {
rel = kv
}
}
if rel != "" {
out[v.Module+" "+v.Version] = "the newer release " + rel + " of " + v.Module + " supersedes it"
}
}
return out, nil
}
// drop deletes every queued key of module's version and ends its publish item: it never publishes (H-A-290 (2)), said with why.
func (r *Republisher) drop(ctx context.Context, module, version, why string) {
ctx = context.WithoutCancel(ctx)
keys, err := r.Queue.KeysOf(ctx, "*."+EscapeToken(module)+"."+EscapeToken(version))
if err != nil {
r.logf("publish again: %s %s never publishes (%s), and its queued keys cannot be listed: %v", module, version, why, err)
}
for _, k := range keys {
if err := r.Queue.Delete(ctx, k); err != nil {
r.logf("%s cannot be deleted from %s: %v", k, PublishQueueState, err)
}
}
r.end(ctx, module, version, why)
}
// end ends module's version's publish item, said with why.
func (r *Republisher) end(ctx context.Context, module, version, why string) {
r.logf("publish again: %s %s is not published: %s; its queued key is dropped and its publish item ended", module, version, why)
if r.Ended != nil {
r.Ended(context.WithoutCancel(ctx), module, version)
}
}
// ActedKey is the acted key of a subject.
func ActedKey(subject string) string { return EscapeToken(subject) }
@@ -183,6 +349,10 @@ func (r *Republisher) queue(ctx context.Context, vs []ReservedVersion, holdersOf
if max > 0 && len(queued) >= max {
break
}
if why := NotStanding(v, true); why != "" {
r.drop(ctx, v.Module, v.Version, why)
continue
}
if v.Fingerprint == "" || v.BuiltAt.IsZero() {
r.logf("publish again: %s %s is not queued: it holds no fingerprint or its build has not ended with every digest", v.Module, v.Version)
continue
@@ -245,7 +415,7 @@ func (r *Republisher) enqueue(ctx context.Context, v ReservedVersion, holder str
r.logf("publish again: %s %s is queued at %s already", v.Module, v.Version, holder)
return false, nil
}
raw, _ := json.Marshal(QueuedPublish{V: 1, Holder: holder, Module: v.Module, Version: v.Version, Artifacts: arts, Queued: r.queuedAt()})
raw, _ := json.Marshal(QueuedPublish{V: 1, Holder: holder, Module: v.Module, Version: v.Version, Artifacts: arts, Queued: r.queuedAt(), Class: r.classOf(v)})
used, err := r.Queue.Bytes(ctx)
if err != nil {
return false, fmt.Errorf("the size of the state %s cannot be read: %w", PublishQueueState, err)
@@ -262,7 +432,15 @@ func (r *Republisher) enqueue(ctx context.Context, v ReservedVersion, holder str
}
return false, fmt.Errorf("%s cannot be queued: %w", key, err)
}
r.logf("publish again: %s %s is queued to publish at %s: %d artifacts", v.Module, v.Version, holder, len(arts))
r.logf("publish again: %s %s is queued to publish at %s: %d artifacts, class %s", v.Module, v.Version, holder, len(arts), r.classOf(v))
if r.classOf(v) == PublishClassLive { // a pass sending a start list lists again, so this one goes next (H-A-291 (2))
r.mu.Lock()
if r.relist == nil {
r.relist = map[string]bool{}
}
r.relist[holder] = true
r.mu.Unlock()
}
return true, nil
}
@@ -299,13 +477,43 @@ func (r *Republisher) Republish(ctx context.Context, module, version string) ([]
return r.queue(ctx, vs, r.holdersFn, 0)
}
// Queued are the queued versions, per holder in the order they are sent, and the acted keys with their sequences:
// builder_publish_queue.
// Queued is builder_publish_queue's answer, small at any size of the queue (design 47 H H-A-290 (5)): the queued versions'
// count per holder and class with the oldest and newest queue time, the first PublishQueueListCap of them in the order they are
// sent (each with its class), the acted keys with their sequences, and the publish items, counted and capped alike.
type Queued struct {
Queue []QueuedPublish `json:"queue"`
Acted map[string]uint64 `json:"acted"`
// Items are the publish items (design 47 G A-457a), each with its tries and its next try; an item that ended says why.
Items []PublishItem `json:"items"`
Total int `json:"total"`
Counts []QueueCount `json:"counts"`
// Queue are the first queued versions, per holder in the order they are sent (the live class first, each class oldest first);
// with a module named, only that module's.
Queue []QueuedPublish `json:"queue"`
// Listed says how many of Total the answer lists.
Listed int `json:"listed"`
Acted map[string]uint64 `json:"acted"`
// ItemCount is how many publish items stand; Items the first of them by their next try (design 47 G A-457a), each with its
// tries and its next try; an item that ended says why.
ItemCount int `json:"item-count"`
Items []PublishItem `json:"items"`
// Capped says a state held more than the one page read of it (H-A-293); Read names each such state, the keys read and its
// size. Every count above is then of the keys read.
Capped bool `json:"capped,omitempty"`
Read []StateCapped `json:"read,omitempty"`
}
// capped notes a state read only in part.
func (q *Queued) capped(c *StateCapped) {
if c != nil {
q.Capped = true
q.Read = append(q.Read, *c)
}
}
// QueueCount is how many versions one holder's queue holds of one class, and when the oldest and the newest were queued.
type QueueCount struct {
Holder string `json:"holder"`
Class string `json:"class"`
Count int `json:"count"`
Oldest time.Time `json:"oldest"`
Newest time.Time `json:"newest"`
}
// PublishItemKeyPrefix opens the key of a publish item in the builder's re-ask state.
@@ -329,69 +537,113 @@ func PublishItemKey(module, version string) string {
return PublishItemKeyPrefix + EscapeToken(module) + "." + EscapeToken(version)
}
// AnswerQueue is builder_publish_queue over the two sections as the tools bundle reads them.
func AnswerQueue(queue, acted, reasks Reader) (Queued, error) {
out := Queued{Queue: []QueuedPublish{}, Acted: map[string]uint64{}, Items: []PublishItem{}}
keys, err := queue.Keys()
// AnswerQueue is builder_publish_queue over the three states as the tools bundle reads them (H-A-290 (5)): each state read in
// bulk (Reader.All), the answer counted and capped at PublishQueueListCap whatever the queue holds; module (and version) narrow the
// listed queue to one module's (one version's), so an item's class can be read.
func AnswerQueue(queue, acted, reasks Reader, module, version string) (Queued, error) {
out := Queued{Counts: []QueueCount{}, Queue: []QueuedPublish{}, Acted: map[string]uint64{}, Items: []PublishItem{}}
vals, c, err := queue.values(PublishQueueState)
out.capped(c)
if err != nil {
return out, fmt.Errorf("the state %s cannot be listed: %w", PublishQueueState, err)
return out, fmt.Errorf("the state %s cannot be read: %w", PublishQueueState, err)
}
for _, k := range keys {
raw, ok, err := queue.Get(k)
if err != nil || !ok {
counts := map[[2]string]*QueueCount{}
var listed []QueuedPublish
for _, raw := range vals {
var q QueuedPublish
if json.Unmarshal(raw, &q) != nil {
continue
}
var q QueuedPublish
if json.Unmarshal(raw, &q) == nil {
if q.Class == "" {
q.Class = PublishClassStart
}
out.Total++
c := counts[[2]string{q.Holder, q.Class}]
if c == nil {
c = &QueueCount{Holder: q.Holder, Class: q.Class, Oldest: q.Queued, Newest: q.Queued}
counts[[2]string{q.Holder, q.Class}] = c
}
c.Count++
if q.Queued.Before(c.Oldest) {
c.Oldest = q.Queued
}
if q.Queued.After(c.Newest) {
c.Newest = q.Queued
}
if (module == "" || q.Module == module) && (version == "" || q.Version == version) {
listed = append(listed, q)
}
}
for _, c := range counts {
out.Counts = append(out.Counts, *c)
}
sort.Slice(out.Counts, func(i, j int) bool {
if out.Counts[i].Holder != out.Counts[j].Holder {
return out.Counts[i].Holder < out.Counts[j].Holder
}
return out.Counts[i].Class < out.Counts[j].Class
})
sort.SliceStable(listed, func(i, j int) bool { return listed[i].Holder < listed[j].Holder })
byHolder := map[string][]QueuedPublish{}
var holders []string
for _, q := range listed {
if byHolder[q.Holder] == nil {
holders = append(holders, q.Holder)
}
byHolder[q.Holder] = append(byHolder[q.Holder], q)
}
for _, h := range holders {
qs := byHolder[h]
sortQueued(qs)
for _, q := range qs {
if len(out.Queue) == PublishQueueListCap {
break
}
out.Queue = append(out.Queue, q)
}
}
sort.SliceStable(out.Queue, func(i, j int) bool {
if out.Queue[i].Holder != out.Queue[j].Holder {
return out.Queue[i].Holder < out.Queue[j].Holder
}
return out.Queue[i].Queued.Before(out.Queue[j].Queued)
})
akeys, err := acted.Keys()
out.Listed = len(out.Queue)
avals, c, err := acted.values(ActedState)
out.capped(c)
if err != nil {
return out, fmt.Errorf("the state %s cannot be listed: %w", ActedState, err)
return out, fmt.Errorf("the state %s cannot be read: %w", ActedState, err)
}
for _, k := range akeys {
raw, ok, err := acted.Get(k)
if err != nil || !ok {
continue
}
for k, raw := range avals {
var a Acted
if json.Unmarshal(raw, &a) == nil {
out.Acted[k] = a.Sequence
}
}
rkeys, err := reasks.Keys()
rvals, c, err := reasks.values("reasks")
out.capped(c)
if err != nil {
return out, fmt.Errorf("the re-ask state cannot be listed: %w", err)
return out, fmt.Errorf("the re-ask state cannot be read: %w", err)
}
for _, k := range rkeys {
for k, raw := range rvals {
if !strings.HasPrefix(k, PublishItemKeyPrefix) {
continue
}
raw, ok, err := reasks.Get(k)
if err != nil || !ok {
continue
}
var it PublishItem
if json.Unmarshal(raw, &it) == nil {
out.Items = append(out.Items, it)
}
}
out.ItemCount = len(out.Items)
sort.SliceStable(out.Items, func(i, j int) bool { return out.Items[i].NextTry.Before(out.Items[j].NextTry) })
if len(out.Items) > PublishQueueListCap {
out.Items = out.Items[:PublishQueueListCap]
}
return out, nil
}
// PublishQueueDescription is builder_publish_queue's description.
const PublishQueueDescription = "The versions the builder will publish again (its state " + PublishQueueState + ", design 47 G section 588): per registry " +
"seat holder, in the order they are sent, each with its artifacts' digests, when it was queued and whether its publish has begun; and the " +
"keys of the state " + ActedState + ", the last stream sequence the builder acted on for each subject; and the publish items (design 47 G " +
"A-457a), each version's tries and next try, and why one ended after its tries. Read-only."
const PublishQueueDescription = "The versions the builder will publish again (its state " + PublishQueueState + ", design 47 G section 588, H H-A-290): " +
"how many each registry seat holder's queue holds per class (build-ended-this-run, sent first, or asked-again-at-start) with the oldest and newest " +
"queue time; the first 50 in the order they are sent, each with its class, its artifacts' digests, when it was queued and whether its publish has " +
"begun (module, and version, list only that module's, so one item's class can be read); the keys of the state " + ActedState + ", the last stream " +
"sequence the builder acted on for each subject; and the publish items (design 47 G A-457a), counted, the first 50 by next try, each version's " +
"tries and next try, and why one ended after its tries. Each state is read in one page; a state past it is answered capped, naming the " +
"keys read and the state's size (H-A-293). Read-only."
// PublishAgainDescription is builder_publish_again's description.
const PublishAgainDescription = "Publish reserved versions again (design 47 G section 588), which builds nothing: with module and version, that reserved " +
@@ -400,22 +652,57 @@ const PublishAgainDescription = "Publish reserved versions again (design 47 G se
"with the versions it queued; each outcome is said as package-published, or left in version-unreleased with the holder's words. A hand act, " +
"recorded in the hand-act log."
// Resume takes up, at the builder's start, every queued version again, a begun one sent anew (§588).
// Resume takes up, at the builder's start, every queued version again, a begun one sent anew (§588): a version whose reservation
// was withdrawn or taken over is dropped with its publish item ended (H-A-290 (2)), and one of the live class whose build ended
// before this run is of the start's now (H-A-290 (1)). It reads the reservations once.
func (r *Republisher) Resume(ctx context.Context) error {
keys, err := r.Queue.KeysOf(ctx, AllFilter)
keys, err := r.Queue.KeysOf(ctx, QueueFilter)
if err != nil {
return fmt.Errorf("the state %s cannot be listed: %w", PublishQueueState, err)
}
all, err := r.Reserved.All(ctx)
if err != nil {
return fmt.Errorf("the queued publishes are not taken up: %w", err)
}
reserved := make(map[string]ReservedVersion, len(all))
for _, v := range all {
reserved[v.Module+" "+v.Version] = v
}
retired, err := r.Reserved.Retired(ctx, all)
if err != nil {
r.logf("publish again: the superseded builds are not retired at the start: %v", err)
}
holders := map[string]bool{}
for _, k := range keys {
raw, _, found, err := r.Queue.Get(ctx, k)
raw, rev, found, err := r.Queue.Get(ctx, k)
if err != nil || !found {
continue
}
var q QueuedPublish
if json.Unmarshal(raw, &q) == nil {
holders[q.Holder] = true
if json.Unmarshal(raw, &q) != nil {
continue
}
v, ok := reserved[q.Module+" "+q.Version]
why := NotStanding(v, ok)
if why == "" {
why = retired[q.Module+" "+q.Version]
}
if why != "" {
if err := r.Queue.Delete(ctx, k); err != nil {
r.logf("%s cannot be deleted from %s: %v", k, PublishQueueState, err)
}
r.end(ctx, q.Module, q.Version, why)
continue
}
if class := r.classOf(v); q.Class != class {
q.Class = class
if raw, err := json.Marshal(q); err == nil {
if _, err := r.Queue.Update(ctx, k, raw, rev); err != nil {
r.logf("%s keeps its class %s at the start: %v", k, q.Class, err)
}
}
}
holders[q.Holder] = true
}
for h := range holders {
r.drainLater(ctx, h)
@@ -445,16 +732,22 @@ func (r *Republisher) drainLater(ctx context.Context, holder string) {
go run()
}
// Drain sends holder's queued versions one at a time, oldest first, each bounded by UnreleasedBound; a key is deleted when
// its outcome is said.
// Drain sends holder's queued versions in passes (H-A-290 (3)): a pass lists the holder's keys once, reads each once, and sends
// them in their order (the live class first, each class oldest first), PublishSendsAtOnce at a time; the keys are listed again
// only when the pass is spent, or when a live publish was queued while it sends a start list: then the sends in flight end and
// the keys are listed again, so the live one goes next (H-A-291 (2)); a start-class one queued meanwhile waits for the pass's end.
// Each send is bounded by UnreleasedBound; a key is deleted when its outcome is said.
func (r *Republisher) Drain(ctx context.Context, holder string) {
for ctx.Err() == nil {
r.mu.Lock()
delete(r.relist, holder)
r.mu.Unlock()
keys, err := r.Queue.KeysOf(ctx, EscapeToken(holder)+".*.*")
if err != nil {
r.logf("the queue of %s cannot be listed: %v", holder, err)
return
}
var items []QueuedPublish
items := make([]QueuedPublish, 0, len(keys))
for _, k := range keys {
if raw, _, found, err := r.Queue.Get(ctx, k); err == nil && found {
var q QueuedPublish
@@ -466,12 +759,35 @@ func (r *Republisher) Drain(ctx context.Context, holder string) {
if len(items) == 0 {
return
}
sort.SliceStable(items, func(i, j int) bool { return items[i].Queued.Before(items[j].Queued) })
r.send(ctx, items[0])
sortQueued(items)
sem := make(chan struct{}, PublishSendsAtOnce)
var wg sync.WaitGroup
for _, q := range items {
if ctx.Err() != nil {
break
}
sem <- struct{}{}
r.mu.Lock()
again := q.Class != PublishClassLive && r.relist[holder]
r.mu.Unlock()
if again {
<-sem
r.logf("publish again: %s's pass lists again after its sends in flight: a live publish was queued", holder)
break
}
wg.Add(1)
go func() {
defer func() { <-sem; wg.Done() }()
r.send(ctx, q)
}()
}
wg.Wait()
}
}
// send publishes one queued version's artifacts and says the outcome, then deletes its key.
// send publishes one queued version's artifacts and says the outcome, then deletes its key. Every call it makes honours the one
// bound it is given, UnreleasedBound (a context's bound, no timer, ADR 0437 §8), and a send that returns without sending says why
// (H-A-290 (4)).
func (r *Republisher) send(ctx context.Context, q QueuedPublish) {
key := QueueKey(q.Holder, q.Module, q.Version)
defer func() {
@@ -479,18 +795,44 @@ func (r *Republisher) send(ctx context.Context, q QueuedPublish) {
r.logf("%s cannot be deleted from %s: %v", key, PublishQueueState, err)
}
}()
bound, cancel := context.WithTimeout(ctx, UnreleasedBound)
defer cancel()
if !q.Begun {
q.Begun = true
raw, _ := json.Marshal(q)
if _, rev, found, err := r.Queue.Get(ctx, key); err == nil && found {
_, _ = r.Queue.Update(ctx, key, raw, rev)
if _, rev, found, err := r.Queue.Get(bound, key); err == nil && found {
_, _ = r.Queue.Update(bound, key, raw, rev)
}
}
v, found, err := r.Reserved.Of(ctx, q.Module, q.Version)
if err != nil || !found {
return // released meanwhile, or dropped
all, err := r.Reserved.All(bound)
if err != nil {
r.logf("publish again: %s %s is not sent to %s: its reservation cannot be read: %v; its publish item asks it again", q.Module, q.Version, q.Holder, err)
return
}
e, err := r.Entry(ctx, v.Fingerprint)
var v ReservedVersion
found := false
var mine []ReservedVersion
for _, w := range all {
if w.Module == q.Module {
mine = append(mine, w)
if w.Version == q.Version {
v, found = w, true
}
}
}
why := NotStanding(v, found)
if why == "" {
retired, err := r.Reserved.Retired(bound, mine)
if err != nil {
r.logf("publish again: %s %s: whether a newer version supersedes it cannot be read, so it is sent: %v", q.Module, q.Version, err)
}
why = retired[q.Module+" "+q.Version]
}
if why != "" {
r.end(ctx, q.Module, q.Version, why)
return
}
e, err := r.Entry(bound, v.Fingerprint)
if err != nil {
r.say(ctx, v, fmt.Sprintf("the catalog entry %s cannot be read: %v", v.Fingerprint, err))
return
@@ -501,29 +843,13 @@ func (r *Republisher) send(ctx context.Context, q QueuedPublish) {
}
sort.Strings(refs)
for _, ref := range refs {
var art *meshcatalog.Artifact
for i := range e.Artifacts {
if e.Artifacts[i].Ref == ref {
art = &e.Artifacts[i]
}
}
seat, ok := "", false
if art != nil {
seat, ok = SeatOfArtifact(*art)
}
seat, name, kind, ok := publishTarget(e, q.Module, ref)
if !ok {
r.say(ctx, v, ref+": the catalog entry names no registry seat for it")
return
}
name := NameOf(q.Module, strings.TrimPrefix(ref, q.Module+":"))
if art.Package != nil && art.Package.Name != "" {
name = art.Package.Name
}
kind := art.Kind
bound, cancel := context.WithTimeout(ctx, UnreleasedBound) // a context's bound, no timer (ADR 0437 §8)
err := r.Send(bound, Publish{Seat: seat, Kind: kind, Name: name, Version: v.Version, Digest: q.Artifacts[ref], Fingerprint: v.Fingerprint,
Commit: v.Commit, Transfer: RepublishTransfer(q.Module, v.Version, strings.TrimPrefix(ref, q.Module+":"))})
cancel()
if err == nil {
r.logf("publish again: %s %s: %s sent to %s as %s %s, digest %s; the package-published is said when the seat says published", q.Module, q.Version, ref, seat, name, v.Version, q.Artifacts[ref])
}
@@ -531,7 +857,7 @@ func (r *Republisher) send(ctx context.Context, q QueuedPublish) {
r.logf("publish again: %s %s: %s refused by %s: %v", q.Module, q.Version, ref, seat, err)
words := err.Error()
if strings.Contains(words, strings.TrimSuffix(NotStoredWords, ": ")) {
if ok, merr := r.Reserved.MarkUnstored(ctx, q.Module, q.Version, ref, words); merr != nil {
if ok, merr := r.Reserved.MarkUnstored(bound, q.Module, q.Version, ref, words); merr != nil {
r.logf("%s %s: the unstored %s is not kept: %v", q.Module, q.Version, ref, merr)
} else if ok {
r.say(ctx, v, ref+" "+NotStoredWords+words)
@@ -543,6 +869,28 @@ func (r *Republisher) send(ctx context.Context, q QueuedPublish) {
}
}
// publishTarget is the registry seat, the name and the kind module's artifact ref is published as, from its catalog entry; ok is
// false when the entry names no registry seat for it.
func publishTarget(e meshcatalog.CatalogEntry, module, ref string) (seat, name, kind string, ok bool) {
var art *meshcatalog.Artifact
for i := range e.Artifacts {
if e.Artifacts[i].Ref == ref {
art = &e.Artifacts[i]
}
}
if art == nil {
return "", "", "", false
}
if seat, ok = SeatOfArtifact(*art); !ok {
return "", "", "", false
}
name = NameOf(module, strings.TrimPrefix(ref, module+":"))
if art.Package != nil && art.Package.Name != "" {
name = art.Package.Name
}
return seat, name, art.Kind, true
}
func (r *Republisher) say(ctx context.Context, v ReservedVersion, why string) {
r.logf("%s %s is not published again: %s", v.Module, v.Version, why)
if r.Unreleased != nil {
@@ -579,3 +927,105 @@ func (r *Reserver) MarkUnstored(ctx context.Context, module, version, artifact,
return true, nil
}
}
// UnheardBound is how many messages the builder's durable on the events stream may hold pending and unacknowledged while a
// publish is asked again (design 47 H H-A-269 (2), H-A-272): at or above it a published of the version may still be unheard, so
// the try is skipped. A constant of the builder, no setting.
const UnheardBound = 100
// HeldVersion is one version a registry seat's verb versions answers of a name, with its digest.
type HeldVersion struct {
Version, Digest string
}
// HeldArtifact is an artifact of a reservation as a registry seat's record holds it at the reservation's version: its reference,
// the seat and the name it is published as, the version and the digest the seat holds.
type HeldArtifact struct {
Ref, Seat, Name, Version, Digest string
}
// Judged is what the registries' record says of a reserved version's missing artifacts (design 47 H H-A-272, H-A-274, H-A-275):
// those held at the version with the built digest (Held), those held at the version with another digest (Elsewhere), and, when an
// artifact is held at neither, the first one lacking (Lacks). All says every missing artifact is held with its built digest.
type Judged struct {
Held, Elsewhere []HeldArtifact
Lacks string
All bool
}
// Held judges v's missing artifacts against the registries' record (design 47 H H-A-269 (2), H-A-272, H-A-274, H-A-275): each
// artifact's registry seat and name as a publish again sends them, its record read through the seat's verb versions (versionsOf).
// A version with no missing artifact is All.
func (r *Republisher) Held(ctx context.Context, v ReservedVersion, versionsOf func(ctx context.Context, seat, name string) ([]HeldVersion, error)) (Judged, error) {
missing := v.Missing()
if len(missing) == 0 {
return Judged{All: true}, nil
}
e, err := r.Entry(ctx, v.Fingerprint)
if err != nil {
return Judged{}, fmt.Errorf("the catalog entry %s of %s %s cannot be read: %w", v.Fingerprint, v.Module, v.Version, err)
}
var out Judged
for _, ref := range missing {
seat, name, _, ok := publishTarget(e, v.Module, ref)
if !ok {
if out.Lacks == "" {
out.Lacks = ref + ": the catalog entry names no registry seat for it"
}
continue
}
held, err := versionsOf(ctx, seat, name)
if err != nil {
return Judged{}, fmt.Errorf("%s's versions of %s cannot be read: %w", seat, name, err)
}
at, found := HeldArtifact{}, false
for _, h := range held {
if strings.TrimPrefix(h.Version, "v") != v.Version {
continue
}
at, found = HeldArtifact{Ref: ref, Seat: seat, Name: name, Version: h.Version, Digest: h.Digest}, true
if h.Digest == v.Artifacts[ref] {
break
}
}
switch {
case !found:
if out.Lacks == "" {
out.Lacks = fmt.Sprintf("%s holds no %s %s", seat, name, v.Version)
}
case at.Digest == v.Artifacts[ref]:
out.Held = append(out.Held, at)
default:
out.Elsewhere = append(out.Elsewhere, at)
}
}
out.All = len(out.Held) == len(missing)
return out, nil
}
// HeldNumbers are the versions (MAJOR.MINOR.PATCH) a registry seat's record holds of any of module's artifacts refs, as the catalog
// entry of fingerprint names their seats and names (design 47 H H-A-275): a number one holds is never reserved. An artifact the
// entry names no registry seat for is read nowhere.
func (r *Republisher) HeldNumbers(ctx context.Context, module, fingerprint string, refs []string, versionsOf func(ctx context.Context, seat, name string) ([]HeldVersion, error)) ([]string, error) {
e, err := r.Entry(ctx, fingerprint)
if err != nil {
return nil, fmt.Errorf("the catalog entry %s of %s cannot be read: %w", fingerprint, module, err)
}
var out []string
for _, ref := range refs {
seat, name, _, ok := publishTarget(e, module, ref)
if !ok {
continue
}
held, err := versionsOf(ctx, seat, name)
if err != nil {
return out, fmt.Errorf("%s's versions of %s cannot be read: %w", seat, name, err)
}
for _, h := range held {
if v := strings.TrimPrefix(h.Version, "v"); v != "" && !slices.Contains(out, v) {
out = append(out, v)
}
}
}
return out, nil
}
@@ -5,8 +5,13 @@ import (
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"strings"
"sync"
"sync/atomic"
"testing"
"testing/synctest"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
@@ -15,10 +20,19 @@ import (
type queueMem struct {
*reserveMem
bytes uint64
// listings counts the listings of one holder's keys (a filter `<holder>.*.*`), what a drain's pass lists.
listings atomic.Int32
}
func (q *queueMem) Bytes(context.Context) (uint64, error) { return q.bytes, nil }
func (q *queueMem) KeysOf(ctx context.Context, filter string) ([]string, error) {
if strings.HasSuffix(filter, ".*.*") && filter != QueueFilter {
q.listings.Add(1)
}
return q.reserveMem.KeysOf(ctx, filter)
}
// republishBed is a Republisher over memory states: reservations of module m (a bundle by the oci seat and a Go package by
// the Go seat), one holder module `oci` that claims the oci seat, and a Send and a Unreleased that record.
type republishBed struct {
@@ -26,8 +40,10 @@ type republishBed struct {
reserved *reserveMem
queue *queueMem
now time.Time
mu sync.Mutex // sent and said, which a holder's sends at once write
sent []Publish
said []string
ended []string
refuse string // the words Send fails with, empty for none
// holders are the registry seats' holders the seat-holders view names (design 47 G A-416).
holders map[string][]string
@@ -48,6 +64,8 @@ func newRepublishBed(t *testing.T) *republishBed {
{Ref: m + ":lib", Kind: "package", Language: "go", Package: &meshcatalog.ArtifactPackage{Ecosystem: "go", Name: "git.novox.be/novox/" + m + "/go"}}}}, nil
},
Send: func(_ context.Context, p Publish) error {
b.mu.Lock()
defer b.mu.Unlock()
b.sent = append(b.sent, p)
if b.refuse != "" {
return errors.New(b.refuse)
@@ -55,8 +73,15 @@ func newRepublishBed(t *testing.T) *republishBed {
return nil
},
Unreleased: func(_ context.Context, v ReservedVersion, why string) {
b.mu.Lock()
defer b.mu.Unlock()
b.said = append(b.said, v.Module+" "+v.Version+": "+why)
},
Ended: func(_ context.Context, module, version string) {
b.mu.Lock()
defer b.mu.Unlock()
b.ended = append(b.ended, module+" "+version)
},
Logf: t.Logf}
b.Holders = func(seat string) []string { return b.holders[seat] }
return b
@@ -190,9 +215,324 @@ func TestRepublish(t *testing.T) {
return json.RawMessage(`{"mode":"publish","module":"m","version":"0.1.0","tries":3,"next-try":"2026-11-17T01:00:00Z","why":"w"}`), true, nil
}}
none := Reader{Keys: func() ([]string, error) { return nil, nil }}
answer, err := AnswerQueue(none, none, items)
answer, err := AnswerQueue(none, none, items, "", "")
if err != nil || len(answer.Items) != 1 || answer.Items[0].Tries != 3 || answer.Items[0].Version != "0.1.0" {
t.Errorf("builder_publish_queue items = %+v (%v), want the one publish item with its tries", answer.Items, err)
}
})
}
// TestTheRegistriesRecordSaysWhetherAVersionIsHeld: design 47 H H-A-272, H-A-274, H-A-275 — a missing artifact its registry seat
// holds at the version (the Go form too) with the built digest is held; at the version with another digest it is held elsewhere;
// a version the seat lacks is said by name. The numbers a registry holds of the module's artifacts are what reserving skips.
func TestTheRegistriesRecordSaysWhetherAVersionIsHeld(t *testing.T) {
ctx := context.Background()
entry := meshcatalog.CatalogEntry{Artifacts: []meshcatalog.Artifact{{Ref: "m:lib", Kind: "package", Language: "go", Package: &meshcatalog.ArtifactPackage{Ecosystem: "go", Name: "git.example/m"}}}}
r := &Republisher{Entry: func(context.Context, string) (meshcatalog.CatalogEntry, error) { return entry, nil }}
v := ReservedVersion{Module: "m", Version: "0.1.37", Fingerprint: "fp", Artifacts: map[string]string{"m:lib": "sha256:a"}}
for _, c := range []struct {
name string
holds []HeldVersion
all, elsewhere, lacks bool
}{
{name: "held in the Go form with the built digest", holds: []HeldVersion{{Version: "v0.1.36", Digest: "sha256:z"}, {Version: "v0.1.37", Digest: "sha256:a"}}, all: true},
{name: "another digest at the version", holds: []HeldVersion{{Version: "0.1.37", Digest: "sha256:b"}}, elsewhere: true},
{name: "the version lacked", holds: []HeldVersion{{Version: "0.1.36", Digest: "sha256:a"}}, lacks: true},
} {
t.Run(c.name, func(t *testing.T) {
var seat, name string
versionsOf := func(_ context.Context, s, n string) ([]HeldVersion, error) { seat, name = s, n; return c.holds, nil }
j, err := r.Held(ctx, v, versionsOf)
if err != nil || j.All != c.all || (len(j.Elsewhere) == 1) != c.elsewhere || (j.Lacks != "") != c.lacks || seat != SeatGoPackages || name != "git.example/m" {
t.Fatalf("judged %+v (%v) asking %s for %s, want all %v, elsewhere %v, lacks %v asking %s for git.example/m", j, err, seat, name, c.all, c.elsewhere, c.lacks, SeatGoPackages)
}
if c.lacks && !strings.Contains(j.Lacks, "0.1.37") {
t.Errorf("what the registry lacks is said as %q", j.Lacks)
}
nums, err := r.HeldNumbers(ctx, "m", "fp", []string{"m:lib"}, versionsOf)
if err != nil || len(nums) != len(c.holds) {
t.Errorf("the held numbers are %v (%v), want one per version the seat holds", nums, err)
}
})
}
v.Published = map[string]bool{"m:lib": true}
if j, err := r.Held(ctx, v, nil); err != nil || !j.All {
t.Errorf("a version with no missing artifact is judged %+v (%v), want all held without a read", j, err)
}
}
// queueAt writes a queued version of module m at holder oci directly, as a start finds it.
func (b *republishBed) queueAt(t *testing.T, v ReservedVersion, class string, at time.Time) {
t.Helper()
raw, _ := json.Marshal(QueuedPublish{V: 1, Holder: "oci", Module: v.Module, Version: v.Version, Artifacts: map[string]string{v.Module + ":prog": "sha256:aa"}, Queued: at, Class: class})
if _, err := b.queue.Create(context.Background(), QueueKey("oci", v.Module, v.Version), raw); err != nil {
t.Fatal(err)
}
}
// TestAHoldersQueueSendsLiveFirstInPasses: design 47 H H-A-290 (1)-(3) — a publish whose build ended in this run is sent before
// any of a build that ended before the start, each class oldest first; a pass lists the holder's keys once and sends them, at most
// four at a time; a build whose reservation was withdrawn or taken over never publishes, its key dropped and its publish item ended,
// at enqueue, at the pass and at the start.
func TestAHoldersQueueSendsLiveFirstInPasses(t *testing.T) {
ctx := context.Background()
t.Run("the live class first, at most four sends at once", func(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
b := newRepublishBed(t)
var old []ReservedVersion
for _, m := range []string{"o1", "o2", "o3", "o4", "o5"} {
old = append(old, b.reserve(t, m))
}
b.Started = b.now
b.reserve(t, "live")
for i, v := range old {
b.queueAt(t, v, PublishClassStart, b.now.Add(time.Duration(i)*time.Second))
}
b.now = b.now.Add(time.Hour) // the live one is queued last, after every old one
b.holders = map[string][]string{SeatArtifacts: {"oci"}}
release := make(chan struct{})
var arrived []string
var inflight, most int
send := b.Send
b.Send = func(ctx context.Context, p Publish) error {
b.mu.Lock()
arrived = append(arrived, p.Name)
inflight++
most = max(most, inflight)
b.mu.Unlock()
<-release
b.mu.Lock()
inflight--
b.mu.Unlock()
return send(ctx, p)
}
b.Go = func(f func()) { go f() }
if q, err := b.Republish(ctx, "live", ""); err != nil || len(q) != 1 {
t.Fatalf("queued %v (%v), want the live version", q, err)
}
synctest.Wait() // every send the bound lets run waits on release
b.mu.Lock()
first := slices.Clone(arrived)
b.mu.Unlock()
if len(first) != PublishSendsAtOnce || !slices.Contains(first, "live/prog") {
t.Errorf("the sends running at once are %v: want %d, the live one among them", first, PublishSendsAtOnce)
}
close(release)
synctest.Wait()
if len(b.sent) != 6 || most != PublishSendsAtOnce {
t.Errorf("sent %d, at most %d at once: want all six, %d at once", len(b.sent), most, PublishSendsAtOnce)
}
})
})
t.Run("a pass lists the keys once for all its sends", func(t *testing.T) {
b := newRepublishBed(t)
var vs []ReservedVersion
for i := range 6 {
vs = append(vs, b.reserve(t, fmt.Sprintf("m%d", i)))
}
for i, v := range vs {
b.queueAt(t, v, PublishClassStart, b.now.Add(time.Duration(i)*time.Second))
}
b.Drain(ctx, "oci")
if n := b.queue.listings.Load(); len(b.sent) != 6 || n != 2 {
t.Errorf("sent %d with %d listings, want six sends from one pass and one listing that finds it spent", len(b.sent), n)
}
})
t.Run("a start makes a live key of a build before it a start key", func(t *testing.T) {
b := newRepublishBed(t)
v := b.reserve(t, "m")
b.Started = b.now
b.queueAt(t, v, PublishClassLive, b.now)
b.Go = func(func()) {} // the start's drain is not run here
if err := b.Resume(ctx); err != nil {
t.Fatal(err)
}
raw, _, _, _ := b.queue.Get(ctx, QueueKey("oci", "m", v.Version))
var q QueuedPublish
if json.Unmarshal(raw, &q) != nil || q.Class != PublishClassStart {
t.Errorf("the key after the start is %s, want the class %s: its build did not end in this run", raw, PublishClassStart)
}
})
for _, at := range []string{"enqueue", "pass", "start"} {
t.Run("a withdrawn build never publishes, at the "+at, func(t *testing.T) {
b := newRepublishBed(t)
v := b.reserve(t, "m")
b.holders = map[string][]string{SeatArtifacts: {"oci"}}
if _, ok, err := b.Reserved.Withdraw(ctx, "m", v.Version); err != nil || !ok {
t.Fatalf("withdrawn %v (%v)", ok, err)
}
switch at {
case "enqueue":
b.queueAt(t, v, PublishClassLive, b.now)
b.Go = func(func()) {} // a key queued before the withdrawal is dropped by the enqueue itself
if q, _ := b.Republish(ctx, "m", v.Version); len(q) != 0 {
t.Errorf("queued %v", q)
}
case "pass":
b.queueAt(t, v, PublishClassLive, b.now)
b.Drain(ctx, "oci")
case "start":
b.queueAt(t, v, PublishClassLive, b.now)
b.Go = func(func()) {}
if err := b.Resume(ctx); err != nil {
t.Fatal(err)
}
}
keys, _ := b.queue.KeysOf(ctx, QueueFilter)
if len(b.sent) != 0 || len(keys) != 0 || fmt.Sprint(b.ended) != "[m "+v.Version+"]" {
t.Errorf("sent %v, keys %v, items ended %v: want nothing sent, the key dropped and m %s's item ended", b.sent, keys, b.ended, v.Version)
}
})
}
t.Run("a live publish queued mid-pass goes after the sends in flight, before the rest of the start list", func(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
b := newRepublishBed(t)
var old []ReservedVersion
for _, m := range []string{"o1", "o2", "o3", "o4", "o5", "o6"} {
old = append(old, b.reserve(t, m))
}
b.Started = b.now
b.reserve(t, "live")
for i, v := range old {
b.queueAt(t, v, PublishClassStart, b.now.Add(time.Duration(i)*time.Second))
}
b.now = b.now.Add(time.Hour)
b.holders = map[string][]string{SeatArtifacts: {"oci"}}
first, then := make(chan struct{}), make(chan struct{}) // the four in flight wait on first, every later send on then
var arrived []string
send := b.Send
b.Send = func(ctx context.Context, p Publish) error {
b.mu.Lock()
arrived = append(arrived, p.Name)
gate := map[bool]chan struct{}{true: first, false: then}[len(arrived) <= PublishSendsAtOnce]
b.mu.Unlock()
<-gate
return send(ctx, p)
}
b.Go = func(f func()) { go f() }
b.drainLater(ctx, "oci")
synctest.Wait() // four start sends in flight, the pass holding o5 and o6
if q, err := b.Republish(ctx, "live", ""); err != nil || len(q) != 1 {
t.Fatalf("queued %v (%v)", q, err)
}
close(first)
synctest.Wait() // the sends after the four: with the live one among them, or o5 and o6 alone when the pass goes on
b.mu.Lock()
next := slices.Clone(arrived[PublishSendsAtOnce:])
b.mu.Unlock()
if !slices.Contains(next, "live/prog") {
t.Errorf("after the four in flight the sends are %v, want the live one among them, the pass listed again", next)
}
close(then)
synctest.Wait()
if len(arrived) != 7 {
t.Errorf("sent %v, want all seven", arrived)
}
})
})
t.Run("a build a newer patch or release of its series supersedes is retired at the pass and at the start, never by a newer series", func(t *testing.T) {
b := newRepublishBed(t)
v := b.reserve(t, "m")
b.holders = map[string][]string{SeatArtifacts: {"oci"}}
if _, err := b.Reserved.Reserve(ctx, "m", "0.2", []string{"m:prog"}, Source{Fingerprint: "src2:m"}); err != nil {
t.Fatal(err)
}
b.queueAt(t, v, PublishClassStart, b.now)
b.Drain(ctx, "oci")
if len(b.sent) != 1 || len(b.ended) != 0 {
t.Errorf("with a standing 0.2: sent %v, ended %v, want m %s sent, its series not superseded (H-A-293)", b.sent, b.ended, v.Version)
}
rel := &reserveMem{mem: newMem()}
raw, _ := json.Marshal(ReleasedRecord{Kept: []ReleasedBuild{{Fingerprint: "f", Version: "0.2.3"}, {Fingerprint: "g", Version: "0.1.9"}}})
_, _ = rel.Create(ctx, ReleasedKey("m"), raw)
b.Reserved.Releases = rel
b.sent = nil
b.queueAt(t, v, PublishClassStart, b.now)
b.Drain(ctx, "oci")
if len(b.sent) != 0 || fmt.Sprint(b.ended) != "[m "+v.Version+"]" {
t.Errorf("at the pass: sent %v, ended %v, want m %s retired by the release 0.1.9", b.sent, b.ended, v.Version)
}
b.ended = nil
b.queueAt(t, v, PublishClassStart, b.now)
b.Go = func(func()) {}
if err := b.Resume(ctx); err != nil {
t.Fatal(err)
}
if keys, _ := b.queue.KeysOf(ctx, QueueFilter); len(keys) != 0 || fmt.Sprint(b.ended) != "[m "+v.Version+"]" {
t.Errorf("at the start: keys %v, ended %v, want m %s retired", keys, b.ended, v.Version)
}
only := &reserveMem{mem: newMem()}
raw, _ = json.Marshal(ReleasedRecord{Kept: []ReleasedBuild{{Fingerprint: "f", Version: "0.2.0"}}})
_, _ = only.Create(ctx, ReleasedKey("n"), raw)
got, err := (&Reserver{Releases: only}).Retired(ctx, []ReservedVersion{{Module: "n", Version: "0.1.4", BuiltAt: b.now}, {Module: "n", Version: "0.1.6"},
{Module: "n", Version: "0.3.0", BuiltAt: b.now}, {Module: "p", Version: "0.1.2", BuiltAt: b.now}})
if err != nil || len(got) != 1 || !strings.Contains(got["n 0.1.4"], "reservation 0.1.6") {
t.Errorf("retired %v (%v), want only n 0.1.4, by the newer patch 0.1.6; n 0.3.0 and p 0.1.2 kept, a release of 0.2 retiring neither", got, err)
}
})
t.Run("a version taken over is not sent, and its item ended", func(t *testing.T) {
b := newRepublishBed(t)
v := b.reserve(t, "m")
b.queueAt(t, v, PublishClassStart, b.now)
if _, err := b.Reserved.Reserve(ctx, "m", "0.1", []string{"m:prog"}, Source{Fingerprint: "src2:other"}); err != nil {
t.Fatal(err)
}
b.Drain(ctx, "oci")
if len(b.sent) != 0 || fmt.Sprint(b.ended) != "[m "+v.Version+"]" {
t.Errorf("sent %v, ended %v: want nothing sent and the item ended", b.sent, b.ended)
}
})
}
// TestThePublishQueueToolAnswersAtAnySize: design 47 H H-A-290 (5) — builder_publish_queue over two thousand queued versions answers
// within a second and small: counts per holder and class with the oldest and newest queue time, a list capped at fifty in the
// order they are sent, and one module's item with its class; each state read in bulk where the reader can.
func TestThePublishQueueToolAnswersAtAnySize(t *testing.T) {
at := time.Date(2026, 11, 20, 17, 0, 0, 0, time.UTC)
vals := map[string]json.RawMessage{}
for i := range 2000 {
holder, class := "oci", PublishClassStart
if i%2 == 1 {
holder = "go"
}
if i >= 1990 {
class = PublishClassLive
}
q := QueuedPublish{V: 1, Holder: holder, Module: fmt.Sprintf("m%d", i), Version: "0.1.0", Artifacts: map[string]string{"a": "sha256:aa"}, Queued: at.Add(time.Duration(i) * time.Second), Class: class}
vals[QueueKey(holder, q.Module, q.Version)], _ = json.Marshal(q)
}
gets := 0
queue := Reader{All: func() (StatePage, error) { return StatePage{Values: vals}, nil },
Keys: func() ([]string, error) { return slices.Collect(maps.Keys(vals)), nil },
Get: func(k string) (json.RawMessage, bool, error) { gets++; v, ok := vals[k]; return v, ok, nil }}
none := Reader{Keys: func() ([]string, error) { return nil, nil }}
start := time.Now()
a, err := AnswerQueue(queue, none, none, "", "")
took := time.Since(start)
raw, _ := json.Marshal(a)
if err != nil || took > time.Second || a.Total != 2000 || len(a.Queue) != PublishQueueListCap || a.Listed != PublishQueueListCap || len(raw) > 64<<10 || gets != 0 {
t.Fatalf("answered %d of %d in %s, %d bytes, %d single reads (%v): want all counted, fifty listed, within a second, small, in bulk", len(a.Queue), a.Total, took, len(raw), gets, err)
}
if fmt.Sprintln(a.Counts[1].Holder, a.Counts[1].Class, a.Counts[1].Count, a.Counts[1].Oldest.Equal(at.Add(1991*time.Second)), a.Counts[1].Newest.Equal(at.Add(1999*time.Second))) != "go "+PublishClassLive+" 5 true true\n" || len(a.Counts) != 4 {
t.Errorf("counts %+v, want per holder and class with their oldest and newest", a.Counts)
}
if a.Queue[0].Class != PublishClassLive || a.Queue[0].Holder != "go" {
t.Errorf("the list opens with %+v, want the go holder's live class, sent first", a.Queue[0])
}
one, err := AnswerQueue(queue, none, none, "m1995", "")
if err != nil || len(one.Queue) != 1 || one.Queue[0].Class != PublishClassLive || one.Total != 2000 {
t.Errorf("one module's answer %+v (%v), want its item with its class", one.Queue, err)
}
if a.Capped || len(a.Read) != 0 {
t.Errorf("a state one page holds is answered capped: %+v", a.Read)
}
queue.All = func() (StatePage, error) { return StatePage{Values: vals, More: true, Keys: 5000, Bytes: 3 << 20}, nil }
if c, err := AnswerQueue(queue, none, none, "", ""); err != nil || !c.Capped || len(c.Read) != 1 || c.Read[0].State != PublishQueueState ||
c.Read[0].KeysRead != 2000 || c.Read[0].StateKeys != 5000 || c.Read[0].StateBytes != 3<<20 || c.Total != 2000 {
t.Errorf("a state past its one page answered capped %v, read %+v (%v): want capped, 2000 keys read of 5000, its size said (H-A-293)", c.Capped, c.Read, err)
}
queue.All = func() (StatePage, error) { return StatePage{}, errors.ErrUnsupported }
if b, err := AnswerQueue(queue, none, none, "", ""); err != nil || b.Total != 2000 || gets != 2000 {
t.Errorf("a reader with no bulk read answered %d (%v) with %d single reads, want every key read one by one", b.Total, err, gets)
}
}
@@ -5,6 +5,8 @@ import (
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"sort"
"strconv"
"strings"
@@ -35,6 +37,9 @@ const (
UnreleasedBound = 10 * time.Minute
// VersionUnreleased is that finding.
VersionUnreleased = "version-unreleased"
// VersionHeldElsewhere is the finding of a number a registry seat already holds, skipped at reserving or moved from (design 47
// H H-A-275), scope module.
VersionHeldElsewhere = "version-held-elsewhere"
)
// ReservedVersion is the value of a reservation key.
@@ -65,12 +70,18 @@ type ReservedVersion struct {
// (design 47 G §371, A-57): what `package-published` says of the publication.
Branch string `json:"branch,omitempty"`
Source int64 `json:"source,omitempty"`
// Revision is the catalog revision number the build's step ask named, the indexer's count (design 47 H H-A-218): what
// `package-published` names beside the source, so the runner finds the publishing pipeline; 0 when no step ask named one.
Revision int64 `json:"revision,omitempty"`
// Dependencies are, by artifact reference, what the step's result says each artifact resolved (kind 1) and was built with
// (kind 3), kept for `package-published` (design 47 G §466, §673, A-57).
Dependencies map[string][]meshbuilds.Dependency `json:"dependencies,omitempty"`
// Kept are the registry seats' published heard while the build had not yet recorded every digest and whose digest marked
// no artifact then: kept as heard, they mark their artifact when the build records its digests (design 47 G A-415).
Kept []KeptPublished `json:"kept-published,omitempty"`
// Withdrawn are the versions of the series a take-over by another fingerprint withdrew, each with the fingerprint whose
// build it was (design 47 H H-A-225): a late publish of one is refused as withdrawn. Kept while the series' key stands.
Withdrawn map[string]string `json:"withdrawn,omitempty"`
}
// KeptPublished is a registry seat's published kept on a reservation, as heard (design 47 G A-415).
@@ -91,6 +102,8 @@ type Source struct {
// that catalog revision (design 47 G §371, A-57), kept on the reservation for the publication.
Branch string
Revision int64
// CatalogRevision is the catalog revision number the build's step ask named (H-A-218), 0 when none did.
CatalogRevision int64
// Rebuild marks a build again of a done key whose version is not released: the standing reservation of Fingerprint is replaced
// and is no floor, so the number is the next above the catalog's highest alone (design 47 G A-490b).
Rebuild bool
@@ -125,6 +138,50 @@ type Reserver struct {
// DefaultReleasedKept.
ReleasedKept int
Now func() time.Time
// Logf says an index write that failed (H-A-269 (1)): the reservation stands, and Reindex writes its index at the next
// start. Nil says nothing.
Logf func(string, ...any)
// HeldNumbers are the versions a registry seat's record holds of any of module's artifacts (design 47 H H-A-275), read before a
// number is reserved: a number one holds is skipped. Nil reads none; a read that fails is said and the reserve proceeds.
HeldNumbers func(ctx context.Context, module, fingerprint string, refs []string) ([]string, error)
// HeldElsewhere is told the numbers of module a reserve skipped because a registry holds them (H-A-275); nil is told none.
HeldElsewhere func(ctx context.Context, module string, skipped []string)
}
// heldNumbers are the patches of series a registry holds of module's artifacts (H-A-275); a read that fails is said, and none.
func (r *Reserver) heldNumbers(ctx context.Context, module, series, fingerprint string, refs []string) map[int]bool {
if r.HeldNumbers == nil {
return nil
}
vs, err := r.HeldNumbers(ctx, module, fingerprint, refs)
if err != nil {
r.said(fmt.Errorf("%s: the registries' versions are not read before reserving, so a number they hold is not skipped: %w", module, err))
}
out := map[int]bool{}
for _, v := range vs {
if s, p, err := SplitVersion(v); err == nil && s == series {
out[p] = true
}
}
return out
}
// nextFree is the first patch after after that no registry holds, and the held numbers it skipped (H-A-275).
func nextFree(series string, after int, held map[int]bool) (int, []string) {
var skipped []string
p := after + 1
for held[p] {
skipped = append(skipped, fmt.Sprintf("%s.%d", series, p))
p++
}
return p, skipped
}
// said is told the outcome of a reindex: a failure is said, the reservation's own write stands.
func (r *Reserver) said(err error) {
if err != nil && r.Logf != nil {
r.Logf("%v", err)
}
}
func (r *Reserver) now() time.Time {
@@ -149,7 +206,10 @@ func SplitVersion(version string) (series string, patch int, err error) {
// Reserve reserves the next version of module's series for a build that starts, for artifacts (their names), and answers
// it. The next patch is the one after the higher of the highest released and the one reserved, 0 when there is neither. A
// conflicting write (another build reserved first) is read again and the next taken.
// conflicting write (another build reserved first) is read again and the next taken. A reservation standing for the same
// fingerprint whose version is not released and is above the catalog's highest is kept and answered as it stands, a build again or a re-run after a restart
// alike (design 47 H H-A-225, which amends G A-490b): the run already building carries that number. A reservation another
// fingerprint takes over is withdrawn: its version is kept in Withdrawn, and Took is told so the older build is ended.
func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts []string, src Source) (ReservedVersion, error) {
if r.Filled != nil && !r.Filled() {
return ReservedVersion{}, ErrNotFilled
@@ -165,25 +225,50 @@ func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts
}
}
key := ReservedKey(module, series)
held := r.heldNumbers(ctx, module, series, src.Fingerprint, artifacts)
for {
cur, rev, found, err := r.get(ctx, key)
if err != nil {
return ReservedVersion{}, err
}
withdrawn := found && hasKey(cur.Withdrawn, cur.Version) // a number a registry holds elsewhere (H-A-279)
if found && !withdrawn && cur.Fingerprint == src.Fingerprint && cur.Fingerprint != "" && !slices.Contains(released, cur.Version) {
if _, p, err := SplitVersion(cur.Version); err == nil && p > high {
return cur, nil // kept until released (H-A-225); one at or below the catalog's highest can never be released
}
}
next := high
if found && !(src.Rebuild && cur.Fingerprint == src.Fingerprint) {
if found && (withdrawn || !(src.Rebuild && cur.Fingerprint == src.Fingerprint)) { // a withdrawn number is never taken again (H-A-226)
if _, p, err := SplitVersion(cur.Version); err == nil && p > next {
next = p
}
}
out := ReservedVersion{V: 1, Module: module, Series: series, Version: fmt.Sprintf("%s.%d", series, next+1), Artifacts: map[string]string{}, At: r.now(),
Repository: src.Repository, Commit: src.Commit, Fingerprint: src.Fingerprint, Branch: src.Branch, Source: src.Revision}
patch, skipped := nextFree(series, next, held)
out := ReservedVersion{V: 1, Module: module, Series: series, Version: fmt.Sprintf("%s.%d", series, patch), Artifacts: map[string]string{}, At: r.now(),
Repository: src.Repository, Commit: src.Commit, Fingerprint: src.Fingerprint, Branch: src.Branch, Source: src.Revision, Revision: src.CatalogRevision}
if src.GoPackage {
out.Tag = GoTagOf(out.Version)
}
for _, a := range artifacts {
out.Artifacts[a] = ""
}
if found {
out.Withdrawn = maps.Clone(cur.Withdrawn)
if cur.Fingerprint != src.Fingerprint {
if out.Withdrawn == nil {
out.Withdrawn = map[string]string{}
}
out.Withdrawn[cur.Version] = cur.Fingerprint // a dropped number stays a gap (H-A-226)
}
// One at or below the catalog's highest released is refused by the plain rule anyway: the map never grows without end.
maps.DeleteFunc(out.Withdrawn, func(v, _ string) bool {
_, p, err := SplitVersion(v)
return err != nil || p <= high
})
if len(out.Withdrawn) == 0 {
out.Withdrawn = nil
}
}
raw, _ := json.Marshal(out)
if found {
_, err = r.Store.Update(ctx, key, raw, rev)
@@ -196,6 +281,10 @@ func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts
if err != nil {
return ReservedVersion{}, fmt.Errorf("%s cannot be reserved: %w", key, err)
}
r.said(r.reindex(ctx, key, cur, out)) // cur is zero when there was none
if len(skipped) > 0 && r.HeldElsewhere != nil {
r.HeldElsewhere(ctx, module, skipped)
}
if found && r.Took != nil {
r.Took(ctx, cur, out)
}
@@ -215,6 +304,38 @@ func (r *Reserver) get(ctx context.Context, key string) (ReservedVersion, uint64
return v, rev, true, nil
}
// Withdraw withdraws module's reservation of version for the build of its fingerprint, whose number a registry holds at another
// digest (design 47 H H-A-275, H-A-279): the number is kept in Withdrawn and stays a gap (H-A-226), so the build again of that
// fingerprint reserves the next number no registry holds, with fresh digests. It answers the reservation as withdrawn, and false
// when none stands at version.
func (r *Reserver) Withdraw(ctx context.Context, module, version string) (ReservedVersion, bool, error) {
series, _, err := SplitVersion(version)
if err != nil {
return ReservedVersion{}, false, err
}
key := ReservedKey(module, series)
for {
cur, rev, found, err := r.get(ctx, key)
if err != nil || !found || cur.Version != version {
return cur, false, err
}
if hasKey(cur.Withdrawn, version) {
return cur, true, nil
}
if cur.Withdrawn == nil {
cur.Withdrawn = map[string]string{}
}
cur.Withdrawn[version] = cur.Fingerprint
raw, _ := json.Marshal(cur)
if _, err := r.Store.Update(ctx, key, raw, rev); errors.Is(err, ErrConflict) {
continue
} else if err != nil {
return cur, false, fmt.Errorf("%s cannot be withdrawn: %w", key, err)
}
return cur, true, nil
}
}
// Built records artifact's digest under the reserved version of module's series; once every artifact has one the build is
// ended (BuiltAt). A reservation moved on to another version (a newer build took the next) is left alone and answers false.
func (r *Reserver) Built(ctx context.Context, module, version, artifact, digest string, deps []meshbuilds.Dependency) (bool, error) {
@@ -228,6 +349,8 @@ func (r *Reserver) Built(ctx context.Context, module, version, artifact, digest
if err != nil || !found || cur.Version != version {
return false, err
}
was := cur
was.Artifacts = maps.Clone(cur.Artifacts)
cur.Artifacts[artifact] = digest
if len(deps) > 0 {
if cur.Dependencies == nil {
@@ -244,6 +367,7 @@ func (r *Reserver) Built(ctx context.Context, module, version, artifact, digest
} else if err != nil {
return false, fmt.Errorf("%s cannot be written: %w", key, err)
}
r.said(r.reindex(ctx, key, was, cur))
return true, nil
}
}
@@ -295,23 +419,6 @@ func (r *Reserver) ReleasedFor(ctx context.Context, module, fingerprint string)
return false, nil
}
// NewestReleased is the newest version the builder's own record of releases keeps for module (design 47 H H-A-165): a
// package with no pin is built against it; false when the record holds none.
func (r *Reserver) NewestReleased(ctx context.Context, module string) (string, bool, error) {
if r.Releases == nil {
return "", false, nil
}
raw, _, found, err := r.Releases.Get(ctx, ReleasedKey(module))
if err != nil || !found {
return "", false, err
}
var rec ReleasedRecord
if json.Unmarshal(raw, &rec) != nil || len(rec.Kept) == 0 {
return "", false, nil
}
return rec.Kept[len(rec.Kept)-1].Version, true, 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
@@ -379,6 +486,7 @@ func (r *Reserver) Released(ctx context.Context, module, version string) ([]stri
if err := r.Store.Delete(ctx, k); err != nil {
return gone, fmt.Errorf("%s cannot be deleted: %w", k, err)
}
r.said(r.reindex(ctx, k, cur, ReservedVersion{}))
gone = append(gone, k)
}
sort.Strings(gone)
@@ -442,15 +550,39 @@ func (r *Reserver) All(ctx context.Context) ([]ReservedVersion, error) {
return out, nil
}
// TakenOver is the reservation of module's series whose withdrawn numbers hold one of the build of fingerprint (design 47 H
// H-A-226), and whether there is one: the series moved to that reservation's fingerprint and version (H-A-244).
func (r *Reserver) TakenOver(ctx context.Context, module, fingerprint string) (ReservedVersion, bool, error) {
all, err := r.All(ctx)
if err != nil {
return ReservedVersion{}, false, err
}
for _, v := range all {
if v.Module != module || v.Fingerprint == fingerprint {
continue
}
for _, fp := range v.Withdrawn {
if fp == fingerprint {
return v, true, nil
}
}
}
return ReservedVersion{}, false, nil
}
// Drop deletes module's reservation of series on a person's word (builder_reserved_drop); the caller writes the hand-act
// log. It answers whether there was one.
func (r *Reserver) Drop(ctx context.Context, module, series string) (bool, error) {
key := ReservedKey(module, series)
_, _, found, err := r.get(ctx, key)
cur, _, found, err := r.get(ctx, key)
if err != nil || !found {
return false, err
}
return true, r.Store.Delete(ctx, key)
if err := r.Store.Delete(ctx, key); err != nil {
return true, err
}
r.said(r.reindex(ctx, key, cur, ReservedVersion{}))
return true, nil
}
// Marked is an artifact of a reservation a registry seat's published newly marked: the reservation as it stands then.
@@ -460,77 +592,147 @@ type Marked struct {
}
// PackagePublished is the seat mesh-builds' package-published of one artifact the holder said published at the reservation's
// version (design 47 G §52, §334, §673, A-57): the artifact reference, the version and the digest published, the watched branch and
// the source revision the build was made from, and the dependencies its step result named.
// version (design 47 G §52, §334, §673, A-57): the artifact reference, the version and the digest published, the watched branch,
// the source revision the build was made from and the catalog revision its step ask named (H-A-218), and the dependencies its
// step result named.
func (m Marked) PackagePublished(digest string, at time.Time) meshbuilds.PackagePublished {
at = at.UTC()
return meshbuilds.PackagePublished{V: 1, Artifact: m.Artifact, At: &at, Branch: m.Reserved.Branch, Source: m.Reserved.Source, Module: m.Reserved.Module,
return meshbuilds.PackagePublished{V: 1, Artifact: m.Artifact, At: &at, Branch: m.Reserved.Branch, Source: m.Reserved.Source, Revision: m.Reserved.Revision, Module: m.Reserved.Module,
Version: m.Reserved.Version, Digest: digest, Dependencies: m.Reserved.Dependencies[m.Artifact]}
}
// Published takes a registry seat's published in: the artifacts of a reservation at version (a leading v is the Go form)
// whose built digest it names are marked published. It answers each artifact it newly marked, with the reservation as marked.
// A published that marks no artifact of a reservation at version whose build has not recorded every digest is kept on that
// reservation as heard (name, version, digest), and the keys it is kept on are answered too (design 47 G A-415): Kept marks
// it when the build records its digests.
// Published takes a registry seat's published in, as PublishedRead does, answering the artifacts newly marked and the keys it is
// kept on.
func (r *Reserver) Published(ctx context.Context, name, version, digest string) ([]Marked, []string, error) {
out, err := r.PublishedRead(ctx, name, version, digest, nil)
return out.Marked, out.Kept, err
}
// ReadReservation is a reservation a published read, as it stood after the published was taken in, and whether one of its built
// digests is the published's (design 47 H H-A-280).
type ReadReservation struct {
Key string
Reserved ReservedVersion
Matched bool
}
// PublishedOutcome is what a published did: the artifacts it newly marked, the keys it is kept on (A-415), and every reservation it
// read, each once, which the journal line is made from (H-A-280).
type PublishedOutcome struct {
Marked []Marked
Kept []string
Read []ReadReservation
}
// PublishedRead takes a registry seat's published in: the artifacts of a reservation at version (a leading v is the Go form)
// whose built digest it names are marked published. A published that marks no artifact of a reservation at version whose build
// has not recorded every digest is kept on that reservation as heard (name, version, digest), and the keys it is kept on are
// answered (design 47 G A-415): Kept marks it when the build records its digests. The reservation is found through the index
// (H-A-269 (1), H-A-271, H-A-280): the reservations holding the digest in one read, and only when none at version holds it, those
// at the version whose build has not recorded every digest in one more; never a scan of every reservation, and each reservation
// read at most once (again only on a write that met another). slow is told before the second pass, which may read many, so the
// caller can say in progress to the bus; nil is told nothing.
func (r *Reserver) PublishedRead(ctx context.Context, name, version, digest string, slow func()) (PublishedOutcome, error) {
version = strings.TrimPrefix(version, "v")
var out PublishedOutcome
if version == "" || digest == "" {
return nil, nil, nil
return out, nil
}
keys, err := r.Store.KeysOf(ctx, AllFilter)
keys, err := r.indexed(ctx, IndexDigestKey(digest))
if err != nil {
return nil, nil, fmt.Errorf("the reservations cannot be listed: %w", err)
return out, fmt.Errorf("the index of digest %s cannot be read: %w", digest, err)
}
sort.Strings(keys)
var marked []Marked
var kept []string
read := map[string]readOne{}
matched, err := r.publishedOn(ctx, keys, name, version, digest, false, read, &out)
if err != nil || matched {
return out, err
}
keys, err = r.indexed(ctx, IndexUnbuiltKey(version))
if err != nil {
return out, fmt.Errorf("the index of the unbuilt at version %s cannot be read: %w", version, err)
}
if len(keys) > 0 && slow != nil {
slow()
}
_, err = r.publishedOn(ctx, keys, name, version, digest, true, read, &out)
return out, err
}
// readOne is a reservation as one pass read it, kept so the next pass reads it no more.
type readOne struct {
v ReservedVersion
rev uint64
ok bool
}
// publishedOn takes a published in on the reservations under keys: an artifact whose built digest it names is marked; with keep,
// a reservation at version whose build has not recorded every digest and that it matches nothing of keeps it (A-415). A
// reservation read by an earlier pass (read) is taken as read; each read is added to out.Read once. It answers whether a
// reservation at version holds the digest.
func (r *Reserver) publishedOn(ctx context.Context, keys []string, name, version, digest string, keep bool, read map[string]readOne, out *PublishedOutcome) (bool, error) {
anyMatched := false
for _, k := range keys {
again:
cur, rev, found, err := r.get(ctx, k)
if err != nil {
return marked, kept, err
}
if !found || cur.Version != version {
continue
}
changed, matched, keep := false, false, false
var arts []string
for a, d := range cur.Artifacts {
if d != digest {
continue
}
matched = true
if !cur.Published[a] {
if cur.Published == nil {
cur.Published = map[string]bool{}
one, seen := read[k]
for {
if !seen {
cur, rev, found, err := r.get(ctx, k)
if err != nil {
return anyMatched, err
}
cur.Published[a], changed = true, true
arts = append(arts, a)
one = readOne{v: cur, rev: rev, ok: found}
}
}
sort.Strings(arts)
if !matched && cur.BuiltAt.IsZero() && !cur.keeps(name, digest) {
cur.Kept = append(cur.Kept, KeptPublished{Name: name, Version: version, Digest: digest})
changed, keep = true, true
}
if !changed {
continue
}
raw, _ := json.Marshal(cur)
if _, err := r.Store.Update(ctx, k, raw, rev); errors.Is(err, ErrConflict) {
goto again
} else if err != nil {
return marked, kept, fmt.Errorf("%s cannot be written: %w", k, err)
}
for _, a := range arts {
marked = append(marked, Marked{Reserved: cur, Artifact: a})
}
if keep {
kept = append(kept, k)
seen = false // a write that meets another reads again
cur := one.v
if !one.ok || cur.Version != version {
read[k] = one
break
}
changed, matched, keepIt := false, false, false
var arts []string
for a, d := range cur.Artifacts {
if d != digest {
continue
}
matched = true
if !cur.Published[a] {
cur.Published = maps.Clone(cur.Published)
if cur.Published == nil {
cur.Published = map[string]bool{}
}
cur.Published[a], changed = true, true
arts = append(arts, a)
}
}
sort.Strings(arts)
if keep && !matched && cur.BuiltAt.IsZero() && !cur.keeps(name, digest) {
cur.Kept = append(slices.Clone(cur.Kept), KeptPublished{Name: name, Version: version, Digest: digest})
changed, keepIt = true, true
}
rev := one.rev
if changed {
raw, _ := json.Marshal(cur)
var err error
if rev, err = r.Store.Update(ctx, k, raw, one.rev); errors.Is(err, ErrConflict) {
continue
} else if err != nil {
return anyMatched, fmt.Errorf("%s cannot be written: %w", k, err)
}
for _, a := range arts {
out.Marked = append(out.Marked, Marked{Reserved: cur, Artifact: a})
}
if keepIt {
out.Kept = append(out.Kept, k)
}
}
anyMatched = anyMatched || matched
if _, was := read[k]; !was {
out.Read = append(out.Read, ReadReservation{Key: k, Reserved: cur, Matched: matched})
}
read[k] = readOne{v: cur, rev: rev, ok: true}
break
}
}
return marked, kept, nil
return anyMatched, nil
}
func (v ReservedVersion) keeps(name, digest string) bool {
@@ -722,11 +924,24 @@ func AnswerReservedByName(ctx context.Context, r Reader, carriers func(context.C
}
return out, nil
}
if series, _, err := SplitVersion(version); err == nil {
if cur, _, found, err := rs.get(ctx, ReservedKey(module, series)); err == nil && found && hasKey(cur.Withdrawn, version) {
// A late publish of a build a take-over withdrew (H-A-225): refused as what it is.
return meshbuilds.ReservedAnswer{Error: fmt.Sprintf("%s (%s) version %s was withdrawn: the build of %s it was reserved for was taken over by %s, which reserves %s",
name, module, version, cur.Withdrawn[version], cur.Fingerprint, cur.Version)}, nil
}
}
return meshbuilds.ReservedAnswer{Error: fmt.Sprintf("%s (%s) has no version %s reserved or released", name, module, version)}, nil
}
return meshbuilds.ReservedAnswer{Error: fmt.Sprintf("%s (%s) has no reserved version", name, module)}, nil
}
// hasKey says whether m holds k.
func hasKey(m map[string]string, k string) bool {
_, ok := m[k]
return ok
}
// NoEntryCarries opens the answer of reserved given a name no entry carries.
const NoEntryCarries = "no entry carries the name "
@@ -125,7 +125,7 @@ func TestReservationIsReadAndMarkedPublished(t *testing.T) {
ctx := context.Background()
store := &reserveMem{mem: newMem()}
r := &Reserver{Store: store, ReleasedOf: func(context.Context, string) ([]string, error) { return []string{"1.4.2"}, nil }}
v, err := r.Reserve(ctx, "m", "1.4", []string{"m:a", "m:b"}, Source{Branch: "main", Revision: 41})
v, err := r.Reserve(ctx, "m", "1.4", []string{"m:a", "m:b"}, Source{Branch: "main", Revision: 41, CatalogRevision: 44})
if err != nil || v.Version != "1.4.3" {
t.Fatalf("reserved %q (%v), want 1.4.3", v.Version, err)
}
@@ -154,12 +154,12 @@ func TestReservationIsReadAndMarkedPublished(t *testing.T) {
if err != nil || len(marked) != 1 {
t.Fatalf("a published of 1.4.3 with a built digest marked %v (%v)", marked, err)
}
// Design 47 G §52, §673, A-57: the package-published of that artifact carries the digest published, the branch and the source
// revision the reservation was made for, and the dependencies its step result named.
// Design 47 G §52, §673, A-57: the package-published of that artifact carries the digest published, the branch, the source
// revision and the catalog revision (H-A-218) the reservation was made for, and the dependencies its step result named.
at := time.Unix(100, 0)
said := marked[0].PackagePublished("sha256:aa", at)
atUTC := at.UTC()
if wantSaid := (meshbuilds.PackagePublished{V: 1, Artifact: "m:a", At: &atUTC, Branch: "main", Source: 41, Module: "m", Version: "1.4.3", Digest: "sha256:aa", Dependencies: deps}); !reflect.DeepEqual(said, wantSaid) {
if wantSaid := (meshbuilds.PackagePublished{V: 1, Artifact: "m:a", At: &atUTC, Branch: "main", Source: 41, Revision: 44, Module: "m", Version: "1.4.3", Digest: "sha256:aa", Dependencies: deps}); !reflect.DeepEqual(said, wantSaid) {
t.Errorf("package-published = %+v, want %+v", said, wantSaid)
}
if marked, _, _ := r.Published(ctx, "m-a", "1.4.3", "sha256:other"); len(marked) != 0 {
@@ -201,13 +201,11 @@ func TestAReleaseIsRecordedByFingerprintBeforeItsReservationGoes(t *testing.T) {
t.Errorf("reservations left: %v", all)
}
// One key per module holds the last releases, the oldest dropped (A-456b).
newest := ""
for _, fp := range []string{"src2:b1", "src2:b2"} {
n, err := r.Reserve(ctx, "m", "0.1", []string{"m:a"}, Source{Fingerprint: fp})
if err != nil {
t.Fatal(err)
}
newest = n.Version
if _, err := r.Released(ctx, "m", n.Version); err != nil {
t.Fatal(err)
}
@@ -221,27 +219,55 @@ func TestAReleaseIsRecordedByFingerprintBeforeItsReservationGoes(t *testing.T) {
if ok, _ := r.ReleasedFor(ctx, "m", "src2:b2"); !ok {
t.Error("the newest release is not kept")
}
// H-A-165: the newest version the record keeps is the pin of a package with none.
if v, ok, err := r.NewestReleased(ctx, "m"); !ok || err != nil || v != newest {
t.Errorf("newest released of m = %q, %v (%v), want %s", v, ok, err, newest)
}
// 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.
func TestTheWithdrawnVersionsAreDroppedOnceReleasedPast(t *testing.T) {
ctx := context.Background()
store := &reserveMem{mem: newMem()}
highest := "0.1.3"
r := &Reserver{Store: store, Filled: func() bool { return true },
ReleasedOf: func(context.Context, string) ([]string, error) { return []string{highest}, nil }}
for _, fp := range []string{"src2:a", "src2:b", "src2:c"} {
if _, err := r.Reserve(ctx, "m", "0.1", []string{"m:a"}, Source{Fingerprint: fp}); err != nil {
t.Fatal(err)
}
}
if _, ok, _ := r.NewestReleased(ctx, "other"); ok {
t.Error("a module never released has a newest release")
cur, _, _, _ := r.get(ctx, ReservedKey("m", "0.1"))
if cur.Version != "0.1.6" || len(cur.Withdrawn) != 2 || cur.Withdrawn["0.1.4"] != "src2:a" || cur.Withdrawn["0.1.5"] != "src2:b" {
t.Fatalf("reservation %+v; want 0.1.6 with 0.1.4 and 0.1.5 withdrawn", cur)
}
// H-A-244: the build whose number was withdrawn finds the reservation its series moved to; the one standing finds none.
if by, took, err := r.TakenOver(ctx, "m", "src2:a"); err != nil || !took || by.Fingerprint != "src2:c" || by.Version != "0.1.6" {
t.Errorf("taken over from src2:a by %+v (%v, %v); want src2:c 0.1.6", by, took, err)
}
if _, took, err := r.TakenOver(ctx, "m", "src2:c"); err != nil || took {
t.Errorf("the standing build src2:c is said taken over (%v, %v)", took, err)
}
highest = "0.1.5" // the catalog released past both withdrawn numbers but the newest
got, err := r.Reserve(ctx, "m", "0.1", []string{"m:a"}, Source{Fingerprint: "src2:d"})
if err != nil || got.Version != "0.1.7" || len(got.Withdrawn) != 1 || got.Withdrawn["0.1.6"] != "src2:c" {
t.Errorf("reserved %+v (%v); want 0.1.7 keeping only 0.1.6 withdrawn", got, err)
}
}
// TestARebuildReservesAboveTheCatalogsHighestWhateverItsStandingNumberWas: design 47 G A-490b — a build again of a done key replaces
// its fingerprint's standing reservation (and tells Took) and numbers above the catalog's highest alone, whether the standing number
// is below it or above it; another fingerprint's standing reservation stays a floor.
// TestARebuildReservesAboveTheCatalogsHighestWhateverItsStandingNumberWas: design 47 G A-490b as H-A-225 amends it — a build again
// of a done key, or a re-run after a restart, keeps its fingerprint's standing reservation while it is unreleased and above the
// catalog's highest; one at or below it is replaced (Took told) by the next above the catalog's highest alone; another
// fingerprint's standing reservation stays a floor and is withdrawn.
func TestARebuildReservesAboveTheCatalogsHighestWhateverItsStandingNumberWas(t *testing.T) {
ctx := context.Background()
for _, c := range []struct {
name, standing, standingFp string
want string
rebuild, kept bool
}{
{name: "standing below the catalog's highest", standing: "0.1.0", standingFp: "fp", want: "0.1.17"},
{name: "standing above the catalog's highest", standing: "0.1.30", standingFp: "fp", want: "0.1.17"},
{name: "another fingerprint's standing number stays a floor", standing: "0.1.30", standingFp: "other", want: "0.1.31"},
{name: "standing below the catalog's highest", standing: "0.1.0", standingFp: "fp", want: "0.1.17", rebuild: true},
{name: "H-A-225: standing above the catalog's highest is kept by a build again", standing: "0.1.30", standingFp: "fp", want: "0.1.30", rebuild: true, kept: true},
{name: "H-A-225: a re-run after a restart keeps its standing number", standing: "0.1.111", standingFp: "fp", want: "0.1.111", kept: true},
{name: "another fingerprint's standing number stays a floor", standing: "0.1.30", standingFp: "other", want: "0.1.31", rebuild: true},
} {
t.Run(c.name, func(t *testing.T) {
store := &reserveMem{mem: newMem()}
@@ -255,10 +281,68 @@ func TestARebuildReservesAboveTheCatalogsHighestWhateverItsStandingNumberWas(t *
r.Took = func(_ context.Context, older, newer ReservedVersion) {
took = append(took, older.Version+">"+newer.Version)
}
got, err := r.Reserve(ctx, "m", "0.1", []string{"m:a"}, Source{Fingerprint: "fp", Rebuild: true})
got, err := r.Reserve(ctx, "m", "0.1", []string{"m:a"}, Source{Fingerprint: "fp", Rebuild: c.rebuild})
if c.kept {
if err != nil || got.Version != c.want || len(took) != 0 || got.Artifacts["m:a"] != "d" {
t.Fatalf("reserved %+v (%v), took %v; want the standing %s kept as it stands", got, err, took, c.want)
}
return
}
if err != nil || got.Version != c.want || len(took) != 1 || took[0] != c.standing+">"+c.want {
t.Fatalf("reserved %q (%v), took %v; want %s replacing %s", got.Version, err, took, c.want, c.standing)
}
if w := got.Withdrawn[c.standing]; (c.standingFp != "fp") != (w == c.standingFp) {
t.Errorf("withdrawn %v; want %s withdrawn only when another fingerprint stood", got.Withdrawn, c.standing)
}
})
}
}
// TestANumberARegistryHoldsIsNeverReserved: design 47 H H-A-275 (the rule of H-A-245 for a registry's record) — a reserve skips
// every number a registry seat holds of the module's artifacts and says the skipped ones; a read that fails lets it proceed; a
// done build whose number a registry holds at another digest has it withdrawn as a gap (H-A-226), and its build again reserves the
// next free number with fresh digests (H-A-279), the index following it.
func TestANumberARegistryHoldsIsNeverReserved(t *testing.T) {
ctx := context.Background()
store := &reserveMem{mem: newMem()}
held := []string{"0.1.37", "0.1.38", "0.2.0"}
var readErr error
var skipped []string
r := &Reserver{Store: store, ReleasedOf: func(context.Context, string) ([]string, error) { return []string{"0.1.36"}, nil },
HeldNumbers: func(_ context.Context, module, fp string, refs []string) ([]string, error) {
if module != "node-tools" || fp != "fp1" || len(refs) != 1 {
t.Errorf("the registries are read for %s %s %v", module, fp, refs)
}
return held, readErr
},
HeldElsewhere: func(_ context.Context, _ string, s []string) { skipped = append(skipped, s...) }}
v, err := r.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, Source{Fingerprint: "fp1", GoPackage: true})
if err != nil || v.Version != "0.1.39" || len(skipped) != 2 {
t.Fatalf("reserved %q (%v), skipped %v: want 0.1.39 past the two numbers the registry holds", v.Version, err, skipped)
}
// The build ends; the registry holds 0.1.39 at another digest meanwhile: the number is withdrawn, and the build again of the same
// fingerprint reserves the next number no registry holds, with no digest yet (H-A-279).
if _, err := r.Built(ctx, "node-tools", "0.1.39", "node-tools:program", "sha256:7c9b10", nil); err != nil {
t.Fatal(err)
}
if w, ok, err := r.Withdraw(ctx, "node-tools", "0.1.39"); err != nil || !ok || w.Withdrawn["0.1.39"] != "fp1" {
t.Fatalf("withdrew %+v (%v %v), want 0.1.39 withdrawn for fp1", w, ok, err)
}
held = []string{"0.1.37", "0.1.38", "0.1.39", "0.1.40", "0.2.0"}
// The build again of a done key reserves as a rebuild (A-490b): a withdrawn number is never its floor's to reuse.
again, err := r.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, Source{Fingerprint: "fp1", GoPackage: true, Rebuild: true})
if err != nil || again.Version != "0.1.41" || again.Artifacts["node-tools:program"] != "" || again.Withdrawn["0.1.39"] != "fp1" || again.Tag != GoTagOf("0.1.41") {
t.Fatalf("the build again reserved %+v (%v), want 0.1.41 with no digest and 0.1.39 kept withdrawn", again, err)
}
if at, _ := r.AtVersion(ctx, "0.1.39"); len(at) != 0 {
t.Errorf("the index by version still names the withdrawn number: %v", at)
}
if _, ok, _ := r.Withdraw(ctx, "node-tools", "0.1.39"); ok {
t.Error("a number no reservation stands at any more was withdrawn")
}
// A registry that cannot be read lets the reserve proceed.
readErr, skipped = errors.New("registry down"), nil
if v, err := r.Reserve(ctx, "node-tools", "0.2", []string{"node-tools:program"}, Source{Fingerprint: "fp1"}); err != nil || v.Version != "0.2.1" {
t.Errorf("with the registry down reserved %q (%v), want 0.2.1 (what it answered still skipped)", v.Version, err)
}
}
@@ -67,6 +67,20 @@ func TestReservedByNameAnswersFromTheViewAndTheCatalog(t *testing.T) {
t.Errorf("%s = %+v, want error naming %q alone", name, got, c.want)
}
}
// H-A-225: another fingerprint taking the series over withdraws the older's version; a late publish of it is refused as
// withdrawn, naming the fingerprint that took it over, never as a version that was never reserved.
if _, err := r.Reserve(ctx, "mesh-sdk", "0.1", []string{"mesh-sdk:ts"}, Source{Fingerprint: "src2:a"}); err != nil {
t.Fatal(err)
}
if _, err := r.Reserve(ctx, "mesh-sdk", "0.1", []string{"mesh-sdk:ts"}, Source{Fingerprint: "src2:b"}); err != nil {
t.Fatal(err)
}
if got := ask("@novox/mesh-sdk", "0.1.5"); !strings.Contains(got.Error, "version 0.1.5 was withdrawn: the build of src2:a it was reserved for was taken over by src2:b, which reserves 0.1.6") {
t.Errorf("a late publish of a withdrawn version = %+v, want refused as withdrawn", got)
}
if got := ask("@novox/mesh-sdk", "9.9.9"); !strings.Contains(got.Error, "reserved or released") {
t.Errorf("a version never reserved = %+v, want refused as neither reserved nor released", got)
}
if _, err := AnswerReservedByName(ctx, rd, Carriers(packagesMem(nil)), released, "x", ""); err == nil {
t.Error("an unreadable view was answered as if no entry carried the name")
}
@@ -4,12 +4,28 @@ import (
"context"
"errors"
"fmt"
"strings"
"time"
)
// AllFilter is the key filter of every version of every name: two tokens.
const AllFilter = "*.*"
// FilterMatches says whether key is under filter as the bus reads a key filter: token by token, a `*` any one token, so AllFilter
// lists the two-token keys alone and never the index's three-token keys (H-A-269 (1)).
func FilterMatches(filter, key string) bool {
ft, kt := strings.Split(filter, "."), strings.Split(key, ".")
if len(ft) != len(kt) {
return false
}
for i := range ft {
if ft[i] != "*" && ft[i] != kt[i] {
return false
}
}
return true
}
// ErrConflict is what a Store answers when a Create finds the key or an Update finds another revision.
var ErrConflict = errors.New("the key exists or changed")
@@ -21,10 +21,59 @@ const (
OldFormClosedEvent = "version.old-form-closed"
)
// Reader reads the state as the tools bundle may: every key, and one.
// Reader reads the state as the tools bundle may: every key, and one; and, where All is set, the state's values in one page,
// one request for many (design 47 H H-A-290 (5), H-A-292).
type Reader struct {
Keys func() ([]string, error)
Get func(key string) (json.RawMessage, bool, error)
// All is one page of the state's values; nil, or an error satisfying errors.Is(err, errors.ErrUnsupported), reads key by key.
All func() (StatePage, error)
}
// StatePage is one page of a state (H-A-292, H-A-293): its values, and, when the state holds more than the page, More with the
// state's size as its info says it (Keys, Bytes; InfoWords when the info cannot be read). No second page is asked.
type StatePage struct {
Values map[string]json.RawMessage
More bool
Keys, Bytes uint64
InfoWords string
}
// StateCapped is what an answer says of a state it read only the first page of (H-A-293): how many keys it read, and the
// state's size from its info.
type StateCapped struct {
State string `json:"state"`
KeysRead int `json:"keys-read"`
StateKeys uint64 `json:"state-keys"`
StateBytes uint64 `json:"state-bytes"`
InfoWords string `json:"info,omitempty"`
}
// values is the state's values: one page where the reader can (capped says what a page past the state's end left out), else
// key by key.
func (r Reader) values(state string) (map[string]json.RawMessage, *StateCapped, error) {
if r.All != nil {
pg, err := r.All()
if !errors.Is(err, errors.ErrUnsupported) {
if err != nil || !pg.More {
return pg.Values, nil, err
}
return pg.Values, &StateCapped{State: state, KeysRead: len(pg.Values), StateKeys: pg.Keys, StateBytes: pg.Bytes, InfoWords: pg.InfoWords}, nil
}
}
keys, err := r.Keys()
if err != nil {
return nil, nil, err
}
out := make(map[string]json.RawMessage, len(keys))
for _, k := range keys {
raw, ok, err := r.Get(k)
if err != nil || !ok {
continue
}
out[k] = raw
}
return out, nil, nil
}
// readStore is a Store over a Reader that refuses every write: the tools bundle only reads versions.
@@ -45,13 +94,9 @@ func (s readStore) KeysOf(_ context.Context, filter string) ([]string, error) {
if err != nil {
return nil, err
}
if filter == AllFilter {
return all, nil
}
prefix := strings.TrimSuffix(filter, "*")
var out []string
for _, k := range all {
if strings.HasPrefix(k, prefix) && !strings.Contains(k[len(prefix):], ".") {
if FilterMatches(filter, k) {
out = append(out, k)
}
}
@@ -66,21 +66,9 @@ func (m *mem) KeysOf(_ context.Context, filter string) ([]string, error) {
if m.down != nil {
return nil, m.down
}
prefix := strings.TrimSuffix(filter, "*")
var out []string
for k := range m.vals {
if filter == AllFilter {
out = append(out, k)
continue
}
if strings.Count(filter, ".") == 2 { // a three-token filter, `a.*.*` as the bus reads it
ft, kt := strings.Split(filter, "."), strings.Split(k, ".")
if len(kt) == 3 && kt[0] == ft[0] {
out = append(out, k)
}
continue
}
if strings.HasPrefix(k, prefix) && !strings.Contains(k[len(prefix):], ".") {
if FilterMatches(filter, k) { // token by token, as the bus reads a filter
out = append(out, k)
}
}
+10 -4
View File
@@ -266,10 +266,16 @@ func TestManifestProcess(t *testing.T) { // 1607/AC1
if _, bus := p["bus"]; bus {
t.Errorf("the process declares a bus: it runs on its own broker credential")
}
// Issue 1966's bootstrap: the package artifact builds is out of the manifest until the new builder runs; the follow-up
// puts it back with its assertion (ADR 0634 §1, ADR 0606 §4: three artifacts, the third the package builds).
if len(m.Build.Artifacts) != 2 {
t.Fatalf("artifacts = %+v, want the program and the tools", m.Build.Artifacts)
// H-A-186, design 47 G §370: a Go package another module imports is a declared package artifact of its module, so every
// release publishes it: builds (ADR 0634 §1, ADR 0606 §4), imported by the build modules and the node-engine, and
// buildrun, imported by the indexer, the view and the watchman.
if len(m.Build.Artifacts) != 4 {
t.Fatalf("artifacts = %+v, want the program, the tools and the packages builds and buildrun", m.Build.Artifacts)
}
for i, name := range []string{"builds", "buildrun"} {
if a := m.Build.Artifacts[2+i]; a.Name != name || a.Kind != "package" || a.Language != "go" || !reflect.DeepEqual(a.Paths, []string{name}) || a.Series != "0.1" {
t.Errorf("package artifact = %+v, want the Go package %s of series 0.1", a, name)
}
}
if a := m.Build.Artifacts[1]; a.Name != "tools" || a.Kind != "bundle" || a.Binary != "mesh-delivery-builder-tools" || !reflect.DeepEqual(a.Loads, []string{"mesh-delivery-builder-tools"}) {
t.Errorf("tools artifact = %+v", a) // 1945
+18
View File
@@ -334,6 +334,24 @@
"loads": [
"mesh-delivery-builder-tools"
]
},
{
"name": "builds",
"kind": "package",
"language": "go",
"paths": [
"builds"
],
"series": "0.1"
},
{
"name": "buildrun",
"kind": "package",
"language": "go",
"paths": [
"buildrun"
],
"series": "0.1"
}
]
}
@@ -1,4 +1,7 @@
package meshcatalog
package meshcatalogclient
// The two helpers below are hand-written, so they live in the seat's client, never under its contract's generated
// root (design 47 H, H-A-200; ADR 0608 §5).
import "strings"
@@ -0,0 +1,22 @@
package meshcatalogclient
import "testing"
// An entry's manifest-digest carries sha256: and the module's value and the key of `manifests` the 64 digits bare, one
// digest in two forms (design 47 G §578); the two helpers live in the seat's client, outside its contract's generated
// root (H-A-200).
func TestAManifestDigestIsPrefixedForTheEntryAndBareForTheKey(t *testing.T) {
const bare = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
for _, tc := range []struct{ in, entry, key string }{
{bare, "sha256:" + bare, bare},
{"sha256:" + bare, "sha256:" + bare, bare},
{"", "", ""},
} {
if got := EntryManifestDigest(tc.in); got != tc.entry {
t.Errorf("EntryManifestDigest(%q) = %q, want %q", tc.in, got, tc.entry)
}
if got := BareManifestDigest(tc.in); got != tc.key {
t.Errorf("BareManifestDigest(%q) = %q, want %q", tc.in, got, tc.key)
}
}
}
@@ -17,8 +17,9 @@ import (
// eventPrefix starts every event subject of the seat.
const eventPrefix = "mesh.seat." + seat.Seat + ".event."
// perSource are the events said per source revision, on <event>.<branch>.<source> (design 47 H §746, H-A-72 (3)).
var perSource = []string{seat.EventPipelineStarted, seat.EventPipelineEnded, seat.EventWaitHeld, seat.EventWaitEnded}
// perRevision are the events said per pipeline, on <event>.<branch>.<revision>, its catalog revision's number as its key
// names it (design 47 H §746, H-A-72 (3), H-A-221).
var perRevision = []string{seat.EventPipelineStarted, seat.EventPipelineEnded, seat.EventWaitHeld, seat.EventWaitEnded}
// Subject is where the runner says a step's event or a run's start: mesh.seat.mesh-pipeline-runner.event.<event>.
// <module>.<branch>.<commit>, each name escaped as a key's name is, so a branch holding a dot is one token (design 47 H
@@ -27,41 +28,42 @@ func Subject(event, module, branch, commit string) string {
return eventPrefix + event + "." + keys.EscapeName(module) + "." + keys.EscapeName(branch) + "." + keys.EscapeName(commit)
}
// SourceSubject is where the runner says a pipeline's start and end and its waits: mesh.seat.mesh-pipeline-runner.
// event.<event>.<branch>.<source>, the branch escaped as a key's name is (design 47 H §746, H-A-72 (3)).
func SourceSubject(event, branch string, source int64) string {
return eventPrefix + event + "." + keys.EscapeName(branch) + "." + strconv.FormatInt(source, 10)
// RevisionSubject is where the runner says a pipeline's start and end and its waits: mesh.seat.mesh-pipeline-runner.
// event.<event>.<branch>.<revision>, the pipeline's catalog revision number, the branch escaped as a key's name is (design
// 47 H §746, H-A-72 (3), H-A-221).
func RevisionSubject(event, branch string, revision int64) string {
return eventPrefix + event + "." + keys.EscapeName(branch) + "." + strconv.FormatInt(revision, 10)
}
// Of is what an event's subject names: a step's event or a run's start names the module, the branch and the commit; an
// event per source revision names the branch and the source.
// event per pipeline names the branch and the pipeline's catalog revision (H-A-221).
type Of struct {
Event, Module, Branch, Commit string
Source int64
Revision int64
}
// Parse reads a subject Subject or SourceSubject built: an event of the seat's, and its names unescaped.
// Parse reads a subject Subject or RevisionSubject built: an event of the seat's, and its names unescaped.
func Parse(subject string) (Of, error) {
rest, ok := strings.CutPrefix(subject, eventPrefix)
toks := strings.Split(rest, ".")
bySource := len(toks) > 0 && slices.Contains(perSource, toks[0])
byRevision := len(toks) > 0 && slices.Contains(perRevision, toks[0])
want := 4
if bySource {
if byRevision {
want = 3
}
if !ok || len(toks) != want || !slices.Contains(seat.Events(), toks[0]) {
return Of{}, fmt.Errorf("meshpipelinerunnerclient: %q is no event subject of the seat %s", subject, seat.Seat)
}
if bySource {
if byRevision {
branch, err := keys.UnescapeName(toks[1])
if err != nil || branch == "" {
return Of{}, fmt.Errorf("meshpipelinerunnerclient: %q: branch: %v", subject, err)
}
source, err := strconv.ParseInt(toks[2], 10, 64)
if err != nil || source < 1 {
return Of{}, fmt.Errorf("meshpipelinerunnerclient: %q: no source revision", subject)
revision, err := strconv.ParseInt(toks[2], 10, 64)
if err != nil || revision < 1 {
return Of{}, fmt.Errorf("meshpipelinerunnerclient: %q: no revision", subject)
}
return Of{Event: toks[0], Branch: branch, Source: source}, nil
return Of{Event: toks[0], Branch: branch, Revision: revision}, nil
}
names := make([]string, 0, 3)
for i, t := range toks[1:] {
@@ -17,14 +17,14 @@ func TestSubjectsAndBodies(t *testing.T) {
if of, err := Parse(s); err != nil || of != (Of{Event: seat.EventStepEnded, Module: "nats", Branch: "release.1", Commit: "c1"}) {
t.Errorf("parse %s: %+v, %v", s, of, err)
}
ps := SourceSubject(seat.EventPipelineEnded, "release.1", 3589)
ps := RevisionSubject(seat.EventPipelineEnded, "release.1", 3589)
if ps != "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.release=2e1.3589" {
t.Errorf("pipeline-ended subject %s", ps)
}
if of, err := Parse(ps); err != nil || of != (Of{Event: seat.EventPipelineEnded, Branch: "release.1", Source: 3589}) {
if of, err := Parse(ps); err != nil || of != (Of{Event: seat.EventPipelineEnded, Branch: "release.1", Revision: 3589}) {
t.Errorf("parse %s: %+v, %v", ps, of, err)
}
if of, err := Parse(SourceSubject(seat.EventWaitHeld, "main", 7)); err != nil || of.Source != 7 || of.Module != "" {
if of, err := Parse(RevisionSubject(seat.EventWaitHeld, "main", 7)); err != nil || of.Revision != 7 || of.Module != "" {
t.Errorf("wait-held: %+v, %v", of, err)
}
for _, bad := range []string{"not.an.event.subject",
@@ -95,6 +95,8 @@ type PackagePublished struct {
Digest string `json:"digest"`
// the module
Module string `json:"module"`
// the catalog revision number of that branch the build was made from, the indexer's count (design 47 H-A-218, H-A-220); absent from a reservation made before the field
Revision int64 `json:"revision,omitempty"`
// the source revision of that branch the build was made from
Source int64 `json:"source"`
V int64 `json:"v"`
@@ -114,9 +116,11 @@ type StepEnded struct {
// the node the builder ran it on, as in the subject
Node string `json:"node"`
// never passed for a build that built nothing
Outcome string `json:"outcome"`
Pipeline string `json:"pipeline"`
Rerun bool `json:"rerun,omitempty"`
Outcome string `json:"outcome"`
// the pins the step's entries were built with, each mesh package's version by its module path, the ones the builder took from the registry for a package the entry named with none included; the runner asks the entry's held test steps with them (H-A-207)
Packages map[string]string `json:"packages,omitempty"`
Pipeline string `json:"pipeline"`
Rerun bool `json:"rerun,omitempty"`
// why it failed or could not run: the entry not built, the part not heard
Said string `json:"said,omitempty"`
Started *time.Time `json:"started,omitempty"`
@@ -715,6 +715,10 @@ type CatalogRevision struct {
Base int64 `json:"base,omitempty"`
// the watched branch the revision is of
Branch string `json:"branch,omitempty"`
// what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of <module> <version>, a take-in again's take-in again of <repository>; absent for a candidate's
Call string `json:"call,omitempty"`
// the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's
CallKind string `json:"call-kind,omitempty"`
// the seat definitions it was judged with, each by its digest, read whole through seat-definitions
Definitions []CatalogRevisionDefinitionsItem `json:"definitions,omitempty"`
// one per module, by name
@@ -725,8 +729,12 @@ type CatalogRevision struct {
Heads string `json:"heads,omitempty"`
// trunk or candidate
Kind string `json:"kind"`
// for call-kind release, the module released (H-A-215)
Module string `json:"module,omitempty"`
// the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover
Movers []TakeInEntry `json:"movers,omitempty"`
// for call-kind take-in-again, the repository taken in again (H-A-215)
Repository string `json:"repository,omitempty"`
// the catalog graph revision's number, counted by its holder
Revision int64 `json:"revision"`
// the source revision it was taken in from; for a candidate, the source revision its heads are merged onto
@@ -735,8 +743,18 @@ type CatalogRevision struct {
Trunk []Head `json:"trunk,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
// for call-kind release, the version released (H-A-215)
Version string `json:"version,omitempty"`
}
// The values of CatalogRevision's call-kind.
const (
CatalogRevisionCallKindTakeIn = "take-in"
CatalogRevisionCallKindRelease = "release"
CatalogRevisionCallKindTakeInAgain = "take-in-again"
CatalogRevisionCallKindRecompute = "recompute"
)
// Edge is one edge of the catalog graph between artifact references, B before A (ADR 0666 section 14): kind 1 B published before A builds (a package A imports), 2 B published before A delivers (fetched by reference at its start), 3 B delivered before A builds (its build module and toolchain), 4 B delivered before A delivers (a provision, bus state, a format's reader), 5 B has acted for A's new version (an acting rule), 6 B runs a version that serves A (a verb or a manifest word A uses).
type Edge struct {
// declared in the artifact entry's needs of A's manifest, where nothing else says it
@@ -1301,6 +1319,10 @@ type CatalogRevisionEvent struct {
At *time.Time `json:"at,omitempty"`
// the watched branch the revision is of, escaped as a key name is
Branch string `json:"branch,omitempty"`
// what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's
Call string `json:"call,omitempty"`
// the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's
CallKind string `json:"call-kind,omitempty"`
// the modules whose entries differ from the revision before it of the same kind
Changed []string `json:"changed,omitempty"`
// how many entries it lists
@@ -1308,12 +1330,26 @@ type CatalogRevisionEvent struct {
Group string `json:"group,omitempty"`
Heads string `json:"heads,omitempty"`
// trunk or candidate: a candidate's moves no running part
Kind string `json:"kind"`
Revision int64 `json:"revision"`
Source int64 `json:"source"`
V int64 `json:"v"`
Kind string `json:"kind"`
// for call-kind release, the module released (H-A-215)
Module string `json:"module,omitempty"`
// for call-kind take-in-again, the repository taken in again (H-A-215)
Repository string `json:"repository,omitempty"`
Revision int64 `json:"revision"`
Source int64 `json:"source"`
V int64 `json:"v"`
// for call-kind release, the version released (H-A-215)
Version string `json:"version,omitempty"`
}
// The values of CatalogRevisionEvent's call-kind.
const (
CatalogRevisionEventCallKindTakeIn = "take-in"
CatalogRevisionEventCallKindRelease = "release"
CatalogRevisionEventCallKindTakeInAgain = "take-in-again"
CatalogRevisionEventCallKindRecompute = "recompute"
)
// FillingEvent is the body of the event filling.
type FillingEvent = Fill
@@ -17,7 +17,7 @@ func TestFixtures(t *testing.T) {
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a trunk revision kept, on the seat's subject", subject: "mesh.seat.mesh-catalog.event.catalog-revision.main", given: "{\"at\":\"2026-11-09T19:00:00Z\",\"branch\":\"main\",\"changed\":[\"xclip\"],\"entries\":2,\"kind\":\"trunk\",\"revision\":12,\"source\":3589,\"v\":1}", wire: "{\"at\":\"2026-11-09T19:00:00Z\",\"branch\":\"main\",\"changed\":[\"xclip\"],\"entries\":2,\"kind\":\"trunk\",\"revision\":12,\"source\":3589,\"v\":1}",
{name: "a trunk revision kept, on the seat's subject", subject: "mesh.seat.mesh-catalog.event.catalog-revision.main", given: "{\"at\":\"2026-11-09T19:00:00Z\",\"branch\":\"main\",\"call\":\"release of mesh-sdk 0.1.27\",\"call-kind\":\"release\",\"changed\":[\"xclip\"],\"entries\":2,\"kind\":\"trunk\",\"module\":\"mesh-sdk\",\"revision\":12,\"source\":3589,\"v\":1,\"version\":\"0.1.27\"}", wire: "{\"at\":\"2026-11-09T19:00:00Z\",\"branch\":\"main\",\"call\":\"release of mesh-sdk 0.1.27\",\"call-kind\":\"release\",\"changed\":[\"xclip\"],\"entries\":2,\"kind\":\"trunk\",\"module\":\"mesh-sdk\",\"revision\":12,\"source\":3589,\"v\":1,\"version\":\"0.1.27\"}",
decode: func(b []byte) (any, error) { var v CatalogRevisionEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-catalog\\.event\\.catalog-revision\\.[^.*> ]+$")},
{name: "a candidate's revision kept", subject: "mesh.seat.mesh-catalog.event.catalog-revision.main", given: "{\"branch\":\"main\",\"entries\":2,\"group\":\"feat/47-G\",\"heads\":\"0123456789ab\",\"kind\":\"candidate\",\"revision\":13,\"source\":3589,\"v\":1}", wire: "{\"branch\":\"main\",\"entries\":2,\"group\":\"feat/47-G\",\"heads\":\"0123456789ab\",\"kind\":\"candidate\",\"revision\":13,\"source\":3589,\"v\":1}",
decode: func(b []byte) (any, error) { var v CatalogRevisionEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-catalog\\.event\\.catalog-revision\\.[^.*> ]+$")},
@@ -59,7 +59,7 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v ModulesAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the module verb (captured: xclip)", subject: "", given: "{\"module\":{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"manifest\":{\"build\":{\"artifacts\":[{\"binary\":\"xclip-tools\",\"from\":\"cmd/xclip-tools\",\"kind\":\"bundle\",\"language\":\"go\",\"loads\":[\"xclip-tools\"],\"name\":\"tools\",\"system\":\"arch\"}]},\"capabilities\":[\"package-manager\"],\"module\":\"xclip\",\"resources\":[{\"id\":\"package\",\"package\":\"xclip\",\"type\":\"package\"}],\"tools\":[\"xclip_copy\",\"xclip_paste\",\"xclip_targets\",\"xclip_session\"],\"version\":\"1\"},\"module\":\"xclip\",\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\"}}", wire: "{\"module\":{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"manifest\":{\"build\":{\"artifacts\":[{\"binary\":\"xclip-tools\",\"from\":\"cmd/xclip-tools\",\"kind\":\"bundle\",\"language\":\"go\",\"loads\":[\"xclip-tools\"],\"name\":\"tools\",\"system\":\"arch\"}]},\"capabilities\":[\"package-manager\"],\"module\":\"xclip\",\"resources\":[{\"id\":\"package\",\"package\":\"xclip\",\"type\":\"package\"}],\"tools\":[\"xclip_copy\",\"xclip_paste\",\"xclip_targets\",\"xclip_session\"],\"version\":\"1\"},\"module\":\"xclip\",\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\"}}",
decode: func(b []byte) (any, error) { var v ModuleAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a watched branch's catalog graph revision", subject: "", given: "{\"at\":\"2026-11-09T19:00:00Z\",\"base\":9,\"branch\":\"main\",\"definitions\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"seat\":\"node-build-go\"}],\"entries\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"mesh-build-go\"},{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"xclip\"}],\"kind\":\"trunk\",\"movers\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fingerprint\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\",\"module\":\"xclip\",\"repository\":\"novox/mesh-catalog\"}],\"revision\":12,\"source\":3589,\"trunk\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"repository\":\"novox/mesh-catalog\"}],\"v\":1}", wire: "{\"at\":\"2026-11-09T19:00:00Z\",\"base\":9,\"branch\":\"main\",\"definitions\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"seat\":\"node-build-go\"}],\"entries\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"mesh-build-go\"},{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"xclip\"}],\"kind\":\"trunk\",\"movers\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fingerprint\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\",\"module\":\"xclip\",\"repository\":\"novox/mesh-catalog\"}],\"revision\":12,\"source\":3589,\"trunk\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"repository\":\"novox/mesh-catalog\"}],\"v\":1}",
{name: "a watched branch's catalog graph revision", subject: "", given: "{\"at\":\"2026-11-09T19:00:00Z\",\"base\":9,\"branch\":\"main\",\"call\":\"release of mesh-sdk 0.1.27\",\"call-kind\":\"release\",\"definitions\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"seat\":\"node-build-go\"}],\"entries\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"mesh-build-go\"},{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"xclip\"}],\"kind\":\"trunk\",\"module\":\"mesh-sdk\",\"movers\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fingerprint\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\",\"module\":\"xclip\",\"repository\":\"novox/mesh-catalog\"}],\"revision\":12,\"source\":3589,\"trunk\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"repository\":\"novox/mesh-catalog\"}],\"v\":1,\"version\":\"0.1.27\"}", wire: "{\"at\":\"2026-11-09T19:00:00Z\",\"base\":9,\"branch\":\"main\",\"call\":\"release of mesh-sdk 0.1.27\",\"call-kind\":\"release\",\"definitions\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"seat\":\"node-build-go\"}],\"entries\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"mesh-build-go\"},{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"xclip\"}],\"kind\":\"trunk\",\"module\":\"mesh-sdk\",\"movers\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fingerprint\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\",\"module\":\"xclip\",\"repository\":\"novox/mesh-catalog\"}],\"revision\":12,\"source\":3589,\"trunk\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"repository\":\"novox/mesh-catalog\"}],\"v\":1,\"version\":\"0.1.27\"}",
decode: func(b []byte) (any, error) {
var v CatalogRevisionsByBranchRevisionValue
err := json.Unmarshal(b, &v)
@@ -65,9 +65,9 @@ const (
// StreamPipelineStarted is the stream pipeline-started is kept in.
const StreamPipelineStarted = "SEAT_mesh-pipeline-runner_pipeline-started"
// SubjectPipelineStarted is where pipeline-started is published, on mesh.seat.mesh-pipeline-runner.event.pipeline-started.<branch>.<source>.
func SubjectPipelineStarted(branch, source string) string {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-started." + branch + "." + source
// SubjectPipelineStarted is where pipeline-started is published, on mesh.seat.mesh-pipeline-runner.event.pipeline-started.<branch>.<revision>.
func SubjectPipelineStarted(branch, revision string) string {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-started." + branch + "." + revision
}
// SubjectPipelineStartedAll hears every pipeline-started.
@@ -76,9 +76,9 @@ const SubjectPipelineStartedAll = "mesh.seat.mesh-pipeline-runner.event.pipeline
// StreamPipelineEnded is the stream pipeline-ended is kept in.
const StreamPipelineEnded = "SEAT_mesh-pipeline-runner_pipeline-ended"
// SubjectPipelineEnded is where pipeline-ended is published, on mesh.seat.mesh-pipeline-runner.event.pipeline-ended.<branch>.<source>.
func SubjectPipelineEnded(branch, source string) string {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-ended." + branch + "." + source
// SubjectPipelineEnded is where pipeline-ended is published, on mesh.seat.mesh-pipeline-runner.event.pipeline-ended.<branch>.<revision>.
func SubjectPipelineEnded(branch, revision string) string {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-ended." + branch + "." + revision
}
// SubjectPipelineEndedAll hears every pipeline-ended.
@@ -120,9 +120,9 @@ const SubjectStepEndedAll = "mesh.seat.mesh-pipeline-runner.event.step-ended.*.*
// StreamWaitHeld is the stream wait-held is kept in.
const StreamWaitHeld = "SEAT_mesh-pipeline-runner_wait-held"
// SubjectWaitHeld is where wait-held is published, on mesh.seat.mesh-pipeline-runner.event.wait-held.<branch>.<source>.
func SubjectWaitHeld(branch, source string) string {
return "mesh.seat.mesh-pipeline-runner.event.wait-held." + branch + "." + source
// SubjectWaitHeld is where wait-held is published, on mesh.seat.mesh-pipeline-runner.event.wait-held.<branch>.<revision>.
func SubjectWaitHeld(branch, revision string) string {
return "mesh.seat.mesh-pipeline-runner.event.wait-held." + branch + "." + revision
}
// SubjectWaitHeldAll hears every wait-held.
@@ -131,9 +131,9 @@ const SubjectWaitHeldAll = "mesh.seat.mesh-pipeline-runner.event.wait-held.*.*"
// StreamWaitEnded is the stream wait-ended is kept in.
const StreamWaitEnded = "SEAT_mesh-pipeline-runner_wait-ended"
// SubjectWaitEnded is where wait-ended is published, on mesh.seat.mesh-pipeline-runner.event.wait-ended.<branch>.<source>.
func SubjectWaitEnded(branch, source string) string {
return "mesh.seat.mesh-pipeline-runner.event.wait-ended." + branch + "." + source
// SubjectWaitEnded is where wait-ended is published, on mesh.seat.mesh-pipeline-runner.event.wait-ended.<branch>.<revision>.
func SubjectWaitEnded(branch, revision string) string {
return "mesh.seat.mesh-pipeline-runner.event.wait-ended." + branch + "." + revision
}
// SubjectWaitEndedAll hears every wait-ended.
@@ -156,11 +156,11 @@ const (
StateStepOutputs = "step-outputs"
)
// PipelinesByBranchSourceKey is the key of one value of the state pipelines under the form "<branch>.<source>".
func PipelinesByBranchSourceKey(branch, source string) string { return branch + "." + source }
// PipelinesByBranchRevisionKey is the key of one value of the state pipelines under the form "<branch>.<revision>".
func PipelinesByBranchRevisionKey(branch, revision string) string { return branch + "." + revision }
// ParsePipelinesByBranchSourceKey reads the parts of a key of the form "<branch>.<source>", in the order of the form; the last result is false for a key of another form.
func ParsePipelinesByBranchSourceKey(key string) (string, string, bool) {
// ParsePipelinesByBranchRevisionKey reads the parts of a key of the form "<branch>.<revision>", in the order of the form; the last result is false for a key of another form.
func ParsePipelinesByBranchRevisionKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
@@ -178,9 +178,9 @@ func ParsePipelinesByBranchSourceKey(key string) (string, string, bool) {
return v0, v2, true
}
// DecodePipelinesByBranchSourceValue reads one value of the state pipelines under the form "<branch>.<source>", refusing a field PipelinesByBranchSourceValue does not know and any text after the value.
func DecodePipelinesByBranchSourceValue(raw []byte) (PipelinesByBranchSourceValue, error) {
var v PipelinesByBranchSourceValue
// DecodePipelinesByBranchRevisionValue reads one value of the state pipelines under the form "<branch>.<revision>", refusing a field PipelinesByBranchRevisionValue does not know and any text after the value.
func DecodePipelinesByBranchRevisionValue(raw []byte) (PipelinesByBranchRevisionValue, error) {
var v PipelinesByBranchRevisionValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
@@ -276,6 +276,48 @@ func DecodePipelinesByBranchRunRunValue(raw []byte) (PipelinesByBranchRunRunValu
return v, nil
}
// PipelinesByStepsPipelineMoverKey is the key of one value of the state pipelines under the form "steps.<pipeline>.<mover>".
func PipelinesByStepsPipelineMoverKey(pipeline, mover string) string {
return "steps." + pipeline + "." + mover
}
// ParsePipelinesByStepsPipelineMoverKey reads the parts of a key of the form "steps.<pipeline>.<mover>", in the order of the form; the last result is false for a key of another form.
func ParsePipelinesByStepsPipelineMoverKey(key string) (string, string, bool) {
rest := key
if !strings.HasPrefix(rest, "steps.") {
return "", "", false
}
rest = rest[6:]
v1, after1, found1 := strings.Cut(rest, ".")
if !found1 || v1 == "" {
return "", "", false
}
rest = after1
if rest == "" {
return "", "", false
}
v3 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v1, v3, true
}
// DecodePipelinesByStepsPipelineMoverValue reads one value of the state pipelines under the form "steps.<pipeline>.<mover>", refusing a field PipelinesByStepsPipelineMoverValue does not know and any text after the value.
func DecodePipelinesByStepsPipelineMoverValue(raw []byte) (PipelinesByStepsPipelineMoverValue, error) {
var v PipelinesByStepsPipelineMoverValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// QueueByQueueNextKey is the key of one value of the state queue under the form "queue.next".
func QueueByQueueNextKey() string { return "queue.next" }
@@ -523,8 +565,10 @@ type LogEntry struct {
Artifact string `json:"artifact,omitempty"`
At time.Time `json:"at"`
// the keys of the kept results the step wrote or carried, <level>.<digest>, which the runner ages by their last-read (design 47 G sections 330, 470)
Kept []string `json:"kept,omitempty"`
Outcome string `json:"outcome,omitempty"`
Kept []string `json:"kept,omitempty"`
// the module of the mover whose step the entry is of (H-A-190)
Module string `json:"module,omitempty"`
Outcome string `json:"outcome,omitempty"`
// the output's name in step-outputs
Output string `json:"output,omitempty"`
Pipeline string `json:"pipeline"`
@@ -621,10 +665,12 @@ type Pipeline struct {
// how often the pipeline has ended: 1 at its first end, one higher at each end again after a passing rerun, so the assigner takes a later end of the same source revision (design 47 G sections 29, 325)
EndCount int64 `json:"end-count,omitempty"`
Ended *time.Time `json:"ended,omitempty"`
// how many movers the pipeline has, set by list alone (H-A-191)
MoverCount int64 `json:"mover-count,omitempty"`
// the modules the pipeline moves, its take-in's entries (design 47 H §746)
Movers []Mover `json:"movers"`
Outcome string `json:"outcome"`
// the pipeline's key, <branch>.<source>, <branch>.<source>.published.<package>.<version> for a pipeline a publish started, or <branch>.run.<run> for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83)
// the pipeline's key, <branch>.<revision>, <branch>.<source>.published.<package>.<version> for a pipeline a publish started, or <branch>.run.<run> for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83)
Pipeline string `json:"pipeline"`
// for a pipeline a package's publish started, that publish (A-202)
Published *Published `json:"published,omitempty"`
@@ -637,11 +683,13 @@ type Pipeline struct {
// the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9)
Source int64 `json:"source"`
Started *time.Time `json:"started,omitempty"`
// every mover's steps, each naming its mover, approval last
// how many steps the pipeline's movers have, set by list alone, which answers the record with its steps empty (H-A-191)
StepCount int64 `json:"step-count,omitempty"`
// every mover's steps, each naming its mover, approval last; in the state pipelines a record's own are empty, each mover's kept under its own key (H-A-187)
Steps []StepResult `json:"steps"`
// the modules a newer waiting take-in of the same branch took out of the pipeline, written with the movers by compare-and-set; at its placing the runner writes a mover's build-step why from it (design 47 H §748, H-A-107)
Superseded []string `json:"superseded,omitempty"`
// the step-log entries of the steps that ended and are not appended to the step log yet, in order; written with the step's end in one write and cleared when appended (design 47 G sections 486, 606)
// the step-log entries of the steps that ended and are not appended to the step log yet, in order; written with the step's end in one write and cleared when appended (design 47 G sections 486, 606); in the state pipelines a record's own are empty, each mover's kept under its own key beside its steps (H-A-189)
Unlogged []LogEntry `json:"unlogged,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
@@ -672,7 +720,7 @@ type PipelineEnded struct {
// per mover its fingerprint, released version, step results and tier, in the delivery order (design 47 H §746, H-A-2)
Movers []MoverEnded `json:"movers"`
Outcome string `json:"outcome"`
// the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
// the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
Pipeline string `json:"pipeline"`
// the catalog graph revision of the branch the pipeline runs for
Revision int64 `json:"revision,omitempty"`
@@ -705,7 +753,7 @@ type PipelineStarted struct {
Call string `json:"call,omitempty"`
// the pipeline's movers
Movers []Mover `json:"movers"`
// the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
// the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
Pipeline string `json:"pipeline"`
// for a pipeline a package's publish started, that publish (A-202)
Published *Published `json:"published,omitempty"`
@@ -766,7 +814,7 @@ type StepEvent struct {
// the module's build-input fingerprint at the commit
Fingerprint string `json:"fingerprint,omitempty"`
Module string `json:"module"`
// the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
// the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
Pipeline string `json:"pipeline"`
Result StepResult `json:"result"`
// the catalog graph revision of the branch the pipeline runs for
@@ -918,7 +966,7 @@ type ToolchainUsed struct {
Version string `json:"version"`
}
// Wait is a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283); said on <branch>.<source> (design 47 H-A-72).
// Wait is a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283); said on <branch>.<revision> (design 47 H-A-72, H-A-221).
type Wait struct {
Artifact string `json:"artifact,omitempty"`
// the step's own ask, where it has one (design 47 G §731)
@@ -935,7 +983,7 @@ type Wait struct {
Module string `json:"module,omitempty"`
// what the step waits on (design 47 *Health and going back*)
On string `json:"on"`
// the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
// the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
Pipeline string `json:"pipeline"`
// the catalog graph revision of the branch the pipeline runs for
Revision int64 `json:"revision,omitempty"`
@@ -976,7 +1024,7 @@ const (
// Waiting is a pipeline waiting its turn under pipelines-at-once (design 47 H §748, H-A-72).
type Waiting struct {
// the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
// the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)
Pipeline string `json:"pipeline"`
}
@@ -1026,6 +1074,8 @@ type StartAnswer struct {
// ShowInput is what show takes.
type ShowInput struct {
// a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187)
Mover string `json:"mover,omitempty"`
// the pipeline's key
Pipeline string `json:"pipeline"`
}
@@ -1305,8 +1355,8 @@ type FullEvent = Fill
// RoomEvent is the body of the event room.
type RoomEvent = Fill
// PipelinesByBranchSourceValue is one value of the state pipelines under the key <branch>.<source>.
type PipelinesByBranchSourceValue = Pipeline
// PipelinesByBranchRevisionValue is one value of the state pipelines under the key <branch>.<revision>.
type PipelinesByBranchRevisionValue = Pipeline
// PipelinesByBranchSourcePublishedPackageVersionValue is one value of the state pipelines under the key <branch>.<source>.published.<package>.<version>.
type PipelinesByBranchSourcePublishedPackageVersionValue = Pipeline
@@ -1314,6 +1364,14 @@ type PipelinesByBranchSourcePublishedPackageVersionValue = Pipeline
// PipelinesByBranchRunRunValue is one value of the state pipelines under the key <branch>.run.<run>.
type PipelinesByBranchRunRunValue = Pipeline
// PipelinesByStepsPipelineMoverValue is one value of the state pipelines under the key steps.<pipeline>.<mover>.
type PipelinesByStepsPipelineMoverValue struct {
// the mover's steps
Steps []StepResult `json:"steps"`
// the step-log entries of the mover's steps that ended and are not appended to the step log yet, in order (H-A-189)
Unlogged []LogEntry `json:"unlogged,omitempty"`
}
// QueueByQueueNextValue is one value of the state queue under the key queue.next.
type QueueByQueueNextValue = int64
@@ -45,7 +45,7 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.step-ended\\.[^.*> ]+\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a take-in's pipeline kept, its steps naming their mover", subject: "", given: "{\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"passed\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"steps\":[{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"seat\":\"node-build-go\",\"status\":\"required\",\"step\":\"lint\"},{\"artifact\":\"nats:program\",\"carried-from\":\"main.3588\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"outcome\":\"carried\",\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},{\"artifact\":\"nats:program\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"status\":\"optional\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"why\":\"TestTheBusWhole failed\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"composition\"},{\"module\":\"nats\",\"outcome\":\"bypassed\",\"status\":\"bypass\",\"step\":\"review\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"status\":\"required\",\"step\":\"approval\"}],\"v\":1}", wire: "{\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"passed\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"steps\":[{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"seat\":\"node-build-go\",\"status\":\"required\",\"step\":\"lint\"},{\"artifact\":\"nats:program\",\"carried-from\":\"main.3588\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"outcome\":\"carried\",\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},{\"artifact\":\"nats:program\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"status\":\"optional\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"why\":\"TestTheBusWhole failed\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"composition\"},{\"module\":\"nats\",\"outcome\":\"bypassed\",\"status\":\"bypass\",\"step\":\"review\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"status\":\"required\",\"step\":\"approval\"}],\"v\":1}",
decode: func(b []byte) (any, error) {
var v PipelinesByBranchSourceValue
var v PipelinesByBranchRevisionValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
@@ -73,13 +73,13 @@ func TestFixtures(t *testing.T) {
}, subjectIs: nil},
{name: "a pipeline waiting its turn, its seq given", subject: "", given: "{\"branch\":\"main\",\"call\":\"fedcba9876543210\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0124\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"waiting\",\"pipeline\":\"main.3590\",\"revision\":13,\"seq\":2,\"source\":3590,\"steps\":[],\"v\":1}", wire: "{\"branch\":\"main\",\"call\":\"fedcba9876543210\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0124\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"waiting\",\"pipeline\":\"main.3590\",\"revision\":13,\"seq\":2,\"source\":3590,\"steps\":[],\"v\":1}",
decode: func(b []byte) (any, error) {
var v PipelinesByBranchSourceValue
var v PipelinesByBranchRevisionValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a waiting pipeline names the movers a newer take-in took out of it", subject: "", given: "{\"branch\":\"main\",\"call\":\"fedcba9876543210\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0124\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"waiting\",\"pipeline\":\"main.3590\",\"revision\":13,\"seq\":2,\"source\":3590,\"steps\":[],\"superseded\":[\"mesh-config\"],\"v\":1}", wire: "{\"branch\":\"main\",\"call\":\"fedcba9876543210\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0124\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"waiting\",\"pipeline\":\"main.3590\",\"revision\":13,\"seq\":2,\"source\":3590,\"steps\":[],\"superseded\":[\"mesh-config\"],\"v\":1}",
decode: func(b []byte) (any, error) {
var v PipelinesByBranchSourceValue
var v PipelinesByBranchRevisionValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
@@ -83,9 +83,9 @@ const SubjectWantedAll = "mesh.seat.mesh-wants.event.wanted.*.*"
// StreamPipelineWanted is the stream pipeline-wanted is kept in.
const StreamPipelineWanted = "SEAT_mesh-wants_pipeline-wanted"
// SubjectPipelineWanted is where pipeline-wanted is published, on mesh.seat.mesh-wants.event.pipeline-wanted.<branch>.<source>.
func SubjectPipelineWanted(branch, source string) string {
return "mesh.seat.mesh-wants.event.pipeline-wanted." + branch + "." + source
// SubjectPipelineWanted is where pipeline-wanted is published, on mesh.seat.mesh-wants.event.pipeline-wanted.<branch>.<revision>.
func SubjectPipelineWanted(branch, revision string) string {
return "mesh.seat.mesh-wants.event.pipeline-wanted." + branch + "." + revision
}
// SubjectPipelineWantedAll hears every pipeline-wanted.
@@ -1001,10 +1001,12 @@ type PipelineWanted struct {
// for tier-late, the late tier's movers not running and the machines they do not run on
NotRunning []NotRunning `json:"not-running,omitempty"`
Outcome string `json:"outcome"`
// the runner's pipeline key, <branch>.<source>, a branch escaped as a key's name is (design 47 H §746)
// the runner's pipeline key, <branch>.<revision>, a branch escaped as a key's name is (design 47 H §746, H-A-213 (4))
Pipeline string `json:"pipeline"`
Source int64 `json:"source"`
V int64 `json:"v"`
// the pipeline's catalog revision number, the number of its key; the indexer frees the pins of that revision, not of another revision of the same source (design 47 H-A-214); absent from an older event
Revision int64 `json:"revision,omitempty"`
Source int64 `json:"source"`
V int64 `json:"v"`
}
// The values of PipelineWanted's outcome.
@@ -29,7 +29,7 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v WantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wanted\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a want removed, its node left or its module unplaced", subject: "mesh.seat.mesh-wants.event.wanted.n1.xclip", given: "{\"at\":\"2026-11-09T19:05:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"removed\":true,\"revision\":41,\"v\":1}", wire: "{\"at\":\"2026-11-09T19:05:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"removed\":true,\"revision\":41,\"v\":1}",
decode: func(b []byte) (any, error) { var v WantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wanted\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a pipeline's wants all run", subject: "mesh.seat.mesh-wants.event.pipeline-wanted.main.3589", given: "{\"branch\":\"main\",\"outcome\":\"running\",\"pipeline\":\"main.3589\",\"source\":3589,\"v\":1}", wire: "{\"branch\":\"main\",\"outcome\":\"running\",\"pipeline\":\"main.3589\",\"source\":3589,\"v\":1}",
{name: "a pipeline's wants all run", subject: "mesh.seat.mesh-wants.event.pipeline-wanted.main.3590", given: "{\"branch\":\"main\",\"outcome\":\"running\",\"pipeline\":\"main.3590\",\"revision\":3590,\"source\":3589,\"v\":1}", wire: "{\"branch\":\"main\",\"outcome\":\"running\",\"pipeline\":\"main.3590\",\"revision\":3590,\"source\":3589,\"v\":1}",
decode: func(b []byte) (any, error) { var v PipelineWantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.pipeline-wanted\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a pipeline's tier late, naming the movers and machines not running", subject: "mesh.seat.mesh-wants.event.pipeline-wanted.main.3590", given: "{\"branch\":\"main\",\"not-running\":[{\"machines\":[\"anchor\",\"laptop\"],\"module\":\"nats\"}],\"outcome\":\"tier-late\",\"pipeline\":\"main.3590\",\"source\":3590,\"v\":1}", wire: "{\"branch\":\"main\",\"not-running\":[{\"machines\":[\"anchor\",\"laptop\"],\"module\":\"nats\"}],\"outcome\":\"tier-late\",\"pipeline\":\"main.3590\",\"source\":3590,\"v\":1}",
decode: func(b []byte) (any, error) { var v PipelineWantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.pipeline-wanted\\.[^.*> ]+\\.[^.*> ]+$")},
@@ -905,8 +905,10 @@ type StepRun struct {
Pipeline string `json:"pipeline"`
// the step is asked again by the runner's rerun
Rerun bool `json:"rerun,omitempty"`
// the source revision of the watched branch the pipeline runs for; absent for a run on request
// the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request
Revision int64 `json:"revision,omitempty"`
// the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request
Source int64 `json:"source,omitempty"`
// the pipeline step
Step string `json:"step"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
@@ -903,8 +903,10 @@ type StepRun struct {
Pipeline string `json:"pipeline"`
// the step is asked again by the runner's rerun
Rerun bool `json:"rerun,omitempty"`
// the source revision of the watched branch the pipeline runs for; absent for a run on request
// the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request
Revision int64 `json:"revision,omitempty"`
// the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request
Source int64 `json:"source,omitempty"`
// the pipeline step
Step string `json:"step"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
@@ -903,8 +903,10 @@ type StepRun struct {
Pipeline string `json:"pipeline"`
// the step is asked again by the runner's rerun
Rerun bool `json:"rerun,omitempty"`
// the source revision of the watched branch the pipeline runs for; absent for a run on request
// the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request
Revision int64 `json:"revision,omitempty"`
// the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request
Source int64 `json:"source,omitempty"`
// the pipeline step
Step string `json:"step"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
@@ -1521,7 +1521,11 @@
},
"revision": {
"type": "integer",
"description": "the source revision of the watched branch the pipeline runs for; absent for a run on request"
"description": "the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request"
},
"source": {
"type": "integer",
"description": "the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request"
},
"fingerprint": {
"type": "string",
@@ -180,6 +180,10 @@
"type": "integer",
"description": "the source revision of that branch the build was made from"
},
"revision": {
"type": "integer",
"description": "the catalog revision number of that branch the build was made from, the indexer's count (design 47 H-A-218, H-A-220); absent from a reservation made before the field"
},
"dependencies": {
"type": "array",
"items": {
@@ -363,6 +367,13 @@
"$ref": "#/defs/BuildEntry"
},
"description": "each entry the step built, by module and fingerprint"
},
"packages": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "the pins the step's entries were built with, each mesh package's version by its module path, the ones the builder took from the registry for a package the entry named with none included; the runner asks the entry's held test steps with them (H-A-207)"
}
},
"required": [
@@ -8,6 +8,10 @@
"revision": 12,
"kind": "trunk",
"source": 3589,
"call": "release of mesh-sdk 0.1.27",
"call-kind": "release",
"module": "mesh-sdk",
"version": "0.1.27",
"entries": 2,
"changed": [
"xclip"
@@ -209,7 +209,11 @@
"repository": "novox/mesh-catalog"
}
],
"base": 9
"base": 9,
"call": "release of mesh-sdk 0.1.27",
"call-kind": "release",
"module": "mesh-sdk",
"version": "0.1.27"
}
},
{
@@ -657,6 +657,32 @@
"source": {
"type": "integer"
},
"call": {
"type": "string",
"description": "what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": {
"type": "string"
},
@@ -1871,6 +1897,32 @@
"type": "integer",
"description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto"
},
"call": {
"type": "string",
"description": "what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of <module> <version>, a take-in again's take-in again of <repository>; absent for a candidate's"
},
"call-kind": {
"type": "string",
"enum": [
"take-in",
"release",
"take-in-again",
"recompute"
],
"description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's"
},
"module": {
"type": "string",
"description": "for call-kind release, the module released (H-A-215)"
},
"version": {
"type": "string",
"description": "for call-kind release, the version released (H-A-215)"
},
"repository": {
"type": "string",
"description": "for call-kind take-in-again, the repository taken in again (H-A-215)"
},
"group": {
"type": "string",
"description": "a candidate's group"
@@ -1,7 +1,7 @@
[
{
"name": "a take-in's pipeline kept, its steps naming their mover",
"of": "state:pipelines/<branch>.<source>",
"of": "state:pipelines/<branch>.<revision>",
"given": {
"pipeline": "main.3589",
"branch": "main",
@@ -200,7 +200,7 @@
},
{
"name": "a pipeline waiting its turn, its seq given",
"of": "state:pipelines/<branch>.<source>",
"of": "state:pipelines/<branch>.<revision>",
"given": {
"pipeline": "main.3590",
"branch": "main",
@@ -224,7 +224,7 @@
},
{
"name": "a waiting pipeline names the movers a newer take-in took out of it",
"of": "state:pipelines/<branch>.<source>",
"of": "state:pipelines/<branch>.<revision>",
"given": {
"pipeline": "main.3590",
"branch": "main",
@@ -86,13 +86,17 @@
},
{
"name": "show",
"description": "One pipeline whole: its steps, its step log and its outputs, with the stores' fill. Reads only.",
"description": "One pipeline whole: its record with every mover's steps, or one mover's steps alone when it names the mover, its step log and its outputs, with the stores' fill. Reads only.",
"input": {
"type": "object",
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key"
},
"mover": {
"type": "string",
"description": "a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187)"
}
},
"required": [
@@ -133,7 +137,7 @@
},
{
"name": "list",
"description": "The pipelines and runs of a module, a branch or a commit, newest first, with the store's fill. Reads only.",
"description": "The pipelines and runs of a module, a branch or a commit, newest first, with the store's fill: each pipeline's record with its movers and steps counted, never its steps (show gives those). Reads only.",
"input": {
"type": "object",
"properties": {
@@ -668,7 +672,7 @@
"events": [
{
"name": "pipeline-started",
"subject": "pipeline-started.<branch>.<source>",
"subject": "pipeline-started.<branch>.<revision>",
"body": {
"$ref": "#/defs/PipelineStarted"
},
@@ -679,7 +683,7 @@
},
{
"name": "pipeline-ended",
"subject": "pipeline-ended.<branch>.<source>",
"subject": "pipeline-ended.<branch>.<revision>",
"body": {
"$ref": "#/defs/PipelineEnded"
},
@@ -723,7 +727,7 @@
},
{
"name": "wait-held",
"subject": "wait-held.<branch>.<source>",
"subject": "wait-held.<branch>.<revision>",
"body": {
"$ref": "#/defs/Wait"
},
@@ -734,7 +738,7 @@
},
{
"name": "wait-ended",
"subject": "wait-ended.<branch>.<source>",
"subject": "wait-ended.<branch>.<revision>",
"body": {
"$ref": "#/defs/Wait"
},
@@ -771,14 +775,14 @@
"name": "pipelines",
"template": "state",
"history": 1,
"description": "one key per pipeline, one per take-in, written by compare-and-set on its absence (design 47 H §746, §747)",
"description": "one key per pipeline, one per take-in, written by compare-and-set on its absence (design 47 H §746, §747), and one key per mover of a pipeline holding that mover's steps (H-A-187)",
"key-forms": [
{
"key": "<branch>.<source>",
"key": "<branch>.<revision>",
"value": {
"$ref": "#/defs/Pipeline"
},
"description": "a take-in's pipeline"
"description": "a pipeline of one catalog revision, keyed by the revision's number (design 47 H-A-213 (4), H-A-219); one kept from before under its source has the same form"
},
{
"key": "<branch>.<source>.published.<package>.<version>",
@@ -793,6 +797,32 @@
"$ref": "#/defs/Pipeline"
},
"description": "a run on request's pipeline, one per run, its movers the named commits' modules; it delivers nothing (H-A-83)"
},
{
"key": "steps.<pipeline>.<mover>",
"value": {
"type": "object",
"properties": {
"steps": {
"type": "array",
"items": {
"$ref": "#/defs/StepResult"
},
"description": "the mover's steps"
},
"unlogged": {
"type": "array",
"items": {
"$ref": "#/defs/LogEntry"
},
"description": "the step-log entries of the mover's steps that ended and are not appended to the step log yet, in order (H-A-189)"
}
},
"required": [
"steps"
]
},
"description": "one mover's steps and unlogged step-log entries in a pipeline, its key the pipeline's and the mover's module escaped as a key's name, written by compare-and-set as the pipeline's record is; the record's own steps stay empty, so a record never grows with the catalog (H-A-187)"
}
]
},
@@ -1169,7 +1199,7 @@
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key, <branch>.<source>, <branch>.<source>.published.<package>.<version> for a pipeline a publish started, or <branch>.run.<run> for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83)"
"description": "the pipeline's key, <branch>.<revision>, <branch>.<source>.published.<package>.<version> for a pipeline a publish started, or <branch>.run.<run> for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83)"
},
"branch": {
"type": "string",
@@ -1238,7 +1268,7 @@
"items": {
"$ref": "#/defs/StepResult"
},
"description": "every mover's steps, each naming its mover, approval last"
"description": "every mover's steps, each naming its mover, approval last; in the state pipelines a record's own are empty, each mover's kept under its own key (H-A-187)"
},
"started": {
"type": "string",
@@ -1253,7 +1283,15 @@
"items": {
"$ref": "#/defs/LogEntry"
},
"description": "the step-log entries of the steps that ended and are not appended to the step log yet, in order; written with the step's end in one write and cleared when appended (design 47 G sections 486, 606)"
"description": "the step-log entries of the steps that ended and are not appended to the step log yet, in order; written with the step's end in one write and cleared when appended (design 47 G sections 486, 606); in the state pipelines a record's own are empty, each mover's kept under its own key beside its steps (H-A-189)"
},
"mover-count": {
"type": "integer",
"description": "how many movers the pipeline has, set by list alone (H-A-191)"
},
"step-count": {
"type": "integer",
"description": "how many steps the pipeline's movers have, set by list alone, which answers the record with its steps empty (H-A-191)"
},
"published": {
"$ref": "#/defs/Published",
@@ -1275,7 +1313,7 @@
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
"description": "the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
},
"branch": {
"type": "string",
@@ -1350,7 +1388,7 @@
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
"description": "the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
},
"branch": {
"type": "string",
@@ -1457,7 +1495,7 @@
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
"description": "the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
},
"module": {
"type": "string"
@@ -1512,7 +1550,7 @@
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
"description": "the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
},
"module": {
"type": "string",
@@ -1597,7 +1635,7 @@
"description": "the run the step waits on, where the runner knows it: a test step's run key and ask (design 47 G §731, A-469v)"
}
},
"description": "a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283); said on <branch>.<source> (design 47 H-A-72)",
"description": "a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283); said on <branch>.<revision> (design 47 H-A-72, H-A-221)",
"required": [
"v",
"pipeline",
@@ -1613,6 +1651,10 @@
"pipeline": {
"type": "string"
},
"module": {
"type": "string",
"description": "the module of the mover whose step the entry is of (H-A-190)"
},
"step": {
"type": "string",
"enum": [
@@ -1936,7 +1978,7 @@
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
"description": "the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)"
}
},
"description": "a pipeline waiting its turn under pipelines-at-once (design 47 H §748, H-A-72)",
@@ -65,12 +65,13 @@
{
"name": "a pipeline's wants all run",
"of": "event:pipeline-wanted",
"subject": "mesh.seat.mesh-wants.event.pipeline-wanted.main.3589",
"subject": "mesh.seat.mesh-wants.event.pipeline-wanted.main.3590",
"given": {
"v": 1,
"pipeline": "main.3589",
"pipeline": "main.3590",
"branch": "main",
"source": 3589,
"revision": 3590,
"outcome": "running"
}
},
@@ -434,7 +434,7 @@
},
{
"name": "pipeline-wanted",
"subject": "pipeline-wanted.<branch>.<source>",
"subject": "pipeline-wanted.<branch>.<revision>",
"keep": {
"max-age-days": 30,
"max-mib": 64
@@ -1725,7 +1725,7 @@
},
"pipeline": {
"type": "string",
"description": "the runner's pipeline key, <branch>.<source>, a branch escaped as a key's name is (design 47 H §746)"
"description": "the runner's pipeline key, <branch>.<revision>, a branch escaped as a key's name is (design 47 H §746, H-A-213 (4))"
},
"branch": {
"type": "string"
@@ -1733,6 +1733,10 @@
"source": {
"type": "integer"
},
"revision": {
"type": "integer",
"description": "the pipeline's catalog revision number, the number of its key; the indexer frees the pins of that revision, not of another revision of the same source (design 47 H-A-214); absent from an older event"
},
"outcome": {
"type": "string",
"enum": [
@@ -69,6 +69,8 @@ export interface PackagePublished {
"digest": string;
/** the module */
"module": string;
/** the catalog revision number of that branch the build was made from, the indexer's count (design 47 H-A-218, H-A-220); absent from a reservation made before the field */
"revision"?: number;
/** the source revision of that branch the build was made from */
"source": number;
"v": number;
@@ -89,6 +91,8 @@ export interface StepEnded {
"node": string;
/** never passed for a build that built nothing */
"outcome": "passed" | "failed" | "nothing to run" | "could not run";
/** the pins the step's entries were built with, each mesh package's version by its module path, the ones the builder took from the registry for a package the entry named with none included; the runner asks the entry's held test steps with them (H-A-207) */
"packages"?: Record<string, string>;
"pipeline": string;
"rerun"?: boolean;
/** why it failed or could not run: the entry not built, the part not heard */
@@ -277,6 +277,10 @@ export interface CatalogRevision {
"base"?: number;
/** the watched branch the revision is of */
"branch"?: string;
/** what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of <module> <version>, a take-in again's take-in again of <repository>; absent for a candidate's */
"call"?: string;
/** the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's */
"call-kind"?: "take-in" | "release" | "take-in-again" | "recompute";
/** the seat definitions it was judged with, each by its digest, read whole through seat-definitions */
"definitions"?: CatalogRevisionDefinitionsItem[];
/** one per module, by name */
@@ -287,8 +291,12 @@ export interface CatalogRevision {
"heads"?: string;
/** trunk or candidate */
"kind": string;
/** for call-kind release, the module released (H-A-215) */
"module"?: string;
/** the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover */
"movers"?: TakeInEntry[];
/** for call-kind take-in-again, the repository taken in again (H-A-215) */
"repository"?: string;
/** the catalog graph revision's number, counted by its holder */
"revision": number;
/** the source revision it was taken in from; for a candidate, the source revision its heads are merged onto */
@@ -297,6 +305,8 @@ export interface CatalogRevision {
"trunk"?: Head[];
/** the layout version */
"v"?: number;
/** for call-kind release, the version released (H-A-215) */
"version"?: string;
}
/** one edge of the catalog graph between artifact references, B before A (ADR 0666 section 14): kind 1 B published before A builds (a package A imports), 2 B published before A delivers (fetched by reference at its start), 3 B delivered before A builds (its build module and toolchain), 4 B delivered before A delivers (a provision, bus state, a format's reader), 5 B has acted for A's new version (an acting rule), 6 B runs a version that serves A (a verb or a manifest word A uses) */
@@ -796,6 +806,10 @@ export interface CatalogRevisionEvent {
"at"?: string;
/** the watched branch the revision is of, escaped as a key name is */
"branch"?: string;
/** what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's */
"call"?: string;
/** the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's */
"call-kind"?: "take-in" | "release" | "take-in-again" | "recompute";
/** the modules whose entries differ from the revision before it of the same kind */
"changed"?: string[];
/** how many entries it lists */
@@ -804,9 +818,15 @@ export interface CatalogRevisionEvent {
"heads"?: string;
/** trunk or candidate: a candidate's moves no running part */
"kind": string;
/** for call-kind release, the module released (H-A-215) */
"module"?: string;
/** for call-kind take-in-again, the repository taken in again (H-A-215) */
"repository"?: string;
"revision": number;
"source": number;
"v": number;
/** for call-kind release, the version released (H-A-215) */
"version"?: string;
}
/** is the body of the event filling. */
@@ -40,13 +40,13 @@ export declare const family: { readonly name: "mesh-pipeline-runner.events"; rea
export declare const pipelineStartedStream: "SEAT_mesh-pipeline-runner_pipeline-started";
export declare function pipelineStartedSubject(branch: string, source: string): string;
export declare function pipelineStartedSubject(branch: string, revision: string): string;
export declare const pipelineStartedSubjectAll: "mesh.seat.mesh-pipeline-runner.event.pipeline-started.*.*";
export declare const pipelineEndedStream: "SEAT_mesh-pipeline-runner_pipeline-ended";
export declare function pipelineEndedSubject(branch: string, source: string): string;
export declare function pipelineEndedSubject(branch: string, revision: string): string;
export declare const pipelineEndedSubjectAll: "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.*.*";
@@ -70,13 +70,13 @@ export declare const stepEndedSubjectAll: "mesh.seat.mesh-pipeline-runner.event.
export declare const waitHeldStream: "SEAT_mesh-pipeline-runner_wait-held";
export declare function waitHeldSubject(branch: string, source: string): string;
export declare function waitHeldSubject(branch: string, revision: string): string;
export declare const waitHeldSubjectAll: "mesh.seat.mesh-pipeline-runner.event.wait-held.*.*";
export declare const waitEndedStream: "SEAT_mesh-pipeline-runner_wait-ended";
export declare function waitEndedSubject(branch: string, source: string): string;
export declare function waitEndedSubject(branch: string, revision: string): string;
export declare const waitEndedSubjectAll: "mesh.seat.mesh-pipeline-runner.event.wait-ended.*.*";
@@ -94,11 +94,11 @@ export declare const states: {
readonly stepOutputs: "step-outputs";
};
/** The key of one value of the state pipelines under the form "<branch>.<source>". */
export declare function pipelinesByBranchSourceKey(branch: string, source: string): string;
/** The key of one value of the state pipelines under the form "<branch>.<revision>". */
export declare function pipelinesByBranchRevisionKey(branch: string, revision: string): string;
/** The parts of a key of the form "<branch>.<source>", or undefined for a key of another form. */
export declare function parsePipelinesByBranchSourceKey(_key: string): { branch: string; source: string } | undefined;
/** The parts of a key of the form "<branch>.<revision>", or undefined for a key of another form. */
export declare function parsePipelinesByBranchRevisionKey(_key: string): { branch: string; revision: string } | undefined;
/** The key of one value of the state pipelines under the form "<branch>.<source>.published.<package>.<version>". */
export declare function pipelinesByBranchSourcePublishedPackageVersionKey(branch: string, source: string, packagePart: string, version: string): string;
@@ -112,6 +112,12 @@ export declare function pipelinesByBranchRunRunKey(branch: string, run: string):
/** The parts of a key of the form "<branch>.run.<run>", or undefined for a key of another form. */
export declare function parsePipelinesByBranchRunRunKey(_key: string): { branch: string; run: string } | undefined;
/** The key of one value of the state pipelines under the form "steps.<pipeline>.<mover>". */
export declare function pipelinesByStepsPipelineMoverKey(pipeline: string, mover: string): string;
/** The parts of a key of the form "steps.<pipeline>.<mover>", or undefined for a key of another form. */
export declare function parsePipelinesByStepsPipelineMoverKey(_key: string): { pipeline: string; mover: string } | undefined;
/** The key of one value of the state queue under the form "queue.next". */
export declare function queueByQueueNextKey(): string;
@@ -186,6 +192,8 @@ export interface LogEntry {
"at": string;
/** the keys of the kept results the step wrote or carried, <level>.<digest>, which the runner ages by their last-read (design 47 G sections 330, 470) */
"kept"?: string[];
/** the module of the mover whose step the entry is of (H-A-190) */
"module"?: string;
"outcome"?: "running" | "waiting" | "passed" | "failed" | "nothing to run" | "bypassed" | "carried" | "could not run" | "waiting for a build node" | "did not build" | "accepted" | "declined" | "superseded" | "cancelled";
/** the output's name in step-outputs */
"output"?: string;
@@ -248,10 +256,12 @@ export interface Pipeline {
/** how often the pipeline has ended: 1 at its first end, one higher at each end again after a passing rerun, so the assigner takes a later end of the same source revision (design 47 G sections 29, 325) */
"end-count"?: number;
"ended"?: string;
/** how many movers the pipeline has, set by list alone (H-A-191) */
"mover-count"?: number;
/** the modules the pipeline moves, its take-in's entries (design 47 H §746) */
"movers": Mover[];
"outcome": "waiting" | "running" | "passed" | "failed" | "refused" | "superseded" | "cancelled";
/** the pipeline's key, <branch>.<source>, <branch>.<source>.published.<package>.<version> for a pipeline a publish started, or <branch>.run.<run> for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83) */
/** the pipeline's key, <branch>.<revision>, <branch>.<source>.published.<package>.<version> for a pipeline a publish started, or <branch>.run.<run> for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83) */
"pipeline": string;
/** for a pipeline a package's publish started, that publish (A-202) */
"published"?: Published;
@@ -264,11 +274,13 @@ export interface Pipeline {
/** the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9) */
"source": number;
"started"?: string;
/** every mover's steps, each naming its mover, approval last */
/** how many steps the pipeline's movers have, set by list alone, which answers the record with its steps empty (H-A-191) */
"step-count"?: number;
/** every mover's steps, each naming its mover, approval last; in the state pipelines a record's own are empty, each mover's kept under its own key (H-A-187) */
"steps": StepResult[];
/** the modules a newer waiting take-in of the same branch took out of the pipeline, written with the movers by compare-and-set; at its placing the runner writes a mover's build-step why from it (design 47 H §748, H-A-107) */
"superseded"?: string[];
/** the step-log entries of the steps that ended and are not appended to the step log yet, in order; written with the step's end in one write and cleared when appended (design 47 G sections 486, 606) */
/** the step-log entries of the steps that ended and are not appended to the step log yet, in order; written with the step's end in one write and cleared when appended (design 47 G sections 486, 606); in the state pipelines a record's own are empty, each mover's kept under its own key beside its steps (H-A-189) */
"unlogged"?: LogEntry[];
/** the layout version */
"v"?: number;
@@ -288,7 +300,7 @@ export interface PipelineEnded {
/** per mover its fingerprint, released version, step results and tier, in the delivery order (design 47 H §746, H-A-2) */
"movers": MoverEnded[];
"outcome": "waiting" | "running" | "passed" | "failed" | "refused" | "superseded" | "cancelled";
/** the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
/** the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
"pipeline": string;
/** the catalog graph revision of the branch the pipeline runs for */
"revision"?: number;
@@ -310,7 +322,7 @@ export interface PipelineStarted {
"call"?: string;
/** the pipeline's movers */
"movers": Mover[];
/** the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
/** the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
"pipeline": string;
/** for a pipeline a package's publish started, that publish (A-202) */
"published"?: Published;
@@ -371,7 +383,7 @@ export interface StepEvent {
/** the module's build-input fingerprint at the commit */
"fingerprint"?: string;
"module": string;
/** the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
/** the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
"pipeline": string;
"result": StepResult;
/** the catalog graph revision of the branch the pipeline runs for */
@@ -478,7 +490,7 @@ export interface ToolchainUsed {
"version": string;
}
/** a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283); said on <branch>.<source> (design 47 H-A-72) */
/** a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283); said on <branch>.<revision> (design 47 H-A-72, H-A-221) */
export interface Wait {
"artifact"?: string;
/** the step's own ask, where it has one (design 47 G §731) */
@@ -495,7 +507,7 @@ export interface Wait {
"module"?: string;
/** what the step waits on (design 47 *Health and going back*) */
"on": "person" | "build node" | "revision view" | "pipelines-at-once";
/** the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
/** the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
"pipeline": string;
/** the catalog graph revision of the branch the pipeline runs for */
"revision"?: number;
@@ -515,7 +527,7 @@ export interface Wait {
/** a pipeline waiting its turn under pipelines-at-once (design 47 H §748, H-A-72) */
export interface Waiting {
/** the pipeline's key, <branch>.<source>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
/** the pipeline's key, <branch>.<revision>, or <branch>.<source>.published.<package>.<version> for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */
"pipeline": string;
}
@@ -556,6 +568,8 @@ export interface StartAnswer {
/** is what show takes. */
export interface ShowInput {
/** a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187) */
"mover"?: string;
/** the pipeline's key */
"pipeline": string;
}
@@ -786,8 +800,8 @@ export type FullEvent = Fill;
/** is the body of the event room. */
export type RoomEvent = Fill;
/** is one value of the state pipelines under the key <branch>.<source>. */
export type PipelinesByBranchSourceValue = Pipeline;
/** is one value of the state pipelines under the key <branch>.<revision>. */
export type PipelinesByBranchRevisionValue = Pipeline;
/** is one value of the state pipelines under the key <branch>.<source>.published.<package>.<version>. */
export type PipelinesByBranchSourcePublishedPackageVersionValue = Pipeline;
@@ -795,6 +809,14 @@ export type PipelinesByBranchSourcePublishedPackageVersionValue = Pipeline;
/** is one value of the state pipelines under the key <branch>.run.<run>. */
export type PipelinesByBranchRunRunValue = Pipeline;
/** is one value of the state pipelines under the key steps.<pipeline>.<mover>. */
export interface PipelinesByStepsPipelineMoverValue {
/** the mover's steps */
"steps": StepResult[];
/** the step-log entries of the mover's steps that ended and are not appended to the step log yet, in order (H-A-189) */
"unlogged"?: LogEntry[];
}
/** is one value of the state queue under the key queue.next. */
export type QueueByQueueNextValue = number;
@@ -40,16 +40,16 @@ export const family = { name: "mesh-pipeline-runner.events", maxAgeDays: 7 };
export const pipelineStartedStream = "SEAT_mesh-pipeline-runner_pipeline-started";
export function pipelineStartedSubject(branch, source) {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-started." + branch + "." + source;
export function pipelineStartedSubject(branch, revision) {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-started." + branch + "." + revision;
}
export const pipelineStartedSubjectAll = "mesh.seat.mesh-pipeline-runner.event.pipeline-started.*.*";
export const pipelineEndedStream = "SEAT_mesh-pipeline-runner_pipeline-ended";
export function pipelineEndedSubject(branch, source) {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-ended." + branch + "." + source;
export function pipelineEndedSubject(branch, revision) {
return "mesh.seat.mesh-pipeline-runner.event.pipeline-ended." + branch + "." + revision;
}
export const pipelineEndedSubjectAll = "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.*.*";
@@ -80,16 +80,16 @@ export const stepEndedSubjectAll = "mesh.seat.mesh-pipeline-runner.event.step-en
export const waitHeldStream = "SEAT_mesh-pipeline-runner_wait-held";
export function waitHeldSubject(branch, source) {
return "mesh.seat.mesh-pipeline-runner.event.wait-held." + branch + "." + source;
export function waitHeldSubject(branch, revision) {
return "mesh.seat.mesh-pipeline-runner.event.wait-held." + branch + "." + revision;
}
export const waitHeldSubjectAll = "mesh.seat.mesh-pipeline-runner.event.wait-held.*.*";
export const waitEndedStream = "SEAT_mesh-pipeline-runner_wait-ended";
export function waitEndedSubject(branch, source) {
return "mesh.seat.mesh-pipeline-runner.event.wait-ended." + branch + "." + source;
export function waitEndedSubject(branch, revision) {
return "mesh.seat.mesh-pipeline-runner.event.wait-ended." + branch + "." + revision;
}
export const waitEndedSubjectAll = "mesh.seat.mesh-pipeline-runner.event.wait-ended.*.*";
@@ -108,23 +108,23 @@ export const states = {
stepOutputs: "step-outputs",
};
/** The key of one value of the state pipelines under the form "<branch>.<source>". */
export function pipelinesByBranchSourceKey(branch, source) {
return branch + "." + source;
/** The key of one value of the state pipelines under the form "<branch>.<revision>". */
export function pipelinesByBranchRevisionKey(branch, revision) {
return branch + "." + revision;
}
/** The parts of a key of the form "<branch>.<source>", or undefined for a key of another form. */
export function parsePipelinesByBranchSourceKey(_key) {
/** The parts of a key of the form "<branch>.<revision>", or undefined for a key of another form. */
export function parsePipelinesByBranchRevisionKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const branch = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
if (_rest === "") return undefined;
const source = _rest;
const revision = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { branch, source };
return { branch, revision };
}
/** The key of one value of the state pipelines under the form "<branch>.<source>.published.<package>.<version>". */
@@ -173,6 +173,27 @@ export function parsePipelinesByBranchRunRunKey(_key) {
return { branch, run };
}
/** The key of one value of the state pipelines under the form "steps.<pipeline>.<mover>". */
export function pipelinesByStepsPipelineMoverKey(pipeline, mover) {
return "steps." + pipeline + "." + mover;
}
/** The parts of a key of the form "steps.<pipeline>.<mover>", or undefined for a key of another form. */
export function parsePipelinesByStepsPipelineMoverKey(_key) {
let _rest = _key;
if (!_rest.startsWith("steps.")) return undefined;
_rest = _rest.slice(6);
const _at1 = _rest.indexOf(".");
if (_at1 <= 0) return undefined;
const pipeline = _rest.slice(0, _at1);
_rest = _rest.slice(_at1 + 1);
if (_rest === "") return undefined;
const mover = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { pipeline, mover };
}
/** The key of one value of the state queue under the form "queue.next". */
export function queueByQueueNextKey() {
return "queue.next";
@@ -50,7 +50,7 @@ export declare const wantedSubjectAll: "mesh.seat.mesh-wants.event.wanted.*.*";
export declare const pipelineWantedStream: "SEAT_mesh-wants_pipeline-wanted";
export declare function pipelineWantedSubject(branch: string, source: string): string;
export declare function pipelineWantedSubject(branch: string, revision: string): string;
export declare const pipelineWantedSubjectAll: "mesh.seat.mesh-wants.event.pipeline-wanted.*.*";
@@ -412,8 +412,10 @@ export interface PipelineWanted {
/** for tier-late, the late tier's movers not running and the machines they do not run on */
"not-running"?: NotRunning[];
"outcome": "running" | "tier-late";
/** the runner's pipeline key, <branch>.<source>, a branch escaped as a key's name is (design 47 H §746) */
/** the runner's pipeline key, <branch>.<revision>, a branch escaped as a key's name is (design 47 H §746, H-A-213 (4)) */
"pipeline": string;
/** the pipeline's catalog revision number, the number of its key; the indexer frees the pins of that revision, not of another revision of the same source (design 47 H-A-214); absent from an older event */
"revision"?: number;
"source": number;
"v": number;
}
@@ -52,8 +52,8 @@ export const wantedSubjectAll = "mesh.seat.mesh-wants.event.wanted.*.*";
export const pipelineWantedStream = "SEAT_mesh-wants_pipeline-wanted";
export function pipelineWantedSubject(branch, source) {
return "mesh.seat.mesh-wants.event.pipeline-wanted." + branch + "." + source;
export function pipelineWantedSubject(branch, revision) {
return "mesh.seat.mesh-wants.event.pipeline-wanted." + branch + "." + revision;
}
export const pipelineWantedSubjectAll = "mesh.seat.mesh-wants.event.pipeline-wanted.*.*";
@@ -510,8 +510,10 @@ export interface StepRun {
"pipeline": string;
/** the step is asked again by the runner's rerun */
"rerun"?: boolean;
/** the source revision of the watched branch the pipeline runs for; absent for a run on request */
/** the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request */
"revision"?: number;
/** the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request */
"source"?: number;
/** the pipeline step */
"step": "lint" | "unit" | "integration";
"toolchain"?: ToolchainUsed;
@@ -510,8 +510,10 @@ export interface StepRun {
"pipeline": string;
/** the step is asked again by the runner's rerun */
"rerun"?: boolean;
/** the source revision of the watched branch the pipeline runs for; absent for a run on request */
/** the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request */
"revision"?: number;
/** the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request */
"source"?: number;
/** the pipeline step */
"step": "lint" | "unit" | "integration";
"toolchain"?: ToolchainUsed;
@@ -510,8 +510,10 @@ export interface StepRun {
"pipeline": string;
/** the step is asked again by the runner's rerun */
"rerun"?: boolean;
/** the source revision of the watched branch the pipeline runs for; absent for a run on request */
/** the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request */
"revision"?: number;
/** the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request */
"source"?: number;
/** the pipeline step */
"step": "lint" | "unit" | "integration";
"toolchain"?: ToolchainUsed;
@@ -141,7 +141,7 @@ func main() {
tools = append(tools, OwedTools(askState(owedAsks, groups.OwedAsksBucket(served), 25*time.Second, func(v []byte) bool {
a, err := groups.DecodeOwedAsk(v)
return err == nil && a.Done()
}), func() ([]OwedRow, error) { return performedRows(performed) }, func(what, why string) error {
}), func(f OwedFilter) ([]OwedRow, error) { return performedRows(performed, f) }, func(what, why string) error {
_, err := recorder.Record(meshhandactsclient.Request{What: what, Why: why, Cause: "owed-dropped"})
return err
}, time.Now)...)
@@ -94,17 +94,55 @@ func TestTheBridgeTools(t *testing.T) {
}
return json.Marshal(a)
}
rows := []OwedRow{{Of: seat.Seat, ID: "a", Outcome: forgemsg.OwedPerformed, At: at}}
rows := []OwedRow{
{OwedEnded: forgemsg.OwedEnded{Of: seat.Seat, ID: "a", Outcome: forgemsg.OwedPerformed, At: at}, Repository: "novox/mesh-sdk", Number: 178},
{OwedEnded: forgemsg.OwedEnded{Of: seat.Seat, ID: "b", Outcome: forgemsg.OwedPerformed, At: at}, Repository: "novox/mesh-sdk", Number: 179}}
var filters []OwedFilter
performed := func(f OwedFilter) ([]OwedRow, error) {
filters = append(filters, f)
var out []OwedRow
for _, r := range rows {
if f.holds(r) {
out = append(out, r)
}
}
return out, nil
}
var recorded []string
recordErr := error(nil)
record := func(what, why string) error { recorded = append(recorded, what+": "+why); return recordErr }
tools := map[string]func(map[string]any) (any, error){}
for _, tl := range OwedTools(ask, func() ([]OwedRow, error) { return rows, nil }, record, func() time.Time { return at }) {
for _, tl := range OwedTools(ask, performed, record, func() time.Time { return at }) {
tools[tl.Name] = tl.Run
}
out, err := tools[OwedTool](map[string]any{"of": seat.Seat})
if m, _ := out.(map[string]any); err != nil || len(m["performed"].([]OwedRow)) != 1 || len(m["backlog"].([]groups.Backlog)) != 1 {
t.Errorf("bridge_owed: %v %v", out, err)
// bridge_owed reads one act or one pull request's acts, never the whole state (H-A-181).
for _, c := range []struct {
name string
args map[string]any
ids []string
}{
{"one pull request", map[string]any{"repository": "novox/mesh-sdk", "number": float64(179)}, []string{"b"}},
{"one act", map[string]any{"of": seat.Seat, "id": "a"}, []string{"a"}},
{"the whole state", map[string]any{"of": seat.Seat}, nil},
{"a repository with no number", map[string]any{"repository": "novox/mesh-sdk"}, nil},
} {
n := len(filters)
out, err := tools[OwedTool](c.args)
if c.ids == nil {
if err == nil || len(filters) != n {
t.Errorf("bridge_owed of %s: %v %v, read %d; want refused, nothing read", c.name, out, err, len(filters)-n)
}
continue
}
m, _ := out.(map[string]any)
got, _ := m["performed"].([]OwedRow)
var ids []string
for _, r := range got {
ids = append(ids, r.ID)
}
if err != nil || !reflect.DeepEqual(ids, c.ids) || len(m["backlog"].([]groups.Backlog)) != 1 {
t.Errorf("bridge_owed of %s: %v %v, want %v", c.name, out, err, c.ids)
}
}
if out, err := tools[OwedAgainTool](map[string]any{"of": seat.Seat, "id": "a"}); err != nil || out.(map[string]any)["outcome"] != forgemsg.OwedPerformed ||
asked[len(asked)-1].Kind != groups.OwedAgain {
@@ -21,26 +21,50 @@ const (
OwedDropTool = "bridge_owed_drop"
)
// OwedRow is one act the bridge performed, as the state performed keeps it: the outcome said as owed.ended.
type OwedRow = forgemsg.OwedEnded
// OwedRow is one act the bridge performed, as the state performed keeps it: the outcome said as owed.ended, and the pull
// request the act names (groups.Performed).
type OwedRow struct {
forgemsg.OwedEnded
Repository string `json:"repository,omitempty"`
Number int `json:"number,omitempty"`
}
// performedRows reads every act the state performed holds; a key that is not an act (a group end's bookkeeping) is left.
func performedRows(s stdio.KeptState) ([]OwedRow, error) {
keys, err := s.Keys()
if err != nil {
return nil, fmt.Errorf("the bridge's performed state cannot be listed: %w", err)
// OwedFilter is what bridge_owed reads of performed: one act (its id, of narrowing it to one key) or one pull request's
// acts (repository and number), never the whole state (novox/hq design 47 H-A-181).
type OwedFilter struct {
Of, ID, Repository string
Number int
}
func (f OwedFilter) holds(r OwedRow) bool {
return (f.Of == "" || r.Of == f.Of) && (f.ID == "" || r.ID == f.ID) &&
(f.Repository == "" || (r.Repository == f.Repository && r.Number == f.Number))
}
// performedRows reads the acts of performed f names, newest first: one key when f names the seat and the id, else each
// key's value held to f. A key that is not an act (a group end's bookkeeping) is left.
func performedRows(s stdio.KeptState, f OwedFilter) ([]OwedRow, error) {
var keys []string
if f.Of != "" && f.ID != "" {
keys = []string{groups.PerformedKey(f.Of, f.ID)}
} else {
all, err := s.Keys()
if err != nil {
return nil, fmt.Errorf("the bridge's performed state cannot be listed: %w", err)
}
keys = all
}
var rows []OwedRow
rows := []OwedRow{}
for _, k := range keys {
e, err := s.Get(k)
if err != nil || e == nil {
continue
}
var p struct {
Ended OwedRow `json:"ended"`
}
var p groups.Performed
if json.Unmarshal(e.Value, &p) == nil && p.Ended.Of != "" {
rows = append(rows, p.Ended)
if r := (OwedRow{OwedEnded: p.Ended, Repository: p.Repository, Number: p.Number}); f.holds(r) {
rows = append(rows, r)
}
}
}
sort.Slice(rows, func(i, j int) bool { return rows[i].At.After(rows[j].At) })
@@ -50,7 +74,7 @@ func performedRows(s stdio.KeptState) ([]OwedRow, error) {
// OwedTools are bridge_owed, bridge_owed_again and bridge_owed_drop: ask writes an owed-asks value and waits for the
// bridge's answer; performed reads the state performed; record writes a hand act in the seat mesh-hand-acts' log before
// a drop is asked, so a drop is never made without its record.
func OwedTools(ask func(key string, value []byte) ([]byte, error), performed func() ([]OwedRow, error), record func(what, why string) error, now func() time.Time) []stdio.Tool {
func OwedTools(ask func(key string, value []byte) ([]byte, error), performed func(OwedFilter) ([]OwedRow, error), record func(what, why string) error, now func() time.Time) []stdio.Tool {
str := func(args map[string]any, k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) }
act := map[string]any{
"of": map[string]any{"type": "string", "description": "the seat that said the act: mesh-delivery (the gate)"},
@@ -66,6 +90,12 @@ func OwedTools(ask func(key string, value []byte) ([]byte, error), performed fun
}
return groups.DecodeOwedAsk(v)
}
read := map[string]any{
"repository": map[string]any{"type": "string", "description": "the pull request's repository, as owner/name; with number"},
"number": map[string]any{"type": "integer", "description": "the pull request's number; with repository"}}
for k, v := range act {
read[k] = v
}
withWhy := map[string]any{"why": map[string]any{"type": "string", "description": "why it is dropped, in plain words"}}
for k, v := range act {
withWhy[k] = v
@@ -74,22 +104,24 @@ func OwedTools(ask func(key string, value []byte) ([]byte, error), performed fun
{Name: OwedTool,
Description: "What the forge bridge performed of what the gate and the checker owe the forge (design 47): each act it said as " +
"owed.ended, newest first, with its seat, id, pull request, outcome (performed, refused, could not be performed, " +
"undecodable, dropped), the forge's words and when, from its state performed (kept 7 days); and the backlog of its " +
"undecodable, dropped), the forge's words and when, from its state performed (kept 7 days), of one act (id, of " +
"narrowing it) or of one pull request (repository and number), never the whole state; and the backlog of its " +
"durable on each seat's stream owed: the last event applied, the events waiting and held, the age of the oldest. " +
"of or id narrow it. Read-only.",
Input: map[string]any{"type": "object", "properties": act},
"Read-only.",
Input: map[string]any{"type": "object", "properties": read},
Run: func(args map[string]any) (any, error) {
rows, err := performed()
f := OwedFilter{Of: str(args, "of"), ID: str(args, "id"), Repository: str(args, "repository")}
if n, ok := args["number"].(float64); ok {
f.Number = int(n)
}
if f.ID == "" && (f.Repository == "" || f.Number <= 0) {
return nil, fmt.Errorf("bridge_owed reads one act (id) or one pull request's acts (repository and number), never the whole state")
}
rows, err := performed(f)
if err != nil {
return nil, err
}
kept := []OwedRow{}
for _, r := range rows {
if (str(args, "of") == "" || r.Of == str(args, "of")) && (str(args, "id") == "" || r.ID == str(args, "id")) {
kept = append(kept, r)
}
}
out := map[string]any{"performed": kept}
out := map[string]any{"performed": rows}
if a, err := asked(groups.OwedBacklog, args); err != nil {
out["backlog-error"] = err.Error()
} else {
@@ -100,8 +132,8 @@ func OwedTools(ask func(key string, value []byte) ([]byte, error), performed fun
{Name: OwedAgainTool,
Description: "Perform one act owed to the forge again now, by hand, whatever its last outcome (a refusal the forge no longer " +
"makes, an act that could not be performed): the bridge calls the seat git's verb of the act under its id (safe to " +
"repeat) and says its outcome as owed.ended. The act is the one the bridge kept, or, for the gate's, the seat " +
"mesh-delivery's groups. Answers the outcome.",
"repeat) and says its outcome as owed.ended. The act is read from the stream owed of the seat that said it, on the " +
"subject of the pull request the bridge's state performed names (kept 7 days there). Answers the outcome.",
Input: map[string]any{"type": "object", "required": []string{"of", "id"}, "properties": act},
Run: func(args map[string]any) (any, error) {
a, err := asked(groups.OwedAgain, args)
@@ -0,0 +1,89 @@
package main
import (
"context"
"fmt"
"strconv"
"github.com/nats-io/nats.go/jetstream"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// The act bridge_owed_again performs again is read from the stream owed of the seat that said it, on the subject of the
// pull request performed names, the stream being the act's one copy (novox/hq design 47 G §162, §163, H-A-181).
// actReader reads the act the seat of said under id from its stream owed, on the subject of the pull request
// (repository and number) the act names, for decode to say each message's id; found false when the stream no longer
// holds it.
type actReader interface {
act(ctx context.Context, of, repository string, number int, id string, idOf func([]byte) string) (data []byte, found bool, err error)
}
// actOf is the act of to perform again, read from its seat's stream owed on the pull request p names.
func (o *owing) actOf(ctx context.Context, of string, p Performed, id string) ([]byte, error) {
read, err := readerOf(of)
if err != nil {
return nil, err
}
// A value of the form before H-A-182 names no pull request: every act the bridge decodes names its repository (a
// status may name no number, said on `.0` as the gate says it), so one with none is the old form, never read again.
if p.Repository == "" {
return nil, fmt.Errorf("performed names no pull request for the act %s of %s: kept in its old form, it expires with the state's TTL", id, of)
}
if o.acts == nil {
return nil, fmt.Errorf("the bridge reads no stream owed, so the act %s of %s cannot be performed again", id, of)
}
data, found, err := o.acts.act(ctx, of, p.Repository, p.Number, id, func(m []byte) string { c, _ := read(m); return c.ID })
if err != nil {
return nil, fmt.Errorf("the act %s of %s cannot be read from %s's stream owed: %w", id, of, of, err)
}
if !found {
return nil, fmt.Errorf("%s's stream owed no longer holds the act %s of %s#%d (kept 7 days)", of, id, p.Repository, p.Number)
}
return data, nil
}
// streamActs reads an act from the gate's stream owed (seat mesh-delivery's StreamOwed) by an ordered consumer filtered
// on the pull request's subject, as the gate says it (SubjectOwed with the repository escaped): every message the
// stream keeps there, the newest of the id kept.
type streamActs struct{ js jetstream.JetStream }
func (s streamActs) act(ctx context.Context, of, repository string, number int, id string, idOf func([]byte) string) ([]byte, bool, error) {
if of != seat.Seat {
return nil, false, fmt.Errorf("the seat %q keeps no stream owed the bridge reads", of)
}
subject := seat.SubjectOwed(keys.EscapeName(repository), strconv.Itoa(number))
st, err := s.js.Stream(ctx, seat.StreamOwed)
if err != nil {
return nil, false, err
}
info, err := st.Info(ctx, jetstream.WithSubjectFilter(subject))
if err != nil {
return nil, false, err
}
held := info.State.Subjects[subject]
if held == 0 {
return nil, false, nil
}
c, err := st.OrderedConsumer(ctx, jetstream.OrderedConsumerConfig{FilterSubjects: []string{subject}})
if err != nil {
return nil, false, err
}
var found []byte
for range held {
m, err := c.Next(jetstream.FetchContext(ctx))
if err != nil {
return nil, false, err
}
if idOf(m.Data()) == id {
found = m.Data()
}
if md, err := m.Metadata(); err == nil && md.NumPending == 0 {
break
}
}
return found, found != nil, nil
}
@@ -5,6 +5,7 @@ import (
"context"
"encoding/json"
"errors"
"fmt"
"log"
"strings"
"testing"
@@ -38,6 +39,24 @@ func (m memPerformed) Get(_ context.Context, key string) ([]byte, bool, error) {
}
func (m memPerformed) Put(_ context.Context, key string, v []byte) error { m[key] = v; return nil }
// memActs is a seat's stream owed by pull request subject (`<repository>#<number>`); asked records what was read.
type memActs struct {
held map[string][][]byte
asked []string
}
func (m *memActs) act(_ context.Context, of, repository string, number int, id string, idOf func([]byte) string) ([]byte, bool, error) {
pr := fmt.Sprintf("%s %s#%d", of, repository, number)
m.asked = append(m.asked, pr)
var found []byte
for _, d := range m.held[pr] {
if idOf(d) == id {
found = d
}
}
return found, found != nil, nil
}
// seatFake answers each seat verb from answers, by its key; one absent is not answered (an error, as a bound passed).
type seatFake struct {
calls []string
@@ -109,9 +128,12 @@ func TestWhatIsOwedIsPerformedSaidAndKept(t *testing.T) {
if v, ok := kept[performedKey(c.of, e.ID)]; ok != c.kept {
t.Errorf("%s: kept %v (%s), want %v", c.name, ok, v, c.kept)
} else if ok {
// The outcome and when, and the pull request the act names, nothing more (§163, H-A-181, H-A-182).
var p Performed
if err := json.Unmarshal(v, &p); err != nil || p.Ended.Outcome != c.outcome || !json.Valid(p.Owed) {
t.Errorf("%s: kept %s, want the outcome and the owed event", c.name, v)
var fields map[string]json.RawMessage
if err := json.Unmarshal(v, &p); err != nil || p.Ended.Outcome != c.outcome || p.Ended.At.IsZero() ||
p.Repository != "novox/mesh-sdk" || p.Number != 178 || json.Unmarshal(v, &fields) != nil || len(fields) != 3 {
t.Errorf("%s: kept %s, want the outcome, when, and the pull request novox/mesh-sdk#178, nothing more", c.name, v)
}
}
}
@@ -142,6 +164,9 @@ func TestWhatIsOwedIsPerformedSaidAndKept(t *testing.T) {
t.Run("asked again, dropped, and its backlog read by hand", func(t *testing.T) {
f := &seatFake{answers: statusOK}
o, pub, kept := newOwing(f)
// The act is read again from the gate's stream owed on its pull request's subject, never from performed (H-A-181).
acts := &memActs{held: map[string][][]byte{"mesh-delivery novox/mesh-sdk#178": {[]byte(`{`), gate("owed is said, a status")}}}
o.acts = acts
status := "status.novox/mesh-sdk#178.aaaaaaaaaaaa.mesh/merge-gate"
if _, err := o.heard(context.Background(), seat.Seat, gate("owed is said, a status")); err != nil {
t.Fatal(err)
@@ -153,11 +178,20 @@ func TestWhatIsOwedIsPerformedSaidAndKept(t *testing.T) {
calls, said int
outcome, answers string
}{
{"again, from performed", groups.OwedAsk{Kind: groups.OwedAgain, Of: seat.Seat, ID: status}, 2, 2, forgemsg.OwedPerformed, "performed"},
{"again, from the gate's stream owed", groups.OwedAsk{Kind: groups.OwedAgain, Of: seat.Seat, ID: status}, 2, 2, forgemsg.OwedPerformed, "performed"},
{"dropped", groups.OwedAsk{Kind: groups.OwedDrop, Of: seat.Seat, ID: status, Why: "set by hand", By: "lead@shanks"}, 2, 3, forgemsg.OwedDropped, "set by hand"},
{"again, an act nobody holds", groups.OwedAsk{Kind: groups.OwedAgain, Of: seat.Seat, ID: "x"}, 2, 3, "", "holds no owed act"},
{"the backlog", groups.OwedAsk{Kind: groups.OwedBacklog}, 2, 3, "", "backlog"},
{"again, the stream no longer holding it", groups.OwedAsk{Kind: groups.OwedAgain, Of: seat.Seat, ID: status}, 2, 3, "", "no longer holds"},
{"again, a value of the old form", groups.OwedAsk{Kind: groups.OwedAgain, Of: seat.Seat, ID: "old"}, 2, 3, "", "names no pull request"},
} {
switch c.name {
case "again, the stream no longer holding it":
acts.held = nil
case "again, a value of the old form":
// Kept before H-A-182: the outcome and the whole act, no pull request; the stream is not read for it.
kept[performedKey(seat.Seat, "old")] = []byte(`{"ended":{"v":1,"of":"mesh-delivery","id":"old","outcome":"performed","at":"2026-11-09T21:00:00Z"},"owed":{"id":"old"}}`)
}
a := o.answer(context.Background(), c.ask, backlog)
if !a.Done() || a.Outcome != c.outcome || !strings.Contains(a.Answer, c.answers) || len(f.calls) != c.calls || len(pub.data) != c.said {
t.Errorf("%s: %+v, called %v, said %d; want %q naming %q, %d calls, %d said", c.name, a, f.calls, len(pub.data), c.outcome, c.answers, c.calls, c.said)
@@ -167,8 +201,12 @@ func TestWhatIsOwedIsPerformedSaidAndKept(t *testing.T) {
}
}
var p Performed
if err := json.Unmarshal(kept[performedKey(seat.Seat, status)], &p); err != nil || p.Ended.Outcome != forgemsg.OwedDropped {
t.Errorf("performed after the drop: %+v %v", p, err)
if err := json.Unmarshal(kept[performedKey(seat.Seat, status)], &p); err != nil || p.Ended.Outcome != forgemsg.OwedDropped ||
p.Repository != "novox/mesh-sdk" || p.Number != 178 {
t.Errorf("performed after the drop: %+v %v; want dropped, its pull request kept", p, err)
}
if len(acts.asked) != 2 || acts.asked[0] != "mesh-delivery novox/mesh-sdk#178" {
t.Errorf("the stream owed was read on %v, want twice on the pull request performed names", acts.asked)
}
})
}
@@ -22,6 +22,7 @@ import (
git "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/git"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-forge-bridge/forgemsg"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-forge-bridge/internal/gitfixture"
@@ -33,7 +34,8 @@ import (
// no others, so a permission the bridge lacks fails a test here and not on the mesh (issue 1279).
//
// From module.json: the registrations and the gate's source-moved heard through its durable on EVENTS; branch-moved and
// what the gate owes heard through its durable on each seat's own stream (SEAT_<seat>_<event>); the seat git's verbs, the
// what the gate owes heard through its durable on each seat's own stream (SEAT_<seat>_<event>), and each seat's kept
// event also read through an ordered consumer of its own (mesh-grants heardGrants, A-233; bridge_owed_again, H-A-181); the seat git's verbs, the
// seat mesh-catalog's registrations, the seat mesh-delivery's source, the seat mesh-broker's show and the seat
// mesh-hand-acts' hand-act called on mesh.seat.<seat>.call.<verb>.<token> (or its plain fallback); its own states heads
// and owed-asks, and performed under the name its binding gives; its stream forge. `**` is written `>` on the wire. The
@@ -82,6 +84,11 @@ accounts {
"$JS.ACK.SEAT_mesh-delivery_owed.n1_mesh-delivery-forge-bridge.>"
"$JS.API.CONSUMER.INFO.SEAT_mesh-delivery_owed.n1_mesh-delivery-forge-bridge"
"$JS.API.CONSUMER.MSG.NEXT.SEAT_mesh-delivery_owed.n1_mesh-delivery-forge-bridge"
"$JS.API.CONSUMER.CREATE.SEAT_mesh-delivery_owed"
"$JS.API.CONSUMER.CREATE.SEAT_mesh-delivery_owed.>"
"$JS.API.CONSUMER.MSG.NEXT.SEAT_mesh-delivery_owed.*"
"$JS.API.CONSUMER.INFO.SEAT_mesh-delivery_owed.*"
"$JS.API.CONSUMER.DELETE.SEAT_mesh-delivery_owed.*"
"mesh.seat.mesh-broker.call.show.n1~mesh-delivery-forge-bridge"
"mesh.seat.mesh-broker.tool.show"
"mesh.seat.mesh-catalog.call.registrations.n1~mesh-delivery-forge-bridge"
@@ -518,7 +525,9 @@ func TestBridgePerformsWhatIsOwedOnce(t *testing.T) {
}
}
gateOwed := gitfixture.Seat(t, seat.Seat, "events", "owed is said, a status", "event:owed")[0]
subject := seat.SubjectOwed("novox~mesh-sdk", "178")
// On the pull request's subject as the gate says it (its repository escaped as a key part), where bridge_owed_again
// reads the act again (H-A-181).
subject := seat.SubjectOwed(keys.EscapeName("novox/mesh-sdk"), "178")
for range 2 {
if _, err := b.js.Publish(b.ctx, subject, gateOwed); err != nil {
t.Fatal(err)
@@ -597,12 +606,22 @@ func TestBridgePerformsWhatIsOwedOnce(t *testing.T) {
if a, err := groupkeys.DecodeOwedAsk(e.Value()); err == nil && a.Done() {
answered = true
if a.Outcome != forgemsg.OwedPerformed || count("git.status") != 3 {
t.Errorf("bridge_owed_again: %+v, status asked %d times; want performed again", a, count("git.status"))
t.Errorf("bridge_owed_again: %+v, status asked %d times; want performed again, read from the gate's stream owed", a, count("git.status"))
}
}
case <-bound:
t.Fatal("bridge_owed_again was not answered within 20 s")
}
}
// performed keeps the outcome, when and the pull request, never the act (§163, H-A-181, H-A-182).
kept, err := b.js.KeyValue(b.ctx, boundPerformed)
if err != nil {
t.Fatal(err)
}
if e, err := kept.Get(b.ctx, performedKey(seat.Seat, g.ID)); err != nil {
t.Errorf("performed of %s: %v", g.ID, err)
} else if fields := (map[string]json.RawMessage{}); json.Unmarshal(e.Value(), &fields) != nil || len(fields) != 3 || fields["owed"] != nil {
t.Errorf("performed of %s keeps %s, want the outcome, when and the pull request alone", g.ID, e.Value())
}
refusedRead(t, b, "mesh-delivery-gate_owed")
}
@@ -108,7 +108,7 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
}
performedKV := &boundBucket{binding: binding, local: performedLocal, js: js}
// What the gate owes the forge, performed through the seat git (design 47 *What the gate owes the forge*).
owe := &owing{call: call, pub: js, performed: kvPerformed{performedKV}, waits: binding.Waiting, now: time.Now, logger: logger}
owe := &owing{call: call, pub: js, performed: kvPerformed{performedKV}, acts: streamActs{js: js}, waits: binding.Waiting, now: time.Now, logger: logger}
keptCall := keptCallOf(ctx, call)
reader := &views.ProcessReader{Module: forgeBridgeModule(), Call: keptCall, Logf: logger.Printf, Hub: hub}
src := sourcebranches.New(sourcebranches.Call(keptCall))
@@ -2,7 +2,6 @@ package main
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
@@ -22,22 +21,14 @@ import (
)
// The state performed (manifest `requires`, the template state, opened by its binding: bound.go) keeps one key per owed act it
// performed, the act's outcome and when, with the owed event as heard (novox/hq design 47 *What the gate owes the
// forge*). It is a saving and a read, never what keeps an act from happening twice: every act is safe to repeat at the
// forge.
// performed, in the form groups.Performed says (novox/hq design 47 G §163, H-A-181, H-A-182). It is a saving and a read,
// never what keeps an act from happening twice: every act is safe to repeat at the forge.
// performedKey is the key of one act in performed: the seat that said it and its id, the id in unpadded base64url, since
// an id may hold what a key may not (`#`, `/`).
func performedKey(of, id string) string {
return of + "." + base64.RawURLEncoding.EncodeToString([]byte(id))
}
// performedKey is the key of one act in performed (groups.PerformedKey).
func performedKey(of, id string) string { return groups.PerformedKey(of, id) }
// Performed is one value of the state performed: the outcome said as owed.ended, and the owed event it answers, so
// bridge_owed_again performs it again from here.
type Performed struct {
Ended forgemsg.OwedEnded `json:"ended"`
Owed json.RawMessage `json:"owed,omitempty"`
}
// Performed is one value of the state performed.
type Performed = groups.Performed
// performedStore is the state performed as the owing reads and writes it.
type performedStore interface {
@@ -70,6 +61,8 @@ type owing struct {
call caller
pub publisher
performed performedStore
// acts reads an act again from the stream owed of the seat that said it (H-A-181), for bridge_owed_again.
acts actReader
// waits, when set, says why the state performed cannot be used yet (its binding, design 47 G §577); empty when it can.
waits func() string
now func() time.Time
@@ -90,12 +83,12 @@ func readerOf(of string) (func([]byte) (bridge.OwedCall, error), error) {
func (o *owing) heard(ctx context.Context, of string, data []byte) (forgemsg.OwedEnded, error) {
read, err := readerOf(of)
if err != nil {
return o.end(ctx, forgemsg.OwedEnded{Of: of, Outcome: forgemsg.OwedUndecodable, Words: err.Error()}, data)
return o.end(ctx, forgemsg.OwedEnded{Of: of, Outcome: forgemsg.OwedUndecodable, Words: err.Error()}, "", 0)
}
c, err := read(data)
if err != nil {
return o.end(ctx, forgemsg.OwedEnded{Of: of, ID: c.ID,
Outcome: forgemsg.OwedUndecodable, Words: err.Error()}, data)
Outcome: forgemsg.OwedUndecodable, Words: err.Error()}, c.Repository, c.Number)
}
if w := o.waiting(); w != "" {
return forgemsg.OwedEnded{Of: c.Of, ID: c.ID}, fmt.Errorf("the bridge %s", w)
@@ -104,7 +97,7 @@ func (o *owing) heard(ctx context.Context, of string, data []byte) (forgemsg.Owe
// said twice, or said again while its outcome was on its way: performed once, the outcome said once
return forgemsg.OwedEnded{Of: c.Of, ID: c.ID}, nil
}
return o.perform(ctx, c, data)
return o.perform(ctx, c)
}
// hear is one message of a seat's stream owed: performed and acknowledged, or, when its outcome could not be said,
@@ -127,19 +120,20 @@ func (o *owing) waiting() string {
}
// perform calls the seat git's verb of one act and says what it came to.
func (o *owing) perform(ctx context.Context, c bridge.OwedCall, data []byte) (forgemsg.OwedEnded, error) {
func (o *owing) perform(ctx context.Context, c bridge.OwedCall) (forgemsg.OwedEnded, error) {
answer, callErr := o.call(ctx, "seat:"+git.Seat+"."+c.Verb, c.Input)
outcome, words := bridge.Outcome(answer, callErr)
if outcome != forgemsg.OwedPerformed {
o.logger.Printf("the owed %s %s of %s#%d (said by %s) is %s: %s", c.Act, c.ID, c.Repository, c.Number, c.Of, outcome, words)
}
return o.end(ctx, forgemsg.OwedEnded{Of: c.Of, ID: c.ID,
Outcome: outcome, Words: words}, data)
Outcome: outcome, Words: words}, c.Repository, c.Number)
}
// end says an act's outcome as owed.ended on the stream forge, then keeps it in performed. An outcome not kept is
// logged: the act may be performed again, which changes nothing at the forge.
func (o *owing) end(ctx context.Context, e forgemsg.OwedEnded, owed []byte) (forgemsg.OwedEnded, error) {
// end says an act's outcome as owed.ended on the stream forge, then keeps it in performed with the pull request the act
// names (repository and number). An outcome not kept is logged: the act may be performed again, which changes nothing at
// the forge.
func (o *owing) end(ctx context.Context, e forgemsg.OwedEnded, repository string, number int) (forgemsg.OwedEnded, error) {
e.At = o.now().UTC()
data, err := forgemsg.EncodeOwedEnded(e)
if err != nil {
@@ -151,10 +145,7 @@ func (o *owing) end(ctx context.Context, e forgemsg.OwedEnded, owed []byte) (for
if e.ID == "" {
return e, nil // an undecodable act with no id is said, and has no key to keep
}
if !json.Valid(owed) {
owed = nil
}
v, err := json.Marshal(Performed{Ended: e, Owed: owed})
v, err := json.Marshal(Performed{Ended: e, Repository: repository, Number: number})
if err == nil {
err = o.performed.Put(ctx, performedKey(e.Of, e.ID), v)
}
@@ -175,19 +166,17 @@ func (o *owing) held(ctx context.Context, of, id string) bool {
return found
}
// owedOf is the owed event of an act to perform again, as performed keeps it.
func (o *owing) owedOf(ctx context.Context, of, id string) ([]byte, error) {
// kept is what performed holds of an act: its outcome and its pull request.
func (o *owing) kept(ctx context.Context, of, id string) (Performed, error) {
v, found, err := o.performed.Get(ctx, performedKey(of, id))
if err != nil {
return nil, fmt.Errorf("performed cannot be read: %w", err)
return Performed{}, fmt.Errorf("performed cannot be read: %w", err)
}
if found {
var p Performed
if err := json.Unmarshal(v, &p); err == nil && len(p.Owed) > 0 {
return p.Owed, nil
}
var p Performed
if !found || json.Unmarshal(v, &p) != nil {
return Performed{}, fmt.Errorf("the bridge holds no owed act %s of %s in its state performed", id, of)
}
return nil, fmt.Errorf("the bridge holds no owed act %s of %s in its state performed", id, of)
return p, nil
}
// answer answers one owed ask: an act performed again now, whatever performed holds of it; an act dropped, said as
@@ -199,20 +188,22 @@ func (o *owing) answer(ctx context.Context, a groups.OwedAsk, backlog func(conte
a.Backlog, a.Answer = backlog(ctx), "the backlog of each seat's stream owed"
return a
}
data, err := o.owedOf(ctx, a.Of, a.ID)
p, err := o.kept(ctx, a.Of, a.ID)
if err != nil {
a.Answer = err.Error()
return a
}
var e forgemsg.OwedEnded
if a.Kind == groups.OwedDrop {
e, err = o.end(ctx, forgemsg.OwedEnded{Of: a.Of, ID: a.ID, Outcome: forgemsg.OwedDropped, Words: a.Why + " (dropped by " + a.By + ")"}, data)
e, err = o.end(ctx, forgemsg.OwedEnded{Of: a.Of, ID: a.ID, Outcome: forgemsg.OwedDropped, Words: a.Why + " (dropped by " + a.By + ")"}, p.Repository, p.Number)
} else if read, rerr := readerOf(a.Of); rerr != nil {
err = rerr
} else if data, rerr := o.actOf(ctx, a.Of, p, a.ID); rerr != nil {
err = rerr
} else if c, rerr := read(data); rerr != nil {
e, err = o.end(ctx, forgemsg.OwedEnded{Of: a.Of, ID: a.ID, Outcome: forgemsg.OwedUndecodable, Words: rerr.Error()}, data)
e, err = o.end(ctx, forgemsg.OwedEnded{Of: a.Of, ID: a.ID, Outcome: forgemsg.OwedUndecodable, Words: rerr.Error()}, p.Repository, p.Number)
} else {
e, err = o.perform(ctx, c, data)
e, err = o.perform(ctx, c)
}
if err != nil {
a.Answer = err.Error()
@@ -0,0 +1,26 @@
package groups
import (
"encoding/base64"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-forge-bridge/forgemsg"
)
// The state performed keeps one key per owed act the bridge performed, its outcome and when, and the pull request the
// act names, nothing more (novox/hq design 47 G §163, H-A-181, H-A-182): the act itself stays in the stream owed of the
// seat that said it, its one copy, where bridge_owed_again reads it again. The bridge writes it; its tools read it.
// PerformedKey is the key of one act in performed: the seat that said it and its id, the id in unpadded base64url, since
// an id may hold what a key may not (`#`, `/`).
func PerformedKey(of, id string) string {
return of + "." + base64.RawURLEncoding.EncodeToString([]byte(id))
}
// Performed is one value of the state performed (§163, H-A-182): the outcome said as owed.ended, with when, and the
// repository and number of the pull request the act names, so bridge_owed reads one pull request's acts and
// bridge_owed_again finds the act on its pull request's subject of the stream owed (H-A-181).
type Performed struct {
Ended forgemsg.OwedEnded `json:"ended"`
Repository string `json:"repository,omitempty"`
Number int `json:"number,omitempty"`
}

Some files were not shown because too many files have changed in this diff Show More