Compare commits

..
Author SHA1 Message Date
mesh-tools 7be95905f2 Merge pull request 'A pipeline's kept revisions are pinned; a lost one ends the pipeline loudly; the held take-in chain is visible (design 47 H2 H-A-496, H-A-497)' (#338) from fix/kept-revision-pins into main 2026-11-22 20:59:29 +00:00
jschoubben 04fe2e30fe H-A-497 indexer: a hand ask of a held branch answers at once
indexer_take_in_pending ran the whole chain of held take-ins inside the one
loop that acts on the takeins asks, minutes long, so its answer was cut and a
second ask waited behind it and answered "holds no source-moved". The ask
now starts the chain beside the loop and answers at once, "chain started at
source <n>, <m> wait"; an ask that meets a running chain answers its state.
The chain's state (branch, source being taken in, since, how many wait) is
the key chain.<branch> of the takeins state, written at each step and
deleted at the chain's end, skipped by the asks' loop and shown by
indexer_pending. A key a stop left is deleted at the indexer's start.

Builds: design 47 H2 H-A-497 (corrected), its addendum and its second addendum
2026-11-22 21:58:07 +01:00
jschoubben 52ad5af1e9 H-A-497 indexer: say each held source the chain takes in next
The indexer already takes a branch's held sources in order in one pass, but
nothing said so: on 22 Nov one hand ask took 114, 115 and 116 in turn, about
four minutes each, and it looked as if each needed its own hand call. Each
take-in the chain starts after one landed is now a journal line, "held
source <n> of <branch> taken in next, after <n-1>".

Builds: design 47 H2 H-A-497 (corrected)
2026-11-22 21:28:45 +01:00
jschoubben cd16358b21 H-A-496 indexer: pin the revisions a pipeline's movers are kept at
The indexer pinned only a pipeline's own revision, so JudgePins removed
revision 292 while main.291's kept mover still had to read it. HeardPins now
pins every revision pipeline-started names in kept under the pipeline's
record, takes the latest started (said again at a re-pin) as the kept set,
freeing a kept revision it no longer names but never the pipeline's own or
its validate base, and pipeline-ended frees them all. JudgePins is
unchanged.

Builds: design 47 H2 H-A-496, H-A-496 addendum
2026-11-22 21:25:33 +01:00
jschoubben 0c2ead025d H-A-496 runner: say kept revisions; a gone kept revision ends the pipeline
main.291 held the one pipelines-at-once turn 50 minutes waiting for kept
revision 292, which the catalog had removed: nothing pinned it and the wait
had no end. pipeline-started now carries every revision the pipeline's movers
are kept at, and a re-pin says it again with the full list, so the indexer
pins them. A catalog read answered "no such object" is the revision gone;
the placing then ends the pipeline failed "kept revision <r> gone", its
movers are left unfinished and rejoin the next pipeline, and its turn is
freed.

Builds: design 47 H2 H-A-496, H-A-496 addendum
2026-11-22 21:23:48 +01:00
jschoubben 5ab9bd9acc H-A-496 contracts: pipeline-started carries the movers' kept revisions
The indexer pinned only a pipeline's own catalog revision, so a revision a
re-pin kept a mover at could be removed while the pipeline still read it
(main.291 waited 50 minutes on removed revision 292). pipeline-started now
carries kept, every revision the pipeline's movers are kept at, said again in
full at each re-pin, so the indexer can pin them. The runner seat's form is
9; the contract is regenerated.

Builds: design 47 H2 H-A-496, H-A-496 addendum
2026-11-22 21:17:08 +01:00
mesh-tools dc33ae26bb Merge pull request 'mesh-delivery-sdk: registry transfers finished or taken over; missing output said (design 47 H2 H-A-481, H-A-482)' (#337) from fix/transfers-and-output into main 2026-11-22 20:05:01 +00:00
mesh-tools a096397928 Merge pull request 'mesh-delivery-builder, mesh-delivery-indexer: upstream artifacts by pinned digest; newest entry only; no git tag (design 47 H2 H-A-486, H-A-487, H-A-489, H-A-492, H-A-494)' (#336) from fix/upstream-release into main 2026-11-22 20:04:59 +00:00
mesh-tools 5548fff81f Merge pull request 'mesh-grants, mesh-delivery-assigner, mesh-delivery-indexer: the tool runner's twin from the membership; a pin names a released version (design 47 H2 H-A-472, H-A-490, H-A-495)' (#335) from fix/tools-twin-membership into main 2026-11-22 20:04:57 +00:00
jschoubben 52fa062e92 H-A-494: the builder writes no git tag at a release and numbers from no tag
A Go package comes from the Go package registry alone, so a released version
is no longer written as a git tag: the release path and the start's take-in
of a released version call no seat git, and a reserve numbers a series from
the catalog's versions and the registries' only, never reading tags. A
reservation's kept tag field stays for records written before.

Builds: design 47 H2 H-A-494 (withdraws H-A-484's tag steps and H-A-493; design 51's fallback tag retired)
2026-11-22 20:56:51 +01:00
jschoubben ef32d60a5e Indexer: a pin names a released version only, never a reservation (H-A-495)
Importers were pinned to mesh-delivery-contracts 0.1.82 to 0.1.84, reserved by
builds a competing build withdrew before release and never published, so their
builds failed "unknown revision". The series' numbered version a reservation
writes no longer pins: a pin is the series' newest released version, so a
version-reserved moves no pin and the release's re-pin moves the importers. A
pin held on a version never released is moved at the next take-in or re-pin and
said per module ("<module>: pinned to <pkg> <v>, never released; moved to <v2>").

Builds: design 47 H2 H-A-495 and its addendum (hq 9e0923ce)
2026-11-22 20:48:32 +01:00
jschoubben cfd2afe39c H-A-492: the record's bound is a setting; a build key read error is said
Review round 1 (principle 11, configurable, never hard-coded): the bound of
the record of a version's digests is the builder's setting
record-bound-seconds (default 60), read from its file as revision-wait and
package-wait are, set on the Builder and used for the record. A build key
the builder cannot read, or that holds no build, is said in its journal
instead of being taken silently as not done (principle 3, failure is loud).

Builds: design 47 H2 H-A-492
2026-11-22 20:25:03 +01:00
jschoubben 21daeb8893 H-A-492: record a version's digests under the builder's own bound
A takeover or an end cancelling a build's context cancelled the record of its
reservation's digests eight times in a day, each leaving a passed build
unreleased. The record now runs under the builder's own bound (one minute,
not cancelled with the build), and a done build whose digests are not
recorded is recorded from its done key at the builder's next look and at its
start (before H-A-484's start check holds it against the released versions),
said each time.

Builds: design 47 H2 H-A-492
2026-11-22 20:17:14 +01:00
jschoubben ae1bf2098d Assigner: a put's want names the version released at its build (H-A-490 addendum)
A put wrote its want by fingerprint alone, which the node-engine cannot
compose. The put now finds the version released at its build's parts, as the
pass does, names it in the want, and is refused when none is released.

Builds: design 47 H2 H-A-490 (addendum)
2026-11-22 20:04:34 +01:00
jschoubben f09bd2668a Assigner: a passed pipeline takes a mover's version released before the pass (H-A-490)
An again pipeline on a built, published key ends naming no version, and the
runner never says its end again, so its movers kept the old want. At the pass,
a mover with no version is matched to the release of its build's parts.

Builds: design 47 H2 H-A-490
2026-11-22 19:57:15 +01:00
jschoubben 82156f8128 mesh-grants: a never-read durable is an orphan; both twins judged where uncomposed
Review round 2: a durable nobody ever read (no pull waiting, no delivery ever) was
named behind when its twin was not current, and the plain durable of a module whose
program left was never judged (live: claude-code's plain durables 1,000 to 3,000
behind beside a current `_tools` twin). A never-read durable is now an orphan
whatever its twin; one read once and lagging stays behind. The pass judges both
twins of every heard entry wherever no pass composes them, also on a stream where
only such durables are held.

Builds: design 47 H2 H-A-472 (eleventh addendum)
2026-11-22 19:54:25 +01:00
jschoubben ffa58e51c4 H-A-489: test the withdrawn step answer and the look before reserving
Review round 1 found two paths untested: a step ask of a withdrawn key
still newest answers failed at once, and a newer entry heard between the
older build's claim and its reservation is not taken over. Each row
fails without its line. The comments of H-A-205 say that H-A-489
overrides it once the newer entry is heard.

Builds: design 47 H2 H-A-489 (review round 1)
2026-11-22 19:51:59 +01:00
jschoubben cc1034630f mesh-grants: the consumers pass judges the tool runner's held twins too
Review round 1 found that with no `_tools` twin composed, the behind and orphan
checks never looked at one: live, five twins on EVENTS held 1,000 to 58,000
messages and none was named. The pass now reads, on the streams each consuming
module's heard entries name, every held `<consumer>_tools` and judges it as any
consumer: behind by the bound, or an orphan when no pull waits and its twin is
current. The stale comments on HasProgram and the orphan finding's text follow.

Builds: design 47 H2 H-A-472 (tenth addendum)
2026-11-22 19:47:49 +01:00
jschoubben 73cb9ba690 H-A-489: build only a branch's newest entry; withdrawn is final
Two fingerprints of one module took the series from each other (nats
flipped between 0.1.140 and 0.1.152): a later look built an older
fingerprint again, and its reservation took the newer one's over.

The builder now refuses, before it reserves or builds, a fingerprint of
the first watched branch that is no longer the newest entry heard there,
saying once per key that it is superseded; a step ask of it fails so,
never waits. It looks again just before it reserves. A key withdrawn is
taken again by no look, only by a person's build again.

Builds: design 47 H2 H-A-489
2026-11-22 19:45:03 +01:00
jschoubben fcac1fc5d0 H-A-487: prove a listing reads no history when its entries carry no time
Review round 1 found the fingerprint guard of the build read unproven: every
entry of the 100-key listing carried a time. The listing is now also read with
entries that say none, and no history may be read.

Builds: design 47 H2 H-A-487 (review round 1 finding)
2026-11-22 19:37:22 +01:00
jschoubben db899d8ad4 H-A-487: a module's builds are read without every key's history
builder_build read every key's whole history to learn when its entry was
written, one more round trip per key of the module; on nats's hundreds of keys
the read crawled. Each entry's own write time now comes with the key's read,
the history is read only for the one key a fingerprint names when its entry
says no time, and a listing cut at the 20 newest says so in its note.

Builds: design 47 H2 H-A-487
2026-11-22 19:30:59 +01:00
jschoubben 4ca6e478a6 mesh-grants: the membership carries the tool runner's twin spec; no twin composed
The grants part stays the one composer of filters while the tool runner makes its
own `_tools` twin: each heard entry, EVENTS included, carries the twin's filters
(the again filter named for it), ack wait, max deliver, max ack pending and
deliver policy. The pass composes no `_tools` consumer any longer, so it makes no
twin nothing reads; the reader grants add the create and delete of the module's
own twin by name. A membership of a module no longer assigned on its node is
withdrawn by a whole pass, so the runner there removes that module's twins. The
part's own hearing loop leaves EVENTS to the hub, now that the membership names it.

Builds: design 47 H2 H-A-472 (fifth, sixth, seventh, eighth and ninth addenda)
2026-11-22 19:30:19 +01:00
jschoubben 564fd5e0bb H-A-486: an upstream artifact needs no publish to release
Design 51 copies an upstream image by its pinned digest, and distribution's
mirror says published with no version, so nats, hello-web, mailu and showcase
could never be released. The reservation keeps its upstream refs (Upstream,
filled at the reserve from the plan's upstream tasks) and Missing never awaits
them; the indexer releases a version once every other artifact is published,
naming each upstream artifact with the pin its manifest gives, and refuses the
release loudly when an upstream artifact names no pin.

Builds: design 47 H2 H-A-486, H-A-486 (addendum)
2026-11-22 19:26:22 +01:00
jschoubben dc6dfef6f0 A reopen drops without a store only when the holder holds the file (H-A-481 second addendum)
The drop without a second store judged from the parts the holder holds,
and distribution's Holds answers per layer: a publish cut before its
store, whose layers were held, was dropped and never said as published.
The drop now asks the holder's own HoldsWhole (the file at its name and
version); nil never drops, and the reopen finishes as usual.

Builds: design 47 H2 H-A-481 second addendum
2026-11-22 19:25:40 +01:00
jschoubben 8eee17a368 A reopen verifies its parts; the takeover bound is a field (H-A-481 addendum)
A reopen that lacked nothing finished from the held set without reading
the chunks back, so a finish cut after its chunks were dropped, or after
its store, stored wrong bytes or stored twice. Now each part taken is
read back and hashed against its digest as a take does, a failing part is
lacked again, and a transfer whose every part the holder already holds is
dropped without a second store. The takeover bound is the receiver's
field TakeOver, two minutes by default, as its sibling bounds.

Builds: design 47 H2 H-A-481 addendum; review round 1 findings (1), (2)
2026-11-22 19:21:47 +01:00
jschoubben 2b79ee1593 A missing output is said as missing; a failed build keeps its error (H-A-482)
The verb output failed "holds no header" on an empty object, since the
runtime's object read answers an absent object as empty data without an
error: an empty object is now no object, said "the ask kept no output".
A failed build kept nothing for the verb output to answer: it now keeps
its error text, as the build module bounded it, as the ask's output
object with the header a test step's carries.

Builds: design 47 H2 H-A-482, H-A-482 addendum (a)
2026-11-22 19:14:02 +01:00
jschoubben 9931d4f900 A transfer is finished or taken over, never left open (H-A-481)
An opener that opened a transfer again with nothing lacked was answered
"nothing lacked" and the transfer never finished; another caller with the
same digest was refused; and a transfer lacking nothing at its open was
finished without its idle bound, so a restart during the finish left it
open. Now a reopen with nothing lacked finishes it, by its opener or by
another caller; a transfer that lacks a part is taken over by another
caller once its last part is older than two minutes; and the idle bound
is armed before every finish at an open.

Builds: design 47 H2 H-A-481
2026-11-22 19:12:33 +01:00
mesh-tools 18136ce063 Merge pull request 'The builder re-reads released versions at start and waits the pause on a refused tag; one parse of every pipeline key form (H-A-484, H-A-485)' (#334) from fix/tags-and-again-tiers into main 2026-11-22 18:06:50 +00:00
jschoubben a5495bb15e Read every pipeline key form by one parse; the assigner moves an again pipeline's tiers (H-A-485)
The assigner took a tier progress for `pipeline.<branch>.<revision>` only (two dots), so
the progress of a pipeline started again at the head, `<branch>.<revision>.again.<n>`,
was never moved and read as an empty end: its later tiers were never wanted. One parse
of the runner's seat's key forms (mesh-delivery-sdk pipelinekey, over the contract's key
parsers) now reads a pipeline's key for the assigner's tier progress and the runner's
mover keys; a pipeline-ended whose key is of no form is refused loudly and nothing of
it is kept.

Builds: design 47 H2 H-A-485
2026-11-22 18:54:40 +01:00
jschoubben 5d3164b5b7 Builder: take a released version the catalog holds at the start; a refused tag waits the pause (H-A-484)
A version-released whose tag the seat git's holder refused was handed back at once,
spent its five deliveries in seconds and was dropped by the bus: its reservation stood
and its publish item asked again every 30 s for ever. At the start the builder now holds
every built, unreleased reservation against the catalog's verb versions and takes a
released one in as its version-released would (tag, release, bound and item ended,
findings cleared); a refused tag is handed back with the publish pause. The tag check
itself is the forge module's, already accepting a nested package path on the catalog's
trunk.

Builds: design 47 H2 H-A-484, H-A-484 addendum
2026-11-22 18:49:52 +01:00
mesh-tools 96d8136e2b Merge pull request 'The builder's publishes have one consumer per holder; publish_first retired (H-A-483)' (#333) from fix/publishes-one-consumer into main 2026-11-22 17:39:50 +00:00
jschoubben c45f1621fb Seat mesh-builds: publish-queue lists in stream order (H-A-483)
The verb's description and its answer's class and list say what the
builder now does: one consumer per holder, items listed in stream order,
no class pulled first. Description only, regenerated with seatgen; the
seat's format stays, as at B4's description changes of this seat.

Builds: design 47 H2 H-A-483 third addendum, §793
2026-11-22 18:30:30 +01:00
jschoubben fd2cb13961 Publish queue: retire builder_publish_first, list in stream order (H-A-483)
With one consumer per holder an item has no class to move ahead of, so
builder_publish_first, its mode and its act go. The verb publish-queue
lists the items in stream order, the order the one consumer gives them,
and its description says so. A holder is a module name, so one ending in
-live or -again (an earlier release's class durable) is refused at the
learn, said, instead of having another holder's durable deleted.

Builds: design 47 H2 H-A-483 third addendum, §793
2026-11-22 18:28:55 +01:00
jschoubben 915a54f136 Publish queue: one pull consumer per holder (H-A-483)
The two class consumers (live, again) could not order live before again
under every scheduling: the idle-dispatch row failed on the build node
after four review rounds. One consumer per learnt holder (publishes-<holder>)
gives items in order; a failed send is handed back with its pause, so an
item put meanwhile goes first by construction. The builder retires the
holder's class durables of the earlier release before making the one,
since a work queue refuses overlapping filters; their unacknowledged items
reach the one consumer. The gap read, the held again items and the live
in-flight check go.

Builds: design 47 H2 H-A-483, its addendum and second addendum, §793
2026-11-22 18:20:06 +01:00
mesh-tools 1c0309df23 Merge pull request 'The assigner's blocked-keeping test waits for the keeping (H-A-476)' (#332) from fix/assigner-test-race into main 2026-11-22 15:34:10 +00:00
mesh-tools 7dd2891f32 Merge pull request 'A failed mover is started again at the head; a reopening pins its revision again (H-A-479)' (#331) from fix/runner-start-modules into main 2026-11-22 15:34:08 +00:00
mesh-tools b7e364e47b Merge pull request 'grants-for answers from what it kept; the runner's widens bound 30 s (H-A-478)' (#330) from fix/grants-for-kept into main 2026-11-22 15:34:04 +00:00
jschoubben dca2545eb7 H-A-479 third addendum: a reopening never builds beside an open pipeline
A rerun that would reopen an ended pipeline while another open delivering
pipeline carries one of its movers at the same revision is refused with
"its pipeline <key> is running", nothing asked, so one entry is never built
side by side. Tests now cover the two paths review round 2 found untested:
the indexer keeps a revision's gathering while another pipeline's
reservation is left and removes it with the last, and a test step's rerun
reopening an ended pipeline says pipeline-started before its run is started
again.

Builds: design 47 H2 H-A-479 third addendum, H-A-479 second addendum, H-A-479 addendum (2); review round 2
2026-11-22 16:29:24 +01:00
jschoubben bd5852b817 H-A-479 second addendum: own movers withdrawn, no side-by-side start, unbounded n
A pipeline ending not passed withdrew every reservation of its revision, so
an again pipeline's failure could withdraw the head's take-in pipeline's
reservations and the other way round. The indexer now withdraws only the
reservations of the ended pipeline's own movers, read from the movers its
pipeline-ended carries, and withdraws the revision's gathering only when
none is left. A start with modules is refused for a module whose head entry
a pipeline still runs ("its pipeline <key> is running"), and takes the next
n without a bound. A rerun reopening an ended pipeline says its
pipeline-started before the step is asked again, so the revision is pinned
before anything reads it. Tests now cover the again form through the
branch's key forms and a release written into a passed again pipeline.

Builds: design 47 H2 H-A-479 second addendum, H-A-479 addendum (2); review round 1
2026-11-22 16:21:31 +01:00
jschoubben 1bfd54425b mesh-grants: kept grants are keyed by revision and inputs, bound tested
A revision's kept grants carry the digest of the inputs they were
composed with; an ask whose inputs differ composes again, so grants-for
never lists a change the candidate did not cause. TestGrantsForKeepsWhatItMay
now proves that a revision dropped beyond the bound has no grants kept
either (review round 1); the Logf comment says the tools program's
journal too.

Builds: design 47 H2 H-A-478 second addendum
2026-11-22 16:13:08 +01:00
jschoubben c6c86801ca H-A-479 (2) runner: a rerun reopening an ended pipeline pins its revision again
The indexer pins a pipeline's revision from pipeline-started to
pipeline-ended, so a rerun of a step in an ended pipeline (main.258's
composition at 14:41, after its end at 14:15) asked a step against a
revision the catalog had already removed. A rerun of an ended delivering
pipeline now reads its revision fresh through the catalog seat's verb
revision first and is refused by name, nothing asked, when it is gone
("its revision <r> is gone; start the mover again at the head"); once
reopened it says its pipeline-started again, so the indexer pins the
revision until its next end.

Builds: design 47 H2 H-A-479, H-A-479 addendum (2)
2026-11-22 16:08:57 +01:00
jschoubben 33feb148ce H-A-479 (1) runner: start with modules starts a failed mover again at the head
A module whose pipeline failed at an unchanged entry was never carried again
until its fingerprint moved, since start refused the head whose pipeline
existed. The start verb now takes modules: the named modules whose newest
entry has no passed pipeline are started at the head's revision, at the
take-in's tiers, keyed <branch>.<revision>.again.<n> (n from 1, written on
absence); a module whose newest entry passed, or that the head holds no
entry of, is refused by name, nothing started. Exactly one of module or
modules is given. The new key form is read by every key-form list (the
sweep's, a release's, the mover keys'). The runner seat's form is 8; the
contract is regenerated.

Builds: design 47 H2 H-A-479, H-A-479 addendum (1)
2026-11-22 16:05:27 +01:00
jschoubben f44442097c mesh-delivery-pipeline: widens-read-bound defaults to 30 s
A cold grants-for (one composing a revision's grants the grants part did
not keep yet) took 3 to 4 s against the 5 s bound and was cut three times
on 2026-11-22; the bound becomes 30 s in the manifest and the code.

Builds: design 47 H2 H-A-478
2026-11-22 16:01:46 +01:00
jschoubben 1f765ef17b mesh-grants: grants-for composes each revision's grants once
grants-for composed every module twice per ask (3 to 4 s against the
runner's 5 s bound, cut three times on 2026-11-22). The tools program
that serves it now keeps each kept revision's composed grants beside the
revision (the newest's and the candidate's), bounded by
grants-for-revisions-per-branch, so a second ask for a kept revision
composes nothing; it reads its inputs at each ask and journals each
stage's time on its standard error.

Builds: design 47 H2 H-A-478, H-A-478 addendum
2026-11-22 16:01:39 +01:00
jschoubben 203454b1a9 Assigner test: read the keeping's need only once the keeping took it
TestAPassWritesWantsWhileAKeepingIsBlocked read the graph's need right after
two passes, while the keeping takes it on its own goroutine; on a loaded build
node it read too early (pipeline main.251). The blocked object bucket now says
when a keeping meets its gate, and the test waits on that, bounded by the
level bound, as it does on the pass and the wake.

Builds: design 47 H2 H-A-476
2026-11-22 14:59:47 +01:00
mesh-tools b691428ffc Merge pull request 'Builder: the publish dispatch sends live first at one processor; judge test row; done-key test bound (H-A-465, H-A-469, H-A-473)' (#329) from fix/main-tests into main 2026-11-22 13:44:24 +00:00
mesh-tools a41a7c2862 Merge pull request 'Orphaned durables: removable by the bus module, left out of the behind check, not composed again (H-A-472)' (#328) from fix/orphan-durables into main 2026-11-22 13:42:31 +00:00
mesh-tools 314a996ed9 Merge pull request 'The delivery view shows pipelines live (issue 1983, H-A-467)' (#327) from feat/pipelines-view into main 2026-11-22 13:41:03 +00:00
jschoubben 7e103f3221 Builder: with again items held, fetch live once more before the gap read
A live item put after the turn's live fetch and before the again items were held
was not yet delivered at the gap read, so no gap showed and the later again item
went first (review round 3 on c37a7317, publishitem.go:792-809). With again items
held the dispatch now fetches live without waiting once more: what it returns runs
and the again items stay held; only an empty fetch leads to the gap read. The test's
idle-dispatch case is a subtest of its own, so it runs alone.

Builds: design 47 H2 §793, H-A-473 (third addendum)
2026-11-22 14:40:17 +01:00
jschoubben c37a7317b7 Builder: every again fetch and gap read follows a live fetch
On the turn after an again item ran, the dispatch fetched again and read the live gap
without fetching live first, so a live item the stream held but had not yet given to
the waiting live pull showed no gap and a later again item went first (review round 2
on b77b70a6, publishitem.go:791). The live consumer is now fetched without waiting on
every turn no live item is held. The test row adds that case and bounds its rounds by
the level's set-up share.

Builds: design 47 H2 §793, H-A-473 (third addendum)
2026-11-22 14:35:41 +01:00
jschoubben b2c9e60ac3 Grants: the bound of a current twin is the setting twin-current-hours
Review round 1: the day after which a twin is no longer current was a
constant here and again in the bus module. It is now the setting
twin-current-hours of the manifest (24 by default), written into a file
the part reads at its start, the field name the bus module's manifest
names too, so the operator sets it once per module alike; the
durable-orphaned condition names the bound. hasOwnProcess no longer sits
under ownServesOf's doc comment.

Builds: design 47 H2 H-A-472 (2) and its third addendum (2); review round 1 findings (2), (3)
2026-11-22 14:34:06 +01:00
jschoubben b77b70a66c Builder: an again item waits for a live one in flight to the idle dispatch's waiting pull
The idle dispatch keeps a waiting pull on each consumer, the bus's only wake for an
item put or delivered again. A live item the waiting pull was given but the dispatch
had not yet received let an again item go first (review finding on 1f33a4c0,
publishitem.go:700, 761, 797). An again item taken while the live pull waits now runs
only once the live consumer's delivered sequence is no further than the live items
received; a gap holds it until the live item arrives and runs.

Builds: design 47 H2 §793, H-A-473 (third addendum)
2026-11-22 14:30:22 +01:00
jschoubben 7f5f175b05 Builder whole test: done builds under the level's set-up bound; the hang at its own
The test ran the builder at a 1 s step bound throughout, so a loaded build
node could fail a build that must end done. Those builds now run under
testbus.SetupBound; the hung step's part starts the builder again at 1 s,
and the build again after it under the set-up bound.

Builds: design 47 H2 §793; H-A-473 (addendum)
2026-11-22 14:16:37 +01:00
jschoubben 1f33a4c04f Builder: the publish dispatch pulls the live consumer itself, then the again
The dispatch read the live consumer's pending count against items the
pull's callback had not yet handed it, so at one processor an again item
was sent before a live one already delivered. It now fetches the live
consumer without waiting and pulls the again consumer only when that
returns nothing; an item is received when its fetch returns it.

Builds: design 47 H2 §793; H-A-473
2026-11-22 14:14:15 +01:00
jschoubben 49c656a4ce Grants: compose a module's program consumer only where it names a program
The pass made <node>_<module> beside <node>_<module>_tools for every
consuming module, so a module whose events only the tool runner reads
got a durable nobody pulls, which piled up and came back after each
removal. The program's consumer is now composed only for a module with
an account of its own and a process resource with no bus of its own;
the tool runner's twin stays for every consuming module.

Builds: design 47 H2 H-A-472 addendum and second addendum, G A-397
2026-11-22 14:12:45 +01:00
jschoubben 9005a2ee8e Grants: the behind check leaves out an orphaned durable and names it apart
About 110 durables left by modules that moved into or out of the tool
runner pile up behind their stream's head and raised 'Messages pile up
for a listener' for no real backlog. A durable with no pulls waiting
whose twin on the stream (<node>_<module> and <node>_<module>_tools) has
pulls waiting and delivered within the day is now left out of that check
and named once in mesh-grants.durable-orphaned, cleared when gone.

Builds: design 47 H2 H-A-472 (2), G A-340
2026-11-22 14:03:55 +01:00
jschoubben b914974b1d Judge test: the unknown top-level word is one no SDK knows
The row proving that the judgement's strict read refuses an unknown
top-level word used class, which the H2 SDK knows, so it failed at main.
It now uses a word no SDK knows and proves the same refusal.

Builds: design 47 H2 H-A-465, H-A-469
2026-11-22 13:57:22 +01:00
jschoubben d151033dae View: the pipelines heard kept for the pages is the setting pipelines-heard
The view kept the last change of at most 1024 pipelines for its pages, a
cap written into the code. A cap is a setting with a default (principle
11): the manifest gives pipelines-heard, 1024 by default, written into a
file of the state directory the process reads at its start. The cap is
kept, not removed: without it the pipelines heard grow without end over
the view's life.

Issue 1983, review round 1 finding 3.
Builds: design 47 H2 H-A-467 (1)
2026-11-22 11:45:32 +01:00
jschoubben 3c742145d7 View: the pipelines page takes a limit, the newest 20 by default
The design gives list a limit with a default of 20; the view asked 20
always and neither the web page nor the terminal view could ask another.
The web list takes a limit query parameter and the terminal view a -limit
flag; a followed branch's list is read at the default, any other limit is
read at the asking.

Issue 1983, review round 1 finding 2.
Builds: design 47 H2 H-A-467 (1)
2026-11-22 11:42:27 +01:00
jschoubben d557c0c2af View: a pipelines list not read is a page shown unreadable, not a refusal
The socket answered a refusal and a list it could not read with the same
field, so the terminal view's -follow ended at a list not read yet (the
runner not answering at the view's start) instead of showing it unreadable
and reading it again at the runner's next event. A refusal now has its own
field; a list's page is handed on whatever it holds. The unit tests' waits
for a change are bounded, so a change never said fails instead of hanging.

Issue 1983, review round 1 finding 1.
Builds: design 47 H2 H-A-467 (1), (2)
2026-11-22 11:41:25 +01:00
jschoubben c11c90348e H-A-467 view: a pipelines page in the web view and the terminal view
The operator follows the pipelines in the delivery view: the newest
pipelines of a branch (main by default, the newest 20) with their steps
counted per outcome, one pipeline's mover rows and one mover's steps, read
through the seat mesh-pipeline-runner's list and show and read again on the
runner's events pipeline-started, step-ended, pipeline-ended and re-pinned,
heard on the module's one pull; the web pages reload on a stream of those
changes and the terminal view's -follow prints again, never on a timer. Each
delivered source revision links to the newest pipeline of its source. The
view keeps no state of its own for it.

Issue 1983.
Builds: design 47 H2 H-A-467 (1), (2), (3), H-A-376
2026-11-22 11:26:08 +01:00
jschoubben 1b177d5912 H-A-467 runner: list's row carries source, revision and steps per outcome
The delivery view's pipelines page reads the newest pipelines of a branch in
one read of list's short form, so each row now carries the pipeline's source
revision, its catalog graph revision and its steps counted per outcome. The
runner seat's form is 7; the contract is regenerated; the full form stays.

Issue 1983.
Builds: design 47 H2 H-A-467 (addendum), H-A-376
2026-11-22 11:12:34 +01:00
129 changed files with 5533 additions and 1159 deletions
@@ -154,6 +154,13 @@ func (b *builtEnds) madeOf(module, fp string) map[string]string {
return parts
}
// releasedOf is the version released of module's done build at fp, the release whose parts are what its build.ended made (design
// 47 G A-421); false when no such release is heard.
func (w *world) releasedOf(module, fp string) (string, bool) {
k, ok := w.released.withParts(module, w.ends.madeOf(module, fp))
return k.Version, ok && k.Version != ""
}
// of is the version of module released from the source revision, with its parts' digests; false before it is heard.
func (r *releasedVersions) of(module string, source int64) (assign.KeptBuild, bool) {
r.mu.Lock()
@@ -19,6 +19,7 @@ import (
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"
"git.novox.be/novox/mesh-sdk/go/testbus"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
@@ -170,15 +171,21 @@ func TestTheWantsAreSaidWantedFromTheKeptAssignmentGraphRevision(t *testing.T) {
}
// blockedObjects is an object bucket whose listing waits while a gate stands: a keeping that does not end until it is opened.
// A listing that meets the gate closes entered: the keeping took its need and runs it (H-A-476).
type blockedObjects struct {
memObjects
mu sync.Mutex
gate chan struct{}
mu sync.Mutex
gate chan struct{}
entered chan struct{}
}
func (b *blockedObjects) Names(ctx context.Context) ([]string, error) {
b.mu.Lock()
gate := b.gate
gate, entered := b.gate, b.entered
if gate != nil && entered != nil {
close(entered)
b.entered = nil
}
b.mu.Unlock()
if gate != nil {
<-gate
@@ -204,16 +211,33 @@ func (b *blockedObjects) Get(ctx context.Context, name string) ([]byte, error) {
func (b *blockedObjects) block() func() {
gate := make(chan struct{})
b.mu.Lock()
b.gate = gate
b.gate, b.entered = gate, make(chan struct{})
b.mu.Unlock()
return func() {
b.mu.Lock()
b.gate = nil
b.gate, b.entered = nil, nil
b.mu.Unlock()
close(gate)
}
}
// awaitBlocked returns once a keeping meets the standing gate, so what the keeping took is read after it took it, and fails the
// test when none did within bound (H-A-476: a test waits on the signal of the work it reads after, never on an order it assumes).
func (b *blockedObjects) awaitBlocked(t *testing.T, bound time.Duration, what string) {
t.Helper()
b.mu.Lock()
entered := b.entered
b.mu.Unlock()
if entered == nil {
return // met already
}
select {
case <-entered:
case <-time.After(bound):
t.Fatalf("no keeping met the gate within %s: %s", bound, what)
}
}
// 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
@@ -222,6 +246,7 @@ 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())
bound := testbus.SetupBound(t) // every wait on a goroutine's work, never a value in the test (H-A-476)
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() }
@@ -252,7 +277,7 @@ func TestAPassWritesWantsWhileAKeepingIsBlocked(t *testing.T) {
go func() { p.pass(context.Background()); close(done) }()
select {
case <-done:
case <-time.After(10 * time.Second):
case <-time.After(bound):
t.Fatal("the pass waits on the keeping of the assignment graph")
}
}
@@ -281,7 +306,7 @@ func TestAPassWritesWantsWhileAKeepingIsBlocked(t *testing.T) {
open()
select {
case <-woke:
case <-time.After(10 * time.Second):
case <-time.After(bound):
t.Fatal("the first keeping's end wakes no pass")
}
pass()
@@ -292,7 +317,8 @@ func TestAPassWritesWantsWhileAKeepingIsBlocked(t *testing.T) {
open = objects.block() // a keeping of new inputs is blocked
placeOn(t, p.w, "g14", "web")
pass()
pass() // the same inputs again
pass() // the same inputs again
objects.awaitBlocked(t, bound, "the keeping of new inputs never took its need") // H-A-476: read the need once it was taken
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)
}
@@ -656,6 +656,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
// once the first registrations are written (§95, §353).
p.ends = newPipelineEnds(kvEnds{ctx, kv}, wake, logger.Printf)
p.ends.trunk = w.trunkName
p.ends.releasedOf = w.releasedOf // a version released before its pipeline passed is taken at the pass (H-A-490)
p.ends.runEnded = func(group string) error { return p.dropCandidate(ctx, group) }
if err := hearEnds(hub, p.ends); err != nil {
logger.Printf("a pipeline's end is not heard, so the wants keep the trunk-only form until the assigner starts again: %v", err)
@@ -409,7 +409,12 @@ func putOfTheBus(t *testing.T) {
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fp, Manifest: mdigest, Repository: "novox/mesh-catalog", Commit: strings.Repeat("c", 40)})
putModuleRaw(p.w, trunkBranch, "nats", mod)
p.w.manifests[mdigest] = parsed{module: "nats", manifest: catalogue.Manifest{Module: "nats", Provides: []catalogue.Offer{{Name: "mesh-bus"}}}}
endDone(t, p.w, "nats", fp, mdigest)
// The build and its release (H-A-490 addendum): the put's want names the version released at its parts.
built, _ := json.Marshal(builds.BuildEnded{Module: "nats", Fingerprint: fp, Outcome: builds.BuildDone, Manifest: mdigest, Made: map[string]string{"program": "sha256:5"}})
rel, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: "nats", Source: 8, Version: "2.10.1", Artifacts: []meshcatalog.VersionArtifact{{Artifact: "nats:program", Digest: "sha256:5"}}})
if p.w.ends.put(built) != nil || p.w.released.put(rel) != nil {
t.Fatal("the build or its release is not heard")
}
hkey, _ := nodeengineclient.HaveKey("novox", "nats")
before, _ := nodeengineclient.EncodeHave(nodeengine.HaveByNodeModuleValue{Fp: meshcatalogclient.SourcePrefix2 + strings.Repeat("a", 64), Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK})
world(buckets.Have, hkey, before)
@@ -489,7 +494,7 @@ func putOfTheBus(t *testing.T) {
<-woke
got = step()
w, err := mwc.DecodeWant(wantsKV.values["want.novox.nats"])
if got.Step != puts.Wanted || err != nil || w.Fp != fp || !w.Put || !w.Hold {
if got.Step != puts.Wanted || err != nil || w.Fp != fp || w.Version != "2.10.1" || !w.Put || !w.Hold {
t.Fatalf("snapshotted, the put stands at %s (%s); the want %+v, %v", got.Step, got.Words, w, err)
}
if call := <-bus.calls; !strings.HasPrefix(call, "seat:mesh-hand-acts.warranted ") || !strings.Contains(call, a.Ask.ID) { // ADR 0565 §11: into the seat
@@ -17,6 +17,7 @@ import (
mprc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshpipelinerunnerclient"
mpcat "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-sdk/pipelinekey"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
@@ -152,6 +153,10 @@ type pipelineEnds struct {
trunk func() string
// now is the clock of the tier progress (tiers.go); nil is time.Now.
now func() time.Time
// releasedOf is the version released of module's build at fp, matched by the parts its build.ended made (world.releasedOf):
// a mover whose version was released before its pipeline passed gets its want at the pass (design 47 H2 H-A-490). nil
// matches none.
releasedOf func(module, fp string) (string, bool)
}
func newPipelineEnds(st endStore, wake func(), logf func(string, ...any)) *pipelineEnds {
@@ -161,11 +166,18 @@ func newPipelineEnds(st endStore, wake func(), logf func(string, ...any)) *pipel
// take keeps, for each mover of a passed pipeline that released a version, that version as the newest of its module on the
// pipeline's branch, by compare-and-set on a newer version (design 47 H §750): an older version, or the same one again, writes
// nothing. A passed mover with no version yet is said in the journal and taken when the runner says the end again naming it
// (H-A-270); it holds its tier in the pipeline's tier progress meanwhile (H-A-277 (1)). It says whether any key changed.
// (H-A-270); it holds its tier in the pipeline's tier progress meanwhile (H-A-277 (1)). A mover whose build's version was
// released before the pass is taken at the pass with that version (H-A-490). It says whether any key changed.
func (e *pipelineEnds) take(p mpr.PipelineEnded) (bool, error) {
if p.Outcome != mpr.PipelineEndedOutcomePassed || p.Run != "" {
return false, nil
}
// The pipeline's key is read by the one parse of the runner's seat's key forms (design 47 H2 H-A-485): a key it does not
// know is refused loudly, and nothing of the pipeline is kept, never an empty tier progress.
if _, err := pipelinekey.Parse(p.Pipeline); err != nil {
e.logf("the pipeline-ended of %s is refused, and none of its movers' versions is kept: %v", p.Pipeline, err)
return false, nil
}
changed := false
var kept []tierMover
versioned := map[string]bool{}
@@ -178,6 +190,14 @@ func (e *pipelineEnds) take(p mpr.PipelineEnded) (bool, error) {
if m.Fingerprint == "" || !moverPassed(m) {
continue
}
if m.Version == "" && e.releasedOf != nil {
// A version released before its pipeline passed (an again pipeline on a built, published key) is never written
// on the mover, nor its end said again: it is judged at the pass, matched by its build's parts (H-A-490).
if v, ok := e.releasedOf(m.Module, m.Fingerprint); ok {
e.logf("%s: %s passed; its version %s was released before the pass, taken now", p.Pipeline, m.Module, v)
m.Version = v
}
}
if m.Version == "" {
// The runner writes a mover's version at its release's version-released, and says this end again once it does
// (H-A-270 (1), (2)): the skip is said, never silent.
@@ -12,6 +12,7 @@ import (
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"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"
@@ -96,6 +97,17 @@ func TestThePassedVersionIsKept(t *testing.T) {
ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, ok))}, &End{Pipeline: "main.6", Source: 6, Fp: "fp2", Version: "0.1.3", Rank: 1}},
{"a newer version replaces", []mpr.PipelineEnded{ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, ok)),
ended("main", 6, pass, mover("web", "fp2", "0.1.10", 1, ok))}, &End{Pipeline: "main.6", Source: 6, Fp: "fp2", Version: "0.1.10", Rank: 1}},
// H-A-485: an again pipeline's end is kept as a take-in's; a key of no form the runner's seat defines is refused, nothing kept.
{"an again pipeline keeps its version", []mpr.PipelineEnded{func() mpr.PipelineEnded {
p := ended("main", 5, pass, mover("web", "fp1", "0.1.2", 2, ok))
p.Pipeline = "main.5.again.2"
return p
}()}, &End{Pipeline: "main.5.again.2", Source: 5, Fp: "fp1", Version: "0.1.2", Rank: 2}},
{"a key of no form is refused", []mpr.PipelineEnded{func() mpr.PipelineEnded {
p := ended("main", 5, pass, mover("web", "fp1", "0.1.2", 2, ok))
p.Pipeline = "main.5.later.2"
return p
}()}, nil},
{"a run on request keeps nothing", []mpr.PipelineEnded{func() mpr.PipelineEnded {
p := ended("main", 5, pass, mover("web", "fp1", "0.1.2", 1, ok))
p.Run = "r1"
@@ -109,6 +121,9 @@ func TestThePassedVersionIsKept(t *testing.T) {
}
}
got, kept := e.endOf("web", "main")
if ks, _ := e.st.keys(); c.name == "a key of no form is refused" && len(ks) != 0 {
t.Errorf("%s: the state written holds %v, want nothing (no empty tier progress)", c.name, ks)
}
switch {
case c.want == nil && kept:
t.Errorf("%s: kept %+v", c.name, got)
@@ -142,10 +157,15 @@ func TestThePassedVersionIsKept(t *testing.T) {
// A6/AC1, A5/AC1 (design 47 H §750): a pass writes, on every node the module is assigned to, the want naming the newest version
// released on its branch whose pipeline passed, with the pipeline and the rank; with none passed it writes none. No grant,
// canary, provider or composition is asked for. H-A-270 (1): a passed end whose mover names no version yet writes no want and
// says so in the journal; the same end said again naming the version writes it.
// says so in the journal; the same end said again naming the version writes it. H-A-490: a version released before its pipeline
// passed (an again pipeline on a built, published key) gets its want at the pass, matched to the mover's build by its parts.
func TestAPassWritesTheWantOfThePassedVersion(t *testing.T) {
fp := meshcatalogclient.SourcePrefix2 + strings.Repeat("a", 64)
for _, passed := range []bool{false, true} {
for _, c := range []struct {
name string
passed, releasedBefore bool
}{{"no pipeline passed", false, false}, {"passed, then its version released", true, false}, {"released, then its pipeline passed", true, true}} {
passed := c.passed
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, time.Now())
p.say = func(oc.Condition) error { return nil }
@@ -158,7 +178,16 @@ func TestAPassWritesTheWantOfThePassedVersion(t *testing.T) {
var journal []string
p.ends = newPipelineEnds(newMemEnds(), func() {}, func(f string, a ...any) { journal = append(journal, fmt.Sprintf(f, a...)) })
p.ends.trunk = p.w.trunkName
if passed {
p.ends.releasedOf = p.w.releasedOf
if c.releasedBefore {
// Built and released in an earlier pipeline that failed: the runner's again pipeline ends naming no version.
rel, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: "web", Source: 4, Version: "0.1.2", Artifacts: []meshcatalog.VersionArtifact{{Artifact: "web:image", Digest: "sha256:7"}}})
built, _ := json.Marshal(builds.BuildEnded{Module: "web", Fingerprint: fp, Outcome: builds.BuildDone, Made: map[string]string{"image": "sha256:7"}})
if err := p.w.released.put(rel); err != nil || p.w.ends.put(built) != nil {
t.Fatal(err)
}
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "", 2, mpr.StepResultOutcomePassed)))
} else if passed {
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "", 2, mpr.StepResultOutcomePassed)))
p.wants(context.Background())
if len(wantsKV.values) != 0 || !slices.Contains(journal, trunkBranch+".5: web passed with no version yet: taken again when its version is written") {
@@ -171,14 +200,14 @@ func TestAPassWritesTheWantOfThePassedVersion(t *testing.T) {
key, _ := mwc.WantKey(node, "web")
raw, got := wantsKV.values[key]
if got != passed {
t.Errorf("passed %v: a want on %s written = %v", passed, node, got)
t.Errorf("%s: a want on %s written = %v", c.name, node, got)
continue
}
if !passed {
continue
}
if w, err := mwc.DecodeWant(raw); err != nil || w.Fp != fp || w.Version != "0.1.2" || w.Pipeline != trunkBranch+".5" || w.Rank != 2 {
t.Errorf("the want on %s = %+v (%v)", node, w, err)
t.Errorf("%s: the want on %s = %+v (%v)", c.name, node, w, err)
}
}
}
@@ -181,6 +181,7 @@ func (p *passer) putWorld(node, module string, put puts.Put, manifest catalogue.
if e, ok := p.w.ends.endOf(module, put.FP); ok { // the build's end heard (A-181): none heard, no state
w.Build, w.BuildWords = e.Outcome, e.Error
}
w.Version, _ = p.w.releasedOf(module, put.FP) // matched by its build's parts, as the pass matches a mover's (H-A-490 addendum)
w.Composed, w.Granted = p.composedFor(node, module, put.FP)
if d := w.Composed; d != nil {
policy := d.Policy
@@ -6,12 +6,14 @@ import (
"fmt"
"slices"
"sort"
"strconv"
"strings"
"time"
mcc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/pipelinekey"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
@@ -58,10 +60,16 @@ type tierProgress struct {
// tierKey is the key of pipeline's tier progress; pipeline is the runner's key `<branch>.<source>`, its branch escaped.
func tierKey(pipeline string) string { return tierPrefix + pipeline }
// isTierKey says whether a key of the state written is a pipeline's tier progress: three parts, the first `pipeline` (a module's
// end has two).
// isTierKey says whether a key of the state written is a pipeline's tier progress: `pipeline.` and a pipeline's key of any form
// the runner's seat defines, read by the one parse (design 47 H2 H-A-485), so an again pipeline's progress is one as a take-in's
// is (a module's end, `<module>.<branch>`, is none).
func isTierKey(key string) bool {
return strings.HasPrefix(key, tierPrefix) && strings.Count(key, ".") == 2
rest, ok := strings.CutPrefix(key, tierPrefix)
if !ok {
return false
}
_, err := pipelinekey.Parse(rest)
return err == nil
}
// startTiers writes the tier progress of a passed pipeline, holding every passed mover, versioned or not, its first tier the
@@ -166,11 +174,11 @@ func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []st
continue
}
pipeline := strings.TrimPrefix(key, tierPrefix)
branchEsc, number, _ := strings.Cut(pipeline, ".")
branch, err := keys.UnescapeName(branchEsc)
pk, err := pipelinekey.Parse(pipeline)
if err != nil {
continue
}
branch, number := pk.Branch, strconv.FormatInt(pk.Revision, 10)
for {
t, rev, ok := p.ends.tiersOf(pipeline)
if !ok {
@@ -28,7 +28,12 @@ import (
// tier-bound: the finding tier-late names it and its machine, pipeline-wanted says tier-late, and no consumer want is written.
func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
db, web := meshcatalogclient.SourcePrefix2+strings.Repeat("d", 64), meshcatalogclient.SourcePrefix2+strings.Repeat("c", 64)
for _, runs := range []bool{true, false} {
// H-A-485: a pipeline started again at the head, keyed `<branch>.<revision>.again.<n>`, moves tier by tier as a take-in's does.
for _, c := range []struct {
runs bool
pipeline string
}{{true, trunkBranch + ".5"}, {false, trunkBranch + ".5"}, {true, trunkBranch + ".5.again.2"}, {false, trunkBranch + ".5.again.2"}} {
runs, pipeline := c.runs, c.pipeline
start := time.Date(2026, 11, 20, 4, 0, 0, 0, time.UTC)
now := start
wantsKV := &memKV{values: map[string][]byte{}}
@@ -41,7 +46,7 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
var said []meshwants.PipelineWanted
p.publishWants = func(event string, body any, _ string) error {
if b, ok := body.(meshwants.PipelineWantedEvent); ok {
if event != "pipeline-wanted."+trunkBranch+".5" {
if event != "pipeline-wanted."+pipeline {
t.Errorf("pipeline-wanted said as %s", event)
}
said = append(said, b)
@@ -65,7 +70,7 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
// 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
e.Source, e.Pipeline = 4, pipeline
if _, err := p.ends.take(e); err != nil {
t.Fatal(err)
}
@@ -76,7 +81,7 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
}
p.wants(context.Background())
if !wanted("g14", "db") || !wanted("ace", "db") || wanted("g14", "web") || wanted("ace", "web") {
t.Fatalf("runs %v: tier 1 alone is not what is wanted first: %v", runs, wantsKV.values)
t.Fatalf("%s runs %v: tier 1 alone is not what is wanted first: %v", pipeline, runs, wantsKV.values)
}
if runs {
raw, _ := json.Marshal(nodeengine.Running{Node: "g14", Module: "db", Fingerprint: db})
@@ -86,15 +91,15 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
now = start.Add(time.Minute)
p.wants(context.Background())
if !wanted("g14", "web") || !wanted("ace", "web") {
t.Fatalf("the consumer's want is not written once its provider runs: %v", wantsKV.values)
t.Fatalf("%s: the consumer's want is not written once its provider runs: %v", pipeline, wantsKV.values)
}
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 || said[0].Revision != 5 || said[0].Source != 4 || len(findings) != 0 {
t.Errorf("every tier runs: said %+v, findings %v", said, findings)
t.Errorf("%s: every tier runs: said %+v, findings %v", pipeline, said, findings)
}
if _, _, ok := p.ends.tiersOf(trunkBranch + ".5"); ok {
if _, _, ok := p.ends.tiersOf(pipeline); ok {
t.Error("the tier progress stands after every tier ran")
}
continue
@@ -107,7 +112,7 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
now = start.Add(30 * time.Minute)
p.wants(context.Background())
p.wants(context.Background())
f, ok := findings["delivery."+assign.KeyID(trunkBranch+".5")+".tier-late"]
f, ok := findings["delivery."+assign.KeyID(pipeline)+".tier-late"]
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)
}
@@ -116,7 +121,7 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
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)
p.sayPipelineWanted(pipeline, 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)
}
@@ -34,6 +34,9 @@ type PutWorld struct {
Build, BuildWords string
// Newest is the module's newest fingerprint at the trunk, which the builder builds by itself.
Newest string
// Version is the version released at the put's fingerprint, matched by its build's parts as the pass matches a mover's;
// "" when none is released (design 47 H2 H-A-490 addendum).
Version string
// Composed is the composition of the module for the node at the fingerprint, as its writer holds it; nil when there is
// none. Granted says the grant at the fingerprint names the node's accounts. Both are read, never asked for (clause 4).
Composed *ComposedDigest
@@ -87,7 +90,10 @@ func StepPut(w PutWorld) PutNext {
if h := w.Have; h == nil || h.Fp != p.FP || h.Composed == "" {
return say(puts.Refused, "%s runs %s at %s, and its have names no composition at that fingerprint, so the want cannot name what runs", w.Node, w.Module, fp)
}
p.Composed = w.Have.Composed
if w.Version == "" {
return say(puts.Refused, "no version released at %s: build or release it first", fp)
}
p.Composed, p.Version = w.Have.Composed, w.Version
words := fmt.Sprintf("the want of %s on %s names %s, the build it runs now (composition %s), from its running statement; the builder's store is not asked",
w.Module, w.Node, fp, short(p.Composed))
if p.Hold {
@@ -115,6 +121,14 @@ func StepPut(w PutWorld) PutNext {
default:
return say(puts.Build, "waits for the builder's build of %s at %s, which is %s", w.Module, fp, w.Build)
}
if p.Step != puts.Wanted && p.Step != puts.Holding {
// The want names the build's released version beside its fingerprint, which the node-engine composes from (H-A-490
// addendum): a build with none released is refused, never wanted by its fingerprint alone.
if w.Version == "" {
return say(puts.Refused, "no version released at %s: build or release it first", fp)
}
p.Version = w.Version
}
if w.Composed == nil || !w.Granted {
missing := fmt.Sprintf("no composition of %s for %s at %s is written", w.Module, w.Node, fp)
if w.Composed != nil {
@@ -212,9 +226,10 @@ func needsPerson(w PutWorld, d ComposedDigest) bool {
return d.Judgement == JudgedRecreates || d.Judgement == JudgedMovesData || d.Judgement == JudgedCannot
}
// PutWant is the want a put writes once it is wanted: the fingerprint, marked put, and held when it holds.
// PutWant is the want a put writes once it is wanted: the fingerprint and the version released at it, marked put, and held when
// it holds.
func PutWant(p puts.Put) mwc.Want {
return mwc.Want{Fp: p.FP, Put: true, Hold: p.Hold, Words: "put: " + p.Why}
return mwc.Want{Fp: p.FP, Version: p.Version, Put: true, Hold: p.Hold, Words: "put: " + p.Why}
}
// PutOwns says what a put does to the node's want: owns says the rules pass over it, want the want it writes (nil: what
@@ -105,7 +105,7 @@ func Wants(m Module, wants map[string]mwc.Want) Outcome {
if !put && had && before.Put && before.Hold {
// The want is the truth (ADR 0546 clause 5): a want marked put and held stands while its put is not heard; only a put
// heard released gives it back to the rule.
p, put = puts.Put{FP: before.Fp, Hold: true, Why: strings.TrimPrefix(before.Words, "put: "), Step: puts.Holding}, true
p, put = puts.Put{FP: before.Fp, Version: before.Version, Hold: true, Why: strings.TrimPrefix(before.Words, "put: "), Step: puts.Holding}, true
}
if put {
if want, owns := PutOwns(p); owns {
@@ -92,7 +92,7 @@ func TestAWantNamesTheNewestPassedVersion(t *testing.T) {
// want stands, marked put and held, and once released the rule writes the passed version again.
func TestAPutOwnsItsNodesWant(t *testing.T) {
m := released()
put := puts.Put{FP: fNew, Hold: true, Why: "the bus's user list", Composed: dig(fNew)}
put := puts.Put{FP: fNew, Version: "1.2.3", Hold: true, Why: "the bus's user list", Composed: dig(fNew)}
for _, c := range []struct {
name string
step string
@@ -100,7 +100,7 @@ func TestAPutOwnsItsNodesWant(t *testing.T) {
want *mwc.Want // nil: nothing written on ace
}{
{"waiting for the operator", puts.Person, wantedOld(), nil},
{"wanted", puts.Wanted, wantedOld(), &mwc.Want{Fp: fNew, Put: true, Hold: true, Words: "put: the bus's user list"}},
{"wanted", puts.Wanted, wantedOld(), &mwc.Want{Fp: fNew, Version: "1.2.3", Put: true, Hold: true, Words: "put: the bus's user list"}},
{"holding, written already", puts.Holding, map[string]mwc.Want{"ace": PutWant(put)}, nil},
{"released: the rule again", puts.Released, map[string]mwc.Want{"ace": PutWant(put)}, &mwc.Want{Fp: fNew, Version: "1.2.3", Pipeline: "main.12", Rank: 2}},
{"not heard: a held want at an older fingerprint stands", "", map[string]mwc.Want{"ace": {Fp: fOld, Put: true, Hold: true, Words: "put: back"}}, nil},
@@ -144,7 +144,7 @@ func stepsOfAPut(t *testing.T) {
running := nodeengine.HaveByNodeModuleValue{Fp: fOld, Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK}
bus := func() PutWorld {
return PutWorld{Node: "novox", Module: "nats", Put: base, Assigned: true, Bus: true, Build: builds.BuildDone, Newest: fNew,
Composed: &d, Granted: true, Have: &running, Now: now}
Version: "1.2.3", Composed: &d, Granted: true, Have: &running, Now: now}
}
cases := []struct {
name string
@@ -172,6 +172,16 @@ func stepsOfAPut(t *testing.T) {
w.Running = &nodeengine.Running{Node: "novox", Module: "nats", Fingerprint: fNew}
return w
}, puts.Refused, "names no composition", false, false, false},
// H-A-490 (addendum): a want names the build's released version, so a done build with none released is refused, and so
// is the build the node runs now when no release names its parts.
{"a done build with no released version: refused", func() PutWorld { w := bus(); w.Version = ""; return w }, puts.Refused, "no version released at", false, false, false},
{"the build the node runs now, no version released: refused", func() PutWorld {
w := bus()
w.Build, w.Newest, w.Version = "", fpOf('c'), ""
w.Running = &nodeengine.Running{Node: "novox", Module: "nats", Fingerprint: fNew}
w.Have = &nodeengine.HaveByNodeModuleValue{Fp: fNew, Composed: dig(fNew), Phase: nodeengineclient.PhaseRunning, Health: nodeengineclient.HealthOK}
return w
}, puts.Refused, "build or release it first", false, false, false},
{"a failed build", func() PutWorld { w := bus(); w.Build, w.BuildWords = builds.BuildFailed, "go vet"; return w }, puts.Refused, "go vet", false, false, false},
{"no composition yet: waits", func() PutWorld { w := bus(); w.Composed = nil; return w }, puts.Compose, "no composition of nats for novox", false, false, false},
{"composed, grant not naming the node", func() PutWorld { w := bus(); w.Granted = false; return w }, puts.Compose, "does not name novox", false, false, false},
@@ -256,6 +266,9 @@ func stepsOfAPut(t *testing.T) {
}
for _, c := range cases {
next := StepPut(c.world())
if (next.Put.Step == puts.Wanted || next.Put.Step == puts.Holding) && c.world().Put.Step == puts.Asked && next.Put.Version != "1.2.3" {
t.Errorf("put, %s: its want names version %q, want the build's released 1.2.3", c.name, next.Put.Version)
}
if next.Put.Step != c.step || !strings.Contains(next.Put.Words, c.says) {
t.Errorf("put, %s: at %s, %q; want %s saying %q", c.name, next.Put.Step, next.Put.Words, c.step, c.says)
}
@@ -65,6 +65,9 @@ type Put struct {
V int `json:"v"`
// FP is the fingerprint put, of the new form.
FP string `json:"fp"`
// Version is the version released at FP, which the want names beside it, once the put found it (design 47 H2 H-A-490
// addendum).
Version string `json:"version,omitempty"`
// Hold keeps the want at FP until released.
Hold bool `json:"hold,omitempty"`
Why string `json:"why"`
@@ -5,9 +5,12 @@ import (
"errors"
"strings"
"testing"
"time"
"mesh-delivery-builder/internal/build"
stdio "git.novox.be/novox/mesh-sdk/go"
"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"
)
@@ -54,3 +57,14 @@ func TestABuildSeatsStepsAreReadInItsHoldersState(t *testing.T) {
t.Errorf("a seat with no holder reads %v; want an error naming it", err)
}
}
// H-A-487: a build key's time is its entry's own write time, read with the key and no history.
func TestABuildKeysTimeIsItsEntrysOwnWriteTime(t *testing.T) {
at := time.Date(2026, 11, 22, 20, 45, 0, 0, time.UTC)
raw, rev, got, err := entryOf(func(key string) (*stdio.StateEntry, error) {
return &stdio.StateEntry{Key: key, Value: json.RawMessage(`{}`), Revision: 4, At: at}, nil
})("k")
if err != nil || string(raw) != "{}" || rev != 4 || !got.Equal(at) {
t.Errorf("entry = %s rev %d at %v (%v); want the entry's own write time %v", raw, rev, got, err, at)
}
}
@@ -430,7 +430,7 @@ func main() {
return a, json.Unmarshal(raw, &a)
}
tools := Tools(r, put, askQueue(stdio.State(build.QueuesState), 25*time.Second), buildAgain, stdio.Log(builds.BuilderLog).Since, time.Now, vr, fr, ofr, reserve)
tools = append(tools, buildTool(&build.BuildReader{Builds: read(stdio.State("builds")), Entry: entryOf(stdio.State("builds")), Asked: read(stdio.State("asked")),
tools = append(tools, buildTool(&build.BuildReader{Builds: read(stdio.State("builds")), Entry: entryOf(stdio.State("builds").Get), Asked: read(stdio.State("asked")),
Newest: newestVia(stdio.Ask), Steps: r}))
tools = append(tools, reservedTools(rr, buildAgain, time.Now, meshhandactsclient.Recorder{Ask: stdio.Ask})...)
as := stdio.State(versions.ActedState)
@@ -481,13 +481,14 @@ func main() {
}
}
// entryOf reads a key with its revision and when it was written.
func entryOf(s stdio.KeptState) func(key string) (json.RawMessage, uint64, time.Time, error) {
// entryOf reads a key with its revision and when it was written, the entry's own write time: no key's history is read
// (design 47 H2 H-A-487).
func entryOf(get func(key string) (*stdio.StateEntry, error)) func(key string) (json.RawMessage, uint64, time.Time, error) {
return func(key string) (json.RawMessage, uint64, time.Time, error) {
e, err := s.Get(key)
e, err := get(key)
if err != nil || e == nil {
return nil, 0, time.Time{}, err
}
return e.Value, e.Revision, written(s, key, e.Revision), nil
return e.Value, e.Revision, e.At, nil
}
}
@@ -73,7 +73,7 @@ func publishQueueVia(ask func(key string, body any) (json.RawMessage, error)) fu
}
}
// publishActTools are builder_publish_drop and builder_publish_first (design 47 H2 §793): hand acts, recorded in the hand-act log
// publishActTools are builder_publish_drop (design 47 H2 §793; builder_publish_first is retired, H-A-483 third addendum): hand acts, recorded in the hand-act log
// first, then written to reasks for the builder, which owns the work queue, to perform and answer.
func publishActTools(ask queueAsker, now func() time.Time, acts meshhandactsclient.Recorder) []stdio.Tool {
str := func(args map[string]any, k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) }
@@ -108,7 +108,6 @@ func publishActTools(ask queueAsker, now func() time.Time, acts meshhandactsclie
}
return []stdio.Tool{
tool(versions.PublishDropTool, build.ModePublishDrop, versions.PublishDropDescription, "dropped the publish of"),
tool(versions.PublishFirstTool, build.ModePublishFirst, versions.PublishFirstDescription, "put first the publish of"),
}
}
@@ -78,8 +78,8 @@ func TestAStateIsReadInOnePage(t *testing.T) {
}
})
// Design 47 H2 §793, H-A-454: builder_publish_queue asks the seat mesh-builds' verb publish-queue, which the builder serves from
// its own stream, and answers its counts, list and cap with the states beside them; builder_publish_drop and
// builder_publish_first record the hand act first, then write their reasks value.
// its own stream, and answers its counts, list and cap with the states beside them; builder_publish_drop records the hand act
// first, then writes its reasks value; builder_publish_first is retired (H-A-483, third addendum).
t.Run("the queue is the builder's verb publish-queue", func(t *testing.T) {
var asked []string
ask := func(key string, body any) (json.RawMessage, error) {
@@ -123,7 +123,7 @@ func TestAStateIsReadInOnePage(t *testing.T) {
t.Errorf("asked %v, answered %+v (%v): want each holder asked in turn at its node, answered together, the silent one with why", asked, hs, err)
}
})
t.Run("drop and first record the hand act, then ask the builder", func(t *testing.T) {
t.Run("drop records the hand act, then asks the builder; first is retired", func(t *testing.T) {
var order []string
ask := func(key string, value []byte) (json.RawMessage, error) {
order = append(order, "ask "+key)
@@ -141,8 +141,8 @@ func TestAStateIsReadInOnePage(t *testing.T) {
t.Fatalf("%s: %v", tool.Name, err)
}
}
if len(tools) != 2 || fmt.Sprint(order) != "[record ask publish-drop.5000000000 record ask publish-first.5000000000]" {
t.Errorf("tools %d, order %v: want each hand act recorded before its reasks value", len(tools), order)
if len(tools) != 1 || tools[0].Name != versions.PublishDropTool || fmt.Sprint(order) != "[record ask publish-drop.5000000000]" {
t.Errorf("tools %d, order %v: want builder_publish_drop alone, its hand act recorded before its reasks value", len(tools), order)
}
if _, err := tools[0].Run(map[string]any{"module": "m", "why": "no version"}); err == nil {
t.Error("a drop naming no version is not refused")
@@ -40,6 +40,7 @@ import (
"git.novox.be/novox/mesh-sdk/go/buscompose"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatdef"
"git.novox.be/novox/mesh-sdk/go/testbus"
"git.novox.be/novox/mesh-sdk/go/views/viewstest"
"mesh-delivery-builder/internal/build"
@@ -578,7 +579,10 @@ func TestBuilderMakesADoneKeyWithTheDigests(t *testing.T) { // 1607/AC7
first := "src2:" + strings.Repeat("1", 64)
b.moduleFP(t, "netcheck", netcheck, "modules/netcheck", bothToolchains, commit, first, 1)
digest := b.moduleFP(t, "netcheck", netcheck, "modules/netcheck", bothToolchains, commit, fp, 2)
b.start(t, "n1", map[string]string{"MESH_BUILDER_STEP_BOUND": "1s"})
// H-A-473 (addendum): the builds that must end done run under the level bound's set-up share, never a bound a loaded
// node cannot meet; the hung step's part below starts the builder again at a short bound of its own.
doneBound := map[string]string{"MESH_BUILDER_STEP_BOUND": testbus.SetupBound(t).String()}
b.start(t, "n1", doneBound)
v := b.await(t, "netcheck", isState(builds.BuildDone))
for _, a := range []string{"tools-go", "tools-typescript"} {
es := reg.of(t, "netcheck/"+a)
@@ -693,6 +697,8 @@ func TestBuilderMakesADoneKeyWithTheDigests(t *testing.T) { // 1607/AC7
}
// DLV-B10: a build module's bound running out fails the trunk build, which is the builder's finding build-failed; the
// fingerprint built again clears it with its done build, numbering nothing of the builder's own (H-A-159).
b.stop()
b.start(t, "n1", map[string]string{"MESH_BUILDER_STEP_BOUND": "1s"}) // a step that never ends runs out of any bound
release := make(chan struct{})
b.fake.hang.Store(&release)
third := "src2:" + strings.Repeat("4", 64)
@@ -713,6 +719,8 @@ func TestBuilderMakesADoneKeyWithTheDigests(t *testing.T) { // 1607/AC7
reg.awaitFinding(t, failed, true)
b.fake.hang.Store(nil)
close(release)
b.stop() // the build again must end done
b.start(t, "n1", doneBound)
b.moduleFP(t, "netcheck", netcheck, "modules/netcheck", bothToolchains, "89abcdef0123456789abcdef0123456789abcdef", third, 3) // the entry moves to a later commit, same fingerprint
b.awaitFP(t, "netcheck", third, isState(builds.BuildDone))
reg.awaitFinding(t, failed, false)
@@ -233,6 +233,12 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
return err
}
b.PackageWait = time.Duration(packageWait) * time.Minute
// A version's digests are recorded under the builder's own bound, never the build's (H-A-492); it is record-bound-seconds.
recordBound, err := numberFile(getenv("MESH_BUILDER_RECORD_BOUND_FILE"), int(build.DefaultRecordBound/time.Second))
if err != nil {
return err
}
b.RecordBound = time.Duration(recordBound) * time.Second
// 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)
@@ -254,11 +260,11 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
}
// A package's number reserved is said as the seat mesh-builds' version-reserved, so the indexer re-pins at the reservation (§805).
reserved.names = versions.NamesFrom(versions.EntriesOf(branches))
reserved.r.Names = reserved.names // a Go package's module path names its tag's directory (§796)
reserved.sayReserved = sayReservedOn(js, cred)
b.Reserved = reserved
// A take-over of a series' reservation by another fingerprint withdraws the older build (H-A-225).
reserved.withdraw = b.Withdraw
reserved.recordAgain = b.RecordAgain // a done build's digests its end did not record are recorded at the start (H-A-492)
// 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.
@@ -273,7 +279,7 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
Entry: entryVia(calls.Call), Send: sendVia(calls.CallKeptAsk),
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)
Started: time.Now()} // a build ended from now on is of the live class, sent first (H-A-290 (1))
Started: time.Now()} // a build ended from now on is of the live class (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))
@@ -322,15 +328,17 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
// 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.Ended
pq.take = items.take
reasksKV.Ready(func(jetstream.KeyValue) { items.AskAllDone(ctx) })
// At the start, a built reservation the catalog holds released is taken in as its version-released would (H-A-484 addendum),
// before the publish items of the rest are asked.
reasksKV.Ready(func(jetstream.KeyValue) {
reserved.releasedAtStart(ctx)
items.AskAllDone(ctx)
})
wirePublishItems(reserved, items, awaitedReserved{awaitedVersions{b: actedKV, bucket: own.acted}}, releasedKept)
acts.Republish = republish.Republish
acts.PublishDrop = func(ctx context.Context, module, version, by, why string) (string, error) {
return pq.drop(ctx, items, module, version, by, why)
}
acts.PublishFirst = func(ctx context.Context, module, version, _, _ string) (string, error) {
return pq.first(ctx, items, module, version)
}
// builder_reserve_done: a done trunk build that reserved none is given a version, and its publish queued as publish again does.
acts.ReserveDone = reserveDoneAct(b.ReserveDone, republish.Republish, logger.Printf)
// The operator is asked once a key's event builds are spent (design 47 G §568): the builder's asker on the seat operator-channel.
@@ -22,19 +22,21 @@ import (
"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"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/testbus"
"git.novox.be/novox/mesh-sdk/go/views"
"mesh-delivery-builder/internal/versions"
)
// Design 47 H2 §793 (whole, against the bus): the builder's work queue publishes, its pull consumers made as it learns a holder.
// A live publish enqueued behind 100 again items while the builder was away is sent first; a dropped item is never sent, and
// put again within the duplicates window is not stored; the move of the old state run twice puts each item once, and the
// builder removes the old state's bucket itself (H-A-461 (1)). The seat mesh-builds' verb publish-queue reads the stream: counts
// per holder and class, the oldest and newest, the live item listed first (H-A-454). Then §796's tag at another commit, its
// reservation's version-reserved waited on by name (§821), and
// §794's backlog held six minutes, as steps (H-A-453 (3)).
func TestThePublishQueueSendsLiveFirstAndNeverADroppedItem(t *testing.T) {
// Design 47 H2 §793 (whole, against the bus): the builder's work queue publishes, one pull consumer made as it learns a holder
// (H-A-483 and its addenda), the class durables of an earlier release retired. No item is lost, a failed send comes back after
// its pause behind an item put meanwhile, and a dropped item never comes back; 100 again items and a live one put while the
// builder was away are all sent, the dropped one never, and put again within the duplicates window it is not stored; the move
// of the old state run twice puts each item once, and the builder removes the old state's bucket itself (H-A-461 (1)). The seat
// mesh-builds' verb publish-queue reads the stream: counts per holder and class, the oldest and newest, the items listed in
// stream order (H-A-454; H-A-483, third addendum). Then §796's tag at another commit, its reservation's version-reserved waited on by name (§821), and §794's
// backlog held six minutes, as steps (H-A-453 (3)).
func TestThePublishQueueLosesNoItemAndNeverSendsADroppedItem(t *testing.T) {
b := startBed(t)
ctx := b.ctx
// The stream as the manifest's old streams section declares it: the module's own, retention work-queue, duplicates 24 hours.
@@ -43,281 +45,426 @@ func TestThePublishQueueSendsLiveFirstAndNeverADroppedItem(t *testing.T) {
Retention: jetstream.WorkQueuePolicy, Discard: jetstream.DiscardNew, Duplicates: 24 * time.Hour, MaxAge: 7 * 24 * time.Hour}); err != nil {
t.Fatal(err)
}
kv := &itemKV{vals: map[string][]byte{}, revs: map[string]uint64{}}
var mu sync.Mutex
var sent []string
published := map[string]bool{} // the modules whose publish is heard
sentCh := make(chan string, 200)
items := &publishItems{reasks: func() jetstream.KeyValue { return kv }, set: publishSettings{Pause: time.Second, PauseMax: time.Minute, Tries: 5},
now: time.Now, logf: t.Logf,
reserved: func(_ context.Context, m, v string) (versions.ReservedVersion, bool, error) {
// One consumer per holder (H-A-483 and its addenda): the holder's class durables of an earlier release are retired, the item
// one of them held unacknowledged reaches the one consumer; no item is lost; a failed send comes back after its pause, and a
// live item put while it waits is sent before it returns; a dropped item never comes back.
t.Run("one consumer", func(t *testing.T) {
const holder, pause = "paused", 3 * time.Second // the pause is far longer than a send of an item put now
bound := testbus.SetupBound(t)
kv := &itemKV{vals: map[string][]byte{}, revs: map[string]uint64{}}
type send struct {
module string
at time.Time
}
var mu sync.Mutex
published, failed := map[string]bool{}, map[string]bool{}
sentCh := make(chan send, 16)
items := &publishItems{reasks: func() jetstream.KeyValue { return kv }, set: publishSettings{Pause: pause, PauseMax: time.Minute, Tries: 5},
now: time.Now, logf: t.Logf,
reserved: func(_ context.Context, m, v string) (versions.ReservedVersion, bool, error) {
mu.Lock()
defer mu.Unlock()
return versions.ReservedVersion{Module: m, Version: v, Artifacts: map[string]string{m + ":a": "sha256:a"}, Published: map[string]bool{m + ":a": published[m]}, BuiltAt: time.Now()}, true, nil
},
send: func(_ context.Context, q versions.QueuedPublish) versions.SendFate {
sentCh <- send{q.Module, time.Now()}
mu.Lock()
defer mu.Unlock()
if (q.Module == "fail" || q.Module == "dropme") && !failed[q.Module] { // the first send of each fails
failed[q.Module] = true
return versions.SendFate{Failed: "the registry is down"}
}
published[q.Module] = true
return versions.SendFate{Sent: true}
}}
pq := &publishQueue{js: b.js, ackWait: time.Minute, logf: t.Logf, take: items.take, binding: publishesOf("mesh-delivery-builder")}
put := func(module, class string) {
q := versions.QueuedPublish{V: 1, Holder: holder, Module: module, Version: "0.1.0", Artifacts: map[string]string{module + ":a": "sha256:a"}, Class: class, Queued: time.Now()}
data, _ := json.Marshal(q)
if _, err := b.js.Publish(ctx, pq.subject(bind, q), data); err != nil {
t.Fatal(err)
}
}
hear := func() { // each publish sent is heard: its item acknowledged once it is held
mu.Lock()
defer mu.Unlock()
return versions.ReservedVersion{Module: m, Version: v, Artifacts: map[string]string{m + ":a": "sha256:a"}, Published: map[string]bool{m + ":a": published[m]}, BuiltAt: time.Now()}, true, nil
},
send: func(_ context.Context, q versions.QueuedPublish) versions.SendFate {
mu.Lock()
sent = append(sent, q.Module)
var done []string
for m, ok := range published {
if ok {
done = append(done, m)
}
}
mu.Unlock()
sentCh <- q.Module
return versions.SendFate{Sent: true}
}}
pq := &publishQueue{js: b.js, ackWait: time.Minute, logf: t.Logf, take: items.take, binding: publishesOf("mesh-delivery-builder")}
item := func(module, class string) versions.QueuedPublish {
return versions.QueuedPublish{V: 1, Holder: "oci", Module: module, Version: "0.1.0", Artifacts: map[string]string{module + ":a": "sha256:a"}, Class: class, Queued: time.Now()}
}
away := func(q versions.QueuedPublish) { // put while the builder was away: no holder learnt, nothing pulled
data, _ := json.Marshal(q)
if _, err := b.js.Publish(ctx, pq.subject(bind, q), data, jetstream.WithMsgID(versions.PublishMsgID(q.Holder, q.Class, q.Module, q.Version))); err != nil {
for _, m := range done {
items.heard(ctx, m, "0.1.0")
}
}
next := func() send {
t.Helper()
select {
case s := <-sentCh:
hear()
return s
case <-time.After(bound):
t.Fatal("no item was sent within the level's set-up share")
}
return send{}
}
// The two class durables an earlier release made, the live one holding an item given and not acknowledged.
for _, class := range []string{versions.PublishClassLive, versions.PublishClassStart} {
if _, err := b.js.CreateOrUpdateConsumer(ctx, bind.Stream, jetstream.ConsumerConfig{Durable: publishesConsumer(holder) + "-" + class,
FilterSubject: bind.Subject + ".publish." + holder + "." + class + ".>", AckPolicy: jetstream.AckExplicitPolicy, AckWait: time.Hour}); err != nil {
t.Fatal(err)
}
}
put("given", versions.PublishClassLive)
old, err := b.js.Consumer(ctx, bind.Stream, publishesConsumer(holder)+"-"+versions.PublishClassLive)
if err != nil {
t.Fatal(err)
}
}
for i := range 100 {
away(item(fmt.Sprintf("a%03d", i), versions.PublishClassStart))
}
away(item("dropme", versions.PublishClassStart))
away(item("live", versions.PublishClassLive))
if answer, err := pq.drop(ctx, items, "dropme", "0.1.0", "op@node", "a test drops it"); err != nil {
t.Fatalf("drop: %v", err)
} else {
t.Log(answer)
}
if dup, err := pq.put(ctx, item("dropme", versions.PublishClassStart)); err != nil || !dup {
t.Errorf("a dropped item put again within the window: duplicate %v (%v), want it not stored", dup, err)
}
raw, err := publishQueueVerb(ctx, pq)("op@node", json.RawMessage(`{}`))
if a, ok := raw.(meshbuilds.PublishQueueAnswer); err != nil || !ok || a.Total != 101 || len(a.Counts) != 2 || a.Counts[0].Class != versions.PublishClassStart ||
a.Counts[0].Count != 100 || a.Counts[1].Count != 1 || a.Counts[0].Oldest.After(a.Counts[0].Newest) || len(a.Queue) != versions.PublishQueueListCap ||
a.Queue[0].Module != "live" || a.Capped {
t.Errorf("publish-queue answered %+v (%v), want 101 items, oci's 100 again and 1 live, fifty listed, the live first", raw, err)
}
if err := pq.learnAll(ctx); err != nil {
t.Fatal(err)
}
select {
case first := <-sentCh:
if first != "live" {
t.Errorf("the first item sent is %s, want the live one, enqueued behind 100 again items", first)
if m, err := old.Next(); err != nil {
t.Fatal(err)
} else if md, _ := m.Metadata(); md.NumDelivered != 1 {
t.Fatalf("the old live durable gave %+v", md)
}
case <-time.After(30 * time.Second):
t.Fatal("nothing was sent")
}
for range 4 { // the again items in flight: at most four held unacknowledged, their publish unheard
select {
case <-sentCh:
case <-time.After(30 * time.Second):
t.Fatal("the again items were not sent")
pq.learn(ctx, holder)
stream, err := b.js.Stream(ctx, bind.Stream)
if err != nil {
t.Fatal(err)
}
var names []string
for n := range stream.ConsumerNames(ctx).Name() {
if strings.HasPrefix(n, publishesConsumer(holder)) {
names = append(names, n)
}
}
if !slices.Equal(names, []string{publishesConsumer(holder)}) {
t.Fatalf("the consumers of %s are %v, want only %s: the class durables retired", holder, names, publishesConsumer(holder))
}
if s := next(); s.module != "given" {
t.Fatalf("sent %s first, want the item the old durable held unacknowledged", s.module)
}
put("fail", versions.PublishClassStart)
put("dropme", versions.PublishClassStart)
var firstFail time.Time
for range 2 {
if s := next(); s.module == "fail" {
firstFail = s.at
}
}
put("live", versions.PublishClassLive) // put while both failed items wait out their pause
if s := next(); s.module != "live" {
t.Fatalf("sent %s, want the live item put while the failed ones wait their pause", s.module)
}
if answer, err := pq.drop(ctx, items, "dropme", "0.1.0", "op@node", "a test drops it"); err != nil {
t.Fatalf("drop: %v", err)
} else {
t.Log(answer)
}
if s := next(); s.module != "fail" || s.at.Sub(firstFail) < pause {
t.Fatalf("sent %s %s after the failed send, want fail again after its pause %s", s.module, s.at.Sub(firstFail), pause)
}
// Every item is acknowledged and the dropped one is gone: nothing is left to come back.
c, err := b.js.Consumer(ctx, bind.Stream, publishesConsumer(holder))
if err != nil {
t.Fatal(err)
}
st, err := b.js.Stream(ctx, bind.Stream)
if err != nil {
t.Fatal(err)
}
for deadline := time.Now().Add(bound); ; {
hear()
info, err := c.Info(ctx)
if err != nil {
t.Fatal(err)
}
sinfo, err := st.Info(ctx, jetstream.WithSubjectFilter(bind.Subject+".publish."+holder+".>"))
if err != nil {
t.Fatal(err)
}
if info.NumAckPending == 0 && info.NumPending == 0 && len(sinfo.State.Subjects) == 0 {
break
}
if time.Now().After(deadline) {
t.Fatalf("the queue of %s holds %v, its consumer %d pending and %d unacknowledged: want every item acknowledged and the dropped one gone", holder, sinfo.State.Subjects, info.NumPending, info.NumAckPending)
}
select {
case s := <-sentCh:
t.Fatalf("sent %s again, want nothing more", s.module)
case <-time.After(10 * time.Millisecond):
}
}
})
t.Run("the queue, the move, tags and backlog", func(t *testing.T) {
kv := &itemKV{vals: map[string][]byte{}, revs: map[string]uint64{}}
var mu sync.Mutex
var sent []string
published := map[string]bool{} // the modules whose publish is heard
sentCh := make(chan string, 200)
items := &publishItems{reasks: func() jetstream.KeyValue { return kv }, set: publishSettings{Pause: time.Second, PauseMax: time.Minute, Tries: 5},
now: time.Now, logf: t.Logf,
reserved: func(_ context.Context, m, v string) (versions.ReservedVersion, bool, error) {
mu.Lock()
defer mu.Unlock()
return versions.ReservedVersion{Module: m, Version: v, Artifacts: map[string]string{m + ":a": "sha256:a"}, Published: map[string]bool{m + ":a": published[m]}, BuiltAt: time.Now()}, true, nil
},
send: func(_ context.Context, q versions.QueuedPublish) versions.SendFate {
mu.Lock()
sent = append(sent, q.Module)
mu.Unlock()
sentCh <- q.Module
return versions.SendFate{Sent: true}
}}
pq := &publishQueue{js: b.js, ackWait: time.Minute, logf: t.Logf, take: items.take, binding: publishesOf("mesh-delivery-builder")}
item := func(module, class string) versions.QueuedPublish {
return versions.QueuedPublish{V: 1, Holder: "oci", Module: module, Version: "0.1.0", Artifacts: map[string]string{module + ":a": "sha256:a"}, Class: class, Queued: time.Now()}
}
away := func(q versions.QueuedPublish) { // put while the builder was away: no holder learnt, nothing pulled
data, _ := json.Marshal(q)
if _, err := b.js.Publish(ctx, pq.subject(bind, q), data, jetstream.WithMsgID(versions.PublishMsgID(q.Holder, q.Class, q.Module, q.Version))); err != nil {
t.Fatal(err)
}
}
for i := range 100 {
away(item(fmt.Sprintf("a%03d", i), versions.PublishClassStart))
}
away(item("dropme", versions.PublishClassStart))
away(item("live", versions.PublishClassLive))
if answer, err := pq.drop(ctx, items, "dropme", "0.1.0", "op@node", "a test drops it"); err != nil {
t.Fatalf("drop: %v", err)
} else {
t.Log(answer)
}
if dup, err := pq.put(ctx, item("dropme", versions.PublishClassStart)); err != nil || !dup {
t.Errorf("a dropped item put again within the window: duplicate %v (%v), want it not stored", dup, err)
}
raw, err := publishQueueVerb(ctx, pq)("op@node", json.RawMessage(`{}`))
if a, ok := raw.(meshbuilds.PublishQueueAnswer); err != nil || !ok || a.Total != 101 || len(a.Counts) != 2 || a.Counts[0].Class != versions.PublishClassStart ||
a.Counts[0].Count != 100 || a.Counts[1].Count != 1 || a.Counts[0].Oldest.After(a.Counts[0].Newest) || len(a.Queue) != versions.PublishQueueListCap ||
a.Queue[0].Module != "a000" || a.Capped {
t.Errorf("publish-queue answered %+v (%v), want 101 items, oci's 100 again and 1 live, fifty listed in stream order, a000 first", raw, err)
}
if err := pq.learnAll(ctx); err != nil {
t.Fatal(err)
}
for range 4 { // the items in flight: at most four held unacknowledged, their publish unheard
select {
case <-sentCh:
case <-time.After(30 * time.Second):
t.Fatal("the again items were not sent")
}
}
deadline := time.After(60 * time.Second)
for { // each publish sent is heard: its item acknowledged, the next sent
mu.Lock()
n, done := len(sent), slices.Clone(sent)
for _, m := range done {
published[m] = true
}
mu.Unlock()
if n >= 101 {
break
}
for _, m := range done {
items.heard(ctx, m, "0.1.0")
}
select {
case <-sentCh:
case <-deadline:
t.Fatalf("sent %d of 101", n)
}
}
}
deadline := time.After(60 * time.Second)
for { // each publish sent is heard: its item acknowledged, the next sent
mu.Lock()
n, done := len(sent), slices.Clone(sent)
for _, m := range done {
published[m] = true
if slices.Contains(sent, "dropme") || len(sent) != 101 {
t.Errorf("sent %d items (dropme among them: %v), want the 101 and never the dropped one", len(sent), slices.Contains(sent, "dropme"))
}
mu.Unlock()
if n >= 101 {
break
// The move of the old state, run twice, puts each item once (at another holder, so the pull of oci is not asked).
old, err := b.js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: builds.StateBucket("mesh-delivery-builder", versions.PublishQueueState)})
if err != nil {
t.Fatal(err)
}
for _, m := range done {
items.heard(ctx, m, "0.1.0")
var tagsWritten []string
call := func(tool string, body any) (json.RawMessage, error) {
switch tool {
case "seat:" + gitseat.Seat + "." + gitseat.VerbTags: // m4's 0.2.0 is tagged at another commit, never read (H-A-494)
tagsWritten = append(tagsWritten, "read "+body.(gitseat.TagsInput).Prefix)
return json.Marshal(gitseat.TagsAnswer{Form: 2, Tags: []gitseat.Tag{{Tag: "modules/m4/v0.2.0", Commit: "c-other"}}})
case "seat:" + gitseat.Seat + ".tag":
tagsWritten = append(tagsWritten, body.(gitseat.TagInput).Tag+"@"+body.(gitseat.TagInput).Commit)
return json.Marshal(gitseat.TagAnswer{Performed: true})
}
return json.Marshal(meshcatalog.VersionsAnswer{Module: "m"})
}
found := &memFindings{vals: map[string][]byte{}}
rv := newReservations(&memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}, call, func() jetstream.KeyValue { return &boundsKV{keys: map[string]bool{}} },
&findings{module: builds.BuilderModule, w: found, logf: t.Logf, now: time.Now}, nil, t.Logf)
rv.filled.Store(true)
type oldItem struct {
key string
raw []byte
}
var olds []oldItem
for _, m := range []string{"m1", "m2", "m3"} {
v, err := rv.Reserve(ctx, m, "0.1", []string{m + ":a"}, versions.Source{Fingerprint: "src2:" + m})
if err != nil {
t.Fatal(err)
}
if err := rv.Built(ctx, m, v.Version, map[string]string{m + ":a": "sha256:a"}, nil); err != nil {
t.Fatal(err)
}
raw, _ := json.Marshal(versions.QueuedPublish{V: 1, Holder: "go", Module: m, Version: v.Version, Artifacts: map[string]string{m + ":a": "sha256:a"}, Class: "asked-again-at-start"})
if _, err := old.Put(ctx, versions.QueueKey("go", m, v.Version), raw); err != nil {
t.Fatal(err)
}
olds = append(olds, oldItem{versions.QueueKey("go", m, v.Version), raw})
}
rp := &versions.Republisher{Reserved: rv.r, Put: func(ctx context.Context, q versions.QueuedPublish) (bool, error) {
data, _ := json.Marshal(q)
ack, err := b.js.Publish(ctx, pq.subject(bind, q), data, jetstream.WithMsgID(versions.PublishMsgID(q.Holder, q.Class, q.Module, q.Version)))
if err != nil {
return false, err
}
return ack.Duplicate, nil
}, Started: time.Now(), Logf: t.Logf}
oldBucket := builds.StateBucket("mesh-delivery-builder", versions.PublishQueueState)
moveOld(ctx, b.js, oldBucket, rp, t.Logf)
if _, err := b.js.KeyValue(ctx, oldBucket); !errors.Is(err, jetstream.ErrBucketNotFound) {
t.Errorf("after the move the old state's bucket answers %v, want it removed by the builder (H-A-461 (1))", err)
}
// A start that stopped before the removal moves the same items again: the duplicates window keeps each once.
again, err := b.js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: oldBucket})
if err != nil {
t.Fatal(err)
}
for _, e := range olds {
if _, err := again.Put(ctx, e.key, e.raw); err != nil {
t.Fatal(err)
}
}
moveOld(ctx, b.js, oldBucket, rp, t.Logf)
moveOld(ctx, b.js, oldBucket, rp, t.Logf) // no bucket left: nothing moves
if _, err := b.js.KeyValue(ctx, oldBucket); !errors.Is(err, jetstream.ErrBucketNotFound) {
t.Errorf("after the second move the old state's bucket answers %v, want it removed", err)
}
st, err := b.js.Stream(ctx, bind.Stream)
if err != nil {
t.Fatal(err)
}
info, err := st.Info(ctx, jetstream.WithSubjectFilter(bind.Subject+".publish.go.>"))
if err != nil {
t.Fatal(err)
}
if len(info.State.Subjects) != 3 || info.State.Subjects[bind.Subject+".publish.go.again.m1.0=2E1=2E0"] != 1 {
t.Errorf("the move run twice left %v on the work queue: want each of the three once, as again", info.State.Subjects)
}
// Design 47 H2 H-A-494: no git tag is read before a reserve nor written at a release: m4's 0.2.0, which the seat git would
// answer tagged at another commit, is reserved, no finding raised, and its version-released writes no tag.
// Design 47 H2 §821, §805: the reservation is said as the seat mesh-builds' version-reserved, said as the process says it
// (sayReservedOn), and waited on by the seat and the event's name.
rv.names = func(context.Context, string, string) (string, bool, error) {
return "git.example/o/r/modules/m4", true, nil
}
rv.sayReserved = sayReservedOn(b.js, process.Account{Module: builds.BuilderModule, Node: "n1"})
said, err := nats.Connect(b.srvURL, nats.UserInfo("ctl", "pw"))
if err != nil {
t.Fatal(err)
}
defer said.Close()
reservedCh := make(chan *nats.Msg, 4)
rs, err := said.ChanSubscribe(meshbuilds.SubjectVersionReserved, reservedCh)
if err != nil {
t.Fatal(err)
}
defer rs.Unsubscribe()
if err := said.Flush(); err != nil {
t.Fatal(err)
}
v4, err := rv.Reserve(ctx, "m4", "0.2", []string{"m4:lib"}, versions.Source{Fingerprint: "src2:m4",
Repository: "o/r", Commit: "c-mine", Branch: "main", CatalogRevision: 1})
elsewhere := views.FindingKey(meshconditionsclient.ScopeModule, "m4", versions.VersionTaggedElsewhere)
if _, raised := found.vals[elsewhere]; err != nil || v4.Version != "0.2.0" || v4.Tag != "" || raised {
t.Fatalf("m4 reserved %+v (%v), %s raised %v: want 0.2.0 naming no tag, no tag read and no finding", v4, err, elsewhere, raised)
}
select {
case <-sentCh:
case <-deadline:
t.Fatalf("sent %d of 101", n)
case m := <-reservedCh:
ev, _, err := meshbuilds.DecodeVersionReservedEvent(m.Data)
if err != nil || ev.Module != "m4" || ev.Artifact != "m4:lib" || ev.Path != "git.example/o/r/modules/m4" || ev.Version != "0.2.0" ||
ev.Fingerprint != "src2:m4" || ev.Revision != "main.1" || m.Header.Get("x-source") != builds.BuilderModule {
t.Errorf("version-reserved = %+v (%v) from %q, want m4:lib at 0.2.0, its path, fingerprint src2:m4 and revision main.1, said by the builder", ev, err, m.Header.Get("x-source"))
}
case <-time.After(10 * time.Second):
t.Fatal("no version-reserved of m4's reservation within 10 s on " + meshbuilds.SubjectVersionReserved)
}
catalogEvents, err := b.js.StreamNameBySubject(ctx, meshcatalog.SubjectVersionReleased) // the bed's stream of the catalog's events
if err != nil {
t.Fatal(err)
}
evs, err := b.js.CreateOrUpdateConsumer(ctx, catalogEvents, jetstream.ConsumerConfig{Durable: "builder-events", AckPolicy: jetstream.AckExplicitPolicy,
FilterSubject: meshcatalog.SubjectVersionReleased, DeliverPolicy: jetstream.DeliverNewPolicy})
if err != nil {
t.Fatal(err)
}
next := func(module, version string) jetstream.Msg {
t.Helper()
data, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: module, Version: version})
if _, err := b.js.Publish(ctx, meshcatalog.SubjectVersionReleased, data); err != nil {
t.Fatal(err)
}
m, err := evs.Next(jetstream.FetchMaxWait(10 * time.Second))
if err != nil {
t.Fatal(err)
}
return m
}
if !rv.heard(ctx, next("m4", "0.2.0")) {
t.Fatal("the reservations did not take version-released")
}
if _, standing, _ := rv.r.Of(ctx, "m4", "0.2.0"); standing || len(tagsWritten) != 0 {
t.Errorf("after version-released m4 0.2.0 standing %v, tags read or written %v: want it released and no tag read or written", standing, tagsWritten)
}
}
mu.Lock()
if slices.Contains(sent, "dropme") || len(sent) != 101 {
t.Errorf("sent %d items (dropme among them: %v), want the 101 and never the dropped one", len(sent), slices.Contains(sent, "dropme"))
}
mu.Unlock()
// The move of the old state, run twice, puts each item once (at another holder, so the pull of oci is not asked).
old, err := b.js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: builds.StateBucket("mesh-delivery-builder", versions.PublishQueueState)})
if err != nil {
t.Fatal(err)
}
var tagsWritten []string
call := func(tool string, body any) (json.RawMessage, error) {
switch tool {
case "seat:" + gitseat.Seat + "." + gitseat.VerbTags: // m4's 0.2.0 is tagged at another commit (§796)
return json.Marshal(gitseat.TagsAnswer{Form: 2, Tags: []gitseat.Tag{{Tag: "modules/m4/v0.2.0", Commit: "c-other"}}})
case "seat:" + gitseat.Seat + ".tag":
tagsWritten = append(tagsWritten, body.(gitseat.TagInput).Tag+"@"+body.(gitseat.TagInput).Commit)
return json.Marshal(gitseat.TagAnswer{Performed: true})
}
return json.Marshal(meshcatalog.VersionsAnswer{Module: "m"})
}
found := &memFindings{vals: map[string][]byte{}}
rv := newReservations(&memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}, call, func() jetstream.KeyValue { return &boundsKV{keys: map[string]bool{}} },
&findings{module: builds.BuilderModule, w: found, logf: t.Logf, now: time.Now}, nil, t.Logf)
rv.filled.Store(true)
type oldItem struct {
key string
raw []byte
}
var olds []oldItem
for _, m := range []string{"m1", "m2", "m3"} {
v, err := rv.Reserve(ctx, m, "0.1", []string{m + ":a"}, versions.Source{Fingerprint: "src2:" + m})
// Design 47 H2 §794 (whole, H-A-453 (3), H-A-462): a message the builder's handler leaves unacknowledged is kept on its
// consumer's ledger in the state consumers on the bus; held six minutes, the health names that backlog, and within five
// minutes it does not.
consumers, err := b.js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: builds.StateBucket(builds.BuilderModule, process.ConsumersState)})
if err != nil {
t.Fatal(err)
}
if err := rv.Built(ctx, m, v.Version, map[string]string{m + ":a": "sha256:a"}, nil); err != nil {
t.Fatal(err)
held := time.Now()
hub := &oneHandler{}
aged := agedHub{hub: hub, ledgers: &ledgers{logf: t.Logf, now: func() time.Time { return held },
sink: consumersSink(process.AwaitBucket(ctx, b.js, nil, builds.StateBucket(builds.BuilderModule, process.ConsumersState), "", t.Logf))}}
_ = aged.Handle(meshcatalog.SubjectVersionReleased, func(m jetstream.Msg) { _ = m.Nak() }) // a handler standing still: asked again
hub.handle(next("m5", "0.1.0"))
state := versions.Reader{Keys: func() ([]string, error) {
l, err := consumers.ListKeys(ctx)
if err != nil {
return nil, err
}
var keys []string
for k := range l.Keys() {
keys = append(keys, k)
}
return keys, nil
}, Get: func(k string) (json.RawMessage, bool, error) {
e, err := consumers.Get(ctx, k)
if errors.Is(err, jetstream.ErrKeyNotFound) {
return nil, false, nil
}
if err != nil {
return nil, false, err
}
return e.Value(), true, nil
}}
if a := versions.BuilderHealth(state, held.Add(6*time.Minute), 5*time.Minute); a.Healthy || !strings.Contains(a.Why, "builder-events (its oldest unacknowledged message waits 6m0s") {
t.Errorf("the health with a backlog held six minutes = %+v, want unhealthy naming builder-events", a)
}
raw, _ := json.Marshal(versions.QueuedPublish{V: 1, Holder: "go", Module: m, Version: v.Version, Artifacts: map[string]string{m + ":a": "sha256:a"}, Class: "asked-again-at-start"})
if _, err := old.Put(ctx, versions.QueueKey("go", m, v.Version), raw); err != nil {
t.Fatal(err)
if a := versions.BuilderHealth(state, held.Add(4*time.Minute), 5*time.Minute); !a.Healthy {
t.Errorf("the health four minutes in = %+v, want healthy", a)
}
olds = append(olds, oldItem{versions.QueueKey("go", m, v.Version), raw})
}
rp := &versions.Republisher{Reserved: rv.r, Put: func(ctx context.Context, q versions.QueuedPublish) (bool, error) {
data, _ := json.Marshal(q)
ack, err := b.js.Publish(ctx, pq.subject(bind, q), data, jetstream.WithMsgID(versions.PublishMsgID(q.Holder, q.Class, q.Module, q.Version)))
if err != nil {
return false, err
}
return ack.Duplicate, nil
}, Started: time.Now(), Logf: t.Logf}
oldBucket := builds.StateBucket("mesh-delivery-builder", versions.PublishQueueState)
moveOld(ctx, b.js, oldBucket, rp, t.Logf)
if _, err := b.js.KeyValue(ctx, oldBucket); !errors.Is(err, jetstream.ErrBucketNotFound) {
t.Errorf("after the move the old state's bucket answers %v, want it removed by the builder (H-A-461 (1))", err)
}
// A start that stopped before the removal moves the same items again: the duplicates window keeps each once.
again, err := b.js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: oldBucket})
if err != nil {
t.Fatal(err)
}
for _, e := range olds {
if _, err := again.Put(ctx, e.key, e.raw); err != nil {
t.Fatal(err)
}
}
moveOld(ctx, b.js, oldBucket, rp, t.Logf)
moveOld(ctx, b.js, oldBucket, rp, t.Logf) // no bucket left: nothing moves
if _, err := b.js.KeyValue(ctx, oldBucket); !errors.Is(err, jetstream.ErrBucketNotFound) {
t.Errorf("after the second move the old state's bucket answers %v, want it removed", err)
}
st, err := b.js.Stream(ctx, bind.Stream)
if err != nil {
t.Fatal(err)
}
info, err := st.Info(ctx, jetstream.WithSubjectFilter(bind.Subject+".publish.go.>"))
if err != nil {
t.Fatal(err)
}
if len(info.State.Subjects) != 3 || info.State.Subjects[bind.Subject+".publish.go.again.m1.0=2E1=2E0"] != 1 {
t.Errorf("the move run twice left %v on the work queue: want each of the three once, as again", info.State.Subjects)
}
// Design 47 H2 §796 (whole, H-A-453 (3)): a module's tags are read before it reserves; a number whose tag stands at another
// commit is skipped, the next number taken and version-tagged-elsewhere raised; the release tags <directory>/v<version> at
// the build's commit, and the module's version-released clears the finding.
rv.r.Names = func(context.Context, string, string) (string, bool, error) {
return "git.example/o/r/modules/m4", true, nil
}
// Design 47 H2 §821, §805: the reservation is said as the seat mesh-builds' version-reserved, said as the process says it
// (sayReservedOn), and waited on by the seat and the event's name.
rv.names, rv.sayReserved = rv.r.Names, sayReservedOn(b.js, process.Account{Module: builds.BuilderModule, Node: "n1"})
said, err := nats.Connect(b.srvURL, nats.UserInfo("ctl", "pw"))
if err != nil {
t.Fatal(err)
}
defer said.Close()
reservedCh := make(chan *nats.Msg, 4)
rs, err := said.ChanSubscribe(meshbuilds.SubjectVersionReserved, reservedCh)
if err != nil {
t.Fatal(err)
}
defer rs.Unsubscribe()
if err := said.Flush(); err != nil {
t.Fatal(err)
}
v4, err := rv.Reserve(ctx, "m4", "0.2", []string{"m4:lib"}, versions.Source{Fingerprint: "src2:m4", GoPackage: true, GoArtifact: "lib",
Repository: "o/r", Commit: "c-mine", Branch: "main", CatalogRevision: 1})
elsewhere := views.FindingKey(meshconditionsclient.ScopeModule, "m4", versions.VersionTaggedElsewhere)
if _, raised := found.vals[elsewhere]; err != nil || v4.Version != "0.2.1" || v4.Tag != "modules/m4/v0.2.1" || !raised {
t.Fatalf("m4 reserved %+v (%v), %s raised %v: want 0.2.1 past 0.2.0's tag at another commit, its tag modules/m4/v0.2.1, and the finding", v4, err, elsewhere, raised)
}
select {
case m := <-reservedCh:
ev, _, err := meshbuilds.DecodeVersionReservedEvent(m.Data)
if err != nil || ev.Module != "m4" || ev.Artifact != "m4:lib" || ev.Path != "git.example/o/r/modules/m4" || ev.Version != "0.2.1" ||
ev.Fingerprint != "src2:m4" || ev.Revision != "main.1" || m.Header.Get("x-source") != builds.BuilderModule {
t.Errorf("version-reserved = %+v (%v) from %q, want m4:lib at 0.2.1, its path, fingerprint src2:m4 and revision main.1, said by the builder", ev, err, m.Header.Get("x-source"))
}
case <-time.After(10 * time.Second):
t.Fatal("no version-reserved of m4's reservation within 10 s on " + meshbuilds.SubjectVersionReserved)
}
catalogEvents, err := b.js.StreamNameBySubject(ctx, meshcatalog.SubjectVersionReleased) // the bed's stream of the catalog's events
if err != nil {
t.Fatal(err)
}
evs, err := b.js.CreateOrUpdateConsumer(ctx, catalogEvents, jetstream.ConsumerConfig{Durable: "builder-events", AckPolicy: jetstream.AckExplicitPolicy,
FilterSubject: meshcatalog.SubjectVersionReleased, DeliverPolicy: jetstream.DeliverNewPolicy})
if err != nil {
t.Fatal(err)
}
next := func(module, version string) jetstream.Msg {
t.Helper()
data, _ := json.Marshal(meshcatalog.VersionReleasedEvent{Module: module, Version: version})
if _, err := b.js.Publish(ctx, meshcatalog.SubjectVersionReleased, data); err != nil {
t.Fatal(err)
}
m, err := evs.Next(jetstream.FetchMaxWait(10 * time.Second))
if err != nil {
t.Fatal(err)
}
return m
}
if !rv.heard(ctx, next("m4", "0.2.1")) {
t.Fatal("the reservations did not take version-released")
}
if _, raised := found.vals[elsewhere]; raised || !slices.Equal(tagsWritten, []string{"modules/m4/v0.2.1@c-mine"}) {
t.Errorf("after version-released %s raised %v, tags written %v: want it cleared and modules/m4/v0.2.1 written at c-mine, no tag moved", elsewhere, raised, tagsWritten)
}
// Design 47 H2 §794 (whole, H-A-453 (3), H-A-462): a message the builder's handler leaves unacknowledged is kept on its
// consumer's ledger in the state consumers on the bus; held six minutes, the health names that backlog, and within five
// minutes it does not.
consumers, err := b.js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: builds.StateBucket(builds.BuilderModule, process.ConsumersState)})
if err != nil {
t.Fatal(err)
}
held := time.Now()
hub := &oneHandler{}
aged := agedHub{hub: hub, ledgers: &ledgers{logf: t.Logf, now: func() time.Time { return held },
sink: consumersSink(process.AwaitBucket(ctx, b.js, nil, builds.StateBucket(builds.BuilderModule, process.ConsumersState), "", t.Logf))}}
_ = aged.Handle(meshcatalog.SubjectVersionReleased, func(m jetstream.Msg) { _ = m.Nak() }) // a handler standing still: asked again
hub.handle(next("m5", "0.1.0"))
state := versions.Reader{Keys: func() ([]string, error) {
l, err := consumers.ListKeys(ctx)
if err != nil {
return nil, err
}
var keys []string
for k := range l.Keys() {
keys = append(keys, k)
}
return keys, nil
}, Get: func(k string) (json.RawMessage, bool, error) {
e, err := consumers.Get(ctx, k)
if errors.Is(err, jetstream.ErrKeyNotFound) {
return nil, false, nil
}
if err != nil {
return nil, false, err
}
return e.Value(), true, nil
}}
if a := versions.BuilderHealth(state, held.Add(6*time.Minute), 5*time.Minute); a.Healthy || !strings.Contains(a.Why, "builder-events (its oldest unacknowledged message waits 6m0s") {
t.Errorf("the health with a backlog held six minutes = %+v, want unhealthy naming builder-events", a)
}
if a := versions.BuilderHealth(state, held.Add(4*time.Minute), 5*time.Minute); !a.Healthy {
t.Errorf("the health four minutes in = %+v, want healthy", a)
}
})
}
@@ -7,7 +7,6 @@ import (
"fmt"
"io/fs"
"os"
"sort"
"strconv"
"strings"
"sync"
@@ -531,9 +530,9 @@ func builtOf(all []versions.ReservedVersion) []versions.ReservedVersion {
// the manifest's old streams section with the work-queue retention, the module's own, consumed by the module's one process on the
// module's account (H-A-464), which declares no bus and so is the stream's one reader by the module's shape; each item on
// `mesh.stream.<module>.event.publish.<holder>.<class>.<module>.<version>` under the message id
// `<holder>.<class>.<module>.<version>`. The builder makes the pull consumers at run time as it learns a holder,
// `publishes-<holder>-<class>`, with ack wait publish-pause-max, max ack pending four and max deliveries ten, and pulls the live
// class first, at most four sends at once per holder.
// `<holder>.<class>.<module>.<version>`. The builder makes one pull consumer at run time as it learns a holder,
// `publishes-<holder>`, with ack wait publish-pause-max, max ack pending four and max deliveries ten, and sends its items in the
// order the consumer gives them, at most four at once per holder (H-A-483 and its addenda).
type publishQueue struct {
js jetstream.JetStream
binding func() (publishesStream, error)
@@ -555,16 +554,16 @@ func publishesOf(module string) func() (publishesStream, error) {
return func() (publishesStream, error) { return b, nil }
}
// The consumers' numbers (H-A-446 (2)): at most four sends in flight per holder and class, and ten deliveries, the work queue's
// largest; the builder ends an item at publish-tries anyway.
// The consumer's numbers (H-A-446 (2)): at most four sends in flight per holder, and ten deliveries, the work queue's largest;
// the builder ends an item at publish-tries anyway.
const (
publishesMaxAckPending = versions.PublishSendsAtOnce
publishesMaxDeliver = 10
)
// publishesConsumer is the durable consumer of holder's items of class.
func publishesConsumer(holder, class string) string {
return versions.PublishesLocal + "-" + holder + "-" + class
// publishesConsumer is the one durable consumer of holder's items (H-A-483 addendum).
func publishesConsumer(holder string) string {
return versions.PublishesLocal + "-" + holder
}
// subject is the item's subject on the bus.
@@ -616,8 +615,15 @@ func (pq *publishQueue) learnAll(ctx context.Context) error {
return nil
}
// learn starts holder's pull once.
// learn starts holder's pull once. A holder is a module name, so one ending in -live or -again, the class durables an earlier
// release made, is refused, said (H-A-483, third addendum): its consumer would be another holder's old durable.
func (pq *publishQueue) learn(ctx context.Context, holder string) {
for _, class := range []string{versions.PublishClassLive, versions.PublishClassStart} {
if strings.HasSuffix(holder, "-"+class) {
pq.logf("the publishes of %s are refused: a holder is a module name, and one ending in -%s names the class durable of an earlier release (H-A-483)", holder, class)
return
}
}
pq.mu.Lock()
if pq.pulling == nil {
pq.pulling = map[string]bool{}
@@ -636,94 +642,71 @@ func (pq *publishQueue) learn(ctx context.Context, holder string) {
}
}
// pull makes holder's two consumers and dispatches their items, the live class first, at most four sends at once: an again item
// waits while a live one waits on the queue.
// pull makes holder's one consumer and dispatches its items (design 47 H2 §793, H-A-483 and its addenda): first it retires the
// holder's class durables an earlier release made (`-live`, `-again`), whose filters a work queue refuses beside the one; their
// unacknowledged items stay on the queue and reach the one consumer.
func (pq *publishQueue) pull(ctx context.Context, holder string) error {
b, err := pq.binding()
if err != nil {
return err
}
chans := map[string]chan jetstream.Msg{}
var live jetstream.Consumer
for _, class := range []string{versions.PublishClassStart, versions.PublishClassLive} { // the again first: the live is first by the dispatch, not by luck
c, err := pq.js.CreateOrUpdateConsumer(ctx, b.Stream, jetstream.ConsumerConfig{Durable: publishesConsumer(holder, class),
FilterSubject: b.Subject + ".publish." + versions.EscapeToken(holder) + "." + class + ".>", AckPolicy: jetstream.AckExplicitPolicy,
AckWait: pq.ackWait, MaxAckPending: publishesMaxAckPending, MaxDeliver: publishesMaxDeliver})
if err != nil {
return fmt.Errorf("the consumer %s: %w", publishesConsumer(holder, class), err)
}
ch := make(chan jetstream.Msg, publishesMaxAckPending)
cc, err := c.Consume(func(m jetstream.Msg) { ch <- m }, jetstream.PullMaxMessages(publishesMaxAckPending))
if err != nil {
return fmt.Errorf("the consumer %s is not pulled: %w", publishesConsumer(holder, class), err)
}
go func() { <-ctx.Done(); cc.Stop() }()
chans[class] = ch
if class == versions.PublishClassLive {
live = c
for _, class := range []string{versions.PublishClassLive, versions.PublishClassStart} {
old := publishesConsumer(holder) + "-" + class
err := pq.js.DeleteConsumer(ctx, b.Stream, old)
switch {
case err == nil:
pq.logf("the consumer %s of an earlier release is removed: the publishes of %s have one consumer (H-A-483)", old, holder)
case !errors.Is(err, jetstream.ErrConsumerNotFound):
return fmt.Errorf("the consumer %s of an earlier release is not removed: %w", old, err)
}
}
liveWaits := func() bool {
info, err := live.Info(ctx)
return err == nil && info.NumPending > 0
c, err := pq.js.CreateOrUpdateConsumer(ctx, b.Stream, jetstream.ConsumerConfig{Durable: publishesConsumer(holder),
FilterSubject: b.Subject + ".publish." + versions.EscapeToken(holder) + ".>", AckPolicy: jetstream.AckExplicitPolicy,
AckWait: pq.ackWait, MaxAckPending: publishesMaxAckPending, MaxDeliver: publishesMaxDeliver})
if err != nil {
return fmt.Errorf("the consumer %s: %w", publishesConsumer(holder), err)
}
pq.logf("pulling the publishes of %s, the live first", holder)
go pq.dispatch(ctx, chans[versions.PublishClassLive], chans[versions.PublishClassStart], liveWaits)
pq.logf("pulling the publishes of %s", holder)
go pq.dispatch(ctx, holder, c)
return nil
}
// dispatch runs the items of one holder, at most four at once, every live item before an again one: an again item pulled while
// a live one waits on the queue (liveWaits) runs after it.
func (pq *publishQueue) dispatch(ctx context.Context, live, again <-chan jetstream.Msg, liveWaits func() bool) {
// dispatch runs the items of one holder in the order its one consumer gives them, at most four at once (design 47 H2 §793,
// H-A-483): each free slot takes the next item through a pull that waits, so an item put or handed back after its pause is
// received the moment the bus gives it; an item handed back reappears only after its pause, so an item put meanwhile goes
// before it. A pull the bus refuses ends the dispatch, said; the holder is pulled again when an item of it is put.
func (pq *publishQueue) dispatch(ctx context.Context, holder string, c jetstream.Consumer) {
sem := make(chan struct{}, versions.PublishSendsAtOnce)
run := func(m jetstream.Msg) {
go func() {
defer func() { <-sem }()
pq.take(ctx, m)
}()
}
var spare jetstream.Msg // an again item pulled while a live one waited
for {
select {
case sem <- struct{}{}:
case <-ctx.Done():
return
}
select {
case m := <-live:
run(m)
continue
default:
}
m := spare
spare = nil
if m == nil {
select {
case lm := <-live:
run(lm)
continue
case m = <-again:
case <-ctx.Done():
return
var got jetstream.Msg
b, err := c.Fetch(1)
if err == nil {
for m := range b.Messages() {
got = m
}
err = b.Error()
}
if liveWaits() {
spare = m
select {
case lm := <-live:
run(lm)
case <-ctx.Done():
return
}
if err != nil && !errors.Is(err, jetstream.ErrNoMessages) && !errors.Is(err, nats.ErrTimeout) && ctx.Err() == nil {
<-sem
pq.logf("the publishes of %s are not pulled: %v; they are pulled when an item of it is put", holder, err)
pq.mu.Lock()
delete(pq.pulling, holder)
pq.mu.Unlock()
return
}
if got == nil {
<-sem
continue
}
select {
case lm := <-live: // came while the queue was asked
spare = m
run(lm)
default:
run(m)
}
go func(m jetstream.Msg) {
defer func() { <-sem }()
pq.take(ctx, m)
}(got)
}
}
@@ -827,45 +810,6 @@ func (pq *publishQueue) drop(ctx context.Context, items *publishItems, module, v
return fmt.Sprintf("the publish of %s %s is dropped: %d items terminated, and none is sent or put again", module, version, len(qs)), nil
}
// first is builder_publish_first (§793): each again item of the version is put again as live, under the message id
// `<holder>.live.<module>.<version>`, and the old terminated; a live id the queue holds within its window takes nothing, and the
// old stays, said.
func (pq *publishQueue) first(ctx context.Context, items *publishItems, module, version string) (string, error) {
qs, st, err := pq.itemsOf(ctx, module, version, versions.PublishClassStart)
if err != nil {
return "", fmt.Errorf("the work queue %s cannot be read: %w", versions.PublishesLocal, err)
}
if len(qs) == 0 {
return "", fmt.Errorf("the work queue %s holds no again item of %s %s", versions.PublishesLocal, module, version)
}
var moved, kept []string
for subj, q := range qs {
q.Class = versions.PublishClassLive
dup, err := pq.put(ctx, q)
if err != nil {
return "", fmt.Errorf("%s %s is not put again as live at %s: %w", module, version, q.Holder, err)
}
if dup {
kept = append(kept, q.Holder)
continue
}
if err := st.Purge(ctx, jetstream.WithPurgeSubject(subj)); err != nil {
return "", fmt.Errorf("the again item of %s %s at %s is not terminated: %w", module, version, q.Holder, err)
}
moved = append(moved, q.Holder)
}
for _, h := range items.settle(module, version, func(h heldItem) bool { return h.q.Class == versions.PublishClassStart }) {
_ = h.m.Term()
}
sort.Strings(moved)
answer := fmt.Sprintf("%s %s is put first as live at %s, its again item terminated", module, version, strings.Join(moved, ", "))
if len(kept) > 0 {
sort.Strings(kept)
answer += fmt.Sprintf("; at %s the work queue holds its live id within the duplicates window, so its again item stays", strings.Join(kept, ", "))
}
return answer, nil
}
// endItem writes the version's publish item ended with answer, made when none stands: Try and take then leave it, and a start
// asks it no more.
func (p *publishItems) endItem(ctx context.Context, module, version, answer string) error {
@@ -440,3 +440,17 @@ func TestAPublishIsNotAskedAgainWhileItsPublishedMayBeUnheard(t *testing.T) {
})
}
}
// Design 47 H2 H-A-483 (third addendum): a holder is a module name, so one ending in -live or -again, the class durables of an
// earlier release, is refused at the learn, said, and nothing of it is pulled.
func TestAHolderNamedLikeAClassDurableIsRefused(t *testing.T) {
for _, holder := range []string{"oci-live", "oci-again"} {
var said []string
pq := &publishQueue{logf: func(f string, a ...any) { said = append(said, fmt.Sprintf(f, a...)) },
binding: func() (publishesStream, error) { return publishesStream{}, errors.New("no bus in a unit test") }}
pq.learn(context.Background(), holder)
if len(said) != 1 || !strings.Contains(said[0], "the publishes of "+holder+" are refused") || pq.pulling[holder] {
t.Errorf("%s: said %q, pulling %v, want it refused at the learn, said once, nothing pulled", holder, said, pq.pulling[holder])
}
}
}
@@ -65,7 +65,7 @@ func reAsked(ctx context.Context, b askAgainer, acts versions.Acts, items *publi
released(ctx, b, kv, e, r, logf)
return
}
if r.Mode == build.ModeRepublish || r.Mode == build.ModePublishDrop || r.Mode == build.ModePublishFirst || r.Mode == build.ModeFloorAgain || r.Mode == build.ModeOldFormDrop || r.Mode == build.ModeReservedDrop || r.Mode == build.ModeReserveDone {
if r.Mode == build.ModeRepublish || r.Mode == build.ModePublishDrop || r.Mode == build.ModeFloorAgain || r.Mode == build.ModeOldFormDrop || r.Mode == build.ModeReservedDrop || r.Mode == build.ModeReserveDone {
// A version's hand act (design 51 *Tools of the builder*) may build again, so it is answered beside the watch.
go versionActed(ctx, acts, kv, e, r, logf)
return
@@ -208,11 +208,8 @@ func versionActed(ctx context.Context, acts versions.Acts, kv jetstream.KeyValue
r.Answer = "queued " + fmt.Sprint(len(r.Queued)) + " versions to publish again: " + strings.Join(r.Queued, ", ") + "; builder_publish_queue shows them"
}
}
} else if r.Mode == build.ModePublishDrop || r.Mode == build.ModePublishFirst {
} else if r.Mode == build.ModePublishDrop {
act := acts.PublishDrop
if r.Mode == build.ModePublishFirst {
act = acts.PublishFirst
}
if act == nil {
err = errors.New("this builder keeps no work queue of publishes")
} else {
@@ -14,7 +14,6 @@ import (
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
"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/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/process"
@@ -57,8 +56,9 @@ type reservations struct {
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
// recordAgain records the digests of a done build of module at fp its end did not record, saying so (design 47 H2 H-A-492);
// nil records none.
recordAgain func(ctx context.Context, module, fp, when string) (string, error)
// 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.
@@ -117,7 +117,7 @@ func sayReservedOn(js jetstream.JetStream, cred process.Account) func(context.Co
// newReservations makes the reserving over store; the released versions of a module are asked of the seat mesh-catalog's
// verb versions through call (design 47 G §348), the only source numbering reads them from.
func newReservations(store versions.ReserveStore, call toolCaller, bounds func() jetstream.KeyValue, found *findings, wake func(context.Context), logf func(string, ...any)) *reservations {
rv := &reservations{call: call, bounds: bounds, found: found, bound: versions.UnreleasedBound, wake: wake, logf: logf}
rv := &reservations{bounds: bounds, found: found, bound: versions.UnreleasedBound, wake: wake, logf: logf}
rv.r = &versions.Reserver{Store: store, Filled: rv.filled.Load, ReleasedOf: func(_ context.Context, module string) ([]string, error) {
raw, err := call("seat:"+meshcatalog.Seat+".versions", meshcatalog.VersionsInput{Module: module})
if err != nil {
@@ -134,8 +134,6 @@ func newReservations(store versions.ReserveStore, call toolCaller, bounds func()
return out, nil
}}
rv.r.Took, rv.r.Logf, rv.r.Reserved = rv.took, logf, rv.reservedSaid
// A module's tags are read before it reserves, and a number tagged at another commit skipped (design 47 H2 §796).
rv.r.Tags, rv.r.TaggedElsewhere = tagsVia(call), rv.taggedElsewhere
return rv
}
@@ -310,7 +308,7 @@ func (rv *reservations) heard(ctx context.Context, m jetstream.Msg) bool {
rv.logf("%s holds what is no version-released, left: %v", m.Subject(), err)
break
}
if err := rv.tagged(ctx, ev); err != nil {
if err := rv.release(ctx, ev); err != nil {
rv.logf("%v; heard again", err)
if nakErr := m.Nak(); nakErr != nil {
rv.logf("leaving %s for the bus to give again: %v", m.Subject(), nakErr)
@@ -318,24 +316,6 @@ func (rv *reservations) heard(ctx context.Context, m jetstream.Msg) bool {
givenUp(m, "the version-released of "+ev.Module+" "+ev.Version, err, rv.logf)
return true
}
gone, err := rv.r.Released(ctx, ev.Module, ev.Version)
if err != nil {
rv.logf("%v; heard again", err)
if nakErr := m.Nak(); nakErr != nil {
rv.logf("leaving %s for the bus to give again: %v", m.Subject(), nakErr)
}
givenUp(m, "the version-released of "+ev.Module+" "+ev.Version, err, rv.logf)
return true
}
for _, k := range gone {
rv.dropBound(ctx, k)
}
if rv.released != nil {
rv.released(ctx, ev.Module, ev.Version)
}
rv.found.clear(ctx, versions.VersionUnreleased, meshconditionsclient.ScopeModule, ev.Module)
rv.found.clear(ctx, versions.VersionHeldElsewhere, meshconditionsclient.ScopeModule, ev.Module)
rv.found.clear(ctx, versions.VersionTaggedElsewhere, meshconditionsclient.ScopeModule, ev.Module)
default:
return false
}
@@ -345,6 +325,87 @@ func (rv *reservations) heard(ctx context.Context, m jetstream.Msg) bool {
return true
}
// release takes a released version in as the catalog's version-released says it (design 47 G §369): its reservation released,
// its bound and publish item ended and its findings cleared. No git tag is written (design 47 H2 H-A-494).
func (rv *reservations) release(ctx context.Context, ev meshcatalog.VersionReleasedEvent) error {
gone, err := rv.r.Released(ctx, ev.Module, ev.Version)
if err != nil {
return err
}
for _, k := range gone {
rv.dropBound(ctx, k)
}
if rv.released != nil {
rv.released(ctx, ev.Module, ev.Version)
}
rv.found.clear(ctx, versions.VersionUnreleased, meshconditionsclient.ScopeModule, ev.Module)
rv.found.clear(ctx, versions.VersionHeldElsewhere, meshconditionsclient.ScopeModule, ev.Module)
rv.found.clear(ctx, versions.VersionTaggedElsewhere, meshconditionsclient.ScopeModule, ev.Module) // one raised before H-A-494
return nil
}
// releasedAtStart takes in, at the builder's start, every built, unreleased reservation whose version the catalog's verb versions
// holds released, as its version-released would (design 47 H2 H-A-484 addendum): a version-released the bus gave up on, or one
// said while the builder was away, is taken all the same, its reservation released and its publish item ended; no tag is written
// (design 47 H2 H-A-494).
// A module whose versions cannot be read, and a release that is not taken, are said and left to its next version-released.
// Before that, a standing reservation with no digests recorded whose build key is done has them recorded from the done key
// (design 47 H2 H-A-492), so it is held against the released versions too.
func (rv *reservations) releasedAtStart(ctx context.Context) {
all, err := rv.r.All(ctx)
if err != nil {
rv.logf("the reservations are not held against the catalog's released versions at the start: %v", err)
return
}
if rv.recordedAtStart(ctx, all) {
if all, err = rv.r.All(ctx); err != nil {
rv.logf("the reservations are not held against the catalog's released versions at the start: %v", err)
return
}
}
read := map[string][]string{}
for _, v := range builtOf(all) {
if versions.NotStanding(v, true) != "" {
continue
}
released, ok := read[v.Module]
if !ok {
if released, err = rv.r.ReleasedOf(ctx, v.Module); err != nil {
rv.logf("%s: the catalog's released versions cannot be read at the start, so its built reservations wait for its next version-released: %v", v.Module, err)
}
read[v.Module] = released
}
if !slices.Contains(released, v.Version) {
continue
}
if err := rv.release(ctx, meshcatalog.VersionReleasedEvent{Module: v.Module, Version: v.Version}); err != nil {
rv.logf("%s %s is released in the catalog and not taken in at the start: %v", v.Module, v.Version, err)
continue
}
rv.logf("%s %s is released in the catalog: taken in at the start, as its version-released", v.Module, v.Version)
}
}
// recordedAtStart records the digests of every standing reservation that has none recorded and whose build key is done (design 47
// H2 H-A-492): a record its build's end lost. It answers whether one was recorded; one that cannot be is said.
func (rv *reservations) recordedAtStart(ctx context.Context, all []versions.ReservedVersion) bool {
if rv.recordAgain == nil {
return false
}
recorded := false
for _, v := range all {
if !v.BuiltAt.IsZero() || v.Fingerprint == "" || versions.NotStanding(v, true) != "" {
continue
}
version, err := rv.recordAgain(ctx, v.Module, v.Fingerprint, "at the builder's start")
if err != nil {
rv.logf("%v", err)
}
recorded = recorded || version != ""
}
return recorded
}
// 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.
@@ -404,33 +465,6 @@ func (rv *reservations) dropped(ctx context.Context, module, series, by, why str
return fmt.Sprintf("the reservation of %s %s is dropped (%s, %s)", module, series, by, why), nil
}
// tagged writes the git tag of a released version (design 47 G §370): on the catalog's version-released, through the seat
// git's verb tag, at the commit the reservation of that version was made from. A version with no reservation (a superseded
// build's version is never released, and the key of a version released by another builder is gone) or one that names no
// tag (a module with no Go package) is tagged nowhere. A tag the forge could not write is an error, the message heard again.
func (rv *reservations) tagged(ctx context.Context, ev meshcatalog.VersionReleasedEvent) error {
res, found, err := rv.r.Of(ctx, ev.Module, ev.Version)
if err != nil {
return fmt.Errorf("the reservation of %s %s cannot be read to tag it: %w", ev.Module, ev.Version, err)
}
if !found || res.Tag == "" || res.Commit == "" {
return nil
}
raw, err := rv.call("seat:"+git.Seat+".tag", git.TagInput{Repository: res.Repository, Commit: res.Commit, Tag: res.Tag})
if err != nil {
return fmt.Errorf("the tag %s of %s is not written: %w", res.Tag, ev.Module, err)
}
var a git.TagAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return fmt.Errorf("the git seat answered what is no tag answer for %s: %w", res.Tag, err)
}
if a.Error != "" || !a.Performed {
return fmt.Errorf("the tag %s of %s is not written: %s (%s)", res.Tag, ev.Module, a.Error, a.ErrorKind)
}
rv.logf("%s is tagged %s at %s", ev.Module, res.Tag, res.Commit)
return nil
}
// 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 {
@@ -502,19 +536,6 @@ func (rv *reservations) heldElsewhere(ctx context.Context, module, why string) {
needs: "builder_reserved shows the reservation and its withdrawn numbers; the registry seat's versions shows what it holds."})
}
// taggedElsewhere raises version-tagged-elsewhere about module (design 47 H2 §796): numbers whose git tag stands at another
// commit were skipped at reserving; a tag is never moved. Cleared at the module's next version-released.
func (rv *reservations) taggedElsewhere(ctx context.Context, module string, skipped []string) {
why := "the tags of " + strings.Join(skipped, ", ") + " stand at another commit, so the reserve skipped them"
rv.logf("%s: %s", module, why)
rv.found.raise(ctx, finding{kind: versions.VersionTaggedElsewhere, scope: meshconditionsclient.ScopeModule, id: module,
summary: module + ": " + why,
headline: "A number whose tag stands at another commit is not used",
explanation: "The repository holds a tag of " + module + " at a commit other than the build's: " + why + ". A tag is never moved.",
resolved: "The catalog says version-released for " + module + ".",
needs: "builder_reserved shows the reservation; the seat git's tags shows each tag with its commit."})
}
// 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
@@ -156,89 +156,117 @@ func TestTheCatalogsWordsMoveTheReservations(t *testing.T) {
}
}
// TestAReleasedVersionIsTaggedAtTheCommitItWasBuiltFrom: design 47 G §370 — the git tag go/vMAJOR.MINOR.PATCH is written through
// the seat git's tag on the catalog's version-released, at the commit the version's reservation was made from; a module with no
// Go package, and a version never released (a superseded build's), are tagged nowhere; a tag the forge did not write leaves
// version-released to be heard again with the reservation standing.
func TestAReleasedVersionIsTaggedAtTheCommitItWasBuiltFrom(t *testing.T) {
// TestAReleasedVersionWritesNoTag: design 47 H2 H-A-494 — the builder writes no git tag at a release, and numbers a series from the
// catalog's versions and the registries' alone: the catalog's version-released releases the reservation with no call of the seat
// git, a reservation written before (one naming a tag) included; the start's take-in of a version the catalog holds released
// (H-A-484 c) the same; and a reserve reads no git tag, a tag standing at another commit no reason to skip a number.
func TestAReleasedVersionWritesNoTag(t *testing.T) {
ctx := context.Background()
var tags []git.TagInput
refuse := ""
var standing []git.Tag // the tags the seat git's tags answers (design 47 H2 §796)
var gitCalls []string // every call of the seat git: none is made
var catalog []meshcatalog.VersionEntry // the released versions the catalog's verb versions answers
call := func(addr string, body any) (json.RawMessage, error) {
switch addr {
case "seat:git.tags":
return json.Marshal(map[string]any{"form": 2, "tags": standing, "a-field-of-a-later-form": true})
case "seat:git.tag":
default:
return json.Marshal(meshcatalog.VersionsAnswer{})
if strings.HasPrefix(addr, "seat:git.") {
gitCalls = append(gitCalls, addr)
if addr == "seat:git.tags" { // a tag standing at another commit, as the forge may still hold one
return json.Marshal(map[string]any{"form": 2, "tags": []git.Tag{{Tag: "go/v0.2.0", Commit: "elsewhere"}}})
}
return json.Marshal(git.TagAnswer{Performed: true})
}
tags = append(tags, body.(git.TagInput))
return json.Marshal(git.TagAnswer{Performed: refuse == "", Error: refuse})
return json.Marshal(meshcatalog.VersionsAnswer{Versions: catalog})
}
fw := &memFindings{vals: map[string][]byte{}}
found := &findings{module: builds.BuilderModule, w: fw, logf: t.Logf, now: func() time.Time { return time.Unix(0, 0) }}
rv := newReservations(&memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}, call, func() jetstream.KeyValue { return &boundsKV{keys: map[string]bool{}} }, found, nil, t.Logf)
store := &memReserve{vals: map[string][]byte{}, revs: map[string]uint64{}}
rv := newReservations(store, call, func() jetstream.KeyValue { return &boundsKV{keys: map[string]bool{}} }, found, nil, t.Logf)
rv.filled.Store(true)
// Design 47 H2 §796: the tag names the Go module's directory, read from its module path: mesh-sdk's `go` here.
rv.r.Names = func(_ context.Context, module, artifact string) (string, bool, error) {
return "git.example/o/r/go", artifact == "lib" || artifact == "pkg", nil
rv.names = func(_ context.Context, _, artifact string) (string, bool, error) {
return "git.example/o/r/go", artifact == "lib", nil
}
goPkg := versions.Source{Repository: "o/r", Commit: "c0ffee", GoPackage: true, GoArtifact: "lib"}
if _, err := rv.Reserve(ctx, "pkg", "0.1", []string{"pkg:lib"}, goPkg); err != nil {
t.Fatal(err)
}
if _, err := rv.Reserve(ctx, "prog", "2.0", []string{"prog:bin"}, versions.Source{Repository: "o/p", Commit: "beef"}); err != nil {
t.Fatal(err)
goPkg := versions.Source{Repository: "o/r", Commit: "c0ffee", Fingerprint: "fpA"}
// oldRecord rewrites a reservation as one written before H-A-494, naming the tag its release was to be written as.
oldRecord := func(module, series, tag string) {
key := versions.ReservedKey(module, series)
var v versions.ReservedVersion
if err := json.Unmarshal(store.vals[key], &v); err != nil {
t.Fatal(err)
}
v.Tag = tag
store.vals[key], _ = json.Marshal(v)
}
release := func(module, version string) *wakeMsg {
m := &wakeMsg{subject: meshcatalog.SubjectVersionReleased, data: []byte(`{"v":1,"module":"` + module + `","version":"` + version + `","source":1,"artifacts":[]}`)}
rv.heard(ctx, m)
return m
}
if m := release("prog", "2.0.0"); !m.acked || len(tags) != 0 {
t.Fatalf("a module with no Go package: acked %v, tags %v; want none written", m.acked, tags)
// The release path: a Go package's version-released releases it, acknowledged, with no tag written.
if v, err := rv.Reserve(ctx, "pkg", "0.1", []string{"pkg:lib"}, goPkg); err != nil || v.Tag != "" {
t.Fatalf("reserved %+v (%v), want a reservation naming no tag", v, err)
}
refuse = "forge down"
if m := release("pkg", "0.1.0"); !m.naked || m.acked {
t.Fatalf("a tag the forge did not write: naked %v acked %v; want the release heard again", m.naked, m.acked)
oldRecord("pkg", "0.1", "go/v0.1.0")
if m := release("pkg", "0.1.0"); !m.acked || m.naked {
t.Fatalf("the release: acked %v naked %v; want it acknowledged", m.acked, m.naked)
}
if all, _ := rv.r.All(ctx); len(all) != 1 {
t.Fatalf("the reservation went with an unwritten tag: %v", all)
if len(gitCalls) != 0 {
t.Errorf("the release called the seat git: %v; want no tag written", gitCalls)
gitCalls = nil
}
refuse = ""
tags = nil
if m := release("pkg", "0.1.0"); !m.acked || len(tags) != 1 || tags[0] != (git.TagInput{Repository: "o/r", Commit: "c0ffee", Tag: "go/v0.1.0"}) {
t.Fatalf("the release: acked %v, tags %+v; want go/v0.1.0 at c0ffee of o/r", m.acked, tags)
if all, _ := rv.r.All(ctx); len(all) != 0 {
t.Fatalf("the released version still stands: %v", all)
}
tags = nil
if _, err := rv.Reserve(ctx, "pkg", "0.1", []string{"pkg:lib"}, goPkg); err != nil { // build A: 0.1.0 (the stub catalog holds none released)
// The start check (H-A-484 c): a built reservation the catalog holds released is released at the start, no tag written; one
// not built, or not released, stands.
// Design 47 H2 H-A-492: at the start, a standing reservation with no digests recorded whose build key is done has them
// recorded (the builder's RecordAgain), and is then held against the released versions as a built one is.
if _, err := rv.Reserve(ctx, "rec", "0.1", []string{"rec:bin"}, versions.Source{Repository: "o/q", Commit: "abc", Fingerprint: "fpR"}); err != nil {
t.Fatal(err)
}
if v, err := rv.Reserve(ctx, "pkg", "0.1", []string{"pkg:lib"}, versions.Source{Repository: "o/r", Commit: "b0b", GoPackage: true, GoArtifact: "lib"}); err != nil || v.Version != "0.1.1" { // build B supersedes A
t.Fatalf("second build reserved %q (%v)", v.Version, err)
var recordedAt []string
rv.recordAgain = func(ctx context.Context, module, fp, when string) (string, error) {
recordedAt = append(recordedAt, module+" "+fp+" "+when)
_, err := rv.r.Built(ctx, module, "0.1.0", "rec:bin", "sha256:bb", nil) // its done key's digest
return "0.1.0", err
}
release("pkg", "0.1.0") // A's version is never released in fact; were it said, it is no reservation of the key
if len(tags) != 0 {
t.Fatalf("a superseded build's version was tagged: %+v", tags)
catalog = []meshcatalog.VersionEntry{{Module: "rec", Version: "0.1.0"}}
rv.releasedAtStart(ctx)
if _, standing, _ := rv.r.Of(ctx, "rec", "0.1.0"); standing || !slices.Equal(recordedAt, []string{"rec fpR at the builder's start"}) {
t.Fatalf("at the start, rec 0.1.0 unrecorded and released: standing %v, recorded %q; want it recorded once at the start and released", standing, recordedAt)
}
if release("pkg", "0.1.1"); len(tags) != 1 || tags[0].Commit != "b0b" {
t.Fatalf("the newer build's version: tags %+v; want go/v0.1.1 at b0b", tags)
catalog, rv.recordAgain = nil, nil
var ended []string
rv.released = func(_ context.Context, module, version string) { ended = append(ended, module+" "+version) }
if _, err := rv.Reserve(ctx, "pkg", "0.1", []string{"pkg:lib"}, versions.Source{Repository: "o/r", Commit: "b0b", Fingerprint: "fpB"}); err != nil {
t.Fatal(err) // 0.1.0 again: the stub catalog holds none released
}
// Design 47 H2 §796: a tag standing at another commit makes the next number and the finding version-tagged-elsewhere, which
// clears at the module's next version-released.
standing = []git.Tag{{Tag: "go/v0.2.0", Commit: "elsewhere"}, {Tag: "go/v0.2.1", Commit: "elsewhere"}}
if v, err := rv.Reserve(ctx, "pkg", "0.2", []string{"pkg:lib"}, goPkg); err != nil || v.Version != "0.2.2" || v.Tag != "go/v0.2.2" {
t.Fatalf("reserved %+v (%v) with 0.2.0 and 0.2.1 tagged elsewhere, want 0.2.2 tagged go/v0.2.2", v, err)
oldRecord("pkg", "0.1", "go/v0.1.0")
rv.releasedAtStart(ctx) // built nothing yet: nothing taken
if all, _ := rv.r.All(ctx); len(all) != 1 {
t.Fatalf("at the start with no build done: reservations %v; want the reservation standing", all)
}
if _, err := rv.r.Built(ctx, "pkg", "0.1.0", "pkg:lib", "sha256:aa", nil); err != nil {
t.Fatal(err)
}
rv.releasedAtStart(ctx) // the catalog holds none released: it stands
if all, _ := rv.r.All(ctx); len(all) != 1 {
t.Fatalf("at the start with nothing released: reservations %v; want the reservation standing", all)
}
catalog = []meshcatalog.VersionEntry{{Module: "pkg", Version: "0.1.0"}}
rv.releasedAtStart(ctx)
if all, _ := rv.r.All(ctx); len(all) != 0 || !slices.Equal(ended, []string{"pkg 0.1.0"}) {
t.Fatalf("at the start with 0.1.0 released: reservations %v, items ended %v; want it released and its item ended", all, ended)
}
if len(gitCalls) != 0 {
t.Errorf("the start check called the seat git: %v; want no tag written", gitCalls)
gitCalls = nil
}
catalog, rv.released = nil, nil
// Numbering reads no tag: the seat git would answer go/v0.2.0 at another commit, and 0.2.0 is reserved all the same.
if v, err := rv.Reserve(ctx, "pkg", "0.2", []string{"pkg:lib"}, goPkg); err != nil || v.Version != "0.2.0" || v.Tag != "" || len(gitCalls) != 0 {
t.Errorf("reserved %+v (%v), git calls %v; want 0.2.0 naming no tag, no git tag read", v, err, gitCalls)
}
key := meshconditionsclient.Key(meshconditionsclient.ScopeModule, "pkg", versions.VersionTaggedElsewhere)
if got, err := decodeFinding(fw.vals[key]); err != nil || !strings.Contains(got.Summary, "0.2.0") || !strings.Contains(got.Summary, "0.2.1") {
t.Fatalf("the finding %s = %+v (%v), want it naming 0.2.0 and 0.2.1", key, got, err)
if fw.vals[key] != nil {
t.Errorf("a reserve raised %s", key)
}
if release("pkg", "0.2.2"); fw.vals[key] != nil {
t.Errorf("version-released of pkg left %s standing", key)
}
standing = nil
// Design 47 H2 §805, H-A-420 (2): a package's number newly reserved is said as version-reserved, its path the package's name
// and its revision the indexer's `<branch>.<n>`; a reservation kept as it stood, an artifact that is no package and a
// reservation naming no catalog revision say none.
@@ -247,7 +275,7 @@ func TestAReleasedVersionIsTaggedAtTheCommitItWasBuiltFrom(t *testing.T) {
return "git.example/o/r/" + artifact, module == "lib2" && artifact == "pkg", nil
}
rv.sayReserved = func(_ context.Context, ev meshbuilds.VersionReservedEvent) error { said = append(said, ev); return nil }
at := versions.Source{Repository: "o/r", Commit: "c1", Fingerprint: "src2:l2", GoPackage: true, GoArtifact: "pkg", Branch: "main", CatalogRevision: 158}
at := versions.Source{Repository: "o/r", Commit: "c1", Fingerprint: "src2:l2", Branch: "main", CatalogRevision: 158}
for range 2 {
if _, err := rv.Reserve(ctx, "lib2", "0.3", []string{"lib2:pkg", "lib2:bin"}, at); err != nil {
t.Fatal(err)
@@ -19,6 +19,8 @@ import (
// `module` alone the module's keys newest first, at most MostBuilds, each with its fingerprint whole, its state, revision and
// since when, its step and node, its error whole, event-builds and the open ask (§568), and `newest` naming each watched branch
// whose newest catalog graph entry of the module names that fingerprint, read from the catalog half by the tools bundle.
// **Each key's time is its entry's own write time** (design 47 H2 H-A-487): the history of a key is read only for the one key a
// fingerprint names, when its entry does not say when it was written, and a listing cut at MostBuilds says so in its note.
// BuildTool is the builder's read tool of a module's build keys.
const BuildTool = "builder_build"
@@ -56,14 +58,16 @@ type BuildAnswer struct {
Builds []BuildRow `json:"builds"`
// Newest is the fingerprint of the module's newest catalog graph entry on each watched branch.
Newest map[string]string `json:"newest-entries,omitempty"`
// Note says what no key shows: that none of the keys is the newest entry's, naming its fingerprint.
// Note says what no key shows: that none of the keys is the newest entry's, naming its fingerprint, and that the listing
// was cut at MostBuilds (H-A-487).
Note string `json:"note,omitempty"`
}
// BuildReader reads what builder_build answers.
type BuildReader struct {
Builds StateRead
// Entry is a key's value with its revision and when it was written; nil leaves both out.
// Entry is a key's value with its revision and when it was written, the entry's own write time (H-A-487); nil leaves both
// out. Builds.Written, the key's history, is read only for the key a fingerprint names when Entry says no time.
Entry func(key string) (json.RawMessage, uint64, time.Time, error)
// Asked is the builder's state asked, which holds the asks the operator was asked.
Asked StateRead
@@ -96,6 +100,9 @@ func (r *BuildReader) Build(module, fingerprint string) (BuildAnswer, error) {
if raw == nil {
continue
}
if at.IsZero() && fingerprint != "" && r.Builds.Written != nil {
at = r.Builds.Written(key) // one key's history, never every key's (H-A-487)
}
v, err := builds.DecodeBuilderBuild(raw)
if err != nil {
return out, fmt.Errorf("%s holds what is not a build: %w", key, err)
@@ -118,7 +125,9 @@ func (r *BuildReader) Build(module, fingerprint string) (BuildAnswer, error) {
}
return rows[i].Key > rows[j].Key
})
var cut string
if len(rows) > MostBuilds {
cut = fmt.Sprintf("%d of %s's %d build keys are answered, the newest by write time; name a fingerprint for another", MostBuilds, module, len(rows))
rows = rows[:MostBuilds]
}
asks := r.openAsks()
@@ -149,6 +158,9 @@ func (r *BuildReader) Build(module, fingerprint string) (BuildAnswer, error) {
out.Note = "no build key of " + module + " is the newest entry's: " + strings.Join(says, "; ")
}
}
if cut != "" {
out.Note = strings.TrimPrefix(out.Note+"; "+cut, "; ")
}
out.Builds = append(out.Builds, rows...)
return out, nil
}
@@ -2,6 +2,7 @@ package build
import (
"encoding/json"
"fmt"
"sort"
"strings"
"testing"
@@ -66,6 +67,31 @@ func TestBuilderBuildAnswersAModulesKeysWhole(t *testing.T) {
if n, err := r.Build("m", ""); err != nil || !strings.Contains(n.Note, "no build key of m is the newest entry's") || !strings.Contains(n.Note, "main names src2:"+strings.Repeat("c", 64)) {
t.Errorf("a module none of whose keys the newest entry names: %+v, %v", n, err)
}
// H-A-487: a module of 100 keys is read by each entry's own write time, no key's history read, and the listing is cut at the
// 20 newest, saying so; a fingerprint's key with no time in its entry has its one history read.
many, at := map[string][]byte{}, map[string]time.Time{}
base := time.Date(2026, 11, 22, 20, 0, 0, 0, time.UTC)
for i := range 100 {
k, _ := builds.BuilderBuildKey("big", fmt.Sprintf("src2:%064x", i))
many[k], at[k] = done, base.Add(time.Duration(i)*time.Minute)
}
histories := 0
st := stateOf(many)
st.Written = func(string) time.Time { histories++; return base }
big := &BuildReader{Builds: st, Entry: func(k string) (json.RawMessage, uint64, time.Time, error) { return many[k], 1, at[k], nil }}
a, err = big.Build("big", "")
if err != nil || len(a.Builds) != MostBuilds || !a.Builds[0].Since.Equal(base.Add(99*time.Minute)) || histories != 0 ||
!strings.Contains(a.Note, "20 of big's 100 build keys are answered") {
t.Fatalf("100 keys: %d rows, newest %v, %d histories read, note %q; want the 20 newest, no history, the cut said", len(a.Builds), a.Builds[0].Since, histories, a.Note)
}
big.Entry = func(k string) (json.RawMessage, uint64, time.Time, error) { return many[k], 1, time.Time{}, nil }
if a, err := big.Build("big", ""); err != nil || len(a.Builds) != MostBuilds || histories != 0 {
t.Fatalf("100 keys with no time in their entries: %d rows (%v), %d histories read; want no history read for a listing", len(a.Builds), err, histories)
}
if one, err := big.Build("big", fmt.Sprintf("src2:%064x", 7)); err != nil || len(one.Builds) != 1 || !one.Builds[0].Since.Equal(base) || histories != 1 {
t.Errorf("one fingerprint with no time in its entry: %+v (%v), %d histories; want its one history read", one, err, histories)
}
}
// Design 47 G §589: builder_stuck answers each key's fingerprint whole, as the build-input fingerprint the catalog graph entry carries it.
@@ -170,6 +170,7 @@ func Unreferenced(b builds.BuilderBuild) bool {
// clause 2, ADR 0498 clauses 4 and 5) or for digests that differ (buildrun.DigestsDifferPrefix, clause 4),
// which wait for another fingerprint, and one failed for want of an image builder (NoImageBuilderPrefix), which waits for
// another fingerprint or a node that runs the image build module (ClaimOptions.ImageBuilder);
// - a failed key withdrawn (withdrawnPrefix) is final for its fingerprint, taken again only by a person's build again (H-A-489);
// - a key queued waiting for a package version (Waits) is claimed building as a new revision once that version is
// published (ClaimOptions.Published, ADR 0500 clause 6), and not before;
// - a key left queued or building by this builder is taken as it stands (ADR 0478 clause 5: a stopped builder takes its
@@ -229,6 +230,8 @@ func (c Claimer) Claim(ctx context.Context, module, fingerprint, manifest string
return nil, nil
case cur.State == builds.BuildFailed && (builds.FailedUntilChanged(cur.Error) || strings.HasPrefix(cur.Error, buildrun.DigestsDifferPrefix)):
return nil, nil
case cur.State == builds.BuildFailed && strings.HasPrefix(cur.Error, withdrawnPrefix) && !opt.ByHand:
return nil, nil // withdrawn is final for its fingerprint: no look builds it again (H-A-489)
case cur.State == builds.BuildFailed && builds.FailedOnTransportFault(cur.Error) && !opt.ByHand && !opt.TakeOver && !opt.ByEvent:
return nil, nil
case cur.State == builds.BuildFailed && strings.HasPrefix(cur.Error, NoImageBuilderPrefix) && (opt.ImageBuilder == nil || !opt.ImageBuilder()):
@@ -106,11 +106,19 @@ func (b *Builder) doneDigests(ctx context.Context, module, fp string) map[string
return nil
}
raw, _, found, err := b.Claimer.Store.Get(ctx, key)
if err != nil || !found {
if err != nil {
b.logf("%s: the build key cannot be read, so it is taken as not done: %v", key, err)
return nil
}
if !found {
return nil
}
cur, err := builds.DecodeBuilderBuild(raw)
if err != nil || cur.State != builds.BuildDone {
if err != nil {
b.logf("%s: the build key holds what is no build, so it is taken as not done: %v", key, err)
return nil
}
if cur.State != builds.BuildDone {
return nil
}
out := map[string]string{}
@@ -122,6 +130,57 @@ func (b *Builder) doneDigests(ctx context.Context, module, fp string) map[string
return out
}
// DefaultRecordBound is the bound of the record of a reservation's digests, its setting record-bound-seconds' default (design 47
// H2 H-A-492).
const DefaultRecordBound = time.Minute
// recordContext is the context a reservation's digests are recorded under: ctx's values with no cancel of its own, bounded by
// RecordBound (design 47 H2 H-A-492), so a takeover or an end cancelling the build cannot cancel the record.
func (b *Builder) recordContext(ctx context.Context) (context.Context, context.CancelFunc) {
bound := b.RecordBound
if bound <= 0 {
bound = DefaultRecordBound
}
return context.WithTimeout(context.WithoutCancel(ctx), bound)
}
// RecordAgain records the digests of fp's done build under its standing reservation when its end did not record them (design 47
// H2 H-A-492): at the builder's look of the key and at its start (when says which), said each time. It answers the version
// recorded, "" when nothing was to be recorded: the key is not done, no reservation stands for fp, or it is recorded already.
func (b *Builder) RecordAgain(ctx context.Context, module, fp, when string) (string, error) {
b.init()
if b.Reserved == nil {
return "", nil
}
digests := b.doneDigests(ctx, module, fp)
if digests == nil {
return "", nil
}
res, ok, err := b.Reserved.ReservedFor(ctx, module, fp)
if err != nil {
return "", fmt.Errorf("%s at %s: whether its done build's digests are recorded cannot be read %s: %w", module, fp, when, err)
}
if !ok || !res.BuiltAt.IsZero() || len(res.Artifacts) == 0 || versions.NotStanding(res, true) != "" {
return "", nil
}
refs := map[string]string{}
for ref := range res.Artifacts {
_, artifact, _ := strings.Cut(ref, ":")
d, have := digests[artifact]
if !have {
return "", fmt.Errorf("%s at %s: the digests of %s are not recorded, and the done key holds no digest of %s to record %s", module, fp, res.Version, ref, when)
}
refs[ref] = d
}
rec, stop := b.recordContext(ctx)
defer stop()
if err := b.Reserved.Built(rec, module, res.Version, refs, nil); err != nil {
return "", fmt.Errorf("%s at %s: the digests of %s are not recorded %s either: %w", module, fp, res.Version, when, err)
}
b.logf("%s at %s: the digests of %s were not recorded at its build's end: recorded %s from the done key", module, fp, res.Version, when)
return res.Version, nil
}
// PackageNamed looks at a module again when the indexer's packages state names a name for one of its packages
// (versions.NamedModule): a done trunk build that left the package unnumbered, its name not known at its claim, is
// numbered then with the done build's digests, and version.numbered says them for its build module's late publish.
@@ -199,8 +258,8 @@ func (b *Builder) reserve(ctx context.Context, module string, m meshcatalog.Modu
}
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 {
if t.Kind == catalogue.ArtifactPackage && t.Language == "go" && !src.GoPackage {
src.GoPackage, src.GoArtifact = true, t.Artifact // its module path names its tag's directory (design 47 H2 §796)
if t.Kind == catalogue.ArtifactUpstream {
src.Upstream = append(src.Upstream, module+":"+t.Artifact) // copied by its pin, never awaited (H-A-486)
}
}
res, err := b.Reserved.Reserve(ctx, module, plan.Series, refs, src)
@@ -32,6 +32,8 @@ type fakeReservations struct {
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)
held map[string]versions.ReservedVersion // by fingerprint, the reservation ReservedFor answers as it stands (H-A-492)
lost error // the record of the digests fails, as a store refusing it would
}
func (f *fakeReservations) TakenOver(_ context.Context, _, fp string) (versions.ReservedVersion, bool, error) {
@@ -46,6 +48,9 @@ func (f *fakeReservations) ReleasedFor(_ context.Context, _, fp string) (bool, e
func (f *fakeReservations) Filled() bool { return f.filled }
func (f *fakeReservations) ReservedFor(_ context.Context, _, fp string) (versions.ReservedVersion, bool, error) {
if v, ok := f.held[fp]; ok {
return v, true, nil
}
for _, s := range f.sources {
if s.Fingerprint == fp {
return versions.ReservedVersion{Version: "held"}, true, nil
@@ -65,7 +70,13 @@ func (f *fakeReservations) Reserve(_ context.Context, module, series string, art
return versions.ReservedVersion{Module: module, Series: series, Version: series + ".5"}, nil
}
func (f *fakeReservations) Built(_ context.Context, _, version string, digests map[string]string, deps map[string][]meshbuilds.Dependency) error {
func (f *fakeReservations) Built(ctx context.Context, _, version string, digests map[string]string, deps map[string][]meshbuilds.Dependency) error {
if err := ctx.Err(); err != nil {
return err // the state's write runs under ctx: a cancelled one records nothing
}
if f.lost != nil {
return f.lost
}
f.deps = deps
f.built = map[string]string{version: ""}
for ref, d := range digests {
@@ -118,6 +129,13 @@ func TestABuildReservesItsVersionAtItsStartOnceTheCatalogFilled(t *testing.T) {
if res.built["m:tool"] != digest || len(res.built) != 2 {
t.Errorf("recorded %v, want the digest of m:tool under the reserved version", res.built)
}
// H-A-486: an upstream artifact is reserved for the record and named as upstream, so its publish is never awaited.
up := &fakeReservations{filled: true}
plan := Plan{Series: "0.1", Tasks: []Task{{Artifact: "server", Kind: catalogue.ArtifactUpstream}, {Artifact: "tools", Kind: catalogue.ArtifactBundle}}}
if _, ok := (&Builder{Reserved: up}).reserve(context.Background(), "nats", meshcatalog.ModulesByModuleValue{Fp2: "f"}, plan, Origin{}, false); !ok ||
!slices.Equal(up.reserved[0], []string{"nats:server", "nats:tools"}) || !slices.Equal(up.sources[0].Upstream, []string{"nats:server"}) {
t.Errorf("an upstream artifact reserved %v from %+v, want both refs reserved and nats:server named upstream", up.reserved, up.sources)
}
r.consider(t, "modules/m")
if len(res.reserved) != 1 {
t.Errorf("a done key reserved again: %v", res.reserved)
@@ -146,6 +164,97 @@ func TestABuildReservesItsVersionAtItsStartOnceTheCatalogFilled(t *testing.T) {
}
}
// TestAVersionsDigestsAreRecordedUnderTheBuildersOwnBound: design 47 H2 H-A-492 — the record of a reservation's digests after a
// build ends runs under the builder's own bound, so a build context cancelled at its end still records; a done build whose
// digests are not recorded is recorded at the builder's next look, said.
func TestAVersionsDigestsAreRecordedUnderTheBuildersOwnBound(t *testing.T) {
manifest := catalogue.Manifest{Module: "m", Version: "0.1", Build: &catalogue.Build{Artifacts: []catalogue.Artifact{goBundle}}}
t.Run("a build's context cancelled at its end still records", func(t *testing.T) {
r := newRig(t, goBundle)
r.mf.byDigest[mdigest('a')] = manifest
res := &fakeReservations{filled: true}
r.b.Reserved = res
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
r.b.Ended = func(context.Context, string) { cancel() } // a takeover or the builder's end, once the key is written
r.b.Module(ctx, "m", moduleValue(t, "modules/m"))
r.b.Wait()
if v := valueOf(t, r.st, r.key); v.State != builds.BuildDone {
t.Fatalf("build = %+v, want done", v)
}
if res.built["m:tool"] != digest {
t.Errorf("recorded %v, want the digest of m:tool under 0.1.5 though the build's context ended", res.built)
}
})
t.Run("the record's bound is the setting record-bound-seconds, never the build's", func(t *testing.T) {
build, cancel := context.WithCancel(context.Background())
cancel()
for _, c := range []struct {
bound, want time.Duration
}{{0, DefaultRecordBound}, {5 * time.Second, 5 * time.Second}} {
rec, stop := (&Builder{RecordBound: c.bound}).recordContext(build)
deadline, has := rec.Deadline()
stop()
if left := time.Until(deadline); !has || left > c.want || left < c.want-time.Second {
t.Errorf("RecordBound %v: the record's context has deadline %v (%v left, %v), want %v left of its own", c.bound, deadline, left, has, c.want)
}
}
rec, stop := (&Builder{}).recordContext(build)
defer stop()
if rec.Err() != nil {
t.Errorf("the record's context ended with the build's: %v", rec.Err())
}
})
t.Run("a build key that cannot be read is said, not taken silently", func(t *testing.T) {
var journal []string
b := &Builder{Claimer: Claimer{Store: unreadable{newMem()}}, Logf: func(f string, a ...any) { journal = append(journal, fmt.Sprintf(f, a...)) }}
if d := b.doneDigests(context.Background(), "m", fp1); d != nil {
t.Errorf("an unreadable key answered digests %v", d)
}
if !slices.ContainsFunc(journal, func(l string) bool {
return strings.Contains(l, "cannot be read") && strings.Contains(l, "bus timeout")
}) {
t.Errorf("journal %q, want a line saying the build key cannot be read, with why", journal)
}
})
t.Run("a done key whose digests are not recorded is recorded at the next look", func(t *testing.T) {
r := newRig(t, goBundle)
r.mf.byDigest[mdigest('a')] = manifest
res := &fakeReservations{filled: true, lost: errors.New("context canceled")}
r.b.Reserved = res
var journal []string
r.b.Logf = func(f string, a ...any) { journal = append(journal, fmt.Sprintf(f, a...)) }
if v := r.consider(t, "modules/m"); v.State != builds.BuildDone || res.built != nil {
t.Fatalf("build %s recorded %v, want done and nothing recorded", v.State, res.built)
}
res.lost = nil
res.held = map[string]versions.ReservedVersion{fp1: {Module: "m", Series: "0.1", Version: "0.1.5", Fingerprint: fp1, Artifacts: map[string]string{"m:tool": ""}}}
r.consider(t, "modules/m")
if res.built["m:tool"] != digest || len(res.built) != 2 {
t.Errorf("recorded %v at the next look, want the done key's digest of m:tool under 0.1.5", res.built)
}
if !slices.ContainsFunc(journal, func(l string) bool {
return strings.Contains(l, "0.1.5 were not recorded") && strings.Contains(l, "recorded at a look")
}) {
t.Errorf("journal %q, want a line saying 0.1.5's digests were recorded at a look", journal)
}
// Recorded once: a reservation whose build ended recorded is left.
res.built = nil
res.held[fp1] = versions.ReservedVersion{Module: "m", Series: "0.1", Version: "0.1.5", Fingerprint: fp1, Artifacts: map[string]string{"m:tool": digest}, BuiltAt: time.Unix(1, 0)}
r.consider(t, "modules/m")
if res.built != nil {
t.Errorf("a recorded reservation was recorded again: %v", res.built)
}
})
}
// unreadable is a builds bucket whose reads fail, as one on a bus that does not answer.
type unreadable struct{ *memStore }
func (unreadable) Get(context.Context, string) ([]byte, uint64, bool, error) {
return nil, 0, false, errors.New("bus timeout")
}
// TestADropOfAReservationIsAReasksValueOfItsOwnKey: design 47 G §369 — builder_reserved_drop asks the builder through
// reasks, under a key of the reservation (never a build key), refusing a module with no MAJOR.MINOR or no why.
func TestADropOfAReservationIsAReasksValueOfItsOwnKey(t *testing.T) {
@@ -236,7 +345,7 @@ func TestAReservedBuildKeepsWhatItsStepResolvedAndWasBuiltWith(t *testing.T) {
// TestAModuleWhoseOnlyArtifactIsAGoPackageIsBuiltUnderItsReservedVersion: design 47 G §370 — a module whose one artifact is
// a Go package (mesh-wireguard's go-overlay) is planned on the Go build seat, its ask carries the reserved version and names
// the seat go-package-registry the package is published and tagged through, and the build is done; a build reserving none
// the seat go-package-registry the package is published through, and the build is done; a build reserving none
// names no seat.
func TestAModuleWhoseOnlyArtifactIsAGoPackageIsBuiltUnderItsReservedVersion(t *testing.T) {
goPackage := catalogue.Artifact{Name: "go-overlay", Kind: catalogue.ArtifactPackage, Language: "go", Paths: []string{"go"}}
@@ -265,10 +374,6 @@ func TestAModuleWhoseOnlyArtifactIsAGoPackageIsBuiltUnderItsReservedVersion(t *t
len(asked[0].Build.Artifacts) != 1 || asked[0].Build.Artifacts[0] != (buildstep.AskArtifact{Artifact: "go-overlay", Seat: c.seat}) {
t.Fatalf("asks %+v, want one Go ask with version %q naming go-overlay on seat %q", asked, c.version, c.seat)
}
// Design 47 H2 §796: the reservation names the Go package's artifact, whose module path names its tag's directory.
if c.version != "" && (len(res.sources) != 1 || !res.sources[0].GoPackage || res.sources[0].GoArtifact != "go-overlay") {
t.Errorf("reserved from %+v, want one source naming the Go package go-overlay", res.sources)
}
})
}
}
@@ -107,7 +107,9 @@ func (b *Builder) keptRevisionHolds(ctx context.Context, run meshbuilds.StepRun,
}
}
// 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.
// took in does; what the picture heard stays as it is, so the newer fingerprint's build is not superseded. Once the picture
// heard a newer entry of the module on the first branch, H-A-489 overrides H-A-205: the older fingerprint is refused
// superseded (buildEntry), never built or reserved.
b.mu.Lock()
for _, e := range run.Entries {
key, err := builds.BuilderBuildKey(e.Module, e.Fingerprint)
@@ -127,6 +127,9 @@ type Builder struct {
// 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
// RecordBound bounds the record of a reservation's digests after a build ends, its setting record-bound-seconds (design 47
// H2 H-A-492): the builder's own bound, never the build's context; DefaultRecordBound when 0.
RecordBound 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)
@@ -177,6 +180,8 @@ type Builder struct {
// 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
// supersededSaid are the build keys refused as superseded (H-A-489), so each is said once.
supersededSaid sync.Map
}
type planned struct {
@@ -310,11 +315,49 @@ func (b *Builder) take(ctx context.Context, o Origin, key string, m meshcatalog.
if superseded != nil {
// A newer fingerprint of the module: the build of the older one in flight is taken out, and its asks are withdrawn
// from the build seats (ADR 0664 §4).
superseded(buildrun.Withdrawn{Why: "the build of " + key + " at " + old.Fp2 + " was superseded by the fingerprint " + m.Fp2})
superseded(buildrun.Withdrawn{Why: supersededWhy(key, old.Fp2, m.Fp2)})
}
b.consider(ctx, key, m)
}
// supersededWhy is the words of a build withdrawn because a newer fingerprint of its module superseded it.
func supersededWhy(module, fp, newer string) string {
return "the build of " + module + " at " + fp + " was superseded by the fingerprint " + newer
}
// withdrawnPrefix opens the error of a key whose build was withdrawn (H-A-225, ADR 0664 §4). It is final for its fingerprint
// (H-A-489): no look builds it again; a person's build again does.
const withdrawnPrefix = "withdrawn: "
// supersededBy is the fingerprint that supersedes fp, a fingerprint of module whose build key is key, when fp is of its
// registration's first watched branch and is no longer the newest entry heard on that branch (H-A-489); "" otherwise. A key no
// entry named is of the first branch, as originOf has it.
func (b *Builder) supersededBy(module, key, fp string) string {
b.mu.Lock()
defer b.mu.Unlock()
o, ok := b.origin[key]
if !ok {
o = Origin{First: true}
}
if !o.First {
return ""
}
newest, heard := b.heard[o.Branch+"\x00"+module]
if !heard || newest.Fp2 == "" || newest.Fp2 == fp {
return ""
}
return newest.Fp2
}
// saySuperseded says, once per key, that the build of fp is refused as superseded by newer (H-A-489), and gives the words.
func (b *Builder) saySuperseded(module, key, fp, newer string) string {
why := "is not built: superseded by " + newer + ", the newest entry heard on its first branch"
if _, said := b.supersededSaid.LoadOrStore(key, true); !said {
b.logf("%s at %s: %s", module, fp, why)
}
return why
}
// 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 when every artifact names them.
@@ -637,6 +680,12 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
whyEnded = fmt.Sprintf(format, args...)
b.logf("%s at %s: %s", module, m.Fp2, whyEnded)
}
// A fingerprint no longer the newest entry heard on its first branch is neither reserved for nor built (H-A-489): two
// fingerprints of one module never take the series from each other.
if newer := b.supersededBy(module, key, m.Fp2); newer != "" {
whyEnded = b.saySuperseded(module, key, m.Fp2, newer)
return
}
plan, planErr, read := b.planOf(ctx, m.Manifest)
var noModule *NoBuildModule
if errors.As(planErr, &noModule) {
@@ -680,6 +729,12 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
}
// Only a build of the registration's first watched branch reserves and releases a version (design 47 G §371).
reserving := trunk && b.originOf(key).First && planErr == nil && !nothing && b.reserves(ctx, module, m, plan)
if trunk && b.originOf(key).First && planErr == nil && !nothing && !reserving {
// A done build whose digests its end did not record is recorded at the next look (design 47 H2 H-A-492).
if _, err := b.RecordAgain(ctx, module, m.Fp2, "at a look"); err != nil {
b.logf("%v", err)
}
}
if reserving && b.waitFill(module, m) {
end("is not built yet: wait-held, the catalog has not said versions-filled")
return
@@ -727,7 +782,7 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
}
}
var reserved versions.ReservedVersion
hasReserved := false
hasReserved, supersededNow := false, ""
if rebuild && cl.Build.State == builds.BuildBuilding {
// 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
@@ -737,10 +792,16 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
}
reserving = true
} else if reserving && cl.Build.State != builds.BuildDone {
reserved, hasReserved = b.reserve(ctx, module, m, plan, b.originOf(key), false)
// Looked at again just before it reserves (H-A-489): a newer entry heard since the claim is not taken over.
if supersededNow = b.supersededBy(module, key, m.Fp2); supersededNow == "" {
reserved, hasReserved = b.reserve(ctx, module, m, plan, b.originOf(key), false)
}
}
var result builds.BuilderBuild
if reserving && !hasReserved && cl.Build.State != builds.BuildDone {
if supersededNow != "" {
// Ended as the newer entry's take-in withdraws a build in flight: final for this fingerprint.
result = builds.BuilderBuild{State: builds.BuildFailed, Error: keyError([]string{withdrawnPrefix + supersededWhy(module, m.Fp2, supersededNow)})}
} else if reserving && !hasReserved && cl.Build.State != builds.BuildDone {
// A trunk build that reserves is never built without its version: it would end done and publish nothing, and its key would
// stay done, never built again (A-490). The key fails with why and is taken again at the next look or by builder_build_again.
result = failed("no version is reserved for this build: the builder's journal says why, and it is built again once one can be")
@@ -765,7 +826,7 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
var w buildrun.Withdrawn
if ctx.Err() == nil && errors.As(context.Cause(run), &w) {
// Taken out, not stopped: the key says so, and the asks are withdrawn (the asker dropped them).
result = builds.BuilderBuild{State: builds.BuildFailed, Error: keyError([]string{"withdrawn: " + w.Why})}
result = builds.BuilderBuild{State: builds.BuildFailed, Error: keyError([]string{withdrawnPrefix + w.Why})}
}
}
if ctx.Err() != nil {
@@ -807,8 +868,13 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
for _, a := range result.Artifacts {
digests[module+":"+a.Name] = a.Digest
}
if err := b.Reserved.Built(ctx, module, reserved.Version, digests, b.takeDependencies(key)); err != nil {
b.logf("%s: the digests of %s are not recorded: %v", cl.Key, reserved.Version, err)
// Under the builder's own bound, never the build's context: a takeover or an end that cancels it no longer leaves a passed
// build unrecorded, so unreleased (design 47 H2 H-A-492).
rec, stop := b.recordContext(ctx)
err := b.Reserved.Built(rec, module, reserved.Version, digests, b.takeDependencies(key))
stop()
if err != nil {
b.logf("%s: the digests of %s are not recorded: %v; recorded again at the builder's next look or start", cl.Key, reserved.Version, err)
}
}
if result.State == builds.BuildFailed {
@@ -333,8 +333,9 @@ func TestAWithdrawnBuildEndsWithdrawn(t *testing.T) {
r := newRig(t, goBundle)
asked, release := make(chan struct{}), make(chan struct{})
answer := r.answer
var once sync.Once
r.asks.Answer = func(a buildstep.StepAsk) buildstep.Step {
close(asked)
once.Do(func() { close(asked) })
<-release
return answer(a)
}
@@ -356,6 +357,85 @@ func TestAWithdrawnBuildEndsWithdrawn(t *testing.T) {
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)
}
// H-A-489: withdrawn is final for the fingerprint: a later look builds it not again; a person's build again does.
n, rev := len(r.asks.Asks()), r.st.revs[r.key]
r.b.Reconsider(context.Background())
r.b.Wait()
if v := valueOf(t, r.st, r.key); len(r.asks.Asks()) != n || r.st.revs[r.key] != rev || !strings.HasPrefix(v.Error, "withdrawn: ") {
t.Errorf("a later look built the withdrawn key again: %d asks (was %d), the key %+v", len(r.asks.Asks()), n, v)
}
if cl, err := r.b.Claimer.Claim(context.Background(), "m", fp1, mdigest('a'), ClaimOptions{ByHand: true}); err != nil || cl == nil {
t.Errorf("a person's build again of the withdrawn key was not claimed: %v", err)
}
}
// H-A-489 (review round 1): a newer entry of the first branch heard between the older build's claim and its reservation is
// not taken over: the older key ends failed withdrawn with no reservation, and the newer reserves.
func TestANewerEntryHeardBeforeTheReservationIsNotTakenOver(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}}}
res := &fakeReservations{filled: true}
r.b.Reserved = res
newer, err := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Repository: "novox/mesh-catalog", Commit: "7a74cee83f88e6585a5511c3cc53bdf0f5303d20",
Fp2: fp2, Manifest: mdigest('a'), Path: "modules/m", Toolchains: CatalogToolchains(agreedToolchains)})
if err != nil {
t.Fatal(err)
}
r.st.before = func() { r.b.Module(context.Background(), "m", newer) } // at the older key's claim
r.b.Module(context.Background(), "m", moduleValue(t, "modules/m"))
r.b.Wait()
if v := valueOf(t, r.st, r.key); v.State != builds.BuildFailed || !strings.HasPrefix(v.Error, "withdrawn: ") || !strings.Contains(v.Error, "superseded by the fingerprint "+fp2) {
t.Errorf("the older key = %+v, want failed withdrawn, superseded by %s", v, fp2)
}
if len(res.sources) != 1 || res.sources[0].Fingerprint != fp2 {
t.Errorf("reserved %+v, want one reservation, the newer's", res.sources)
}
}
// H-A-489: a fingerprint of the first branch that is no longer its newest entry heard is neither reserved for nor built, and
// said once; the again loop that looks at it later builds nothing.
func TestAnOlderFingerprintAskedAfterANewerEntryIsRefused(t *testing.T) {
r := newRig(t, goBundle)
var mu sync.Mutex
var said []string
r.b.Logf = func(f string, a ...any) { mu.Lock(); said = append(said, fmt.Sprintf(f, a...)); mu.Unlock() }
r.bm.fails["ace/build_go_build"] = "go build of tool: boom"
older := meshcatalog.ModulesByModuleValue{Repository: "novox/mesh-catalog", Commit: "7a74cee83f88e6585a5511c3cc53bdf0f5303d20", Fp2: fp1, Manifest: mdigest('a'),
Path: "modules/m", Toolchains: CatalogToolchains(agreedToolchains)}
r.b.Module(context.Background(), "m", moduleValue(t, "modules/m"))
r.b.Wait()
delete(r.bm.fails, "ace/build_go_build")
newer := older
newer.Fp2 = fp2
data, err := meshcatalogclient.EncodeModule(newer)
if err != nil {
t.Fatal(err)
}
r.b.Module(context.Background(), "m", data)
r.b.Wait()
rev := r.st.revs[r.key]
for range 2 {
r.b.consider(context.Background(), "m", older) // as consider's again loop or a step's look takes it
r.b.Wait()
}
if v := valueOf(t, r.st, r.key); v.State != builds.BuildFailed || r.st.revs[r.key] != rev {
t.Errorf("the older key = %+v at revision %d (was %d), want it left as it failed", v, r.st.revs[r.key], rev)
}
k2, _ := builds.BuilderBuildKey("m", fp2)
if v := valueOf(t, r.st, k2); v.State != builds.BuildDone {
t.Errorf("the newer key = %+v, want done", v)
}
mu.Lock()
defer mu.Unlock()
n := 0
for _, l := range said {
if strings.Contains(l, fp1+": is not built: superseded by "+fp2) {
n++
}
}
if n != 1 {
t.Errorf("superseded said %d times, want once: %q", n, said)
}
}
// 1887/AC1, AC2: a trunk fingerprint with no key is one ask on the Go seat's delivery stream, named in the building key
@@ -142,6 +142,10 @@ func (b *Builder) buildEntry(ctx context.Context, pipeline string, e meshbuilds.
}
return answered(meshbuilds.StepEndedOutcomeFailed, failedWords, "existing build")
}
if newer := b.supersededBy(entry.Module, key, entry.Fp); newer != "" {
// Refused, not waited on (H-A-489): no look builds a superseded fingerprint, so its end would never come.
return answered(meshbuilds.StepEndedOutcomeFailed, fmt.Sprintf("%s at %s %s", entry.Module, entry.Fp, b.saySuperseded(entry.Module, key, entry.Fp, newer)), "refused")
}
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)
@@ -232,7 +236,7 @@ func (b *Builder) keyEnd(ctx context.Context, key string) (done bool, failed str
switch {
case v.State == builds.BuildDone && !Unpublished(v, b.Seats):
return true, "", true
case v.State == builds.BuildFailed && builds.FailedUntilChanged(v.Error):
case v.State == builds.BuildFailed && (builds.FailedUntilChanged(v.Error) || strings.HasPrefix(v.Error, withdrawnPrefix)):
return false, key + ": " + v.Error, true
}
return false, "", false
@@ -74,6 +74,21 @@ func TestABuildStepAnswersItsEnd(t *testing.T) {
if end := ask(entries...); end.Outcome != meshbuilds.StepEndedOutcomePassed || end.Step != meshbuilds.StepEndedStepBuild || len(end.Entries) != 1 || end.Entries[0].Commit != "c1" || end.Pipeline != "main.1.m" {
t.Errorf("a done build: %+v", end)
}
// H-A-489 (review round 1): a withdrawn key whose fingerprint is still the newest entry is answered failed at once, naming
// withdrawn: no look builds it again, so its end is never waited for.
rw := newRig(t, catalogue.Artifact{Name: "files", Kind: "archive"})
rw.b.StepEntry = r.b.StepEntry
withdrawn, _ := builds.EncodeBuilderBuild(builds.BuilderBuild{State: builds.BuildFailed, Manifest: mdigest('a'), Error: withdrawnPrefix + "its reservation 0.1.3 was taken over"})
if _, err := rw.st.Create(t.Context(), rw.key, withdrawn); err != nil {
t.Fatal(err)
}
rw.b.Module(t.Context(), "m", moduleValue(t, "modules/m")) // the newest entry heard is fp1
rw.b.Wait()
bounded, cancel := context.WithTimeout(t.Context(), 2*time.Second)
defer cancel()
if end := rw.b.BuildStep(bounded, "ask1", meshbuilds.StepRun{Pipeline: "main.1.m", Step: meshbuilds.StepRunStepBuild, Entries: entries}); end.Outcome != meshbuilds.StepEndedOutcomeFailed || !strings.Contains(end.Said, "withdrawn: ") {
t.Errorf("a withdrawn key asked: %+v, want failed at once naming withdrawn", end)
}
}
// A step ask waits for the end of its build without a timer: the log entry of that end wakes it (design 47 G A-97).
@@ -434,9 +449,10 @@ func aStepAskWaitsForItsRevision(t *testing.T) {
}
// 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.
// H-A-205: two pipelines of consecutive revisions run at once; the picture holds source revision 46, while the older pipeline
// asks the build of revision 45. Its kept catalog revision is read by number and the build runs while the picture never heard
// a newer entry of m (a restart); once it heard one on the first branch, H-A-489 overrides H-A-205 and the older ask is refused
// superseded. A kept revision naming another fingerprint fails the step, naming it.
func anOlderKeptRevisionIsReadByNumber(t *testing.T) {
var held atomic.Int64
held.Store(46)
@@ -460,6 +476,24 @@ func anOlderKeptRevisionIsReadByNumber(t *testing.T) {
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)
}
// H-A-489: once the picture heard the newer entry of m on the first branch, the older ask is refused superseded and
// nothing is built or reserved for it; the newer entry's build keeps the series.
rn, resn, entryn := revisionRig(t, &held, make(chan struct{}, 1))
rn.b.RevisionWait = time.Nanosecond
rn.b.FirstBranch = r.b.FirstBranch
rn.b.KeptRevision = func(context.Context, string, int64) (int64, map[string]string, error) {
return 45, map[string]string{"m": fp1}, nil
}
entryn.Fp = fp2
rn.b.Entry(context.Background(), Origin{Branch: "main", Source: 46, First: true}, entryn)
rn.b.Wait()
if endn := rn.b.BuildStep(t.Context(), "a1", run); endn.Outcome != meshbuilds.StepEndedOutcomeFailed || !strings.Contains(endn.Said, "superseded by "+fp2) {
t.Errorf("the older ask after the newer entry: end = %+v; want failed, superseded by %s", endn, fp2)
}
rn.b.Wait()
if _, built := rn.st.vals[rn.key]; built || len(resn.sources) != 1 || resn.sources[0].Fingerprint != fp2 {
t.Errorf("built %v, reserved %+v; want nothing built for the older, one reservation, the newer's", built, resn.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) {
@@ -74,14 +74,11 @@ const ModePublish = "publish"
// optional, name what to publish again; the builder answers with the versions it queued (Queued).
const ModeRepublish = "republish"
// ModePublishDrop and ModePublishFirst are the Modes of a reasks value of builder_publish_drop and builder_publish_first (design
// 47 H2 §793): Module and Version name the item; the builder terminates it, or puts it again as live and terminates the old.
const (
ModePublishDrop = "publish-drop"
ModePublishFirst = "publish-first"
)
// ModePublishDrop is the Mode of a reasks value of builder_publish_drop (design 47 H2 §793): Module and Version name the item;
// the builder terminates it.
const ModePublishDrop = "publish-drop"
// NewPublishAct is the value builder_publish_drop (mode ModePublishDrop) or builder_publish_first (ModePublishFirst) writes
// NewPublishAct is the value builder_publish_drop (mode ModePublishDrop) writes
// (§793): its key, `<mode>.<unix nanoseconds>` (a call is one value), and the value. Module, version and why are required.
func NewPublishAct(mode, module, version, why, by string, at time.Time) (string, []byte, error) {
module, version = strings.TrimSpace(module), strings.TrimSpace(version)
@@ -27,10 +27,8 @@ type Acts struct {
ReserveDone func(ctx context.Context, module, fp, by, why string, at time.Time) (string, error)
// DropReserved drops a module's reservation of one MAJOR.MINOR by hand (builder_reserved_drop): its answer, or why not.
DropReserved func(ctx context.Context, module, series, by, why string, at time.Time) (string, error)
// PublishDrop terminates one publish item, and PublishFirst puts it again as live and terminates the old (builder_publish_drop,
// builder_publish_first, design 47 H2 §793): the answer, or why not.
PublishDrop func(ctx context.Context, module, version, by, why string) (string, error)
PublishFirst func(ctx context.Context, module, version, by, why string) (string, error)
// PublishDrop terminates one publish item (builder_publish_drop, design 47 H2 §793): the answer, or why not.
PublishDrop func(ctx context.Context, module, version, by, why string) (string, error)
}
// FloorAgain is builder_floor_again of name: refused, since the builder numbers nothing of its own and no claim asks a floor
@@ -37,9 +37,8 @@ const (
PublishQueueTool = "builder_publish_queue"
// QueueFull is what version-unreleased says of a version the work queue's cap refused.
QueueFull = "queue full"
// PublishDropTool and PublishFirstTool are builder_publish_drop and builder_publish_first (§793).
PublishDropTool = "builder_publish_drop"
PublishFirstTool = "builder_publish_first"
// PublishDropTool is builder_publish_drop (§793); builder_publish_first is retired (H-A-483, third addendum).
PublishDropTool = "builder_publish_drop"
// NotStoredWords opens what a refused artifact is said as.
NotStoredWords = "not stored: "
// VerbPublish is the registry seats' verb a publish again sends, VerbVersions the one whose record says what a seat holds
@@ -48,7 +47,7 @@ const (
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 items are pulled
// live first, each class oldest first (design 47 H H-A-290 (1), H2 §793).
// by its one consumer in the order they are put (design 47 H H-A-290 (1), H2 §793, H-A-483).
PublishClassLive = "live"
PublishClassStart = "again"
// PublishSendsAtOnce bounds the sends of one holder that run at once, its consumers' max ack pending (H-A-290 (3), §793).
@@ -97,21 +96,19 @@ type QueuedPublish struct {
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 {
// streamOrder sorts the keys of the work queue's items in stream order: each key is its item's stream sequence (the builder's
// reader, publishitem.go), compared as a number; a key that is no number sorts after them by its words.
func streamOrder(keys []string) {
sort.SliceStable(keys, func(i, j int) bool {
a, aerr := strconv.ParseUint(keys[i], 10, 64)
b, berr := strconv.ParseUint(keys[j], 10, 64)
switch {
case aerr == nil && berr == nil:
return a < b
case aerr == nil || berr == nil:
return aerr == nil
}
return qs[i].Queued.Before(qs[j].Queued)
return keys[i] < keys[j]
})
}
@@ -456,7 +453,7 @@ func (r *Republisher) Republish(ctx context.Context, module, version string) ([]
type Queued struct {
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);
// Queue are the first queued versions, in stream order, the order each holder's one consumer gives them (H-A-483);
// with a module named, only that module's.
Queue []QueuedPublish `json:"queue"`
// Listed says how many of Total the answer lists.
@@ -512,7 +509,8 @@ func PublishItemKey(module, version string) string {
// PublishQueueOf is the seat mesh-builds' verb publish-queue (design 47 H2 §793; H-A-454): the builder's read of its own work queue
// publishes (queue, its items read in bulk, capped past its bound), small at any size of the queue (H-A-290 (5)): the items' count
// per holder and class with the oldest and newest queue time, and the first PublishQueueListCap in the order they are sent; module
// per holder and class with the oldest and newest queue time, and the first PublishQueueListCap in stream order, the order the
// holder's one consumer gives them (H-A-483, third addendum); module
// (and version) narrow the list to one module's (one version's), so an item's class can be read.
func PublishQueueOf(queue Reader, module, version string) (meshbuilds.PublishQueueAnswer, error) {
out := meshbuilds.PublishQueueAnswer{Counts: []meshbuilds.PublishQueueAnswerCountsItem{}, Queue: []meshbuilds.PublishQueueAnswerQueueItem{}}
@@ -525,7 +523,13 @@ func PublishQueueOf(queue Reader, module, version string) (meshbuilds.PublishQue
}
counts := map[[2]string]*meshbuilds.PublishQueueAnswerCountsItem{}
var listed []QueuedPublish
for _, raw := range vals {
keys := make([]string, 0, len(vals))
for k := range vals {
keys = append(keys, k)
}
streamOrder(keys)
for _, k := range keys {
raw := vals[k]
var q QueuedPublish
if json.Unmarshal(raw, &q) != nil {
continue
@@ -559,25 +563,12 @@ func PublishQueueOf(queue Reader, module, version string) (meshbuilds.PublishQue
}
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, meshbuilds.PublishQueueAnswerQueueItem{Holder: q.Holder, Module: q.Module, Version: q.Version,
Class: q.Class, Artifacts: q.Artifacts, Queued: q.Queued})
if len(out.Queue) == PublishQueueListCap {
break
}
out.Queue = append(out.Queue, meshbuilds.PublishQueueAnswerQueueItem{Holder: q.Holder, Module: q.Module, Version: q.Version,
Class: q.Class, Artifacts: q.Artifacts, Queued: q.Queued})
}
out.Listed = int64(len(out.Queue))
return out, nil
@@ -631,20 +622,17 @@ func AnswerQueue(q meshbuilds.PublishQueueAnswer, acted, reasks Reader) (Queued,
// PublishQueueDescription is builder_publish_queue's description.
const PublishQueueDescription = "The versions the builder will publish again (its work queue " + PublishesLocal + ", design 47 G section 588, H2 section 793): " +
"how many each registry seat holder's items hold per class (live, a build a pipeline's step waits on, pulled first, or again, asked again at a start) " +
"with the oldest and newest queue time; the first 50 in the order they are pulled, each with its class, its artifacts' digests and when it was " +
"how many each registry seat holder's items hold per class (live, a build a pipeline's step waits on, or again, asked again at a start) " +
"with the oldest and newest queue time; the first 50 in stream order, the order each holder's one consumer pulls them, each with its class, its artifacts' digests and when it was " +
"queued (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 (its tries spent, or dropped). A read past its pages is answered capped, naming the items read and the " +
"queue's size (H-A-293). Read-only."
// PublishDropDescription and PublishFirstDescription are builder_publish_drop's and builder_publish_first's (§793).
// PublishDropDescription is builder_publish_drop's (§793).
const PublishDropDescription = "Drop one version's publish (design 47 H2 section 793): its items on the work queue " + PublishesLocal + " are " +
"terminated at every holder, and its publish item ended with who dropped it and why, so it is never sent or put again; builder_publish_again " +
"asks it anew. A hand act, recorded in the hand-act log first."
const PublishFirstDescription = "Put one version's publish first (design 47 H2 section 793): each of its again items on the work queue " +
PublishesLocal + " is put again as live, under the message id <holder>.live.<module>.<version>, pulled before every again item, and the old " +
"terminated. A hand act, recorded in the hand-act log first."
// 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 " +
@@ -7,6 +7,7 @@ import (
"fmt"
"maps"
"slices"
"strconv"
"strings"
"sync"
"testing"
@@ -404,8 +405,9 @@ func answerOf(queue, acted, reasks Reader, module, version string) (Queued, erro
}
// 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.
// within a second and small: counts per holder and class with the oldest and newest queue time, a list capped at fifty in stream
// order (H-A-483, third addendum: each key is its item's stream sequence), 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{}
@@ -418,7 +420,7 @@ func TestThePublishQueueToolAnswersAtAnySize(t *testing.T) {
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)
vals[strconv.Itoa(i+1)], _ = json.Marshal(q) // the reader keys each item by its stream sequence
}
gets := 0
queue := Reader{All: func() (StatePage, error) { return StatePage{Values: vals}, nil },
@@ -435,8 +437,10 @@ func TestThePublishQueueToolAnswersAtAnySize(t *testing.T) {
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])
for i, q := range a.Queue {
if q.Module != fmt.Sprintf("m%d", i) {
t.Fatalf("the list holds %s at %d, want m%d: the items in stream order, whatever their holder or class", q.Module, i, i)
}
}
one, err := answerOf(queue, none, none, "m1995", "")
if err != nil || len(one.Queue) != 1 || one.Queue[0].Class != PublishClassLive || one.Total != 2000 {
@@ -10,10 +10,8 @@ import (
"sort"
"strconv"
"strings"
"sync"
"time"
"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/meshbuilds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
)
@@ -42,8 +40,8 @@ const (
// 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"
// VersionTaggedElsewhere is the finding of a number whose git tag stands at another commit, skipped at reserving (design 47
// H2 §796), scope module; cleared at the module's next version-released.
// VersionTaggedElsewhere is the finding of a number whose git tag stood at another commit, which a reserve skipped before no
// tag was read (design 47 H2 H-A-494); one raised before is cleared at the module's next version-released.
VersionTaggedElsewhere = "version-tagged-elsewhere"
)
@@ -55,6 +53,10 @@ type ReservedVersion struct {
Version string `json:"version"` // MAJOR.MINOR.PATCH
// Artifacts are the module's artifacts at the version: the digest once built, empty before.
Artifacts map[string]string `json:"artifacts"`
// Upstream are the artifacts of kind upstream, by reference (design 47 H2 H-A-486): kept in Artifacts with their digest for the
// record, never awaited, as design 51 copies an upstream image by its pinned digest and no registry seat says it published at
// a version. A reservation written before carries none.
Upstream []string `json:"upstream,omitempty"`
// BuiltAt is when the build ended with every digest known; the publish's bound counts from it.
BuiltAt time.Time `json:"built-at,omitzero"`
// Published are the artifacts a registry seat said published at this version with the built digest.
@@ -63,8 +65,8 @@ type ReservedVersion struct {
// was kept.
PublishedAt map[string]time.Time `json:"published-at,omitempty"`
At time.Time `json:"at"`
// Repository and Commit are what the build was made from, and Tag the git tag its release is written as (a Go
// package's, GoTagOf): empty for a module with no Go package (design 47 G §370), or whose Go package's directory is not known.
// Repository and Commit are what the build was made from. Tag is kept for a reservation written before design 47 H2 H-A-494:
// no git tag is written at a release any more, and a new reservation names none.
Repository string `json:"repository,omitempty"`
Commit string `json:"commit,omitempty"`
Tag string `json:"tag,omitempty"`
@@ -110,22 +112,19 @@ type KeptPublished struct {
Digest string `json:"digest"`
}
// Source is what a build reserving a version is made from (design 47 G §370): the repository and commit the git tag is
// written at, and whether the module has a Go package, whose version is tagged.
// Source is what a build reserving a version is made from (design 47 G §370): the repository and commit, kept on the reservation.
type Source struct {
Repository, Commit string
// Fingerprint is the fingerprint of the catalog entry the build is made from (design 47 G A-76).
Fingerprint string
GoPackage bool
// GoArtifact is the artifact that is the module's Go package, whose module path names the directory its tag is written in
// (design 47 H2 §796).
GoArtifact string
// Branch is the watched branch of the catalog revision whose entry the build came from, and Revision the source revision of
// 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
// Upstream are the artifacts of kind upstream among those reserved, by reference (H-A-486), kept on the reservation.
Upstream []string
// 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
@@ -171,92 +170,6 @@ type Reserver struct {
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)
// Names answers a Go package's module path, which names the directory its tag is written in (design 47 H2 §796); nil, or a
// name not known, tags the version nowhere, said.
Names PackageNames
// Tags reads repository's tags starting with prefix, each with the commit it names, through the seat git's tags (design 47
// H2 §796); away says the read met a transport fault or the error kind away, which lets the reservation go on, said. Nil
// reads none.
Tags func(ctx context.Context, repository, prefix string) (tags []git.Tag, away bool, err error)
// TaggedElsewhere is told the numbers of module a reserve skipped because their tag stands at another commit (§796); nil
// is told none.
TaggedElsewhere func(ctx context.Context, module string, skipped []string)
tagsMu sync.Mutex
// tagsRead are the tags last read of each module, by series patch to the commit, with the catalog revision they were read
// under: a module's tags are read once per catalog revision it reserves under (§796).
tagsRead map[string]tagsAt
}
// tagsAt are a module's tags of one series read under one catalog revision: patch to the commit its tag names.
type tagsAt struct {
revision, prefix string
commits map[int]string
}
// goDirectory is the directory of module's Go package in its repository (§796), from its module path; ok is false, said, when
// no name or no directory of the repository is known.
func (r *Reserver) goDirectory(ctx context.Context, module string, src Source) (string, bool) {
if r.Names == nil {
return "", false
}
path, known, err := r.Names(ctx, module, src.GoArtifact)
switch {
case err != nil:
r.said(fmt.Errorf("%s: its Go package's name cannot be read, so its version is tagged nowhere: %w", module, err))
return "", false
case !known:
r.said(fmt.Errorf("%s: no name of its Go package %s is known yet, so its version is tagged nowhere", module, src.GoArtifact))
return "", false
}
dir, ok := GoDirectory(path, src.Repository)
if !ok {
r.said(fmt.Errorf("%s: its Go package %s is not a module path of the repository %s, so its version is tagged nowhere", module, path, src.Repository))
}
return dir, ok
}
// taggedAt are the patches of series whose tag `<directory>/v<series>.<patch>` stands, each with its commit, read once per
// catalog revision the module reserves under (§796). A read that meets a transport fault or away answers none, said, and the
// reservation goes on; any other failure refuses the reservation, naming it.
func (r *Reserver) taggedAt(ctx context.Context, module, series, dir string, src Source) (map[int]string, error) {
if r.Tags == nil {
return nil, nil
}
prefix := TagPrefix(dir) + series + "."
revision := ""
if src.CatalogRevision > 0 {
revision = fmt.Sprintf("%s.%d", src.Branch, src.CatalogRevision)
r.tagsMu.Lock()
got, ok := r.tagsRead[module]
r.tagsMu.Unlock()
if ok && got.revision == revision && got.prefix == prefix {
return got.commits, nil
}
}
tags, away, err := r.Tags(ctx, src.Repository, prefix)
if err != nil && away {
r.said(fmt.Errorf("%s: its tags %s* cannot be read (%w), so the reservation goes on without them", module, prefix, err))
return nil, nil
}
if err != nil {
return nil, fmt.Errorf("the tags %s* of %s cannot be read: %w", prefix, module, err)
}
commits := map[int]string{}
for _, t := range tags {
if s, p, err := SplitVersion(strings.TrimPrefix(t.Tag, TagPrefix(dir))); err == nil && s == series && strings.HasPrefix(t.Tag, prefix) {
commits[p] = t.Commit
}
}
if revision != "" {
r.tagsMu.Lock()
if r.tagsRead == nil {
r.tagsRead = map[string]tagsAt{}
}
r.tagsRead[module] = tagsAt{revision: revision, prefix: prefix, commits: commits}
r.tagsMu.Unlock()
}
return commits, nil
}
// heldNumbers are the patches of series a registry holds of module's artifacts (H-A-275); a read that fails is said, and none.
@@ -277,19 +190,15 @@ func (r *Reserver) heldNumbers(ctx context.Context, module, series, fingerprint
return out
}
// nextFree is the first patch after after that no registry holds and whose tag stands at no other commit than commit, with the
// held numbers it skipped (H-A-275) and those tagged elsewhere (design 47 H2 §796).
func nextFree(series string, after int, held map[int]bool, tagged map[int]string, commit string) (int, []string, []string) {
var skipped, elsewhere []string
// nextFree is the first patch after after that no registry holds, with the held numbers it skipped (H-A-275). No git tag is
// read: a series is numbered from the catalog's versions and the registries' alone (design 47 H2 H-A-494).
func nextFree(series string, after int, held map[int]bool) (int, []string) {
var skipped []string
for p := after + 1; ; p++ {
switch c, ok := tagged[p]; {
case held[p]:
skipped = append(skipped, fmt.Sprintf("%s.%d", series, p))
case ok && c != commit:
elsewhere = append(elsewhere, fmt.Sprintf("%s.%d (tagged at %s)", series, p, c))
default:
return p, skipped, elsewhere
if !held[p] {
return p, skipped
}
skipped = append(skipped, fmt.Sprintf("%s.%d", series, p))
}
}
@@ -342,15 +251,6 @@ func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts
}
key := ReservedKey(module, series)
held := r.heldNumbers(ctx, module, series, src.Fingerprint, artifacts)
dir, tagged := "", false
var tags map[int]string
if src.GoPackage {
if dir, tagged = r.goDirectory(ctx, module, src); tagged {
if tags, err = r.taggedAt(ctx, module, series, dir, src); err != nil {
return ReservedVersion{}, err
}
}
}
for {
cur, rev, found, err := r.get(ctx, key)
if err != nil {
@@ -368,15 +268,13 @@ func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts
next = p
}
}
patch, skipped, elsewhere := nextFree(series, next, held, tags, src.Commit)
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 tagged {
out.Tag = GoTagOf(dir, out.Version)
}
for _, a := range artifacts {
out.Artifacts[a] = ""
}
out.Upstream = slices.Clone(src.Upstream)
if found {
out.Withdrawn = maps.Clone(cur.Withdrawn)
if cur.Fingerprint != src.Fingerprint {
@@ -410,9 +308,6 @@ func (r *Reserver) Reserve(ctx context.Context, module, series string, artifacts
if len(skipped) > 0 && r.HeldElsewhere != nil {
r.HeldElsewhere(ctx, module, skipped)
}
if len(elsewhere) > 0 && r.TaggedElsewhere != nil {
r.TaggedElsewhere(ctx, module, elsewhere)
}
if found && r.Took != nil {
r.Took(ctx, cur, out)
}
@@ -1134,11 +1029,11 @@ const (
ReservedVerb = meshbuilds.VerbReserved
)
// Missing are the artifacts of v no registry seat said published, sorted.
// Missing are the artifacts of v no registry seat said published, sorted; an upstream one is never awaited (H-A-486).
func (v ReservedVersion) Missing() []string {
var out []string
for a := range v.Artifacts {
if !v.Published[a] {
if !v.Published[a] && !slices.Contains(v.Upstream, a) {
out = append(out, a)
}
}
@@ -5,11 +5,9 @@ import (
"encoding/json"
"errors"
"reflect"
"strings"
"testing"
"time"
"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/meshbuilds"
)
@@ -171,6 +169,23 @@ func TestReservationIsReadAndMarkedPublished(t *testing.T) {
if got := cur.Missing(); !reflect.DeepEqual(got, []string{"m:b"}) {
t.Errorf("missing = %v, want m:b", got)
}
// H-A-486: an upstream artifact is reserved and recorded with its digest, but never awaited: once the others are published
// nothing is missing.
up, err := r.Reserve(ctx, "u", "0.1", []string{"u:server", "u:tools"}, Source{Upstream: []string{"u:server"}})
if err != nil || !reflect.DeepEqual(up.Upstream, []string{"u:server"}) {
t.Fatalf("reserved %+v (%v), want u:server kept as upstream", up, err)
}
for _, a := range []string{"u:server", "u:tools"} {
if _, err := r.Built(ctx, "u", up.Version, a, "sha256:"+a, nil); err != nil {
t.Fatal(err)
}
}
if marked, _, err := r.Published(ctx, "u-tools", up.Version, "sha256:u:tools"); err != nil || len(marked) != 1 {
t.Fatalf("the published of u:tools marked %v (%v)", marked, err)
}
if cur, _, _ := r.At(ctx, ReservedKey("u", "0.1")); len(cur.Missing()) != 0 || cur.Artifacts["u:server"] != "sha256:u:server" {
t.Errorf("missing = %v with artifacts %v, want none missing and the upstream digest kept", cur.Missing(), cur.Artifacts)
}
if key, ok := ReservedBoundOf(ReservedBoundKey("m", "1.4")); !ok || key != ReservedKey("m", "1.4") || ReservedBoundFor(key) != ReservedBoundKey("m", "1.4") {
t.Errorf("the bound key does not name the reservation back: %q %v", key, ok)
}
@@ -399,7 +414,7 @@ func TestANumberARegistryHoldsIsNeverReserved(t *testing.T) {
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})
v, err := r.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, Source{Fingerprint: "fp1", Repository: "o/r", Commit: "c1"})
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)
}
@@ -413,9 +428,9 @@ func TestANumberARegistryHoldsIsNeverReserved(t *testing.T) {
}
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})
again, err := r.Reserve(ctx, "node-tools", "0.1", []string{"node-tools:program"}, Source{Fingerprint: "fp1", Repository: "o/r", Commit: "c1", Rebuild: true})
if err != nil || again.Version != "0.1.41" || again.Artifacts["node-tools:program"] != "" || again.Withdrawn["0.1.39"] != "fp1" || again.Tag != "" {
t.Fatalf("the build again reserved %+v (%v), want 0.1.41 with no digest, 0.1.39 kept withdrawn, and no tag (no Go package name known)", again, err)
t.Fatalf("the build again reserved %+v (%v), want 0.1.41 with no digest, 0.1.39 kept withdrawn, and no tag (design 47 H2 H-A-494)", 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)
@@ -428,50 +443,4 @@ func TestANumberARegistryHoldsIsNeverReserved(t *testing.T) {
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)
}
// Design 47 H2 §796: a Go package's tags are read before it reserves, once per catalog revision; a number whose tag
// `<directory>/v<version>` stands at another commit is skipped and said, one at the build's own commit is not; the version's
// tag names the Go module's directory; a read met away lets the reservation go on, any other failure refuses it.
r.HeldNumbers = nil
var tagReads int
var tagsErr error
var tagsAway bool
var elsewhere []string
tags := []git.Tag{{Tag: "modules/nt/v0.3.0", Commit: "c-other"}, {Tag: "modules/nt/v0.3.1", Commit: "c-mine"}, {Tag: "modules/nt/v0.3.2", Commit: "c-other2"}}
r.Names = func(_ context.Context, module, artifact string) (string, bool, error) {
return "git.example/o/r/modules/nt", module == "node-tools" && artifact == "lib", nil
}
r.Tags = func(_ context.Context, repository, prefix string) ([]git.Tag, bool, error) {
tagReads++
if repository != "o/r" || prefix != "modules/nt/v0.3." {
t.Errorf("tags read of %s %q, want o/r modules/nt/v0.3.", repository, prefix)
}
return tags, tagsAway, tagsErr
}
r.TaggedElsewhere = func(_ context.Context, _ string, s []string) { elsewhere = append(elsewhere, s...) }
at := Source{Fingerprint: "fp3", GoPackage: true, GoArtifact: "lib", Repository: "o/r", Commit: "c-mine", Branch: "main", CatalogRevision: 7}
v3, err := r.Reserve(ctx, "node-tools", "0.3", []string{"node-tools:lib"}, at)
if err != nil || v3.Version != "0.3.1" || v3.Tag != "modules/nt/v0.3.1" || len(elsewhere) != 1 || !strings.Contains(elsewhere[0], "0.3.0") {
t.Fatalf("reserved %+v (%v), tagged elsewhere %v: want 0.3.1 (0.3.0 tagged at another commit, 0.3.1 at the build's own), tag modules/nt/v0.3.1", v3, err, elsewhere)
}
at.Fingerprint, at.Commit, elsewhere = "fp4", "c-new", nil
if v4, err := r.Reserve(ctx, "node-tools", "0.3", []string{"node-tools:lib"}, at); err != nil || v4.Version != "0.3.3" || tagReads != 1 || len(elsewhere) != 1 || !strings.Contains(elsewhere[0], "0.3.2") {
t.Fatalf("reserved %+v (%v) after %d reads, tagged elsewhere %v: want 0.3.3 past 0.3.2's tag, the tags read once for revision main.7", v4, err, tagReads, elsewhere)
}
at.CatalogRevision, at.Fingerprint, tagsErr, tagsAway = 8, "fp5", errors.New("the forge is away"), true
if v5, err := r.Reserve(ctx, "node-tools", "0.3", []string{"node-tools:lib"}, at); err != nil || v5.Version != "0.3.4" || tagReads != 2 {
t.Fatalf("with the tags away reserved %+v (%v) after %d reads, want 0.3.4 and the reservation going on", v5, err, tagReads)
}
at.CatalogRevision, at.Fingerprint, tagsAway = 9, "fp6", false
if _, err := r.Reserve(ctx, "node-tools", "0.3", []string{"node-tools:lib"}, at); err == nil || !strings.Contains(err.Error(), "tags") {
t.Errorf("a tags read refused not away reserved anyway (%v), want the reservation refused naming the tags", err)
}
if d, ok := GoDirectory("git.example/novox/mesh-sdk/go", "https://git.example/novox/mesh-sdk.git"); !ok || d != "go" || GoTagOf(d, "0.1.9") != "go/v0.1.9" {
t.Errorf("mesh-sdk's Go package: directory %q (%v), want go and the tag go/v0.1.9", d, ok)
}
if d, ok := GoDirectory("git.example/o/r", "o/r"); !ok || d != "" || GoTagOf(d, "1.0.0") != "v1.0.0" {
t.Errorf("a root Go module: directory %q (%v), want the root and the tag v1.0.0", d, ok)
}
if _, ok := GoDirectory("git.example/o/rr/x", "o/r"); ok {
t.Error("a module path of another repository was given a directory")
}
}
@@ -1,31 +0,0 @@
package versions
import (
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/trunk"
)
// GoTagOf is the git tag a Go package's released version is written as (design 47 H2 §796): `<directory>/v<version>`, the
// directory of its Go module in the repository, which the Go toolchain's direct fallback reads; `v<version>` at the root. The
// `go/v<version>` tags go from new versions.
func GoTagOf(directory, version string) string { return TagPrefix(directory) + version }
// GoDirectory is the directory of the Go module path modulePath in repository (`<owner>/<name>`, or a clone address naming
// it): the part of the path after the repository's own, as the Go toolchain reads a module kept in a subdirectory; empty at
// the root. ok is false when the path is not one of that repository.
func GoDirectory(modulePath, repository string) (string, bool) {
repo := "/" + strings.ToLower(trunk.RepositoryName(repository))
lower := strings.ToLower(modulePath)
for from := 0; ; {
i := strings.Index(lower[from:], repo)
if i < 0 || repo == "/" {
return "", false
}
end := from + i + len(repo)
if end == len(lower) || lower[end] == '/' {
return strings.Trim(modulePath[end:], "/"), true
}
from = end
}
}
+15 -11
View File
@@ -152,7 +152,7 @@ func TestManifestDeclarations(t *testing.T) { // 1607/AC1
// Design 51 *The floor*: the floor's three sources, the registry seats' versions, git.tags and indexer_requirements.
// The watchdogs seat's presence says a node's machine is heard (issue 1966, ADR 0596 §2, ADR 0668 §3).
if want := []string{"seat:mesh-catalog.entry", "seat:mesh-catalog.registrations", "seat:mesh-catalog.seat-definitions", "seat:mesh-catalog.revision", "seat:mesh-delivery.source", "seat:container-image-registry.publish", "seat:container-image-registry.remove", "seat:container-image-registry.versions",
"seat:git.tag", "seat:git.tags",
"seat:git.tags", // the floor's source alone: no tag is written at a release (design 47 H2 H-A-494)
"seat:go-package-registry.publish", "seat:go-package-registry.remove", "seat:go-package-registry.versions", "seat:mesh-artifact-sweep.held", "seat:mesh-builds.reserved", "seat:mesh-builds.drop", "seat:mesh-builds.publish-queue", "seat:mesh-catalog.versions", "seat:mesh-hand-acts.hand-act", "seat:mesh-module-assigner.assignments", "seat:mesh-watchdogs.presence", "seat:node-build-go.drop", "seat:node-build-image.drop", "seat:node-build-node.drop", "seat:node-build-go.answer", "seat:node-build-image.answer", "seat:node-build-node.answer", "seat:node-engine.manifest-reads", "seat:npm-package-registry.publish", "seat:npm-package-registry.remove",
"seat:npm-package-registry.versions", "seat:oci-artifact-registry.publish", "seat:oci-artifact-registry.remove", "seat:oci-artifact-registry.versions",
// A-231: the build asks on each build seat's queue delivery (accept.delivery.<asker>).
@@ -199,15 +199,17 @@ func TestManifestDeclarations(t *testing.T) { // 1607/AC1
m.Streams[3].Duplicates != 24 || m.Streams[3].MaxDeliveries != 10 || m.Streams[3].MaxAgeDays != 7 || m.Streams[3].MaxMiB != 64 {
t.Errorf("streams = %+v, want waits with wait-held.** and wait-ended.**, 7 days, 16 MiB, the builds' stream (build.ended.**, 7 days, kept last per subject: design 47 G A-181) and the findings' stream", m.Streams)
}
if c, ok := m.Config["toolchain-wait-minutes"]; !ok || c.Default != float64(60) || len(m.Config) != 12 ||
if c, ok := m.Config["toolchain-wait-minutes"]; !ok || c.Default != float64(60) || len(m.Config) != 13 ||
// design 47 H2 §775, H-A-381 (2): the kept-call pace and the taken key's bound, read by the process
m.Config["kept-call-pace-first"].Default != "1s" || m.Config["kept-call-pace-max"].Default != "30s" || m.Config["ask-taken-bound"].Default != "10m" ||
!m.Config["kept-call-pace-first"].Runtime || !m.Config["kept-call-pace-max"].Runtime || !m.Config["ask-taken-bound"].Runtime ||
// H-A-461 (2): the bounds of §794 are settings read at run time, 100 ms and 5 minutes by default
m.Config["slow-event"].Default != "100ms" || m.Config["events-behind-bound"].Default != "5m" || !m.Config["slow-event"].Runtime || !m.Config["events-behind-bound"].Runtime ||
m.Config["revision-wait-minutes"].Default != float64(2) || m.Config["package-wait-minutes"].Default != float64(10) ||
// H-A-492: the record of a version's digests runs under the builder's own bound, a setting of 60 s by default
m.Config["record-bound-seconds"].Default != float64(60) ||
m.Config["publish-pause"].Default != float64(30) || m.Config["publish-pause-max"].Default != float64(30) || m.Config["publish-tries"].Default != float64(5) || m.Config["publish-tries"].Maximum != 10 {
t.Errorf("config = %+v, want toolchain-wait-minutes of 60, revision-wait-minutes of 2 (H-A-156), package-wait-minutes of 10 (H-A-165), the publish settings 30 s, 30 min and 5 tries, at most 10 (design 47 G §588, §633, A-457a; H2 H-A-446 (2))", m.Config)
t.Errorf("config = %+v, want toolchain-wait-minutes of 60, revision-wait-minutes of 2 (H-A-156), package-wait-minutes of 10 (H-A-165), record-bound-seconds of 60 (H-A-492), the publish settings 30 s, 30 min and 5 tries, at most 10 (design 47 G §588, §633, A-457a; H2 H-A-446 (2))", m.Config)
}
// Design 47 G §349: version.numbered is no longer said; old-form-closed on the family version, apart from the builds' ends.
if want := []string{"build.asked-again", "version.old-form-closed"}; !reflect.DeepEqual(m.Emits, want) {
@@ -266,7 +268,7 @@ func TestManifestProcess(t *testing.T) { // 1607/AC1
t.Errorf("health = %v, want kind unit alone", p["health"])
}
env, _ := p["env"].(map[string]any)
if len(env) != 8 || env["MESH_BUILDER_REVISION_WAIT_FILE"] != "${dir:state}/revision-wait-minutes" || env["MESH_BUILDER_PACKAGE_WAIT_FILE"] != "${dir:state}/package-wait-minutes" || env["MESH_BUILDER_PUBLISH_TRIES_FILE"] != "${dir:state}/publish-tries" || env["MESH_BROKER_FILE"] != "${dir:state}/broker" || env["MESH_BUILDER_TOOLCHAIN_WAIT_FILE"] != "${dir:state}/toolchain-wait-minutes" {
if len(env) != 9 || env["MESH_BUILDER_RECORD_BOUND_FILE"] != "${dir:state}/record-bound-seconds" || env["MESH_BUILDER_REVISION_WAIT_FILE"] != "${dir:state}/revision-wait-minutes" || env["MESH_BUILDER_PACKAGE_WAIT_FILE"] != "${dir:state}/package-wait-minutes" || env["MESH_BUILDER_PUBLISH_TRIES_FILE"] != "${dir:state}/publish-tries" || env["MESH_BROKER_FILE"] != "${dir:state}/broker" || env["MESH_BUILDER_TOOLCHAIN_WAIT_FILE"] != "${dir:state}/toolchain-wait-minutes" {
t.Errorf("env = %v, want the broker file and the path of the toolchain wait's file, never the setting itself (design 47 G §672, A-71)", p["env"])
}
for k, v := range env {
@@ -274,14 +276,16 @@ func TestManifestProcess(t *testing.T) { // 1607/AC1
t.Errorf("env %s = %v: a setting reaches the process as a file, never its environment (A-71)", k, v)
}
}
found := false
for _, r := range m.Resources {
if r["type"] == "file" && r["path"] == "${dir:state}/toolchain-wait-minutes" && r["content"] == "${config:toolchain-wait-minutes}" {
found = true
for _, setting := range []string{"toolchain-wait-minutes", "record-bound-seconds"} { // H-A-492: the record's bound too
found := false
for _, r := range m.Resources {
if r["type"] == "file" && r["path"] == "${dir:state}/"+setting && r["content"] == "${config:"+setting+"}" {
found = true
}
}
if !found {
t.Errorf("no file resource with the content ${config:%s}: A-71", setting)
}
}
if !found {
t.Errorf("no file resource with the content ${config:toolchain-wait-minutes}: A-71")
}
for _, r := range m.Resources {
if r["id"] == "settings" {
+17 -1
View File
@@ -91,7 +91,6 @@
"invokes": [
"seat:container-image-registry.remove",
"seat:container-image-registry.versions",
"seat:git.tag",
"seat:git.tags",
"seat:go-package-registry.remove",
"seat:go-package-registry.versions",
@@ -183,6 +182,14 @@
"trusted": false,
"default": 10
},
"record-bound-seconds": {
"type": "number",
"description": "seconds the builder gives the record of a version's digests after its build ends, under its own bound and never the build's (design 47 H2 H-A-492).",
"minimum": 1,
"maximum": 3600,
"trusted": false,
"default": 60
},
"ask-taken-bound": {
"type": "string",
"description": "how long the builder keeps the id of an ask it took from the seat mesh-builds' work queue, so a repeat of it is taken once, a Go duration such as 10m (design 47 H2 §775; H-A-381 (2)).",
@@ -310,6 +317,14 @@
"mode": "0600",
"content": "${config:package-wait-minutes}"
},
{
"id": "record-bound",
"type": "file",
"path": "${dir:state}/record-bound-seconds",
"owner": "mesh-delivery-builder",
"mode": "0600",
"content": "${config:record-bound-seconds}"
},
{
"id": "publish-pause",
"type": "file",
@@ -361,6 +376,7 @@
"MESH_BUILDER_TOOLCHAIN_WAIT_FILE": "${dir:state}/toolchain-wait-minutes",
"MESH_BUILDER_REVISION_WAIT_FILE": "${dir:state}/revision-wait-minutes",
"MESH_BUILDER_PACKAGE_WAIT_FILE": "${dir:state}/package-wait-minutes",
"MESH_BUILDER_RECORD_BOUND_FILE": "${dir:state}/record-bound-seconds",
"MESH_BUILDER_PUBLISH_PAUSE_FILE": "${dir:state}/publish-pause",
"MESH_BUILDER_PUBLISH_PAUSE_MAX_FILE": "${dir:state}/publish-pause-max",
"MESH_BUILDER_PUBLISH_TRIES_FILE": "${dir:state}/publish-tries",
@@ -57,7 +57,7 @@ func VerbDescription(verb string) string {
case VerbDrop:
return "End an ask on the seat's work queue for a caller that no longer waits for it (its step ended by its bound): one waiting is ended dropped when it is pulled, one taken is cancelled; both end the step could-not-run, its why naming the drop and who asked it, so no holder works on it after (design 47 H2 §778; H-A-401; ADR 0664 §4)."
case VerbPublishQueue:
return "What the builder's work queue publishes holds, read by the builder from its own stream (design 47 H2 §793; H-A-454): the items' count per registry seat holder and class with the oldest and newest queue time, and the first 50 in the order they are pulled (the live class first, each class oldest first); module, and version, list only that module's items. A queue read past 4,000 items is answered capped, naming the items read and the queue's size."
return "What the builder's work queue publishes holds, read by the builder from its own stream (design 47 H2 §793; H-A-454): the items' count per registry seat holder and class with the oldest and newest queue time, and the first 50 in stream order, the order each holder's one consumer pulls them (H-A-483); module, and version, list only that module's items. A queue read past 4,000 items is answered capped, naming the items read and the queue's size."
}
return ""
}
@@ -338,7 +338,7 @@ const (
type PublishQueueAnswerQueueItem struct {
// each artifact reference, <module>:<artifact>, with the digest to publish
Artifacts map[string]string `json:"artifacts,omitempty"`
// live, a build a pipeline's step waits on, pulled first; again, asked again at a start
// live, a build a pipeline's step waits on; again, asked again at a start
Class string `json:"class"`
// the registry seat's holder the item is sent to, a module
Holder string `json:"holder"`
@@ -368,7 +368,7 @@ type PublishQueueAnswer struct {
ItemsRead int64 `json:"items-read,omitempty"`
// how many of total the answer lists
Listed int64 `json:"listed"`
// the first 50 items listed, per holder in the order they are pulled
// the first 50 items listed, in stream order
Queue []PublishQueueAnswerQueueItem `json:"queue"`
// with capped: the queue's size in bytes
QueueBytes int64 `json:"queue-bytes,omitempty"`
@@ -14,13 +14,13 @@ const Seat = "mesh-pipeline-runner"
// Form is the form of the seat's values, events and answers this contract was generated at (design 47 H2 §780):
// a reader of a value of another form says "form N, this reader knows M".
const Form = 6
const Form = 9
// The forms and the digest of the fields this contract was generated from: the generator's compare fails a definition
// whose fields changed while its forms did not (design 47 H2 §780).
const (
generatedForms = "6"
generatedFieldsDigest = "AcceptAnswer=224df0394653 Accepted=d2b011e5090f AskAgainAnswer=224df0394653 CancelAnswer=a0dcc32b3f57 EndAgainAnswer=a0dcc32b3f57 FailedStep=cd7184342136 Fill=7a76c9ceb157 FillingEvent=5bd4df78ed84 FullEvent=5bd4df78ed84 KeptAnswer=dfe0d48bc169 KeptByLevelDigestValue=f06c90f7da7f KeptResult=af5f81f189b7 ListAnswer=284210b3c054 LogEntry=b059967b2ae4 Member=8a103baec01f Mover=5db376275bcf MoverEnded=4b35095f6829 MoverRow=b61f41d131a3 Pipeline=2663792125bf PipelineEnded=523f8fc0fe41 PipelineEndedEvent=cb44007f7173 PipelineEndedPhases=9d1c33ce4cc4 PipelineEndedPhasesBuild=a08d49692a09 PipelineEndedPhasesComposition=a08d49692a09 PipelineEndedPhasesIntegration=a08d49692a09 PipelineEndedPhasesLint=a08d49692a09 PipelineEndedPhasesUnit=a08d49692a09 PipelineEndedPhasesValidate=a08d49692a09 PipelineRow=64600be410e9 PipelineStarted=a3d000f095db PipelineStartedEvent=eaa401af4117 PipelinesByBranchRevisionUnfinishedModuleValue=693580eed498 PipelinesByBranchRevisionValue=693580eed498 PipelinesByBranchRunRunValue=693580eed498 PipelinesByBranchSourcePublishedPackageVersionValue=693580eed498 PipelinesByStepsPipelineMoverValue=94de99db7816 PlaceAnswer=a0dcc32b3f57 PlaceUnfinishedAnswer=ed94ced4513a Published=d9af3024dacc QueueByQueueNextValue=765a2918a728 QueueByRunningPipelineValue=ed94ced4513a QueueByWaitingSequenceValue=99605298ae13 RePinnedEvent=92fd04bfa6d3 RerunAnswer=9b7efd0df344 ReviewAnswer=f397b8965179 RoomEvent=5bd4df78ed84 RunAnswer=96bd45aa2e62 RunStarted=b280617410c3 RunStartedEvent=0767a9358fa3 Shared=c981cf6aa860 SharedAskedBy=c9b30cc4d0d0 ShowAnswer=48b8cecc529a StandsAnswer=0afa3693bf3b StartAnswer=ed94ced4513a StepEndedEvent=799020642c19 StepEvent=64f18c40ed5d StepLogByPipelineValue=ffdde090a101 StepResult=0dac0e15d017 StepStartedEvent=799020642c19 TestCounts=9c1332427159 TestRun=ca5a87f3b6b8 TestRunPackage=a7d30558470d TestRunReader=c9b30cc4d0d0 TestRunsAnswer=7ab81a45ca33 TestRunsDropAnswer=8ee70b35469d ToolchainUsed=43b6d42376fb Wait=21e4ee7a3ef1 WaitEndedEvent=2bf6d38041c0 WaitHeldEvent=2bf6d38041c0 Waiting=ed94ced4513a WhyCarriedAnswer=8e2fcea6479f Widening=e2790a307466"
generatedForms = "9"
generatedFieldsDigest = "AcceptAnswer=224df0394653 Accepted=d2b011e5090f AskAgainAnswer=224df0394653 CancelAnswer=a0dcc32b3f57 EndAgainAnswer=a0dcc32b3f57 FailedStep=cd7184342136 Fill=7a76c9ceb157 FillingEvent=5bd4df78ed84 FullEvent=5bd4df78ed84 KeptAnswer=dfe0d48bc169 KeptByLevelDigestValue=f06c90f7da7f KeptResult=af5f81f189b7 ListAnswer=284210b3c054 LogEntry=b059967b2ae4 Member=8a103baec01f Mover=5db376275bcf MoverEnded=4b35095f6829 MoverRow=b61f41d131a3 Pipeline=2663792125bf PipelineEnded=523f8fc0fe41 PipelineEndedEvent=cb44007f7173 PipelineEndedPhases=9d1c33ce4cc4 PipelineEndedPhasesBuild=a08d49692a09 PipelineEndedPhasesComposition=a08d49692a09 PipelineEndedPhasesIntegration=a08d49692a09 PipelineEndedPhasesLint=a08d49692a09 PipelineEndedPhasesUnit=a08d49692a09 PipelineEndedPhasesValidate=a08d49692a09 PipelineRow=f58dbdcaf2d4 PipelineStarted=582f8ff3b28d PipelineStartedEvent=eaa401af4117 PipelinesByBranchRevisionAgainNValue=693580eed498 PipelinesByBranchRevisionUnfinishedModuleValue=693580eed498 PipelinesByBranchRevisionValue=693580eed498 PipelinesByBranchRunRunValue=693580eed498 PipelinesByBranchSourcePublishedPackageVersionValue=693580eed498 PipelinesByStepsPipelineMoverValue=94de99db7816 PlaceAnswer=a0dcc32b3f57 PlaceUnfinishedAnswer=ed94ced4513a Published=d9af3024dacc QueueByQueueNextValue=765a2918a728 QueueByRunningPipelineValue=ed94ced4513a QueueByWaitingSequenceValue=99605298ae13 RePinnedEvent=92fd04bfa6d3 RerunAnswer=9b7efd0df344 ReviewAnswer=f397b8965179 RoomEvent=5bd4df78ed84 RunAnswer=96bd45aa2e62 RunStarted=b280617410c3 RunStartedEvent=0767a9358fa3 Shared=c981cf6aa860 SharedAskedBy=c9b30cc4d0d0 ShowAnswer=48b8cecc529a StandsAnswer=0afa3693bf3b StartAnswer=ed94ced4513a StepEndedEvent=799020642c19 StepEvent=64f18c40ed5d StepLogByPipelineValue=ffdde090a101 StepResult=0dac0e15d017 StepStartedEvent=799020642c19 TestCounts=9c1332427159 TestRun=ca5a87f3b6b8 TestRunPackage=a7d30558470d TestRunReader=c9b30cc4d0d0 TestRunsAnswer=7ab81a45ca33 TestRunsDropAnswer=8ee70b35469d ToolchainUsed=43b6d42376fb Wait=21e4ee7a3ef1 WaitEndedEvent=2bf6d38041c0 WaitHeldEvent=2bf6d38041c0 Waiting=ed94ced4513a WhyCarriedAnswer=8e2fcea6479f Widening=e2790a307466"
)
const (
@@ -69,11 +69,11 @@ func VerbDescription(verb string) string {
case VerbRun:
return "The run on request of one or more members, each a module at a named commit, through their pipelines; delivers nothing, replacing the checker's try (ADR 0666 section 18). Says run-started."
case VerbStart:
return "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log."
return "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log. With modules, a pipeline at the head keyed <branch>.<revision>.again.<n> carrying the named modules whose newest entry has no passed pipeline, at the take-in's tiers; a module whose newest entry passed is refused by name. Exactly one of module or modules (design 47 H2 H-A-479)."
case VerbShow:
return "One pipeline: naming a mover, its steps alone; with no mover, each mover's row (its module, outcome and failed step), never every step of every mover, or the steps of any mover the step and state filters hold; and its step log, with the stores' fill (design 47 H2 §789, H-A-376). Reads only."
case VerbList:
return "The pipelines and runs of a module, a branch or a commit, newest first: by default one short row per pipeline, the newest 20 (its key, call, start, end, outcome, movers' count and first failed or could-not-run step with its module and why); the whole pipelines, each record with its movers and steps counted, never its steps (show gives those), only with full and a limit (design 47 H2 H-A-376). Reads only."
return "The pipelines and runs of a module, a branch or a commit, newest first: by default one short row per pipeline, the newest 20 (its key, call, source, revision, start, end, outcome, movers' count, its steps counted per outcome and first failed or could-not-run step with its module and why); the whole pipelines, each record with its movers and steps counted, never its steps (show gives those), only with full and a limit (design 47 H2 H-A-376, H-A-467). Reads only."
case VerbStands:
return "What stands still, and since when: each step not ended and each wait held. Reads only."
case VerbWhyCarried:
@@ -354,6 +354,44 @@ func DecodePipelinesByBranchRevisionUnfinishedModuleValue(raw []byte) (Pipelines
return v, formRead(raw), nil
}
// PipelinesByBranchRevisionAgainNKey is the key of one value of the state pipelines under the form "<branch>.<revision>.again.<n>".
func PipelinesByBranchRevisionAgainNKey(branch, revision, n string) string {
return branch + "." + revision + ".again." + n
}
// ParsePipelinesByBranchRevisionAgainNKey reads the parts of a key of the form "<branch>.<revision>.again.<n>", in the order of the form; the last result is false for a key of another form.
func ParsePipelinesByBranchRevisionAgainNKey(key string) (string, string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", "", false
}
rest = after0
v2, after2, found2 := strings.Cut(rest, ".again.")
if !found2 || v2 == "" {
return "", "", "", false
}
rest = after2
if rest == "" {
return "", "", "", false
}
v4 := rest
rest = ""
if rest != "" {
return "", "", "", false
}
return v0, v2, v4, true
}
// DecodePipelinesByBranchRevisionAgainNValue reads one value of the state pipelines under the form "<branch>.<revision>.again.<n>" as another part wrote it: a field PipelinesByBranchRevisionAgainNValue does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780).
func DecodePipelinesByBranchRevisionAgainNValue(raw []byte) (PipelinesByBranchRevisionAgainNValue, int, error) {
var v PipelinesByBranchRevisionAgainNValue
if err := json.Unmarshal(raw, &v); err != nil {
return v, 0, err
}
return v, formRead(raw), 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
@@ -879,7 +917,7 @@ const (
PipelineEndedOutcomeCancelled = "cancelled"
)
// PipelineRow is one pipeline in list's short form (design 47 H2 H-A-376).
// PipelineRow is one pipeline in list's short form, with its source, revision and its steps counted per outcome (design 47 H2 H-A-376, H-A-467).
type PipelineRow struct {
// the merge call whose source revision the take-in took in
Call string `json:"call,omitempty"`
@@ -889,8 +927,14 @@ type PipelineRow struct {
MoverCount int64 `json:"mover-count"`
Outcome string `json:"outcome"`
// the pipeline's key
Pipeline string `json:"pipeline"`
Started *time.Time `json:"started,omitempty"`
Pipeline string `json:"pipeline"`
// the catalog graph revision of the branch the pipeline runs for (design 47 H2 H-A-467)
Revision int64 `json:"revision,omitempty"`
// the source revision of the watched branch the pipeline runs for, its key (design 47 H2 H-A-467)
Source int64 `json:"source,omitempty"`
Started *time.Time `json:"started,omitempty"`
// how many of the pipeline's steps hold each outcome, by the step's outcome (design 47 H2 H-A-467)
Steps map[string]int64 `json:"steps,omitempty"`
}
// The values of PipelineRow's outcome.
@@ -904,7 +948,7 @@ const (
PipelineRowOutcomeCancelled = "cancelled"
)
// PipelineStarted is a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52).
// PipelineStarted is a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52), and again at a re-pin with its kept revisions (H2 H-A-496).
type PipelineStarted struct {
At *time.Time `json:"at,omitempty"`
// the watched branch, or the branch of a run on request
@@ -913,6 +957,8 @@ type PipelineStarted struct {
Call string `json:"call,omitempty"`
// is the form of what this value carries, left out while it is 1 (design 47 H2 §780).
Form int64 `json:"form,omitempty"`
// every catalog revision the pipeline's movers are kept at, said again in full at each re-pin, so the indexer pins each while the pipeline runs (design 47 H2 H-A-496 and its addendum)
Kept []int64 `json:"kept,omitempty"`
// the pipeline's movers
Movers []Mover `json:"movers"`
// 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)
@@ -1238,7 +1284,10 @@ type RunAnswer struct {
// StartInput is what start takes.
type StartInput struct {
Branch string `json:"branch"`
Module string `json:"module"`
// the one mover of the head's pipeline <branch>.<revision>; absent when modules is given
Module string `json:"module,omitempty"`
// the modules started again at the head, each whose newest entry has no passed pipeline (a failed, cut or superseded one); absent when module is given (design 47 H2 H-A-479)
Modules []string `json:"modules,omitempty"`
// why, written with the caller the runtime proves in the hand-act log
Why string `json:"why"`
}
@@ -1631,6 +1680,9 @@ type PipelinesByBranchRunRunValue = Pipeline
// PipelinesByBranchRevisionUnfinishedModuleValue is one value of the state pipelines under the key <branch>.<revision>.unfinished.<module>.
type PipelinesByBranchRevisionUnfinishedModuleValue = Pipeline
// PipelinesByBranchRevisionAgainNValue is one value of the state pipelines under the key <branch>.<revision>.again.<n>.
type PipelinesByBranchRevisionAgainNValue = Pipeline
// PipelinesByStepsPipelineMoverValue is one value of the state pipelines under the key steps.<pipeline>.<mover>.
type PipelinesByStepsPipelineMoverValue struct {
// is the form of what this value carries, left out while it is 1 (design 47 H2 §780).
@@ -19,6 +19,8 @@ func TestFixtures(t *testing.T) {
}{
{name: "a take-in's pipeline started with its two movers", subject: "mesh.seat.mesh-pipeline-runner.event.pipeline-started.main.3589", given: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-sdk\",\"module\":\"mesh-sdk\",\"repository\":\"mesh-sdk\",\"tier\":1},{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":2}],\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"v\":1}", wire: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-sdk\",\"module\":\"mesh-sdk\",\"repository\":\"mesh-sdk\",\"tier\":1},{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":2}],\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"v\":1}",
decode: func(b []byte) (any, error) { var v PipelineStartedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.pipeline-started\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a pipeline started again at a re-pin, with the three revisions its movers are kept at (H-A-496)", subject: "mesh.seat.mesh-pipeline-runner.event.pipeline-started.main.291", given: "{\"at\":\"2026-11-22T20:00:00Z\",\"branch\":\"main\",\"kept\":[292,295,298],\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"pipeline\":\"main.291\",\"revision\":291,\"source\":114,\"v\":1}", wire: "{\"at\":\"2026-11-22T20:00:00Z\",\"branch\":\"main\",\"kept\":[292,295,298],\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"repository\":\"mesh-networking\",\"tier\":1}],\"pipeline\":\"main.291\",\"revision\":291,\"source\":114,\"v\":1}",
decode: func(b []byte) (any, error) { var v PipelineStartedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.pipeline-started\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a pipeline ended passed: per mover its version, steps and tier, an optional step failed", subject: "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.main.3589", given: "{\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-sdk\",\"module\":\"mesh-sdk\",\"steps\":[{\"module\":\"mesh-sdk\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"validate\"}],\"tier\":1,\"version\":\"0.1.21\",\"widens\":[{\"name\":\"seat:mesh-wants.input\",\"what\":\"grant\"}]},{\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"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\"}],\"tier\":2,\"version\":\"0.1.15\"}],\"outcome\":\"passed\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"v\":1}", wire: "{\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-sdk\",\"module\":\"mesh-sdk\",\"steps\":[{\"module\":\"mesh-sdk\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"validate\"}],\"tier\":1,\"version\":\"0.1.21\",\"widens\":[{\"name\":\"seat:mesh-wants.input\",\"what\":\"grant\"}]},{\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"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\"}],\"tier\":2,\"version\":\"0.1.15\"}],\"outcome\":\"passed\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"v\":1}",
decode: func(b []byte) (any, error) { var v PipelineEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.pipeline-ended\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a pipeline of two movers ended with its phases and one mover left unfinished", subject: "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.main.3589", given: "{\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"form\":2,\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-sdk\",\"module\":\"mesh-sdk\",\"steps\":[{\"module\":\"mesh-sdk\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"validate\"}],\"tier\":1,\"version\":\"0.1.21\",\"widens\":[{\"name\":\"seat:mesh-wants.input\",\"what\":\"grant\"}]},{\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"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\"}],\"tier\":2,\"version\":\"0.1.15\"}],\"outcome\":\"passed\",\"phases\":{\"build\":{\"end\":\"2026-11-21T22:02:00Z\",\"start\":\"2026-11-21T22:00:06Z\"},\"composition\":{\"end\":\"2026-11-21T22:06:00Z\",\"start\":\"2026-11-21T22:04:01Z\"},\"ended\":\"2026-11-21T22:06:00Z\",\"placed\":\"2026-11-21T22:00:05Z\",\"taken\":\"2026-11-21T22:00:00Z\",\"unit\":{\"end\":\"2026-11-21T22:04:00Z\",\"start\":\"2026-11-21T22:02:01Z\"}},\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"unfinished\":[\"mesh-delivery-view\"],\"v\":1}", wire: "{\"branch\":\"main\",\"call\":\"0123456789abcdef\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"form\":2,\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-sdk\",\"module\":\"mesh-sdk\",\"steps\":[{\"module\":\"mesh-sdk\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"validate\"}],\"tier\":1,\"version\":\"0.1.21\",\"widens\":[{\"name\":\"seat:mesh-wants.input\",\"what\":\"grant\"}]},{\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"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\"}],\"tier\":2,\"version\":\"0.1.15\"}],\"outcome\":\"passed\",\"phases\":{\"build\":{\"end\":\"2026-11-21T22:02:00Z\",\"start\":\"2026-11-21T22:00:06Z\"},\"composition\":{\"end\":\"2026-11-21T22:06:00Z\",\"start\":\"2026-11-21T22:04:01Z\"},\"ended\":\"2026-11-21T22:06:00Z\",\"placed\":\"2026-11-21T22:00:05Z\",\"taken\":\"2026-11-21T22:00:00Z\",\"unit\":{\"end\":\"2026-11-21T22:04:00Z\",\"start\":\"2026-11-21T22:02:01Z\"}},\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"unfinished\":[\"mesh-delivery-view\"],\"v\":1}",
@@ -156,7 +156,7 @@
{
"name": "publish-queue",
"class": "read",
"description": "What the builder's work queue publishes holds, read by the builder from its own stream (design 47 H2 §793; H-A-454): the items' count per registry seat holder and class with the oldest and newest queue time, and the first 50 in the order they are pulled (the live class first, each class oldest first); module, and version, list only that module's items. A queue read past 4,000 items is answered capped, naming the items read and the queue's size.",
"description": "What the builder's work queue publishes holds, read by the builder from its own stream (design 47 H2 §793; H-A-454): the items' count per registry seat holder and class with the oldest and newest queue time, and the first 50 in stream order, the order each holder's one consumer pulls them (H-A-483); module, and version, list only that module's items. A queue read past 4,000 items is answered capped, naming the items read and the queue's size.",
"input": {
"type": "object",
"properties": {
@@ -243,7 +243,7 @@
"live",
"again"
],
"description": "live, a build a pipeline's step waits on, pulled first; again, asked again at a start"
"description": "live, a build a pipeline's step waits on; again, asked again at a start"
},
"artifacts": {
"type": "object",
@@ -266,7 +266,7 @@
"queued"
]
},
"description": "the first 50 items listed, per holder in the order they are pulled"
"description": "the first 50 items listed, in stream order"
},
"listed": {
"type": "integer",
@@ -29,6 +29,29 @@
"at": "2026-11-10T10:00:00Z"
}
},
{
"name": "a pipeline started again at a re-pin, with the three revisions its movers are kept at (H-A-496)",
"of": "event:pipeline-started",
"subject": "mesh.seat.mesh-pipeline-runner.event.pipeline-started.main.291",
"given": {
"pipeline": "main.291",
"branch": "main",
"revision": 291,
"source": 114,
"v": 1,
"movers": [
{
"module": "nats",
"commit": "0123456789abcdef0123456789abcdef01234567",
"fingerprint": "fp-0123",
"repository": "mesh-networking",
"tier": 1
}
],
"kept": [292, 295, 298],
"at": "2026-11-22T20:00:00Z"
}
},
{
"name": "a pipeline ended passed: per mover its version, steps and tier, an optional step failed",
"of": "event:pipeline-ended",
@@ -50,12 +50,20 @@
},
{
"name": "start",
"description": "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log.",
"description": "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log. With modules, a pipeline at the head keyed <branch>.<revision>.again.<n> carrying the named modules whose newest entry has no passed pipeline, at the take-in's tiers; a module whose newest entry passed is refused by name. Exactly one of module or modules (design 47 H2 H-A-479).",
"input": {
"type": "object",
"properties": {
"module": {
"type": "string"
"type": "string",
"description": "the one mover of the head's pipeline <branch>.<revision>; absent when modules is given"
},
"modules": {
"type": "array",
"items": {
"type": "string"
},
"description": "the modules started again at the head, each whose newest entry has no passed pipeline (a failed, cut or superseded one); absent when module is given (design 47 H2 H-A-479)"
},
"branch": {
"type": "string"
@@ -66,7 +74,6 @@
}
},
"required": [
"module",
"branch",
"why"
]
@@ -171,7 +178,7 @@
},
{
"name": "list",
"description": "The pipelines and runs of a module, a branch or a commit, newest first: by default one short row per pipeline, the newest 20 (its key, call, start, end, outcome, movers' count and first failed or could-not-run step with its module and why); the whole pipelines, each record with its movers and steps counted, never its steps (show gives those), only with full and a limit (design 47 H2 H-A-376). Reads only.",
"description": "The pipelines and runs of a module, a branch or a commit, newest first: by default one short row per pipeline, the newest 20 (its key, call, source, revision, start, end, outcome, movers' count, its steps counted per outcome and first failed or could-not-run step with its module and why); the whole pipelines, each record with its movers and steps counted, never its steps (show gives those), only with full and a limit (design 47 H2 H-A-376, H-A-467). Reads only.",
"input": {
"type": "object",
"properties": {
@@ -910,6 +917,13 @@
},
"description": "a pipeline of its own of one mover kept in the runner's state unfinished, put in it by place-unfinished; the revision the unfinished entry names (design 47 H2 §86, H-A-398)"
},
{
"key": "<branch>.<revision>.again.<n>",
"value": {
"$ref": "#/defs/Pipeline"
},
"description": "a pipeline started again at the head by start with modules, its movers the named modules whose newest entry has no passed pipeline; n from 1, taken by writing on absence (design 47 H2 H-A-479)"
},
{
"key": "steps.<pipeline>.<mover>",
"value": {
@@ -1661,9 +1675,16 @@
"published": {
"$ref": "#/defs/Published",
"description": "for a pipeline a package's publish started, that publish (A-202)"
},
"kept": {
"type": "array",
"items": {
"type": "integer"
},
"description": "every catalog revision the pipeline's movers are kept at, said again in full at each re-pin, so the indexer pins each while the pipeline runs (design 47 H2 H-A-496 and its addendum)"
}
},
"description": "a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52)",
"description": "a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52), and again at a re-pin with its kept revisions (H2 H-A-496)",
"required": [
"v",
"pipeline",
@@ -2275,6 +2296,14 @@
"type": "string",
"description": "the merge call whose source revision the take-in took in"
},
"source": {
"type": "integer",
"description": "the source revision of the watched branch the pipeline runs for, its key (design 47 H2 H-A-467)"
},
"revision": {
"type": "integer",
"description": "the catalog graph revision of the branch the pipeline runs for (design 47 H2 H-A-467)"
},
"started": {
"type": "string",
"format": "date-time"
@@ -2301,9 +2330,16 @@
},
"failed": {
"$ref": "#/defs/FailedStep"
},
"steps": {
"type": "object",
"additionalProperties": {
"type": "integer"
},
"description": "how many of the pipeline's steps hold each outcome, by the step's outcome (design 47 H2 H-A-467)"
}
},
"description": "one pipeline in list's short form (design 47 H2 H-A-376)",
"description": "one pipeline in list's short form, with its source, revision and its steps counted per outcome (design 47 H2 H-A-376, H-A-467)",
"required": [
"pipeline",
"outcome",
@@ -2338,5 +2374,5 @@
]
}
},
"form": 6
"form": 9
}
@@ -251,7 +251,7 @@ export interface PublishQueueAnswerCountsItem {
export interface PublishQueueAnswerQueueItem {
/** each artifact reference, <module>:<artifact>, with the digest to publish */
"artifacts"?: Record<string, string>;
/** live, a build a pipeline's step waits on, pulled first; again, asked again at a start */
/** live, a build a pipeline's step waits on; again, asked again at a start */
"class": "live" | "again";
/** the registry seat's holder the item is sent to, a module */
"holder": string;
@@ -275,7 +275,7 @@ export interface PublishQueueAnswer {
"items-read"?: number;
/** how many of total the answer lists */
"listed": number;
/** the first 50 items listed, per holder in the order they are pulled */
/** the first 50 items listed, in stream order */
"queue": PublishQueueAnswerQueueItem[];
/** with capped: the queue's size in bytes */
"queue-bytes"?: number;
@@ -121,6 +121,12 @@ export declare function pipelinesByBranchRevisionUnfinishedModuleKey(branch: str
/** The parts of a key of the form "<branch>.<revision>.unfinished.<module>", or undefined for a key of another form. */
export declare function parsePipelinesByBranchRevisionUnfinishedModuleKey(_key: string): { branch: string; revision: string; module: string } | undefined;
/** The key of one value of the state pipelines under the form "<branch>.<revision>.again.<n>". */
export declare function pipelinesByBranchRevisionAgainNKey(branch: string, revision: string, n: string): string;
/** The parts of a key of the form "<branch>.<revision>.again.<n>", or undefined for a key of another form. */
export declare function parsePipelinesByBranchRevisionAgainNKey(_key: string): { branch: string; revision: string; n: 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;
@@ -420,7 +426,7 @@ export interface PipelineEnded {
"why"?: string;
}
/** one pipeline in list's short form (design 47 H2 H-A-376) */
/** one pipeline in list's short form, with its source, revision and its steps counted per outcome (design 47 H2 H-A-376, H-A-467) */
export interface PipelineRow {
/** the merge call whose source revision the take-in took in */
"call"?: string;
@@ -431,10 +437,16 @@ export interface PipelineRow {
"outcome": "waiting" | "running" | "passed" | "failed" | "refused" | "superseded" | "cancelled";
/** the pipeline's key */
"pipeline": string;
/** the catalog graph revision of the branch the pipeline runs for (design 47 H2 H-A-467) */
"revision"?: number;
/** the source revision of the watched branch the pipeline runs for, its key (design 47 H2 H-A-467) */
"source"?: number;
"started"?: string;
/** how many of the pipeline's steps hold each outcome, by the step's outcome (design 47 H2 H-A-467) */
"steps"?: Record<string, number>;
}
/** a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52) */
/** a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52), and again at a re-pin with its kept revisions (H2 H-A-496) */
export interface PipelineStarted {
"at"?: string;
/** the watched branch, or the branch of a run on request */
@@ -443,6 +455,8 @@ export interface PipelineStarted {
"call"?: string;
/** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */
"form"?: number;
/** every catalog revision the pipeline's movers are kept at, said again in full at each re-pin, so the indexer pins each while the pipeline runs (design 47 H2 H-A-496 and its addendum) */
"kept"?: number[];
/** the pipeline's movers */
"movers": Mover[];
/** 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) */
@@ -693,7 +707,10 @@ export interface RunAnswer {
/** is what start takes. */
export interface StartInput {
"branch": string;
"module": string;
/** the one mover of the head's pipeline <branch>.<revision>; absent when modules is given */
"module"?: string;
/** the modules started again at the head, each whose newest entry has no passed pipeline (a failed, cut or superseded one); absent when module is given (design 47 H2 H-A-479) */
"modules"?: string[];
/** why, written with the caller the runtime proves in the hand-act log */
"why": string;
}
@@ -1025,6 +1042,9 @@ export type PipelinesByBranchRunRunValue = Pipeline;
/** is one value of the state pipelines under the key <branch>.<revision>.unfinished.<module>. */
export type PipelinesByBranchRevisionUnfinishedModuleValue = Pipeline;
/** is one value of the state pipelines under the key <branch>.<revision>.again.<n>. */
export type PipelinesByBranchRevisionAgainNValue = Pipeline;
/** is one value of the state pipelines under the key steps.<pipeline>.<mover>. */
export interface PipelinesByStepsPipelineMoverValue {
/** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */
@@ -199,6 +199,29 @@ export function parsePipelinesByBranchRevisionUnfinishedModuleKey(_key) {
return { branch, revision, module };
}
/** The key of one value of the state pipelines under the form "<branch>.<revision>.again.<n>". */
export function pipelinesByBranchRevisionAgainNKey(branch, revision, n) {
return branch + "." + revision + ".again." + n;
}
/** The parts of a key of the form "<branch>.<revision>.again.<n>", or undefined for a key of another form. */
export function parsePipelinesByBranchRevisionAgainNKey(_key) {
let _rest = _key;
const _at0 = _rest.indexOf(".");
if (_at0 <= 0) return undefined;
const branch = _rest.slice(0, _at0);
_rest = _rest.slice(_at0 + 1);
const _at2 = _rest.indexOf(".again.");
if (_at2 <= 0) return undefined;
const revision = _rest.slice(0, _at2);
_rest = _rest.slice(_at2 + 7);
if (_rest === "") return undefined;
const n = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { branch, revision, n };
}
/** The key of one value of the state pipelines under the form "steps.<pipeline>.<mover>". */
export function pipelinesByStepsPipelineMoverKey(pipeline, mover) {
return "steps." + pipeline + "." + mover;
@@ -664,7 +664,8 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
sources.refresh()
})
// The held take-ins are taken in again from the state held at the start, before a branch's consumer gives a later one
// (design 47 H, H-A-114, H-A-118).
// (design 47 H, H-A-114, H-A-118); a chain's key a stop left is deleted first (H2 H-A-497 addendum).
ix.EndChains(ctx)
sources.takeAgain()
sources.refresh()
if stopped != nil {
@@ -265,24 +265,34 @@ type actor struct {
s *sourceMoved
}
// HeldAgain takes a branch's held source revisions in again now (indexer_take_in_pending).
// HeldAgain takes a branch's held source revisions in again now (indexer_take_in_pending), beside the asks' loop, and answers
// at once (design 47 H2 H-A-497 and its addendum): a chain that runs already answers its state from the state takeins; held
// sources start the chain at the first, written there before it runs, answered with how many wait.
func (a actor) HeldAgain(ctx context.Context, branch string) index.TakenIn {
r := index.TakenIn{Module: branch}
if hs, err := a.HeldOf(ctx, branch); err != nil || len(hs) == 0 {
if c, running, err := a.ChainOf(ctx, branch); err != nil {
r.Answer = "the state takeins is not read: " + err.Error()
return r
} else if running {
r.Held = true
r.Answer = fmt.Sprintf("a chain runs: source %d taken in since %s, %d wait", c.Source, c.Since.Format(time.RFC3339), c.Waiting)
return r
}
hs, err := a.HeldOf(ctx, branch)
if err != nil || len(hs) == 0 {
r.Answer = "the branch " + branch + " holds no source-moved"
if err != nil {
r.Answer = "the state held is not read: " + err.Error()
}
return r
}
a.s.takeAgain()
hs, err := a.HeldOf(ctx, branch)
still := err != nil || len(hs) > 0
r.Stored, r.Held = !still, still
r.Answer = "taken in"
if still {
r.Answer = "still held: indexer_pending says why"
}
c := a.StartChain(ctx, hs)
go func() {
a.s.takeAgain()
a.EndChain(a.s.ctx, branch)
}()
r.Held = true
r.Answer = fmt.Sprintf("chain started at source %d, %d wait", c.Source, c.Waiting)
return r
}
@@ -97,6 +97,98 @@ func TestAHeldSourceMovedIsSkippedByHand(t *testing.T) {
}
}
// chainStore is a takeins state in memory, safe beside the chain's own goroutine, which says on ended when a chain key goes.
type chainStore struct {
mu sync.Mutex
vals map[string][]byte
ended chan string
}
func (c *chainStore) Get(_ context.Context, k string) ([]byte, uint64, bool, error) {
c.mu.Lock()
defer c.mu.Unlock()
v, ok := c.vals[k]
return v, 1, ok, nil
}
func (c *chainStore) Keys(context.Context) ([]string, error) {
c.mu.Lock()
defer c.mu.Unlock()
var out []string
for k := range c.vals {
out = append(out, k)
}
return out, nil
}
func (c *chainStore) Create(_ context.Context, k string, v []byte) error {
c.mu.Lock()
defer c.mu.Unlock()
c.vals[k] = v
return nil
}
func (c *chainStore) Update(ctx context.Context, k string, v []byte, _ uint64) error {
return c.Create(ctx, k, v)
}
func (c *chainStore) Delete(_ context.Context, k string, _ uint64) error {
c.mu.Lock()
_, had := c.vals[k]
delete(c.vals, k)
c.mu.Unlock()
if had && strings.HasPrefix(k, index.ChainPrefix) {
c.ended <- k
}
return nil
}
// Design 47 H2 H-A-497 and its addendum: a hand ask of a branch with held sources starts the chain beside the asks' loop
// and answers at once; an ask that meets the running chain answers its state, which the state takeins holds and
// indexer_pending shows; the chain's key goes at its end.
func TestAHandAskOfAHeldBranchAnswersAtOnce(t *testing.T) {
ctx := context.Background()
held := &memStore{vals: map[string][]byte{}}
takeIns := &chainStore{vals: map[string][]byte{}, ended: make(chan string, 4)}
ix := &index.Indexer{Held: held, TakeIns: takeIns, Logf: func(string, ...any) {},
Now: func() time.Time { return time.Date(2026, 11, 22, 21, 7, 0, 0, time.UTC) }}
handlers := map[string]func(jetstream.Msg){}
s := &sourceMoved{ctx: ctx, ix: ix,
branches: func(context.Context) ([]string, error) { return []string{"main"}, nil },
bind: func(_ context.Context, branch string, each func(jetstream.Msg)) (func(), error) {
handlers[branch] = each
return func() {}, nil
},
logf: func(string, ...any) {}}
s.refresh()
for _, n := range []int{114, 115, 116} {
m := &fakeMsg{subject: fmt.Sprintf("mesh.seat.mesh-delivery.event.source-moved.main.%d", n),
data: []byte(fmt.Sprintf(`{"v":1,"branch":"main","source":%d,"call":"%d123456789abcde","heads":[]}`, n, n))}
handlers["main"](msgOf{f: m})
}
a := actor{ix, s}
s.again.Lock() // the chain waits for the lock, so it is still running at the second ask
if r := a.HeldAgain(ctx, "main"); r.Answer != "chain started at source 114, 2 wait" {
s.again.Unlock()
t.Fatalf("the first ask answered %+v, want the chain started at once", r)
}
r := a.HeldAgain(ctx, "main")
var pending any
var err error
for _, tool := range index.HeldTools(held, takeIns, nil, ix.Now, nil) {
if tool.Name == index.PendingTool {
pending, err = tool.Run(map[string]any{})
}
}
s.again.Unlock()
chains := pending.(index.PendingAnswer).Chains
if r.Answer != "a chain runs: source 114 taken in since 2026-11-22T21:07:00Z, 2 wait" || !r.Held {
t.Errorf("the ask meeting the chain answered %+v, want its state at once", r)
}
if err != nil || len(chains) != 1 || chains[0].Branch != "main" || chains[0].Source != 114 || chains[0].Waiting != 2 {
t.Errorf("indexer_pending shows chains %+v (%v), want main's at 114 with 2 waiting", chains, err)
}
if k := <-takeIns.ended; k != index.ChainKey("main") {
t.Errorf("the key %s went, want main's chain", k)
}
}
// revisionObjects is the catalog revisions' object bucket in memory.
type revisionObjects map[string][]byte
@@ -33,8 +33,8 @@ type takerIn interface {
// written back, by compare-and-set at its revision, with what the indexer stored or why not. A value
// answered already (this indexer's own write) or deleted is left.
func takenIn(ctx context.Context, ix takerIn, kv jetstream.KeyValue, e jetstream.KeyValueEntry, logf func(string, ...any)) {
if e.Operation() != jetstream.KeyValuePut || strings.HasPrefix(e.Key(), index.RunningPrefix) {
return // a running take-in's waiting-on is the indexer's own record, no ask (H-A-409)
if e.Operation() != jetstream.KeyValuePut || strings.HasPrefix(e.Key(), index.RunningPrefix) || strings.HasPrefix(e.Key(), index.ChainPrefix) {
return // a running take-in's waiting-on and a running chain are the indexer's own records, no ask (H-A-409, H-A-497)
}
a, err := index.DecodeTakeIn(e.Value())
if err != nil {
@@ -51,6 +51,9 @@ type PendingAnswer struct {
Held []HeldTakeIn `json:"held"`
// Running are the take-ins that run, each with what it waits on (design 47 H2 §803, H-A-409).
Running []RunningTakeIn `json:"running,omitempty"`
// Chains are the running chains of held take-ins, each branch's source being taken in, since when and how many wait
// (H-A-497 addendum).
Chains []HeldChain `json:"chains,omitempty"`
}
// ErrHeldUnwritten says a source-moved that could not be taken in is not written into the state held either: its message
@@ -167,26 +170,153 @@ func (ix *Indexer) unhold(ctx context.Context, branch string, source int64) {
}
}
// TakeHeldIn takes every branch's held source revisions in, each branch in its order, on the indexer's own room and at its
// start (H-A-114, H-A-118): a branch stops at the first that still cannot be taken in, which stays held with those behind it.
// TakeHeldIn takes every branch's held source revisions in, each branch in its order, on the indexer's own room, at its
// start and by hand (H-A-114, H-A-118): a branch stops at the first that still cannot be taken in, which stays held with those
// behind it. Once a held one is taken in, the next held of its branch is taken in at once, each such start said in the journal
// (design 47 H2 H-A-497).
func (ix *Indexer) TakeHeldIn(ctx context.Context) {
all, err := ReadHeld(ctx, ix.Held)
if err != nil {
ix.logf("take-in: the state %s is not read, so no held take-in is taken in again now: %v", HeldState, err)
return
}
stopped := map[string]bool{}
stopped, landed := map[string]bool{}, map[string]int64{}
behind := map[string]int{}
for _, h := range all {
behind[h.Branch]++
}
for i, h := range all {
behind[h.Branch]--
if stopped[h.Branch] {
continue
}
if _, err := ix.TakeInSource(ctx, h.Event()); err != nil {
if prev, ok := landed[h.Branch]; ok {
ix.logf("take-in: held source %d of %s taken in next, after %d (H-A-497)", h.Source, h.Branch, prev)
}
ix.writeChain(ctx, HeldChain{Branch: h.Branch, Source: h.Source, Since: ix.now().UTC(), Waiting: behind[h.Branch]})
if _, err := ix.TakeInSource(ctx, h.Event()); err == nil {
landed[h.Branch] = h.Source
} else {
ix.logf("take-in: source revision %d of %s is still held: %v", h.Source, h.Branch, err)
stopped[h.Branch] = true
}
// The chain of a branch ends at its first held again or its last held (H-A-497 addendum).
if stopped[h.Branch] || !slices.ContainsFunc(all[i+1:], func(n HeldTakeIn) bool { return n.Branch == h.Branch }) {
ix.endChain(ctx, h.Branch)
}
}
}
// ChainPrefix is the takeins keys of the chains of held take-ins: `chain.<branch>`, the branch escaped as a key's name is,
// holding the branch's chain while it runs (design 47 H2 H-A-497 and its addendum): written at each step, deleted at its end.
const ChainPrefix = "chain."
// ChainKey is the takeins key of branch's chain.
func ChainKey(branch string) string { return ChainPrefix + keys.EscapeName(branch) }
// HeldChain is a running chain of a branch's held take-ins (H-A-497 addendum): the source being taken in, since when, and
// how many held sources of the branch wait behind it.
type HeldChain struct {
Branch string `json:"branch"`
Source int64 `json:"source"`
Since time.Time `json:"since"`
Waiting int `json:"waiting"`
}
// writeChain writes branch's chain at its step c into the state takeins; a failed write is said.
func (ix *Indexer) writeChain(ctx context.Context, c HeldChain) {
if ix.TakeIns == nil {
return
}
data, err := json.Marshal(c)
if err == nil {
err = write(ctx, ix.TakeIns, ChainKey(c.Branch), func([]byte, bool) ([]byte, bool, error) { return data, false, nil })
}
if err != nil {
ix.logf("take-in: the chain of %s at source revision %d is not written into %s: %v", c.Branch, c.Source, TakeInsState, err)
}
}
// EndChain deletes branch's chain from the state takeins once the take-in its ask started returned, so a chain whose held
// sources another act took first is never left running.
func (ix *Indexer) EndChain(ctx context.Context, branch string) { ix.endChain(ctx, branch) }
// EndChains deletes every chain the state takeins holds, at the indexer's start (H-A-497 addendum): no chain runs before the
// start's take-in, so a key left by a stop between a chain's last take-in and its end would answer "a chain runs" for good.
func (ix *Indexer) EndChains(ctx context.Context) {
chains, err := ReadChains(ctx, ix.TakeIns)
if err != nil {
ix.logf("take-in: the chains in %s are not read, so none left by a stop is deleted: %v", TakeInsState, err)
return
}
for _, c := range chains {
ix.logf("take-in: the chain of %s at source revision %d, left by a stop, is deleted at the start", c.Branch, c.Source)
ix.endChain(ctx, c.Branch)
}
}
// endChain deletes branch's chain from the state takeins.
func (ix *Indexer) endChain(ctx context.Context, branch string) {
if ix.TakeIns == nil {
return
}
if err := write(ctx, ix.TakeIns, ChainKey(branch), func([]byte, bool) ([]byte, bool, error) { return nil, true, nil }); err != nil {
ix.logf("take-in: the chain of %s is not deleted from %s: %v", branch, TakeInsState, err)
}
}
// StartChain writes branch's chain at its first held source, before the chain is taken in beside the asks (H-A-497
// addendum), so an ask after it finds it running; it answers that chain.
func (ix *Indexer) StartChain(ctx context.Context, held []HeldTakeIn) HeldChain {
c := HeldChain{Branch: held[0].Branch, Source: held[0].Source, Since: ix.now().UTC(), Waiting: len(held) - 1}
ix.writeChain(ctx, c)
return c
}
// ChainOf is branch's running chain in the state takeins, and whether one runs.
func (ix *Indexer) ChainOf(ctx context.Context, branch string) (HeldChain, bool, error) {
if ix.TakeIns == nil {
return HeldChain{}, false, nil
}
v, _, found, err := ix.TakeIns.Get(ctx, ChainKey(branch))
if err != nil || !found {
return HeldChain{}, false, err
}
var c HeldChain
if err := json.Unmarshal(v, &c); err != nil {
return HeldChain{}, false, fmt.Errorf("%s.%s: %w", TakeInsState, ChainKey(branch), err)
}
return c, true, nil
}
// ReadChains are the running chains the state takeins holds (H-A-497 addendum), each branch's once.
func ReadChains(ctx context.Context, st Store) ([]HeldChain, error) {
if st == nil {
return nil, nil
}
ks, err := st.Keys(ctx)
if err != nil {
return nil, err
}
slices.Sort(ks)
var out []HeldChain
for _, k := range ks {
if !strings.HasPrefix(k, ChainPrefix) {
continue
}
v, _, found, err := st.Get(ctx, k)
if err != nil {
return nil, err
}
var c HeldChain
if !found || json.Unmarshal(v, &c) != nil {
continue
}
out = append(out, c)
}
return out, nil
}
// SkipTakeIn ends a held source revision unwritten by hand (indexer_take_in_skip, §744): it says take-in.taken with no entries,
// skipped, by and why, and deletes the branch's held take-in; the caller acknowledges the source-moved.
func (ix *Indexer) SkipTakeIn(ctx context.Context, e meshdelivery.SourceMovedEvent, by, why string) error {
@@ -236,7 +366,7 @@ func HeldTools(held, takeIns Store, ask func(key string, value []byte) (TakeInAs
{Name: PendingTool,
Description: "Each watched branch's held take-in (design 47 H §744): the source revision of the gate's source-moved the indexer " +
"could not take in (the catalog store full, a read of the forge unanswered), why and since when, in order, each kept here once " +
"acknowledged and taken in again on the indexer's room and at its start; and each running take-in that waits over a minute on another part, its waiting-on (part, verb, since). indexer_take_in_pending takes it again now, indexer_take_in_skip ends it unwritten.",
"acknowledged and taken in again on the indexer's room and at its start; each running take-in that waits over a minute on another part, its waiting-on (part, verb, since); and each running chain of held take-ins, the source being taken in, since when and how many wait. indexer_take_in_pending takes it again now, indexer_take_in_skip ends it unwritten.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) {
h, err := ReadHeld(context.Background(), held)
@@ -244,11 +374,16 @@ func HeldTools(held, takeIns Store, ask func(key string, value []byte) (TakeInAs
return PendingAnswer{Held: h}, err
}
r, err := ReadRunning(context.Background(), takeIns)
return PendingAnswer{Held: h, Running: r}, err
if err != nil {
return PendingAnswer{Held: h, Running: r}, err
}
c, err := ReadChains(context.Background(), takeIns)
return PendingAnswer{Held: h, Running: r, Chains: c}, err
}},
{Name: TakeInPendingTool,
Description: "Take a watched branch's held source-moved in again now (design 47 H §744), as the indexer's room would: " +
"answers whether it was taken in. indexer_pending names the held branches.",
"the held sources are taken in in order beside the asks, and it answers at once that the chain started at a source and " +
"how many wait, or, while a chain runs, its state (design 47 H2 H-A-497). indexer_pending names the held branches and the running chains.",
Input: map[string]any{"type": "object", "required": []string{"branch"}, "properties": map[string]any{
"branch": map[string]any{"type": "string", "description": "the watched branch, as indexer_pending names it"},
"why": map[string]any{"type": "string", "description": "why it is taken again now"}}},
@@ -73,8 +73,8 @@ func pinObject(key string) (string, bool) {
}
// HeardPins applies one event of the seat mesh-pipeline-runner the indexer's durable consumers gave it (design 47 H §749): a
// pipeline-started pins the revision it names under the record `pipeline.<pipeline>`, its pipeline-ended frees it and every
// other revision the record pins (H-A-147). A body
// pipeline-started pins the revision it names, and each revision its movers are kept at (design 47 H2 H-A-496), under the
// record `pipeline.<pipeline>`, its pipeline-ended frees it and every other revision the record pins (H-A-147). A body
// that is no such event, or names no revision, changes nothing; an error leaves the event unacknowledged, so the bus gives it
// again; one applied twice changes nothing.
func (ix *Indexer) HeardPins(ctx context.Context, started *runner.PipelineStarted, ended *runner.PipelineEnded) error {
@@ -83,7 +83,15 @@ func (ix *Indexer) HeardPins(ctx context.Context, started *runner.PipelineStarte
}
switch {
case started != nil && started.Revision > 0 && started.Pipeline != "":
if err := ix.pin(ctx, PinKey(started.Branch, started.Revision), PipelineRecord(started.Pipeline)); err != nil {
record := PipelineRecord(started.Pipeline)
if err := ix.pin(ctx, PinKey(started.Branch, started.Revision), record); err != nil {
return err
}
// Every revision the pipeline's movers are kept at is pinned under its record too, so no judge removes one it still
// reads (design 47 H2 H-A-496); the latest started's kept set is the pipeline's kept pins, so a kept revision the
// record pins that this started no longer names is freed (H-A-496 addendum). A kept revision is always newer than the
// pipeline's own (a re-pin of its own source, H-A-283), so its own revision and its validate base stay pinned.
if err := ix.pinKept(ctx, started.Branch, started.Revision, started.Kept, record); err != nil {
return err
}
// The reservations of the pipeline's revision settle at its start, if they gather (design 47 H2 §805, H-A-424 (1)).
@@ -105,9 +113,14 @@ func (ix *Indexer) HeardPins(ctx context.Context, started *runner.PipelineStarte
}
}
}
// A pipeline that did not pass withdraws the reservations its revision holds (design 47 H2 §805, H-A-418 (1)).
// A pipeline that did not pass withdraws the reservations its revision holds of its own movers, never another open
// pipeline's at that revision (design 47 H2 §805, H-A-418 (1), H-A-479 second addendum).
if ended.Outcome != runner.PipelineEndedOutcomePassed {
if err := ix.Withdraw(ctx, ended.Branch, ended.Revision); err != nil {
movers := make([]string, 0, len(ended.Movers))
for _, m := range ended.Movers {
movers = append(movers, m.Module)
}
if err := ix.Withdraw(ctx, ended.Branch, ended.Revision, movers); err != nil {
return fmt.Errorf("the reservations of %s are not withdrawn: %w", BranchObject(ended.Branch, ended.Revision), err)
}
}
@@ -224,6 +237,41 @@ func (ix *Indexer) unpinElsewhere(ctx context.Context, record string) error {
return nil
}
// pinKept pins each of kept, the revisions a pipeline of branch at revision own keeps movers at, under record, and frees
// every revision newer than own the record pins that kept does not name (design 47 H2 H-A-496 and its addendum).
func (ix *Indexer) pinKept(ctx context.Context, branch string, own int64, kept []int64, record string) error {
for _, r := range kept {
if r <= 0 || r == own {
continue
}
if err := ix.pin(ctx, PinKey(branch, r), record); err != nil {
return err
}
}
pinKeys, err := ix.Pins.Keys(ctx)
if err != nil {
return err
}
for _, k := range pinKeys {
b, r, ok := ParsePinKey(k)
if !ok || b != branch || r <= own || slices.Contains(kept, r) {
continue
}
v, _, found, err := ix.Pins.Get(ctx, k)
if err != nil {
return err
}
var pv PinValue
if !found || json.Unmarshal(v, &pv) != nil || !slices.Contains(pv.Records, record) {
continue
}
if err := ix.unpin(ctx, k, record); err != nil {
return err
}
}
return nil
}
// PipelineRecord is the record a pipeline pins its revision under: `pipeline.<branch>.<source>` (design 47 H §743, A-449a).
func PipelineRecord(pipeline string) string { return "pipeline." + pipeline }
@@ -13,6 +13,47 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// Design 47 H2 H-A-496 and its addendum: a pipeline-started pins the pipeline's own revision and each revision its movers
// are kept at under the pipeline's record; a later started (said again at a re-pin) is the pipeline's kept set, freeing a
// kept revision it no longer names but never the pipeline's own; pipeline-ended frees them all.
func TestAPipelinesKeptRevisionsArePinnedUntilItEnds(t *testing.T) {
ctx := context.Background()
pending := uint64(1) // the keeps judge nothing while the consumer is behind
ix := &Indexer{Module: testSelf, Revisions: newMemObjects(1 << 20), Pins: newMem(), Findings: newFindings(),
Now: func() time.Time { return time.Date(2026, 11, 22, 20, 0, 0, 0, time.UTC) }, PinsPending: func(context.Context) (uint64, error) { return pending, nil }}
kept := func() []string {
n, _ := ix.Revisions.Names(ctx)
return slices.DeleteFunc(n, func(s string) bool { _, _, ok := RevisionGroup(s); return !ok })
}
reader := meshcatalog.CatalogEntry{Module: "reader", Repository: "novox/r", Manifest: map[string]any{}}
for source := int64(1); source <= 6; source++ {
e := reader
e.Commit = fmt.Sprintf("c%d", source)
if err := ix.KeepBranchEntries(ctx, "main", source, map[string]meshcatalog.CatalogEntry{"reader": e}, nil); err != nil {
t.Fatal(err)
}
}
pending = 0
heard := func(started *runner.PipelineStarted, ended *runner.PipelineEnded, want ...string) {
t.Helper()
if err := ix.HeardPins(ctx, started, ended); err != nil {
t.Fatal(err)
}
ix.JudgePins(ctx)
if got := kept(); !slices.Equal(got, want) {
t.Errorf("kept %v, want %v", got, want)
}
}
heard(&runner.PipelineStarted{Branch: "main", Pipeline: "main.1", Revision: 1, Kept: []int64{2, 3, 4}}, nil,
"main.1", "main.2", "main.3", "main.4", "main.6")
if v, _, _, _ := ix.Pins.Get(ctx, "main.3"); !slices.Equal(mustRecords(t, v), []string{"pipeline.main.1"}) {
t.Errorf("the pin of main.3 holds %s, want the pipeline's record", v)
}
heard(&runner.PipelineStarted{Branch: "main", Pipeline: "main.1", Revision: 1, Kept: []int64{3, 4}}, nil,
"main.1", "main.3", "main.4", "main.6")
heard(nil, &runner.PipelineEnded{Branch: "main", Pipeline: "main.1", Revision: 1, Outcome: runner.PipelineEndedOutcomeFailed}, "main.6")
}
// Design 47 H §749 (G §579, A-169, A-171): the indexer pins a revision on a pipeline-started that names it and frees it on its
// pipeline-ended, counts a record once, and removes a revision only while its consumers are caught up, judged against the pins
// its own state holds, never a count of pins stated: one two pipelines pin stays until both free it, one neither pinned nor
@@ -2,6 +2,7 @@ package index
import (
"context"
"encoding/json"
"fmt"
"slices"
"strings"
@@ -100,9 +101,10 @@ func TestAReleaseRepinsAnEntryNamingItsPackageWithNoPin(t *testing.T) {
t.Errorf("said %+v, want catalog-revision of each branch with the release's call", said)
}
// Design 47 H2 §805, H-A-418, H-A-420, H-A-424, H-A-436: a pipeline reserving twenty packages of mesh-sdk in main's
// revision 2 keeps one re-pin revision of main when its gathering settles, at its first step-ended; its release then
// keeps none on main, and a pipeline that did not pass withdraws its reservations back to the newest released version.
// Design 47 H2 H-A-495 (ending H-A-418 (2), H-A-424 (4)), H-A-436: a pin names only a released version. A pipeline
// reserving twenty packages of mesh-sdk in main's revision 2 moves no pin when its gathering settles; the release of
// the reserved version re-pins g in one revision; a pipeline that did not pass withdraws its reservations and moves
// nothing; and a pin held on a version never released is moved to the newest released at the next re-pin, said.
ix.Files = func(_ context.Context, _, _ string, dirs []string) (map[string]map[string]string, error) {
out := map[string]map[string]string{}
for _, d := range dirs {
@@ -110,6 +112,8 @@ func TestAReleaseRepinsAnEntryNamingItsPackageWithNoPin(t *testing.T) {
}
return out, nil
}
var lines []string
ix.Logf = func(format string, args ...any) { lines = append(lines, fmt.Sprintf(format, args...)) }
heard := newMem()
ix.Heard = heard
revision := BranchObject("main", 2)
@@ -120,6 +124,7 @@ func TestAReleaseRepinsAnEntryNamingItsPackageWithNoPin(t *testing.T) {
}
return rev.Revision
}
const sdkGo = "git.novox.be/novox/mesh-sdk/go"
for i := range 20 {
e := meshbuilds.VersionReservedEvent{Module: "mesh-sdk", Artifact: fmt.Sprintf("mesh-sdk:p%d", i), Path: "mesh-sdk/go", Version: "0.1.28", Revision: revision}
if err := ix.HearVersionReserved(ctx, e); err != nil {
@@ -129,35 +134,82 @@ func TestAReleaseRepinsAnEntryNamingItsPackageWithNoPin(t *testing.T) {
if _, _, open, _ := heard.Get(ctx, SettlingKey(revision)); !open || newest() != 2 {
t.Fatalf("twenty reservations: gathering open %v, main's newest %d, want open and no revision kept before it settles", open, newest())
}
if err := ix.Settle(ctx, revision); err != nil || newest() != 3 {
t.Fatalf("the gathering settled (%v) keeping main's newest %d, want one re-pin revision, 3", err, newest())
if err := ix.Settle(ctx, revision); err != nil || newest() != 2 {
t.Fatalf("the gathering settled (%v) keeping main's newest %d, want still 2: a reservation moves no pin", err, newest())
}
if now, _ := moduleOf(t, mods, "g"); now.Packages["git.novox.be/novox/mesh-sdk/go"] != "v0.1.28" {
t.Errorf("g after the reservations is pinned %v, want v0.1.28", now.Packages)
if now, _ := moduleOf(t, mods, "g"); now.Packages[sdkGo] != "v0.1.27" {
t.Errorf("g after the reservations is pinned %v, want the released v0.1.27", now.Packages)
}
if err := ix.Settle(ctx, revision); err != nil || newest() != 3 {
t.Errorf("a second step-ended settled (%v) keeping main's newest %d, want still 3", err, newest())
}
if _, err := ix.HearVersion(ctx, HeardVersion{Package: "mesh-sdk/go", GoModule: "git.novox.be/novox/mesh-sdk/go", Version: "0.1.28", Commit: strings.Repeat("1", 40), Published: true}); err != nil {
if _, err := ix.HearVersion(ctx, HeardVersion{Package: "mesh-sdk/go", GoModule: sdkGo, Version: "0.1.28", Commit: strings.Repeat("1", 40), Published: true}); err != nil {
t.Fatal(err)
}
if _, err := ix.Repin(ctx, "mesh-sdk", "0.1.28"); err != nil || newest() != 3 {
t.Errorf("the release of the reserved 0.1.28 re-pinned (%v) keeping main's newest %d, want no revision more", err, newest())
t.Errorf("the release of the reserved 0.1.28 re-pinned (%v) keeping main's newest %d, want one revision more, 3", err, newest())
}
if now, _ := moduleOf(t, mods, "g"); now.Packages[sdkGo] != "v0.1.28" {
t.Errorf("g after the release is pinned %v, want v0.1.28", now.Packages)
}
next := BranchObject("main", 3)
if err := ix.HearVersionReserved(ctx, meshbuilds.VersionReservedEvent{Module: "mesh-sdk", Artifact: "mesh-sdk:p0", Path: "mesh-sdk/go", Version: "0.1.29", Revision: next}); err != nil {
t.Fatal(err)
}
if err := ix.Settle(ctx, next); err != nil || newest() != 4 {
t.Fatalf("the reservation of 0.1.29 settled (%v) keeping main's newest %d, want 4", err, newest())
if err := ix.Settle(ctx, next); err != nil || newest() != 3 {
t.Fatalf("the reservation of 0.1.29 settled (%v) keeping main's newest %d, want still 3", err, newest())
}
if err := ix.Withdraw(ctx, "main", 3); err != nil || newest() != 5 {
t.Fatalf("the withdrawal (%v) kept main's newest %d, want 5", err, newest())
// H-A-479 second addendum: a pipeline at the same revision whose movers are others withdraws none of mesh-sdk's.
if err := ix.Withdraw(ctx, "main", 3, []string{"app"}); err != nil || newest() != 3 {
t.Fatalf("another pipeline's withdrawal (%v) kept main's newest %d, want 3: nothing of mesh-sdk withdrawn", err, newest())
}
if now, _ := moduleOf(t, mods, "g"); now.Packages["git.novox.be/novox/mesh-sdk/go"] != "v0.1.28" {
if _, _, kept, _ := heard.Get(ctx, ReservedKey(next, "mesh-sdk")); !kept {
t.Fatalf("another pipeline's withdrawal took mesh-sdk's reservation")
}
if err := ix.Withdraw(ctx, "main", 3, []string{"mesh-sdk"}); err != nil || newest() != 3 {
t.Fatalf("the withdrawal (%v) kept main's newest %d, want 3: the withdrawn reservation pinned nothing", err, newest())
}
if now, _ := moduleOf(t, mods, "g"); now.Packages[sdkGo] != "v0.1.28" {
t.Errorf("g after the withdrawal is pinned %v, want the newest released v0.1.28", now.Packages)
}
if _, _, kept, _ := heard.Get(ctx, ReservedKey(next, "mesh-sdk")); kept {
t.Errorf("the withdrawn reservation is still kept")
}
stale, _ := moduleOf(t, mods, "g")
stale.Packages = map[string]string{sdkGo: "v0.1.29"} // pinned before H-A-495 to the withdrawn reservation
mods.put("g", mustEncode(t, stale))
lines = nil
if _, err := ix.Repin(ctx, "mesh-sdk", "0.1.28"); err != nil {
t.Fatal(err)
}
if now, _ := moduleOf(t, mods, "g"); now.Packages[sdkGo] != "v0.1.28" {
t.Errorf("g pinned to the never released v0.1.29 is pinned %v after a re-pin, want v0.1.28", now.Packages)
}
if said := "g: pinned to " + sdkGo + " v0.1.29, never released; moved to v0.1.28"; !slices.Contains(lines, said) {
t.Errorf("the re-pin said %q, want the line %q", lines, said)
}
// H-A-479 second addendum: two pipelines' movers reserve at one revision while its gathering is open; withdrawing one
// pipeline's mover keeps the gathering and the other's reservation, withdrawing the last removes the gathering too.
six := BranchObject("main", 6)
for _, m := range []string{"one", "two"} {
raw, _ := json.Marshal(Reserved{V: 1, Revision: six, Module: m})
if err := heard.Create(ctx, ReservedKey(six, m), raw); err != nil {
t.Fatal(err)
}
}
if err := heard.Create(ctx, SettlingKey(six), []byte(`{}`)); err != nil {
t.Fatal(err)
}
if err := ix.Withdraw(ctx, "main", 6, []string{"one"}); err != nil {
t.Fatal(err)
}
_, _, gathering, _ := heard.Get(ctx, SettlingKey(six))
_, _, one, _ := heard.Get(ctx, ReservedKey(six, "one"))
_, _, two, _ := heard.Get(ctx, ReservedKey(six, "two"))
if !gathering || one || !two {
t.Fatalf("withdrawing one: gathering %v, one kept %v, two kept %v; want the gathering and two kept, one gone", gathering, one, two)
}
if err := ix.Withdraw(ctx, "main", 6, []string{"two"}); err != nil {
t.Fatal(err)
}
if _, _, gathering, _ := heard.Get(ctx, SettlingKey(six)); gathering {
t.Error("withdrawing the last reservation kept the revision's gathering")
}
}
@@ -17,13 +17,13 @@ import (
// A release re-pins once, at its reservation (design 47 H2 §805; H-A-418, H-A-420, H-A-424). The builder says
// version-reserved when it reserves a package's number, naming the revision `<branch>.<n>` its pipeline runs. The indexer
// writes the series' numbered version with the contents read at the commit of the module's entry in that revision, so
// acceptedSeries and releasedPins pin it, and keeps the reservation in its state heard under
// writes the series' numbered version with the contents read at the commit of the module's entry in that revision, and
// keeps the reservation in its state heard under
// `reserved.<revision>.<module>`, each key living reserved-keep. It gathers a pipeline's reservations per revision and
// writes one re-pin revision of that revision's branch when the gathering settles: at the first pipeline-started or
// step-ended of that pipeline heard after them, or at the expiry of the key settling.<revision>, written reserved-settle
// after the first. The release's package-published then
// moves no fingerprint. A pipeline-ended not passed whose revision holds reservations withdraws them: the series'
// after the first. A pin names only a released version, never a reservation (design 47 H2 H-A-495), so that re-pin
// moves no pin, and the release's re-pin (H-A-165) moves the importers. A pipeline-ended not passed whose revision holds reservations withdraws them: the series'
// numbered goes back to its newest released version and the importers are re-pinned to it.
// ReservedPrefix begins every key of the state heard holding a revision's reservations of one module.
@@ -350,20 +350,35 @@ func (ix *Indexer) settleNow(ctx context.Context, revision string) error {
return err
}
// Withdraw takes a pipeline-ended not passed of branch's revision in: each reservation the revision holds is withdrawn, its
// series' numbered set back to the newest released version, its importers re-pinned to that, and its key deleted.
func (ix *Indexer) Withdraw(ctx context.Context, branch string, revision int64) error {
// Withdraw takes a pipeline-ended not passed of branch's revision in: each reservation the revision holds of one of the
// ended pipeline's own movers is withdrawn, its series' numbered set back to the newest released version, its importers
// re-pinned to that, and its key deleted. Another open pipeline's reservations at the same revision are kept, and the
// revision's gathering is withdrawn only when none of them is left (design 47 H2 H-A-479 second addendum).
func (ix *Indexer) Withdraw(ctx context.Context, branch string, revision int64, movers []string) error {
if ix.Heard == nil {
return nil
}
name := BranchObject(branch, revision)
if _, rev, found, err := ix.Heard.Get(ctx, SettlingKey(name)); err == nil && found {
_ = ix.Heard.Delete(ctx, SettlingKey(name), rev) // the gathering is withdrawn with it
}
held, revs, err := ix.reservedOf(ctx, name)
if err != nil || len(held) == 0 {
all, revs, err := ix.reservedOf(ctx, name)
if err != nil {
return err
}
held := map[string]Reserved{}
for key, r := range all {
if slices.Contains(movers, r.Module) {
held[key] = r
} else {
delete(revs, key)
}
}
if len(held) == len(all) {
if _, rev, found, err := ix.Heard.Get(ctx, SettlingKey(name)); err == nil && found {
_ = ix.Heard.Delete(ctx, SettlingKey(name), rev) // the gathering is withdrawn with it
}
}
if len(held) == 0 {
return nil
}
for _, r := range held {
for _, one := range r.Reservations {
if err := ix.withdrawNumbered(ctx, one); err != nil {
@@ -198,14 +198,10 @@ func acceptedSeries(series map[string]SeriesPackage, m catalogue.Manifest, repos
return out, pins
}
// pinnedVersion is the version of a series its users are pinned to: its numbered one when a reservation wrote it with its
// contents and it is newer than the newest released (design 47 H2 §805, H-A-418 (2), H-A-424 (4)), else the newest; nil
// for none.
// pinnedVersion is the version of a series its users are pinned to: its newest released one, never a reservation's
// numbered one, which a pipeline that does not pass withdraws unpublished (design 47 H2 H-A-495, which ends H-A-418 (2)
// and H-A-424 (4)); nil for none.
func pinnedVersion(s SeriesPackage) *SeriesVersion {
if n := s.Numbered; n != nil && n.Contents != nil && (s.Newest == nil || CompareVersions("v"+s.Newest.Version, "v"+n.Version) < 0) {
p := publishedOfNumbered(*n.Contents)
return &SeriesVersion{Version: n.Version, Commit: n.Commit, Digest: n.Digest, Fingerprint: n.Fingerprint, Contents: contentsOfPublished(p)}
}
return s.Newest
}
@@ -371,11 +371,35 @@ func TestATakeInOnAFullStoreIsHeldAndSaidOnce(t *testing.T) {
len(held[0].Heads) != 1 || held[0].Heads[0] != moved.Heads[0] || !reflect.DeepEqual(held[0].Event(), moved) {
t.Fatalf("held = %+v, want 3 then 4, each with its event whole", held)
}
// H-A-497: behind them a source whose head the forge does not answer, and one more behind it.
for _, n := range []struct {
source int64
commit string
}{{5, "c-unread"}, {6, f.Merge}} {
e := moved
e.Source, e.Call, e.Heads = n.source, fmt.Sprintf("%d123456789abcdef", n.source), []meshdelivery.SourceMovedEventHeadsItem{{Repository: f.Repository, Commit: n.commit}}
if behind, err := ix.HoldBehind(ctx, e); err != nil || !behind {
t.Fatalf("source %d held behind: %v (%v)", n.source, behind, err)
}
}
var lines []string
ix.Logf = func(format string, args ...any) { lines = append(lines, fmt.Sprintf(format, args...)) }
ix.TakeIns = newMem()
// H-A-497 addendum: while the chain runs, its key names the source being taken in and how many wait behind it.
var steps []string
read := ix.Read
ix.Read = func(ctx context.Context, repository, sha, dir string) (RepoRead, error) {
if c, ok, _ := ix.ChainOf(ctx, "main"); ok {
steps = append(steps, fmt.Sprintf("%d/%d", c.Source, c.Waiting))
}
return read(ctx, repository, sha, dir)
}
objects.capacity = 1 << 22
if ok, err := ix.RoomAgain(ctx); err != nil || !ok || rooms != 1 {
t.Fatalf("room said %v %d times (%v), want once the store has room", ok, rooms, err)
}
// H-A-114: on room (and at start) the held ones are taken in again from the state held alone, in their order.
// H-A-114, H-A-497: on room (and at start, and by hand) the held ones are taken in again from the state held alone, in
// their order, each next one at once and said in the journal, until one is held again: those behind it stay held.
ix.TakeHeldIn(ctx)
var taken []int64
for _, e := range *said {
@@ -386,8 +410,38 @@ func TestATakeInOnAFullStoreIsHeldAndSaidOnce(t *testing.T) {
if !reflect.DeepEqual(taken, []int64{3, 4}) {
t.Errorf("taken again on room: %v of %+v, want 3 then 4", taken, *said)
}
if held, _ := ReadHeld(ctx, ix.Held); len(held) != 0 {
t.Errorf("held = %+v after the take-in, want none", held)
if held, _ := ReadHeld(ctx, ix.Held); len(held) != 2 || held[0].Source != 5 || held[1].Source != 6 {
t.Errorf("held = %+v after the take-in, want 5 held again and 6 behind it", held)
}
for _, want := range []string{
"take-in: held source 4 of main taken in next, after 3 (H-A-497)",
"take-in: held source 5 of main taken in next, after 4 (H-A-497)",
} {
if !slices.Contains(lines, want) {
t.Errorf("the journal holds no line %q: %q", want, lines)
}
}
for _, l := range lines {
if strings.Contains(l, "held source 6 of main taken in") {
t.Errorf("source 6 was taken in behind a held one: %q", l)
}
}
if !slices.Contains(steps, "4/2") || !slices.Contains(steps, "5/1") {
t.Errorf("the chain's key read at each take-in %v, want main at 4 with 2 waiting and at 5 with 1", steps)
}
// H-A-497 addendum: the chain's key in the state takeins goes at its end, here its first held again, and one a stop
// left is deleted at the start.
if chains, err := ReadChains(ctx, ix.TakeIns); err != nil || len(chains) != 0 {
t.Errorf("chains %+v (%v) after the chain stopped, want none", chains, err)
}
ix.writeChain(ctx, HeldChain{Branch: "main", Source: 9, Waiting: 1})
if ix.EndChains(ctx); func() bool { c, _ := ReadChains(ctx, ix.TakeIns); return len(c) != 0 }() {
t.Error("a chain's key left by a stop stays after the start")
}
ix.Read = read
ix.Logf, ix.TakeIns = nil, nil
for _, src := range []int64{5, 6} {
ix.unhold(ctx, "main", src)
}
// A skip ends a held source revision unwritten: take-in.taken with no entries, skipped, by and why; held is deleted.
ix.hold(ctx, meshdelivery.SourceMovedEvent{Branch: "nox-mesh", Source: 9, Call: "fedcba9876543210"}, "the catalog store is full")
@@ -236,6 +236,7 @@ func (ix *Indexer) recomputeLocked(ctx context.Context, overlay map[string]meshc
fp, none string
tcs map[string]meshcatalog.ToolchainUsed // by language, when there is a fingerprint
pkgs sdkstep.PackageVersions // the package versions, when there is a fingerprint
moved []string // the pins moved off a version never released, said (H-A-495)
}
done := map[string]result{}
visiting := map[string]bool{}
@@ -313,6 +314,7 @@ func (ix *Indexer) recomputeLocked(ctx context.Context, overlay map[string]meshc
// a pin is a released version, never a commit (H-A-161), and the version line's fingerprint takes it (H-A-167)
r.fp, r.pkgs = pinnedOf(f, series, k.manifest, k.cur.Repository, kept.Packages)
r.tcs = toolchainsUsed(toolchains)
r.moved = neverReleased(module, k.held.Packages, r.pkgs, series, k.manifest)
}
}
if _, merged := overlay[module]; !merged && (repository != "" && !trunk.SameRepository(k.cur.Repository, repository) &&
@@ -325,6 +327,9 @@ func (ix *Indexer) recomputeLocked(ctx context.Context, overlay map[string]meshc
}
done[module] = r
k.cur.Inputs2 = &kept
for _, line := range r.moved {
ix.logf("%s", line)
}
return r
}
finals := map[string]meshcatalog.ModulesByModuleValue{}
@@ -140,7 +140,9 @@ func (ix *Indexer) HearPackagePublished(ctx context.Context, p meshbuilds.Packag
}
var want []string
for _, a := range entry.Artifacts {
want = append(want, a.Ref)
if a.Kind != catalogue.ArtifactUpstream { // an upstream copy is released by its pinned digest, never published (H-A-486)
want = append(want, a.Ref)
}
}
key := PendingPrefix + keys.EscapeName(p.Module) + "." + keys.EscapeName(p.Version)
var have published
@@ -211,7 +213,15 @@ func (ix *Indexer) releaseVersion(ctx context.Context, p meshbuilds.PackagePubli
late := len(kept) > 0 && compareVersions(kept[0].Version, p.Version) > 0
at := ix.now().UTC()
v := meshcatalog.VersionEntry{V: int64(keys.Version), Module: p.Module, Version: p.Version, Source: have.Source, At: &at, Late: late}
pins, err := upstreamPins(entry)
if err != nil {
return err
}
for _, a := range entry.Artifacts {
if a.Kind == catalogue.ArtifactUpstream {
v.Artifacts = append(v.Artifacts, meshcatalog.VersionArtifact{Artifact: a.Ref, Digest: pins[a.Ref]})
continue
}
v.Artifacts = append(v.Artifacts, have.Artifacts[a.Ref])
}
slices.SortFunc(v.Artifacts, func(a, b meshcatalog.VersionArtifact) int { return strings.Compare(a.Artifact, b.Artifact) })
@@ -255,6 +265,46 @@ func (ix *Indexer) releaseVersion(ctx context.Context, p meshbuilds.PackagePubli
return ix.forgetPublished(ctx, pendingKey)
}
// upstreamPins are the pinned digests of the entry's upstream artifacts, by reference, read from its manifest's from
// (`<image>@sha256:<digest>`): design 51 copies an upstream image by that digest, so a release names it (H-A-486). An upstream
// artifact whose manifest names no pin refuses the release, naming it.
func upstreamPins(entry meshcatalog.CatalogEntry) (map[string]string, error) {
out := map[string]string{}
if !slices.ContainsFunc(entry.Artifacts, func(a meshcatalog.Artifact) bool { return a.Kind == catalogue.ArtifactUpstream }) {
return out, nil
}
raw, err := json.Marshal(entry.Manifest)
if err != nil {
return nil, err
}
var m struct {
Build struct {
Artifacts []struct {
Name string `json:"name"`
Kind string `json:"kind"`
From string `json:"from"`
} `json:"artifacts"`
} `json:"build"`
}
if err := json.Unmarshal(raw, &m); err != nil {
return nil, fmt.Errorf("the manifest of %s's entry does not read, so its upstream artifacts' pins are not known: %w", entry.Module, err)
}
for _, a := range m.Build.Artifacts {
if a.Kind != catalogue.ArtifactUpstream {
continue
}
if _, d, ok := strings.Cut(a.From, "@"); ok && strings.HasPrefix(d, "sha256:") {
out[ArtifactRefOf(entry.Module, a.Name)] = d
}
}
for _, a := range entry.Artifacts {
if _, ok := out[a.Ref]; a.Kind == catalogue.ArtifactUpstream && !ok {
return nil, fmt.Errorf("%s is an upstream artifact whose manifest names no pinned digest (from <image>@sha256:<digest>), so %s releases no version", a.Ref, entry.Module)
}
}
return out, nil
}
// trimVersions deletes the module's oldest versions beyond the kept 100, never its highest of any MAJOR.MINOR.
func (ix *Indexer) trimVersions(ctx context.Context, module string) error {
kept, err := ModuleVersions(ctx, ix.Versions, module) // newest first
@@ -423,6 +473,29 @@ func pinnedOf(f form, series map[string]SeriesPackage, m catalogue.Manifest, rep
return fingerprint.WithPins(f.fp, pins), pins
}
// neverReleased are the lines said of a module whose held pins (was) name a version above its series' newest released one,
// a reservation withdrawn unpublished, and whose new pins move it (design 47 H2 H-A-495): "<module>: pinned to <package>
// <version>, never released; moved to <version>". nil for none.
func neverReleased(module string, was map[string]string, pins sdkstep.PackageVersions, series map[string]SeriesPackage, m catalogue.Manifest) []string {
var out []string
for _, p := range slices.Sorted(maps.Keys(was)) {
old, now := strings.TrimPrefix(was[p], "v"), pins[p]
if _, ok := versionParts(old); !ok || was[p] == now {
continue
}
for _, s := range series {
if s.GoModule != p || s.Newest == nil || s.Series != m.AcceptedSeries(s.Name) {
continue
}
if in, _ := SeriesOf(old); in == s.Series && compareVersions(old, strings.TrimPrefix(s.Newest.Version, "v")) > 0 {
out = append(out, fmt.Sprintf("%s: pinned to %s %s, never released; moved to %s", module, p, was[p], cmp.Or(now, "no version")))
}
break
}
}
return out
}
// moduleOfKey is the module a modules key names; "" for none.
func moduleOfKey(key string) string {
if key == "" {
@@ -83,6 +83,36 @@ func TestAVersionIsReleasedOnceEveryArtifactIsPublished(t *testing.T) {
if compareVersions(oldest, "0.1.5") < 0 {
t.Errorf("the oldest kept is %s: the oldest were not the ones deleted", oldest)
}
// H-A-486: an upstream artifact is copied by its pinned digest and never published, so the version is released once every
// other artifact is, the upstream one named with the pin its manifest gives; one whose manifest names no pin releases none.
pin := "sha256:" + strings.Repeat("ab", 32)
nats := func(from string) map[string]meshcatalog.CatalogEntry {
return map[string]meshcatalog.CatalogEntry{"nats": {Module: "nats", Manifest: map[string]any{"build": map[string]any{"artifacts": []any{
map[string]any{"name": "server", "kind": "upstream", "from": from},
map[string]any{"name": "tools", "kind": "bundle", "from": "."}}}},
Artifacts: []meshcatalog.Artifact{{Ref: "nats:server", Kind: "upstream"}, {Ref: "nats:tools", Kind: "bundle", Language: "go"}}}}
}
for i, c := range []struct {
from, version string
released bool
}{{"nats:2.12-alpine@" + pin, "0.1.1", true}, {"nats:2.12-alpine", "0.1.2", false}} {
rev, objects, err := CatalogRevisionOf(meshcatalog.CatalogRevision{Revision: int64(4 + i), Kind: "trunk"}, nats(c.from))
if err != nil {
t.Fatal(err)
}
if err := KeepRevision(ctx, ix.Revisions, rev, objects); err != nil {
t.Fatal(err)
}
err = ix.HearPackagePublished(ctx, meshbuilds.PackagePublished{Module: "nats", Artifact: "nats:tools", Digest: "sha256:tools", Version: c.version, Source: 9, Branch: "main"})
got, _ := ModuleVersions(ctx, ix.Versions, "nats")
switch {
case c.released && (err != nil || len(got) != 1 || len(got[0].Artifacts) != 2 || got[0].Artifacts[0] != (meshcatalog.VersionArtifact{Artifact: "nats:server", Digest: pin})):
t.Fatalf("pinned %q: released %+v (%v); want the server named with its pin", c.from, got, err)
case !c.released && (err == nil || !strings.Contains(err.Error(), "no pinned digest") || len(got) != 1):
t.Fatalf("unpinned %q: released %+v (%v); want a refusal naming the pin", c.from, got, err)
}
}
}
// Design 47 G §372, A-350: the first fill records, once, each module's highest version the builder gave a number, numbered or
@@ -27,9 +27,10 @@ func TestTheJudge(t *testing.T) {
want: map[string]string{"a": `secret-`}},
{name: "an unknown field", raws: map[string]string{"a": `{"module":"a","version":"1.0","a-field-from-later":1}`},
want: map[string]string{"a": `"a-field-from-later"`}},
// H-A-465: the take-in sets a top-level word it does not know aside (ForInputs); the judgement still refuses it.
{name: "a word a newer SDK adds", raws: map[string]string{"a": `{"module":"a","version":"1.0","class":"core"}`},
want: map[string]string{"a": `"class"`}},
// H-A-465: the take-in sets a top-level word it does not know aside (ForInputs); the judgement still refuses it. The
// word is one no SDK knows: class, the word of H-A-465's night, is known since H2.
{name: "a word a newer SDK adds", raws: map[string]string{"a": `{"module":"a","version":"1.0","zzz-unknown-word":"core"}`},
want: map[string]string{"a": `"zzz-unknown-word"`}},
// Design 47 G §23, §28: a step's status is kept in the registration and never in a manifest.
{name: "a manifest naming a step's status", raws: map[string]string{"a": `{"module":"a","version":"1.0","policy":{"lint":"bypass"}}`},
want: map[string]string{"a": `"policy"`}},
@@ -19,11 +19,11 @@ func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio.
}
return []stdio.Tool{
verbTool[seat.StartInput](ask, "start", seat.VerbStart,
"Start by hand the delivering pipeline of the head of a watched branch for a module, by the seat verb start: the branch, the module and why. A head whose pipeline is written already is refused by the verb, naming it.",
obj([]string{"branch", "module", "why"}, map[string]any{"branch": str, "module": str, "why": str}),
"Start by hand the delivering pipeline of the head of a watched branch for a module, by the seat verb start: the branch, the module and why. A head whose pipeline is written already is refused by the verb, naming it. With modules instead of module, the named modules whose newest entry has no passed pipeline (a failed, cut or superseded one) are started again at the head, keyed <branch>.<revision>.again.<n>; a module whose newest entry passed is refused by name (design 47 H2 H-A-479).",
obj([]string{"branch", "why"}, map[string]any{"branch": str, "module": str, "modules": map[string]any{"type": "array", "items": str}, "why": str}),
func(in seat.StartInput) string {
if in.Branch == "" || in.Module == "" {
return "start names the watched branch and the module"
if in.Branch == "" || (in.Module == "") == (len(in.Modules) == 0) {
return "start names the watched branch and exactly one of the module or the modules"
}
return whyOf(in.Why)
}),
@@ -18,7 +18,11 @@ func TestVerbTools(t *testing.T) {
{"start", "runner_start", "seat:mesh-pipeline-runner.start", "", map[string]any{"branch": "main", "module": "i3", "why": "cancelled"},
seat.StartInput{Branch: "main", Module: "i3", Why: "cancelled"}},
{"start no why", "runner_start", "", "names why", map[string]any{"branch": "main", "module": "i3"}, nil},
{"start no module", "runner_start", "", "branch and the module", map[string]any{"branch": "main", "why": "x"}, nil},
{"start no module", "runner_start", "", "exactly one of the module or the modules", map[string]any{"branch": "main", "why": "x"}, nil},
// H-A-479: modules start the named modules again at the head; both together are refused.
{"start modules", "runner_start", "seat:mesh-pipeline-runner.start", "", map[string]any{"branch": "main", "modules": []any{"i3", "lib"}, "why": "failed"},
seat.StartInput{Branch: "main", Modules: []string{"i3", "lib"}, Why: "failed"}},
{"start module and modules", "runner_start", "", "exactly one of the module or the modules", map[string]any{"branch": "main", "module": "i3", "modules": []any{"lib"}, "why": "x"}, nil},
{"run", "runner_run", "seat:mesh-pipeline-runner.run", "", map[string]any{"members": []any{map[string]any{}}, "why": "x"},
seat.RunInput{Members: []seat.Member{{}}, Why: "x"}},
{"run no members", "runner_run", "", "members", map[string]any{}, nil},
@@ -96,3 +96,34 @@ func TestARevisionHeardIsHandedToItsStart(t *testing.T) {
t.Errorf("a body that is no event = %v, want it ended", err)
}
}
// H-A-479 addendum (2): a revision is held when the catalog seat's revision verb answers that revision, read fresh; none-yet,
// another revision or a refusal saying "no such object" is gone; another failure is said as it is.
func TestRevisionHeldReadsTheCatalogsRevisionFresh(t *testing.T) {
for _, c := range []struct {
name string
answer catalog.RevisionAnswer
err error
gone bool
fails bool
}{
{name: "held", answer: catalog.RevisionAnswer{Revision: &catalog.CatalogRevision{Revision: 258}}},
{name: "another revision", answer: catalog.RevisionAnswer{Revision: &catalog.CatalogRevision{Revision: 259}}, gone: true, fails: true},
{name: "none yet", answer: catalog.RevisionAnswer{NoneYet: true}, gone: true, fails: true},
{name: "removed", err: errors.New("revision main.258: no such object"), gone: true, fails: true},
{name: "unreachable", err: errors.New("no responders"), fails: true},
} {
var asked catalog.RevisionInput
call := func(_ string, body any) (json.RawMessage, error) {
asked = body.(catalog.RevisionInput)
if c.err != nil {
return nil, c.err
}
return json.Marshal(c.answer)
}
err := revisionHeld(call)("main", 258)
if (err != nil) != c.fails || errors.Is(err, pipeline.ErrRevisionGone) != c.gone || asked.Revision != 258 || asked.Branch != "main" {
t.Errorf("%s: %v (asked %+v)", c.name, err, asked)
}
}
}
@@ -4,10 +4,14 @@ import (
"encoding/json"
"errors"
"fmt"
"strings"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
catalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatlist"
@@ -65,5 +69,37 @@ func writeVerbs(h *pipeline.Hearer, s *pipeline.Starter, view func(string) (pipe
candidate := func(group, branch string, revision int64) (pipeline.Half, error) {
return readCandidate(calls.CallKept, catalog.CatalogRevisionEvent{Kind: "candidate", Group: group, Branch: branch, Revision: revision})
}
return pipeline.Verbs{Hearer: h, Starter: s, View: view, Candidate: candidate, Acts: meshhandactsclient.Recorder{Ask: calls.Call}}
return pipeline.Verbs{Hearer: h, Starter: s, View: view, Candidate: candidate, Acts: meshhandactsclient.Recorder{Ask: calls.Call},
RevisionHeld: revisionHeld(calls.CallKept)}
}
// revisionHeld reads the first page of a branch's catalog revision through the catalog seat's verb revision, never a kept
// copy, so a rerun reopening an ended pipeline knows whether the catalog still keeps its revision (design 47 H2 H-A-479
// addendum (2)): an answer of that revision is kept; none-yet, another revision, or a refusal saying the catalog's
// "no such object" is gone (pipeline.ErrRevisionGone); any other failure is said as it is.
func revisionHeld(call func(key string, body any) (json.RawMessage, error)) func(string, int64) error {
return func(branch string, revision int64) error {
raw, err := call(meshcatalogclient.RevisionVerb, catalog.RevisionInput{Branch: keys.EscapeName(branch), Revision: revision})
if err != nil {
if strings.Contains(err.Error(), "no such object") {
return fmt.Errorf("%w: %v", pipeline.ErrRevisionGone, err)
}
return err
}
answer, said, ok := buscalls.Unwrap(raw)
if !ok {
if strings.Contains(said, "no such object") {
return fmt.Errorf("%w: %s", pipeline.ErrRevisionGone, said)
}
return fmt.Errorf("%s answered: %s", meshcatalogclient.RevisionVerb, said)
}
var a catalog.RevisionAnswer
if err := json.Unmarshal(answer, &a); err != nil {
return fmt.Errorf("%s answered no revision: %w", meshcatalogclient.RevisionVerb, err)
}
if a.NoneYet || a.Revision == nil || a.Revision.Revision != revision {
return fmt.Errorf("%w: %s answered no revision %d of %s", pipeline.ErrRevisionGone, meshcatalogclient.RevisionVerb, revision, branch)
}
return nil
}
}
@@ -4,6 +4,7 @@ import (
"encoding/json"
"fmt"
"strconv"
"strings"
"sync"
"time"
@@ -38,8 +39,9 @@ func widenerOf(call func(key string, body any) (json.RawMessage, error), bound t
const (
envWidensReadBound = "MESH_RUNNER_WIDENS_READ_BOUND_FILE"
envRevisionsKept = "MESH_RUNNER_REVISIONS_KEPT_FILE"
// defaultReadBound is how long one read of widens waits for its answer: a few seconds, never the call's 30.
defaultReadBound = 5 * time.Second
// defaultReadBound is how long one read of widens waits for its answer: 30 s, so a cold grants-for (one that composes a
// revision's grants the grants part did not keep yet) is not cut (design 47 H2 H-A-478).
defaultReadBound = 30 * time.Second
// defaultRevisionsKept is how many catalog revisions the runner keeps once read; a revision of the catalog graph is some 1.4 MB.
defaultRevisionsKept = 6
)
@@ -149,10 +151,17 @@ func catalogRevision(call func(string, any) (json.RawMessage, error), kept *revi
for {
raw, err := call("seat:"+catalog.Seat+"."+catalog.VerbRevision, in)
if err != nil {
// A revision the catalog answers "no such object" for is gone (design 47 H2 H-A-496): a kept mover's wait on it ends.
if strings.Contains(err.Error(), "no such object") {
return pipeline.Half{}, fmt.Errorf("%w: %v", pipeline.ErrRevisionGone, err)
}
return pipeline.Half{}, err
}
answer, said, ok := buscalls.Unwrap(raw)
if !ok {
if strings.Contains(said, "no such object") {
return pipeline.Half{}, fmt.Errorf("%w: %s answered: %s", pipeline.ErrRevisionGone, catalog.VerbRevision, said)
}
return pipeline.Half{}, fmt.Errorf("%s answered: %s", catalog.VerbRevision, said)
}
var a catalog.RevisionAnswer
@@ -2,6 +2,7 @@ package main
import (
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
@@ -63,6 +64,19 @@ func TestCatalogRevisionIsKeptOnceRead(t *testing.T) {
if h, err := read("main", 0); err != nil || calls != 3 || len(h.Entries) != 2 {
t.Fatalf("the newest made calls %d, %+v, %v; want its first page only", calls, h, err)
}
// A revision the catalog answers "no such object" for is gone, whether refused or answered so (design 47 H2 H-A-496).
for _, gone := range []func(string, any) (json.RawMessage, error){
func(string, any) (json.RawMessage, error) {
return nil, fmt.Errorf("revision main.292: no such object")
},
func(string, any) (json.RawMessage, error) {
return json.RawMessage(`{"content":[{"text":"revision main.292: no such object"}],"isError":true}`), nil
},
} {
if _, err := catalogRevision(gone, newRevisionCache(1))("main", 292); !errors.Is(err, pipeline.ErrRevisionGone) {
t.Errorf("a revision the catalog has no object of reads %v, want it gone", err)
}
}
c := newRevisionCache(1)
c.put("main", pipeline.Half{Revision: 1})
c.put("main", pipeline.Half{Revision: 2})
@@ -115,7 +129,7 @@ func TestWidensSettings(t *testing.T) {
kept int
ok bool
}{
{"defaults", nil, 5 * time.Second, 6, true},
{"defaults", nil, 30 * time.Second, 6, true},
{"set", map[string]string{envWidensReadBound: "2s\n", envRevisionsKept: "3\n"}, 2 * time.Second, 3, true},
{"no duration", map[string]string{envWidensReadBound: "5"}, 0, 0, false},
{"no number", map[string]string{envRevisionsKept: "0"}, 0, 0, false},
@@ -11,6 +11,7 @@ import (
"sync"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/pipelinekey"
"git.novox.be/novox/mesh-sdk/go/keys"
)
@@ -28,23 +29,20 @@ func StepsKey(pipeline, mover string) string {
// stepsPrefix is the start of every mover key of one pipeline.
func stepsPrefix(pipeline string) string { return StepsKey(pipeline, "") }
// IsStepsKey says whether a key of the state pipelines is a mover's steps rather than a pipeline's record: `steps.` and a
// pipeline key of a take-in's (4 parts), a run's (5 parts, its third `run`), an unfinished mover's own (6 parts, its fourth
// `unfinished`, H-A-398) or a publish's (7 parts) and one mover.
// IsStepsKey says whether a key of the state pipelines is a mover's steps rather than a pipeline's record: `steps.`, a pipeline's
// key of any form the seat defines (a take-in's, a run's, a publish's, an unfinished mover's own or one started again at the head,
// H-A-398, H-A-479), read by the one parse of the seat's key forms (design 47 H2 H-A-485), and one mover.
func IsStepsKey(key string) bool {
parts := strings.Split(key, ".")
if parts[0] != "steps" {
rest, ok := strings.CutPrefix(key, "steps.")
if !ok {
return false
}
switch len(parts) {
case 4, 7:
return true
case 5:
return parts[2] == runToken
case 6:
return parts[3] == unfinishedToken
i := strings.LastIndex(rest, ".")
if i <= 0 || i == len(rest)-1 {
return false
}
return false
_, err := pipelinekey.Parse(rest[:i])
return err == nil
}
// RawState is the state pipelines as bytes: a key's value and revision (nil, 0 and no error when it has none), a create by
@@ -286,12 +286,27 @@ func (r Reads) List(in seat.ListInput) (seat.ListAnswer, error) {
}
rows := make([]seat.PipelineRow, 0, len(out))
for _, p := range out {
rows = append(rows, seat.PipelineRow{Pipeline: p.Pipeline, Call: p.Call, Started: p.Started, Ended: p.Ended, Outcome: p.Outcome,
MoverCount: p.MoverCount, Failed: firstFailed(steps[p.Pipeline])})
// A row carries its source, its revision and its steps counted per outcome (design 47 H2 H-A-467): a page's list is
// one read of the short form.
rows = append(rows, seat.PipelineRow{Pipeline: p.Pipeline, Call: p.Call, Source: p.Source, Revision: p.Revision,
Started: p.Started, Ended: p.Ended, Outcome: p.Outcome, MoverCount: p.MoverCount, Steps: stepCounts(steps[p.Pipeline]),
Failed: firstFailed(steps[p.Pipeline])})
}
return seat.ListAnswer{Rows: rows}, nil
}
// stepCounts is how many of steps hold each outcome (design 47 H2 H-A-467), nil for none.
func stepCounts(steps []seat.StepResult) map[string]int64 {
if len(steps) == 0 {
return nil
}
out := map[string]int64{}
for _, s := range steps {
out[s.Outcome]++
}
return out
}
// Stands is every step that has started and not ended, with what it waits on and since when (§75, §83): the watchman
// seeds its open waits from it.
func (r Reads) Stands() (seat.StandsAnswer, error) {
@@ -67,7 +67,7 @@ func TestReads(t *testing.T) {
Step: seat.StepResultStepApproval, Status: "required", Outcome: seat.StepResultOutcomeWaiting, On: seat.WaitOnPerson, Started: &t2}},
Unlogged: []seat.LogEntry{{Pipeline: "next.8", Module: "delta", Step: seat.StepResultStepBuild, What: seat.LogEntryWhatEnded, At: t1}}})
// A pipeline that failed: list's row names its first failed step (design 47 H2 H-A-376).
put(t, pipes, "gone.2", seat.Pipeline{Pipeline: "gone.2", Branch: "gone", Call: "call-2", Outcome: seat.PipelineOutcomeFailed, Started: &t0, Ended: &t1,
put(t, pipes, "gone.2", seat.Pipeline{Pipeline: "gone.2", Branch: "gone", Call: "call-2", Source: 2, Revision: 5, Outcome: seat.PipelineOutcomeFailed, Started: &t0, Ended: &t1,
Movers: []seat.Mover{{Module: "zeta", Commit: "g2"}}, Steps: []seat.StepResult{
{Module: "zeta", Step: seat.StepResultStepLint, Artifact: "zeta:program", Status: "optional", Outcome: seat.StepResultOutcomeFailed},
{Module: "zeta", Step: seat.StepResultStepUnit, Artifact: "zeta:program", Status: "required", Outcome: seat.StepResultOutcomeCouldNotRun, Why: "its node lacks node-build-node"}}})
@@ -150,13 +150,19 @@ func TestReads(t *testing.T) {
a, err := r.List(seat.ListInput{Branch: "main", Limit: 1})
return names(a.Rows), err
}, "main.7.gamma"},
// Design 47 H2 H-A-376: a row is the pipeline's key, call, start, end, outcome, movers' count and first failed step;
// Design 47 H2 H-A-376, H-A-467: a row is the pipeline's key, call, source, revision, start, end, outcome, movers' count,
// its steps per outcome and first failed step;
// the whole pipelines are answered only with full and a limit; with no limit the rows are the newest 20.
{"list's row of a failed pipeline", func() (string, error) {
a, err := r.List(seat.ListInput{Branch: "gone"})
raw, _ := json.Marshal(a.Rows)
return fmt.Sprint(string(raw), " ", len(a.Pipelines)), err
}, `[{"call":"call-2","ended":"2026-11-11T10:01:00Z","failed":{"artifact":"zeta:program","module":"zeta","outcome":"could not run","step":"unit","why":"its node lacks node-build-node"},"mover-count":1,"outcome":"failed","pipeline":"gone.2","started":"2026-11-11T10:00:00Z"}] 0`},
}, `[{"call":"call-2","ended":"2026-11-11T10:01:00Z","failed":{"artifact":"zeta:program","module":"zeta","outcome":"could not run","step":"unit","why":"its node lacks node-build-node"},"mover-count":1,"outcome":"failed","pipeline":"gone.2","revision":5,"source":2,"started":"2026-11-11T10:00:00Z","steps":{"could not run":1,"failed":1}}] 0`},
// Design 47 H2 H-A-467: a row counts the steps per outcome, a mover's kept steps (H-A-187) with them.
{"list's row counts its steps per outcome", func() (string, error) {
a, err := r.List(seat.ListInput{Branch: "next"})
return fmt.Sprint(a.Rows[0].Source, " ", a.Rows[0].Steps), err
}, "8 map[passed:2 waiting:1]"},
{"list's full needs a limit", func() (string, error) {
_, err := r.List(seat.ListInput{Full: true})
return "", err
@@ -25,7 +25,7 @@ func (h *Hearer) Released(ev catalog.VersionReleasedEvent, branch string) (int,
// A pipeline is keyed by its revision (H-A-213 (4)), so the pipelines of a source are those naming it, of either key
// form a source's pipelines were kept under.
var pkeys []string
for _, f := range []string{b + ".*", b + ".*.published.*.*", b + ".*." + unfinishedToken + ".*"} {
for _, f := range []string{b + ".*", b + ".*.published.*.*", b + ".*." + unfinishedToken + ".*", b + ".*." + againToken + ".*"} {
k, err := h.Store.Keys(f)
if err != nil {
return 0, fmt.Errorf("the pipelines of source %d are not listed: %w", ev.Source, err)
@@ -132,6 +132,11 @@ func (s *Starter) keepIn(key string, half Half, movers []seat.Mover) []seat.Move
s.logf("%s keeps the movers revision %d of its own source %d re-pinned, %s: %d steps ended superseded, %d asked again (H-A-283, H-A-284)",
key, half.Revision, half.Source, strings.Join(moved, ", "), len(ended), len(asks))
s.sayRePinned(p, kept, revisions, half.Revision)
// The re-pin says pipeline-started again with every revision its movers are kept at, so the indexer pins them (design
// 47 H2 H-A-496 and its addendum).
if keeps {
s.sayStartedPipeline(p, now)
}
for _, st := range ended {
if s.Say == nil {
break
@@ -66,7 +66,7 @@ func TestASameSourceRepinKeepsTheMoverInItsPipeline(t *testing.T) {
store := &MoverStore{Raw: newMemRaw()}
asks := &stepAsks{}
var said []seat.StepEvent
var repinned []string
var repinned, starts []string
var left [][]seat.StepResult
s := &Starter{Pipelines: store, Store: store, Steps: asks, Name: "the-runner", Now: ticking(), Revision: read,
Registration: func(m string) (catalog.Registration, bool) { return reg, m == "app" },
@@ -77,6 +77,9 @@ func TestASameSourceRepinKeepsTheMoverInItsPipeline(t *testing.T) {
if ev, ok := body.(seat.RePinnedEvent); ok {
repinned = append(repinned, fmt.Sprintf("%s %s %s %d", subject, ev.Pipeline, ev.Mover, ev.Revision))
}
if ev, ok := body.(seat.PipelineStarted); ok {
starts = append(starts, fmt.Sprintf("%s %v", ev.Pipeline, ev.Kept))
}
return nil
},
Left: func(_ string, leave, drop []seat.StepResult, _ string) { left = append(left, append(leave, drop...)) }}
@@ -133,6 +136,11 @@ func TestASameSourceRepinKeepsTheMoverInItsPipeline(t *testing.T) {
if kept, err := store.KeptRevisions(key); err != nil || kept["app"] != 11 {
t.Errorf("kept-revisions = %v (%v), want app at 11", kept, err)
}
// design 47 H2 H-A-496 and its addendum: the start names no kept revision, the re-pin says pipeline-started again with
// every revision its movers are kept at.
if want := []string{key + " []", key + " [11]"}; !slices.Equal(starts, want) {
t.Errorf("pipeline-started said %q, want %q", starts, want)
}
// The pin check reads the kept mover's entry at the revision it was kept at, never the pipeline's.
if n, err := s.AskPinHeld(store, key, "app", map[string]string{"git.novox.be/novox/mesh-sdk/go": "v0.1.26", "git.novox.be/novox/x/go": "v0.1.1"}, read); n == 0 || err != nil {
after, _, _ := store.Get(key)
@@ -255,6 +263,60 @@ func TestAKeptMoverWaitingOnItsRevisionSaysSo(t *testing.T) {
}
}
// design 47 H2 H-A-496: a kept mover whose kept revision the catalog answers "no such object" for waits no longer: the
// pipeline ends failed "kept revision 11 gone" at the placing, is said ended, frees its turn, and leaves its mover
// unfinished, so it rejoins the next pipeline.
func TestAKeptRevisionGoneEndsThePipeline(t *testing.T) {
reg, entries, _, read := repinFixture()
revision := func(branch string, rev int64) (Half, error) {
if rev == 11 {
return Half{}, fmt.Errorf("revision main.11: no such object: %w", ErrRevisionGone)
}
return read(branch, rev)
}
store := &MoverStore{Raw: newMemRaw()}
var turned, ended []string
u := memUnfinished{}
h := &Hearer{Store: store, Name: "the-runner", Unfinished: &Unfinished{Store: u},
Say: func(subject string, body any) error {
if ev, ok := body.(seat.PipelineEnded); ok {
ended = append(ended, ev.Pipeline+" "+ev.Outcome)
}
return nil
},
Turn: func(key string) { turned = append(turned, key) }}
registered := false
s := &Starter{Pipelines: store, Store: store, Steps: &stepAsks{}, Name: "the-runner", Now: ticking(), Revision: revision,
Say: func(string, any) error { return nil }, Ended: h.EndedAtPlacing,
Registration: func(m string) (catalog.Registration, bool) { return reg, registered && m == "app" }}
key := Key("main", 10)
if ok, err := s.Start(Begin{Branch: "main", Source: 41, Revision: 10, Entries: entries,
Movers: []seat.Mover{{Module: "app", Commit: "c1", Fingerprint: "src2:aa", Repository: "o/app"}}}); !ok || err != nil {
t.Fatalf("start = %v, %v", ok, err)
}
if n, err := s.Revised(revisionEvent(11), read); n != 0 || err != nil {
t.Fatalf("the re-pin started %d (%v)", n, err)
}
registered = true
lagging := func(string) (Half, bool) { return Half{Revision: 10, Source: 41, Entries: entries}, true }
if _, err := s.Registered(store, reg, lagging); err != nil {
t.Fatalf("the placing: %v", err)
}
p, _, err := store.Get(key)
if err != nil {
t.Fatal(err)
}
if p.Outcome != seat.PipelineOutcomeFailed || p.Ended == nil || !strings.HasPrefix(p.Why, "kept revision 11 gone") {
t.Fatalf("the pipeline = %s, %q, ended %v: want failed with kept revision 11 gone", p.Outcome, p.Why, p.Ended)
}
if !slices.Equal(ended, []string{key + " failed"}) || !slices.Equal(turned, []string{key}) {
t.Fatalf("said ended %v, turns freed %v: want %s's end said and its turn freed", ended, turned, key)
}
if _, held := u[UnfinishedKey("main", "app")]; !held {
t.Fatalf("app is not left unfinished, so it rejoins no pipeline: %v", u)
}
}
// rawKept reads a memRaw as the reads do.
type rawKept struct{ r *memRaw }
@@ -69,8 +69,19 @@ func keyRevision(b Begin) int64 {
}
// keyForms are the filters of every key form of the state pipelines: a revision's, a run's, a publish's kept from before
// a release revision started one pipeline (H-A-213 (2)), and an unfinished mover's pipeline of its own (H-A-398).
var keyForms = []string{"*.*", "*." + runToken + ".*", "*.*.published.*.*", "*.*." + unfinishedToken + ".*"}
// a release revision started one pipeline (H-A-213 (2)), an unfinished mover's pipeline of its own (H-A-398), and a pipeline
// started again at the head (H-A-479).
var keyForms = []string{"*.*", "*." + runToken + ".*", "*.*.published.*.*", "*.*." + unfinishedToken + ".*", "*.*." + againToken + ".*"}
// againToken is the third part of the key of a pipeline started again at the head by start with modules,
// `<branch>.<revision>.again.<n>` (design 47 H2 H-A-479 addendum (1)).
const againToken = "again"
// AgainPipelineKey is the key of the n-th pipeline started again at revision of branch, `<branch>.<revision>.again.<n>`
// (H-A-479 addendum (1)).
func AgainPipelineKey(branch string, revision int64, n int) string {
return seat.PipelinesByBranchRevisionAgainNKey(keys.EscapeName(branch), strconv.FormatInt(revision, 10), strconv.Itoa(n))
}
// AllKeys are every pipeline's key, of each key form (§746, §747; H-A-83).
func AllKeys(store interface {
@@ -336,6 +347,27 @@ func (s *Starter) holderless(p *seat.Pipeline, asks []Asked, now time.Time) ([]A
return nil, ended
}
// keptGone ends p failed at its placing, "kept revision <r> gone", when the catalog no longer holds revision r a mover of
// it is kept at (design 47 H2 H-A-496): each step not ended ends not asked, so its movers, whose steps never ran, are left
// unfinished and rejoin the next pipeline (§786), and its end frees its turn under pipelines-at-once. It answers the steps
// it ended, none when it had none; the pipeline's Ended says it ended.
func keptGone(p *seat.Pipeline, r int64, err error, now time.Time) []int {
why := fmt.Sprintf("kept revision %d gone", r)
ended := []int{}
for i := range p.Steps {
st := &p.Steps[i]
if !open(*st) && st.Outcome != seat.StepResultOutcomeWaiting {
continue
}
st.Outcome, st.Why, st.Ended, st.Ask, st.Shared = seat.StepResultOutcomeNotAsked, "the pipeline failed: "+why, &now, "", nil
p.Unlogged = append(p.Unlogged, endEntry(p.Pipeline, *st, now))
ended = append(ended, i)
}
p.Outcome, p.Why, p.Ended = seat.PipelineOutcomeFailed, fmt.Sprintf("%s (%v)", why, err), &now
p.EndCount++
return ended
}
// endedAtPlacing says a pipeline holderless ended at placing (A-470h): each step it ended in its step-ended, then the
// pipeline's end, through Ended; with none given it is said in the journal alone.
func (s *Starter) endedAtPlacing(p seat.Pipeline, steps []int) error {
@@ -405,18 +437,36 @@ func (s *Starter) create(key string, p seat.Pipeline) error {
return s.Pipelines.Create(key, raw)
}
// started is a pipeline's pipeline-started (§746): its key, branch, source, call, revision and movers.
func started(p seat.Pipeline, at time.Time) seat.PipelineStarted {
// started is a pipeline's pipeline-started (§746): its key, branch, source, call, revision and movers, and kept, every
// catalog revision its movers are kept at (design 47 H2 H-A-496), so the indexer pins each while the pipeline runs.
func started(p seat.Pipeline, at time.Time, kept []int64) seat.PipelineStarted {
return seat.PipelineStarted{V: 1, At: &at, Pipeline: p.Pipeline, Branch: p.Branch, Source: p.Source, Call: p.Call,
Revision: p.Revision, Movers: p.Movers, Published: p.Published, Run: p.Run}
Revision: p.Revision, Movers: p.Movers, Published: p.Published, Run: p.Run, Kept: kept}
}
// sayStartedPipeline says p's pipeline-started on <branch>.<revision> (§746).
// keptList is every distinct revision of kept-revisions, in order (H-A-496).
func keptList(kept map[string]int64) []int64 {
var out []int64
for _, r := range kept {
if r > 0 && !slices.Contains(out, r) {
out = append(out, r)
}
}
slices.Sort(out)
return out
}
// sayStartedPipeline says p's pipeline-started on <branch>.<revision> (§746), with the revisions its movers are kept at as
// its record's kept-revisions holds them (H-A-496): a re-pin says it again with the full list (H-A-496 addendum).
func (s *Starter) sayStartedPipeline(p seat.Pipeline, at time.Time) {
if s.Say == nil {
return
}
if err := s.Say(runnerclient.RevisionSubject(seat.EventPipelineStarted, p.Branch, subjectRevision(p)), started(p, at)); err != nil {
kept, err := keptOfStore(s.Store, p.Pipeline)
if err != nil {
s.logf("the kept-revisions of %s are not read, so its pipeline-started names no kept revision: %v", p.Pipeline, err)
}
if err := s.Say(runnerclient.RevisionSubject(seat.EventPipelineStarted, p.Branch, subjectRevision(p)), started(p, at, keptList(kept))); err != nil {
s.logf("pipeline-started of %s is not said: %v", p.Pipeline, err)
}
}
@@ -434,6 +484,8 @@ func (s *Starter) placeMovers(p *seat.Pipeline, reg func(module string) (catalog
if err != nil {
s.logf("the kept-revisions of %s are not read, so its movers are placed as movers not kept: %v", p.Pipeline, err)
}
var gone int64
var goneWhy error
all := entries
for i, m := range p.Movers {
// A mover that left for a newer pipeline is placed there, never here (H-A-223, H-A-361).
@@ -449,7 +501,13 @@ func (s *Starter) placeMovers(p *seat.Pipeline, reg func(module string) (catalog
entries := all
if rev := kept[m.Module]; rev > 0 {
var err error
if entries, err = s.keptEntries(p.Branch, rev); err != nil {
if entries, err = s.keptEntries(p.Branch, rev); errors.Is(err, ErrRevisionGone) {
// A kept revision the catalog no longer holds is never read: the pipeline ends failed (H-A-496).
if gone == 0 {
gone, goneWhy = rev, err
}
continue
} else if err != nil {
// It waits for its kept revision to be read, said once and carried on the mover (design 47 H2 §787).
if m.Unplaced != seat.MoverUnplacedKeptRevisionUnread || m.Revision != rev {
s.logf("%s: %s waits for its kept revision %d to be read (%v)", p.Pipeline, m.Module, rev, err)
@@ -509,6 +567,9 @@ func (s *Starter) placeMovers(p *seat.Pipeline, reg func(module string) (catalog
}
}
}
if gone > 0 {
return nil, unregistered, keptGone(p, gone, goneWhy, now), notAsked
}
if steps, ended := cycled(p, waits, unregistered, reg, all, now, s.Name); ended {
return nil, unregistered, steps, notAsked
} else {
@@ -691,7 +752,7 @@ func (s *Starter) Start(b Begin) (bool, error) {
}
s.ran(key)
s.sayNotAsked(p, notAsked)
if len(ended) > 0 {
if len(ended) > 0 || p.Ended != nil {
return true, s.endedAtPlacing(p, ended)
}
if s.Steps != nil && len(asks) > 0 {
@@ -867,16 +928,19 @@ func (s *Starter) placeWaiting(store Updater, due func(seat.Pipeline) bool, reg
if err != nil {
note(err)
}
if n == 0 {
// A pipeline its placing ended (a kept revision gone, H-A-496) is said ended though it placed no step.
if n == 0 && ended == nil {
continue
}
count++
s.logf("%s: %d steps placed from %s (A-327)", key, n, from)
// A pipeline whose steps were never asked is started by this placing (A-446a); the pipeline-started of its start,
// said already, is said again harmlessly.
s.sayStartedPipeline(p, now)
if n > 0 {
s.logf("%s: %d steps placed from %s (A-327)", key, n, from)
// A pipeline whose steps were never asked is started by this placing (A-446a); the pipeline-started of its start,
// said already, is said again harmlessly.
s.sayStartedPipeline(p, now)
}
s.sayNotAsked(p, notAsked)
if len(ended) > 0 {
if ended != nil {
if err := s.endedAtPlacing(p, ended); err != nil {
note(err)
}
@@ -922,7 +986,7 @@ func (s *Starter) placeOne(store Updater, key string, due func(seat.Pipeline) bo
s.logf("%s: %s has no registration yet: its steps wait on its registration, which places them (A-327)", key, m)
s.registrationMissing(m, key)
}
if len(p.Steps) == before {
if len(p.Steps) == before && p.Ended == nil {
// A mover that now waits for its kept revision, or no longer does, is written so (design 47 H2 §787).
if unplacedMarks(p) == marks {
return p, nil, nil, nil, 0, nil
@@ -655,6 +655,50 @@ func TestNoWriteOfATestRunActsOnAReadBeforeItsLatestChange(t *testing.T) {
t.Error("the step's finding was written before its run's end")
}
})
// H-A-479 addendum (2): a test step's rerun reopening an ended pipeline says its pipeline-started before its run is
// started again, so its revision is pinned before the step is asked.
t.Run("a test step's rerun reopening an ended pipeline pins its revision first", func(t *testing.T) {
f := newRunFixture()
p := f.start(t, 4, 9)
unit := stepNamed(p, "app:program", "unit")
run := unit.Shared[0].Run
ended := time.Now()
if _, err := f.h.OnStepEnded(stepSeatOf(t, "node-build-go"), "mesh.seat.node-build-go.event.step-ended.ace", StepEnded{ID: unit.Ask,
Pipeline: p.Pipeline, Module: "app", Commit: "c1", Fingerprint: "src2:aa", Step: "unit", Node: "ace", Outcome: "failed", Ended: &ended}); err != nil {
t.Fatal(err)
}
q, rev, _ := f.store.Get(p.Pipeline)
q.Outcome, q.Ended = seat.PipelineOutcomeFailed, &ended
if _, err := f.store.Update(p.Pipeline, q, rev); err != nil {
t.Fatal(err)
}
before, _, _ := f.runs.Get(run)
var started []string
f.s.Say = func(_ string, body any) error {
if ps, ok := body.(seat.PipelineStarted); ok {
if r, _, _ := f.runs.Get(run); r.Ask != before.Ask || r.Ended == nil {
t.Errorf("pipeline-started said after the run was started again (ask %s, was %s)", r.Ask, before.Ask)
}
started = append(started, ps.Pipeline)
}
return nil
}
v := Verbs{Hearer: f.h, Starter: f.s, View: func(string) (Half, bool) {
return Half{Entries: map[string]catalog.CatalogEntry{
"app": {Module: "app", Path: "modules/app", Artifacts: []catalog.Artifact{{Ref: "app:program", Language: "go"}, {Ref: "app:tools", Language: "go"}}},
"mesh-build-go": {Module: "mesh-build-go", Acts: []catalog.ActingRule{{Seat: "node-build-go", Step: "build", On: "go"}}}}}, true
}, Acts: &actLog{}, RevisionHeld: func(string, int64) error { return nil }}
a, err := v.Rerun("op@shanks", seat.RerunInput{Pipeline: p.Pipeline, Step: "unit", Artifact: "app:program", Why: "fixed"})
if err != nil {
t.Fatal(err)
}
if len(started) != 1 || started[0] != p.Pipeline {
t.Errorf("pipeline-started at the reopening = %v, want %s once", started, p.Pipeline)
}
if r, _, _ := f.runs.Get(run); r.Ask != a.Result.Ask || r.Ended != nil {
t.Errorf("the rerun's run = %+v; want the new ask running", r)
}
})
// A rerun whose read of the key is changed before its write (a step joining the ended run) writes from the latest read,
// carrying that reader, never answering the change as an error nor putting back the earlier readers.
t.Run("a rerun writes its run from the latest read", func(t *testing.T) {
@@ -4,6 +4,7 @@ import (
"errors"
"fmt"
"slices"
"strconv"
"strings"
"time"
@@ -29,8 +30,15 @@ type Verbs struct {
Acts views.HandActs
// Runs answers the read verb test-runs, answered by the process that holds test-runs-cap-mib (A-470i).
Runs RunsRead
// RevisionHeld says whether a branch's catalog revision is still kept, read through the catalog seat's verb revision
// at the time of the ask: nil when it is, an error wrapping ErrRevisionGone when it is removed (design 47 H2 H-A-479
// addendum (2)).
RevisionHeld func(branch string, revision int64) error
}
// ErrRevisionGone is a catalog revision the catalog no longer keeps (H-A-479 addendum (2)).
var ErrRevisionGone = errors.New("the catalog revision is gone")
func (v Verbs) now() time.Time { return v.Hearer.now() }
func (v Verbs) record(verb, what, why string) error {
@@ -275,13 +283,89 @@ func (v Verbs) EndAgain(_ string, in seat.EndAgainInput) (seat.EndAgainAnswer, e
// the ask saying it is a rerun and the caller the bus proved; a failed pipeline runs again and ends once more with its end
// count one higher (§325), an approval never asked waiting again. A review waits again; an approval is asked again by
// `ask-again`.
//
// A rerun of a step in an ended delivering pipeline reopens it: its revision is read first and the rerun refused by name,
// nothing asked, when the catalog removed it; once reopened its pipeline-started is said again, so the indexer pins its
// revision again until its next end (design 47 H2 H-A-479 addendum (2)).
func (v Verbs) Rerun(caller string, in seat.RerunInput) (seat.RerunAnswer, error) {
if in.Step == seat.StepResultStepApproval {
return seat.RerunAnswer{}, errors.New("an approval is asked again by ask-again, not rerun")
}
reopens, err := v.reopening(in.Pipeline)
if err != nil {
return seat.RerunAnswer{}, err
}
return v.rerun(caller, in, reopens)
}
// sayReopened says pipeline-started again for p, written reopened by a rerun, before its step is asked again, so the
// indexer pins its revision again before anything reads it (H-A-479 addendum (2)).
func (v Verbs) sayReopened(p seat.Pipeline, reopens bool) {
if !reopens || v.Starter == nil || p.Ended != nil {
return
}
v.Starter.sayStartedPipeline(p, v.now())
v.Starter.logf("%s reopened by a rerun: its pipeline-started is said again, so its revision %d is pinned again (H-A-479)", p.Pipeline, p.Revision)
}
// reopening says whether a rerun of pipeline key reopens an ended delivering pipeline, refusing it when its revision is
// gone (H-A-479 addendum (2)). A pipeline not read, a run's, or one the rerun refuses anyway is left to the rerun.
func (v Verbs) reopening(key string) (bool, error) {
p, _, err := v.Hearer.Store.Get(key)
if err != nil || p.Ended == nil || p.Run != "" || p.Revision <= 0 ||
p.Outcome == seat.PipelineOutcomeCancelled || p.Outcome == seat.PipelineOutcomeSuperseded {
return false, nil
}
// A reopening never builds beside an open pipeline carrying one of its movers at the same revision (H-A-479 third
// addendum).
if open, err := v.openBeside(p); err != nil {
return false, err
} else if open != "" {
return false, fmt.Errorf("the pipeline %s ended and is not reopened: its pipeline %s is running: nothing was asked", key, open)
}
if v.RevisionHeld != nil {
if err := v.RevisionHeld(p.Branch, p.Revision); errors.Is(err, ErrRevisionGone) {
return false, fmt.Errorf("the pipeline %s ended and its revision %d is gone; start the mover again at the head: nothing was asked (%v)", key, p.Revision, err)
} else if err != nil {
return false, fmt.Errorf("the pipeline %s ended and its revision %d is not read, so it is not reopened: nothing was asked: %w", key, p.Revision, err)
}
}
return true, nil
}
// openBeside is the key of another delivering pipeline of p's branch and revision, not ended, carrying one of p's movers it
// did not leave; empty when none (H-A-479 third addendum).
func (v Verbs) openBeside(p seat.Pipeline) (string, error) {
pkeys, err := branchKeys(v.Hearer.Store, p.Branch)
if err != nil {
return "", fmt.Errorf("the pipelines of %s are not listed, so %s is not reopened: nothing was asked: %w", p.Branch, p.Pipeline, err)
}
for _, key := range pkeys {
if key == p.Pipeline {
continue
}
o, _, err := v.Hearer.Store.Get(key)
if err != nil {
return "", fmt.Errorf("the pipeline %s is not read, so %s is not reopened: nothing was asked: %w", key, p.Pipeline, err)
}
if o.Run != "" || o.Ended != nil || o.Revision != p.Revision ||
(o.Outcome != seat.PipelineOutcomeRunning && o.Outcome != seat.PipelineOutcomeWaiting) {
continue
}
for _, m := range p.Movers {
if Moves(o, m.Module) && !slices.Contains(o.Superseded, m.Module) {
return key, nil
}
}
}
return "", nil
}
// rerun asks one step again (Rerun).
func (v Verbs) rerun(caller string, in seat.RerunInput, reopens bool) (seat.RerunAnswer, error) {
if p, _, err := v.Hearer.Store.Get(in.Pipeline); err == nil {
if i, err := stepOf(p, in.Module, in.Step, in.Artifact); err == nil && v.Hearer.TestRuns != nil && sharedRun(p.Steps[i]) != "" && BoundSeat(p.Steps[i].Seat) {
return v.rerunTest(caller, in, p.Steps[i])
return v.rerunTest(caller, in, p.Steps[i], reopens)
}
}
var ask *Asked
@@ -332,6 +416,7 @@ func (v Verbs) Rerun(caller string, in seat.RerunInput) (seat.RerunAnswer, error
if err != nil {
return seat.RerunAnswer{}, err
}
v.sayReopened(p, reopens)
if ask != nil {
v.Starter.carry(in.Pipeline, []Asked{*ask})
if err := askAll(v.Starter.Steps, in.Pipeline, []Asked{*ask}, func(commit string) bool { return v.Starter.recovered(in.Pipeline, commit) }, v.Starter.Asks.arm, v.Starter.logf); err != nil {
@@ -349,7 +434,7 @@ func (v Verbs) Rerun(caller string, in seat.RerunInput) (seat.RerunAnswer, error
// rerunTest asks a test step of a test run again (design 47 G §727, A-469l): it joins its key's run while that runs, reads one
// that started after the step's last end, or else starts a new run under a new ask, replacing the ended key by compare-and-set
// and carrying its readers into the new value, so the new run's end moves every former reader that did not pass.
func (v Verbs) rerunTest(caller string, in seat.RerunInput, st seat.StepResult) (seat.RerunAnswer, error) {
func (v Verbs) rerunTest(caller string, in seat.RerunInput, st seat.StepResult, reopens bool) (seat.RerunAnswer, error) {
h := v.Hearer
run := sharedRun(st)
if open(st) {
@@ -430,6 +515,7 @@ func (v Verbs) rerunTest(caller string, in seat.RerunInput, st seat.StepResult)
if err != nil {
return seat.RerunAnswer{}, err
}
v.sayReopened(p, reopens)
switch {
case join || read:
v.Starter.joinRun(run, reader)
@@ -649,10 +735,17 @@ func (v Verbs) Run(caller string, in seat.RunInput) (seat.RunAnswer, error) {
// Start starts by hand a delivering pipeline for the head of a watched branch the runner's catalog half holds, recorded in
// the hand-act log first (§306, §394): the pipeline of that branch's source revision and the module, as a take-in would
// start it. A head whose pipeline is written already starts nothing and is refused, naming the pipeline.
// start it. A head whose pipeline is written already starts nothing and is refused, naming the pipeline. With modules it
// starts the named modules again at the head instead (startAgain, H-A-479); exactly one of module or modules is given.
func (v Verbs) Start(_ string, in seat.StartInput) (seat.StartAnswer, error) {
if in.Module != "" && len(in.Modules) > 0 {
return seat.StartAnswer{}, errors.New("start names the module or the modules, not both: nothing was started")
}
if in.Branch != "" && len(in.Modules) > 0 {
return v.startAgain(in)
}
if in.Branch == "" || in.Module == "" {
return seat.StartAnswer{}, errors.New("start names the watched branch and the module")
return seat.StartAnswer{}, errors.New("start names the watched branch and the module or the modules")
}
if v.Starter == nil || v.View == nil {
return seat.StartAnswer{}, errors.New("the runner cannot start a pipeline: it holds no starter or no catalog half")
@@ -681,6 +774,117 @@ func (v Verbs) Start(_ string, in seat.StartInput) (seat.StartAnswer, error) {
return seat.StartAnswer{Pipeline: key}, nil
}
// startAgain starts by hand, recorded in the hand-act log first, a pipeline at the head of a watched branch carrying the
// named modules whose newest entry, the head's, has no passed pipeline (a failed, cut or superseded one), with the head's
// revision as its candidate and the take-in's tiers (design 47 H2 H-A-479): keyed `<branch>.<revision>.again.<n>`, n from 1,
// taken by writing on absence (addendum (1)). Its pipeline-started pins the head's revision as a take-in's does, and its
// versions are reserved at its build steps as a take-in's are. A module the head holds no entry of, or whose newest entry
// passed in a pipeline, is refused by name, nothing started.
func (v Verbs) startAgain(in seat.StartInput) (seat.StartAnswer, error) {
if v.Starter == nil || v.View == nil || v.Hearer == nil || v.Hearer.Store == nil {
return seat.StartAnswer{}, errors.New("the runner cannot start a pipeline again: it holds no starter, no catalog half or no state pipelines")
}
half, ok := v.View(in.Branch)
if !ok || half.Source <= 0 {
return seat.StartAnswer{}, fmt.Errorf("the catalog half of %s is not held at a source revision yet: nothing was started", in.Branch)
}
movers := make([]seat.Mover, 0, len(in.Modules))
var absent []string
for _, m := range in.Modules {
e, ok := half.Entries[m]
if !ok {
absent = append(absent, m)
continue
}
if slices.ContainsFunc(movers, func(x seat.Mover) bool { return x.Module == m }) {
continue
}
movers = append(movers, seat.Mover{Module: m, Commit: e.Commit, Fingerprint: e.Fp, Repository: e.Repository})
}
if len(absent) > 0 {
return seat.StartAnswer{}, fmt.Errorf("the head of %s (revision %d) holds no entry of %s: nothing was started", in.Branch, half.Revision, strings.Join(absent, ", "))
}
passed, running, err := v.heldEntries(in.Branch, movers)
if err != nil {
return seat.StartAnswer{}, err
}
if len(passed) > 0 {
return seat.StartAnswer{}, fmt.Errorf("the newest entry of %s passed already: nothing was started", strings.Join(passed, ", "))
}
if len(running) > 0 {
return seat.StartAnswer{}, fmt.Errorf("the newest entry of %s: nothing was started", strings.Join(running, ", "))
}
movers = Tiers(movers, half.Entries, v.Starter.logf)
names := make([]string, 0, len(movers))
for _, m := range movers {
names = append(names, m.Module)
}
prefix := AgainPipelineKey(in.Branch, half.Revision, 0)
prefix = prefix[:len(prefix)-1]
held, err := v.Hearer.Store.Keys(prefix + "*")
if err != nil {
return seat.StartAnswer{}, fmt.Errorf("the pipelines started again at revision %d of %s are not listed: nothing was started: %w", half.Revision, in.Branch, err)
}
n := 1
for _, k := range held {
if i, err := strconv.Atoi(strings.TrimPrefix(k, prefix)); err == nil && i >= n {
n = i + 1
}
}
if err := v.record(seat.VerbStart, fmt.Sprintf("started %s again at the head of %s by hand", strings.Join(names, ", "), in.Branch), in.Why); err != nil {
return seat.StartAnswer{}, err
}
// The next n is taken without a bound: each refusal means the key exists (H-A-479 second addendum).
for ; ; n++ {
key := AgainPipelineKey(in.Branch, half.Revision, n)
started, err := v.Starter.Start(Begin{Branch: in.Branch, Source: half.Source, Revision: half.Revision, Entries: half.Entries,
Key: key, Movers: movers})
if err != nil {
return seat.StartAnswer{}, err
}
if started {
v.Starter.logf("%s starts %s again at the head by hand (H-A-479)", key, strings.Join(names, ", "))
return seat.StartAnswer{Pipeline: key}, nil
}
}
}
// heldEntries are the movers whose module, at the mover's fingerprint, a delivering pipeline of branch carries and did not
// leave: passed, those a passed pipeline holds (a newest entry that passed is not started again, H-A-479); running, those a
// pipeline not ended holds, each said "<module>: its pipeline <key> is running", so two pipelines never build one entry side
// by side (H-A-479 second addendum).
func (v Verbs) heldEntries(branch string, movers []seat.Mover) (passed, running []string, err error) {
pkeys, err := branchKeys(v.Hearer.Store, branch)
if err != nil {
return nil, nil, fmt.Errorf("the pipelines of %s are not listed, so nothing was started: %w", branch, err)
}
seen := map[string]bool{}
for _, key := range pkeys {
p, _, err := v.Hearer.Store.Get(key)
if err != nil {
return nil, nil, fmt.Errorf("the pipeline %s is not read, so nothing was started: %w", key, err)
}
open := p.Ended == nil && (p.Outcome == seat.PipelineOutcomeRunning || p.Outcome == seat.PipelineOutcomeWaiting)
if p.Run != "" || (p.Outcome != seat.PipelineOutcomePassed && !open) {
continue
}
for _, m := range movers {
if seen[m.Module] || slices.Contains(p.Superseded, m.Module) {
continue
}
if pm, ok := MoverOf(p, m.Module); ok && pm.Fingerprint == m.Fingerprint {
seen[m.Module] = true
if open {
running = append(running, m.Module+": its pipeline "+key+" is running")
} else {
passed = append(passed, m.Module+" (in "+key+")")
}
}
}
}
return passed, running, nil
}
// AskAgain asks a declined approval step once more (§306, §36), recorded in the hand-act log first: the step waits again,
// marked asked again by the caller the bus proved, and is asked at once when the pipeline's every other required step
// passed, under an ask of its own (the earlier ask's decision ended it).
@@ -1,7 +1,9 @@
package pipeline
import (
"encoding/json"
"errors"
"fmt"
"strings"
"testing"
"time"
@@ -423,3 +425,180 @@ func TestAValidateRerunMovesEveryMoversValidateAndReopensItsCompositions(t *test
}
}
}
// H-A-479: start with modules starts a pipeline at the head keyed <branch>.<revision>.again.<n> carrying the named modules
// whose newest entry has no passed pipeline, at the take-in's tiers; a module whose newest entry passed is refused by name,
// nothing started; exactly one of module or modules is given; a second start takes the next n.
func TestStartWithModulesStartsAFailedMoverAgainAtTheHead(t *testing.T) {
v, store, _, _, acts, _ := verbsFixture()
made := created{}
var started []seat.PipelineStarted
v.Starter.Pipelines = made
v.Starter.Say = func(_ string, body any) error {
if ps, ok := body.(seat.PipelineStarted); ok {
started = append(started, ps)
}
return nil
}
_, entries := placeFixture()
app := entries["app"]
app.Fp, app.Commit, app.Repository = "src2:aa", "c1", "o/app"
entries["app"] = app
entries["lib"] = catalog.CatalogEntry{Module: "lib", Fp: "src2:bb", Commit: "c2", Repository: "o/lib"}
v.View = func(string) (Half, bool) { return Half{Source: 7, Revision: 9, Entries: entries}, true }
// The fixture's main.5 moves app at src2:aa and failed; lib's newest entry passed in main.8.
e := store[pkey]
e.p.Outcome = seat.PipelineOutcomeFailed
store[pkey] = e
store["main.8"] = struct {
p seat.Pipeline
rev uint64
}{seat.Pipeline{Pipeline: "main.8", Branch: "main", Source: 6, Revision: 8, Outcome: seat.PipelineOutcomePassed,
Movers: []seat.Mover{{Module: "lib", Fingerprint: "src2:bb"}, {Module: "app", Fingerprint: "src2:aa"}}, Superseded: []string{"app"}}, 1}
if _, err := v.Start("operator", seat.StartInput{Branch: "main", Module: "app", Modules: []string{"app"}, Why: "x"}); err == nil {
t.Error("a start naming both module and modules was taken")
}
// A pipeline still running at app's head entry refuses the start: two pipelines never build one entry side by side.
store["main.7"] = struct {
p seat.Pipeline
rev uint64
}{seat.Pipeline{Pipeline: "main.7", Branch: "main", Source: 6, Revision: 7, Outcome: seat.PipelineOutcomeRunning,
Movers: []seat.Mover{{Module: "app", Fingerprint: "src2:aa"}}}, 1}
if _, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app"}, Why: "x"}); err == nil || !strings.Contains(err.Error(), "its pipeline main.7 is running") {
t.Errorf("a start of app while main.7 runs it = %v; want refused naming main.7", err)
}
delete(store, "main.7")
if _, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app", "lib"}, Why: "x"}); err == nil || !strings.Contains(err.Error(), "lib") {
t.Errorf("a start naming lib, whose newest entry passed, = %v; want refused naming lib", err)
}
if len(made) != 0 {
t.Fatalf("a refused start wrote %d pipelines", len(made))
}
a, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app"}, Why: "its pipeline failed at an unchanged entry"})
if err != nil || a.Pipeline != "main.9.again.1" || made["main.9.again.1"] == nil {
t.Fatalf("start with modules = %+v, %v; written %v", a, err, len(made))
}
var p seat.Pipeline
if err := json.Unmarshal(made["main.9.again.1"], &p); err != nil {
t.Fatal(err)
}
if p.Revision != 9 || p.Source != 7 || len(p.Movers) != 1 || p.Movers[0].Module != "app" || p.Movers[0].Fingerprint != "src2:aa" || p.Movers[0].Tier != 1 {
t.Errorf("the pipeline = %+v, want app at src2:aa, tier 1, at revision 9 of source 7", p)
}
if len(started) != 1 || started[0].Pipeline != "main.9.again.1" || started[0].Revision != 9 {
t.Errorf("pipeline-started = %+v, want main.9.again.1 at revision 9 (its revision pinned)", started)
}
// The next start at the same head, once main.9.again.1 failed, takes the next n.
at := time.Unix(3, 0)
p.Outcome, p.Ended = seat.PipelineOutcomeFailed, &at
store["main.9.again.1"] = struct {
p seat.Pipeline
rev uint64
}{p, 1}
if a, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app"}, Why: "again"}); err != nil || a.Pipeline != "main.9.again.2" {
t.Errorf("a second start with modules = %+v, %v; want main.9.again.2", a, err)
}
if len(*acts) != 2 {
t.Errorf("hand acts %v, want the two starts recorded", *acts)
}
// main.9.again.1 passed: its version is written into it as into any pipeline of its source, and a further start of app is
// refused naming it, read through the branch's key forms.
p.Outcome = seat.PipelineOutcomePassed
store["main.9.again.1"] = struct {
p seat.Pipeline
rev uint64
}{p, 1}
if wrote, err := v.Hearer.Released(catalog.VersionReleasedEvent{Module: "app", Version: "0.1.2", Source: 7}, "main"); err != nil || wrote != 1 ||
store["main.9.again.1"].p.Movers[0].Version != "0.1.2" {
t.Errorf("the release of app 0.1.2 wrote %d (%v), the again pipeline's mover %+v; want its version written", wrote, err, store["main.9.again.1"].p.Movers)
}
if _, err := v.Start("operator", seat.StartInput{Branch: "main", Modules: []string{"app"}, Why: "x"}); err == nil || !strings.Contains(err.Error(), "main.9.again.1") {
t.Errorf("a start of app after main.9.again.1 passed = %v; want refused naming it", err)
}
if !IsStepsKey(StepsKey("main.9.again.1", "app")) {
t.Error("a mover key of an again pipeline is not read as a mover's steps")
}
// H-A-485: the mover keys are read by the one parse of the seat's key forms; a pipeline key of no form (its n or its
// revision no number) is no mover's steps.
for _, k := range []string{"steps.main.9.again.x.app", "steps.main.r9.app", "steps.main.9.again.0.app"} {
if IsStepsKey(k) {
t.Errorf("%s, of no pipeline key form, is read as a mover's steps", k)
}
}
}
// H-A-479 addendum (2): a rerun of a step in an ended pipeline pins its revision again at the reopening (its pipeline-started
// said again), and is refused by name, nothing asked, when the revision is already removed.
func TestARerunOfAnEndedPipelinePinsItsRevisionAgainOrIsRefusedWhenItIsGone(t *testing.T) {
v, store, _, asks, _, _ := verbsFixture()
var started []seat.PipelineStarted
v.Starter.Say = func(_ string, body any) error {
if ps, ok := body.(seat.PipelineStarted); ok {
if len(asks.asks) != 0 {
t.Errorf("pipeline-started said after the step was asked again (%d asks): its revision is pinned too late", len(asks.asks))
}
started = append(started, ps)
}
return nil
}
e := store[pkey]
at := time.Unix(2, 0)
e.p.Revision, e.p.Outcome, e.p.Ended = 5, seat.PipelineOutcomeFailed, &at
for i := range e.p.Steps {
if e.p.Steps[i].Artifact == "app:program" && e.p.Steps[i].Step == "lint" {
e.p.Steps[i].Outcome = seat.StepResultOutcomeFailed
}
}
store[pkey] = e
gone := true
v.RevisionHeld = func(branch string, revision int64) error {
if gone {
return fmt.Errorf("revision %s.%d: no such object: %w", branch, revision, ErrRevisionGone)
}
return nil
}
in := seat.RerunInput{Pipeline: pkey, Step: "lint", Artifact: "app:program", Why: "retry"}
// H-A-479 third addendum: another open pipeline carrying app at the same revision refuses the reopening.
store["main.5.again.1"] = struct {
p seat.Pipeline
rev uint64
}{seat.Pipeline{Pipeline: "main.5.again.1", Branch: "main", Source: 5, Revision: 5, Outcome: seat.PipelineOutcomeRunning,
Movers: []seat.Mover{{Module: "app", Fingerprint: "src2:aa"}}}, 1}
gone = false
if _, err := v.Rerun("operator", in); err == nil || !strings.Contains(err.Error(), "its pipeline main.5.again.1 is running") {
t.Fatalf("a reopening beside main.5.again.1 = %v; want refused naming it", err)
}
if len(asks.asks) != 0 || store[pkey].p.Outcome != seat.PipelineOutcomeFailed {
t.Fatalf("a refused reopening asked %d, left the pipeline %s", len(asks.asks), store[pkey].p.Outcome)
}
delete(store, "main.5.again.1")
gone = true
if _, err := v.Rerun("operator", in); err == nil || !strings.Contains(err.Error(), "its revision 5 is gone; start the mover again at the head") {
t.Fatalf("a rerun of an ended pipeline whose revision is gone = %v; want refused by name", err)
}
if len(asks.asks) != 0 || store[pkey].p.Outcome != seat.PipelineOutcomeFailed || len(started) != 0 {
t.Fatalf("a refused rerun asked %d, left the pipeline %s, said %d starts", len(asks.asks), store[pkey].p.Outcome, len(started))
}
gone = false
if _, err := v.Rerun("operator", in); err != nil {
t.Fatal(err)
}
if len(started) != 1 || started[0].Pipeline != pkey || started[0].Revision != 5 {
t.Errorf("pipeline-started at the reopening = %+v, want %s at revision 5 (its revision pinned again)", started, pkey)
}
// A rerun of a running pipeline reopens nothing and says no start.
e = store[pkey]
for i := range e.p.Steps {
if e.p.Steps[i].Artifact == "app:program" && e.p.Steps[i].Step == "unit" {
e.p.Steps[i].Outcome = seat.StepResultOutcomeFailed
}
}
store[pkey] = e
if _, err := v.Rerun("operator", seat.RerunInput{Pipeline: pkey, Step: "unit", Artifact: "app:program", Why: "x"}); err != nil {
t.Fatal(err)
}
if len(started) != 1 {
t.Errorf("a rerun of a running pipeline said pipeline-started again: %+v", started)
}
}
@@ -237,7 +237,8 @@ func runSettingsOf(raw []byte) bool {
}
if len(m.Config) != len(want)+len(words) || m.Config["test-runs-cap-mib"]["maximum"] != float64(64) || m.Config["test-runs-cap-mib"]["default"] != float64(16) ||
m.Config["pipelines-at-once"]["minimum"] != float64(1) || m.Config["pipelines-at-once"]["maximum"] != float64(8) ||
m.Config["pipelines-at-once"]["default"] != float64(1) || m.Config["pipelines-waiting-cap"]["default"] != float64(64) {
m.Config["pipelines-at-once"]["default"] != float64(1) || m.Config["pipelines-waiting-cap"]["default"] != float64(64) ||
m.Config["widens-read-bound"]["default"] != "30s" {
return false
}
env := map[string]bool{}
+2 -2
View File
@@ -138,9 +138,9 @@
},
"widens-read-bound": {
"type": "string",
"description": "how long one read of a pipeline end's widens (the catalog's revision, the seat holders, the grants part) waits for its answer before it is cut and said could not run, a Go duration such as 5s (design 47 G A-472, A-472a).",
"description": "how long one read of a pipeline end's widens (the catalog's revision, the seat holders, the grants part) waits for its answer before it is cut and said could not run, a Go duration such as 30s (design 47 G A-472, A-472a, H2 H-A-478: long enough that a cold grants-for is not cut).",
"trusted": false,
"default": "5s"
"default": "30s"
},
"revisions-kept": {
"type": "number",
+1
View File
@@ -13,6 +13,7 @@ require (
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/containerimageregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/gopackageregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildnode v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/npmpackageregistry v0.0.0-00010101000000-000000000000
+93 -6
View File
@@ -27,6 +27,10 @@ const (
IdleAfter = 24 * time.Hour
// FullPercent is the fill of the objects past which the receiver says they fill.
FullPercent = 80
// TakeOverAfter is how long a transfer's last part must lie behind it before another caller opening it with the
// same digest takes it over (design 47 H2 H-A-481): a sender restarted mid-transfer goes on, a live one is not
// pushed aside.
TakeOverAfter = 2 * time.Minute
)
// Want is one part an opening names: its digest (sha256:<hex>) and its size.
@@ -117,12 +121,17 @@ type Receiver[M any] struct {
// Bound reads the cap the objects' binding carries (BusCap): the bus's own bound, which then counts over Cap.
// Optional; an error or a zero falls back to Cap.
Bound func() (uint64, error)
// MaxChunk, Idle and Full override MaxReceived, IdleAfter and FullPercent when set.
// MaxChunk, Idle, TakeOver and Full override MaxReceived, IdleAfter, TakeOverAfter and FullPercent when set.
MaxChunk int
Idle time.Duration
TakeOver time.Duration
Full uint64
// Holds says the holder already holds a part, which then counts as held at the open and is not sent. Optional.
Holds func(t Transfer[M], digest string) bool
// HoldsWhole says the holder holds the file itself the transfer brings (its manifest or reference at the name and
// version its shape names), never from its parts alone (design 47 H2 H-A-481 second addendum): a reopen that lacks
// nothing is then dropped without a second store. Optional: nil never drops, and the reopen finishes as usual.
HoldsWhole func(t Transfer[M]) bool
// Check is the caller's check of a whole transfer before anything is stored; its error is the refusal's reason.
// Optional.
Check func(t Transfer[M]) error
@@ -172,6 +181,13 @@ func (r *Receiver[M]) CapNow() uint64 {
return r.Cap
}
func (r *Receiver[M]) takeOver() time.Duration {
if r.TakeOver > 0 {
return r.TakeOver
}
return TakeOverAfter
}
func (r *Receiver[M]) fullPct() uint64 {
if r.Full > 0 {
return r.Full
@@ -180,8 +196,12 @@ func (r *Receiver[M]) fullPct() uint64 {
}
// Open opens a transfer for opener, or opens it again: a transfer already open answers what it lacks, so a cut transfer
// goes on from there, and only its opener may open it again. A new transfer that would pass the cap is refused; parts
// the holder holds count as held; when nothing is lacked the transfer ends at once.
// goes on from there. A transfer is finished or taken over, never left open (design 47 H2 H-A-481 and its addendum):
// one opened again with nothing lacked (its finish was cut) is finished, by its opener or by another caller with the
// same digest, once each part taken in it is read back and hashes to its digest (a part that does not is lacked again),
// and dropped without a second store when the holder already holds the file itself (HoldsWhole); one that lacks a part is another
// caller's only once its last part is older than TakeOver, and is refused to it before. A new transfer that would pass the cap is refused; parts the holder holds count as held; when nothing is
// lacked the transfer ends at once, its idle bound armed before the finish, so a cut finish never leaves it open.
func (r *Receiver[M]) Open(id, opener string, parts []Want, shape M) (Received, error) {
switch {
case strings.TrimSpace(id) == "" || strings.ContainsAny(id, "/. *>"):
@@ -197,8 +217,33 @@ func (r *Receiver[M]) Open(id, opener string, parts []Want, shape M) (Received,
if t, found, err := r.Transfers.Get(id); err != nil {
return Received{}, err
} else if found {
if t.Opener != opener {
return Received{}, fmt.Errorf("refused for %s: transfer %s was opened by another caller", opener, id)
if len(t.Lacks()) == 0 {
if r.heldWhole(t) {
// The cut came after the store: the holder holds the file, so it is not stored a second time.
if _, err := r.Drop(id); err != nil {
return Received{}, fmt.Errorf("transfer %s is stored already and cannot be dropped: %w", id, err)
}
return Received{ID: id, Ended: true}, nil
}
if !r.verify(&t) {
return r.finishArmed(t)
}
if err := r.Transfers.Put(t); err != nil {
return Received{}, fmt.Errorf("transfer %s cannot be kept: %w", id, err)
}
r.tell(t.FillAtOpen)
}
switch {
case len(t.Lacks()) == 0:
return r.finishArmed(t)
case t.Opener != opener && r.now().Sub(t.Last) < r.takeOver():
return Received{}, fmt.Errorf("refused for %s: transfer %s was opened by another caller, whose last part came %s ago (taken over after %s)",
opener, id, r.now().Sub(t.Last).Round(time.Second), r.takeOver())
case t.Opener != opener:
t.Opener = opener
if err := r.Transfers.Put(t); err != nil {
return Received{}, fmt.Errorf("transfer %s cannot be taken over by %s: %w", id, opener, err)
}
}
return Received{ID: id, Lacks: t.Lacks()}, r.arm(id)
}
@@ -227,11 +272,53 @@ func (r *Receiver[M]) Open(id, opener string, parts []Want, shape M) (Received,
}
r.tell(used)
if len(t.Lacks()) == 0 {
return Received{ID: id, Ended: true}, r.finish(t)
return r.finishArmed(t)
}
return Received{ID: id, Lacks: t.Lacks()}, r.arm(id)
}
// heldWhole says the holder already holds the file t brings (HoldsWhole), so a finish cut after its store stores nothing
// again; parts held alone never say it (H-A-481 second addendum), since a publish cut before its store must still be
// said as published or refused.
func (r *Receiver[M]) heldWhole(t Transfer[M]) bool {
return r.HoldsWhole != nil && r.HoldsWhole(t)
}
// verify reads each part taken in t back from the objects and hashes it against its digest, as Take does at a part's
// last chunk (H-A-481 addendum): a finish cut after its chunks were dropped reads them absent, which the runtime's
// object read answers as empty. A part that fails has its chunks dropped and is lacked again. It answers whether any
// part failed, t changed with it.
func (r *Receiver[M]) verify(t *Transfer[M]) bool {
failed := false
for _, p := range t.Parts {
if !t.Taken(p.Digest) || !slices.Contains(t.Held, p.Digest) {
continue
}
whole, err := r.part(*t, p.Digest)
if err == nil && "sha256:"+sum(whole) == p.Digest {
continue
}
r.dropChunks(*t, p.Digest)
delete(t.Chunks, p.Digest)
t.Held = slices.DeleteFunc(t.Held, func(d string) bool { return d == p.Digest })
failed = true
}
if failed {
r.reanchor(t)
}
return failed
}
// finishArmed finishes a transfer that lacks nothing at an open, its idle bound armed first (H-A-481): a finish cut
// by a restart leaves a kept transfer its key still drops, and the next open finishes it. A key not written fails the
// open loudly before the finish, the transfer kept for the next open.
func (r *Receiver[M]) finishArmed(t Transfer[M]) (Received, error) {
if err := r.arm(t.ID); err != nil {
return Received{}, err
}
return Received{ID: t.ID, Ended: true}, r.finish(t)
}
// arm bounds an open transfer by its idle key. A key that cannot be written fails the open loudly (the transfer is
// kept, so the opener's next open of it answers what is held and arms it again).
func (r *Receiver[M]) arm(id string) error {
@@ -289,6 +289,106 @@ func aHolderTakesAFileInParts(t *testing.T) {
}
})
// Design 47 H2 H-A-481: a transfer is finished or taken over, never left open. A finish cut by a restart leaves the
// transfer kept with every part held and its chunks in the objects (cut): the opener's next open, or another caller's
// with the same digest, finishes it; a transfer that lacks a part is another caller's once its last part is older
// than TakeOverAfter, refused to it before; and a transfer that lacks nothing at its open is armed before its finish.
t.Run("a transfer is finished or taken over, never left open", func(t *testing.T) {
var order []string
pkg.Arm = func(id string, _ time.Duration) error { order = append(order, "arm "+id); return nil }
store := pkg.Store
defer func() { pkg.Arm, pkg.Holds, pkg.HoldsWhole, pkg.Store = nil, nil, nil, store }()
// cut leaves c1 as a cut finish does: "whole" all chunks there, "lacked" a part short, "gone" its chunks dropped
// before the cut, "wrong" a chunk that does not hash.
cut := func(id, how string) {
tr := Transfer[packageShape]{ID: id, Opener: "builder", Parts: []Want{part}, Chunks: map[string]int{part.Digest: 1},
Held: []string{part.Digest}, Opened: now, Last: now, Shape: packageShape{"m", "1"}}
switch how {
case "whole":
objects[pkg.chunkName(id, part.Digest, 0)] = blob
case "lacked":
tr.Held = nil
objects[pkg.chunkName(id, part.Digest, 0)] = blob[:1000]
case "wrong":
objects[pkg.chunkName(id, part.Digest, 0)] = []byte("other")
}
if err := pkg.Transfers.Put(tr); err != nil {
t.Fatal(err)
}
}
for _, c := range []struct {
name, opener, how string
after, takeOver time.Duration
storeHolds string // "parts": Holds answers every part; "file": HoldsWhole answers the file
want string // "stored", "dropped", "lacked again", "lacks" (taken over) or the refusal's words
}{
{name: "the opener opens a cut finish again", opener: "builder", how: "whole", want: "stored"},
{name: "another caller opens a cut finish", opener: "other", how: "whole", want: "stored"},
{name: "a cut after the chunks were dropped", opener: "builder", how: "gone", want: "lacked again"},
{name: "a cut finish whose chunk does not hash", opener: "builder", how: "wrong", want: "lacked again"},
{name: "a cut after the store: the holder holds the file", opener: "builder", how: "whole", storeHolds: "file", want: "dropped"},
{name: "a cut before the store: the holder holds the parts, not the file", opener: "builder", how: "whole", storeHolds: "parts", want: "stored"},
{name: "another caller while the opener sends", opener: "other", how: "lacked", after: time.Minute, want: "another caller, whose last part came 1m0s ago"},
{name: "another caller once the last part is two minutes old", opener: "other", how: "lacked", after: TakeOverAfter, want: "lacks"},
{name: "the receiver's own takeover bound", opener: "other", how: "lacked", after: time.Minute, takeOver: 30 * time.Second, want: "lacks"},
} {
pkgLog = nil
pkg.TakeOver = c.takeOver
pkg.Holds, pkg.HoldsWhole = nil, nil
switch c.storeHolds {
case "parts":
pkg.Holds = func(Transfer[packageShape], string) bool { return true }
case "file":
pkg.HoldsWhole = func(tr Transfer[packageShape]) bool { return tr.Shape == packageShape{"m", "1"} }
}
cut("c1", c.how)
now = now.Add(c.after)
got, err := pkg.Open("c1", c.opener, []Want{part}, packageShape{"m", "1"})
kept, open, _ := pkg.Transfers.Get("c1")
switch c.want {
case "stored":
if err != nil || !got.Ended || open || len(pkgLog) != 1 || pkgLog[0].outcome != "stored" || string(pkgLog[0].parts[part.Digest]) != string(blob) {
t.Errorf("%s: open = %+v, %v, still open %v, log %+v; want it finished and stored", c.name, got, err, open, pkgLog)
}
case "dropped":
if err != nil || !got.Ended || open || len(pkgLog) != 0 {
t.Errorf("%s: open = %+v, %v, still open %v, log %+v; want it dropped, not stored again", c.name, got, err, open, pkgLog)
}
case "lacked again":
if err != nil || got.Ended || !open || len(pkgLog) != 0 || !reflect.DeepEqual(got.Lacks, []string{part.Digest}) || kept.Taken(part.Digest) {
t.Errorf("%s: open = %+v, %v, log %+v, kept %+v; want the part lacked again, nothing stored", c.name, got, err, pkgLog, kept)
}
_, _ = pkg.Drop("c1")
case "lacks":
if err != nil || got.Ended || !open || kept.Opener != c.opener || !reflect.DeepEqual(got.Lacks, []string{part.Digest}) {
t.Errorf("%s: open = %+v, %v, opener %q; want it taken over by %s, lacking the part", c.name, got, err, kept.Opener, c.opener)
}
if r, err := pkg.Take("c1", c.opener, part.Digest, 1, true, blob[1000:], nil); err != nil || !r.Ended {
t.Errorf("%s: the new opener's last chunk = %+v, %v", c.name, r, err)
}
default:
if err == nil || !strings.Contains(err.Error(), c.want) || !open || kept.Opener != "builder" {
t.Errorf("%s: open = %v, opener %q; want refused with %q, the transfer kept", c.name, err, kept.Opener, c.want)
}
_, _ = pkg.Drop("c1")
}
if len(objects) != 0 {
t.Errorf("%s: %d objects left", c.name, len(objects))
}
}
pkg.TakeOver = 0
order = nil
pkg.Holds = func(Transfer[packageShape], string) bool { return true }
pkg.Store = func(tr Transfer[packageShape], _ map[string][]byte) error {
order = append(order, "store "+tr.ID)
return nil
}
if got, err := pkg.Open("c2", "builder", []Want{part}, packageShape{"m", "1"}); err != nil || !got.Ended ||
!reflect.DeepEqual(order, []string{"arm c2", "store c2"}) {
t.Errorf("a transfer lacking nothing at its open = %+v, %v, %v; want its idle bound armed before its finish", got, err, order)
}
})
// An open transfer is bounded by its idle key (Arm); the key's end (Expired) drops it idle, arms it again for the
// rest when it took a chunk since, and leaves a gone one; a key not written fails the open loudly. The cap the
// binding carries (Bound) counts over Cap.
@@ -0,0 +1,100 @@
// Package pipelinekey reads the key of a pipeline in the seat mesh-pipeline-runner's state pipelines, in every key form the
// seat defines, through the seat's contract (design 47 H2 H-A-485): one parse, used by the runner, the assigner and the view, so
// a pipeline started again at the head (`<branch>.<revision>.again.<n>`, H-A-479) or an unfinished mover's own pipeline
// (`<branch>.<revision>.unfinished.<module>`, H-A-398) is read as a take-in's is. A key of no form the seat defines is refused
// with an error, never read as an empty one.
package pipelinekey
import (
"fmt"
"strconv"
"strings"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// The key forms of a pipeline in the state pipelines (the seat's key forms, design 47 H §746, H-A-213 (2), H-A-398, H-A-479).
const (
FormRevision = "<branch>.<revision>"
FormRun = "<branch>.run.<run>"
FormPublished = "<branch>.<source>.published.<package>.<version>"
FormUnfinished = "<branch>.<revision>.unfinished.<module>"
FormAgain = "<branch>.<revision>.again.<n>"
)
// Key is a pipeline's key read: its form, its watched branch (unescaped), and the parts its form names: the revision (a
// published form's source), the run, the package and version (escaped, as the key holds them), the unfinished mover's
// module (unescaped) and the again form's n.
type Key struct {
Form string
Branch string
Revision int64
Run string
Package string
Version string
Module string
N int
}
// Parse reads key as a pipeline's key of one of the seat's forms; any other key is an error naming the forms.
func Parse(key string) (Key, error) {
parts := strings.Split(key, ".")
var k Key
var branch, revision, n, module string
ok := false
switch {
case len(parts) == 2:
branch, revision, ok = seat.ParsePipelinesByBranchRevisionKey(key)
k.Form = FormRevision
case len(parts) == 3 && parts[1] == "run":
branch, k.Run, ok = seat.ParsePipelinesByBranchRunRunKey(key)
k.Form = FormRun
case len(parts) == 4 && parts[2] == "unfinished":
branch, revision, module, ok = seat.ParsePipelinesByBranchRevisionUnfinishedModuleKey(key)
k.Form = FormUnfinished
case len(parts) == 4 && parts[2] == "again":
branch, revision, n, ok = seat.ParsePipelinesByBranchRevisionAgainNKey(key)
k.Form = FormAgain
case len(parts) == 5 && parts[2] == "published":
branch, revision, k.Package, k.Version, ok = seat.ParsePipelinesByBranchSourcePublishedPackageVersionKey(key)
k.Form = FormPublished
}
if !ok {
return Key{}, refused(key, "it is of no form the seat defines")
}
var err error
if k.Branch, err = keys.UnescapeName(branch); err != nil || k.Branch == "" {
return Key{}, refused(key, "its branch does not read")
}
if k.Form != FormRun {
if k.Revision, err = strconv.ParseInt(revision, 10, 64); err != nil || k.Revision <= 0 {
return Key{}, refused(key, "its revision is no number above 0")
}
}
switch k.Form {
case FormRun:
if k.Run == "" {
return Key{}, refused(key, "it names no run")
}
case FormUnfinished:
if k.Module, err = keys.UnescapeName(module); err != nil || k.Module == "" {
return Key{}, refused(key, "its module does not read")
}
case FormAgain:
if k.N, err = strconv.Atoi(n); err != nil || k.N < 1 {
return Key{}, refused(key, "its n is no number from 1")
}
case FormPublished:
if k.Package == "" || k.Version == "" {
return Key{}, refused(key, "it names no package or no version")
}
}
return k, nil
}
// refused is the error of a key Parse does not read.
func refused(key, why string) error {
return fmt.Errorf("%q is no key of a pipeline of the seat %s (%s): %s", key, seat.Seat,
strings.Join([]string{FormRevision, FormRun, FormPublished, FormUnfinished, FormAgain}, ", "), why)
}
@@ -0,0 +1,43 @@
package pipelinekey
import (
"strings"
"testing"
)
// H-A-485: every key form of a pipeline the seat mesh-pipeline-runner defines is read, the again form and the unfinished form as
// a take-in's, its branch and module unescaped; a key of no form, or whose parts do not read, is refused naming why.
func TestEveryPipelineKeyFormIsReadAndAnyOtherRefused(t *testing.T) {
for _, c := range []struct {
key string
want Key
why string
}{
{key: "main.265", want: Key{Form: FormRevision, Branch: "main", Revision: 265}},
{key: "main.265.again.2", want: Key{Form: FormAgain, Branch: "main", Revision: 265, N: 2}},
{key: "feat=2fx.12.unfinished.mesh-tools", want: Key{Form: FormUnfinished, Branch: "feat/x", Revision: 12, Module: "mesh-tools"}},
{key: "main.run.r7", want: Key{Form: FormRun, Branch: "main", Run: "r7"}},
{key: "main.40.published.lib.0=2e1=2e2", want: Key{Form: FormPublished, Branch: "main", Revision: 40, Package: "lib", Version: "0=2e1=2e2"}},
{key: "main", why: "no form"},
{key: "main.265.again", why: "no form"},
{key: "main.265.later.2", why: "no form"},
{key: "main.265.again.0", why: "its n"},
{key: "main.265.again.x", why: "its n"},
{key: "main.r1", why: "its revision"},
{key: "main.0", why: "its revision"},
{key: "ma=zz.5", why: "its branch"},
{key: "main.5.unfinished.=zz", why: "its module"},
{key: "main.5.6.7.8.9", why: "no form"},
} {
got, err := Parse(c.key)
if c.why != "" {
if err == nil || !strings.Contains(err.Error(), c.why) || !strings.Contains(err.Error(), FormAgain) {
t.Errorf("%s: read %+v (%v); want it refused, %s, naming the forms", c.key, got, err, c.why)
}
continue
}
if err != nil || got != c.want {
t.Errorf("%s: read %+v (%v); want %+v", c.key, got, err, c.want)
}
}
}
+8 -1
View File
@@ -84,7 +84,14 @@ func RunAsk(ctx context.Context, steps AskSteps, ask sdkstep.StepAsk) (any, erro
if ask.Build != nil {
job := *ask.Build
job.Fetch = withPackages(job.Fetch, ask.Packages)
return steps.build(ctx, job, ask.Version)
out, err := steps.build(ctx, job, ask.Version)
var dec *Declining
if err != nil && !sdkstep.IsPassing(err) && !errors.As(err, &dec) && ctx.Err() == nil {
// A failed build keeps its error text, as the build module bounded it, as the ask's output object, header and
// text as a test step's, so the verb output answers why after the fact (design 47 H2 H-A-482 and its addendum (a)).
steps.keepRunOutput(ask.ID, err.Error(), nil)
}
return out, err
}
if ask.Step != nil || ask.Install != nil {
return steps.runStep(ctx, ask)
@@ -117,6 +117,23 @@ imports {"module":"modules/m","workspace":"/w/1"}`
if !slices.Equal(answer.Imports, []string{"git.novox.be/novox/mesh-sdk/go/announce", "git.novox.be/novox/mesh-sdk/go/health"}) {
t.Errorf("the answer's imports are %v", answer.Imports)
}
// Design 47 H2 H-A-482 addendum (a): a failed build keeps its error text, as the build module bounded it, as the ask's
// output object, which the verb output answers.
outputs := fakeOutputs{m: map[string][]byte{}}
steps.Outputs, steps.Node = outputs, "ace"
steps.Build = func(context.Context, map[string]any) (any, error) {
return nil, errors.New("esbuild for code: status 1 | ✘ [ERROR] Could not resolve \"./missing\" … 812 bytes left out … main.js:1:1)")
}
failed := ask(sdkstep.BuildJob{Module: "m", Path: "modules/m", Fetch: &sdkstep.Fetch{Repository: "novox/x", Commit: runCommit},
Artifacts: []sdkstep.AskArtifact{{Artifact: "bundle"}}})
if _, err := RunAsk(context.Background(), steps, failed); err == nil {
t.Fatal("a failed build answered no error")
}
got2, err := readOutput(outputs, "ace", failed.ID, nil)
if err != nil || !strings.Contains(got2.Output, `bundle: esbuild for code: status 1 | ✘ [ERROR] Could not resolve "./missing"`) || got2.Size != len(got2.Output) {
t.Errorf("the failed build's output = %+v, %v; want its error text kept", got2, err)
}
}
// A build ask for another toolchain is declined (ADR 0584 clause 2), so the node sits out and the asker puts it again.
+8 -4
View File
@@ -125,7 +125,8 @@ func EndedHere(node string, keys func() ([]string, error), get func(key string)
// readOutput answers the verb output for ask (design 47 H2 §791, H-A-412): from the object `<node>.<ask>`, the text's last
// OutputTail bytes, its size and failing tests from the header; with no object, no longer kept when this node's steps key
// shows the ask ended here more than OutputsMaxAge ago, and refused otherwise, naming why (an ask never run here, or one
// whose output this node did not keep).
// that kept no output). An empty object is no object (H-A-482): the runtime's object read answers an absent object as
// empty data without an error, which is not a header fault.
func readOutput(o OutputObjects, node, ask string, ended func(ask string) (time.Time, bool, error)) (sdkstep.OutputAnswer, error) {
if o == nil {
return sdkstep.OutputAnswer{}, fmt.Errorf("this module keeps no %s store", OutputsStore)
@@ -135,11 +136,14 @@ func readOutput(o OutputObjects, node, ask string, ended func(ask string) (time.
return sdkstep.OutputAnswer{}, err
}
got, gerr := o.Get(name)
if gerr == nil {
if gerr == nil && len(got.Data) > 0 {
return outputOf(ask, got.Data)
}
if gerr == nil {
gerr = fmt.Errorf("the object %s in the %s store is empty", name, OutputsStore)
}
if ended == nil {
return sdkstep.OutputAnswer{}, fmt.Errorf("the output %s in the %s store: %w", name, OutputsStore, gerr)
return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s kept no output: %w", ask, gerr)
}
at, here, err := ended(ask)
switch {
@@ -150,7 +154,7 @@ func readOutput(o OutputObjects, node, ask string, ended func(ask string) (time.
case !at.IsZero() && now().Sub(at) > OutputsMaxAge:
return sdkstep.OutputAnswer{Ask: ask, NoLongerKept: true}, nil
default:
return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s ran on %s, and its output is not in the %s store: %w", ask, node, OutputsStore, gerr)
return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s ran on %s, and the ask kept no output: %w", ask, node, gerr)
}
}
@@ -64,7 +64,9 @@ func TestOutputsKeptAreRead(t *testing.T) {
return raw
}
steps := map[string]json.RawMessage{"mesh-delivery-pipeline.ace.a2": step(at.Add(-OutputsMaxAge - time.Hour)), "mesh-delivery-pipeline.ace.a3": step(at.Add(-time.Hour)),
"mesh-delivery-pipeline.g14.a4": step(at.Add(-OutputsMaxAge - time.Hour))}
"mesh-delivery-pipeline.g14.a4": step(at.Add(-OutputsMaxAge - time.Hour)), "mesh-delivery-pipeline.ace.a6": step(at.Add(-time.Hour))}
// H-A-482: the runtime's object read answers an absent object as empty data, no error; that is no output, not a header fault.
out.m["ace.a6"] = []byte{}
keys := func() ([]string, error) {
return slices.Collect(func(y func(string) bool) {
for k := range steps {
@@ -82,7 +84,8 @@ func TestOutputsKeptAreRead(t *testing.T) {
}{
{ask: "a1", want: sdkstep.OutputAnswer{Ask: "a1", Output: long[len(long)-OutputTail:], Size: len(long), Failing: failing}},
{ask: "a2", want: sdkstep.OutputAnswer{Ask: "a2", NoLongerKept: true}},
{ask: "a3", fail: "ran on ace, and its output is not in the outputs store"},
{ask: "a3", fail: "ran on ace, and the ask kept no output"},
{ask: "a6", fail: "ran on ace, and the ask kept no output: the object ace.a6 in the outputs store is empty"},
{ask: "a4", fail: "never ran on ace"},
{ask: "a5", fail: "never ran on ace"},
{fail: "asked for no ask"},
+3 -2
View File
@@ -267,8 +267,9 @@ func (s AskSteps) testStep(ctx context.Context, ask sdkstep.StepAsk, end *sdkste
return nil
}
// keepRunOutput keeps a test step's level text as the run's output `<node>.<ask id>` in the outputs objects, with the
// header of the failing tests and their words from the level's results (design 47 H2 §791, H-A-412 (1)). A holder that
// keepRunOutput keeps a test step's level text, or a failed build's error text (H-A-482), as the run's output `<node>.<ask
// id>` in the outputs objects, with the header of the failing tests and their words from the level's results (design 47
// H2 §791, H-A-412 (1)). A holder that
// keeps no outputs, or a write that fails, is said in the journal: the step's end stands on the results.
func (s AskSteps) keepRunOutput(ask, text string, failed []sdkstep.Failure) {
var failing []sdkstep.FailingTest
@@ -3,6 +3,8 @@
// to write the operator's answer to an ask that needs no proof of who answered (the view refuses the merge's Approve). `holds`
// lists every fingerprint the assigner holds with its node, cause and answer; `hold-release <module> <fingerprint> [words]` and
// `hold-keep <module> <fingerprint> [words]` answer its hold ask, again when the operator changes their mind (issue 1906).
// `pipelines [branch]` and `pipeline <pipeline> [mover]` are the pipelines page (design 47 H2 H-A-467): a branch's newest
// pipelines, one pipeline's mover rows or one mover's steps; with -follow printed again at each change the runner's events say.
package main
import (
@@ -13,7 +15,9 @@ import (
"os"
"strings"
"text/tabwriter"
"time"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"mesh-delivery-view/internal/view"
)
@@ -31,9 +35,19 @@ func run(args []string, socket string, out, errOut io.Writer) int {
fs := flag.NewFlagSet("mesh-delivery-cli", flag.ContinueOnError)
fs.SetOutput(errOut)
asJSON := fs.Bool("json", false, "print the rows as JSON")
follow := fs.Bool("follow", false, "pipelines and pipeline: print again at each change the runner's events say, until interrupted")
next := fs.String("next", "", "pipeline: the cursor of the next page a pipeline's answer named")
limit := fs.Int("limit", view.DefaultPipelinesLimit, "pipelines: the newest this many pipelines of the branch")
if err := fs.Parse(args); err != nil {
return 2
}
if fs.NArg() > 0 && (fs.Arg(0) == "pipelines" || fs.Arg(0) == "pipeline") {
if *limit < 1 {
fmt.Fprintln(errOut, "mesh-delivery-cli: -limit is a number of at least one")
return 2
}
return pipelines(socket, fs.Args(), *next, *limit, *follow, *asJSON, out, errOut)
}
if fs.NArg() > 0 && fs.Arg(0) == "holds" {
return holds(socket, *asJSON, out, errOut)
}
@@ -53,7 +67,7 @@ func run(args []string, socket string, out, errOut io.Writer) int {
}
if fs.NArg() > 0 {
if fs.Arg(0) != "answer" || fs.NArg() < 3 {
fmt.Fprintln(errOut, "mesh-delivery-cli shows the rows, or answers: mesh-delivery-cli answer <ask key> <option> [words]; holds; hold-release|hold-keep <module> <fingerprint> [words]")
fmt.Fprintln(errOut, "mesh-delivery-cli shows the rows, or answers: mesh-delivery-cli answer <ask key> <option> [words]; holds; hold-release|hold-keep <module> <fingerprint> [words]; [-follow] [-limit <n>] pipelines [branch]; [-follow] [-next <cursor>] pipeline <pipeline> [mover]")
return 2
}
key, option := fs.Arg(1), fs.Arg(2)
@@ -82,6 +96,61 @@ func run(args []string, socket string, out, errOut io.Writer) int {
return 0
}
// pipelines prints the pipelines page (design 47 H2 H-A-467): `pipelines [branch]` the newest pipelines of a branch (main by
// default), `pipeline <pipeline> [mover]` one pipeline's mover rows or one mover's steps; with -follow again at each change.
func pipelines(socket string, args []string, next string, limit int, follow, asJSON bool, out, errOut io.Writer) int {
var branch, pipeline, mover string
switch {
case args[0] == "pipelines" && len(args) <= 2:
if len(args) == 2 {
branch = args[1]
}
case args[0] == "pipeline" && (len(args) == 2 || len(args) == 3):
pipeline = args[1]
if len(args) == 3 {
mover = args[2]
}
default:
fmt.Fprintln(errOut, "mesh-delivery-cli [-follow] [-limit <n>] pipelines [branch]; mesh-delivery-cli [-follow] [-next <cursor>] pipeline <pipeline> [mover]")
return 2
}
var failed error
err := view.AskPipelines(socket, branch, limit, pipeline, mover, next, follow, func(page view.PipelinesPage, show *seatShow) bool {
if follow {
fmt.Fprintf(out, "--- %s ---\n", time.Now().Format("15:04:05"))
}
if asJSON {
enc := json.NewEncoder(out)
enc.SetIndent("", " ")
var v any = page
if show != nil {
v = show
}
if failed = enc.Encode(v); failed != nil {
return false
}
return true
}
if show != nil {
view.PipelineTable(out, *show, mover)
} else {
view.PipelinesTable(out, page)
}
return true
})
if err == nil {
err = failed
}
if err != nil {
fmt.Fprintln(errOut, "mesh-delivery-cli:", err)
return 1
}
return 0
}
// seatShow is the seat's answer of show, as the view hands it on.
type seatShow = seat.ShowAnswer
// holds prints every hold: module, fingerprint, node, since, answer, words.
func holds(socket string, asJSON bool, out, errOut io.Writer) int {
rows, err := view.AskHolds(socket)
@@ -22,6 +22,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient"
"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"
pseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate"
)
@@ -304,3 +305,63 @@ func rawAsk(t *testing.T, a oc.Ask) json.RawMessage {
}
const testView = "acme-view"
// Design 47 H2 H-A-467: the terminal view's pipelines page: a branch's newest pipelines, and one pipeline's mover rows.
func TestThePipelinesCommands(t *testing.T) {
m := view.New(testView)
call := func(key string, body any) (json.RawMessage, error) {
switch key {
case view.PipelinesListVerb:
in := body.(pseat.ListInput)
if in.Branch != "next" {
return json.Marshal(pseat.ListAnswer{})
}
rows := []pseat.PipelineRow{{Pipeline: "next.3", Source: 2, Revision: 3, Outcome: "passed", MoverCount: 1, Steps: map[string]int64{"passed": 4}},
{Pipeline: "next.2", Source: 2, Revision: 2, Outcome: "superseded", MoverCount: 1}}
return json.Marshal(pseat.ListAnswer{Rows: rows[:min(int(in.Limit), len(rows))]})
case view.PipelinesShowVerb:
return json.Marshal(pseat.ShowAnswer{Pipeline: pseat.Pipeline{Pipeline: "next.3", Outcome: "passed", Movers: []pseat.Mover{{Module: "alpha", Fingerprint: "src2:aa", Version: "0.2.1"}}},
Movers: []pseat.MoverRow{{Module: "alpha", Outcome: "passed"}}})
}
return nil, nil
}
m.SetPipelines(view.NewPipelines(call, nil, 0, nil))
dir, err := os.MkdirTemp(os.Getenv("TMPDIR"), "p")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { os.RemoveAll(dir) })
l, err := view.ListenSocket(filepath.Join(dir, "cli.sock"))
if err != nil {
t.Fatal(err)
}
ctx, cancel := context.WithCancel(context.Background())
t.Cleanup(cancel)
go view.ServeSocket(ctx, l, m)
path := filepath.Join(dir, "cli.sock")
for _, r := range []struct {
args []string
want string
}{
{[]string{"pipelines", "next"}, "next.3 3 2 passed 1 4 0 0 0 0 0 0 0"},
{[]string{"pipelines", "next"}, "next.2"}, // the newest 20 by default
{[]string{"-limit", "1", "pipelines", "next"}, "next.3"},
{[]string{"pipeline", "next.3"}, "alpha src2:aa 0.2.1 passed"},
{[]string{"-json", "pipeline", "next.3"}, `"fingerprint": "src2:aa"`},
} {
var out, errOut bytes.Buffer
if code := run(r.args, path, &out, &errOut); code != 0 || !strings.Contains(strings.Join(strings.Fields(out.String()), " "), strings.Join(strings.Fields(r.want), " ")) {
t.Errorf("%v = %d %q %q, want it to hold %q", r.args, code, out.String(), errOut.String(), r.want)
}
}
var out, errOut bytes.Buffer
if code := run([]string{"-limit", "1", "pipelines", "next"}, path, &out, &errOut); code != 0 || strings.Contains(out.String(), "next.2") {
t.Errorf("-limit 1 = %d %q, want only the newest", code, out.String())
}
for _, args := range [][]string{{"pipeline"}, {"-limit", "0", "pipelines"}} {
out.Reset()
if code := run(args, path, &out, &errOut); code != 2 {
t.Errorf("%v = %d, want 2", args, code)
}
}
}
@@ -27,9 +27,11 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-assigner/asks"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient"
pclient "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshpipelinerunnerclient"
"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"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
pseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate"
"git.novox.be/novox/mesh-sdk/go/process"
@@ -888,6 +890,78 @@ func TestProcessWholeSaysTheSourceRevisionIsDelivered(t *testing.T) {
if stored, gerr := kvs[viewstate.BucketsOf(testView).Reach].Get(ctx, re.Key); gerr != nil || string(stored.Value()) != string(re.Reach) {
t.Errorf("the event carries %s, the state reach holds %v (%v)", re.Reach, stored, gerr)
}
// Design 47 H2 H-A-467: the pipelines page reads the seat mesh-pipeline-runner's list, again at the runner's event heard on
// the module's one pull, and the delivered source revision links to the newest pipeline of its source.
pipelines := pipelinesRunner(t, nc)
pipelines.set(pseat.PipelineRow{Pipeline: "release.9", Source: rev, Revision: 9, Outcome: "passed", MoverCount: 1},
pseat.PipelineRow{Pipeline: "release.8", Source: rev, Revision: 8, Outcome: "superseded", MoverCount: 1})
var seen [][]string
err = view.AskPipelines(env["MESH_DELIVERY_SOCKET"], catalogBranch, 0, "", "", "", true, func(page view.PipelinesPage, _ *pseat.ShowAnswer) bool {
var keys []string
for _, r := range page.Rows {
keys = append(keys, r.Pipeline)
}
seen = append(seen, keys)
if len(seen) == 1 {
pipelines.set(pseat.PipelineRow{Pipeline: "release.10", Source: rev + 1, Revision: 10, Outcome: "running", MoverCount: 1},
pseat.PipelineRow{Pipeline: "release.9", Source: rev, Revision: 9, Outcome: "passed", MoverCount: 1})
body, _ := json.Marshal(pseat.PipelineEndedEvent{Pipeline: "release.9", Branch: catalogBranch, Source: rev, Revision: 9, Outcome: "passed"})
if _, err := js.Publish(ctx, pclient.RevisionSubject(pseat.EventPipelineEnded, catalogBranch, 9), body); err != nil {
t.Error(err)
return false
}
}
return len(seen) < 2 || !slices.Contains(keys, "release.10")
})
if err != nil || len(seen) < 2 || seen[len(seen)-1][0] != "release.10" {
t.Fatalf("the pipelines followed = %v, %v; want release.10 after the runner's event", seen, err)
}
snap, err := view.Ask(env["MESH_DELIVERY_SOCKET"])
if err != nil {
t.Fatal(err)
}
for _, src := range snap.Sources {
if src.Branch == catalogBranch && src.Pipeline != "release.9" {
t.Errorf("the delivery of %s's source revision %d links to %q, want release.9", src.Branch, src.Revision, src.Pipeline)
}
}
}
// fakeList is the seat mesh-pipeline-runner's verb list as its holder answers it on the bus, from the rows the test sets.
type fakeList struct {
mu sync.Mutex
rows []pseat.PipelineRow
}
func (f *fakeList) set(rows ...pseat.PipelineRow) {
f.mu.Lock()
defer f.mu.Unlock()
f.rows = rows
}
func pipelinesRunner(t *testing.T, nc *nats.Conn) *fakeList {
t.Helper()
f := &fakeList{}
subject := "mesh.seat." + pseat.Seat + ".call." + pseat.VerbList
for _, s := range []string{subject, subject + ".>"} {
sub, err := nc.Subscribe(s, func(m *nats.Msg) {
var in pseat.ListInput
_ = json.Unmarshal(m.Data, &in)
f.mu.Lock()
a := pseat.ListAnswer{}
if in.Branch == catalogBranch && in.Limit == view.DefaultPipelinesLimit {
a.Rows = f.rows
}
f.mu.Unlock()
raw, _ := json.Marshal(map[string]any{"result": a, "node": "n0"})
_ = m.Respond(raw)
})
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = sub.Unsubscribe() })
}
return f
}
// 1906/D10, whole on the bus (through run): a want that differs from its have is said `moving`, the have reaching it running and
@@ -15,6 +15,7 @@ import (
"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/meshwants"
"io"
"io/fs"
"log"
"maps"
"mesh-delivery-view/internal/view"
@@ -22,6 +23,7 @@ import (
"os"
"os/signal"
"slices"
"strconv"
"strings"
"sync"
"syscall"
@@ -191,6 +193,18 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
if err := hearWaits(ctx, hub, js, own.Waits, logger.Printf); err != nil {
return fmt.Errorf("the waits' events are not handled: %w", err)
}
// The pipelines page reads the seat mesh-pipeline-runner's list and show, and reads again on the runner's events heard on
// the module's one pull, never on a timer (design 47 H2 H-A-467); the watched branches' lists link each delivery.
heard, err := numberFile(getenv("MESH_DELIVERY_VIEW_PIPELINES_HEARD_FILE"), view.DefaultPipelinesHeard)
if err != nil {
return fmt.Errorf("the setting pipelines-heard: %w", err)
}
pipes := view.NewPipelines(calls.Call, branches.Followed, heard, logger.Printf)
model.SetPipelines(pipes)
if err := hearPipelines(hub, pipes, logger.Printf); err != nil {
return fmt.Errorf("the runner's events are not handled: %w", err)
}
go pipes.Run(ctx)
if err := hub.StartUntilBound(ctx, js, cred, nil, nil); err != nil {
logger.Printf("the consumer is not heard yet (tried again until it is): %v", err)
}
@@ -536,3 +550,27 @@ func (c *catalogModules) apply(module string, entry meshcatalog.CatalogEntry, li
e.History = true
c.model.Apply(e)
}
// numberFile reads a setting the node-engine writes into a file of the state directory: def when path is empty, the file
// missing or empty; an error when it holds no number of at least one.
func numberFile(path string, def int) (int, error) {
if path == "" {
return def, nil
}
raw, err := os.ReadFile(path)
if errors.Is(err, fs.ErrNotExist) {
return def, nil
}
if err != nil {
return 0, err
}
v := strings.TrimSpace(string(raw))
if v == "" {
return def, nil
}
n, err := strconv.Atoi(v)
if err != nil || n < 1 {
return 0, fmt.Errorf("%s holds %q, which is not a number of at least one", path, v)
}
return n, nil
}

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