Compare commits

...
257 Commits
Author SHA1 Message Date
jschoubben ce7669d433 Builder: its whole test waits on version-reserved by name after a reservation
The publish queue's whole test reserves m4 and waits on the seat
mesh-builds' version-reserved by its subject, said as the process says it
(sayReservedOn, now one function main and the test share); without the
event the step fails. Also gofmt of the pipeline's order_test.go.

Builds: design 47 H2 §821, §805; review round 2 finding 2
2026-11-22 03:58:49 +01:00
jschoubben 473451f7e6 Builder: its process runs on the module's account again, with no bus
A process account is granted only what its bus names, never its seat's
work, so a builder on an account of its own could build nothing at its
first start. The process declares no bus and takes the module's broker
credential, as before B13; as the module's one process it is the one
reader of the work queue publishes. Class, caps, settings and the
publish-queue removal stay. The validator built at this head accepts the
builder in the change case (the trunk case refuses it: no class, uncapped
states).

Builds: design 47 H2 §793, §820; H-A-464 (corrects H-A-454 second addendum); review round 2
2026-11-22 03:56:30 +01:00
jschoubben 5f090cd99f Indexer judge: one busless process is its module's work-queue reader
A module whose one process declares no bus runs that process on the
module's account, so its work-queue stream is read by exactly one process
without naming it in bus.queues; two processes, or one with a bus, still
name the reader. Lets the builder keep its process on the module's account.

Builds: design 47 H2 §793, §820; H-A-464 (ADR 0436 §6); review round 2
2026-11-22 03:52:44 +01:00
jschoubben a5e10c70e2 Join: merge feat/47-H2-f3 into feat/47-H2 2026-11-22 03:39:45 +01:00
jschoubben b0a614779d Join: merge feat/47-H2-f2 into feat/47-H2 2026-11-22 03:39:45 +01:00
jschoubben c9d7b1365a Join: merge feat/47-H2-f1 into feat/47-H2 2026-11-22 03:39:45 +01:00
jschoubben 342da2c625 I4 fix: §805's whole criterion is a step of the indexer's whole packages test
Review round 1 found §805's whole criterion (a release of a module
importing twenty packages of its own pipeline keeps one re-pin revision)
unit-tested only. It becomes a step of
TestASourceRevisionMovingMeshSDKNamesItAndItsImporters, the indexer whole
against an embedded bus: twenty version-reserved of mesh-sdk in main's
revision are kept in heard, its pipeline-started keeps one re-pin revision
(importer its mover, pinned to the reserved version), and the next
pipeline's reservation keeps the revision after it. The bed's indexer
durable on EVENTS now takes version-reserved, as the manifest's consumes
name it. The step fails when pipeline-started does not settle the
gathering.

Builds: design 47 H2 §805; H-A-453 (3)
2026-11-22 03:37:26 +01:00
jschoubben e611103ec9 §819: the delivery SDK's count of transport-fault runs is a row of the again table
The test that a transport fault counts the runs that started, not the bus's
deliveries, is folded into the again-delays table as its second run, so the
SDK's unit tests fall by one instead of rising.

Builds: design 47 H2 §819 (H-A-453 (4): a module's count never rises in a change)
2026-11-22 03:31:56 +01:00
jschoubben dde4108504 I1 fix: §802's whole criterion is a step of the indexer's whole packages test
Review round 1 found §802's whole criterion (a commit touching two test
files of two modules of 36 moves those two and their importers alone)
unit-tested only. It becomes a step of
TestASourceRevisionMovingMeshSDKNamesItAndItsImporters, the indexer whole
against an embedded bus: the catalogue holds 36 modules, lib-a and lib-b
among them, required by app-a (require) and app-b (require and replace);
a commit changing lib-a's and lib-b's trees alone moves lib-a, lib-b,
app-a and app-b and none of the other 32. The step fails when the
repository's commit enters the tree input, and when a derived directory
does not.

Builds: design 47 H2 §802; H-A-453 (3)
2026-11-22 03:31:00 +01:00
jschoubben 81ea73a45f R1 (§775): a composition ask whose holder is away passes its step, a step of the runner's whole test
The holder of mesh-wants is away while a re-pin asks the composition again:
the put meets no responders, is put again at the kept-call pace (a hundredth
of its default, so 40 s is 400 ms) and lands once the holder is back; the step
then passes with no hand act.

Builds: design 47 H2 §775 (H-A-453 (3): the whole criterion proven at its level)
2026-11-22 03:30:37 +01:00
jschoubben d68e71700a builder: the slow-event and events-behind-bound bounds are settings (F3)
The review found §794's two bounds fixed in code: the builder's 100 ms
for saying a slow event's handling, and builder_health's five minutes
for naming a consumer behind. Both become settings read at run time,
slow-event (100ms) and events-behind-bound (5m), declared in the
manifest's config with those defaults; a value that is no duration
refuses the builder's start, and makes the health say it.

Builds: design 47 H2 §794, H-A-461 (2)
2026-11-22 03:30:26 +01:00
jschoubben c0489000ba I6 fix: the seat-list's whole criterion is a step of the indexer's whole input test
Review round 1 found §814's whole criterion (a run by hand against
seat-list gives the live validate's verdicts for the builder's and the
runner's manifests) unit-tested only. It becomes a step of
TestIndexerAnswersARunsInputOverOneMiBInChunks, the indexer started whole
against an embedded bus: with the tests' seat list in seat-definitions the
indexer keeps it in seat-lists and hands it by the verb seat-list in
chunks; the object read by its address gives the same bytes, and the
judge's verdicts for the two manifests from the verb's bytes and from a
request file read again as cmd/mesh-judge reads it are the same.

Builds: design 47 H2 §814; H-A-453 (3)
2026-11-22 03:29:51 +01:00
jschoubben eac4dca2a7 builder: prove the tag at another commit and the six-minute backlog whole (F2)
The review found §794's backlog and §796's tag at another commit proven
only by unit tests. Both become steps of the builder's whole test on the
embedded bus: a reservation skips 0.2.0 whose tag stands at another
commit, takes 0.2.1 with the finding version-tagged-elsewhere, the
release writes modules/m4/v0.2.1 at the build's commit and the
version-released heard from the bus clears the finding; a message the
handler asks again is kept on its consumer's ledger in the state
consumers on the bus, and the health held six minutes names it.
The health judgement moves from the tools program's main into
internal/versions (BuilderHealth), which the tools program calls, so the
whole test can prove it. The test's comment no longer says the old state
is dropped through the bus module (F1).

Builds: design 47 H2 §794, §796, H-A-453 (3), H-A-435, H-A-462
2026-11-22 03:28:57 +01:00
jschoubben 7cf8ea380e D2 (§821): the runner says re-pinned where a re-pin lands; its whole test waits on its events by name
A kept mover's re-pin was declared in the runner's seat but never said, so a
wait on mesh-pipeline-runner.re-pinned was never answered. The runner's whole
test now waits on pipeline-started, step-ended, pipeline-ended and re-pinned by
seat and name, a same-source re-pin revision being one of its steps.

Builds: design 47 H2 §821 (round-1 finding: EventRePinned unused outside the contracts)
2026-11-22 03:27:57 +01:00
jschoubben 61d6424c44 I2 fix: a take-in's waiting line and bound are settings
Review round 1 found the take-in's waiting bounds fixed in code
(takein_waiting.go:23-24, one and five minutes). They become the settings
take-in-waiting-line (default 1m) and take-in-waiting-bound (default 5m),
declared in the manifest and read at the start as reserved-keep is; zero
on the indexer takes the defaults. The waiting test gains a row with the
settings at 2m and 10m and checks the bounds the wait asks; the manifest
test's settings rows gain the two keys.

Builds: design 47 H2 §803; H-A-461 (2), P11
2026-11-22 03:25:03 +01:00
jschoubben a75d2d07bf I6 fix: the indexer's heard is capped at 32 MiB, above its live fill
Review round 1 found heard capped at 8 MiB (module.json:137) while its
live fill is above a quarter of that. Fill read 2026-11-22 02:23 UTC with
nats.nats_buckets on novox (the bus module's show makes no entry for a
foundation part's old-section state): mesh-delivery-indexer_heard
4,654,001 bytes (4.44 MiB), 5,499 values. Four times the fill is
17.75 MiB; the smallest power of two above it is 32 MiB (H-A-437).

Builds: design 47 H2 §814, §820; H-A-461 (3), H-A-437
2026-11-22 03:23:37 +01:00
jschoubben 3ff3987aa2 builder: remove the old publish-queue bucket itself after the move (F1)
The bus module's keeper made no entry for the builder's old-section
publish-queue, so nats_drop refused it at every start and the move
re-put its items after the 24 h window. The builder, which made the
bucket, now deletes it itself once every item is on the work queue;
the manifest no longer names publish-queue nor invokes nats.nats_drop.
The whole test proves the move and the removal on the embedded bus,
and a second move of the same items after a stopped start puts each
once. Also corrects the publishes comment: the process consumes the
work queue on its own account (H-A-454 second addendum).

Builds: design 47 H2 §793, H-A-461 (1), H-A-454 (second addendum)
2026-11-22 03:23:19 +01:00
jschoubben a63f4e001b I6 fix: the seat-list's unit test is a row of TestTheControlRecords
Review round 1 found the indexer's unit tests rose by one in H2
(seatlists_test.go:75, TestTheSeatListIsOneObjectByItsDigest). §819 as
H-A-453 (4) reads it: a module's count never rises in a change. The test
becomes the row "seat-list" of TestTheControlRecords, its steps unchanged,
so the count stands where main has it.

Builds: design 47 H2 §819, §814; H-A-453 (4)
2026-11-22 03:22:39 +01:00
jschoubben abfe37e690 Join: merge feat/47-H2-b into feat/47-H2
No conflicts. The mesh-builds contract is regenerated with seatgen: -b's
publish-queue verb and feat/47-H2's descriptions meet in one
VerbDescription (seatgen -check clean).

Builds: design 47 H2 (join of the develop step, playbook 07)
2026-11-22 02:49:04 +01:00
jschoubben 56ca9a9791 M-class (view): class core, every state capped, the finding stream at 8 MiB
The view claims the seat mesh-delivery-view, so its class is core and every
store it keeps names its cap. Fills read on novox (nats_buckets, 2026-11-22
02:50), all under a quarter of 8 MiB, so 8 MiB each: reach 280,654 bytes,
waits 39,678, first-views 7,521, findings 3,400, view-marks 237, answers 0.
Its finding stream keeps 7 days at 8 MiB, not 16.

Builds: design 47 H2 §810, §812, §814, §820; H-A-394 (1), H-A-437
2026-11-22 02:48:54 +01:00
jschoubben 380412d94f M-class (assigner): class core, every state capped above its live fill
It claims the seat mesh-wants, so its class is core, and every state it
keeps names its cap. Fills read on novox (nats_buckets, 2026-11-22 02:50):
findings 3,507,749 and proposals 3,648,514 bytes, above a quarter of 8 MiB,
so 16 MiB (the power of two above four times the fill); every other state
under 2 MiB, so 8: wants 1,737,869, written 889,116, waits 780,485,
candidates 564,884, asks 513,017, puts 442,260, placement 221,392,
differences 176,358, assignments 147,691, seat-holders 80,508, engine-reads
38,397, pulses 5,100, first-views 4,631, view-marks 1,776, copies 140,
policies 0, put-waits 0.

Builds: design 47 H2 §810, §812, §814; H-A-394 (1), H-A-437
2026-11-22 02:48:27 +01:00
jschoubben 1146a6a37f M-class (teller): class leaf, the finding stream at 8 MiB
The teller claims no seat, so its class is leaf, declared by the same rule;
its finding stream keeps 7 days at 8 MiB, not 16.

Builds: design 47 H2 §810, §820; H-A-394 (1)
2026-11-22 02:48:06 +01:00
jschoubben eb02389d45 M-class (watchman): class core, the finding stream at 8 MiB
It claims a seat, so its class is core; its finding stream keeps 7 days at
8 MiB, not 16.

Builds: design 47 H2 §810, §814, §820; H-A-394 (1)
2026-11-22 02:48:06 +01:00
jschoubben 6545469a2b M-class (enrolment): class core, the finding stream at 8 MiB
It claims the seat mesh-node-enroller, so its class is core; its finding
stream keeps 7 days at 8 MiB, not 16, as every module's does (live fill of
its findings state: 0 bytes).

Builds: design 47 H2 §810, §814, §820; H-A-394 (1)
2026-11-22 02:47:46 +01:00
jschoubben 8c50d77b04 M-class (grants): the grants part's manifest says class core
It claims the seat mesh-grants, so its delivery carries a contract of the
mesh; the manifest check refuses a seat-claiming manifest with no class.

Builds: design 47 H2 §810, §814; H-A-394 (1)
2026-11-22 02:47:46 +01:00
jschoubben bb1ab9f10d M-class (pipeline): the runner's manifest says class core
The runner claims the seat mesh-pipeline-runner, so its delivery carries a
contract of the mesh: the manifest check refuses a seat-claiming manifest
with no class. Its states already name their caps.

Builds: design 47 H2 §810, §814; H-A-394 (1)
2026-11-22 02:47:10 +01:00
jschoubben f756718324 B10: build_current asks every build seat's holder its current, in turn
The tools bundle follows the seat-holders view of the claimant of
mesh-module-assigner, names each build seat's holder per node from it, asks
each holder's current at its node one after another and answers them
together, a holder that does not answer listed with why; it reads no presence
and chooses no node. The manifest lists the tool and the three build seats'
current among the module's invokes, outside the process's bus.

Builds: design 47 H2 §801; H-A-446 (1)
2026-11-22 02:44:18 +01:00
jschoubben 5e6ebefd47 B13: the builder's manifest names what its process does, on an account of its own
The manifest says class core (it claims a seat), caps every state by the fill
read on the bus (builds 128 MiB, findings and versions 32, bounds 16, the rest
8; H-A-437), keeps the findings history at 8 MiB for 7 days, invokes the bus
module's nats_drop for the moved bucket, and bounds publish-tries at 10 with 5
as its default. The process gains a bus of its own naming the work queue
publishes in queues with the module's emits, consumes, state and invokes, its
credential broker-builder, so the validator accepts the work-queue stream read
by exactly one process. Verdict: the judge at feat/47-H2-i ce6c39e4 accepts the
builder in the change case and refuses it in the trunk case (no class,
uncapped states).

Builds: design 47 H2 §783, §812, §814, §820; H-A-394 (1), H-A-437, H-A-446 (2), H-A-454 second and third addenda
2026-11-22 02:41:30 +01:00
jschoubben 726592b74c V1 usage by current: build_usage judges a build seat by what its holder runs
A held module still runs its asks, and a have that says running proves
nothing about the holder: the usage view asks each build seat's verb current
on each node at once, says the seat held where its holder answers, counts the
asks it lists as running, and says a step key it does not list left running.
The node-engine's phase is shown and judges nothing. The manifest invokes the
three build seats' current.

Builds: design 47 H2 §813 (9), §801
2026-11-22 02:40:15 +01:00
jschoubben b6a7e0bad3 B4 (H-A-454): publishes is the builder's own work-queue stream, read by the verb publish-queue
The work queue publishes is declared in the manifest's old streams section
(retention work-queue, duplicates 24 h, max-deliveries 10, 64 MiB, 7 days), the
module's own stream consumed on the module's account, so the bus binding asked
of the broker seat goes; the consumers per holder and class are still made at
run time. The seat mesh-builds gains the read verb publish-queue, served by the
builder from its own stream (counts per holder and class, oldest and newest, a
list capped at 50, capped past 4,000 items read), and builder_publish_queue asks
it in place of the runtime's stream and work-queue reads. Two whole tests of a
gone artifact are folded into one, so the builder's integration count stays at
18 with the publishes whole test.

Builds: design 47 H2 §793, §819, §820; H-A-440 (1), H-A-446 (2), H-A-454 and its addendum
2026-11-22 02:35:32 +01:00
jschoubben b65b617361 Join fix: the forge bridge reads the kept-call pace as mesh-sdk's function
mesh-sdk a323a3fd made busretry.KeptPace a function read once and held
atomically; the bridge (from feat/47-H2-a) still read it as a variable and
did not compile against it.

Builds: design 47 H2 §782
2026-11-22 02:35:19 +01:00
jschoubben 474ef0335a Join: merge feat/47-H2-a into feat/47-H2
No conflicts; no side raised a form of mesh-wants or mesh-delivery, so both stay
at 2. The mesh-wants contract is regenerated with seatgen: the keep-now verb
(-a) and the drop verb's description (feat/47-H2) meet in one VerbDescription
(seatgen -check clean).

Builds: design 47 H2 (join of the develop step, playbook 07)
2026-11-22 02:33:58 +01:00
jschoubben ed3c4a2297 Join: merge feat/47-H2-i into feat/47-H2
No conflicts; the mesh-catalog seat's form 5 is -i's (feat/47-H2 left it at 3),
and its contract is regenerated with seatgen so the seat-list verb's description
follows the merged seat.json (seatgen -check clean).

Builds: design 47 H2 (join of the develop step, playbook 07)
2026-11-22 02:33:37 +01:00
jschoubben ce6c39e46c I6 (5): the judge's tests read the catalogue at the group's head
The captured catalogue beside the judge (testdata/beside) is re-archived from
mesh-catalog 30a3e665 (feat/47-H2, the delivery group's catalogue head), so the
judge's rules are tested against manifests that name their class where they
claim a seat; the catalogue fixtures of judge and internal/index move from
835bf22b and a67f0196 to 30a3e665 (ca-trust refreshed; avahi, audit-logger and
netcheck kept at a67f0196, which they still match). Tested against mesh-sdk
a323a3fd (seatlisttest holds the group's definitions); the build seats' check
now holds current, pause and resume among the verbs the seats' definitions
serve, which have grown since 1887.

Builds: design 47 H2 §814, H-A-428, H-A-452
2026-11-22 02:31:52 +01:00
jschoubben d6d15a5497 B4: the publish items travel on the work queue publishes, live first
The bucket publish-queue listed and reread itself before each send; its items
now ride the builder's work queue publishes, pulled per holder and class by
consumers the builder makes as it learns a holder, the live class first, a
failed send handed back with the pause, an item acknowledged when its publish
is heard and terminated when its build is withdrawn, superseded or dropped.
builder_publish_drop and builder_publish_first act through reasks after the
hand-act log; builder_publish_queue reads the queue through the runtime. The
old state's items are moved once at the start, then dropped through the bus
module.

Builds: design 47 H2 §793, §820; H-A-290, H-A-291, H-A-440, H-A-446 (2), H-A-448
2026-11-22 02:22:59 +01:00
jschoubben 80ff1afacc §819: the runner's tests folded to 104 unit and 3 integration
Eight unit tests and two integration tests become rows of the test they
sit beside (t.Run of the same body), so the runner ends below its start
of 105 unit and 4 integration tests counted by top-level function.

Builds: design 47 H2 §819
2026-11-22 02:19:17 +01:00
jschoubben 5e94328066 I7 (4b): a repository with no module registers as a source alone
register takes the source form (a check of a build seat and a step kind,
no module, no path, one branch) and keeps it, its history and its
registration-changed under source.<owner>.<name>. One whose tree at the
branch's head holds a module.json at its root or under modules/, read
through the seat git's trees, is refused holds-manifest. A move of its
branch is taken in with no movers.

Builds: design 47 H2 §815, §806; H-A-349 DQ-9, H-A-438, H-A-450
2026-11-22 02:17:59 +01:00
jschoubben 3e90604eb4 D (H-A-450): register's refused names holds-manifest
A source-only registration whose repository holds a manifest is refused
by a value the enum names, so a caller registers its module instead. The
seat's form rises to 5; regenerated with seatgen, -check clean.

Builds: design 47 H2 §815; H-A-450 (1)
2026-11-22 02:16:59 +01:00
jschoubben 205a9256b8 H-A-401: the build-step part's drop says a dropped step ends could not run
The step-ended outcomes gain no dropped: the drop verb's description now
says both a waiting and a running ask end their step could not run, the
why naming the drop and who asked it, one way for an ask that never ran.

Builds: design 47 H2 H-A-401
2026-11-22 02:16:43 +01:00
jschoubben 14cd44b98e §823: the stale copies contracts/ and sdk/ at the repository's root go
No module built from them: every reader uses modules/mesh-delivery-contracts
and modules/mesh-delivery-sdk. Neither held a manifest, so the indexer's
module graph is unchanged. The repository check of the delivery SDK now
refuses a go.mod or Go import naming either root path again.

Builds: design 47 H2 §823
2026-11-22 02:16:07 +01:00
jschoubben 67caa79640 H-A-376: the runner's list answers short rows, show each mover's row
list answers by default the newest 20 short rows (key, call, start, end,
outcome, movers' count and the first failed or could-not-run step with its
module and why), and the whole pipelines only with full and a limit. show
answers one mover's steps when it names one, the steps its filters hold,
or else each mover's row, never every step of every mover. The tools
program describes each seat verb's tool from its contract, which seatgen
now generates a VerbDescription for; runner_cancel reads the whole
pipelines with full. The runner seat's form is 6.

Builds: design 47 H2 H-A-376, H-A-449, §789
2026-11-22 02:14:51 +01:00
jschoubben 9ab1c3b8f3 H-A-375: a declined pipeline step is put again on a node that has its need
A holder whose node lacks what a step's packages need (the artifact's
check-needs, now named on the integration step's ask) says the step's end
declined with needs and lacks, in place of could not run. The runner puts
it again under a new ask id naming in not-on the nodes that declined it;
a holder on a listed node hands it back at once. The nodes that can take it
are the holders of the step's seat and of the need's seat less those that
declined; when none is left the step ends could not run naming the need
and the nodes asked. The build-step part's form is 3, the runner seat's 5.

Builds: design 47 H2 H-A-375, H-A-445 (ADR 0552 §2, §4)
2026-11-22 02:08:40 +01:00
jschoubben 6b0ccc5d27 I6 (4a): the indexer builds no candidate for a source-only check
A run member or mover named source.<owner>.<name> is a source-only
registration's check, which the runner runs as one step: StartRun builds
it no candidate and keeps no run, and its pipeline-ended keeps none either.

Builds: design 47 H2 §815; H-A-438, H-A-442
2026-11-22 02:07:36 +01:00
jschoubben 7d58b2e56f H-A-441: the validate step takes the trunk's seat list from seat-list and names its digest
A revision that names no definitions of its own is judged by the trunk's
seat list as the seat mesh-catalog's chunked verb seat-list hands it, asked
as a kept call under the run's ask: its bytes fill Request.Seats and its
digest is the request's seat-list, the bytes refused when their size or
sha256 is not the answer's, so every validate run of one list judges the
same bytes and the validator reads no bus. A revision naming its own
definitions keeps them, sorted by seat, and names the sha256 of those
bytes. The manifest invokes seat:mesh-catalog.seat-list.

Builds: design 47 H2 §814; H-A-441, H-A-443
2026-11-22 02:06:47 +01:00
jschoubben f838a6c34c I6 (3): the indexer's manifest names its class, a cap on every state, and the kept-call pace
class core (it claims mesh-catalog). Every state names its cap. Fills read
with the bus module's nats_buckets on novox, 2026-11-22 ~02:20 CET (its
show answers only entries the bus module made, not old sections):
candidates 3,963,006 B (3.78 MiB) -> 16 MiB; manifests 5,463,959 B
(5.21 MiB) -> 32 MiB; seat-definitions 4,392,352 B (4.19 MiB) -> 32 MiB;
at 8 MiB, each at or below 2 MiB: packages 767,959; takeins 468,577;
findings 293,571; registrations 111,058; inputs 26,473; taken 5,595;
predefined 4,215; requirements 3,945; view-marks 3,068; first-views 1,554;
oldsections 256; runs 152; held 140; build-edges 0. Seventeen states, not
the sixteen the handover counted. The findings stream keeps 8 MiB, 7 days.
kept-call-pace-first 1s and kept-call-pace-max 30s, runtime settings, as
it makes kept calls.

Builds: design 47 H2 §775, §783, §810, §812, §814, §820; H-A-394 (1), H-A-411 (1) (2), H-A-437
2026-11-22 02:05:29 +01:00
jschoubben 381934396b I6 (2c): the indexer keeps the seat list at its start too
Once the seat definitions' state is bound at the start, the indexer keeps
the seat list in seat-lists, so seat-list answers from the first delivery
and never refuses "not kept yet" for want of a trunk definition's move.

Builds: design 47 H2 §814, §820; H-A-447
2026-11-22 02:04:18 +01:00
jschoubben 6ebc63dce3 Merge commit 'c8ba4863' into feat/47-H2-a 2026-11-22 02:04:13 +01:00
jschoubben a343fddfe7 I6 (1): the indexer's integration fixtures that claim a seat name their class
The whole indexer's hand manifests of a build module and of the assigner's
holder claim a seat, so they name class core, as the judge now asks; with
none, every take-in of those tests refused them and waited out its bound.

Builds: design 47 H2 §814; H-A-394 (1)
2026-11-22 02:03:04 +01:00
jschoubben c8ba486318 I6 (2b): the indexer keeps the seat list as one object and hands it by seat-list
At each trunk seat-definition move (said or not) the indexer writes the
trunk's definitions, resolved, as one JSON array sorted by seat into its
objects seat-lists under its sha256, when not held, and deletes every
object but the newest two, never the one just kept; one journal line per
write and delete. Its process serves the chunked verb seat-list: digest,
size and chunks, then the object's bytes; a list not kept yet is refused
naming it. The manifest serves seat-list and declares seat-lists in its old
objects section at 64 MiB. composer.Request gains seat-list, the digest of
the bytes Seats were filled from; the judge reads Seats alone.

Builds: design 47 H2 §814, §820; H-A-441, H-A-443 (1)
2026-11-22 02:00:07 +01:00
jschoubben 92ba593639 I6 (2a): the seat mesh-catalog's seat-list hands the seat list's bytes in chunks
seat-list is a chunked read verb, as input is: input call (128 random
bits), answer digest (the list's sha256, its object's name in seat-lists),
size and chunks, then the bytes on the call's chunk subject. The object
name leaves the answer. The seat's form rises to 4; regenerated with
seatgen, -check clean; the fixtures read so.

Builds: design 47 H2 §814, §820; H-A-441, H-A-443 (1)
2026-11-22 01:57:10 +01:00
jschoubben b45f12f70f B8: the builder's record of a build carries its end and outcome
The artifact store's sweep read each done key's history to learn when its build ended.
A done or failed key now carries ended and outcome, written with its end (kept as it was
when the same end is written again), so a reader of the builds reads no key history.

Builds: design 47 H2 §797
2026-11-22 01:57:04 +01:00
jschoubben c8cc249a90 B7: a tag names its commit; the builder reads a module's tags before it reserves
A number whose tag stood at another commit was reserved again, and a Go package outside
mesh-sdk's go directory was tagged go/v<version>, which the Go toolchain never reads. The
builder now reads the Go package's tags once per catalog revision, skips a number tagged at
another commit with the finding version-tagged-elsewhere (cleared at the next release), and
tags <directory>/v<version>, the directory read from the package's module path.

Builds: design 47 H2 §796
2026-11-22 01:54:49 +01:00
jschoubben b3724ca0f4 Merge feat/47-H2-sdk (9a7cc2b6) into feat/47-H2
The delivery SDK's step parts land beside the runner's work, so H-A-375
builds on them. The registrations client's test names no other seat, as
the generator's check of ADR 0625 §4 asks.

Builds: design 47 H2 H-A-375 (its base)
2026-11-22 01:50:22 +01:00
jschoubben ba54f82a70 I6 (1): the judge refuses an uncapped delivery store and a seat claim with no class
A delivery module (one claiming a seat of the delivery system, read from the
seat list's definitions) is refused for a state, log or objects entry with no
cap, in its old section or in requires; a seat-claiming manifest names class
core or leaf; finding-events is 8 MiB, 7 days; the objects template takes
max-age-days. internal/beside says a group's check reads the catalog member's
head beside it, main only when the catalog is not in the group.

Red until the captured catalog is refreshed (I6 (5)): judge
TestRulesSecrets/EveryCatalogueIdentityFitsWhatItRequires,
TestRulesSecrets/ParseManifestForInputsReadsAValueFallingBackToAPredefinedKey,
TestRulesPlacement/TheCataloguesBarPlacesBlocksAndItsShapeCoversEveryShow,
TestRulesBus/NoCatalogueManifestNamesAnInstallation; internal/index
TestAnArtifactOfNoToolchainHasNoLanguageAndNoLock,
TestAMergedManifestIsKeptOnceByItsDigestAndNamedByTheModule,
TestAModuleWithNoToolchainArtifactGetsItsFingerprintAtOnce,
TestAManifestFallingBackToAPredefinedKeyIsRead (each a captured catalog
manifest with no class, or finding-events at 16).

Builds: design 47 H2 §814, §820, §783; H-A-394 (1), H-A-411 (1) (4), H-A-415 (1), H-A-428, H-A-430 (3), H-A-434
2026-11-22 01:49:26 +01:00
jschoubben 76b1ea11a9 R13 (H-A-406): a build that passes places again the steps not asked on it
A mover's build that passes, a rerun's among them, takes out of its
pipeline the steps that ended not asked because it did not build, by the
same take-out a hand-off uses, and the pipeline's placing places those
movers again: their dependents need no hand rerun. The journal says it.

Builds: design 47 H2 H-A-406 (H-A-361's kind)
2026-11-22 01:48:41 +01:00
jschoubben 8e926283e3 R12: the runner's manifest: its findings history drops its oldest at 8 MiB, every state capped, the kept call's pace
The findings stream is 8 MiB, kept 7 days, its oldest dropped when full
(no findings-max-age setting: nothing reads one). Every state names its
cap: 8 MiB, bounds 16 MiB above four times its live fill (2,188,123 bytes
on novox, 2026-11-22 00:16 UTC; queue 50,604, findings 285,807, the rest
under 3 KB). ask-silent-bound, its file and its environment go. The kept
call's pace is declared, kept-call-pace-first 1s and kept-call-pace-max
30s, read at runtime. The runner consumes mesh-builds' and mesh-wants'
ask-taken and invokes their drop. The whole test writes 10,000 findings
past the manifest's cap and none is refused.

Builds: design 47 H2 §783, §775, §777, §778, §820; H-A-411 (1), (2), H-A-437
2026-11-22 01:47:16 +01:00
jschoubben 13d960a120 F1: an owed act failing on a part away stays owed, and a record's acts are performed again
An owed act met by the forge away (401 while the store was replaced) ended
could not be performed and nothing performed it again. Each act is now a kept
call at the module's pace (kept-call-pace-first, kept-call-pace-max) until
owed-away-bound (60 minutes), then ends could not be performed naming every
try. Before each try the bridge reads the pull request through the seat git's
pull: one closed unmerged ends owed.ended not-needed, never performed. The
gate's owed event gains record (the delivery record's source revision), kept
with the act in performed, and bridge_owed_again by record and why performs
again every act of that record that ended could not be performed, written in
the hand-act log first.

Builds: design 47 H2 §807, §775, §819, H-A-432
2026-11-22 01:46:49 +01:00
jschoubben 29162d170c B5 (H-A-435 second addendum): the builder's process health stays kind unit, builder_health a tool beside it
A tool-only health is refused by the validator (ADR 0227 rule 8, ADR 0240 rule 2), as the
runner's manifest has it: the unit check stays, the tool reads the consumers beside it.

Builds: design 47 H2 §794; H-A-435 second addendum
2026-11-22 01:46:25 +01:00
jschoubben aac7476cfe B11: a package's number newly reserved is said as version-reserved
The indexer re-pinned every importer at each publish; it re-pins once at the reservation
when the builder says version-reserved, with the package's path and the indexer's revision name.

Builds: design 47 H2 §805; H-A-420 (2)
2026-11-22 01:43:29 +01:00
jschoubben 515688cf6f R11: a source-only registration's head is run on request as its check's one step
A run whose one member is a source-only registration's key
source.<owner>.<name> runs that registration's check: one step of its
kind on the build seat it names, at the repository's root, asked on the
seat's check stream as every step, its status the registration's policy's.
Its mover is the registration's key, its repository the origin and its
fingerprint the commit's root tree hash, read through the seat git's trees
as a kept call; so its step-ended names the key, escaped into one subject
part, and the tree. A candidate's revision places nothing of it; at its
turn in the queue its step is placed from its registration. A source member
beside another, or a key with no source-only registration, is refused. The
registrations follower keys a source-only registration by its key.

Builds: design 47 H2 §815, §775; H-A-408, H-A-438
2026-11-22 01:43:20 +01:00
jschoubben 83caf486b6 B5 (H-A-435): the builder's health is builder_health, and a slow event is one journal line
The builder said nothing when its events backed up or one handling stood still; its health
now reads each durable consumer's oldest unacknowledged message from its state consumers,
and an event handled over 100 ms is said with the part that took it.

Builds: design 47 H2 §794, §820; H-A-435 and its addendum
2026-11-22 01:41:11 +01:00
jschoubben bcff47d257 B6 (H-A-425): a plan no seat builds is kept in the state unbuildable and said in one line
A line per module drowned the journal at 6,500 plans; the plans live on the bus, where
builder_unbuildable reads them, and the builder says them once per start and per seat list change.

Builds: design 47 H2 §795, §820; H-A-425
2026-11-22 01:37:32 +01:00
jschoubben b76b9c58f4 F2: the bridge's state performed is capped and pruned toward its cap at the bridge's own writes
performed filled on 2026-11-21 with nothing to stop it. It is now bound through
mesh-sdk's process.PrunedState: its figures are read when the bridge opens the
bucket its binding names, each write is counted, and past prune-mark (70 %) the
oldest acts are purged to prune-target (50 %) in one journal line, a key kept
under _keep/<key> staying. The bus drops acts older than three days by the
entry's TTL (performed-keep). performed, heads and owed-asks name an 8 MiB cap.
The tools bundle serves mesh-delivery-forge-bridge_state_prune_now and
_state_keep from stateobjects.PruneTools, each written in the hand-act log.

Builds: design 47 H2 §812, §819, H-A-380, H-A-386, H-A-411 (2), H-A-433
2026-11-22 01:36:34 +01:00
jschoubben 40c2870a71 I4: a release re-pins once, at its reservation
The builder's version-reserved writes the series' numbered version with the
contents of the module's entry commit, so acceptedSeries and releasedPins pin
it; the indexer keeps each reservation in heard (reserved.<revision>.<module>,
reserved-keep) and gathers a revision's reservations until its pipeline's
start, its first step-ended or the expiry of settling.<revision>
(reserved-settle), then keeps one re-pin revision of that branch. The release's
package-published moves no fingerprint; a pipeline-ended not passed withdraws
its reservations to the newest released version.

Builds: design 47 H2 §805; H-A-418, H-A-420, H-A-424, H-A-436
2026-11-22 01:35:56 +01:00
jschoubben 9a7cc2b632 BM publish version (sdk): publishParts refuses a Go package or a bundle that names no version
A publish by its digest alone marks no reservation, so no build module may publish a Go package or a
bundle without the version its ask reserved; the refusal is loud and comes before the seat is asked.
An archive may still publish by its digest.

Builds: design 47 H2 H-A-373, H-A-373 (addendum)
2026-11-22 01:35:11 +01:00
jschoubben 38ad9ed84d R10: a step's output is read where its build seat's holder keeps it
runner_step_output (pipeline, mover, step) reads the step from the state
pipelines and asks the verb output of the build seat's holder on the node
its step key names, by the step's ask, once per artifact the step ran for;
a step that reads a shared run is answered by that run's ask. The runner
keeps no output of its own: the objects step-outputs go, with the step's
and the log entry's output and show's outputs; the runner seat's form
rises to 4. The manifest invokes the three build seats' output.

Builds: design 47 H2 §791; H-A-412 (1)
2026-11-22 01:34:54 +01:00
jschoubben d096ba37e3 BM3 install queue (sdk): DeclareAskWorkers declares a seat's every queue, the Node seat's install too
A node puller bound no install worker, so the Node build seat stopped taking its install asks: the
workers are now declared per AskQueues(language), not AskKinds.

Builds: design 47 H2 H-A-403
2026-11-22 01:33:35 +01:00
jschoubben 7ed668fa53 I7: a catalog entry carries its manifest's class
The gate reads a mover's class from its catalog entry when it opens the
delivery record, so the indexer writes the manifest's class there.

Builds: design 47 H2 §810; H-A-394 (1), H-A-431 (1)
2026-11-22 01:32:06 +01:00
jschoubben 9b2b2a934c Merge commit '84989daf' into feat/47-H2-i 2026-11-22 01:31:32 +01:00
jschoubben 84989dafb2 D7: a catalog entry carries its class
The seat mesh-catalog's CatalogEntry gains class, core or leaf; an entry
without it reads as leaf. The indexer writes it from the manifest. The
seat's form rises to 3; regenerated with seatgen, -check clean.

Builds: design 47 H2 §810; H-A-394 (1), H-A-431 (1)
2026-11-22 01:28:07 +01:00
jschoubben d13efa8abe R9: the stalled bound is the setting stalled-bound; the health names a step whose ask is untaken past it
Builds: design 47 H2 §790, §778 (the health line), §781 (read through mesh-sdk's settings reader)
2026-11-22 01:23:58 +01:00
jschoubben 40ad2650bd A4: a want of no pipeline carries the newest source held for it
A placement's build or a put written after a delivery carried the kept
graph's trunk source as its run, which can be older than the delivered
want's, so the compare-and-set refused a person's act (the whole test of a
placement back at a module's first build). The newest source the assigner
holds for such a want is now the kept trunk source or the run of the want
written, whichever is newer.

Builds: design 47 H2 §813 (1); H-A-416
2026-11-22 01:22:52 +01:00
jschoubben 43a88ef96c R7: the registration check waits for its view; runner_health answers registrations-read
Builds: design 47 H2 §788
2026-11-22 01:19:27 +01:00
jschoubben b9bc44024d A2: the seat mesh-wants' drop says the step ends could-not-run
The drop's description said a dropped ask's step ends "dropped", an outcome
the step-ended has not: it ends could-not-run, its why naming the drop and
who asked it, as the assigner says it.

Builds: design 47 H2 §778; H-A-401
2026-11-22 01:19:20 +01:00
jschoubben 477d351fc0 A4: a want carries its run and is written by compare-and-set refusing a lower one
Two writers of a node's want could leave it at an older delivery, and the
node-engine could not tell a newer want from an older one. Each want now
carries run: the source revision of the pipeline that released it, or, for a
want of no pipeline (a put, a placement's build, a removal), the newest
source the assigner holds. It is written by compare-and-set (create, or
update at the revision read), refusing a want whose run is lower than the
one written, said in the journal; a want that differs only by its run stands,
so no node composes again for it. The answer's other half is the node-engine's:
its manifest states declaration-reads and declaration-writes, the assigner's
neither.

Builds: design 47 H2 §813 (1); H-A-355 (1), H-A-416
2026-11-22 01:19:20 +01:00
jschoubben 8f89dd29f5 A2: the assigner reads an oversized run answer through the build seat's verb answer
The build-step part's output verb loses call and chunks (form 2): a
composition or validate run's answer over the inline bound is read through
the Go build seat's read verb answer (buildstep.StepEnded.ReadOutput, the
chunked call), so the manifest invokes seat:node-build-go.answer in place of
seat:node-build-go.output.

Builds: design 47 H2 §791; H-A-412 and its addendum
2026-11-22 01:19:20 +01:00
jschoubben 346b37d623 B2 (H-A-401): the seat mesh-builds' drop says a dropped ask's step ends could-not-run
Builds: design 47 H2 §778, H-A-401
2026-11-22 01:17:53 +01:00
jschoubben a43b722dbb BM4 kit (sdk): the conformance kit judges the build-step part's form 2
StepEnds also refuses steps that keep no outputs. SeatVerbs, which every build
module runs with its seat tools and steps, judges current, output and answer at
form 2, and runs a pipeline step whose test answer holds the level's text, a
NOT RUN skip and a failure, naming an install archive: its end must carry the
not-run, the archive must reach the test call and the run's output must be
read back through the module's verb output; an install is judged only where
the steps install, on node-build-node alone.

Builds: design 47 H2 §791, §800, §801; H-A-367, H-A-412, H-A-421
2026-11-22 01:16:57 +01:00
jschoubben 8d43ce0cb9 R6: a kept mover waiting on its kept revision says so; the record's kept-revisions are read past, not dropped
The runner seat's Mover gains unplaced (kept-revision-unread) and revision, the seat's form 3.

Builds: design 47 H2 §787, §780 (fate: the drop of kept-revisions before the decode goes)
2026-11-22 01:16:51 +01:00
jschoubben c623987fcc B1 (H-A-412): the builder reads an oversized step end through the build seat's verb answer
The wait answered "no verb to read" for every step whose end is kept as its
answer object: the process never set the asker's reader and its manifest
invoked no build seat's answer.

Builds: design 47 H2 §791, H-A-412 (addendum)
2026-11-22 01:16:34 +01:00
jschoubben 1aba89e8ba A6: a validate step counts only problems new against its case before
A take-in that touched a manifest failed its validate step on every problem
that manifest already had, so an old problem blocked any change to it. The
step now counts, for every manifest and between manifests, only the problems
the case before does not hold; assigner_validate_before (pipeline, module)
answers from the kept validate run the ones it holds and did not count.

Builds: design 47 H2 §814
2026-11-22 01:15:54 +01:00
jschoubben 7c9da7d0cb A5: a failed keeping of the assignment graph runs again, and by hand
A keeping that failed was handed again only by the next pass, so with no
change of inputs no revision was kept and no want said as wanted. A failed
keeping now runs again after keeping-retry (a runtime setting, 30s, the
holder's own deadline), unless a newer revision was handed meanwhile, and
raises keeping-failed (scope module) at the third failure in a row, cleared at
the next keeping that succeeds. The seat mesh-wants gains the act keep-now,
which the assigner's process serves: it keeps the pass's newest computed
revision at once, one keeping at a time, and answers the revision kept or the
fault met; the tool assigner_keep_now writes the hand act first and calls it.

Builds: design 47 H2 §813 (2); H-A-417
2026-11-22 01:14:05 +01:00
jschoubben 427885013e R8: a pipeline is read in parts: show filters while reading and pages at 768 KB; runner_show, runner_movers
Builds: design 47 H2 §789, §779 (the cursor), §811
2026-11-22 01:12:57 +01:00
jschoubben 02ec2f00d9 BM4 (sdk): a run's test output is kept as <node>.<ask> and read by the verb output
A test step takes the level's text out of its test answers (their member
output) and keeps it in the holder's outputs objects as <node>.<ask id>, a
header of its size and the failing tests with their words from the level's
results beside the text; a check ask's answer keeps none. The verb output at
the part's form 2 takes the ask and answers the text's last 64 KB, its size and
the failing tests from the header; no-longer-kept only when this node's steps
key shows the ask ended more than the max-age (7 days) ago, an ask never run
here refused naming it.

Builds: design 47 H2 §791, §820; H-A-367 (1), H-A-412 (1) and its second and third addenda
2026-11-22 01:12:46 +01:00
jschoubben 6ea33475b6 B1 (H-A-412): a step's oversized end is read as its answer object
The delivery SDK's build-step part keeps a step's end over the steps state's
value as the object answer.<ask>, read through the build seat's verb answer;
OutputObject is gone. The builder's wait names the answer object it could
not read.

Builds: design 47 H2 §775, §791; H-A-412
2026-11-22 01:12:25 +01:00
jschoubben cc5f803f87 I5: the registrations are read in one call, filtered and paged
The verb registrations and the new tool indexer_registrations filter by
module and repository while they read, at most 768 KB a page, capped with
the cursor next: the tools bundle reads the state from the bus's cursor
(mesh/state.page), a store that pages none by its keys in order; total is
said when one page holds the whole read.

Builds: design 47 H2 §806, §811, §779
2026-11-22 01:12:04 +01:00
jschoubben fad9f059ee BM4b (sdk): an end over the steps state's value is read through the verb answer
A step's end is an event, not a verb's answer, so an end over what the steps
state's value or step-ended carries has a reader of its own: keepOver keeps it
in the steps objects as answer.<ask>, the step key and step-ended carry
answer-object in place of output-object, and the build seats gain the read
verb answer (ask and call, marked chunks); output stays the run text's reader.
Step.Whole and StepEnded.ReadOutput read through answer.

Builds: design 47 H2 §791; H-A-412 (2) and its addendum
2026-11-22 01:08:58 +01:00
jschoubben d719a69b7d I3: a dry run keeps its packages in its own scratch state
A branch's take-in, a run's candidate and a branch's re-pin compute as dry
runs whose packages went to the trunk's packages state. They now write them
to the state dry-runs under <branch>.<call>.packages.<name>, read through to
the live state, deleted when the dry run answers and every key at the
indexer's start; the manifests stay create-once by digest as every take-in's.
indexer_dry_runs reads the state; the manifest asks for it, 16 MiB, one
hour's TTL.

Builds: design 47 H2 §804, §820; H-A-413 and its addendum
2026-11-22 01:08:34 +01:00
jschoubben 905a055a1e B2: the builder serves the seat mesh-builds' drop and its queue's tools
A caller whose step ended by its bound could not stop the builder working on
its ask, and nobody could see what waited on the seat's work queue. The
builder now serves the seat's verb drop: an ask it runs is cancelled, one not
pulled yet is kept dropped in its state taken (dropped.<ask>, for
ask-taken-bound); both end the step could-not-run naming the drop and who
asked it. builder_asks reads the waiting asks through the runtime and the
taken ones and the drops from the state taken; builder_ask_drop asks the
seat's drop once the hand act is recorded.

Builds: design 47 H2 §777, §778; H-A-401, H-A-404, H-A-410
2026-11-22 01:08:30 +01:00
jschoubben 48aa36120d A3: an answered validate or composition ask is one journal line
The journal said a step's end only when it failed to say it, so an ask's
answer could not be followed by reading the journal. The assigner writes
"answered <ask> <pipeline> <movers> <step> <outcome>" where the step's end is
said, the one place a validate or composition ask is answered.

Builds: design 47 H2 §792
2026-11-22 01:07:50 +01:00
jschoubben e216e94029 A1: the assigner asks each machine's compose-candidate as a kept call
A composition step ended at a node-engine's first "no responders": the
engine between two lives gave no input. The holder of mesh-wants now asks
compose-candidate through mesh-sdk's kept chunked call, under the ask id
<step ask>.<node> the engine takes once, called again at the kept-call pace
through transport faults until compose-ask-bound (a runtime setting, 10s).

Builds: design 47 H2 §775; H-A-405, H-A-364
2026-11-22 01:07:22 +01:00
jschoubben dc72860ce0 A2: the assigner pulls the seat mesh-wants' work queue and takes each ask once
A step ask put while the assigner was down waited for nobody: the plain
subscription heard only what came while it ran. The assigner now pulls every
waiting ask from the seat's one worker, takes it once by its id in its state
taken (for ask-taken-bound), says ask-taken at the pull, sends in-progress
while the step runs and acknowledges once the step's end is said. It serves
the seat's act drop: a running ask is cancelled, one not yet pulled is kept in
taken as dropped.<ask>; either ends its step could not run naming the drop.
assigner_asks reads what waits on the queue (stdio.QueueWaiting) and what is
taken or dropped; assigner_ask_drop ends one ask, written in the hand-act log.
The manifest declares taken, drop, the two tools, ask-taken-bound and the
kept-call pace as runtime settings.

Builds: design 47 H2 §777, §775, §778, §820; H-A-381, H-A-401, H-A-404, H-A-410
2026-11-22 01:05:07 +01:00
jschoubben 62e8274bf9 R5: a mover left unfinished by another's failure is put in a pipeline again
A pipeline ending failed or cancelled keeps each mover whose own required
steps passed or never ran in the runner's state unfinished and names it in
pipeline-ended's unfinished; the branch's next kept catalog revision carries
it, or starts a pipeline for it alone. runner_unfinished reads the state,
runner_unfinished_drop drops one key, runner_unfinished_place asks the new
seat verb place-unfinished (contracts regenerated), both hand acts.

Builds: design 47 H2 §786, §820 (unfinished), H-A-398
2026-11-22 01:02:58 +01:00
jschoubben 8bd66112f0 I2: a take-in says what it waits on
A source-moved take-in waiting over a minute on the seat git writes one
journal line and its waiting-on (part, verb, since) in the state takeins
under running.<source revision>, removed at the take-in's end; past five
minutes it raises take-in-waiting (scope merge), cleared when the wait
ends. indexer_pending answers the running take-ins beside the held ones.
The wait is measured by a context's bound, no timer (ADR 0437 §8).

Builds: design 47 H2 §803, H-A-409
2026-11-22 01:02:11 +01:00
jschoubben 8617b521a6 BM5 (sdk): a build seat's current says what it takes and every ask it runs
The verb current answers at the part's form 2: the node, whether it takes
asks and why not (paused, capacity 0, unhealthy) since when, its capacity, and
every ask it runs with who asked it. Each judgement keeps since when.

Builds: design 47 H2 §801; H-A-367 (2), H-A-399 (1)
2026-11-22 01:00:22 +01:00
jschoubben 8813c4e9e9 BM4a (sdk): a build seat's holder keeps its outputs in its outputs objects
steprun.OutputsStore names the holder's `outputs` objects, which its manifest
requires with their cap and max-age, in place of the steps state's own
objects store.

Builds: design 47 H2 §791, §820; H-A-399 (1)
2026-11-22 01:00:22 +01:00
jschoubben b00cf73d77 BM3 (sdk): an install is a StepAsk of the kind install, dispatched by RunAsk
node-build-node accepts install as a StepAsk holding an install job (the
InstallAsk's fields and the module's fingerprint) under the version its
archive is published with; install is its own queue on that seat alone and
its holder pulls it. RunAsk dispatches the kind to the module's install body,
which publishes the archive <module>:node-modules to the artifact store, and
the install's end names the reference it answered.

Builds: design 47 H2 §800; H-A-367 (4), H-A-379, H-A-399 (1) (2), H-A-403
2026-11-22 01:00:22 +01:00
jschoubben 7ffec1b56b I1: a module's fingerprint takes a package by what is published, never by a commit of its repository
A package of another repository none publishes leaves the module without a
fingerprint (NoPackageVersion) instead of taking the gate's source head; one
of the module's own repository none publishes enters by its directory's tree,
which the tree input carries, so the same source gives the same fingerprint.

Builds: design 47 H2 §802, H-A-349 DQ-8, H-A-350 DMC-5
2026-11-22 00:53:49 +01:00
jschoubben 592637e6d7 BM2b (sdk): a step's install archive reaches its test calls
The integration step's ask names the install archive; the step run carries
it on the check job it runs and hands it to every test call as its argument
archive, for the Go build module to unpack into the workspace.

Builds: design 47 H2 §800; H-A-367 (4), H-A-399 (1)
2026-11-22 00:53:20 +01:00
jschoubben 3fce8700bf BM2 (sdk): a test that cannot run says NOT RUN; a starved setup runs again
ReadGoTest answers the skips whose words open "NOT RUN:" as not-run with
their reasons; a pipeline test step carries them into its end, the level
passing. A level whose every failure is a starved setup (testbus.SetupStarved)
ends its run again by the again-delays; its third run ends the step could
not run "the bus did not answer in setup within <bound> under load", never
failed. A step's last run that meets a fetch or publish fault now says its
end failed with the why it opens with, so the runner hears it.

Builds: design 47 H2 §800, §799; H-A-294, H-A-367 (3), H-A-368, H-A-399 (1)
2026-11-22 00:53:20 +01:00
jschoubben 3a647a8e2d B3: an answered build ask is one journal line naming its ask
The line a build step's finish wrote named no ask, so an answer could not be
matched to the ask the runner put. BuildStep now takes the ask's id and its
finish writes "answered <ask> <pipeline> <movers> <step> <outcome>".

Builds: design 47 H2 §792
2026-11-22 00:52:34 +01:00
jschoubben 7dbd440a4e B1: the builder pulls the seat mesh-builds' work queue and takes each ask once
An ask put while the builder is down waited for nobody: the plain subscription
heard only what came while it ran. The builder now pulls every waiting ask from
the seat's one worker, takes it once by its id in its state taken (for
ask-taken-bound), says ask-taken at the pull, sends in-progress while it builds
and acknowledges once the step's end is said. Its publish to a registry seat is
a kept call carrying the publish's ask id. The manifest declares taken and the
kept-call pace and ask-taken-bound as runtime settings.

Builds: design 47 H2 §775, §777, §820; H-A-381
2026-11-22 00:45:40 +01:00
jschoubben 9acf583daf R3: a step's end is one journal line, said in one place; Resume puts no taken ask again
Every step-ended goes through sayStepEnded, which writes "step ended <pipeline>
<mover> <step> <outcome> in <duration>"; the cancel verb now says each step it
ends. Resume at a start puts again only an open step's ask no holder took.

Builds: design 47 H2 §784, §777 (H-A-397)
2026-11-22 00:35:13 +01:00
jschoubben f420a8213a R2: an ask's bound counts from the pull and ends its step, dropped
The bound key ask.<seat>.<ask> is armed at the put, again at the holder's
ask-taken (heard now for mesh-builds and mesh-wants too) with what is left
since taken-at, again from now at each step-progress, and at a start for every
open ask whose key is gone; it is deleted at the step's end. Past it the step
ends could-not-run, naming an untaken ask's seat holder as taking none, and its
ask is dropped through the seat's drop. The silent seats' bound, the second put
under AgainID, the ask2. keys and the put again at a holder's running go; a put
refused by a full work queue is said and put again at the kept-call pace.

Builds: design 47 H2 §777, §778 (H-A-349 DQ-4, H-A-395)
2026-11-22 00:30:56 +01:00
jschoubben e7d9849efa R4: pipeline-ended carries the pipeline's phases
taken (the record's start at its take-in), placed (the earliest step start),
ended, and per step kind the earliest start and latest end across movers, so
the gate reads where a pipeline's time went.

Builds: design 47 H2 §785
2026-11-22 00:22:50 +01:00
jschoubben f6e7f4210b B9: a fetch or a publish met away ends its run again, by again-delays, with no seat call
The build modules' shared steprun parts of §799: again-delays (15s,60s) read
into a Puller's Delay; a fetch's 401/5xx or connection fault and a publish's
no responders or exited bundle are transport faults whose why opens fetch: or
publish:; the assigner call that named a silent holder goes. The builder reads
an exited bundle as no responders and keeps the part in a key's fault words.

Builds: design 47 H2 §799 (H-A-390)
2026-11-22 00:20:17 +01:00
jschoubben 1058b0eec6 R1: the runner puts a step's ask and asks published as kept calls, paced, within ask-unanswered-bound
A put that met a transport fault is put again under the ask's own id at the
kept-call pace instead of failing the step at the first fault.

Builds: design 47 H2 §775
2026-11-22 00:15:07 +01:00
jschoubben 125d6382ea D6: the delivery seat's deliveries filters before it sizes
deliveries filters by repository, module, outcome and since while it reads,
pages by the cursor next and answers its deliveries with capped and total.
The seat's form rises to 2.

Builds: design 47 H2 §779, §811
2026-11-22 00:09:51 +01:00
jschoubben d2d3ebbf44 D5: the git seat's tags name their commits, and a holder says away
tags answers items {tag, commit}; trees' description says a missing directory
answers not-found; the error kind away joins refused, not-found and failed,
every answer carrying part and words with it; tag's description names the
<directory>/v<version> form. The seat's form rises to 2. The builder's,
bridge's and indexer's readers take the tag's name from the item.

Builds: design 47 H2 §776, §796; H-A-350 DMC-2, DMC-3, H-A-354
2026-11-22 00:08:50 +01:00
jschoubben 278310cc67 D4: the catalog seat pages registrations, says the seat list, takes a source alone
registrations filters by repository beside module while it reads, pages by
the cursor next and answers capped and total. The read verb seat-list answers
the seat list's object in seat-lists by digest, size and name. A registration
takes a source-only form under source.<owner>.<name>, with origin, one branch,
policy and check (a build seat and a step kind), naming no module; its history
keeps the same key. The seat's form rises to 2.

Builds: design 47 H2 §806, §811, §814, §815; H-A-349 DQ-9, DQ-10
2026-11-22 00:05:48 +01:00
jschoubben 1767d7b4e9 D3b: an install ends in a step-ended naming the step install
The build-step part's step enum and the delivery SDK's PipelineSteps gain
install; an install's end copies the module and the commit its ask names and
carries the archive, and the SDK's check takes it so.

Builds: design 47 H2 §800; H-A-367 (4), H-A-379
2026-11-22 00:04:05 +01:00
jschoubben ac99946fcb D4a: the registry's list takes module and a cursor, and pages at 768 KB
oci-artifact-registry's list filters by module beside name while it reads,
continues from the opaque cursor next and answers capped and total; the
seat's form rises to 2. The shared remove no longer judges its caller for a
retention removal.

Builds: design 47 H2 §779, §811, §813 (7); H-A-350 DMC-10
2026-11-22 00:02:21 +01:00
jschoubben 4749c686eb D3: the build-step part says output, current, not-run and install in its form 2
output takes the ask and answers the output's last 64 KB, its size, the
failing tests with their words, or no longer kept; its call and chunks go.
current answers the node, whether it takes asks and why not since when, its
capacity and every ask it runs with its asker. A step's end gains not-run and
archive, a step ask names the archive to unpack, and node-build-node accepts
install. The delivery SDK's neutral forms carry the same fields.

Builds: design 47 H2 §791, §800, §801; H-A-350 DMC-16, H-A-367
2026-11-22 00:00:41 +01:00
jschoubben 1f5b0f813d Merge origin/main into feat/47-H2 2026-11-21 23:53:44 +01:00
mesh-tools fe5fa6ac94 Merge pull request 'The runner takes out the stayers' steps not asked on a mover that left and places them again at the hand-off (H-A-361)' (#321) from fix/47-H2-end-after-handoff into main 2026-11-21 22:38:18 +00:00
jschoubben 99b25a7db4 H-A-361: a hand-off places again the stayers not asked on a mover that left
On 21 Nov the order was the reverse of the first commit's: mesh-contracts'
old build was withdrawn first (21:50:16), so the stayers that awaited it
were placed not asked, and only then did the hand-offs take it away. A
mover that left is still a dependency of those stayers: their not-asked
steps held the pipeline's end as failures. At the hand-off the steps of
each stayer that ended not asked on a dependency that left, directly or
through a mover itself taken out, are taken out, so the placing that
follows places them again against the newest published package; a
dependency that truly did not build is named again at that placing. The
journal says which movers are placed again.

Builds: design 47 H H-A-361, H-A-53, H-A-223
2026-11-21 23:34:24 +01:00
jschoubben a559b0e7c9 D1b: the two seats' work queues carry their settings, derived once in mesh-sdk
mesh-builds' and mesh-wants' accepted kind step names max-age 24h, max-msgs
10,000, ack-wait 60s, in-progress 20s, max-ack-pending 1,000, max-deliveries 5
and a duplicates window of 2m; the grants part makes each seat's ask stream
through mesh-sdk's buscompose.SeatQueue and says a seat whose settings it
refuses, and its own copy of the derivation goes.

Builds: design 47 H2 §777; H-A-350 DMC-1, H-A-362
2026-11-21 23:23:04 +01:00
jschoubben 7606d515fd H-A-361: a hand-off places the movers that stay; a mover that left is not awaited
main.158 and main.163 ended failed seconds after newer pipelines took
movers away: the movers that stay still awaited the movers that left,
whose builds had ended superseded, so the next placing ended them "not
asked: its dependency did not build" and the end judgement counted
them as failures. A mover that left is no longer awaited (the stayer
builds against the newest published package, H-A-53), is never placed
in the older pipeline, and the hand-off places what stays at once and
says in the journal which movers stay.

Builds: design 47 H H-A-361, H-A-53, H-A-223
2026-11-21 23:17:59 +01:00
jschoubben b40745534f D2: the runner's seat says phases, unfinished and re-pinned, and pages show
A step keeps asked-at and taken-at; pipeline-ended carries phases and
unfinished; show takes step and state filters and the cursor next, and
answers capped and total; re-pinned is declared. The seat's form rises to 2.

Builds: design 47 H2 §778, §785, §786, §789, §821; H-A-349 DQ-13
2026-11-21 23:17:31 +01:00
jschoubben c1ec75789f Readers of mesh-contracts' regenerated seats take the form
The node enroller's and the watchdogs' generated decoders answer the form
they read (mesh-contracts K1); their readers here take it.

Builds: design 47 H2 §780
2026-11-21 23:15:31 +01:00
jschoubben 75208ffcba D1: mesh-builds and mesh-wants say ask-taken, take drop, and the want carries run
Both seats declare ask-taken (ask, node, at) on ask-taken.<ask> and gain the
act drop; mesh-builds declares version-reserved; the want value the
node-engine applies carries run, the composition run's pipeline sequence, and
mesh-wants' form rises to 2. The queue settings of the accepted kind wait on
mesh-sdk's seatdef and buscompose (H-A-362, D1b).

Builds: design 47 H2 §777, §778, §805, §813 (1), §821; H-A-349 DQ-1, H-A-350 DMC-15, H-A-355 (1)
2026-11-21 23:15:31 +01:00
jschoubben 6046ebe2e0 G1: the fields digest is kept per type
A type added or removed whole changes no reader's value; only a type whose
fields changed while the form did not fails the compare.

Builds: design 47 H2 §780; H-A-352 (2)
2026-11-21 23:15:31 +01:00
jschoubben ff7db33720 G1, D0: seat readers decode tolerantly and say their form
The seat generator gives every value, event and answer the wire field form
(left out while 1) and a tolerant decoder answering the form it read; each
contract carries its forms and a digest of its fields, and the compare fails
a definition whose fields changed while its form did not. Every delivery seat
is regenerated, and the readers take the form.

Builds: design 47 H2 §780; H-A-352
2026-11-21 23:11:10 +01:00
jschoubben 2df32b7892 T1: the teller's ask-again for want of room goes
The channel holds no room to wait for (A-424): a refusal for want of room is
said as any refusal is, and its waiting, its bound of refusals and their tests
go. The wait for asks the router did not take stays.

Builds: design 47 H2 §813 (10)
2026-11-21 23:03:08 +01:00
mesh-tools 7e597a623e Merge pull request 'The runner and the builder write a journal line per step end, ask placed and ask answered (H-A-320, H-A-333)' (#320) from fix/47-H2-journal-lines into main 2026-11-21 21:01:55 +00:00
jschoubben 6a847a8d9c H-A-333: the ended line at every said end, the answered line at every answer
The runner's ended line was written only for a heard step-ended and its run's
readers; the unanswered-bound end, the end at placing, a supersede, a re-pin,
the approval's end, the start pass and the verbs said their ends silently. It
is now written in Hearer.say, the one place that says step-ended, and at the
starter's two sayers that call stepEvent directly (repin, sayNotAsked). The
builder's answered line sat on four of buildEntry's returns; the ask's answer
is now one line in BuildStep's finish, naming the pipeline, the movers, the
step and the outcome, the per-entry existing/built-now line kept beside it.

Builds: design 47 H H-A-320 (1), H-A-333
2026-11-21 21:58:36 +01:00
jschoubben dc83ef3e27 H-A-320 (1): a journal line per step end, step ask and build answer
A working 36-mover pipeline was read as stalled twice: the runner wrote no
line when a step ended or was asked, and the builder none when it answered a
step ask. The runner now writes "<pipeline> <mover> <step> ended <outcome>
(<node>, <duration>)" at each step end it writes (the asking step, every
reader of its test run, and each reader EndRun ends), and "<pipeline> <mover>
<step> asked on <seat>" for each ask put (the re-ask paths keep their own
line). The builder writes "<module>@<fingerprint> build step answered
<outcome> for <pipeline> (existing build / built now)".

Builds: design 47 H H-A-320 (1)
2026-11-21 21:50:48 +01:00
mesh-tools 600c13b9e9 Merge pull request 'Design 47 H: the runner redoes a cut placing, places on a late end, names a stalled pipeline, and reads a prior publish from the build seat (H-A-311, H-A-313, H-A-326, H-A-328, H-A-331)' (#319) from fix/47-H1-runner-placing-redone into main 2026-11-21 20:48:59 +00:00
mesh-tools 5396dc9b11 Merge pull request 'The teller's want-of-room test bed answers the seat-holder ask; one taker of registration-changed (H-A-295)' (#318) from fix/47-H1-teller-test-want-of-room into main 2026-11-21 20:48:56 +00:00
mesh-tools 425dbaef99 Merge pull request 'Design 47 H: a passed pipeline whose movers' versions arrive late still writes its wants (H-A-270, H-A-273, H-A-277)' (#317) from fix/47-H1-end-taken-when-versioned into main 2026-11-21 20:48:49 +00:00
jschoubben 714c2c1ccc H-A-331: the published answer carries the publish time and digest where kept; a withdrawn number is never published
The verb published answered no time, and after a release no digest,
while the seat form says both come when published. The builder now
keeps when it heard or confirmed each publish on the mark, and each
published digest on a kept release; marks and releases written before
answer without them. A number a take-over withdrew is not published.
The runner drops a pipeline's kept answers at its end.

Builds: design 47 H H-A-331, H-A-328
2026-11-21 21:38:50 +01:00
jschoubben e583dce741 H-A-326 (1), (3): a mover's wait on a package is a read first, an event second
main.137 stood twenty minutes with nats and mesh-vault waiting on
mesh-grants packages published at 20:00, before the wait was written,
so no publish event came. The runner now asks the build seat's
published when it writes the wait and places the mover when the
package is published, saying so in the journal apart from an event.

Builds: design 47 H H-A-326 (1), H-A-326 (3), H-A-328
2026-11-21 21:25:03 +01:00
jschoubben 5e76fdf725 H-A-328: the seat mesh-builds answers published; the builder serves it
A package published before a pipeline existed is in no record of the
runner, so the builder, which owns publishes, answers whether an
artifact built at a fingerprint is published, from its reservations
(marked from the registries' record) and its releases.

Builds: design 47 H H-A-328, H-A-326 (1), H-A-274
2026-11-21 21:25:03 +01:00
jschoubben 438c8740a6 H-A-326 (2): a pipeline waiting only on packages is named stalled
A step held on a package's publish counted as open, so a pipeline whose
only movers waited on publishes that had come before their wait was
never named by runner_health (main.137, twenty minutes).

Builds: design 47 H H-A-326 (2), H-A-311 (3)
2026-11-21 21:18:32 +01:00
jschoubben 05d9f90bdb H-A-311 (3) review: the health reads records keeping revisions; a required step waiting is open
runner_health, show, list and stands refused every pipeline record
carrying the runner's own kept-revisions ("unknown field
kept-revisions" on main.131 and main.137): the field is now dropped
before the seat's strict decode. A required step waiting (an approval,
a pin-held step) now counts as open, as the end's judgement holds it.

Builds: design 47 H H-A-311 (3), H-A-313, H-A-285, H-A-309, H-A-322
2026-11-21 20:53:04 +01:00
jschoubben f22945c26a H-A-311 (3): runner_health names a running pipeline with nothing open and nothing placed for five minutes
main.137 stood seventeen minutes with nothing open while runner_health
said healthy. The tools program says each such pipeline in its journal
once per key (H-A-313).

Builds: design 47 H H-A-311 (3), H-A-313
2026-11-21 20:44:43 +01:00
jschoubben e137df7189 H-A-311 (2): a step-progress or step-end heard late still places what its end unlocks
A late progress or end moved nothing, so movers waiting on what the
step's end gave stayed unplaced: main.137 placed nothing after its
lint's late progress at 20:17:55.

Builds: design 47 H H-A-311 (2), H-A-286, H-A-288
2026-11-21 20:43:02 +01:00
jschoubben 6c66bf9a5a H-A-311 (1): a placing cut by a concurrent write is done again from the record read again
A placing whose compare-and-set was refused because the pipeline was
written meanwhile was dropped and never done again: main.137 stood
seventeen minutes with eleven steps placed until a restart.

Builds: design 47 H H-A-311 (1), H-A-288
2026-11-21 20:41:29 +01:00
jschoubben b79fd19c84 Teller: hear registration-changed on the views reader's one subscription
Since mesh-sdk heard a seat's event on its bare subject too (H-A-166), the teller's
own hub handler of registration-changed overlapped the one the views reader makes
for the catalog half's followers: the hub refused the reader's, said "a message has
one taker", and registered none of the reader's adopted events after it, so the
catalog half's registrations and source branches were their first views' alone.
The widenings now hear the event through ProcessReader.AdoptEvent beside the
followers; a failed handling is given back for the bus to ask again, as before.
The carry test now fails when any of the reader's events is refused.

issue 1960 (H1), test stability.

Builds: design 47 G A-199, A-222, §532, §335
2026-11-21 19:24:22 +01:00
jschoubben 70bb8f7f51 Teller test bed: answer who holds operator-channel, so a catch-up does not hold the asks' watch
The want-of-room test failed most runs since 20 Nov: the teller's picture of the
assigner's asks hands the first ask on twice (its first view, then again), and the
second sight of an open asking catches up with the router's record, which first asks
the seat mesh-module-assigner's assignments who holds operator-channel. The bed
neither granted nor answered that call, so it waited out its call timeout on the
watch's goroutine, and the second ask, written meanwhile, was not raised within the
test's 10 s. The bed now grants and answers the call as the live seat does, naming
ops-router, so the catch-up reads ops-router_asks at once (20 of 20 runs pass, were
0 of 20 locally).

issue 1960 (H1), test stability.

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

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

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

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

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

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

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

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

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

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

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

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

Builds: design 47 H H-A-275, H-A-279, H-A-226
2026-11-21 15:56:04 +01:00
jschoubben 070f60404e Assigner: a passed mover with no version yet holds its tier
The tier progress started at the lowest tier of the versioned movers, so every
lower tier counted as run and a mover whose version came late was wanted after
its consumer. The progress now holds every passed mover, and a tier with one
whose version is not written does not run until it is.

Builds: design 47 H H-A-270, H-A-273, H-A-277 (1)
2026-11-21 15:55:30 +01:00
jschoubben 7f855f0e52 Runner: say the end again only for a passed pipeline, and again on a version heard again
A say that failed after the version was written was lost: the redelivery found
the version held and said nothing. A failed, superseded or cancelled end writes
no want, so it is not said again.

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

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

Builds: design 47 H H-A-274, H-A-275, H-A-245, H-A-226
2026-11-21 15:51:21 +01:00
jschoubben 3dfc18023a Assigner: a mover whose version came late joins the tier progress at its tier
The tier progress was written once, from the movers the first end named, so
a mover taken from the end said again was wanted out of tier order: a late
tier-2 consumer and the tier above it were wanted together. It now joins
the progress at its tier, and is wanted at once only when that tier ran.

Builds: design 47 H H-A-270, H-A-273
2026-11-21 15:44:58 +01:00
jschoubben 1489493431 Assigner: say a passed mover with no version yet; one registration-changed handler
The holder skipped such a mover silently, so a passed pipeline wrote no want
and nothing said why; the runner now says the end again once the version is
written, and the holder takes it then. The pipeline ends took registrations
from a second handler that the hub refused at every start (a message has one
taker); they are told by the catalog half's one follower instead.

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

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

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

Builds: design 47 H H-A-269 (1), H-A-271
2026-11-21 15:37:44 +01:00
jschoubben e927bb8971 Runner: a version written after a pipeline's end says pipeline-ended again
The seat mesh-wants' holder skips a passed mover with no version yet; the
version-released arrives late, so the end it took named none and no want was
written. Saying the same pipeline-ended again, naming the version, lets the
holder take the mover it skipped.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Builds: design 47 H H-A-198, H-A-199, H-A-157, H-A-172
2026-11-20 22:14:53 +01:00
mesh-tools d40f314e52 Merge pull request 'Design 47 H1: the grants holder keeps the catalog revisions it read and learns the newest from the event (H-A-193, H-A-195)' (#294) from fix/47-H1-grants-for-cache into main 2026-11-20 20:56:03 +00:00
jschoubben 120a0554d6 mesh-grants: grants-for keeps a bounded cache of the followed branches
The kept catalog revisions had no design line and their bound stood in
the code. They are now bounded per branch by the module's setting
grants-for-revisions-per-branch (default 4, oldest dropped, a run's
candidate counted within its branch's), read at the start from the file
the manifest writes, and kept only for the watched branches the part's
branch follower follows: a branch that leaves them is freed at the next
grants-for or catalog-revision event. A kept revision is a cache of the
catalog seat's own truth, never a state of the mesh.

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

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

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

Builds: design 47 G §441, §401; H §774
2026-11-20 21:40:15 +01:00
850 changed files with 41108 additions and 22003 deletions
@@ -1,63 +0,0 @@
// Package containerimageregistryclient is the container-image-registry seat's client (novox/hq ADR 0627 §1, §2; ADR 0611, design 51
// *Publishing*): it publishes a file in parts to the seat's holder. `publish` opens the transfer naming every part,
// the holder answers the parts it lacks, and only those travel by `publish-part`, in chunks a bus message carries; a
// cut transfer goes on from what the holder answers when the same transfer is opened again. The sending in parts is
// mesh-sdk's seat-neutral runtime (parts); this client binds it to this seat's verbs and types alone. The call is the
// caller's own (a bundle's stdio.Ask, a process's call of a seat verb), so it holds no transport.
package containerimageregistryclient
import (
"context"
"encoding/base64"
"encoding/json"
"fmt"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/containerimageregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// Call asks one verb of the seat, `seat:<seat>.<verb>`, with a body, and answers its JSON.
type Call func(key string, body any) (json.RawMessage, error)
// Sent is what a Publish did: the transfer, whether the holder held its digest already, the parts it lacked and were
// sent, and the chunks they took.
type Sent struct {
Transfer string
parts.Sent
}
// Publish opens (or opens again) the transfer in on the seat and sends the parts the holder answers it lacks, each in
// chunks of at most parts.MaxChunk, in sequence, the last marked. in.Parts is written from parts. A part whose bytes
// do not hash to its digest is refused before anything of it is sent; a part the holder does not name is never read.
// Its outcome, published or refused, is the holder's event, which the caller waits for.
func Publish(ctx context.Context, call Call, in seat.PublishInput, ps []parts.Part) (Sent, error) {
open := func(_ context.Context, ps []parts.Part) (parts.Opened, error) {
in.Parts = make([]seat.Part, 0, len(ps))
for _, p := range ps {
in.Parts = append(in.Parts, seat.Part{Digest: p.Digest, Size: p.Size})
}
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublish, in)
if err != nil {
return parts.Opened{}, fmt.Errorf("%s's publish of %s: %w", seat.Seat, in.Name, err)
}
var a seat.PublishAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return parts.Opened{}, fmt.Errorf("%s's answer to publish: %w", seat.Seat, err)
}
return parts.Opened{Held: a.Held, Lacks: a.Lacks}, nil
}
chunk := func(_ context.Context, part string, sequence int, last bool, data []byte) error {
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublishPart, seat.PublishPartInput{Transfer: in.Transfer, Part: part,
Sequence: int64(sequence), Last: last, Data: base64.StdEncoding.EncodeToString(data)})
if err != nil {
return fmt.Errorf("%s's publish-part: %w", seat.Seat, err)
}
var a seat.PublishPartAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return fmt.Errorf("%s's answer to publish-part: %w", seat.Seat, err)
}
return nil
}
sent, err := parts.Send(ctx, open, chunk, ps)
return Sent{Transfer: in.Transfer, Sent: sent}, err
}
@@ -1,57 +0,0 @@
package containerimageregistryclient
import (
"bytes"
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"io"
"testing"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/containerimageregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// The client publishes over its own seat's verbs alone (ADR 0627 §1): publish names every part, and only the part the
// holder lacks travels by publish-part, its bytes whole, the last chunk marked.
func TestPublishTalksToItsOwnSeat(t *testing.T) {
held, lacked := []byte("held"), []byte("lacked")
part := func(b []byte) parts.Part {
sum := sha256.Sum256(b)
return parts.Part{Digest: "sha256:" + hex.EncodeToString(sum[:]), Size: int64(len(b)),
Open: func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(b)), nil }}
}
ps := []parts.Part{part(held), part(lacked)}
var asked []string
var got []byte
call := func(key string, body any) (json.RawMessage, error) {
asked = append(asked, key)
raw, _ := json.Marshal(body)
switch key {
case "seat:container-image-registry.publish":
var in seat.PublishInput
_ = json.Unmarshal(raw, &in)
if len(in.Parts) != 2 {
t.Errorf("publish names %d parts, want 2", len(in.Parts))
}
return json.Marshal(seat.PublishAnswer{Transfer: in.Transfer, Lacks: []string{ps[1].Digest}})
case "seat:container-image-registry.publish-part":
var in seat.PublishPartInput
_ = json.Unmarshal(raw, &in)
data, _ := base64.StdEncoding.DecodeString(in.Data)
if in.Part != ps[1].Digest || !in.Last || in.Transfer != "t1" {
t.Errorf("publish-part %+v", in)
}
got = append(got, data...)
return json.Marshal(seat.PublishPartAnswer{Transfer: in.Transfer, Part: in.Part})
}
t.Fatalf("asked %s", key)
return nil, nil
}
sent, err := Publish(context.Background(), call, seat.PublishInput{Transfer: "t1", Name: "x"}, ps)
if err != nil || sent.Transfer != "t1" || sent.Chunks != 1 || len(sent.Parts) != 1 || !bytes.Equal(got, lacked) || len(asked) != 2 {
t.Errorf("sent %+v, %q arrived, asked %v, %v", sent, got, asked, err)
}
}
@@ -1,18 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/clients/containerimageregistryclient
go 1.26.0
require (
git.novox.be/novox/mesh-delivery/contracts/go/seats/containerimageregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/sdk v0.0.0-00010101000000-000000000000
)
require (
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000 // indirect
github.com/klauspost/compress v1.20.1 // indirect
github.com/nats-io/nats.go v1.54.0 // indirect
github.com/nats-io/nkeys v0.4.16 // indirect
github.com/nats-io/nuid v1.0.1 // indirect
golang.org/x/crypto v0.57.0 // indirect
golang.org/x/sys v0.48.0 // indirect
)
@@ -1,12 +0,0 @@
github.com/klauspost/compress v1.20.1 h1:T7kKElXUMXrUJ2E9QhQhxFtcK5rPyLdsGZvdbLMPdiQ=
github.com/klauspost/compress v1.20.1/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
@@ -1,116 +0,0 @@
// Package reference holds the form of an artifact's reference once a registry seat published it: `<seat>/<module>/<artifact>@<digest>`
// (novox/hq ADR 0605 §9), and the older `artifact-store://<path>` form read beside it. It is the rule the holders and callers of the two
// registry seats that front the artifact store share (the seats' client, novox/hq ADR 0625 §4, ADR 0634 §2); it names no seat itself (ADR 0634 §4, ADR 0635 §4): the
// caller gives the seats' names from their contracts (Seats), so a package here cannot drift from a contract.
package reference
import "strings"
// ArtifactStoreScheme marks a reference to something in the mesh's artifact store, kept without the store's address.
const ArtifactStoreScheme = "artifact-store://"
// UpstreamPrefix opens the holder's own name for an upstream copy it keeps: `upstream/<host>/<path>@<digest>`, after
// `<image seat>/` in the seat's form and after `artifact-store://` in the older one.
const UpstreamPrefix = "upstream/"
// Seats are the names of the two registry seats a reference of the registry form names first: Image the seat that fronts
// images and upstream copies (container-image-registry), Object the seat that fronts bundles and archives
// (oci-artifact-registry). The caller reads them from the seats' contracts.
type Seats struct{ Image, Object string }
// All is the two names.
func (s Seats) All() []string { return []string{s.Image, s.Object} }
// Recorded is a reference as the mesh records it: the artifact store's address, if the builder wrote one, taken off.
func (s Seats) Recorded(reference string) string {
if _, _, seat := s.InRegistrySeat(reference); seat || strings.HasPrefix(reference, ArtifactStoreScheme) {
return reference
}
if rest, isURL := strings.CutPrefix(reference, "http://"); isURL {
if _, path, ok := strings.Cut(rest, "/v2/"); ok && strings.Contains(path, "/blobs/") {
return ArtifactStoreScheme + path
}
return reference
}
host, path, ok := strings.Cut(reference, "/")
if !ok || !isRegistryHost(host) || !strings.Contains(path, "@sha256:") {
return reference
}
return ArtifactStoreScheme + path
}
// isRegistryHost is the runtime's own rule for reading the first component of a reference as a registry rather than a
// namespace: it has a dot or a port in it, or it is localhost.
func isRegistryHost(component string) bool {
return component == "localhost" || strings.ContainsAny(component, ".:")
}
// InArtifactStore reports whether a reference is a kept one, and what it names there: `<module>/<artifact>@<digest>` for an
// image, `<module>/<artifact>/blobs/<digest>` for a bundle or an archive. It reads both forms (ADR 0605 §9).
func (s Seats) InArtifactStore(reference string) (path string, kept bool) {
if seat, rest, ok := s.InRegistrySeat(reference); ok {
if seat == s.Object {
name, digest, _ := strings.Cut(rest, "@")
return name + "/blobs/" + digest, true
}
return rest, true
}
return strings.CutPrefix(reference, ArtifactStoreScheme)
}
// SeatReference is the reference a build names an image, bundle, archive or upstream copy by once it published it through
// a registry seat: `<seat>/<module>/<artifact>@sha256:<digest>`, as InRegistrySeat reads it back.
func SeatReference(seat, module, artifact, digest string) string {
return seat + "/" + module + "/" + artifact + "@" + digest
}
// InRegistrySeat reads a reference in the form a registry seat answers: the seat it came through and the rest. A seat's
// name holds no dot or port, so no image of an outside registry reads as one, and a kept `artifact-store://` reference is
// not one. It also reads the holder's own naming of an upstream copy through the image seat, whose rest InUpstream reads.
func (s Seats) InRegistrySeat(reference string) (seat, path string, ok bool) {
first, rest, found := strings.Cut(reference, "/")
if !found || !strings.Contains(rest, "@sha256:") {
return "", "", false
}
if _, _, upstream := InUpstream(rest); upstream && first == s.Image {
return first, rest, true
}
if strings.Count(rest, "/") != 1 {
return "", "", false
}
for _, name := range s.All() {
if first == name {
return name, rest, true
}
}
return "", "", false
}
// InUpstream reads a path in the holder's naming of an upstream copy, `upstream/<host>/<path>@sha256:<digest>`: the
// upstream registry host and the image's path there, with its digest.
func InUpstream(path string) (host, image string, ok bool) {
rest, found := strings.CutPrefix(path, UpstreamPrefix)
if !found {
return "", "", false
}
host, image, found = strings.Cut(rest, "/")
name, digest, pinned := strings.Cut(image, "@")
if !found || !isRegistryHost(host) || name == "" || strings.HasPrefix(name, "/") || strings.HasSuffix(name, "/") ||
strings.Contains(name, "//") || !pinned || !strings.HasPrefix(digest, "sha256:") || strings.Contains(digest, "/") {
return "", "", false
}
return host, image, true
}
// Routed is a kept reference as a machine fetches it, through the artifact store at `address` (host:port). A reference
// that is not a kept one is what it was.
func (s Seats) Routed(reference, address string) string {
path, kept := s.InArtifactStore(reference)
if !kept {
return reference
}
if strings.Contains(path, "/blobs/") {
return "http://" + address + "/v2/" + path
}
return address + "/" + path
}
@@ -1,69 +0,0 @@
package reference
import (
"strings"
"testing"
)
var digest = "sha256:" + strings.Repeat("d", 64)
var seats = Seats{Image: "container-image-registry", Object: "object-registry"}
func TestAReferenceIsRecordedWithoutTheStoresAddress(t *testing.T) {
cases := map[string]string{
"anchor.internal:5100/gitea/server@" + digest: ArtifactStoreScheme + "gitea/server@" + digest,
"localhost:5000/gitea/server@" + digest: ArtifactStoreScheme + "gitea/server@" + digest,
"http://anchor.internal:5100/v2/gitea/config/blobs/" + digest: ArtifactStoreScheme + "gitea/config/blobs/" + digest,
ArtifactStoreScheme + "gitea/server@" + digest: ArtifactStoreScheme + "gitea/server@" + digest,
digest: digest,
"@novox/sdk@1.2.3": "@novox/sdk@1.2.3",
"gitea/gitea@" + digest: "gitea/gitea@" + digest,
"https://registry.example/v2/gitea/config/blobs/" + digest: "https://registry.example/v2/gitea/config/blobs/" + digest,
// The form a registry seat answers is recorded as it is (ADR 0605 §9).
"container-image-registry/gitea/server@" + digest: "container-image-registry/gitea/server@" + digest,
"object-registry/gitea/config@" + digest: "object-registry/gitea/config@" + digest,
}
for announced, want := range cases {
if got := seats.Recorded(announced); got != want {
t.Errorf("Recorded(%q) = %q, want %q", announced, got, want)
}
}
// And every reader reads both forms: a kept reference and the seat's are fetched from the same place.
for reference, want := range map[string]string{
ArtifactStoreScheme + "gitea/server@" + digest: "10.0.0.1:5000/gitea/server@" + digest,
"container-image-registry/gitea/server@" + digest: "10.0.0.1:5000/gitea/server@" + digest,
ArtifactStoreScheme + "gitea/config/blobs/" + digest: "http://10.0.0.1:5000/v2/gitea/config/blobs/" + digest,
"object-registry/gitea/config@" + digest: "http://10.0.0.1:5000/v2/gitea/config/blobs/" + digest,
"registry.example/gitea/server@" + digest: "registry.example/gitea/server@" + digest,
"mesh-artifact-store/gitea/server@" + digest: "mesh-artifact-store/gitea/server@" + digest,
// An upstream copy under the holder's own naming, in both forms.
"container-image-registry/upstream/quay.io:443/org/app@" + digest: "10.0.0.1:5000/upstream/quay.io:443/org/app@" + digest,
ArtifactStoreScheme + "upstream/quay.io:443/org/app@" + digest: "10.0.0.1:5000/upstream/quay.io:443/org/app@" + digest,
} {
if got := seats.Routed(reference, "10.0.0.1:5000"); got != want {
t.Errorf("Routed(%q) = %q, want %q", reference, got, want)
}
}
// A build module names what it published in the seat's form, and reads it back as the seat it came through.
for _, seat := range seats.All() {
ref := SeatReference(seat, "gitea", "config", digest)
if got, path, ok := seats.InRegistrySeat(ref); !ok || got != seat || path != "gitea/config@"+digest {
t.Errorf("SeatReference(%s) = %q, read back as %q %q %v", seat, ref, got, path, ok)
}
}
// The holder's naming of an upstream copy reads through the image seat only, and InUpstream reads its host and path.
for reference, want := range map[string]bool{
"container-image-registry/upstream/quay.io:443/org/app@" + digest: true,
"object-registry/upstream/quay.io:443/org/app@" + digest: false,
"container-image-registry/upstream/org/app@" + digest: false,
"container-image-registry/upstream/quay.io/app": false,
} {
_, path, ok := seats.InRegistrySeat(reference)
if ok != want {
t.Errorf("InRegistrySeat(%q) read %v, want %v", reference, ok, want)
}
if host, image, up := InUpstream(path); ok && (!up || host != "quay.io:443" || image != "org/app@"+digest) {
t.Errorf("InUpstream(%q) = %q %q %v", path, host, image, up)
}
}
}
@@ -1,63 +0,0 @@
// Package gopackageregistryclient is the go-package-registry seat's client (novox/hq ADR 0627 §1, §2; ADR 0611, design 51
// *Publishing*): it publishes a file in parts to the seat's holder. `publish` opens the transfer naming every part,
// the holder answers the parts it lacks, and only those travel by `publish-part`, in chunks a bus message carries; a
// cut transfer goes on from what the holder answers when the same transfer is opened again. The sending in parts is
// mesh-sdk's seat-neutral runtime (parts); this client binds it to this seat's verbs and types alone. The call is the
// caller's own (a bundle's stdio.Ask, a process's call of a seat verb), so it holds no transport.
package gopackageregistryclient
import (
"context"
"encoding/base64"
"encoding/json"
"fmt"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/gopackageregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// Call asks one verb of the seat, `seat:<seat>.<verb>`, with a body, and answers its JSON.
type Call func(key string, body any) (json.RawMessage, error)
// Sent is what a Publish did: the transfer, whether the holder held its digest already, the parts it lacked and were
// sent, and the chunks they took.
type Sent struct {
Transfer string
parts.Sent
}
// Publish opens (or opens again) the transfer in on the seat and sends the parts the holder answers it lacks, each in
// chunks of at most parts.MaxChunk, in sequence, the last marked. in.Parts is written from parts. A part whose bytes
// do not hash to its digest is refused before anything of it is sent; a part the holder does not name is never read.
// Its outcome, published or refused, is the holder's event, which the caller waits for.
func Publish(ctx context.Context, call Call, in seat.PublishInput, ps []parts.Part) (Sent, error) {
open := func(_ context.Context, ps []parts.Part) (parts.Opened, error) {
in.Parts = make([]seat.Part, 0, len(ps))
for _, p := range ps {
in.Parts = append(in.Parts, seat.Part{Digest: p.Digest, Size: p.Size})
}
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublish, in)
if err != nil {
return parts.Opened{}, fmt.Errorf("%s's publish of %s: %w", seat.Seat, in.Name, err)
}
var a seat.PublishAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return parts.Opened{}, fmt.Errorf("%s's answer to publish: %w", seat.Seat, err)
}
return parts.Opened{Held: a.Held, Lacks: a.Lacks}, nil
}
chunk := func(_ context.Context, part string, sequence int, last bool, data []byte) error {
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublishPart, seat.PublishPartInput{Transfer: in.Transfer, Part: part,
Sequence: int64(sequence), Last: last, Data: base64.StdEncoding.EncodeToString(data)})
if err != nil {
return fmt.Errorf("%s's publish-part: %w", seat.Seat, err)
}
var a seat.PublishPartAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return fmt.Errorf("%s's answer to publish-part: %w", seat.Seat, err)
}
return nil
}
sent, err := parts.Send(ctx, open, chunk, ps)
return Sent{Transfer: in.Transfer, Sent: sent}, err
}
@@ -1,57 +0,0 @@
package gopackageregistryclient
import (
"bytes"
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"io"
"testing"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/gopackageregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// The client publishes over its own seat's verbs alone (ADR 0627 §1): publish names every part, and only the part the
// holder lacks travels by publish-part, its bytes whole, the last chunk marked.
func TestPublishTalksToItsOwnSeat(t *testing.T) {
held, lacked := []byte("held"), []byte("lacked")
part := func(b []byte) parts.Part {
sum := sha256.Sum256(b)
return parts.Part{Digest: "sha256:" + hex.EncodeToString(sum[:]), Size: int64(len(b)),
Open: func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(b)), nil }}
}
ps := []parts.Part{part(held), part(lacked)}
var asked []string
var got []byte
call := func(key string, body any) (json.RawMessage, error) {
asked = append(asked, key)
raw, _ := json.Marshal(body)
switch key {
case "seat:go-package-registry.publish":
var in seat.PublishInput
_ = json.Unmarshal(raw, &in)
if len(in.Parts) != 2 {
t.Errorf("publish names %d parts, want 2", len(in.Parts))
}
return json.Marshal(seat.PublishAnswer{Transfer: in.Transfer, Lacks: []string{ps[1].Digest}})
case "seat:go-package-registry.publish-part":
var in seat.PublishPartInput
_ = json.Unmarshal(raw, &in)
data, _ := base64.StdEncoding.DecodeString(in.Data)
if in.Part != ps[1].Digest || !in.Last || in.Transfer != "t1" {
t.Errorf("publish-part %+v", in)
}
got = append(got, data...)
return json.Marshal(seat.PublishPartAnswer{Transfer: in.Transfer, Part: in.Part})
}
t.Fatalf("asked %s", key)
return nil, nil
}
sent, err := Publish(context.Background(), call, seat.PublishInput{Transfer: "t1", Name: "x"}, ps)
if err != nil || sent.Transfer != "t1" || sent.Chunks != 1 || len(sent.Parts) != 1 || !bytes.Equal(got, lacked) || len(asked) != 2 {
t.Errorf("sent %+v, %q arrived, asked %v, %v", sent, got, asked, err)
}
}
@@ -1,18 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/clients/gopackageregistryclient
go 1.26.0
require (
git.novox.be/novox/mesh-delivery/contracts/go/seats/gopackageregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/sdk v0.0.0-00010101000000-000000000000
)
require (
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000 // indirect
github.com/klauspost/compress v1.20.1 // indirect
github.com/nats-io/nats.go v1.54.0 // indirect
github.com/nats-io/nkeys v0.4.16 // indirect
github.com/nats-io/nuid v1.0.1 // indirect
golang.org/x/crypto v0.57.0 // indirect
golang.org/x/sys v0.48.0 // indirect
)
@@ -1,12 +0,0 @@
github.com/klauspost/compress v1.20.1 h1:T7kKElXUMXrUJ2E9QhQhxFtcK5rPyLdsGZvdbLMPdiQ=
github.com/klauspost/compress v1.20.1/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
@@ -1,74 +0,0 @@
package meshcatalogclient
import (
"crypto/sha256"
"encoding/hex"
"fmt"
"regexp"
"sort"
"strings"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// FingerprintSet is the `fpset` of a candidate's pull requests: the first 12 hex digits of the sha256 over the lines
// `<module>=<fp2>` or `<module>=none:<reason>` of every module with an entry in a pull's fps, sorted and joined by a newline,
// so it is the same for every order and changes with any fingerprint or reason. A manifest digest does not enter: the
// fingerprint already covers the manifest. It is the empty string when no pull request carries a fingerprint. The checker
// keys its verdict by it.
func FingerprintSet(pulls []seat.CandidatesByGroupValuePullsItem) string {
lines := map[string]bool{}
for _, p := range pulls {
for module, m := range p.Fps {
if m.Fp2 != "" {
lines[module+"="+m.Fp2] = true
} else {
lines[module+"=none:"+m.None2] = true
}
}
}
if len(lines) == 0 {
return ""
}
all := make([]string, 0, len(lines))
for l := range lines {
all = append(all, l)
}
sort.Strings(all)
sum := sha256.Sum256([]byte(strings.Join(all, "\n")))
return hex.EncodeToString(sum[:])[:12]
}
// CandidatesKey is the key, in the state candidates, of a group: `<group>` escaped (keys.EscapeName), the branch name the
// group's pull requests share (a slash is allowed); a lone pull request is a group of one under its branch name.
func CandidatesKey(group string) (string, error) {
if group == "" {
return "", fmt.Errorf("meshcatalogclient: the group name is empty")
}
return seat.CandidatesByGroupKey(keys.EscapeName(group)), nil
}
// ParseCandidatesKey is the inverse of CandidatesKey.
func ParseCandidatesKey(key string) (string, error) {
part, ok := seat.ParseCandidatesByGroupKey(key)
if !ok {
return "", fmt.Errorf("meshcatalogclient: %q is not a candidates key", key)
}
group, err := keys.UnescapeName(part)
if err != nil {
return "", fmt.Errorf("meshcatalogclient: %q is not a candidates key: %w", key, err)
}
return group, nil
}
var tryGroupOK = regexp.MustCompile(`^try-[0-9]{1,20}$`)
// IsTryGroup says a candidates key is the group of a whole try, try-<digits>, which is also the try's id: the indexer makes the
// candidate of a try's group from its previews, and the checker judges it by its try, never as a pull request's check.
func IsTryGroup(key string) bool { return tryGroupOK.MatchString(key) }
// NoneNoPreview is why a candidate's touched module has no fingerprint of the new form yet: its merge preview is not
// computed. The indexer writes it; a reader that waits for a try's candidate takes one that still says it as not yet the
// candidate of the heads previewed.
const NoneNoPreview = "no merge preview is computed"
@@ -1,167 +0,0 @@
package meshcatalogclient
import (
"errors"
"strings"
"testing"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/keys"
)
func hex64(c string) string { return strings.Repeat(c, 64) }
// The digest and the candidate's fingerprint set equal what the trunk's go/delivery computed for the same input (the
// expected strings are its output), so a key or a verdict written before is read after.
func TestDigestAndFingerprintSetKeepTheirForms(t *testing.T) {
if got := ManifestDigest([]byte(`{"module":"nats"}`)); got != "19a7450f557153c318558acac91cd6972321a192f6f95c3698a0e4c57edd4359" {
t.Errorf("ManifestDigest = %s", got)
}
pull := func(fps map[string]seat.CandidatesByGroupValuePullsItemFpsValue) []seat.CandidatesByGroupValuePullsItem {
return []seat.CandidatesByGroupValuePullsItem{{Fps: fps}}
}
fps := map[string]seat.CandidatesByGroupValuePullsItemFpsValue{"nats": {Fp2: SourcePrefix2 + hex64("a")}, "zsh": {None2: "no manifest"}}
set := FingerprintSet(pull(fps))
if set != "50a3f57cc4e2" {
t.Errorf("FingerprintSet = %s", set)
}
fps["zsh"] = seat.CandidatesByGroupValuePullsItemFpsValue{None2: "another reason"}
if FingerprintSet(pull(fps)) == set {
t.Error("a changed reason leaves the set as it was")
}
if FingerprintSet(pull(nil)) != "" {
t.Error("no fingerprint gives a set")
}
}
// A manifest and a module are read back as written, and each rule of the old values is kept: a refusal names its reason.
func TestManifestAndModuleValuesKeepTheirRules(t *testing.T) {
if _, err := ManifestsKey("abc"); err == nil || !strings.Contains(err.Error(), `"abc"`) {
t.Errorf("ManifestsKey(abc) = %v", err)
}
if k, err := ParseManifestsKey(hex64("b")); err != nil || k != hex64("b") {
t.Errorf("ParseManifestsKey = %q, %v", k, err)
}
raw, err := EncodeManifest(seat.ManifestsByDigestValue{Module: "nats", Manifest: `{"module":"nats"}`})
if err != nil {
t.Fatal(err)
}
if m, err := DecodeManifest(raw); err != nil || m.Module != "nats" || m.V != keys.Version {
t.Errorf("DecodeManifest = %+v, %v", m, err)
}
for _, bad := range []seat.ManifestsByDigestValue{{Module: "a.b", Manifest: "{}"}, {Module: "nats"}, {Module: "nats", Manifest: "not json"}, {Module: "nats", Manifest: "{\"a\":\"\xff\"}"}} {
if _, err := EncodeManifest(bad); err == nil {
t.Errorf("EncodeManifest(%+v) is accepted", bad)
}
}
if _, err := DecodeManifest([]byte(`{"module":"nats","manifest":"{}"}`)); !errors.Is(err, keys.ErrUnknownVersion) {
t.Errorf("a manifest with no version: %v", err)
}
good := seat.ModulesByModuleValue{Fp2: SourcePrefix2 + hex64("a"), Repository: "novox/mesh-catalog", Commit: "c", Manifest: hex64("b"), Path: RootPath}
raw, err = EncodeModule(good)
if err != nil {
t.Fatal(err)
}
if m, err := DecodeModule(raw); err != nil || m.Fp2 != good.Fp2 || m.Path != RootPath {
t.Errorf("DecodeModule = %+v, %v", m, err)
}
refused := good
refused.Verdict, refused.Problems = VerdictRefused, []string{"p"}
if _, err := EncodeModule(refused); err != nil {
t.Errorf("a refused module: %v", err)
}
for name, mutate := range map[string]func(m *seat.ModulesByModuleValue){
"neither a fingerprint nor a reason": func(m *seat.ModulesByModuleValue) { m.Fp2 = "" },
"both fp2 and none2": func(m *seat.ModulesByModuleValue) { m.None2 = "x" },
"an old fingerprint of another form": func(m *seat.ModulesByModuleValue) { m.Fp = "src2:" + hex64("a") },
"a fingerprint of the old key form": func(m *seat.ModulesByModuleValue) { m.Fp2 = "src1:" + hex64("a") },
"inputs and no manifest": func(m *seat.ModulesByModuleValue) {
m.Manifest = ""
m.Inputs2 = &seat.ModulesByModuleValueInputs2{Tree: "t"}
},
"a refusal with no problem": func(m *seat.ModulesByModuleValue) { m.Verdict = VerdictRefused },
"problems with no refusal": func(m *seat.ModulesByModuleValue) { m.Problems = []string{"p"} },
"unknown fields with no refusal": func(m *seat.ModulesByModuleValue) { m.Unknown = []string{"series"} },
"a path outside the directory": func(m *seat.ModulesByModuleValue) { m.Paths = map[string][]string{"tools": {"../x"}} },
"a toolchain with no recipe": func(m *seat.ModulesByModuleValue) {
m.Toolchains = map[string]seat.ToolchainUsed{"go": {Language: "go", Version: "1.26"}}
},
"an import form with no imports": func(m *seat.ModulesByModuleValue) {
m.Inputs2 = &seat.ModulesByModuleValueInputs2{Tree: "t", ImportForm: SourcePrefix2 + hex64("a")}
},
} {
m := good
mutate(&m)
if _, err := EncodeModule(m); err == nil {
t.Errorf("%s: EncodeModule accepts %+v", name, m)
}
}
}
// A verdict is taken as the readers have always taken it: a missing one accepted, a refusal held with its problems, a wait
// held with the fields it waits on, and a module's own verdict field gives the same.
func TestVerdictsAreTakenAsTheReadersTookThem(t *testing.T) {
if refused, problems := TakeVerdict(nil); refused || problems != nil {
t.Errorf("no verdict: %v %v", refused, problems)
}
waits := seat.VerdictsByDigestValue{Module: "nats", State: VerdictManifestWaits, Unknown: []string{"series"}, Judge: "j"}
refused, problems := TakeVerdict(&waits)
if !refused || len(problems) != 1 || problems[0] != "it carries series, which the indexer's judge does not know yet" {
t.Errorf("a wait: %v %v", refused, problems)
}
if got := VerdictWhy(waits); got != "the indexer's judge (j) holds the manifest of nats: "+problems[0] {
t.Errorf("VerdictWhy(wait) = %q", got)
}
if as := VerdictAsRefused(waits); as.State != VerdictRefused || len(as.Unknown) != 0 || as.Problems[0] != problems[0] {
t.Errorf("VerdictAsRefused = %+v", as)
}
no := seat.VerdictsByDigestValue{Module: "nats", State: VerdictRefused, Problems: []string{"a", "b"}, Judge: "j"}
if got := VerdictWhy(no); got != "the indexer's judge (j) refused the manifest of nats: a; b" {
t.Errorf("VerdictWhy(refused) = %q", got)
}
if !SameVerdict(no, seat.VerdictsByDigestValue{Module: "nats", State: VerdictRefused, Problems: []string{"a", "b"}, Judge: "k"}) {
t.Error("another judge is another verdict")
}
fromModule := ModuleVerdict("nats", seat.ModulesByModuleValue{Verdict: VerdictRefused, Unknown: []string{"series"}, Problems: []string{"x"}})
if fromModule == nil || fromModule.State != VerdictManifestWaits || fromModule.Unknown[0] != "series" {
t.Errorf("a refusal naming unknown fields is the wait it was written as: %+v", fromModule)
}
if ModuleVerdict("nats", seat.ModulesByModuleValue{}) != nil {
t.Error("a module with no verdict carries one")
}
for _, bad := range []seat.VerdictsByDigestValue{{Module: "nats", State: "accepted", Problems: []string{"p"}, Judge: "j"}, {Module: "nats", State: "refused", Judge: "j"}, {Module: "nats", State: "accepted"}, {Module: "nats", State: "odd", Judge: "j"}} {
if _, err := EncodeVerdict(bad); err == nil {
t.Errorf("EncodeVerdict(%+v) is accepted", bad)
}
}
raw, err := EncodeVerdict(no)
if err != nil {
t.Fatal(err)
}
if v, err := DecodeVerdict(raw); err != nil || !SameVerdict(v, no) {
t.Errorf("DecodeVerdict = %+v, %v", v, err)
}
if k, err := VerdictsKey(hex64("c")); err != nil || k != hex64("c") {
t.Errorf("VerdictsKey = %q %v", k, err)
}
if _, err := ModulesKey("a.b"); err == nil {
t.Error("ModulesKey accepts a dotted name")
}
}
func TestCandidatesKeyEscapesTheGroupAndReadsBack(t *testing.T) {
key, err := CandidatesKey("fix/1.2")
if err != nil {
t.Fatal(err)
}
if key == "fix/1.2" {
t.Errorf("the group is not escaped: %q", key)
}
if group, err := ParseCandidatesKey(key); err != nil || group != "fix/1.2" {
t.Errorf("read back = %q, %v", group, err)
}
if _, err := CandidatesKey(""); err == nil {
t.Error("an empty group keys")
}
}
@@ -1,41 +0,0 @@
// Package meshcatalogclient holds the logic the holders and callers of the seat mesh-catalog share over its contract (novox/hq
// ADR 0625 §4, ADR 0634 §2): the form of a module's source fingerprint, `src2:` and 64 lowercase hex digits (ADR 0593 §2),
// over the `fp2` field of the seat's `modules` value. The indexer computes a fingerprint alone, in its own package; every part
// that keys a state by it, the node-engine among them, reads this form here.
package meshcatalogclient
import (
"fmt"
"strings"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// SourcePrefix2 opens every source fingerprint of the form.
const SourcePrefix2 = "src2:"
// Toolchain2 is what an artifact's toolchain enters the fingerprint as (novox/hq ADR 0405 clause 7): the artifact's
// language, the installed toolchain's version and the build module's recipe version.
type Toolchain2 struct {
Language string
Version string
Recipe string
}
// KeyPart is a fingerprint as a key part: its 64 hex digits without the prefix, since a bus key may not hold ':'. It
// refuses a value that is not `src2:` and 64 lowercase hex digits, a src1 fingerprint included, naming it.
func KeyPart(fp string) (string, error) {
part, ok := strings.CutPrefix(fp, SourcePrefix2)
if !ok || !keys.IsHex64(part) {
return "", fmt.Errorf("fingerprint: %q is not a fingerprint of the form, %s and 64 lowercase hex digits", fp, SourcePrefix2)
}
return part, nil
}
// ParseKeyPart is the inverse of KeyPart. It refuses a part that is not 64 lowercase hex digits, naming it.
func ParseKeyPart(part string) (string, error) {
if !keys.IsHex64(part) {
return "", fmt.Errorf("fingerprint: %q is not the key part of a fingerprint, 64 lowercase hex digits", part)
}
return SourcePrefix2 + part, nil
}
@@ -1,34 +0,0 @@
package meshcatalogclient
import (
"strings"
"testing"
)
// The key part holds only bus key characters and parsing gives the fingerprint back; a src1 or malformed value is refused,
// naming it.
func TestFingerprintKeyPart(t *testing.T) {
fp := SourcePrefix2 + strings.Repeat("ab", 32)
part, err := KeyPart(fp)
if err != nil {
t.Fatal(err)
}
if len(part) != 64 || strings.Trim(part, "0123456789abcdef") != "" {
t.Errorf("key part %q is not 64 lowercase hex characters", part)
}
back, err := ParseKeyPart(part)
if err != nil || back != fp {
t.Errorf("parse(%q) = %q, %v; want %q", part, back, err, fp)
}
src1 := "src1:" + strings.Repeat("c", 64)
for _, bad := range []string{src1, "src2:", "src2:xyz", "", "src2:" + strings.Repeat("A", 64), "src2:" + strings.Repeat("a", 63)} {
if _, err := KeyPart(bad); err == nil || !strings.Contains(err.Error(), "\""+bad+"\"") {
t.Errorf("KeyPart(%q) = %v, want a refusal naming it", bad, err)
}
}
for _, bad := range []string{src1, "src2:" + strings.Repeat("a", 64), strings.Repeat("a", 63), strings.Repeat("A", 64), "", "zz"} {
if _, err := ParseKeyPart(bad); err == nil || !strings.Contains(err.Error(), "\""+bad+"\"") {
t.Errorf("ParseKeyPart(%q) = %v, want a refusal naming it", bad, err)
}
}
}
@@ -1,8 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/clients/meshcatalogclient
go 1.26.0
require (
git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000
)
@@ -1,12 +0,0 @@
github.com/klauspost/compress v1.20.1 h1:T7kKElXUMXrUJ2E9QhQhxFtcK5rPyLdsGZvdbLMPdiQ=
github.com/klauspost/compress v1.20.1/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
@@ -1,79 +0,0 @@
package meshcatalogclient
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"unicode/utf8"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// ManifestDigest is the hex sha256 of a manifest's bytes exactly as read at the commit: the key of a `manifests` value and
// the digest a `modules` value and a candidate's module carry (novox/hq ADR 0429 clause 16).
func ManifestDigest(raw []byte) string {
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:])
}
// ManifestsKey is the key of a `manifests` value: the manifest's digest, 64 lowercase hex digits. The indexer writes it
// once, by a create that fails when the key exists.
func ManifestsKey(digest string) (string, error) {
if !keys.IsHex64(digest) {
return "", fmt.Errorf("meshcatalogclient: %q is not a manifest digest, 64 lowercase hex digits", digest)
}
return seat.ManifestsByDigestKey(digest), nil
}
// ParseManifestsKey is the inverse of ManifestsKey.
func ParseManifestsKey(key string) (string, error) {
digest, err := ManifestsKey(key)
if err != nil {
return "", fmt.Errorf("meshcatalogclient: %q is not a manifests key: %w", key, err)
}
return digest, nil
}
func checkManifest(m seat.ManifestsByDigestValue) error {
if err := keys.CheckName("module", m.Module); err != nil {
return err
}
if m.Manifest == "" {
return fmt.Errorf("meshcatalogclient: the manifest of %s is empty", m.Module)
}
if !utf8.ValidString(m.Manifest) {
return fmt.Errorf("meshcatalogclient: the manifest of %s is not UTF-8 text, which a value cannot hold byte for byte", m.Module)
}
if !json.Valid([]byte(m.Manifest)) {
return fmt.Errorf("meshcatalogclient: the manifest of %s is not JSON", m.Module)
}
return nil
}
// EncodeManifest is m as JSON at the kept values' version; it refuses a module that is not a name and a manifest that is
// empty, not UTF-8 or not JSON.
func EncodeManifest(m seat.ManifestsByDigestValue) ([]byte, error) {
if err := checkManifest(m); err != nil {
return nil, err
}
m.V = keys.Version
return json.Marshal(m)
}
// DecodeManifest reads a `manifests` value; it refuses an unknown version (keys.ErrUnknownVersion) and what EncodeManifest
// refuses.
func DecodeManifest(data []byte) (seat.ManifestsByDigestValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.ManifestsByDigestValue{}, err
}
var m seat.ManifestsByDigestValue
if err := json.Unmarshal(data, &m); err != nil {
return seat.ManifestsByDigestValue{}, fmt.Errorf("meshcatalogclient: value does not fit its shape: %w", err)
}
if err := checkManifest(m); err != nil {
return seat.ManifestsByDigestValue{}, err
}
return m, nil
}
@@ -1,133 +0,0 @@
package meshcatalogclient
import (
"encoding/json"
"fmt"
"path"
"strings"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// RootPath is a `modules` value's path when the module's manifest is its repository's root.
const RootPath = "."
// SourcePrefix1 opens the fingerprint of the old form a `modules` value may still carry in `fp`.
const SourcePrefix1 = "src1:"
// ModulesKey is the key of a `modules` value: the module's name.
func ModulesKey(module string) (string, error) {
if err := keys.CheckName("module", module); err != nil {
return "", err
}
return seat.ModulesByModuleKey(module), nil
}
// ParseModulesKey is the inverse of ModulesKey.
func ParseModulesKey(key string) (string, error) {
module, err := ModulesKey(key)
if err != nil {
return "", fmt.Errorf("meshcatalogclient: %q is not a modules key: %w", key, err)
}
return module, nil
}
// CheckModule refuses a `modules` value that contradicts itself: both or neither of a fingerprint and the reason for none,
// of either form, an old fingerprint not of the form `src1:`, kept inputs without a manifest digest, a verdict the indexer
// does not write, problems without a refusal (or a refusal without problems), a path that is not clean inside the module's
// directory, and a fingerprint or a digest not of its form.
func CheckModule(m seat.ModulesByModuleValue) error {
switch {
case m.Fp != "" && m.None != "":
return fmt.Errorf("meshcatalogclient: a module has both a fingerprint and a reason for none")
case m.Fp == "" && m.None == "" && m.Fp2 == "" && m.None2 == "":
return fmt.Errorf("meshcatalogclient: a module has neither a fingerprint nor a reason for none, of either form")
case m.Fp != "" && !strings.HasPrefix(m.Fp, SourcePrefix1):
return fmt.Errorf("meshcatalogclient: the module's fingerprint %q does not start with %s", m.Fp, SourcePrefix1)
case m.Fp2 != "" && m.None2 != "":
return fmt.Errorf("meshcatalogclient: a module has both fp2 and none2")
}
for language, t := range m.Toolchains {
if t.Version == "" || t.Recipe == "" {
return fmt.Errorf("meshcatalogclient: the module's toolchain of %q needs its version and its recipe version", language)
}
}
if m.Inputs2 != nil && m.Manifest == "" {
return fmt.Errorf("meshcatalogclient: a module keeps new-form inputs but has no manifest digest")
}
for artifact, paths := range m.Paths {
if artifact == "" || len(paths) == 0 {
return fmt.Errorf("meshcatalogclient: the module's named paths of the artifact %q are empty or name no artifact", artifact)
}
for _, p := range paths {
if !cleanInside(p) {
return fmt.Errorf("meshcatalogclient: the artifact %q names the path %q, not a clean path inside the module's directory", artifact, p)
}
}
}
if in := m.Inputs2; in != nil {
if f := in.ImportForm; f != "" && (len(in.Imports) == 0 || !strings.HasPrefix(f, SourcePrefix2) || !keys.IsHex64(f[len(SourcePrefix2):])) {
return fmt.Errorf("meshcatalogclient: the kept import form %q is set only with imports, and is %s and 64 hex digits", f, SourcePrefix2)
}
for p, object := range in.Paths {
if !cleanInside(p) {
return fmt.Errorf("meshcatalogclient: the named path %q is not a clean path inside the module's directory", p)
}
if object == "" {
return fmt.Errorf("meshcatalogclient: the named path %q names no git object", p)
}
}
}
switch {
case m.Verdict != "" && m.Verdict != VerdictAccepted && m.Verdict != VerdictRefused:
return fmt.Errorf("meshcatalogclient: the module's verdict %q is neither %s nor %s", m.Verdict, VerdictAccepted, VerdictRefused)
case len(m.Unknown) > 0 && m.Verdict != VerdictRefused:
return fmt.Errorf("meshcatalogclient: a module's unknown fields are named only with the refusal a wait is written as")
case m.Verdict != "" && m.Manifest == "":
return fmt.Errorf("meshcatalogclient: a module carries a verdict and no manifest digest")
case (m.Verdict == VerdictRefused) != (len(m.Problems) > 0):
return fmt.Errorf("meshcatalogclient: a module's problems are named only with a refusal, and a refusal names them")
case m.Verdict == VerdictRefused && len(m.Warnings) > 0:
return fmt.Errorf("meshcatalogclient: a refused module warns: a refusal names problems")
}
if m.Fp2 != "" {
if _, err := KeyPart(m.Fp2); err != nil {
return err
}
}
if m.Manifest != "" {
if _, err := ManifestsKey(m.Manifest); err != nil {
return err
}
}
return nil
}
func cleanInside(p string) bool {
return p != "" && p == path.Clean(p) && !strings.HasPrefix(p, "/") && p != ".." && !strings.HasPrefix(p, "../")
}
// EncodeModule is m as JSON at the kept values' version; it refuses what CheckModule refuses.
func EncodeModule(m seat.ModulesByModuleValue) ([]byte, error) {
if err := CheckModule(m); err != nil {
return nil, err
}
m.V = keys.Version
return json.Marshal(m)
}
// DecodeModule reads a `modules` value; it refuses an unknown version (keys.ErrUnknownVersion) and what EncodeModule refuses.
func DecodeModule(data []byte) (seat.ModulesByModuleValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.ModulesByModuleValue{}, err
}
var m seat.ModulesByModuleValue
if err := json.Unmarshal(data, &m); err != nil {
return seat.ModulesByModuleValue{}, fmt.Errorf("meshcatalogclient: value does not fit its shape: %w", err)
}
if err := CheckModule(m); err != nil {
return seat.ModulesByModuleValue{}, err
}
return m, nil
}
@@ -1,168 +0,0 @@
package meshcatalogclient
import (
"encoding/json"
"fmt"
"slices"
"strings"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// The states of a verdict on a manifest (novox/hq ADR 0578 §1): the indexer judges every manifest it takes in once and
// every other part takes the verdict from the seat's state `verdicts`.
const (
// VerdictAccepted is the state of a manifest the judge found no problem in.
VerdictAccepted = "accepted"
// VerdictRefused is the state of a manifest the judge found a problem in; the verdict's problems say each.
VerdictRefused = "refused"
// VerdictManifestWaits is the state of a manifest that carries a field the judge does not know: it is not refused,
// because a newer judge may know the field; the verdict's unknown names each. A reader holds the module as a refused
// one and keeps what runs. In a `modules` value it is written as a refusal naming the fields.
VerdictManifestWaits = "waits"
)
// VerdictsKey is the key of a `verdicts` value: the digest of the manifest it judges.
func VerdictsKey(digest string) (string, error) {
if !keys.IsHex64(digest) {
return "", fmt.Errorf("meshcatalogclient: %q is not a manifest digest, 64 lowercase hex digits", digest)
}
return seat.VerdictsByDigestKey(digest), nil
}
// VerdictRefuses says whether v refuses its manifest.
func VerdictRefuses(v seat.VerdictsByDigestValue) bool { return v.State == VerdictRefused }
// VerdictWaits says whether v says the manifest waits for a judge that knows its fields.
func VerdictWaits(v seat.VerdictsByDigestValue) bool { return v.State == VerdictManifestWaits }
// VerdictHeld says whether a reader holds the module as refused: the manifest is refused or waits.
func VerdictHeld(v seat.VerdictsByDigestValue) bool { return VerdictRefuses(v) || VerdictWaits(v) }
// WaitsOn says, in words, what a waiting manifest waits on.
func WaitsOn(v seat.VerdictsByDigestValue) string {
return "it carries " + strings.Join(v.Unknown, ", ") + ", which the indexer's judge does not know yet"
}
// TakeVerdict is how a reader takes the verdict on a manifest (ADR 0578 §3): held, with its problems, when the indexer
// wrote a refusal, or, for a manifest that waits, with the words that say which fields it waits on. A missing verdict (nil)
// is taken as accepted: every manifest the indexer holds before it has judged it was taken in under the judges that ran
// until then. A reader holds a refused module and names it with VerdictWhy, and reads the rest.
func TakeVerdict(v *seat.VerdictsByDigestValue) (refused bool, problems []string) {
if v == nil || !VerdictHeld(*v) {
return false, nil
}
if VerdictWaits(*v) {
return true, []string{WaitsOn(*v)}
}
return true, v.Problems
}
// VerdictWhy is a refusal in a reader's words: the module, that the indexer's judge refused its manifest, and each problem.
func VerdictWhy(v seat.VerdictsByDigestValue) string {
if !VerdictHeld(v) {
return ""
}
judge := "the indexer's judge"
if v.Judge != "" {
judge += " (" + v.Judge + ")"
}
if VerdictWaits(v) {
return fmt.Sprintf("%s holds the manifest of %s: %s", judge, v.Module, WaitsOn(v))
}
why := fmt.Sprintf("%s refused the manifest of %s:", judge, v.Module)
for _, p := range v.Problems {
why += " " + p + ";"
}
return why[:len(why)-1]
}
// VerdictAsRefused is v as a reader that does not know the waiting state takes it: a waiting verdict is a refusal naming what
// it waits on, any other verdict is v.
func VerdictAsRefused(v seat.VerdictsByDigestValue) seat.VerdictsByDigestValue {
if !VerdictWaits(v) {
return v
}
v.State, v.Problems, v.Unknown = VerdictRefused, []string{WaitsOn(v)}, nil
return v
}
// SameVerdict says whether v and o say the same of a manifest: the module, the state, the problems, the unknown fields and
// the warnings, whoever judged and when. The indexer writes a verdict only when it is not the same as the one it holds.
func SameVerdict(v, o seat.VerdictsByDigestValue) bool {
return v.Module == o.Module && v.State == o.State && slices.Equal(v.Problems, o.Problems) && slices.Equal(v.Unknown, o.Unknown) && slices.Equal(v.Warnings, o.Warnings)
}
func checkVerdict(v seat.VerdictsByDigestValue) error {
if err := keys.CheckName("module", v.Module); err != nil {
return err
}
if v.State != VerdictManifestWaits && len(v.Unknown) > 0 {
return fmt.Errorf("meshcatalogclient: the verdict on %s names unknown fields and does not wait", v.Module)
}
switch v.State {
case VerdictAccepted:
if len(v.Problems) > 0 {
return fmt.Errorf("meshcatalogclient: the verdict on %s accepts its manifest and names problems", v.Module)
}
case VerdictRefused:
if len(v.Problems) == 0 {
return fmt.Errorf("meshcatalogclient: the verdict on %s refuses its manifest and names no problem", v.Module)
}
if len(v.Warnings) > 0 {
return fmt.Errorf("meshcatalogclient: the verdict on %s refuses its manifest and warns: a refusal names problems", v.Module)
}
case VerdictManifestWaits:
if len(v.Unknown) == 0 || len(v.Problems) > 0 || len(v.Warnings) > 0 {
return fmt.Errorf("meshcatalogclient: the verdict on %s waits and names no unknown field, or names problems or warnings: a wait names the fields", v.Module)
}
default:
return fmt.Errorf("meshcatalogclient: the verdict on %s is %q, none of %s, %s and %s", v.Module, v.State, VerdictAccepted, VerdictRefused, VerdictManifestWaits)
}
if v.Judge == "" {
return fmt.Errorf("meshcatalogclient: the verdict on %s names no judge", v.Module)
}
return nil
}
// EncodeVerdict is v as JSON at the kept values' version; it refuses a verdict without a module or a judge, a state other
// than accepted, refused or waits, a refusal naming no problem and an acceptance naming one.
func EncodeVerdict(v seat.VerdictsByDigestValue) ([]byte, error) {
if err := checkVerdict(v); err != nil {
return nil, err
}
v.V = keys.Version
return json.Marshal(v)
}
// DecodeVerdict reads a `verdicts` value; it refuses an unknown version (keys.ErrUnknownVersion) and what EncodeVerdict
// refuses.
func DecodeVerdict(data []byte) (seat.VerdictsByDigestValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.VerdictsByDigestValue{}, err
}
var v seat.VerdictsByDigestValue
if err := json.Unmarshal(data, &v); err != nil {
return seat.VerdictsByDigestValue{}, fmt.Errorf("meshcatalogclient: value does not fit its shape: %w", err)
}
if err := checkVerdict(v); err != nil {
return seat.VerdictsByDigestValue{}, err
}
return v, nil
}
// ModuleVerdict is the verdict a `modules` value carries, or nil when it carries none (taken as accepted, TakeVerdict). A
// refusal naming unknown fields is the wait it was written as.
func ModuleVerdict(module string, m seat.ModulesByModuleValue) *seat.VerdictsByDigestValue {
if m.Verdict == "" && len(m.Warnings) == 0 {
return nil
}
if m.Verdict == "" {
return &seat.VerdictsByDigestValue{Module: module, State: VerdictAccepted, Warnings: m.Warnings}
}
if m.Verdict == VerdictRefused && len(m.Unknown) > 0 {
return &seat.VerdictsByDigestValue{Module: module, State: VerdictManifestWaits, Unknown: m.Unknown}
}
return &seat.VerdictsByDigestValue{Module: module, State: m.Verdict, Problems: m.Problems}
}
@@ -1,323 +0,0 @@
// Package meshdeliveryclient holds the logic the holders and callers of the seat mesh-delivery share over its contract
// (novox/hq ADR 0625 §4, ADR 0634 §2, ADR 0635 §5): the keys of its states `merges`, `asks` and `owed` and the rules their
// values keep, the id the teller gives the router for an ask, and the act an ask's options bind. The gate writes them, the
// forge bridge, the teller and the assigner read them; the contract's decoding is strict by schema only, so these rules are
// written once here and no caller copies them.
package meshdeliveryclient
import (
"crypto/sha256"
"encoding/hex"
"fmt"
"regexp"
"sort"
"strconv"
"strings"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// AskKindMerge is the kind of the gate's ask for a group's merge, the first part of its key.
const AskKindMerge = "merge"
// VerbMerge is the act an ask for a group's merge binds in its options, `mesh-delivery.merge` (Approve).
const VerbMerge = "merge"
// Head is one pull request at one commit: the repository as `<owner>/<name>` and the full sha.
type Head struct {
Repository string `json:"repository"`
Number int `json:"number"`
Head string `json:"head"`
}
// HeadsHash is the first 12 hex digits of the sha256 over the lines `<repository>#<number>=<head>`, sorted and joined by a
// newline: the same for every order of heads, different when any head changes. An empty list is refused.
func HeadsHash(heads []Head) (string, error) {
if len(heads) == 0 {
return "", fmt.Errorf("meshdeliveryclient: a heads hash needs at least one pull request")
}
lines := make([]string, len(heads))
for i, h := range heads {
lines[i] = fmt.Sprintf("%s#%d=%s", h.Repository, h.Number, h.Head)
}
sort.Strings(lines)
sum := sha256.Sum256([]byte(strings.Join(lines, "\n")))
return hex.EncodeToString(sum[:])[:12], nil
}
var hashOK = regexp.MustCompile(`^[0-9a-f]{12}$`)
func groupKey(group string) (string, error) {
if group == "" {
return "", fmt.Errorf("meshdeliveryclient: the group name is empty")
}
return keys.EscapeName(group), nil
}
// MergesKey is the key, in the state merges, of a group: `<group>`, escaped so a branch such as `fix/1.2` keys.
func MergesKey(group string) (string, error) { return groupKey(group) }
// MergeAskKey is the key, in the state asks, of the ask for merging a group at these heads: `merge.<group>.<heads hash>`.
// The teller's answer has the same key.
func MergeAskKey(group string, heads []Head) (string, error) {
part, err := groupKey(group)
if err != nil {
return "", err
}
hash, err := HeadsHash(heads)
if err != nil {
return "", err
}
return AskKindMerge + "." + part + "." + hash, nil
}
// ParseAskKey is the inverse of MergeAskKey: the kind, the group and the heads hash.
func ParseAskKey(key string) (kind, group, hash string, err error) {
parts := strings.Split(key, ".")
if len(parts) != 3 || parts[0] != AskKindMerge {
return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key, merge.<group>.<heads hash>", key)
}
if parts[1] == "" {
return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key: the group name is empty", key)
}
if group, err = keys.UnescapeName(parts[1]); err != nil {
return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key: %w", key, err)
}
if !hashOK.MatchString(parts[2]) {
return "", "", "", fmt.Errorf("meshdeliveryclient: %q is not an ask key: %q is not 12 hex digits", key, parts[2])
}
return parts[0], group, parts[2], nil
}
// SettleGroupPrefix begins the group of a settle ask (novox/hq ADR 0556 clause 5): a person's ask to settle deliveries held
// because their merge reached the trunk without a passing check. It is kept in the asks under MergeAskKey like a merge ask,
// so the teller carries it unchanged. Git forbids a colon in a branch name, so no pull request's group ever begins with it.
const SettleGroupPrefix = "settle:"
// SettleGroup is the group of the settle ask of these delivery ids: the prefix and twelve hex digits of the sha256 over the
// ids, sorted and joined by a newline, so the same deliveries asked again keep one key.
func SettleGroup(ids []string) string {
sorted := append([]string(nil), ids...)
sort.Strings(sorted)
sum := sha256.Sum256([]byte(strings.Join(sorted, "\n")))
return SettleGroupPrefix + hex.EncodeToString(sum[:])[:12]
}
// AskVerb is the act the options of an ask bind, by its group: a settle ask's `mesh-delivery.settle`, any other
// `mesh-delivery.merge`. The gate composes the act with it and the teller checks a warrant against it.
func AskVerb(group string) string {
if strings.HasPrefix(group, SettleGroupPrefix) {
return seat.Seat + "." + seat.VerbSettle
}
return seat.Seat + "." + VerbMerge
}
// AskID is the id the teller gives the router for the ask at askKey. The router's ids refuse dots, so in the readable part a
// dot becomes `-` and any other byte outside letters, digits, `_` and `-` becomes `_`; that part is cut to fit, and every id
// ends in `-` and the first 12 hex digits of the sha256 of the whole key, so two keys never give one id. It cannot be read
// back: the teller keeps the key beside it.
func AskID(askKey string) string {
const most = 64 // the router's bound on an id
const tail = 13 // "-" and 12 hex digits
readable := []byte(askKey)
for i, c := range readable {
switch {
case c >= 'A' && c <= 'Z', c >= 'a' && c <= 'z', c >= '0' && c <= '9':
case c == '.':
readable[i] = '-'
default: // a slash, an equals sign or any other byte the router's id refuses
readable[i] = '_'
}
}
if len(readable) > 0 && (readable[0] == '-' || readable[0] == '_') {
readable[0] = 'k' // an id starts with a letter or digit
}
if len(readable) > most-tail {
readable = readable[:most-tail]
}
sum := sha256.Sum256([]byte(askKey))
return string(readable) + "-" + hex.EncodeToString(sum[:])[:12]
}
// AskingID is the id of the asking-th writing of the ask at askKey. Asking 0 and 1 give AskID(askKey), so the first asking's
// id is unchanged; asking n of 2 or more gives the AskID form of askKey + "." + n, so each asking has an id of its own and the
// router, which drops an ask under an id it keeps as a redelivery, takes each as new and an answer to an earlier asking is
// never taken for a later one.
func AskingID(askKey string, asking int) string {
if asking < 2 {
return AskID(askKey)
}
return AskID(askKey + "." + strconv.Itoa(asking))
}
// The acts the gate owes the forge, the last part of an owed key.
const (
OwedStatus = "status"
OwedView = "view"
OwedNote = "note"
OwedComment = "comment"
)
// The status contexts the mesh owes the forge.
const (
StatusContextMergeGate = "mesh/merge-gate"
StatusContextDelivery = "mesh/delivery"
StatusContextDeliveryGroup = "mesh/delivery-group"
StatusContextRepoCheck = "mesh/repo-check"
StatusContextCheck = "mesh/check"
)
var statusContexts = []string{StatusContextMergeGate, StatusContextDelivery, StatusContextDeliveryGroup, StatusContextRepoCheck, StatusContextCheck}
// StatusContexts is the contexts, in a new slice.
func StatusContexts() []string { return append([]string(nil), statusContexts...) }
// The states a status the gate owes the forge may carry.
var statusStates = []string{"pending", "success", "failure", "error", "warning"}
func checkStatusContext(context string) error {
for _, c := range statusContexts {
if context == c {
return nil
}
}
return fmt.Errorf("meshdeliveryclient: the status context %q is not one of %s", context, strings.Join(statusContexts, ", "))
}
// ParseOwedAct splits an owed act into its kind and, for a status, its context, for a comment its sequence as digits. The act
// is `status=<context>`, `view`, `note` or `comment.<seq>`.
func ParseOwedAct(act string) (kind, context string, err error) {
kind, context, hasContext := strings.Cut(act, "=")
switch kind {
case OwedStatus:
if !hasContext {
return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q is a status without its context, status=<context>", act)
}
if err := checkStatusContext(context); err != nil {
return "", "", err
}
return kind, context, nil
case OwedView, OwedNote:
if hasContext {
return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q takes no context", act)
}
return kind, "", nil
}
if kind, seq, ok := strings.Cut(act, "."); ok && kind == OwedComment {
if n, err := strconv.Atoi(seq); err != nil || n < 1 || strconv.Itoa(n) != seq {
return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q is a comment without its sequence, comment.<seq> with seq of 1 or more", act)
}
return OwedComment, seq, nil
}
return "", "", fmt.Errorf("meshdeliveryclient: the owed act %q is not status=<context>, view, note or comment.<seq>", act)
}
// OwedCommentAct is the act of the seq-th comment on a head: `comment.<seq>`, seq of 1 or more, so a second comment has a key
// of its own and does not overwrite the first.
func OwedCommentAct(seq int) (string, error) {
if seq < 1 {
return "", fmt.Errorf("meshdeliveryclient: a comment's sequence is 1 or more, not %d", seq)
}
return OwedComment + "." + strconv.Itoa(seq), nil
}
func escapeRepository(repository string) (string, error) {
owner, name, ok := strings.Cut(repository, "/")
if !ok || owner == "" || name == "" || strings.Contains(name, "/") {
return "", fmt.Errorf("meshdeliveryclient: the repository %q is not <owner>/<name>, with exactly one slash", repository)
}
return keys.EscapeName(owner) + "/" + keys.EscapeName(name), nil
}
func unescapeRepository(part string) (string, error) {
owner, name, ok := strings.Cut(part, "/")
if !ok || owner == "" || name == "" || strings.Contains(name, "/") {
return "", fmt.Errorf("meshdeliveryclient: the repository %q is not <owner>/<name>, with exactly one slash", part)
}
o, err := keys.UnescapeName(owner)
if err != nil {
return "", err
}
n, err := keys.UnescapeName(name)
if err != nil {
return "", err
}
return o + "/" + n, nil
}
// OwedKey is the key, in the state owed, of an act the gate owes the forge on a pull request at a head:
// `<repository>.<number>.<head>.<act>`. The number is 0 for a commit no pull request names, and never negative.
func OwedKey(repository string, number int, head, act string) (string, error) {
repo, err := escapeRepository(repository)
if err != nil {
return "", err
}
if number < 0 {
return "", fmt.Errorf("meshdeliveryclient: an owed key's pull request number is 0 (none) or more, not %d", number)
}
if err := keys.CheckName("head", head); err != nil {
return "", err
}
if _, _, err := ParseOwedAct(act); err != nil {
return "", err
}
return repo + "." + strconv.Itoa(number) + "." + head + "." + act, nil
}
// ParseOwedKey is the inverse of OwedKey; act is whole, as `status=<context>` for a status.
func ParseOwedKey(key string) (repository string, number int, head, act string, err error) {
parts := strings.SplitN(key, ".", 4) // a comment's act holds a dot
if len(parts) != 4 {
return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key, <repository>.<number>.<head>.<act>", key)
}
number, convErr := strconv.Atoi(parts[1])
if convErr != nil {
return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key: %q is not a pull request number", key, parts[1])
}
if repository, err = unescapeRepository(parts[0]); err != nil {
return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key: %w", key, err)
}
if _, err := OwedKey(repository, number, parts[2], parts[3]); err != nil {
return "", 0, "", "", fmt.Errorf("meshdeliveryclient: %q is not an owed key: %w", key, err)
}
return repository, number, parts[2], parts[3], nil
}
// CheckOwed refuses an owed value the forge bridge could not perform: a status needs its context (one the mesh owes), a
// state of the list and a target; a view and a comment need text; a note needs text and a ref.
func CheckOwed(o seat.OwedByRepositoryNumberHeadActValue) error {
const who = "meshdeliveryclient: "
switch o.Act {
case OwedStatus:
if o.Context == "" {
return fmt.Errorf(who + "an owed status has no context")
}
if err := checkStatusContext(o.Context); err != nil {
return err
}
if o.Target == "" {
return fmt.Errorf(who + "an owed status has no target")
}
for _, s := range statusStates {
if o.State == s {
return nil
}
}
return fmt.Errorf(who+"the owed status state %q is not %s", o.State, strings.Join(statusStates, ", "))
case OwedView, OwedComment:
if o.Text == "" {
return fmt.Errorf(who+"an owed %s has no text", o.Act)
}
case OwedNote:
if o.Text == "" {
return fmt.Errorf(who + "an owed note has no text")
}
if o.Ref == "" {
return fmt.Errorf(who + "an owed note has no ref")
}
default:
return fmt.Errorf(who+"the owed act %q is not status, view, note or comment", o.Act)
}
return nil
}
@@ -1,129 +0,0 @@
package meshdeliveryclient
import (
"encoding/json"
"os"
"strings"
"testing"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery"
)
// The keys, ids and acts equal what the gate and the teller have always written (the expected strings are the trunk's own
// output for the same input), so a value written before is read after.
func TestTheAsksAndOwedActsKeepTheirFormsAndRules(t *testing.T) {
heads := []Head{{Repository: "novox/a", Number: 3, Head: "abc"}, {Repository: "novox/b", Number: 1, Head: "def"}}
key, err := MergeAskKey("fix/1.2", heads)
if err != nil || key != "merge.fix/1=2e2.d106c7950d28" {
t.Fatalf("MergeAskKey = %q, %v", key, err)
}
if rev, _ := MergeAskKey("fix/1.2", []Head{heads[1], heads[0]}); rev != key {
t.Errorf("the heads' order changes the key: %q", rev)
}
if kind, group, hash, err := ParseAskKey(key); err != nil || kind != "merge" || group != "fix/1.2" || hash != "d106c7950d28" {
t.Errorf("ParseAskKey = %q %q %q %v", kind, group, hash, err)
}
for _, bad := range []string{"merge.g", "settle.g.d106c7950d28", "merge..d106c7950d28", "merge.g.D106C7950D28", "merge.g.d106"} {
if _, _, _, err := ParseAskKey(bad); err == nil {
t.Errorf("ParseAskKey(%q) reads a wrong key", bad)
}
}
if _, err := MergeAskKey("", heads); err == nil {
t.Error("an empty group keys")
}
if _, err := MergeAskKey("g", nil); err == nil {
t.Error("no heads keys")
}
if id := AskID(key); id != "merge-fix_1_2e2-d106c7950d28-400030402c88" || AskingID(key, 1) != id || AskingID(key, 0) != id {
t.Errorf("AskID = %q", id)
}
if id := AskingID(key, 3); id != "merge-fix_1_2e2-d106c7950d28-3-ea06879e48d8" || len(id) > 64 {
t.Errorf("AskingID(3) = %q", id)
}
if g := SettleGroup([]string{"b", "a"}); g != "settle:7e18f737311b" || g != SettleGroup([]string{"a", "b"}) {
t.Errorf("SettleGroup = %q", g)
}
if AskVerb(SettleGroup([]string{"a"})) != "mesh-delivery.settle" || AskVerb("fix/1") != "mesh-delivery.merge" {
t.Error("AskVerb binds the wrong act")
}
for act, want := range map[string]string{"status=mesh/check": "novox/a.3.abc.status=mesh/check", "view": "novox/a.3.abc.view", "comment.2": "novox/a.3.abc.comment.2"} {
k, err := OwedKey("novox/a", 3, "abc", act)
if err != nil || k != want {
t.Errorf("OwedKey(%q) = %q, %v", act, k, err)
}
if repo, n, head, a, err := ParseOwedKey(k); err != nil || repo != "novox/a" || n != 3 || head != "abc" || a != act {
t.Errorf("ParseOwedKey(%q) = %q %d %q %q %v", k, repo, n, head, a, err)
}
}
for _, act := range []string{"status", "status=mesh/other", "view=x", "comment", "comment.0", "comment.01", "other"} {
if _, err := OwedKey("novox/a", 3, "abc", act); err == nil {
t.Errorf("OwedKey takes the act %q", act)
}
}
if _, err := OwedKey("novox", 0, "abc", "view"); err == nil {
t.Error("a repository with no slash keys")
}
if _, err := OwedKey("novox/a", -1, "abc", "view"); err == nil {
t.Error("a negative number keys")
}
if act, err := OwedCommentAct(2); err != nil || act != "comment.2" {
t.Errorf("OwedCommentAct = %q, %v", act, err)
}
type owed = seat.OwedByRepositoryNumberHeadActValue
for name, c := range map[string]struct {
v owed
says string
}{
"a good status": {owed{Act: "status", Context: StatusContextCheck, Target: "http://x", State: "success"}, ""},
"a good note": {owed{Act: "note", Text: "t", Ref: "mesh-plan"}, ""},
"a status no target": {owed{Act: "status", Context: StatusContextCheck, State: "success"}, "no target"},
"a status wrong state": {owed{Act: "status", Context: StatusContextCheck, Target: "x", State: "done"}, "state"},
"a status no context": {owed{Act: "status", Target: "x", State: "success"}, "no context"},
"a view no text": {owed{Act: "view"}, "no text"},
"a note no ref": {owed{Act: "note", Text: "t"}, "no ref"},
"an unknown act": {owed{Act: "merge"}, "not status"},
} {
err := CheckOwed(c.v)
if (c.says == "") != (err == nil) || (err != nil && !strings.Contains(err.Error(), c.says)) {
t.Errorf("%s: CheckOwed = %v, want %q", name, err, c.says)
}
}
}
// The removed verbs are the optional rows of the seat's definition that say they were removed, each with the replacement
// the definition gives: the list and the definition cannot drift apart.
func TestTheRemovedVerbsAreTheDefinitionsRemovedRows(t *testing.T) {
raw, err := os.ReadFile("../../../seats/mesh-delivery/seat.json")
if err != nil {
t.Fatal(err)
}
var def struct {
Verbs []struct {
Name string `json:"name"`
Description string `json:"description"`
Optional bool `json:"optional"`
} `json:"verbs"`
}
if err := json.Unmarshal(raw, &def); err != nil {
t.Fatal(err)
}
removed := RemovedVerbs()
rows := 0
for _, v := range def.Verbs {
if !strings.HasPrefix(v.Description, RemovedPrefix) {
if _, in := removed[v.Name]; in {
t.Errorf("%s is in the removed list, the definition keeps it", v.Name)
}
continue
}
rows++
if want, in := removed[v.Name]; !in || !v.Optional || v.Description != RemovedPrefix+want {
t.Errorf("%s: in the list %v, optional %v, described %q, want %q", v.Name, in, v.Optional, v.Description, RemovedPrefix+want)
}
}
if rows != len(removed) || rows == 0 {
t.Errorf("the definition removes %d verbs, the list names %d", rows, len(removed))
}
}
@@ -1,407 +0,0 @@
package meshdeliveryclient
import (
"bytes"
"encoding/json"
"fmt"
"reflect"
"strconv"
"strings"
"time"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// The values of the seat's states `source`, `merges`, `asks`, `owed` and `turns`, in the seat's types: each is stamped
// with Version when encoded, read strictly (an unknown field refused) and its version checked when decoded, and its rules
// held on both sides, so the gate that writes them and the readers (the forge bridge, the teller, the assigner, the view)
// agree. What the schema cannot say is written here once (ADR 0625 §4).
// Version is the layout version of the seat's values.
const Version = 1
// MergeState is the state of a pull request in a merge.
type MergeState string
// The states a merge's pull request is in.
const (
MergeMerging MergeState = "merging"
MergeMerged MergeState = "merged"
MergeRefused MergeState = "refused"
)
// SourceMainKey is the one key of the state source.
const SourceMainKey = "main"
func encodeValue(v any, check error, stamp func()) ([]byte, error) {
if check != nil {
return nil, check
}
stamp()
return json.Marshal(v)
}
// ApprovedKey is the key, in a merge's approved heads, of a pull request: `<repository>@<number>`.
func ApprovedKey(repository string, number int) string {
return repository + "@" + strconv.Itoa(number)
}
// TurnsKey is the key, in the state turns, of a repository: `<owner>.<name>`, lower-case and escaped.
func TurnsKey(repository string) (string, error) {
repository = strings.ToLower(repository)
part, err := escapeRepository(repository)
if err != nil {
return "", err
}
return strings.Replace(part, "/", ".", 1), nil
}
// ParseTurnsKey is the inverse of TurnsKey; a key that does not name a lower-case <owner>/<name> is refused.
func ParseTurnsKey(key string) (string, error) {
owner, name, ok := strings.Cut(key, ".")
if !ok || owner == "" || name == "" || strings.Contains(name, ".") {
return "", fmt.Errorf("meshdeliveryclient: %q is not a turns key, <owner>.<name>", key)
}
repository, err := unescapeRepository(owner + "/" + name)
if err != nil {
return "", fmt.Errorf("meshdeliveryclient: %q is not a turns key: %w", key, err)
}
if again, err := TurnsKey(repository); err != nil || again != key {
return "", fmt.Errorf("meshdeliveryclient: %q is not a turns key: it does not name a lowercase <owner>/<name>", key)
}
return repository, nil
}
// ----- source
// CheckSource refuses a source naming no repository, a repository with no name or an empty head.
func CheckSource(s seat.SourceByMainValue) error {
if len(s.Heads) == 0 {
return fmt.Errorf("meshdeliveryclient: a source names no repository")
}
for repository, head := range s.Heads {
if repository == "" {
return fmt.Errorf("meshdeliveryclient: a source names a repository with no name")
}
if head == "" {
return fmt.Errorf("meshdeliveryclient: the source's head of %s is empty", repository)
}
}
return nil
}
// EncodeSource is s as the value of the key main.
func EncodeSource(s seat.SourceByMainValue) ([]byte, error) {
return encodeValue(&s, CheckSource(s), func() { s.V = Version })
}
// DecodeSource reads the value of the key main.
func DecodeSource(data []byte) (seat.SourceByMainValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.SourceByMainValue{}, err
}
s, err := seat.DecodeSourceByMainValue(data)
if err != nil {
return s, fmt.Errorf("meshdeliveryclient: a source does not fit its shape: %w", err)
}
return s, CheckSource(s)
}
// SameSource says whether two sources are the same.
func SameSource(a, b seat.SourceByMainValue) bool { return reflect.DeepEqual(a, b) }
// ----- merge
// CheckMerge refuses a merge naming no group, ask or pull request, a pull request outside the approved heads or at
// another head than the Approve was for, and a state that lacks what it needs: merged its commit, refused the forge's words.
func CheckMerge(m seat.MergesByGroupValue) error {
if m.Group == "" {
return fmt.Errorf("meshdeliveryclient: a merge names no group")
}
if m.Ask == "" {
return fmt.Errorf("meshdeliveryclient: a merge names no ask")
}
if len(m.Pulls) == 0 {
return fmt.Errorf("meshdeliveryclient: a merge names no pull request")
}
for key, sha := range m.Approved {
if sha == "" {
return fmt.Errorf("meshdeliveryclient: the approved head of %s is empty", key)
}
}
for _, p := range m.Pulls {
who := fmt.Sprintf("%s#%d", p.Repository, p.Number)
if len(m.Approved) > 0 {
sha, ok := m.Approved[ApprovedKey(p.Repository, int(p.Number))]
if !ok {
return fmt.Errorf("meshdeliveryclient: the pull request %s is handed to the merge but is not among the approved heads", who)
}
if sha != p.Head {
return fmt.Errorf("meshdeliveryclient: the pull request %s is handed at head %q but the Approve was for %q", who, p.Head, sha)
}
}
switch MergeState(p.State) {
case MergeMerging:
case MergeMerged:
if p.Commit == "" {
return fmt.Errorf("meshdeliveryclient: the merged pull request %s has no merge commit", who)
}
case MergeRefused:
if p.Words == "" {
return fmt.Errorf("meshdeliveryclient: the refused pull request %s has no words of the forge", who)
}
default:
return fmt.Errorf("meshdeliveryclient: the state %q of %s is not merging, merged or refused", p.State, who)
}
}
return nil
}
// EncodeMerge is m as the value of a group's key.
func EncodeMerge(m seat.MergesByGroupValue) ([]byte, error) {
return encodeValue(&m, CheckMerge(m), func() { m.V = Version })
}
// DecodeMerge reads the value of a group's key.
func DecodeMerge(data []byte) (seat.MergesByGroupValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.MergesByGroupValue{}, err
}
m, err := seat.DecodeMergesByGroupValue(data)
if err != nil {
return m, fmt.Errorf("meshdeliveryclient: a merge does not fit its shape: %w", err)
}
return m, CheckMerge(m)
}
// SameMerge says whether two merges are the same.
func SameMerge(a, b seat.MergesByGroupValue) bool { return reflect.DeepEqual(a, b) }
// ----- ask
// HeadsOf are an ask's heads as Heads (for HeadsHash and MergeAskKey).
func HeadsOf(items []seat.AsksByMergeGroupHeadsValueHeadsItem) []Head {
out := make([]Head, len(items))
for i, h := range items {
out[i] = Head{Repository: h.Repository, Number: int(h.Number), Head: h.Head}
}
return out
}
// CheckAsk refuses an ask with no group or heads, a negative count, or an ask that is no object.
func CheckAsk(a seat.AsksByMergeGroupHeadsValue) error {
if a.Asking < 0 {
return fmt.Errorf("meshdeliveryclient: the ask's asking %d is negative", a.Asking)
}
if _, err := MergeAskKey(a.Group, HeadsOf(a.Heads)); err != nil {
return fmt.Errorf("meshdeliveryclient: an ask needs its group and at least one pull request's head: %w", err)
}
raw, err := json.Marshal(a.Ask)
var fields map[string]json.RawMessage
if err != nil || len(bytes.TrimSpace(raw)) == 0 || json.Unmarshal(raw, &fields) != nil || fields == nil {
return fmt.Errorf("meshdeliveryclient: the value carries no router's ask")
}
return nil
}
// EncodeAsk is a as the value of a merge ask's key; a.Ask may be a json.RawMessage.
func EncodeAsk(a seat.AsksByMergeGroupHeadsValue) ([]byte, error) {
return encodeValue(&a, CheckAsk(a), func() { a.V = Version })
}
// DecodeAsk reads the value of a merge ask's key; its Ask is the router's ask as a decoded object.
func DecodeAsk(data []byte) (seat.AsksByMergeGroupHeadsValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.AsksByMergeGroupHeadsValue{}, err
}
a, err := seat.DecodeAsksByMergeGroupHeadsValue(data)
if err != nil {
return a, fmt.Errorf("meshdeliveryclient: an ask does not fit its shape: %w", err)
}
return a, CheckAsk(a)
}
// SameAsk says whether two asks are the same (the router's ask by its content).
func SameAsk(a, b seat.AsksByMergeGroupHeadsValue) bool { return reflect.DeepEqual(a, b) }
// ----- owed
// EncodeOwed is o as the value of an owed key, after CheckOwed.
func EncodeOwed(o seat.OwedByRepositoryNumberHeadActValue) ([]byte, error) {
return encodeValue(&o, CheckOwed(o), func() { o.V = Version })
}
// DecodeOwed reads the value of an owed key.
func DecodeOwed(data []byte) (seat.OwedByRepositoryNumberHeadActValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.OwedByRepositoryNumberHeadActValue{}, err
}
o, err := seat.DecodeOwedByRepositoryNumberHeadActValue(data)
if err != nil {
return o, fmt.Errorf("meshdeliveryclient: an owed value does not fit its shape: %w", err)
}
return o, CheckOwed(o)
}
// SameOwed says whether two owed values are the same.
func SameOwed(a, b seat.OwedByRepositoryNumberHeadActValue) bool { return a == b }
// ----- turns
// CheckTurn refuses a turn whose repository is not lower-case, that names no delivery, or whose deliveries repeat a heads
// hash, lack their times, are out of the order of the Approve, or name a wait without a verdict key.
func CheckTurn(t seat.TurnsByRepositoryValue) error {
repository := strings.ToLower(t.Repository)
if repository != t.Repository {
return fmt.Errorf("meshdeliveryclient: the turn's repository %q is not lowercase", t.Repository)
}
if _, err := escapeRepository(repository); err != nil {
return err
}
if len(t.Waiting) == 0 {
return fmt.Errorf("meshdeliveryclient: the turn of %s names no delivery: its key is deleted instead", t.Repository)
}
seen := map[string]bool{}
for i, w := range t.Waiting {
if w.Group == "" {
return fmt.Errorf("meshdeliveryclient: a delivery in the turn of %s names no group", t.Repository)
}
if !hashOK.MatchString(w.Heads) {
return fmt.Errorf("meshdeliveryclient: the heads hash %q in the turn of %s is not 12 lowercase hex digits", w.Heads, t.Repository)
}
if seen[w.Heads] {
return fmt.Errorf("meshdeliveryclient: the turn of %s names the heads %s twice", t.Repository, w.Heads)
}
seen[w.Heads] = true
if w.Approved.IsZero() || w.Since.IsZero() {
return fmt.Errorf("meshdeliveryclient: the delivery %s in the turn of %s says no time of its Approve or of its wait", w.Group, t.Repository)
}
if i > 0 && w.Approved.Before(t.Waiting[i-1].Approved) {
return fmt.Errorf("meshdeliveryclient: the turn of %s is not in the order of the Approve: %s was approved before %s", t.Repository, w.Group, t.Waiting[i-1].Group)
}
if w.WaitsFor != "" {
if _, _, err := parseVerdictKey(w.WaitsFor); err != nil {
return fmt.Errorf("meshdeliveryclient: the delivery %s in the turn of %s waits for what is not a verdict key: %w", w.Group, t.Repository, err)
}
} else if (w.WaitsSince != nil && !w.WaitsSince.IsZero()) || w.Step != "" {
return fmt.Errorf("meshdeliveryclient: the delivery %s in the turn of %s says when and where a check runs, and names no check", w.Group, t.Repository)
}
}
return nil
}
// parseVerdictKey is the checker's verdict key `<group>.<heads hash>` (the checker's client has the same rule over its
// own seat; a client uses its own seat's contract alone).
func parseVerdictKey(key string) (group, heads string, err error) {
i := strings.LastIndex(key, ".")
if i < 0 || !hashOK.MatchString(key[i+1:]) || i == 0 || strings.Contains(key[:i], ".") {
return "", "", fmt.Errorf("%q is not a verdict key, <group>.<heads hash>", key)
}
if group, err = keys.UnescapeName(key[:i]); err != nil {
return "", "", err
}
return group, key[i+1:], nil
}
// TurnHolds says whether a delivery at these heads is not in the turn while the turn names others: the delivery's
// check or merge holds back for the one before it.
func TurnHolds(t seat.TurnsByRepositoryValue, heads string) bool {
if len(t.Waiting) == 0 {
return false
}
for _, w := range t.Waiting {
if w.Heads == heads {
return false
}
}
return true
}
// EncodeTurn is t as the value of a repository's key.
func EncodeTurn(t seat.TurnsByRepositoryValue) ([]byte, error) {
if err := CheckTurn(t); err != nil {
return nil, err
}
t.V = Version
return json.Marshal(t)
}
// DecodeTurn reads the value of a repository's key.
func DecodeTurn(data []byte) (seat.TurnsByRepositoryValue, error) {
if err := keys.CheckVersion(data); err != nil {
return seat.TurnsByRepositoryValue{}, err
}
t, err := seat.DecodeTurnsByRepositoryValue(data)
if err != nil {
return t, fmt.Errorf("meshdeliveryclient: a turn does not fit its shape: %w", err)
}
return t, CheckTurn(t)
}
// SameTurn says whether two turns are the same, a time by the instant it names.
func SameTurn(a, b seat.TurnsByRepositoryValue) bool {
if len(a.Waiting) != len(b.Waiting) || a.Repository != b.Repository || a.V != b.V {
return false
}
for i := range a.Waiting {
x, y := a.Waiting[i], b.Waiting[i]
if !x.Approved.Equal(y.Approved) || !x.Since.Equal(y.Since) || !sameTime(x.WaitsSince, y.WaitsSince) {
return false
}
x.Approved, y.Approved, x.Since, y.Since, x.WaitsSince, y.WaitsSince = time.Time{}, time.Time{}, time.Time{}, time.Time{}, nil, nil
if !reflect.DeepEqual(x, y) {
return false
}
}
return true
}
func sameTime(a, b *time.Time) bool {
if a == nil || a.IsZero() {
return b == nil || b.IsZero()
}
return b != nil && a.Equal(*b)
}
// Answer is the operator's answer to a merge ask as the gate acts on it: the option chosen, the warrant that proves who
// answered, and the words said. It is the teller's state `answers` under the ask's key (the teller's own record; this is
// its layout for the gate that reads it).
type Answer struct {
V int `json:"v"`
Option string `json:"option"`
Warrant string `json:"warrant"`
Words string `json:"words"`
}
// CheckAnswer refuses an answer lacking its option, warrant or words.
func CheckAnswer(a Answer) error {
for _, f := range []struct{ name, value string }{{"option", a.Option}, {"warrant", a.Warrant}, {"words", a.Words}} {
if f.value == "" {
return fmt.Errorf("meshdeliveryclient: an answer has no %s", f.name)
}
}
return nil
}
// EncodeAnswer is a as the value of an answer's key.
func EncodeAnswer(a Answer) ([]byte, error) {
return encodeValue(&a, CheckAnswer(a), func() { a.V = Version })
}
// DecodeAnswer reads the value of an answer's key.
func DecodeAnswer(data []byte) (Answer, error) {
if err := keys.CheckVersion(data); err != nil {
return Answer{}, err
}
var a Answer
dec := json.NewDecoder(bytes.NewReader(data))
dec.DisallowUnknownFields()
if err := dec.Decode(&a); err != nil {
return Answer{}, fmt.Errorf("meshdeliveryclient: an answer does not fit its shape: %w", err)
}
return a, CheckAnswer(a)
}
// SameAnswer says whether two answers are the same.
func SameAnswer(a, b Answer) bool { return a == b }
@@ -1,186 +0,0 @@
package meshdeliveryclient
import (
"encoding/json"
"errors"
"reflect"
"strings"
"testing"
"time"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// sameJSON says whether two documents hold the same values (the generated types write their fields in alphabetical
// order, the old package's in declaration order: the bytes differ, the documents do not).
func sameJSON(t *testing.T, got []byte, want string) {
t.Helper()
var g, w any
if err := json.Unmarshal(got, &g); err != nil {
t.Fatalf("%s: %v", got, err)
}
if err := json.Unmarshal([]byte(want), &w); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(g, w) {
t.Errorf("got %s\nwant %s", got, want)
}
}
// The goldens are the output of go/delivery's Encode* before it was deleted; each value must encode to the same
// document and decode back to what it was.
func TestGateValuesEncodeAsGoDeliveryDid(t *testing.T) {
ap := time.Date(2026, 11, 5, 10, 0, 0, 0, time.UTC)
wait := ap.Add(2 * time.Minute)
for _, c := range []struct {
name string
encode func() ([]byte, error)
decode func([]byte) (any, error)
value any
golden string
}{
{"source", func() ([]byte, error) {
return EncodeSource(seat.SourceByMainValue{Group: "fix/1.2", Heads: map[string]string{"novox/a": "aaaa", "novox/b": "bbbb"}})
}, func(b []byte) (any, error) { return DecodeSource(b) },
seat.SourceByMainValue{V: 1, Group: "fix/1.2", Heads: map[string]string{"novox/a": "aaaa", "novox/b": "bbbb"}},
`{"v":1,"group":"fix/1.2","heads":{"novox/a":"aaaa","novox/b":"bbbb"}}`},
{"merge", func() ([]byte, error) {
return EncodeMerge(seat.MergesByGroupValue{Group: "g", Ask: "merge.g.0123456789ab", Approved: map[string]string{"novox/a@7": "h1"},
Pulls: []seat.MergesByGroupValuePullsItem{{Repository: "novox/a", Number: 7, Head: "h1", State: "merged", Commit: "c1"}}})
}, func(b []byte) (any, error) { return DecodeMerge(b) },
seat.MergesByGroupValue{V: 1, Group: "g", Ask: "merge.g.0123456789ab", Approved: map[string]string{"novox/a@7": "h1"},
Pulls: []seat.MergesByGroupValuePullsItem{{Repository: "novox/a", Number: 7, Head: "h1", State: "merged", Commit: "c1"}}},
`{"v":1,"group":"g","ask":"merge.g.0123456789ab","approved":{"novox/a@7":"h1"},"pulls":[{"repository":"novox/a","number":7,"head":"h1","state":"merged","commit":"c1"}]}`},
{"ask", func() ([]byte, error) {
return EncodeAsk(seat.AsksByMergeGroupHeadsValue{Group: "g", Asking: 2, Ask: json.RawMessage(`{"headline":"x"}`),
Heads: []seat.AsksByMergeGroupHeadsValueHeadsItem{{Repository: "novox/a", Number: 7, Head: "h1"}}})
}, func(b []byte) (any, error) { return DecodeAsk(b) },
seat.AsksByMergeGroupHeadsValue{V: 1, Group: "g", Asking: 2, Ask: map[string]any{"headline": "x"},
Heads: []seat.AsksByMergeGroupHeadsValueHeadsItem{{Repository: "novox/a", Number: 7, Head: "h1"}}},
`{"v":1,"group":"g","heads":[{"repository":"novox/a","number":7,"head":"h1"}],"ask":{"headline":"x"},"asking":2}`},
{"owed", func() ([]byte, error) {
return EncodeOwed(seat.OwedByRepositoryNumberHeadActValue{Act: OwedStatus, Context: StatusContextCheck, Target: "t", State: "pending"})
}, func(b []byte) (any, error) { return DecodeOwed(b) },
seat.OwedByRepositoryNumberHeadActValue{V: 1, Act: OwedStatus, Context: StatusContextCheck, Target: "t", State: "pending"},
`{"v":1,"act":"status","context":"mesh/check","target":"t","state":"pending"}`},
{"turn", func() ([]byte, error) {
return EncodeTurn(seat.TurnsByRepositoryValue{Repository: "novox/a", Waiting: []seat.TurnsByRepositoryValueWaitingItem{{
Group: "g", Heads: "0123456789ab", Ask: "k", Approved: ap, Since: ap.Add(time.Minute), WaitsFor: "g.0123456789ab", WaitsSince: &wait, Step: "s"}}})
}, func(b []byte) (any, error) { return DecodeTurn(b) },
seat.TurnsByRepositoryValue{V: 1, Repository: "novox/a", Waiting: []seat.TurnsByRepositoryValueWaitingItem{{
Group: "g", Heads: "0123456789ab", Ask: "k", Approved: ap, Since: ap.Add(time.Minute), WaitsFor: "g.0123456789ab", WaitsSince: &wait, Step: "s"}}},
`{"v":1,"repository":"novox/a","waiting":[{"group":"g","heads":"0123456789ab","ask":"k","approved":"2026-11-05T10:00:00Z","since":"2026-11-05T10:01:00Z","waits-for":"g.0123456789ab","waits-since":"2026-11-05T10:02:00Z","step":"s"}]}`},
{"answer", func() ([]byte, error) { return EncodeAnswer(Answer{Option: "merge", Warrant: "w", Words: "ok"}) },
func(b []byte) (any, error) { return DecodeAnswer(b) }, Answer{V: 1, Option: "merge", Warrant: "w", Words: "ok"},
`{"v":1,"option":"merge","warrant":"w","words":"ok"}`},
} {
raw, err := c.encode()
if err != nil {
t.Fatalf("%s: %v", c.name, err)
}
sameJSON(t, raw, c.golden)
back, err := c.decode([]byte(c.golden))
if err != nil || !reflect.DeepEqual(back, c.value) {
t.Errorf("%s decoded %+v, %v; want %+v", c.name, back, err, c.value)
}
}
}
func TestGateKeysAsGoDeliveryHadThem(t *testing.T) {
for in, want := range map[string]string{"novox/Mesh-sdk": "novox.mesh-sdk", "novox/mesh-sdk": "novox.mesh-sdk", "novox/mesh.x": "novox.mesh=2ex"} {
got, err := TurnsKey(in)
if err != nil || got != want {
t.Errorf("TurnsKey(%q) = %q, %v; want %q", in, got, err, want)
}
}
if r, err := ParseTurnsKey("novox.mesh=2ex"); err != nil || r != "novox/mesh.x" {
t.Errorf("%q %v", r, err)
}
for _, bad := range []string{"novox", "novox.Mesh", "a.b.c", ".x", "novox.mesh-sdk."} {
if _, err := ParseTurnsKey(bad); err == nil {
t.Errorf("%q parses as a turns key", bad)
}
}
if _, err := TurnsKey("novox"); err == nil {
t.Error("a repository with no slash keys")
}
if k := ApprovedKey("novox/a", 7); k != "novox/a@7" {
t.Error(k)
}
if SourceMainKey != seat.SourceByMainKey() {
t.Error("the source's key is the seat's")
}
}
func TestGateValuesRefuseWhatTheirRulesRefuse(t *testing.T) {
ap := time.Date(2026, 11, 5, 10, 0, 0, 0, time.UTC)
pull := seat.MergesByGroupValuePullsItem{Repository: "novox/a", Number: 7, Head: "h1", State: "merging"}
merge := func(edit func(*seat.MergesByGroupValue)) error {
m := seat.MergesByGroupValue{Group: "g", Ask: "k", Pulls: []seat.MergesByGroupValuePullsItem{pull}}
edit(&m)
_, err := EncodeMerge(m)
return err
}
turn := func(edit func(*seat.TurnsByRepositoryValue)) error {
tv := seat.TurnsByRepositoryValue{Repository: "novox/a", Waiting: []seat.TurnsByRepositoryValueWaitingItem{{Group: "g", Heads: "0123456789ab", Approved: ap, Since: ap}}}
edit(&tv)
_, err := EncodeTurn(tv)
return err
}
for name, c := range map[string]struct {
err error
want string
}{
"merge: no group": {merge(func(m *seat.MergesByGroupValue) { m.Group = "" }), "no group"},
"merge: no pull": {merge(func(m *seat.MergesByGroupValue) { m.Pulls = nil }), "no pull request"},
"merge: not approved": {merge(func(m *seat.MergesByGroupValue) { m.Approved = map[string]string{"novox/b@1": "x"} }), "not among the approved"},
"merge: other head": {merge(func(m *seat.MergesByGroupValue) { m.Approved = map[string]string{"novox/a@7": "x"} }), "Approve was for"},
"merge: merged no commit": {merge(func(m *seat.MergesByGroupValue) { m.Pulls[0].State = "merged" }), "no merge commit"},
"merge: refused no words": {merge(func(m *seat.MergesByGroupValue) { m.Pulls[0].State = "refused" }), "no words"},
"merge: unknown state": {merge(func(m *seat.MergesByGroupValue) { m.Pulls[0].State = "lost" }), "not merging, merged or refused"},
"turn: upper case": {turn(func(v *seat.TurnsByRepositoryValue) { v.Repository = "Novox/a" }), "not lowercase"},
"turn: empty": {turn(func(v *seat.TurnsByRepositoryValue) { v.Waiting = nil }), "names no delivery"},
"turn: bad hash": {turn(func(v *seat.TurnsByRepositoryValue) { v.Waiting[0].Heads = "xyz" }), "12 lowercase hex"},
"turn: no time": {turn(func(v *seat.TurnsByRepositoryValue) { v.Waiting[0].Since = time.Time{} }), "no time"},
"turn: step with no wait": {turn(func(v *seat.TurnsByRepositoryValue) { v.Waiting[0].Step = "s" }), "names no check"},
"turn: not a verdict key": {turn(func(v *seat.TurnsByRepositoryValue) { v.Waiting[0].WaitsFor = "nope" }), "not a verdict key"},
} {
if c.err == nil || !strings.Contains(c.err.Error(), c.want) {
t.Errorf("%s: %v, want %q", name, c.err, c.want)
}
}
if _, err := EncodeSource(seat.SourceByMainValue{Group: "g"}); err == nil {
t.Error("an empty source encodes")
}
if _, err := EncodeAsk(seat.AsksByMergeGroupHeadsValue{Group: "g", Ask: "text", Heads: []seat.AsksByMergeGroupHeadsValueHeadsItem{{Repository: "novox/a", Number: 1, Head: "h"}}}); err == nil {
t.Error("an ask that is no object encodes")
}
if _, err := EncodeAnswer(Answer{Option: "merge"}); err == nil {
t.Error("an answer with no warrant encodes")
}
if _, err := DecodeSource([]byte(`{"v":2,"group":"g","heads":{"a":"b"}}`)); !errors.Is(err, keys.ErrUnknownVersion) {
t.Errorf("another version: %v", err)
}
if _, err := DecodeMerge([]byte(`{"v":1,"group":"g","ask":"k","pulls":[],"extra":1}`)); err == nil {
t.Error("an unknown field decodes")
}
}
func TestTurnHoldsAndSameTurn(t *testing.T) {
ap := time.Date(2026, 11, 5, 10, 0, 0, 0, time.UTC)
tv := seat.TurnsByRepositoryValue{V: 1, Repository: "novox/a", Waiting: []seat.TurnsByRepositoryValueWaitingItem{{Group: "g", Heads: "0123456789ab", Approved: ap, Since: ap}}}
if TurnHolds(tv, "0123456789ab") || !TurnHolds(tv, "ba9876543210") || TurnHolds(seat.TurnsByRepositoryValue{}, "x") {
t.Error("a turn holds a delivery that is not in it while others wait")
}
other := tv
other.Waiting = []seat.TurnsByRepositoryValueWaitingItem{tv.Waiting[0]}
other.Waiting[0].Approved = ap.In(time.FixedZone("x", 3600))
if !SameTurn(tv, other) {
t.Error("the same instant in another zone is another turn")
}
other.Waiting[0].Since = ap.Add(time.Second)
if SameTurn(tv, other) {
t.Error("another instant is the same turn")
}
}
@@ -1,8 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/clients/meshdeliveryclient
go 1.26.0
require (
git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000
)
@@ -1,12 +0,0 @@
github.com/klauspost/compress v1.20.1 h1:T7kKElXUMXrUJ2E9QhQhxFtcK5rPyLdsGZvdbLMPdiQ=
github.com/klauspost/compress v1.20.1/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
@@ -1,18 +0,0 @@
package meshdeliveryclient
// RemovedPrefix opens the description of a verb release 6 removed from the seat mesh-delivery (novox/hq ADR 0539 clause 17):
// the definition keeps it as an optional row with no input, so the holder of before and the holder of release 6 both hold
// the seat, and a caller is answered by name with its replacement.
const RemovedPrefix = "Removed in R6 (ADR 0539): refused by name, naming its replacement: "
// RemovedVerbs are the seat's verbs release 6 removed, each with its replacement in words: with no plan the gate keeps the
// merge's states and derives nothing after the merge. A new map each call.
func RemovedVerbs() map[string]string {
return map[string]string{
"times": "the delivery view (nox-delivery): each machine's want and have, and since when",
"what-if": "the merge check's composition, which composes every machine a change touches",
"release": "the assigner's asks (hold, restore, backup, record), answered on the phone or in the delivery view",
"stop": "a bad fingerprint is held and its canary set back by the assigner (ADR 0429 §6, ADR 0539 clause 18)",
"retire-history": "nothing to retire: the gate keeps no delivery after its merge",
}
}
@@ -1,8 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/clients/meshwantsclient
go 1.26.0
require (
git.novox.be/novox/mesh-delivery/contracts/go/seats/meshwants v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000
)
@@ -1,326 +0,0 @@
// Package meshwantsclient is the client of the seat mesh-wants: the keys of its state wants, and the check and the codec
// of a want, a node's own want and a hold, which every module that reads or writes wants shares (the assigner that writes
// them, the node-engine, the provisioner and the artifact store that read them). The layouts are the seat's contract; this
// file writes the version and refuses what the earlier codec refused (novox/hq ADR 0528, ADR 0539, ADR 0546, ADR 0634 §4).
package meshwantsclient
import (
"encoding/json"
"fmt"
"regexp"
"strings"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// The three values of the state wants, in the seat's types.
type (
// Want is a node's want for a module: the fingerprint it should run and the digest of the one composition it allows,
// or Removed, or Self when the node composes it itself; Newest and Rule name what holds the node back.
Want = seat.WantsByWantNodeModuleValue
// NodeWant is a node's own want: the digest of the node's own composition it may apply.
NodeWant = seat.WantsByWantNodeNodeValue
// Held is a fingerprint the assigner holds: the node whose health check failed on it, and the check's words.
Held = seat.WantsByHeldModuleFingerprintValue
)
// The rules of ADR 0429 §6 and ADR 0539 clause 6, by number, as a want or a difference names the one that holds a node back.
const (
RuleBuildDone = 1 // the build of F is done
RuleNotHeld = 2 // F is not held
RuleCanary = 3 // the node is the module's canary, or the canary runs F healthy
RuleStep = 4 // at most step other nodes are ahead (step 0: no limit, ADR 0528 §3)
RuleProviders = 5 // every provider the module requires runs healthy on that node, or at its canary
RuleGrant = 6 // the module's credential for F exists (grants.<module>.<fp>)
RuleComposed = 7 // the module's composition for that node at F exists (ADR 0539 §6)
// RuleProvisions: every provision the module requires on that node is provided (novox/hq ADR 0570 §4).
RuleProvisions = 8
)
// ruleRead is the highest rule a reader takes (novox/hq ADR 0614 §2, §4): 9 and 10 are kept for the verb wait and the
// capability hold of a later release.
const ruleRead = 10
// The answers a want carries to a failed backup before an apply (ADR 0539 clause 16).
const (
// BackupAgain is the answer to back the module up again before the apply.
BackupAgain = seat.WantsByWantNodeModuleValueBackupAgain
// BackupSkip is the answer to go on without a backup.
BackupSkip = seat.WantsByWantNodeModuleValueBackupSkip
)
// NodeWord is the last part of a node's own key.
const NodeWord = "node"
const (
wantWord = "want"
heldWord = "held"
srcWord = "src2:"
)
var (
moduleNameOK = regexp.MustCompile(`^[-/_a-zA-Z0-9]+(\.[-/_a-zA-Z0-9]+)*$`)
digestForm = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`)
)
func moduleKeyPart(module string) (string, error) {
if module == "" {
return "", fmt.Errorf("wants: the module name is empty")
}
if !moduleNameOK.MatchString(module) {
return "", fmt.Errorf("wants: the module name %q holds a wildcard, whitespace, '=', an empty part between dots or a character a key refuses", module)
}
return keys.EscapeName(module), nil
}
func parseModuleKeyPart(part string) (string, error) {
if err := keys.CheckName("module", part); err != nil {
return "", err
}
module, err := keys.UnescapeName(part)
if err != nil {
return "", err
}
if back, err := moduleKeyPart(module); err != nil || back != part {
return "", fmt.Errorf("wants: the module part %q is not a module name as a key writes it", part)
}
return module, nil
}
func checkFingerprint(fp, of string) error {
if part, ok := strings.CutPrefix(fp, srcWord); !ok || !keys.IsHex64(part) {
return fmt.Errorf("wants: %s: %q is not a fingerprint of the new form, %s and 64 lowercase hex digits", of, fp, srcWord)
}
return nil
}
func checkDigest(digest, of string) error {
if !digestForm.MatchString(digest) {
return fmt.Errorf("wants: %s %q is not sha256:<64 lowercase hex digits>", of, digest)
}
return nil
}
func checkRule(rule int64, of string) error {
if rule < RuleBuildDone || rule > ruleRead {
return fmt.Errorf("wants: %s names the rule %d, which is not one of 1 to %d", of, rule, ruleRead)
}
return nil
}
// WantKey is the key, in the state wants, of a node's want for a module: `want.<node>.<module>`. A module named `node` is
// refused, since `want.<node>.node` is the node's own key.
func WantKey(node, module string) (string, error) {
if err := keys.CheckName("node", node); err != nil {
return "", err
}
part, err := moduleKeyPart(module)
if err != nil {
return "", err
}
if module == NodeWord {
return "", fmt.Errorf(`wants: the module name "node" is refused: want.%s.node is the node's own key`, node)
}
return seat.WantsByWantNodeModuleKey(node, part), nil
}
// WantNodeKey is the key of a node's own want: `want.<node>.node`.
func WantNodeKey(node string) (string, error) {
if err := keys.CheckName("node", node); err != nil {
return "", err
}
return seat.WantsByWantNodeNodeKey(node), nil
}
// ParseWantNodeKey is the inverse of WantNodeKey; it refuses a module's want key and any key of another form.
func ParseWantNodeKey(key string) (node string, err error) {
node, ok := seat.ParseWantsByWantNodeNodeKey(key)
if !ok || keys.CheckName("node", node) != nil {
return "", fmt.Errorf("wants: %q is not a node's own want key, want.<node>.node", key)
}
return node, nil
}
// ParseWantKey is the inverse of WantKey; it refuses a held key, the node's own want key and any key of another form.
func ParseWantKey(key string) (node, module string, err error) {
refused := fmt.Errorf("wants: %q is not a want key, want.<node>.<module>", key)
node, part, ok := seat.ParseWantsByWantNodeModuleKey(key)
if !ok || part == NodeWord || keys.CheckName("node", node) != nil {
return "", "", refused
}
if module, err = parseModuleKeyPart(part); err != nil {
return "", "", refused
}
return node, module, nil
}
// HeldKey is the key of a module's fingerprint the assigner holds: `held.<module>.<hex>`, the hex being the
// fingerprint's key part.
func HeldKey(module, fingerprint string) (string, error) {
if err := keys.CheckName("module", module); err != nil {
return "", err
}
if err := checkFingerprint(fingerprint, "a held key's fingerprint"); err != nil {
return "", err
}
return seat.WantsByHeldModuleFingerprintKey(module, strings.TrimPrefix(fingerprint, srcWord)), nil
}
// ParseHeldKey is the inverse of HeldKey: the module and the fingerprint (`src2:` and the hex).
func ParseHeldKey(key string) (module, fingerprint string, err error) {
module, part, ok := seat.ParseWantsByHeldModuleFingerprintKey(key)
if !ok || keys.CheckName("module", module) != nil || !keys.IsHex64(part) {
return "", "", fmt.Errorf("wants: %q is not a held key, held.<module>.<fingerprint hex>", key)
}
return module, srcWord + part, nil
}
func checkWant(w Want) error {
if w.Removed {
if w.Fp != "" || w.Composed != "" || w.Newest != "" || w.Rule != 0 || w.Backup != "" || w.Put || w.Hold || w.Self || w.Yes != "" || w.Release != "" {
return fmt.Errorf("wants: a removed want names no fingerprint, composition, rule, backup answer or put")
}
return nil
}
if w.Hold && !w.Put {
return fmt.Errorf("wants: only a put holds a want")
}
if w.Put && (w.Newest != "" || w.Rule != 0) {
return fmt.Errorf("wants: a put's want is held back by no rule")
}
if err := checkFingerprint(w.Fp, "a want's fingerprint"); err != nil {
return err
}
// A node the catalogue places composes its own modules (ADR 0547 §2): its want is Self and names the build alone. Any
// other want names the one composition it allows (ADR 0539 clause 1).
switch {
case w.Self && w.Composed != "":
return fmt.Errorf("wants: the want of %s says the node composes it, and names a composition", w.Fp)
case !w.Self && w.Composed == "":
return fmt.Errorf("wants: the want of %s names no composition: a want names the digest of the one composition it allows (ADR 0539 clause 1), unless the node composes it itself", w.Fp)
case w.Composed != "":
if err := checkDigest(w.Composed, "a want's composition digest"); err != nil {
return err
}
}
if w.Yes != "" {
if err := checkDigest(w.Yes, "the digest a want's yes allows"); err != nil {
return err
}
} else if w.Release != "" {
return fmt.Errorf("wants: the want of %s names the release %s and no yes it gave", w.Fp, w.Release)
}
switch w.Backup {
case "", BackupAgain, BackupSkip:
default:
return fmt.Errorf("wants: the backup answer %q is not %s or %s", w.Backup, BackupAgain, BackupSkip)
}
if w.Newest == "" && w.Rule == 0 {
return nil
}
if err := checkFingerprint(w.Newest, "a want's newest fingerprint"); err != nil {
return err
}
if w.Newest == w.Fp {
return fmt.Errorf("wants: a want at its newest fingerprint names no rule holding it back")
}
return checkRule(w.Rule, "a want held back")
}
// CheckWant refuses a want the codec refuses.
func CheckWant(w Want) error { return checkWant(w) }
// EncodeWant is w as JSON at the kept values' version; it refuses a fingerprint not of the new form, a removed want naming
// one, and a want that names no composition unless the node composes it itself.
func EncodeWant(w Want) ([]byte, error) {
if err := checkWant(w); err != nil {
return nil, err
}
w.V = keys.Version
return json.Marshal(w)
}
// DecodeWant reads a want; it refuses an unknown version (keys.ErrUnknownVersion), a field the contract does not know and
// what EncodeWant refuses.
func DecodeWant(data []byte) (Want, error) {
if err := keys.CheckVersion(data); err != nil {
return Want{}, err
}
w, err := seat.DecodeWantsByWantNodeModuleValue(data)
if err != nil {
return Want{}, fmt.Errorf("wants: value does not fit its shape: %w", err)
}
if err := checkWant(w); err != nil {
return Want{}, err
}
return w, nil
}
// SameWant says whether two wants are the same value, so the assigner writes only when they differ.
func SameWant(a, b Want) bool { return a == b }
func checkNodeWant(w NodeWant) error {
switch {
case w.Self && w.Composed != "":
return fmt.Errorf("wants: the node's own want says the node composes it, and names a composition")
case w.Self:
return nil
}
return checkDigest(w.Composed, "the node's own want's composition digest")
}
// EncodeNodeWant is w as JSON; it refuses a digest not of the sha256 form, and a want that names no composition unless it
// says the node composes its own (Self, ADR 0547 §2).
func EncodeNodeWant(w NodeWant) ([]byte, error) {
if err := checkNodeWant(w); err != nil {
return nil, err
}
w.V = keys.Version
return json.Marshal(w)
}
// DecodeNodeWant reads a node's own want; it refuses an unknown version, a field a node's own want does not have (a
// fingerprint among them), and what EncodeNodeWant refuses.
func DecodeNodeWant(data []byte) (NodeWant, error) {
if err := keys.CheckVersion(data); err != nil {
return NodeWant{}, err
}
w, err := seat.DecodeWantsByWantNodeNodeValue(data)
if err != nil {
return NodeWant{}, fmt.Errorf("wants: a node's own want does not fit its shape: %w", err)
}
if err := checkNodeWant(w); err != nil {
return NodeWant{}, err
}
return w, nil
}
func checkHeld(h Held) error { return keys.CheckName("node", h.Node) }
// EncodeHeld is h as JSON; it refuses a node name a key refuses.
func EncodeHeld(h Held) ([]byte, error) {
if err := checkHeld(h); err != nil {
return nil, err
}
h.V = keys.Version
return json.Marshal(h)
}
// DecodeHeld reads a hold; it refuses an unknown version and what EncodeHeld refuses.
func DecodeHeld(data []byte) (Held, error) {
if err := keys.CheckVersion(data); err != nil {
return Held{}, err
}
h, err := seat.DecodeWantsByHeldModuleFingerprintValue(data)
if err != nil {
return Held{}, fmt.Errorf("wants: value does not fit its shape: %w", err)
}
if err := checkHeld(h); err != nil {
return Held{}, err
}
return h, nil
}
// SameHeld says whether two holds are the same value.
func SameHeld(a, b Held) bool { return a == b }
@@ -1,162 +0,0 @@
package meshwantsclient
import (
"encoding/json"
"errors"
"reflect"
"strings"
"testing"
"git.novox.be/novox/mesh-sdk/go/keys"
)
func rep(c string) string { return strings.Repeat(c, 64) }
// TestWantsAreWhatTheEarlierCodecWrote holds the values and keys equal to what go/delivery's codec wrote for the same
// values (the golden texts are its output; the field order is the contract's now, so values are compared decoded), and the
// refusals it made.
func TestWantsAreWhatTheEarlierCodecWrote(t *testing.T) {
a, b, c, d := "src2:"+rep("a"), "src2:"+rep("b"), "sha256:"+rep("c"), "sha256:"+rep("d")
sameJSON := func(t *testing.T, got []byte, want string) {
t.Helper()
var g, w any
if err := json.Unmarshal(got, &g); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(want), &w); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(g, w) {
t.Fatalf("wrote %s, the earlier codec wrote %s", got, want)
}
}
t.Run("wants", func(t *testing.T) {
for name, row := range map[string]struct {
w Want
golden string
}{
"composed": {Want{Fp: a, Composed: c, Words: "w"}, `{"v":1,"fp":"` + a + `","composed":"` + c + `","words":"w"}`},
"held back": {Want{Fp: a, Self: true, Newest: b, Rule: RuleGrant, Backup: BackupAgain, Words: "held"}, `{"v":1,"fp":"` + a + `","newest":"` + b + `","rule":6,"backup":"again","words":"held","self":true}`},
"put": {Want{Fp: a, Self: true, Put: true, Hold: true, Yes: d, Release: "r1"}, `{"v":1,"fp":"` + a + `","put":true,"hold":true,"yes":"` + d + `","release":"r1","self":true}`},
"removed": {Want{Removed: true, Words: "gone"}, `{"v":1,"removed":true,"words":"gone"}`},
} {
t.Run(name, func(t *testing.T) {
raw, err := EncodeWant(row.w)
if err != nil {
t.Fatal(err)
}
sameJSON(t, raw, row.golden)
back, err := DecodeWant(raw)
if err != nil || !SameWant(back, func() Want { w := row.w; w.V = keys.Version; return w }()) {
t.Fatalf("read back %+v, %v", back, err)
}
})
}
})
t.Run("refused", func(t *testing.T) {
for name, w := range map[string]Want{
"old fingerprint": {Fp: "src1:abc", Composed: c},
"no composition": {Fp: a},
"self and composition": {Fp: a, Self: true, Composed: c},
"hold without put": {Fp: a, Self: true, Hold: true},
"put held back": {Fp: a, Self: true, Put: true, Newest: b, Rule: RuleStep},
"removed names a rule": {Removed: true, Rule: 1},
"release without yes": {Fp: a, Self: true, Release: "r"},
"backup answer unknown": {Fp: a, Self: true, Backup: "later"},
"newest equals fp": {Fp: a, Self: true, Newest: a, Rule: RuleStep},
"rule 11": {Fp: a, Self: true, Newest: b, Rule: 11},
"newest without a rule": {Fp: a, Self: true, Newest: b},
"composition not sha256": {Fp: a, Composed: "sha256:xyz"},
} {
if _, err := EncodeWant(w); err == nil {
t.Errorf("%s: written", name)
}
}
if _, err := EncodeWant(Want{Fp: a, Self: true, Newest: b, Rule: 10}); err != nil {
t.Errorf("rule 10 is read: %v", err)
}
if _, err := DecodeWant([]byte(`{"fp":"` + a + `","self":true}`)); !errors.Is(err, keys.ErrUnknownVersion) {
t.Errorf("no version: %v", err)
}
if _, err := DecodeWant([]byte(`{"v":1,"fp":"` + a + `","self":true,"extra":1}`)); err == nil {
t.Error("an unknown field is read")
}
})
t.Run("node want and hold", func(t *testing.T) {
raw, err := EncodeNodeWant(NodeWant{Composed: c, Words: "n"})
if err != nil {
t.Fatal(err)
}
sameJSON(t, raw, `{"v":1,"composed":"`+c+`","words":"n"}`)
raw, err = EncodeNodeWant(NodeWant{Self: true})
if err != nil {
t.Fatal(err)
}
sameJSON(t, raw, `{"v":1,"composed":"","self":true}`)
if back, err := DecodeNodeWant(raw); err != nil || !back.Self {
t.Fatalf("%+v %v", back, err)
}
for name, w := range map[string]NodeWant{"none": {}, "both": {Self: true, Composed: c}, "bad": {Composed: "x"}} {
if _, err := EncodeNodeWant(w); err == nil {
t.Errorf("%s: written", name)
}
}
if _, err := DecodeNodeWant([]byte(`{"v":1,"composed":"` + c + `","fp":"` + a + `"}`)); err == nil {
t.Error("a fingerprint in a node's own want is read")
}
raw, err = EncodeHeld(Held{Node: "ace", Words: "unhealthy"})
if err != nil {
t.Fatal(err)
}
sameJSON(t, raw, `{"v":1,"node":"ace","words":"unhealthy"}`)
if h, err := DecodeHeld(raw); err != nil || !SameHeld(h, Held{V: 1, Node: "ace", Words: "unhealthy"}) {
t.Fatalf("%+v %v", h, err)
}
if _, err := EncodeHeld(Held{Node: "a.b"}); err == nil {
t.Error("a node with a dot is held")
}
})
t.Run("keys", func(t *testing.T) {
for _, row := range []struct{ module, want string }{
{"mesh-delivery-assigner", "want.ace.mesh-delivery-assigner"},
{"novox.be", "want.ace.novox=2ebe"},
} {
k, err := WantKey("ace", row.module)
if err != nil || k != row.want {
t.Fatalf("WantKey %s = %q, %v", row.module, k, err)
}
if n, m, err := ParseWantKey(k); err != nil || n != "ace" || m != row.module {
t.Fatalf("ParseWantKey %q = %q %q %v", k, n, m, err)
}
}
if k, err := HeldKey("mesh-delivery-assigner", a); err != nil || k != "held.mesh-delivery-assigner."+rep("a") {
t.Fatalf("HeldKey = %q %v", k, err)
}
if m, fp, err := ParseHeldKey("held.mesh-delivery-assigner." + rep("a")); err != nil || m != "mesh-delivery-assigner" || fp != a {
t.Fatalf("ParseHeldKey = %q %q %v", m, fp, err)
}
if k, err := WantNodeKey("ace"); err != nil || k != "want.ace.node" {
t.Fatalf("WantNodeKey = %q %v", k, err)
}
if n, err := ParseWantNodeKey("want.ace.node"); err != nil || n != "ace" {
t.Fatalf("ParseWantNodeKey = %q %v", n, err)
}
if _, err := WantKey("ace", "node"); err == nil {
t.Error("a module named node has a want key")
}
if _, err := HeldKey("novox.be", a); err == nil {
t.Error("a module with a dot has a held key")
}
for _, key := range []string{"want.ace.node", "held.m." + rep("a"), "ace.m", "want.ace", "want..m"} {
if _, _, err := ParseWantKey(key); err == nil {
t.Errorf("%q is a want key", key)
}
}
if _, err := ParseWantNodeKey("want.ace.m"); err == nil {
t.Error("a module's want is a node's own")
}
if _, _, err := ParseHeldKey("want.ace.m"); err == nil {
t.Error("a want key is a held key")
}
})
}
@@ -1,63 +0,0 @@
// Package npmpackageregistryclient is the npm-package-registry seat's client (novox/hq ADR 0627 §1, §2; ADR 0611, design 51
// *Publishing*): it publishes a file in parts to the seat's holder. `publish` opens the transfer naming every part,
// the holder answers the parts it lacks, and only those travel by `publish-part`, in chunks a bus message carries; a
// cut transfer goes on from what the holder answers when the same transfer is opened again. The sending in parts is
// mesh-sdk's seat-neutral runtime (parts); this client binds it to this seat's verbs and types alone. The call is the
// caller's own (a bundle's stdio.Ask, a process's call of a seat verb), so it holds no transport.
package npmpackageregistryclient
import (
"context"
"encoding/base64"
"encoding/json"
"fmt"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/npmpackageregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// Call asks one verb of the seat, `seat:<seat>.<verb>`, with a body, and answers its JSON.
type Call func(key string, body any) (json.RawMessage, error)
// Sent is what a Publish did: the transfer, whether the holder held its digest already, the parts it lacked and were
// sent, and the chunks they took.
type Sent struct {
Transfer string
parts.Sent
}
// Publish opens (or opens again) the transfer in on the seat and sends the parts the holder answers it lacks, each in
// chunks of at most parts.MaxChunk, in sequence, the last marked. in.Parts is written from parts. A part whose bytes
// do not hash to its digest is refused before anything of it is sent; a part the holder does not name is never read.
// Its outcome, published or refused, is the holder's event, which the caller waits for.
func Publish(ctx context.Context, call Call, in seat.PublishInput, ps []parts.Part) (Sent, error) {
open := func(_ context.Context, ps []parts.Part) (parts.Opened, error) {
in.Parts = make([]seat.Part, 0, len(ps))
for _, p := range ps {
in.Parts = append(in.Parts, seat.Part{Digest: p.Digest, Size: p.Size})
}
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublish, in)
if err != nil {
return parts.Opened{}, fmt.Errorf("%s's publish of %s: %w", seat.Seat, in.Name, err)
}
var a seat.PublishAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return parts.Opened{}, fmt.Errorf("%s's answer to publish: %w", seat.Seat, err)
}
return parts.Opened{Held: a.Held, Lacks: a.Lacks}, nil
}
chunk := func(_ context.Context, part string, sequence int, last bool, data []byte) error {
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublishPart, seat.PublishPartInput{Transfer: in.Transfer, Part: part,
Sequence: int64(sequence), Last: last, Data: base64.StdEncoding.EncodeToString(data)})
if err != nil {
return fmt.Errorf("%s's publish-part: %w", seat.Seat, err)
}
var a seat.PublishPartAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return fmt.Errorf("%s's answer to publish-part: %w", seat.Seat, err)
}
return nil
}
sent, err := parts.Send(ctx, open, chunk, ps)
return Sent{Transfer: in.Transfer, Sent: sent}, err
}
@@ -1,57 +0,0 @@
package npmpackageregistryclient
import (
"bytes"
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"io"
"testing"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/npmpackageregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// The client publishes over its own seat's verbs alone (ADR 0627 §1): publish names every part, and only the part the
// holder lacks travels by publish-part, its bytes whole, the last chunk marked.
func TestPublishTalksToItsOwnSeat(t *testing.T) {
held, lacked := []byte("held"), []byte("lacked")
part := func(b []byte) parts.Part {
sum := sha256.Sum256(b)
return parts.Part{Digest: "sha256:" + hex.EncodeToString(sum[:]), Size: int64(len(b)),
Open: func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(b)), nil }}
}
ps := []parts.Part{part(held), part(lacked)}
var asked []string
var got []byte
call := func(key string, body any) (json.RawMessage, error) {
asked = append(asked, key)
raw, _ := json.Marshal(body)
switch key {
case "seat:npm-package-registry.publish":
var in seat.PublishInput
_ = json.Unmarshal(raw, &in)
if len(in.Parts) != 2 {
t.Errorf("publish names %d parts, want 2", len(in.Parts))
}
return json.Marshal(seat.PublishAnswer{Transfer: in.Transfer, Lacks: []string{ps[1].Digest}})
case "seat:npm-package-registry.publish-part":
var in seat.PublishPartInput
_ = json.Unmarshal(raw, &in)
data, _ := base64.StdEncoding.DecodeString(in.Data)
if in.Part != ps[1].Digest || !in.Last || in.Transfer != "t1" {
t.Errorf("publish-part %+v", in)
}
got = append(got, data...)
return json.Marshal(seat.PublishPartAnswer{Transfer: in.Transfer, Part: in.Part})
}
t.Fatalf("asked %s", key)
return nil, nil
}
sent, err := Publish(context.Background(), call, seat.PublishInput{Transfer: "t1", Name: "x"}, ps)
if err != nil || sent.Transfer != "t1" || sent.Chunks != 1 || len(sent.Parts) != 1 || !bytes.Equal(got, lacked) || len(asked) != 2 {
t.Errorf("sent %+v, %q arrived, asked %v, %v", sent, got, asked, err)
}
}
@@ -1,18 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/clients/npmpackageregistryclient
go 1.26.0
require (
git.novox.be/novox/mesh-delivery/contracts/go/seats/npmpackageregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/sdk v0.0.0-00010101000000-000000000000
)
require (
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000 // indirect
github.com/klauspost/compress v1.20.1 // indirect
github.com/nats-io/nats.go v1.54.0 // indirect
github.com/nats-io/nkeys v0.4.16 // indirect
github.com/nats-io/nuid v1.0.1 // indirect
golang.org/x/crypto v0.57.0 // indirect
golang.org/x/sys v0.48.0 // indirect
)
@@ -1,12 +0,0 @@
github.com/klauspost/compress v1.20.1 h1:T7kKElXUMXrUJ2E9QhQhxFtcK5rPyLdsGZvdbLMPdiQ=
github.com/klauspost/compress v1.20.1/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
@@ -1,63 +0,0 @@
// Package ociartifactregistryclient is the oci-artifact-registry seat's client (novox/hq ADR 0627 §1, §2; ADR 0611, design 51
// *Publishing*): it publishes a file in parts to the seat's holder. `publish` opens the transfer naming every part,
// the holder answers the parts it lacks, and only those travel by `publish-part`, in chunks a bus message carries; a
// cut transfer goes on from what the holder answers when the same transfer is opened again. The sending in parts is
// mesh-sdk's seat-neutral runtime (parts); this client binds it to this seat's verbs and types alone. The call is the
// caller's own (a bundle's stdio.Ask, a process's call of a seat verb), so it holds no transport.
package ociartifactregistryclient
import (
"context"
"encoding/base64"
"encoding/json"
"fmt"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/ociartifactregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// Call asks one verb of the seat, `seat:<seat>.<verb>`, with a body, and answers its JSON.
type Call func(key string, body any) (json.RawMessage, error)
// Sent is what a Publish did: the transfer, whether the holder held its digest already, the parts it lacked and were
// sent, and the chunks they took.
type Sent struct {
Transfer string
parts.Sent
}
// Publish opens (or opens again) the transfer in on the seat and sends the parts the holder answers it lacks, each in
// chunks of at most parts.MaxChunk, in sequence, the last marked. in.Parts is written from parts. A part whose bytes
// do not hash to its digest is refused before anything of it is sent; a part the holder does not name is never read.
// Its outcome, published or refused, is the holder's event, which the caller waits for.
func Publish(ctx context.Context, call Call, in seat.PublishInput, ps []parts.Part) (Sent, error) {
open := func(_ context.Context, ps []parts.Part) (parts.Opened, error) {
in.Parts = make([]seat.Part, 0, len(ps))
for _, p := range ps {
in.Parts = append(in.Parts, seat.Part{Digest: p.Digest, Size: p.Size})
}
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublish, in)
if err != nil {
return parts.Opened{}, fmt.Errorf("%s's publish of %s: %w", seat.Seat, in.Name, err)
}
var a seat.PublishAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return parts.Opened{}, fmt.Errorf("%s's answer to publish: %w", seat.Seat, err)
}
return parts.Opened{Held: a.Held, Lacks: a.Lacks}, nil
}
chunk := func(_ context.Context, part string, sequence int, last bool, data []byte) error {
raw, err := call("seat:"+seat.Seat+"."+seat.VerbPublishPart, seat.PublishPartInput{Transfer: in.Transfer, Part: part,
Sequence: int64(sequence), Last: last, Data: base64.StdEncoding.EncodeToString(data)})
if err != nil {
return fmt.Errorf("%s's publish-part: %w", seat.Seat, err)
}
var a seat.PublishPartAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return fmt.Errorf("%s's answer to publish-part: %w", seat.Seat, err)
}
return nil
}
sent, err := parts.Send(ctx, open, chunk, ps)
return Sent{Transfer: in.Transfer, Sent: sent}, err
}
@@ -1,57 +0,0 @@
package ociartifactregistryclient
import (
"bytes"
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"io"
"testing"
seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/ociartifactregistry"
"git.novox.be/novox/mesh-delivery/sdk/parts"
)
// The client publishes over its own seat's verbs alone (ADR 0627 §1): publish names every part, and only the part the
// holder lacks travels by publish-part, its bytes whole, the last chunk marked.
func TestPublishTalksToItsOwnSeat(t *testing.T) {
held, lacked := []byte("held"), []byte("lacked")
part := func(b []byte) parts.Part {
sum := sha256.Sum256(b)
return parts.Part{Digest: "sha256:" + hex.EncodeToString(sum[:]), Size: int64(len(b)),
Open: func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(b)), nil }}
}
ps := []parts.Part{part(held), part(lacked)}
var asked []string
var got []byte
call := func(key string, body any) (json.RawMessage, error) {
asked = append(asked, key)
raw, _ := json.Marshal(body)
switch key {
case "seat:oci-artifact-registry.publish":
var in seat.PublishInput
_ = json.Unmarshal(raw, &in)
if len(in.Parts) != 2 {
t.Errorf("publish names %d parts, want 2", len(in.Parts))
}
return json.Marshal(seat.PublishAnswer{Transfer: in.Transfer, Lacks: []string{ps[1].Digest}})
case "seat:oci-artifact-registry.publish-part":
var in seat.PublishPartInput
_ = json.Unmarshal(raw, &in)
data, _ := base64.StdEncoding.DecodeString(in.Data)
if in.Part != ps[1].Digest || !in.Last || in.Transfer != "t1" {
t.Errorf("publish-part %+v", in)
}
got = append(got, data...)
return json.Marshal(seat.PublishPartAnswer{Transfer: in.Transfer, Part: in.Part})
}
t.Fatalf("asked %s", key)
return nil, nil
}
sent, err := Publish(context.Background(), call, seat.PublishInput{Transfer: "t1", Name: "x"}, ps)
if err != nil || sent.Transfer != "t1" || sent.Chunks != 1 || len(sent.Parts) != 1 || !bytes.Equal(got, lacked) || len(asked) != 2 {
t.Errorf("sent %+v, %q arrived, asked %v, %v", sent, got, asked, err)
}
}
@@ -1,18 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/clients/ociartifactregistryclient
go 1.26.0
require (
git.novox.be/novox/mesh-delivery/contracts/go/seats/ociartifactregistry v0.0.0-00010101000000-000000000000
git.novox.be/novox/mesh-delivery/sdk v0.0.0-00010101000000-000000000000
)
require (
git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000 // indirect
github.com/klauspost/compress v1.20.1 // indirect
github.com/nats-io/nats.go v1.54.0 // indirect
github.com/nats-io/nkeys v0.4.16 // indirect
github.com/nats-io/nuid v1.0.1 // indirect
golang.org/x/crypto v0.57.0 // indirect
golang.org/x/sys v0.48.0 // indirect
)
@@ -1,12 +0,0 @@
github.com/klauspost/compress v1.20.1 h1:T7kKElXUMXrUJ2E9QhQhxFtcK5rPyLdsGZvdbLMPdiQ=
github.com/klauspost/compress v1.20.1/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
@@ -1,528 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package containerimageregistry is the contract of the seat "container-image-registry", defined whole (seats/container-image-registry/seat.json): The mesh's container images, in the one artifact store: the OCI distribution protocol's read side, an image's tags and mirroring an outside image.
package containerimageregistry
import (
"bytes"
"encoding/json"
"errors"
"strings"
)
// Seat is the seat's name.
const Seat = "container-image-registry"
const (
VerbPublish = "publish"
VerbPublishPart = "publish-part"
VerbVersions = "versions"
VerbRemove = "remove"
VerbMirror = "mirror"
VerbTags = "tags"
VerbHold = "hold"
VerbRelease = "release"
VerbList = "list"
)
const (
EventPublished = "published"
EventRefused = "refused"
EventRemoved = "removed"
EventKept = "kept"
EventHeld = "held"
EventReleased = "released"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove, VerbMirror, VerbTags, VerbHold, VerbRelease, VerbList}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventPublished, EventRefused, EventRemoved, EventKept, EventHeld, EventReleased}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "container-image-registry.events"
FamilyMaxAgeDays = 7
)
// SubjectPublished is where published is published.
const SubjectPublished = "mesh.seat.container-image-registry.event.published"
// SubjectRefused is where refused is published.
const SubjectRefused = "mesh.seat.container-image-registry.event.refused"
// SubjectRemoved is where removed is published.
const SubjectRemoved = "mesh.seat.container-image-registry.event.removed"
// SubjectKept is where kept is published.
const SubjectKept = "mesh.seat.container-image-registry.event.kept"
// SubjectHeld is where held is published.
const SubjectHeld = "mesh.seat.container-image-registry.event.held"
// SubjectReleased is where released is published.
const SubjectReleased = "mesh.seat.container-image-registry.event.released"
const (
StateHolds = "holds"
StateWindows = "windows"
)
// HoldsBySeatNameDigestKey is the key of one value of the state holds under the form "<seat>.<name>.<digest>".
func HoldsBySeatNameDigestKey(seat, name, digest string) string {
return seat + "." + name + "." + digest
}
// ParseHoldsBySeatNameDigestKey reads the parts of a key of the form "<seat>.<name>.<digest>", in the order of the form; the last result is false for a key of another form.
func ParseHoldsBySeatNameDigestKey(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, ".")
if !found2 || v2 == "" {
return "", "", "", false
}
rest = after2
if rest == "" {
return "", "", "", false
}
v4 := rest
rest = ""
if rest != "" {
return "", "", "", false
}
return v0, v2, v4, true
}
// DecodeHoldsBySeatNameDigestValue reads one value of the state holds under the form "<seat>.<name>.<digest>", refusing a field HoldsBySeatNameDigestValue does not know and any text after the value.
func DecodeHoldsBySeatNameDigestValue(raw []byte) (HoldsBySeatNameDigestValue, error) {
var v HoldsBySeatNameDigestValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// WindowsByCallerKey is the key of one value of the state windows under the form "<caller>".
func WindowsByCallerKey(caller string) string { return caller }
// ParseWindowsByCallerKey reads the parts of a key of the form "<caller>", in the order of the form; the last result is false for a key of another form.
func ParseWindowsByCallerKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeWindowsByCallerValue reads one value of the state windows under the form "<caller>", refusing a field WindowsByCallerValue does not know and any text after the value.
func DecodeWindowsByCallerValue(raw []byte) (WindowsByCallerValue, error) {
var v WindowsByCallerValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// Artifact is one published thing, as every registry event and answer names it.
type Artifact struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Artifact's kind.
const (
ArtifactKindPackage = "package"
ArtifactKindImage = "image"
ArtifactKindBundle = "bundle"
ArtifactKindArchive = "archive"
ArtifactKindUpstream = "upstream"
)
// Hold is the body of held and released.
type Hold struct {
// when, RFC 3339
At string `json:"at,omitempty"`
// the caller the holder proved
By string `json:"by,omitempty"`
// the digest
Digest string `json:"digest"`
// the module holding the seat
Holder string `json:"holder"`
// the name
Name string `json:"name"`
// why
Reason string `json:"reason,omitempty"`
}
// Listed is a type of the contract.
type Listed struct {
// for a manifest keeping one bundle or archive, the digest of that blob: what a reference names it by
Artifact string `json:"artifact,omitempty"`
// the manifest's digest, sha256:<hex>
Digest string `json:"digest"`
// a hold keeps it from retention
Held bool `json:"held"`
// it is an index, naming a manifest per platform
Index bool `json:"index"`
// for an index, the digests of the manifests it names
Platforms []string `json:"platforms,omitempty"`
// its bytes: its own content and every blob it names
Size int64 `json:"size"`
// the tags naming it, none for an untagged one
Tags []string `json:"tags,omitempty"`
}
// Outcome is the body of published, refused and removed.
type Outcome struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// the module holding the seat that said it
Holder string `json:"holder"`
// what it is
Kind string `json:"kind"`
// the Go module path a Go package is fetched under, equal to name for a Go package (go-package-registry's published); empty for every other kind of artifact
Module string `json:"module,omitempty"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// why: a refusal's cause, a removal's (retention, tag-gone, by-hand), or why a removal was kept (shared-digest)
Reason string `json:"reason,omitempty"`
// the reference the seat answers: <registry>/<module>/<artifact>@sha256:<digest>, or <name>@<version> for a package (ADR 0605 §9)
Reference string `json:"reference,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// for kept: the other tags still naming its digest
Tags []string `json:"tags,omitempty"`
// the transfer it ends, when it ended one
Transfer string `json:"transfer,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Outcome's kind.
const (
OutcomeKindPackage = "package"
OutcomeKindImage = "image"
OutcomeKindBundle = "bundle"
OutcomeKindArchive = "archive"
OutcomeKindUpstream = "upstream"
)
// Part is one part of a transfer.
type Part struct {
// the part's digest, sha256:<hex>: an image's layer or config, a package's file, a bundle's blob
Digest string `json:"digest"`
// its size in bytes
Size int64 `json:"size"`
}
// Repository is a type of the contract.
type Repository struct {
// each manifest it holds, by digest
Manifests []Listed `json:"manifests"`
// the repository
Name string `json:"name"`
}
// PublishInput is what publish takes.
type PublishInput struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// every part's digest and size; none when the digest is already held
Parts []Part `json:"parts,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the transfer's name, the caller's own; the same name opens the same transfer again
Transfer string `json:"transfer"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of PublishInput's kind.
const (
PublishInputKindPackage = "package"
PublishInputKindImage = "image"
PublishInputKindBundle = "bundle"
PublishInputKindArchive = "archive"
PublishInputKindUpstream = "upstream"
)
// PublishAnswer is what publish answers.
type PublishAnswer struct {
// the digest is held already: nothing to send; the outcome follows as an event
Held bool `json:"held,omitempty"`
// the digests of the parts the holder lacks, to send by publish-part
Lacks []string `json:"lacks,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartInput is what publish-part takes.
type PublishPartInput struct {
// the chunk's bytes, base64 (at most 760 KiB before encoding)
Data string `json:"data"`
// this chunk is the part's last
Last bool `json:"last"`
// the part's digest
Part string `json:"part"`
// the chunk's place in its part, from 0
Sequence int64 `json:"sequence"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartAnswer is what publish-part answers.
type PublishPartAnswer struct {
// the part is whole and its bytes match its digest
Complete bool `json:"complete,omitempty"`
// the part
Part string `json:"part"`
// the chunks of the part held so far
Received int64 `json:"received,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// VersionsInput is what versions takes.
type VersionsInput struct {
// narrowed to one kind (optional)
Kind string `json:"kind,omitempty"`
// the name
Name string `json:"name"`
}
// VersionsAnswer is what versions answers.
type VersionsAnswer struct {
// the name
Name string `json:"name"`
// newest first
Versions []Artifact `json:"versions"`
}
// RemoveInput is what remove takes.
type RemoveInput struct {
// the digest (for a bundle, archive or copied base)
Digest string `json:"digest,omitempty"`
// the name
Name string `json:"name"`
// why it goes
Reason string `json:"reason"`
// the tag (for a tagged version)
Tag string `json:"tag,omitempty"`
// the version
Version string `json:"version,omitempty"`
}
// The values of RemoveInput's reason.
const (
RemoveInputReasonTagGone = "tag-gone"
RemoveInputReasonRetention = "retention"
)
// RemoveAnswer is what remove answers.
type RemoveAnswer struct {
Artifact *Artifact `json:"artifact,omitempty"`
// it stays whole, its tag and its bytes: the store cannot remove the tag alone while another tag names its digest (reason, tags)
Kept bool `json:"kept,omitempty"`
// why it was kept: shared-digest, another tag names its digest
Reason string `json:"reason,omitempty"`
// it is gone
Removed bool `json:"removed"`
// the other tags still naming its digest, when kept
Tags []string `json:"tags,omitempty"`
}
// The values of RemoveAnswer's reason.
const (
RemoveAnswerReasonSharedDigest = "shared-digest"
)
// MirrorInput is what mirror takes.
type MirrorInput struct {
// its pinned digest, sha256:<hex>
Digest string `json:"digest"`
// the name it is kept under
Name string `json:"name"`
// the outside image's reference
Source string `json:"source"`
}
// MirrorAnswer is what mirror answers.
type MirrorAnswer struct {
// the digest stored
Digest string `json:"digest"`
// the reference the seat answers
Reference string `json:"reference"`
}
// TagsInput is what tags takes.
type TagsInput struct {
// the image
Name string `json:"name"`
}
// TagsAnswerTagsItem is a type of the contract.
type TagsAnswerTagsItem struct {
// its digest
Digest string `json:"digest"`
// the tag
Tag string `json:"tag"`
}
// TagsAnswer is what tags answers.
type TagsAnswer struct {
// the image
Name string `json:"name"`
// every tag
Tags []TagsAnswerTagsItem `json:"tags"`
}
// HoldInput is what hold takes.
type HoldInput struct {
// the digest
Digest string `json:"digest"`
// the name
Name string `json:"name"`
// which of the sweep's rules keeps it
Reason string `json:"reason"`
}
// HoldAnswer is what hold answers.
type HoldAnswer struct {
// it is held
Held bool `json:"held"`
// when the hold began, RFC 3339
Since string `json:"since,omitempty"`
}
// ReleaseInput is what release takes.
type ReleaseInput struct {
// the digest
Digest string `json:"digest"`
// the name
Name string `json:"name"`
// why it is let go
Reason string `json:"reason"`
}
// ReleaseAnswer is what release answers.
type ReleaseAnswer struct {
// a hold was let go; false when there was none
Released bool `json:"released"`
}
// ListInput is what list takes.
type ListInput struct {
// the repository, <module>/<artifact>; every repository of the seat when not given
Name string `json:"name,omitempty"`
}
// ListAnswer is what list answers.
type ListAnswer struct {
// each repository named, in order of its name
Repositories []Repository `json:"repositories"`
}
// PublishedEvent is the body of the event published.
type PublishedEvent = Outcome
// RefusedEvent is the body of the event refused.
type RefusedEvent = Outcome
// RemovedEvent is the body of the event removed.
type RemovedEvent = Outcome
// KeptEvent is the body of the event kept.
type KeptEvent = Outcome
// HeldEvent is the body of the event held.
type HeldEvent = Hold
// ReleasedEvent is the body of the event released.
type ReleasedEvent = Hold
// HoldsBySeatNameDigestValue is one value of the state holds under the key <seat>.<name>.<digest>.
type HoldsBySeatNameDigestValue struct {
By string `json:"by"`
Digest string `json:"digest"`
Kind string `json:"kind"`
Name string `json:"name"`
Seat string `json:"seat"`
// when (RFC 3339 time)
Since string `json:"since"`
Why string `json:"why,omitempty"`
}
// WindowsByCallerValueDroppedItem is a type of the contract.
type WindowsByCallerValueDroppedItem struct {
// when (RFC 3339 time)
At string `json:"at,omitempty"`
By string `json:"by,omitempty"`
Node string `json:"node"`
Why string `json:"why,omitempty"`
}
// WindowsByCallerValue is one value of the state windows under the key <caller>.
type WindowsByCallerValue struct {
// when it last closed (RFC 3339 time)
Closed string `json:"closed,omitempty"`
// retired nodes dropped by hand
Dropped []WindowsByCallerValueDroppedItem `json:"dropped,omitempty"`
// the nodes holding it open
Holding []string `json:"holding,omitempty"`
LastHolding []string `json:"last_holding,omitempty"`
// the caller whose window it is
Name string `json:"name"`
Open bool `json:"open,omitempty"`
// node to when it began to hold
Since map[string]string `json:"since,omitempty"`
// of each node holding the window, why it holds it
Why map[string]string `json:"why,omitempty"`
}
@@ -1,82 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package containerimageregistry
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/container-image-registry/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "published on the seat's subject", subject: "mesh.seat.container-image-registry.event.published", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.container-image-registry\\.event\\.published$")},
{name: "refused on the seat's subject", subject: "mesh.seat.container-image-registry.event.refused", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RefusedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.container-image-registry\\.event\\.refused$")},
{name: "removed on the seat's subject", subject: "mesh.seat.container-image-registry.event.removed", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RemovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.container-image-registry\\.event\\.removed$")},
{name: "kept on the seat's subject: a tagged version sharing its digest stays, naming the tags on it", subject: "mesh.seat.container-image-registry.event.kept", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reason\":\"shared-digest\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"reason\":\"shared-digest\",\"reference\":\"container-image-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}",
decode: func(b []byte) (any, error) { var v KeptEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.container-image-registry\\.event\\.kept$")},
{name: "held on the seat's subject", subject: "mesh.seat.container-image-registry.event.held", given: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}", wire: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}",
decode: func(b []byte) (any, error) { var v HeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.container-image-registry\\.event\\.held$")},
{name: "released on the seat's subject", subject: "mesh.seat.container-image-registry.event.released", given: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}", wire: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}",
decode: func(b []byte) (any, error) { var v ReleasedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.container-image-registry\\.event\\.released$")},
{name: "a hold", subject: "", given: "{\"by\":\"operator@shanks\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"base\",\"name\":\"base\",\"seat\":\"container-image-registry\",\"since\":\"2026-11-05T10:00:00Z\"}", wire: "{\"by\":\"operator@shanks\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"base\",\"name\":\"base\",\"seat\":\"container-image-registry\",\"since\":\"2026-11-05T10:00:00Z\"}",
decode: func(b []byte) (any, error) {
var v HoldsBySeatNameDigestValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "an open window", subject: "", given: "{\"holding\":[\"ace\"],\"name\":\"mesh-delivery-builder\",\"open\":true,\"since\":{\"ace\":\"2026-11-05T10:00:00Z\"}}", wire: "{\"holding\":[\"ace\"],\"name\":\"mesh-delivery-builder\",\"open\":true,\"since\":{\"ace\":\"2026-11-05T10:00:00Z\"}}",
decode: func(b []byte) (any, error) { var v WindowsByCallerValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "publish opens a transfer", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a field the reader does not know is dropped", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"image\",\"later\":{\"x\":1},\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"image\",\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "publish answers what it lacks", subject: "", given: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}", wire: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a chunk of a part", subject: "", given: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}", wire: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishPartInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the versions held", subject: "", given: "{\"name\":\"mesh-sdk\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"mesh-sdk\",\"version\":\"0.1.19\"}]}", wire: "{\"name\":\"mesh-sdk\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"mesh-sdk\",\"version\":\"0.1.19\"}]}",
decode: func(b []byte) (any, error) { var v VersionsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a release of what is not held answers released false", subject: "", given: "{\"released\":false}", wire: "{\"released\":false}",
decode: func(b []byte) (any, error) { var v ReleaseAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a tagged version sharing its digest with another tag is kept, not removed", subject: "", given: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}", wire: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}",
decode: func(b []byte) (any, error) { var v RemoveAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers an index with its platforms, its tag and its hold", subject: "", given: "{\"repositories\":[{\"manifests\":[{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":false,\"index\":true,\"platforms\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"size\":2048,\"tags\":[\"3\"]},{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"held\":false,\"index\":false,\"size\":1024}],\"name\":\"mail/server\"}]}", wire: "{\"repositories\":[{\"manifests\":[{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":false,\"index\":true,\"platforms\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"size\":2048,\"tags\":[\"3\"]},{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"held\":false,\"index\":false,\"size\":1024}],\"name\":\"mail/server\"}]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/containerimageregistry
go 1.26.0
@@ -1,262 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package gopackageregistry is the contract of the seat "go-package-registry", defined whole (seats/go-package-registry/seat.json): The mesh's Go modules: Go's module proxy protocol's read side, and publishing over the bus.
package gopackageregistry
// Seat is the seat's name.
const Seat = "go-package-registry"
const (
VerbPublish = "publish"
VerbPublishPart = "publish-part"
VerbVersions = "versions"
VerbRemove = "remove"
)
const (
EventPublished = "published"
EventRefused = "refused"
EventRemoved = "removed"
EventKept = "kept"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventPublished, EventRefused, EventRemoved, EventKept}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "go-package-registry.events"
FamilyMaxAgeDays = 7
)
// SubjectPublished is where published is published.
const SubjectPublished = "mesh.seat.go-package-registry.event.published"
// SubjectRefused is where refused is published.
const SubjectRefused = "mesh.seat.go-package-registry.event.refused"
// SubjectRemoved is where removed is published.
const SubjectRemoved = "mesh.seat.go-package-registry.event.removed"
// SubjectKept is where kept is published.
const SubjectKept = "mesh.seat.go-package-registry.event.kept"
// Artifact is one published thing, as every registry event and answer names it.
type Artifact struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Artifact's kind.
const (
ArtifactKindPackage = "package"
ArtifactKindImage = "image"
ArtifactKindBundle = "bundle"
ArtifactKindArchive = "archive"
ArtifactKindUpstream = "upstream"
)
// Outcome is the body of published, refused and removed.
type Outcome struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// the module holding the seat that said it
Holder string `json:"holder"`
// what it is
Kind string `json:"kind"`
// the Go module path a Go package is fetched under, equal to name for a Go package (go-package-registry's published); empty for every other kind of artifact
Module string `json:"module,omitempty"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// why: a refusal's cause, a removal's (retention, tag-gone, by-hand), or why a removal was kept (shared-digest)
Reason string `json:"reason,omitempty"`
// the reference the seat answers: <registry>/<module>/<artifact>@sha256:<digest>, or <name>@<version> for a package (ADR 0605 §9)
Reference string `json:"reference,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// for kept: the other tags still naming its digest
Tags []string `json:"tags,omitempty"`
// the transfer it ends, when it ended one
Transfer string `json:"transfer,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Outcome's kind.
const (
OutcomeKindPackage = "package"
OutcomeKindImage = "image"
OutcomeKindBundle = "bundle"
OutcomeKindArchive = "archive"
OutcomeKindUpstream = "upstream"
)
// Part is one part of a transfer.
type Part struct {
// the part's digest, sha256:<hex>: an image's layer or config, a package's file, a bundle's blob
Digest string `json:"digest"`
// its size in bytes
Size int64 `json:"size"`
}
// PublishInput is what publish takes.
type PublishInput struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// every part's digest and size; none when the digest is already held
Parts []Part `json:"parts,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the transfer's name, the caller's own; the same name opens the same transfer again
Transfer string `json:"transfer"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of PublishInput's kind.
const (
PublishInputKindPackage = "package"
PublishInputKindImage = "image"
PublishInputKindBundle = "bundle"
PublishInputKindArchive = "archive"
PublishInputKindUpstream = "upstream"
)
// PublishAnswer is what publish answers.
type PublishAnswer struct {
// the digest is held already: nothing to send; the outcome follows as an event
Held bool `json:"held,omitempty"`
// the digests of the parts the holder lacks, to send by publish-part
Lacks []string `json:"lacks,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartInput is what publish-part takes.
type PublishPartInput struct {
// the chunk's bytes, base64 (at most 760 KiB before encoding)
Data string `json:"data"`
// this chunk is the part's last
Last bool `json:"last"`
// the part's digest
Part string `json:"part"`
// the chunk's place in its part, from 0
Sequence int64 `json:"sequence"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartAnswer is what publish-part answers.
type PublishPartAnswer struct {
// the part is whole and its bytes match its digest
Complete bool `json:"complete,omitempty"`
// the part
Part string `json:"part"`
// the chunks of the part held so far
Received int64 `json:"received,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// VersionsInput is what versions takes.
type VersionsInput struct {
// narrowed to one kind (optional)
Kind string `json:"kind,omitempty"`
// the name
Name string `json:"name"`
}
// VersionsAnswer is what versions answers.
type VersionsAnswer struct {
// the name
Name string `json:"name"`
// newest first
Versions []Artifact `json:"versions"`
}
// RemoveInput is what remove takes.
type RemoveInput struct {
// the digest (for a bundle, archive or copied base)
Digest string `json:"digest,omitempty"`
// the name
Name string `json:"name"`
// why it goes
Reason string `json:"reason"`
// the tag (for a tagged version)
Tag string `json:"tag,omitempty"`
// the version
Version string `json:"version,omitempty"`
}
// The values of RemoveInput's reason.
const (
RemoveInputReasonTagGone = "tag-gone"
RemoveInputReasonRetention = "retention"
)
// RemoveAnswer is what remove answers.
type RemoveAnswer struct {
Artifact *Artifact `json:"artifact,omitempty"`
// it stays whole, its tag and its bytes: the store cannot remove the tag alone while another tag names its digest (reason, tags)
Kept bool `json:"kept,omitempty"`
// why it was kept: shared-digest, another tag names its digest
Reason string `json:"reason,omitempty"`
// it is gone
Removed bool `json:"removed"`
// the other tags still naming its digest, when kept
Tags []string `json:"tags,omitempty"`
}
// The values of RemoveAnswer's reason.
const (
RemoveAnswerReasonSharedDigest = "shared-digest"
)
// PublishedEvent is the body of the event published.
type PublishedEvent = Outcome
// RefusedEvent is the body of the event refused.
type RefusedEvent = Outcome
// RemovedEvent is the body of the event removed.
type RemovedEvent = Outcome
// KeptEvent is the body of the event kept.
type KeptEvent = Outcome
// GoPackageRegistryForm is the form of the provision go-package-registry.
type GoPackageRegistryForm struct {
// the read side's address
URL string `json:"url"`
}
@@ -1,66 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package gopackageregistry
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/go-package-registry/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "published on the seat's subject", subject: "mesh.seat.go-package-registry.event.published", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"module\":\"git.novox.be/novox/mesh-sdk/go\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"module\":\"git.novox.be/novox/mesh-sdk/go\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.go-package-registry\\.event\\.published$")},
{name: "refused on the seat's subject", subject: "mesh.seat.go-package-registry.event.refused", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reason\":\"retention\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reason\":\"retention\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RefusedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.go-package-registry\\.event\\.refused$")},
{name: "removed on the seat's subject", subject: "mesh.seat.go-package-registry.event.removed", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reason\":\"retention\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reason\":\"retention\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RemovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.go-package-registry\\.event\\.removed$")},
{name: "kept on the seat's subject: a tagged version sharing its digest stays, naming the tags on it", subject: "mesh.seat.go-package-registry.event.kept", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reason\":\"shared-digest\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"reason\":\"shared-digest\",\"reference\":\"git.novox.be/novox/mesh-sdk/go@0.1.19\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}",
decode: func(b []byte) (any, error) { var v KeptEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.go-package-registry\\.event\\.kept$")},
{name: "publish opens a transfer", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a field the reader does not know is dropped", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"later\":{\"x\":1},\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "publish answers what it lacks", subject: "", given: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}", wire: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a chunk of a part", subject: "", given: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}", wire: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishPartInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the versions held", subject: "", given: "{\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"version\":\"0.1.19\"}]}", wire: "{\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"git.novox.be/novox/mesh-sdk/go\",\"version\":\"0.1.19\"}]}",
decode: func(b []byte) (any, error) { var v VersionsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a tagged version sharing its digest with another tag is kept, not removed", subject: "", given: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}", wire: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}",
decode: func(b []byte) (any, error) { var v RemoveAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/gopackageregistry
go 1.26.0
@@ -1,129 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package meshartifactsweep is the contract of the seat "mesh-artifact-sweep", defined whole (seats/mesh-artifact-sweep/seat.json): no description.
package meshartifactsweep
import "time"
// Seat is the seat's name.
const Seat = "mesh-artifact-sweep"
const (
VerbArtifacts = "artifacts"
VerbHeld = "held"
VerbCollect = "collect"
VerbMirrors = "mirrors"
VerbImages = "images"
)
const (
EventArtifactsGone = "artifacts-gone"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbArtifacts, VerbHeld, VerbCollect, VerbMirrors, VerbImages}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventArtifactsGone}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "mesh-artifact-sweep.events"
FamilyMaxAgeDays = 7
)
// SubjectArtifactsGone is where artifacts-gone is published.
const SubjectArtifactsGone = "mesh.seat.mesh-artifact-sweep.event.artifacts-gone"
// ArtifactsGone is the body of artifacts-gone.
type ArtifactsGone struct {
// when the sweep found it
At *time.Time `json:"at,omitempty"`
// artifacts-gone
Event string `json:"event"`
// the key's fingerprint
Fingerprint string `json:"fingerprint"`
// every reference of the key the store does not hold, sorted
Gone []string `json:"gone"`
// the builder's done key
Key string `json:"key,omitempty"`
// the module whose builder's key names a gone artifact
Module string `json:"module"`
}
// ArtifactsInput is what artifacts takes.
type ArtifactsInput struct {
// "true": list the collected references too (counted always)
Collected string `json:"collected,omitempty"`
// only this repository's references, as <module>/<artifact> (the counts stay whole)
Repository string `json:"repository,omitempty"`
}
// The values of ArtifactsInput's collected.
const (
ArtifactsInputCollectedTrue = "true"
ArtifactsInputCollectedFalse = "false"
)
// ArtifactsAnswer is what artifacts answers.
type ArtifactsAnswer = map[string]any
// HeldInput is what held takes.
type HeldInput struct {
// the artifacts' references, artifact-store://<module>/<artifact>/blobs/sha256:<hex>: a list, or one text separated by commas
References []string `json:"references"`
}
// HeldAnswer is what held answers.
type HeldAnswer struct {
// the references the store answered 404 for
Gone []string `json:"gone"`
// the references the store holds
Held []string `json:"held"`
// the store asked, host and port
Store string `json:"store,omitempty"`
// a reference the store could not be asked about, to why
Unknown map[string]string `json:"unknown,omitempty"`
}
// CollectInput is what collect takes.
type CollectInput struct {
// "true": let go of what is eligible (needs why); without it nothing is done
Confirm string `json:"confirm,omitempty"`
// let go of at most this many (500 by default, at most 5000)
Most string `json:"most,omitempty"`
// with confirm: why, required and recorded
Why string `json:"why,omitempty"`
}
// The values of CollectInput's confirm.
const (
CollectInputConfirmTrue = "true"
CollectInputConfirmFalse = "false"
)
// CollectAnswer is what collect answers.
type CollectAnswer = map[string]any
// MirrorsInput is what mirrors takes.
type MirrorsInput struct {
}
// MirrorsAnswer is what mirrors answers.
type MirrorsAnswer = map[string]any
// ImagesInput is what images takes.
type ImagesInput struct {
// the machine's name
Node string `json:"node"`
}
// ImagesAnswer is what images answers.
type ImagesAnswer = map[string]any
// ArtifactsGoneEvent is the body of the event artifacts-gone.
type ArtifactsGoneEvent = ArtifactsGone
@@ -1,54 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package meshartifactsweep
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/mesh-artifact-sweep/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "artifacts-gone on the seat's subject", subject: "mesh.seat.mesh-artifact-sweep.event.artifacts-gone", given: "{\"at\":\"2026-11-05T15:04:05Z\",\"event\":\"artifacts-gone\",\"fingerprint\":\"f1\",\"gone\":[\"artifact-store://ca-trust/archive/blobs/sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"artifact-store://ca-trust/archive/blobs/sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"key\":\"ca-trust.archive.f1\",\"module\":\"ca-trust\"}", wire: "{\"at\":\"2026-11-05T15:04:05Z\",\"event\":\"artifacts-gone\",\"fingerprint\":\"f1\",\"gone\":[\"artifact-store://ca-trust/archive/blobs/sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"artifact-store://ca-trust/archive/blobs/sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"key\":\"ca-trust.archive.f1\",\"module\":\"ca-trust\"}",
decode: func(b []byte) (any, error) { var v ArtifactsGoneEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-artifact-sweep\\.event\\.artifacts-gone$")},
{name: "held asks the references", subject: "", given: "{\"references\":[\"artifact-store://ca-trust/archive/blobs/sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"artifact-store://ca-trust/archive/blobs/sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"artifact-store://ca-trust/archive/blobs/sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\"]}", wire: "{\"references\":[\"artifact-store://ca-trust/archive/blobs/sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"artifact-store://ca-trust/archive/blobs/sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"artifact-store://ca-trust/archive/blobs/sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\"]}",
decode: func(b []byte) (any, error) { var v HeldInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "held answers held, gone and unknown", subject: "", given: "{\"gone\":[\"artifact-store://ca-trust/archive/blobs/sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"held\":[\"artifact-store://ca-trust/archive/blobs/sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"],\"store\":\"store.test:5100\",\"unknown\":{\"artifact-store://ca-trust/archive/blobs/sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\":\"the store answered 503\"}}", wire: "{\"gone\":[\"artifact-store://ca-trust/archive/blobs/sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"held\":[\"artifact-store://ca-trust/archive/blobs/sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"],\"store\":\"store.test:5100\",\"unknown\":{\"artifact-store://ca-trust/archive/blobs/sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\":\"the store answered 503\"}}",
decode: func(b []byte) (any, error) { var v HeldAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "held answers with nothing unknown", subject: "", given: "{\"gone\":[],\"held\":[],\"store\":\"store.test:5100\"}", wire: "{\"gone\":[],\"held\":[],\"store\":\"store.test:5100\"}",
decode: func(b []byte) (any, error) { var v HeldAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/meshartifactsweep
go 1.26.0
-652
View File
@@ -1,652 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package meshcatalog is the contract of the seat "mesh-catalog", defined whole (seats/mesh-catalog/seat.json): The catalog of the mesh: every module the trunk holds with its manifest, fingerprint and verdict, the packages published, and the seat list (ADR 0636 §1, §4).
package meshcatalog
import (
"bytes"
"encoding/json"
"errors"
"strings"
"time"
)
// Seat is the seat's name.
const Seat = "mesh-catalog"
const (
VerbModules = "modules"
VerbModule = "module"
VerbProvides = "provides"
VerbDependents = "dependents"
VerbSeatDefinitions = "seat-definitions"
)
const (
EventSeatDefinitionChanged = "seat-definition-changed"
EventSeatDefinitionRemoved = "seat-definition-removed"
EventManifestAccepted = "manifest-accepted"
EventManifestRefused = "manifest-refused"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbModules, VerbModule, VerbProvides, VerbDependents, VerbSeatDefinitions}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventSeatDefinitionChanged, EventSeatDefinitionRemoved, EventManifestAccepted, EventManifestRefused}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "mesh-catalog.events"
FamilyMaxAgeDays = 7
)
// SubjectSeatDefinitionChanged is where seat-definition-changed is published.
const SubjectSeatDefinitionChanged = "mesh.seat.mesh-catalog.event.seat-definition-changed"
// SubjectSeatDefinitionRemoved is where seat-definition-removed is published.
const SubjectSeatDefinitionRemoved = "mesh.seat.mesh-catalog.event.seat-definition-removed"
// SubjectManifestAccepted is where manifest-accepted is published.
const SubjectManifestAccepted = "mesh.seat.mesh-catalog.event.manifest-accepted"
// SubjectManifestRefused is where manifest-refused is published.
const SubjectManifestRefused = "mesh.seat.mesh-catalog.event.manifest-refused"
const (
StateManifests = "manifests"
StateModules = "modules"
StateCandidates = "candidates"
StateVerdicts = "verdicts"
StatePredefined = "predefined"
StatePackages = "packages"
)
// ManifestsByDigestKey is the key of one value of the state manifests under the form "<digest>".
func ManifestsByDigestKey(digest string) string { return digest }
// ParseManifestsByDigestKey reads the parts of a key of the form "<digest>", in the order of the form; the last result is false for a key of another form.
func ParseManifestsByDigestKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeManifestsByDigestValue reads one value of the state manifests under the form "<digest>", refusing a field ManifestsByDigestValue does not know and any text after the value.
func DecodeManifestsByDigestValue(raw []byte) (ManifestsByDigestValue, error) {
var v ManifestsByDigestValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// ModulesByModuleKey is the key of one value of the state modules under the form "<module>".
func ModulesByModuleKey(module string) string { return module }
// ParseModulesByModuleKey reads the parts of a key of the form "<module>", in the order of the form; the last result is false for a key of another form.
func ParseModulesByModuleKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeModulesByModuleValue reads one value of the state modules under the form "<module>", refusing a field ModulesByModuleValue does not know and any text after the value.
func DecodeModulesByModuleValue(raw []byte) (ModulesByModuleValue, error) {
var v ModulesByModuleValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// CandidatesByGroupKey is the key of one value of the state candidates under the form "<group>".
func CandidatesByGroupKey(group string) string { return group }
// ParseCandidatesByGroupKey reads the parts of a key of the form "<group>", in the order of the form; the last result is false for a key of another form.
func ParseCandidatesByGroupKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeCandidatesByGroupValue reads one value of the state candidates under the form "<group>", refusing a field CandidatesByGroupValue does not know and any text after the value.
func DecodeCandidatesByGroupValue(raw []byte) (CandidatesByGroupValue, error) {
var v CandidatesByGroupValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// VerdictsByDigestKey is the key of one value of the state verdicts under the form "<digest>".
func VerdictsByDigestKey(digest string) string { return digest }
// ParseVerdictsByDigestKey reads the parts of a key of the form "<digest>", in the order of the form; the last result is false for a key of another form.
func ParseVerdictsByDigestKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeVerdictsByDigestValue reads one value of the state verdicts under the form "<digest>", refusing a field VerdictsByDigestValue does not know and any text after the value.
func DecodeVerdictsByDigestValue(raw []byte) (VerdictsByDigestValue, error) {
var v VerdictsByDigestValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PredefinedByListKey is the key of one value of the state predefined under the form "list".
func PredefinedByListKey() string { return "list" }
// ParsePredefinedByListKey reads the parts of a key of the form "list", in the order of the form; the last result is false for a key of another form.
func ParsePredefinedByListKey(key string) bool {
rest := key
if !strings.HasPrefix(rest, "list") {
return false
}
rest = rest[4:]
if rest != "" {
return false
}
return true
}
// DecodePredefinedByListValue reads one value of the state predefined under the form "list", refusing a field PredefinedByListValue does not know and any text after the value.
func DecodePredefinedByListValue(raw []byte) (PredefinedByListValue, error) {
var v PredefinedByListValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PackagesByModuleKey is the key of one value of the state packages under the form "<module>".
func PackagesByModuleKey(module string) string { return module }
// ParsePackagesByModuleKey reads the parts of a key of the form "<module>", in the order of the form; the last result is false for a key of another form.
func ParsePackagesByModuleKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodePackagesByModuleValue reads one value of the state packages under the form "<module>", refusing a field PackagesByModuleValue does not know and any text after the value.
func DecodePackagesByModuleValue(raw []byte) (PackagesByModuleValue, error) {
var v PackagesByModuleValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PackagesByPackageSeriesKey is the key of one value of the state packages under the form "<package>.<series>".
func PackagesByPackageSeriesKey(packagePart, series string) string { return packagePart + "." + series }
// ParsePackagesByPackageSeriesKey reads the parts of a key of the form "<package>.<series>", in the order of the form; the last result is false for a key of another form.
func ParsePackagesByPackageSeriesKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodePackagesByPackageSeriesValue reads one value of the state packages under the form "<package>.<series>", refusing a field PackagesByPackageSeriesValue does not know and any text after the value.
func DecodePackagesByPackageSeriesValue(raw []byte) (PackagesByPackageSeriesValue, error) {
var v PackagesByPackageSeriesValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// ToolchainUsed is a toolchain a fingerprint was computed with (ADR 0405 clause 7).
type ToolchainUsed struct {
Language string `json:"language"`
// the build module's recipe version
Recipe string `json:"recipe"`
// the installed toolchain's version
Version string `json:"version"`
}
// ModulesInput is what modules takes.
type ModulesInput struct {
}
// ModulesAnswerModulesItem is a type of the contract.
type ModulesAnswerModulesItem struct {
// the merge commit it was last changed at
Commit string `json:"commit"`
// its fingerprint (src2: and 64 hex digits); absent when it has none
Fp string `json:"fp,omitempty"`
Module string `json:"module"`
// why it has none
None string `json:"none,omitempty"`
// the module's directory in its repository, '.' for a root
Path string `json:"path,omitempty"`
Repository string `json:"repository"`
}
// ModulesAnswer is what modules answers.
type ModulesAnswer struct {
Modules []ModulesAnswerModulesItem `json:"modules"`
}
// ModuleInput is what module takes.
type ModuleInput struct {
// the module's name
Module string `json:"module"`
}
// ModuleAnswerModule is a type of the contract.
type ModuleAnswerModule struct {
// the merge commit it was last changed at
Commit string `json:"commit"`
// its fingerprint (src2: and 64 hex digits); absent when it has none
Fp string `json:"fp,omitempty"`
// the module's manifest as the trunk holds it
Manifest map[string]any `json:"manifest,omitempty"`
Module string `json:"module"`
// why it has none
None string `json:"none,omitempty"`
// the module's directory in its repository, '.' for a root
Path string `json:"path,omitempty"`
Repository string `json:"repository"`
}
// ModuleAnswer is what module answers.
type ModuleAnswer struct {
Module ModuleAnswerModule `json:"module"`
}
// ProvidesInput is what provides takes.
type ProvidesInput struct {
// the provision, such as postgres-database
Provision string `json:"provision"`
}
// ProvidesAnswer is what provides answers.
type ProvidesAnswer = map[string]any
// DependentsInput is what dependents takes.
type DependentsInput struct {
// the module's name
Module string `json:"module"`
}
// DependentsAnswer is what dependents answers.
type DependentsAnswer = map[string]any
// SeatDefinitionsInput is what seat-definitions takes.
type SeatDefinitionsInput struct {
// the seat's name; none lists every trunk seat
Seat string `json:"seat,omitempty"`
}
// SeatDefinitionsAnswerEntry is a type of the contract.
type SeatDefinitionsAnswerEntry struct {
// the definition, resolved with the parts it includes
Definition map[string]any `json:"definition,omitempty"`
Digest string `json:"digest"`
Seat string `json:"seat"`
// trunk
Source string `json:"source"`
// why the definition could not be read, when it could not
Unparsed string `json:"unparsed,omitempty"`
}
// SeatDefinitionsAnswerSeatsItem is a type of the contract.
type SeatDefinitionsAnswerSeatsItem struct {
Digest string `json:"digest"`
Seat string `json:"seat"`
// trunk
Source string `json:"source"`
}
// SeatDefinitionsAnswer is what seat-definitions answers.
type SeatDefinitionsAnswer struct {
Entry *SeatDefinitionsAnswerEntry `json:"entry,omitempty"`
Found bool `json:"found,omitempty"`
Revision int64 `json:"revision,omitempty"`
Seat string `json:"seat,omitempty"`
Seats []SeatDefinitionsAnswerSeatsItem `json:"seats,omitempty"`
}
// SeatDefinitionChangedEvent is the body of the event seat-definition-changed.
type SeatDefinitionChangedEvent struct {
Digest string `json:"digest"`
Seat string `json:"seat"`
// trunk
Source string `json:"source"`
}
// SeatDefinitionRemovedEvent is the body of the event seat-definition-removed.
type SeatDefinitionRemovedEvent struct {
Seat string `json:"seat"`
}
// ManifestAcceptedEventBusStateItem is a type of the contract.
type ManifestAcceptedEventBusStateItem struct {
Configuration map[string]any `json:"configuration,omitempty"`
Name string `json:"name"`
Options map[string]any `json:"options,omitempty"`
Storage string `json:"storage"`
Template string `json:"template,omitempty"`
Types []map[string]any `json:"types,omitempty"`
}
// ManifestAcceptedEvent is the body of the event manifest-accepted.
type ManifestAcceptedEvent struct {
BusState []ManifestAcceptedEventBusStateItem `json:"bus-state"`
Digest string `json:"digest"`
Judge string `json:"judge"`
Module string `json:"module"`
// the indexer's revision of the verdict it says; a reader asks its first view again on a gap in it; zero from an indexer that does not say it
Revision int64 `json:"revision,omitempty"`
V int64 `json:"v"`
}
// ManifestRefusedEvent is the body of the event manifest-refused.
type ManifestRefusedEvent struct {
Digest string `json:"digest"`
Judge string `json:"judge"`
Module string `json:"module"`
Problems []string `json:"problems"`
// the indexer's revision of the verdict it says; a reader asks its first view again on a gap in it; zero from an indexer that does not say it
Revision int64 `json:"revision,omitempty"`
V int64 `json:"v"`
}
// ManifestsByDigestValue is one value of the state manifests under the key <digest>.
type ManifestsByDigestValue struct {
// the manifest, UTF-8 JSON text
Manifest string `json:"manifest"`
Module string `json:"module"`
// the layout version
V int64 `json:"v,omitempty"`
}
// ModulesByModuleValueInputs2 is a type of the contract.
type ModulesByModuleValueInputs2 struct {
Bases []string `json:"bases,omitempty"`
Builder string `json:"builder,omitempty"`
Contexts map[string]string `json:"contexts,omitempty"`
ImportForm string `json:"import-form,omitempty"`
Imports []string `json:"imports,omitempty"`
Locks map[string]string `json:"locks,omitempty"`
Packages []string `json:"packages,omitempty"`
Paths map[string]string `json:"paths,omitempty"`
Tree string `json:"tree"`
}
// ModulesByModuleValue is one value of the state modules under the key <module>.
type ModulesByModuleValue struct {
Commit string `json:"commit"`
// the old-form fingerprint
Fp string `json:"fp,omitempty"`
FpSrc int64 `json:"fp-src,omitempty"`
// src2: fingerprint
Fp2 string `json:"fp2,omitempty"`
Inputs2 *ModulesByModuleValueInputs2 `json:"inputs2,omitempty"`
// manifest digest
Manifest string `json:"manifest,omitempty"`
Needs []string `json:"needs,omitempty"`
None string `json:"none,omitempty"`
// why it has none
None2 string `json:"none2,omitempty"`
Packages map[string]string `json:"packages,omitempty"`
Path string `json:"path,omitempty"`
Paths map[string][]string `json:"paths,omitempty"`
Problems []string `json:"problems,omitempty"`
Repository string `json:"repository"`
// the source revision
Src int64 `json:"src,omitempty"`
// by language: the toolchain FP2 was computed with
Toolchains map[string]ToolchainUsed `json:"toolchains,omitempty"`
Unknown []string `json:"unknown,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Verdict string `json:"verdict,omitempty"`
Warnings []string `json:"warnings,omitempty"`
}
// CandidatesByGroupValuePullsItemFpsValue is a type of the contract.
type CandidatesByGroupValuePullsItemFpsValue struct {
Fp2 string `json:"fp2,omitempty"`
Manifest string `json:"manifest,omitempty"`
None2 string `json:"none2,omitempty"`
Packages map[string]string `json:"packages,omitempty"`
Paths map[string]string `json:"paths,omitempty"`
}
// CandidatesByGroupValuePullsItem is a type of the contract.
type CandidatesByGroupValuePullsItem struct {
Fps map[string]CandidatesByGroupValuePullsItemFpsValue `json:"fps,omitempty"`
Head string `json:"head"`
Modules []string `json:"modules"`
Number int64 `json:"number"`
Repository string `json:"repository"`
}
// CandidatesByGroupValue is one value of the state candidates under the key <group>.
type CandidatesByGroupValue struct {
// the source revision it is read on
Base int64 `json:"base"`
Fpset string `json:"fpset,omitempty"`
Group string `json:"group"`
Heads string `json:"heads"`
Pulls []CandidatesByGroupValuePullsItem `json:"pulls"`
// the layout version
V int64 `json:"v,omitempty"`
}
// VerdictsByDigestValue is one value of the state verdicts under the key <digest>.
type VerdictsByDigestValue struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Judge string `json:"judge,omitempty"`
Module string `json:"module"`
Problems []string `json:"problems,omitempty"`
State string `json:"state"`
Unknown []string `json:"unknown,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Warnings []string `json:"warnings,omitempty"`
}
// PredefinedByListValue is one value of the state predefined under the key list.
type PredefinedByListValue struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Commit string `json:"commit"`
// the foundation's predefined list as kept
List any `json:"list"`
// the layout version
V int64 `json:"v,omitempty"`
}
// PackagesByModuleValuePackagesItem is a type of the contract.
type PackagesByModuleValuePackagesItem struct {
Digest string `json:"digest"`
Package string `json:"package"`
}
// PackagesByModuleValue is one value of the state packages under the key <module>.
type PackagesByModuleValue struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Commit string `json:"commit"`
Dir string `json:"dir,omitempty"`
// the Go module path
Module string `json:"module"`
Packages []PackagesByModuleValuePackagesItem `json:"packages"`
Repository string `json:"repository"`
// digest of go.mod and go.sum
Requires string `json:"requires,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
}
// PackagesByPackageSeriesValueNewestContentsPackagesItem is a type of the contract.
type PackagesByPackageSeriesValueNewestContentsPackagesItem struct {
Digest string `json:"digest"`
Package string `json:"package"`
}
// PackagesByPackageSeriesValueNewestContents is a type of the contract.
type PackagesByPackageSeriesValueNewestContents struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Commit string `json:"commit"`
Dir string `json:"dir,omitempty"`
// the Go module path
Module string `json:"module"`
Packages []PackagesByPackageSeriesValueNewestContentsPackagesItem `json:"packages"`
Repository string `json:"repository"`
// digest of go.mod and go.sum
Requires string `json:"requires,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
}
// PackagesByPackageSeriesValueNewest is a type of the contract.
type PackagesByPackageSeriesValueNewest struct {
Commit string `json:"commit,omitempty"`
Contents *PackagesByPackageSeriesValueNewestContents `json:"contents,omitempty"`
Digest string `json:"digest,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
Version string `json:"version"`
}
// PackagesByPackageSeriesValueNumberedContentsPackagesItem is a type of the contract.
type PackagesByPackageSeriesValueNumberedContentsPackagesItem struct {
Digest string `json:"digest"`
Package string `json:"package"`
}
// PackagesByPackageSeriesValueNumberedContents is a type of the contract.
type PackagesByPackageSeriesValueNumberedContents struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Commit string `json:"commit"`
Dir string `json:"dir,omitempty"`
// the Go module path
Module string `json:"module"`
Packages []PackagesByPackageSeriesValueNumberedContentsPackagesItem `json:"packages"`
Repository string `json:"repository"`
// digest of go.mod and go.sum
Requires string `json:"requires,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
}
// PackagesByPackageSeriesValueNumbered is a type of the contract.
type PackagesByPackageSeriesValueNumbered struct {
Commit string `json:"commit,omitempty"`
Contents *PackagesByPackageSeriesValueNumberedContents `json:"contents,omitempty"`
Digest string `json:"digest,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
Version string `json:"version"`
}
// PackagesByPackageSeriesValue is one value of the state packages under the key <package>.<series>.
type PackagesByPackageSeriesValue struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
GoModule string `json:"go-module,omitempty"`
Name string `json:"name"`
Newest *PackagesByPackageSeriesValueNewest `json:"newest,omitempty"`
Numbered *PackagesByPackageSeriesValueNumbered `json:"numbered,omitempty"`
Package string `json:"package,omitempty"`
Seat string `json:"seat,omitempty"`
Series string `json:"series"`
// the layout version
V int64 `json:"v,omitempty"`
}
@@ -1,70 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package meshcatalog
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/mesh-catalog/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a manifest (xclip, read through mesh-catalog.module)", subject: "", given: "{\"manifest\":\"{\\\"build\\\":{\\\"artifacts\\\":[{\\\"binary\\\":\\\"xclip-tools\\\",\\\"from\\\":\\\"cmd/xclip-tools\\\",\\\"kind\\\":\\\"bundle\\\",\\\"language\\\":\\\"go\\\",\\\"loads\\\":[\\\"xclip-tools\\\"],\\\"name\\\":\\\"tools\\\",\\\"system\\\":\\\"arch\\\"}]},\\\"capabilities\\\":[\\\"package-manager\\\"],\\\"module\\\":\\\"xclip\\\",\\\"resources\\\":[{\\\"id\\\":\\\"package\\\",\\\"package\\\":\\\"xclip\\\",\\\"type\\\":\\\"package\\\"}],\\\"tools\\\":[\\\"xclip_copy\\\",\\\"xclip_paste\\\",\\\"xclip_targets\\\",\\\"xclip_session\\\"],\\\"version\\\":\\\"1\\\"}\",\"module\":\"xclip\",\"v\":1}", wire: "{\"manifest\":\"{\\\"build\\\":{\\\"artifacts\\\":[{\\\"binary\\\":\\\"xclip-tools\\\",\\\"from\\\":\\\"cmd/xclip-tools\\\",\\\"kind\\\":\\\"bundle\\\",\\\"language\\\":\\\"go\\\",\\\"loads\\\":[\\\"xclip-tools\\\"],\\\"name\\\":\\\"tools\\\",\\\"system\\\":\\\"arch\\\"}]},\\\"capabilities\\\":[\\\"package-manager\\\"],\\\"module\\\":\\\"xclip\\\",\\\"resources\\\":[{\\\"id\\\":\\\"package\\\",\\\"package\\\":\\\"xclip\\\",\\\"type\\\":\\\"package\\\"}],\\\"tools\\\":[\\\"xclip_copy\\\",\\\"xclip_paste\\\",\\\"xclip_targets\\\",\\\"xclip_session\\\"],\\\"version\\\":\\\"1\\\"}\",\"module\":\"xclip\",\"v\":1}",
decode: func(b []byte) (any, error) { var v ManifestsByDigestValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a module (xclip, read through mesh-catalog.modules; the inputs and toolchains no tool reads are not here)", subject: "", given: "{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp2\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\",\"v\":1}", wire: "{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp2\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\",\"v\":1}",
decode: func(b []byte) (any, error) { var v ModulesByModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a candidate", subject: "", given: "{\"base\":3,\"group\":\"feat/registry\",\"heads\":\"0123456789ab\",\"pulls\":[{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"modules\":[\"nats\"],\"number\":1,\"repository\":\"novox/mesh-sdk\"}],\"v\":1}", wire: "{\"base\":3,\"group\":\"feat/registry\",\"heads\":\"0123456789ab\",\"pulls\":[{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"modules\":[\"nats\"],\"number\":1,\"repository\":\"novox/mesh-sdk\"}],\"v\":1}",
decode: func(b []byte) (any, error) { var v CandidatesByGroupValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a refused verdict (nats, read through the indexer's verdicts tool)", subject: "", given: "{\"at\":\"2026-11-04T18:51:12.614583047+01:00\",\"judge\":\"exe:661e6fb424d7ffea\",\"module\":\"nats\",\"problems\":[\"this is not a module manifest: a state is either a name or {name, history, ttl-seconds, per-machine, key-ttl}: json: unknown field \\\"read-only\\\" (read without state[2].read-only)\"],\"state\":\"refused\"}", wire: "{\"at\":\"2026-11-04T18:51:12.614583047+01:00\",\"judge\":\"exe:661e6fb424d7ffea\",\"module\":\"nats\",\"problems\":[\"this is not a module manifest: a state is either a name or {name, history, ttl-seconds, per-machine, key-ttl}: json: unknown field \\\"read-only\\\" (read without state[2].read-only)\"],\"state\":\"refused\"}",
decode: func(b []byte) (any, error) { var v VerdictsByDigestValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the predefined list", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"list\":{\"streams\":[]},\"v\":1}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"list\":{\"streams\":[]},\"v\":1}",
decode: func(b []byte) (any, error) { var v PredefinedByListValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a published Go module", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"module\":\"git.novox.be/novox/mesh-sdk/go\",\"packages\":[{\"digest\":\"ab\",\"package\":\"git.novox.be/novox/mesh-sdk/go/keys\"}],\"repository\":\"novox/mesh-sdk\",\"v\":1}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"module\":\"git.novox.be/novox/mesh-sdk/go\",\"packages\":[{\"digest\":\"ab\",\"package\":\"git.novox.be/novox/mesh-sdk/go/keys\"}],\"repository\":\"novox/mesh-sdk\",\"v\":1}",
decode: func(b []byte) (any, error) { var v PackagesByModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a package series", subject: "", given: "{\"name\":\"go-keys\",\"series\":\"0.1\",\"v\":1}", wire: "{\"name\":\"go-keys\",\"series\":\"0.1\",\"v\":1}",
decode: func(b []byte) (any, error) {
var v PackagesByPackageSeriesValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a module with its toolchain", subject: "", given: "{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp2\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"repository\":\"novox/mesh-catalog\",\"toolchains\":{\"go\":{\"language\":\"go\",\"recipe\":\"1\",\"version\":\"1.26.0\"}},\"v\":1}", wire: "{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp2\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"repository\":\"novox/mesh-catalog\",\"toolchains\":{\"go\":{\"language\":\"go\",\"recipe\":\"1\",\"version\":\"1.26.0\"}},\"v\":1}",
decode: func(b []byte) (any, error) { var v ModulesByModuleValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the modules verb (captured: the first three modules)", subject: "", given: "{\"modules\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:5e4a1b4ad4ea6175c05e4655ce58aeb957547149d4c9805eb27636efd50c1c87\",\"module\":\"adwaita\",\"path\":\"modules/adwaita\",\"repository\":\"novox/mesh-catalog\"},{\"commit\":\"b112adcecc41d18f54190cbd2fc864199b70c518\",\"fp\":\"src2:7dd0db8e98224f46121a5ae05c0b9c5a430eff531a5120aa40b1a59237853a3f\",\"module\":\"amqp-email-forwarder\",\"path\":\".\",\"repository\":\"jschoubben/amqp-email-forwarder\"},{\"commit\":\"dd458cb155f5f5fa3ed824a23728e444be5b156a\",\"fp\":\"src2:a98f8152f0a837dd5ba883a15efaf110ba88100193157e4bdb1a93ba55209371\",\"module\":\"artifact-store-tools\",\"path\":\"modules/artifact-store-tools\",\"repository\":\"novox/mesh-catalog\"}]}", wire: "{\"modules\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:5e4a1b4ad4ea6175c05e4655ce58aeb957547149d4c9805eb27636efd50c1c87\",\"module\":\"adwaita\",\"path\":\"modules/adwaita\",\"repository\":\"novox/mesh-catalog\"},{\"commit\":\"b112adcecc41d18f54190cbd2fc864199b70c518\",\"fp\":\"src2:7dd0db8e98224f46121a5ae05c0b9c5a430eff531a5120aa40b1a59237853a3f\",\"module\":\"amqp-email-forwarder\",\"path\":\".\",\"repository\":\"jschoubben/amqp-email-forwarder\"},{\"commit\":\"dd458cb155f5f5fa3ed824a23728e444be5b156a\",\"fp\":\"src2:a98f8152f0a837dd5ba883a15efaf110ba88100193157e4bdb1a93ba55209371\",\"module\":\"artifact-store-tools\",\"path\":\"modules/artifact-store-tools\",\"repository\":\"novox/mesh-catalog\"}]}",
decode: func(b []byte) (any, error) { var v ModulesAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the module verb (captured: xclip)", subject: "", given: "{\"module\":{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"manifest\":{\"build\":{\"artifacts\":[{\"binary\":\"xclip-tools\",\"from\":\"cmd/xclip-tools\",\"kind\":\"bundle\",\"language\":\"go\",\"loads\":[\"xclip-tools\"],\"name\":\"tools\",\"system\":\"arch\"}]},\"capabilities\":[\"package-manager\"],\"module\":\"xclip\",\"resources\":[{\"id\":\"package\",\"package\":\"xclip\",\"type\":\"package\"}],\"tools\":[\"xclip_copy\",\"xclip_paste\",\"xclip_targets\",\"xclip_session\"],\"version\":\"1\"},\"module\":\"xclip\",\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\"}}", wire: "{\"module\":{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"manifest\":{\"build\":{\"artifacts\":[{\"binary\":\"xclip-tools\",\"from\":\"cmd/xclip-tools\",\"kind\":\"bundle\",\"language\":\"go\",\"loads\":[\"xclip-tools\"],\"name\":\"tools\",\"system\":\"arch\"}]},\"capabilities\":[\"package-manager\"],\"module\":\"xclip\",\"resources\":[{\"id\":\"package\",\"package\":\"xclip\",\"type\":\"package\"}],\"tools\":[\"xclip_copy\",\"xclip_paste\",\"xclip_targets\",\"xclip_session\"],\"version\":\"1\"},\"module\":\"xclip\",\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\"}}",
decode: func(b []byte) (any, error) { var v ModuleAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
-3
View File
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog
go 1.26.0
-455
View File
@@ -1,455 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package meshdelivery is the contract of the seat "mesh-delivery", defined whole (seats/mesh-delivery/seat.json): The delivery gate: reads and steers deliveries, merges and the checks that decide them; the merge is made on the operator's Approve once both checks passed.
package meshdelivery
import (
"bytes"
"encoding/json"
"errors"
"strings"
"time"
)
// Seat is the seat's name.
const Seat = "mesh-delivery"
const (
VerbDeliveries = "deliveries"
VerbTimes = "times"
VerbShow = "show"
VerbGroups = "groups"
VerbWhatIf = "what-if"
VerbChecks = "checks"
VerbTable = "table"
VerbStalled = "stalled"
VerbRecheck = "recheck"
VerbRelease = "release"
VerbStop = "stop"
VerbClose = "close"
VerbRetireHistory = "retire-history"
VerbSettle = "settle"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbDeliveries, VerbTimes, VerbShow, VerbGroups, VerbWhatIf, VerbChecks, VerbTable, VerbStalled, VerbRecheck, VerbRelease, VerbStop, VerbClose, VerbRetireHistory, VerbSettle}
}
const (
StateSource = "source"
StateMerges = "merges"
StateAsks = "asks"
StateOwed = "owed"
StateTurns = "turns"
)
// SourceByMainKey is the key of one value of the state source under the form "main".
func SourceByMainKey() string { return "main" }
// ParseSourceByMainKey reads the parts of a key of the form "main", in the order of the form; the last result is false for a key of another form.
func ParseSourceByMainKey(key string) bool {
rest := key
if !strings.HasPrefix(rest, "main") {
return false
}
rest = rest[4:]
if rest != "" {
return false
}
return true
}
// DecodeSourceByMainValue reads one value of the state source under the form "main", refusing a field SourceByMainValue does not know and any text after the value.
func DecodeSourceByMainValue(raw []byte) (SourceByMainValue, error) {
var v SourceByMainValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// MergesByGroupKey is the key of one value of the state merges under the form "<group>".
func MergesByGroupKey(group string) string { return group }
// ParseMergesByGroupKey reads the parts of a key of the form "<group>", in the order of the form; the last result is false for a key of another form.
func ParseMergesByGroupKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeMergesByGroupValue reads one value of the state merges under the form "<group>", refusing a field MergesByGroupValue does not know and any text after the value.
func DecodeMergesByGroupValue(raw []byte) (MergesByGroupValue, error) {
var v MergesByGroupValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// AsksByMergeGroupHeadsKey is the key of one value of the state asks under the form "merge.<group>.<heads>".
func AsksByMergeGroupHeadsKey(group, heads string) string { return "merge." + group + "." + heads }
// ParseAsksByMergeGroupHeadsKey reads the parts of a key of the form "merge.<group>.<heads>", in the order of the form; the last result is false for a key of another form.
func ParseAsksByMergeGroupHeadsKey(key string) (string, string, bool) {
rest := key
if !strings.HasPrefix(rest, "merge.") {
return "", "", false
}
rest = rest[6:]
v1, after1, found1 := strings.Cut(rest, ".")
if !found1 || v1 == "" {
return "", "", false
}
rest = after1
if rest == "" {
return "", "", false
}
v3 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v1, v3, true
}
// DecodeAsksByMergeGroupHeadsValue reads one value of the state asks under the form "merge.<group>.<heads>", refusing a field AsksByMergeGroupHeadsValue does not know and any text after the value.
func DecodeAsksByMergeGroupHeadsValue(raw []byte) (AsksByMergeGroupHeadsValue, error) {
var v AsksByMergeGroupHeadsValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// OwedByRepositoryNumberHeadActKey is the key of one value of the state owed under the form "<repository>.<number>.<head>.<act>".
func OwedByRepositoryNumberHeadActKey(repository, number, head, act string) string {
return repository + "." + number + "." + head + "." + act
}
// ParseOwedByRepositoryNumberHeadActKey reads the parts of a key of the form "<repository>.<number>.<head>.<act>", in the order of the form; the last result is false for a key of another form.
func ParseOwedByRepositoryNumberHeadActKey(key string) (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, ".")
if !found2 || v2 == "" {
return "", "", "", "", false
}
rest = after2
v4, after4, found4 := strings.Cut(rest, ".")
if !found4 || v4 == "" {
return "", "", "", "", false
}
rest = after4
if rest == "" {
return "", "", "", "", false
}
v6 := rest
rest = ""
if rest != "" {
return "", "", "", "", false
}
return v0, v2, v4, v6, true
}
// DecodeOwedByRepositoryNumberHeadActValue reads one value of the state owed under the form "<repository>.<number>.<head>.<act>", refusing a field OwedByRepositoryNumberHeadActValue does not know and any text after the value.
func DecodeOwedByRepositoryNumberHeadActValue(raw []byte) (OwedByRepositoryNumberHeadActValue, error) {
var v OwedByRepositoryNumberHeadActValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// TurnsByRepositoryKey is the key of one value of the state turns under the form "<repository>".
func TurnsByRepositoryKey(repository string) string { return repository }
// ParseTurnsByRepositoryKey reads the parts of a key of the form "<repository>", in the order of the form; the last result is false for a key of another form.
func ParseTurnsByRepositoryKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeTurnsByRepositoryValue reads one value of the state turns under the form "<repository>", refusing a field TurnsByRepositoryValue does not know and any text after the value.
func DecodeTurnsByRepositoryValue(raw []byte) (TurnsByRepositoryValue, error) {
var v TurnsByRepositoryValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// DeliveriesInput is what deliveries takes.
type DeliveriesInput struct {
// "true": the final ones of the last thirty days too
All string `json:"all,omitempty"`
// a group's id (its branch name)
Group string `json:"group,omitempty"`
// owner/repository
Repository string `json:"repository,omitempty"`
// one state, e.g. delivering or held
State string `json:"state,omitempty"`
}
// The values of DeliveriesInput's all.
const (
DeliveriesInputAllTrue = "true"
DeliveriesInputAllFalse = "false"
)
// DeliveriesAnswer is what deliveries answers.
type DeliveriesAnswer = map[string]any
// TimesInput is what times takes.
type TimesInput struct {
}
// TimesAnswer is what times answers.
type TimesAnswer = map[string]any
// ShowInput is what show takes.
type ShowInput struct {
// a delivery's id, or a group's
ID string `json:"id"`
}
// ShowAnswer is what show answers.
type ShowAnswer = map[string]any
// GroupsInput is what groups takes.
type GroupsInput struct {
// "true": the groups that ended too
All string `json:"all,omitempty"`
}
// The values of GroupsInput's all.
const (
GroupsInputAllTrue = "true"
GroupsInputAllFalse = "false"
)
// GroupsAnswer is what groups answers.
type GroupsAnswer = map[string]any
// WhatIfInput is what what-if takes.
type WhatIfInput struct {
}
// WhatIfAnswer is what what-if answers.
type WhatIfAnswer = map[string]any
// ChecksInput is what checks takes.
type ChecksInput struct {
// a commit's sha, or the start of one, instead of a pull request
Commit string `json:"commit,omitempty"`
// a pull request's number: its head is read
Number string `json:"number,omitempty"`
// owner/repository
Repository string `json:"repository"`
}
// ChecksAnswer is what checks answers.
type ChecksAnswer = map[string]any
// TableInput is what table takes.
type TableInput struct {
}
// TableAnswer is what table answers.
type TableAnswer = map[string]any
// StalledInput is what stalled takes.
type StalledInput struct {
}
// StalledAnswer is what stalled answers.
type StalledAnswer = map[string]any
// RecheckInput is what recheck takes.
type RecheckInput struct {
// the delivery's id
ID string `json:"id"`
// why, kept with the transition
Why string `json:"why"`
}
// RecheckAnswer is what recheck answers.
type RecheckAnswer = map[string]any
// ReleaseInput is what release takes.
type ReleaseInput struct {
}
// ReleaseAnswer is what release answers.
type ReleaseAnswer = map[string]any
// StopInput is what stop takes.
type StopInput struct {
}
// StopAnswer is what stop answers.
type StopAnswer = map[string]any
// CloseInput is what close takes.
type CloseInput struct {
// the delivery's id
ID string `json:"id"`
// the condition it answers
Why string `json:"why"`
}
// CloseAnswer is what close answers.
type CloseAnswer = map[string]any
// RetireHistoryInput is what retire-history takes.
type RetireHistoryInput struct {
}
// RetireHistoryAnswer is what retire-history answers.
type RetireHistoryAnswer = map[string]any
// SettleInput is what settle takes.
type SettleInput struct {
// the held deliveries' ids (owner/repository@commit)
Ids []string `json:"ids"`
// why they may be settled, shown to the operator
Why string `json:"why"`
}
// SettleAnswer is what settle answers.
type SettleAnswer = map[string]any
// SourceByMainValue is one value of the state source under the key main.
type SourceByMainValue struct {
// the group that moved it
Group string `json:"group"`
// repository to the merged head, a full commit
Heads map[string]string `json:"heads"`
// the layout version
V int64 `json:"v,omitempty"`
}
// MergesByGroupValuePullsItem is a type of the contract.
type MergesByGroupValuePullsItem struct {
Commit string `json:"commit,omitempty"`
Head string `json:"head"`
Number int64 `json:"number"`
Repository string `json:"repository"`
// merging, merged or refused
State string `json:"state"`
Words string `json:"words,omitempty"`
}
// MergesByGroupValue is one value of the state merges under the key <group>.
type MergesByGroupValue struct {
// <repository>@<number> to the approved head
Approved map[string]string `json:"approved,omitempty"`
// the ask key
Ask string `json:"ask"`
Group string `json:"group"`
Pulls []MergesByGroupValuePullsItem `json:"pulls"`
// the layout version
V int64 `json:"v,omitempty"`
}
// AsksByMergeGroupHeadsValueHeadsItem is a type of the contract.
type AsksByMergeGroupHeadsValueHeadsItem struct {
// the full commit
Head string `json:"head"`
Number int64 `json:"number"`
// <owner>/<name>
Repository string `json:"repository"`
}
// AsksByMergeGroupHeadsValue is one value of the state asks under the key merge.<group>.<heads>.
type AsksByMergeGroupHeadsValue struct {
// the operator-channel ask as raised
Ask any `json:"ask"`
// the number of times it was asked
Asking int64 `json:"asking,omitempty"`
Group string `json:"group"`
Heads []AsksByMergeGroupHeadsValueHeadsItem `json:"heads"`
// the layout version
V int64 `json:"v,omitempty"`
}
// OwedByRepositoryNumberHeadActValue is one value of the state owed under the key <repository>.<number>.<head>.<act>.
type OwedByRepositoryNumberHeadActValue struct {
// status=<context>, view, note or comment.<seq>
Act string `json:"act"`
Context string `json:"context,omitempty"`
Ref string `json:"ref,omitempty"`
State string `json:"state,omitempty"`
Target string `json:"target,omitempty"`
Text string `json:"text,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
}
// TurnsByRepositoryValueWaitingItem is a type of the contract.
type TurnsByRepositoryValueWaitingItem struct {
// when (RFC 3339 time)
Approved time.Time `json:"approved"`
Ask string `json:"ask,omitempty"`
Group string `json:"group"`
Heads string `json:"heads"`
// when (RFC 3339 time)
Since time.Time `json:"since"`
Step string `json:"step,omitempty"`
WaitsFor string `json:"waits-for,omitempty"`
// when (RFC 3339 time)
WaitsSince *time.Time `json:"waits-since,omitempty"`
}
// TurnsByRepositoryValue is one value of the state turns under the key <repository>.
type TurnsByRepositoryValue struct {
Repository string `json:"repository"`
// the layout version
V int64 `json:"v,omitempty"`
Waiting []TurnsByRepositoryValueWaitingItem `json:"waiting"`
}
@@ -1,64 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package meshdelivery
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/mesh-delivery/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "the source revision", subject: "", given: "{\"group\":\"feat/registry\",\"heads\":{\"novox/mesh-sdk\":\"cccccccccccccccccccccccccccccccccccccccc\"},\"v\":1}", wire: "{\"group\":\"feat/registry\",\"heads\":{\"novox/mesh-sdk\":\"cccccccccccccccccccccccccccccccccccccccc\"},\"v\":1}",
decode: func(b []byte) (any, error) { var v SourceByMainValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a merge", subject: "", given: "{\"ask\":\"merge.feat=registry.0123456789ab\",\"group\":\"feat/registry\",\"pulls\":[{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":1,\"repository\":\"novox/mesh-sdk\",\"state\":\"merging\"}],\"v\":1}", wire: "{\"ask\":\"merge.feat=registry.0123456789ab\",\"group\":\"feat/registry\",\"pulls\":[{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":1,\"repository\":\"novox/mesh-sdk\",\"state\":\"merging\"}],\"v\":1}",
decode: func(b []byte) (any, error) { var v MergesByGroupValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "an ask", subject: "", given: "{\"ask\":{\"headline\":\"merge\"},\"group\":\"feat/registry\",\"heads\":[{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":1,\"repository\":\"novox/mesh-sdk\"}],\"v\":1}", wire: "{\"ask\":{\"headline\":\"merge\"},\"group\":\"feat/registry\",\"heads\":[{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":1,\"repository\":\"novox/mesh-sdk\"}],\"v\":1}",
decode: func(b []byte) (any, error) {
var v AsksByMergeGroupHeadsValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "an act owed", subject: "", given: "{\"act\":\"view\",\"v\":1}", wire: "{\"act\":\"view\",\"v\":1}",
decode: func(b []byte) (any, error) {
var v OwedByRepositoryNumberHeadActValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a turn", subject: "", given: "{\"repository\":\"novox/mesh-sdk\",\"v\":1,\"waiting\":[{\"approved\":\"2026-11-05T10:00:00Z\",\"group\":\"feat/registry\",\"heads\":\"0123456789ab\",\"since\":\"2026-11-05T10:01:00Z\"}]}", wire: "{\"repository\":\"novox/mesh-sdk\",\"v\":1,\"waiting\":[{\"approved\":\"2026-11-05T10:00:00Z\",\"group\":\"feat/registry\",\"heads\":\"0123456789ab\",\"since\":\"2026-11-05T10:01:00Z\"}]}",
decode: func(b []byte) (any, error) { var v TurnsByRepositoryValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
-3
View File
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery
go 1.26.0
-337
View File
@@ -1,337 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package meshwants is the contract of the seat "mesh-wants", defined whole (seats/mesh-wants/seat.json): The seat that says what each node should run and whether each module's new builds wait for a person (ADR 0565, ADR 0539).
package meshwants
import (
"bytes"
"encoding/json"
"errors"
"strings"
)
// Seat is the seat's name.
const Seat = "mesh-wants"
const (
VerbUpgrade = "upgrade"
VerbBus = "bus"
)
const (
EventPolicyChanged = "policy-changed"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbUpgrade, VerbBus}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventPolicyChanged}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "mesh-wants.events"
FamilyMaxAgeDays = 7
)
// SubjectPolicyChanged is where policy-changed is published.
const SubjectPolicyChanged = "mesh.seat.mesh-wants.event.policy-changed"
const (
StateWants = "wants"
StateDifferences = "differences"
StateCompositions = "compositions"
)
// WantsByWantNodeModuleKey is the key of one value of the state wants under the form "want.<node>.<module>".
func WantsByWantNodeModuleKey(node, module string) string { return "want." + node + "." + module }
// ParseWantsByWantNodeModuleKey reads the parts of a key of the form "want.<node>.<module>", in the order of the form; the last result is false for a key of another form.
func ParseWantsByWantNodeModuleKey(key string) (string, string, bool) {
rest := key
if !strings.HasPrefix(rest, "want.") {
return "", "", false
}
rest = rest[5:]
v1, after1, found1 := strings.Cut(rest, ".")
if !found1 || v1 == "" {
return "", "", false
}
rest = after1
if rest == "" {
return "", "", false
}
v3 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v1, v3, true
}
// DecodeWantsByWantNodeModuleValue reads one value of the state wants under the form "want.<node>.<module>", refusing a field WantsByWantNodeModuleValue does not know and any text after the value.
func DecodeWantsByWantNodeModuleValue(raw []byte) (WantsByWantNodeModuleValue, error) {
var v WantsByWantNodeModuleValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// WantsByWantNodeNodeKey is the key of one value of the state wants under the form "want.<node>.node".
func WantsByWantNodeNodeKey(node string) string { return "want." + node + ".node" }
// ParseWantsByWantNodeNodeKey reads the parts of a key of the form "want.<node>.node", in the order of the form; the last result is false for a key of another form.
func ParseWantsByWantNodeNodeKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "want.") {
return "", false
}
rest = rest[5:]
v1, after1, found1 := strings.Cut(rest, ".node")
if !found1 || v1 == "" {
return "", false
}
rest = after1
if rest != "" {
return "", false
}
return v1, true
}
// DecodeWantsByWantNodeNodeValue reads one value of the state wants under the form "want.<node>.node", refusing a field WantsByWantNodeNodeValue does not know and any text after the value.
func DecodeWantsByWantNodeNodeValue(raw []byte) (WantsByWantNodeNodeValue, error) {
var v WantsByWantNodeNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// WantsByHeldModuleFingerprintKey is the key of one value of the state wants under the form "held.<module>.<fingerprint>".
func WantsByHeldModuleFingerprintKey(module, fingerprint string) string {
return "held." + module + "." + fingerprint
}
// ParseWantsByHeldModuleFingerprintKey reads the parts of a key of the form "held.<module>.<fingerprint>", in the order of the form; the last result is false for a key of another form.
func ParseWantsByHeldModuleFingerprintKey(key string) (string, string, bool) {
rest := key
if !strings.HasPrefix(rest, "held.") {
return "", "", false
}
rest = rest[5:]
v1, after1, found1 := strings.Cut(rest, ".")
if !found1 || v1 == "" {
return "", "", false
}
rest = after1
if rest == "" {
return "", "", false
}
v3 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v1, v3, true
}
// DecodeWantsByHeldModuleFingerprintValue reads one value of the state wants under the form "held.<module>.<fingerprint>", refusing a field WantsByHeldModuleFingerprintValue does not know and any text after the value.
func DecodeWantsByHeldModuleFingerprintValue(raw []byte) (WantsByHeldModuleFingerprintValue, error) {
var v WantsByHeldModuleFingerprintValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// DifferencesByNodeModuleKey is the key of one value of the state differences under the form "<node>.<module>".
func DifferencesByNodeModuleKey(node, module string) string { return node + "." + module }
// ParseDifferencesByNodeModuleKey reads the parts of a key of the form "<node>.<module>", in the order of the form; the last result is false for a key of another form.
func ParseDifferencesByNodeModuleKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeDifferencesByNodeModuleValue reads one value of the state differences under the form "<node>.<module>", refusing a field DifferencesByNodeModuleValue does not know and any text after the value.
func DecodeDifferencesByNodeModuleValue(raw []byte) (DifferencesByNodeModuleValue, error) {
var v DifferencesByNodeModuleValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// CompositionsByGroupHeadsKey is the key of one value of the state compositions under the form "<group>.<heads>".
func CompositionsByGroupHeadsKey(group, heads string) string { return group + "." + heads }
// ParseCompositionsByGroupHeadsKey reads the parts of a key of the form "<group>.<heads>", in the order of the form; the last result is false for a key of another form.
func ParseCompositionsByGroupHeadsKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeCompositionsByGroupHeadsValue reads one value of the state compositions under the form "<group>.<heads>", refusing a field CompositionsByGroupHeadsValue does not know and any text after the value.
func DecodeCompositionsByGroupHeadsValue(raw []byte) (CompositionsByGroupHeadsValue, error) {
var v CompositionsByGroupHeadsValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// UpgradeInput is what upgrade takes.
type UpgradeInput struct {
// "true": each node's own composition, by its digest, and the assigner's findings
Compare string `json:"compare,omitempty"`
// one module
Module string `json:"module,omitempty"`
// with module: roll, together, record, or default to take a person's choice back
Policy string `json:"policy,omitempty"`
// with policy: why, required and kept
Why string `json:"why,omitempty"`
}
// The values of UpgradeInput's compare.
const (
UpgradeInputCompareTrue = "true"
UpgradeInputCompareFalse = "false"
)
// UpgradeAnswer is what upgrade answers.
type UpgradeAnswer = map[string]any
// BusInput is what bus takes.
type BusInput struct {
}
// BusAnswer is what bus answers.
type BusAnswer = map[string]any
// PolicyChangedEvent is the body of the event policy-changed.
type PolicyChangedEvent = map[string]any
// WantsByWantNodeModuleValue is one value of the state wants under the key want.<node>.<module>.
type WantsByWantNodeModuleValue struct {
// again or skip
Backup string `json:"backup,omitempty"`
Composed string `json:"composed,omitempty"`
Fp string `json:"fp,omitempty"`
Hold bool `json:"hold,omitempty"`
Newest string `json:"newest,omitempty"`
Put bool `json:"put,omitempty"`
Release string `json:"release,omitempty"`
Removed bool `json:"removed,omitempty"`
// the rule that holds the node back, 1 to 10
Rule int64 `json:"rule,omitempty"`
Self bool `json:"self,omitempty"`
V int64 `json:"v,omitempty"`
Words string `json:"words,omitempty"`
Yes string `json:"yes,omitempty"`
}
// The values of WantsByWantNodeModuleValue's backup.
const (
WantsByWantNodeModuleValueBackupAgain = "again"
WantsByWantNodeModuleValueBackupSkip = "skip"
)
// WantsByWantNodeNodeValue is one value of the state wants under the key want.<node>.node.
type WantsByWantNodeNodeValue struct {
Composed string `json:"composed"`
Self bool `json:"self,omitempty"`
V int64 `json:"v,omitempty"`
Words string `json:"words,omitempty"`
}
// WantsByHeldModuleFingerprintValue is one value of the state wants under the key held.<module>.<fingerprint>.
type WantsByHeldModuleFingerprintValue struct {
Node string `json:"node"`
V int64 `json:"v,omitempty"`
Words string `json:"words,omitempty"`
}
// DifferencesByNodeModuleValue is one value of the state differences under the key <node>.<module>.
type DifferencesByNodeModuleValue struct {
Rule int64 `json:"rule,omitempty"`
Sent string `json:"sent,omitempty"`
SentBuild string `json:"sent-build,omitempty"`
Unexplained bool `json:"unexplained,omitempty"`
V int64 `json:"v,omitempty"`
Want string `json:"want,omitempty"`
WantRemoved bool `json:"want-removed,omitempty"`
Words string `json:"words,omitempty"`
}
// CompositionsByGroupHeadsValue is one value of the state compositions under the key <group>.<heads>.
type CompositionsByGroupHeadsValue struct {
Group string `json:"group"`
// 12 lowercase hex digits
Heads string `json:"heads"`
Machine string `json:"machine,omitempty"`
Machines []string `json:"machines,omitempty"`
Sdk string `json:"sdk,omitempty"`
// pass, fail or waits
State string `json:"state"`
// milliseconds
Took int64 `json:"took,omitempty"`
V int64 `json:"v,omitempty"`
Warnings []string `json:"warnings,omitempty"`
Words string `json:"words,omitempty"`
}
@@ -1,76 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package meshwants
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/mesh-wants/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a want", subject: "", given: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}", wire: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}",
decode: func(b []byte) (any, error) {
var v WantsByWantNodeModuleValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a node's own want", subject: "", given: "{\"composed\":\"sha256:aa\",\"self\":true,\"v\":1}", wire: "{\"composed\":\"sha256:aa\",\"self\":true,\"v\":1}",
decode: func(b []byte) (any, error) {
var v WantsByWantNodeNodeValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a held fingerprint", subject: "", given: "{\"node\":\"ace\",\"v\":1}", wire: "{\"node\":\"ace\",\"v\":1}",
decode: func(b []byte) (any, error) {
var v WantsByHeldModuleFingerprintValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a difference", subject: "", given: "{\"unexplained\":true,\"v\":1,\"want\":\"ab12\"}", wire: "{\"unexplained\":true,\"v\":1,\"want\":\"ab12\"}",
decode: func(b []byte) (any, error) {
var v DifferencesByNodeModuleValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a composition", subject: "", given: "{\"group\":\"g1\",\"heads\":\"0123456789ab\",\"state\":\"pass\",\"v\":1}", wire: "{\"group\":\"g1\",\"heads\":\"0123456789ab\",\"state\":\"pass\",\"v\":1}",
decode: func(b []byte) (any, error) {
var v CompositionsByGroupHeadsValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
-3
View File
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/meshwants
go 1.26.0
-678
View File
@@ -1,678 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package nodebuildgo is the contract of the seat "node-build-go", defined whole (seats/node-build-go/seat.json): The Go build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.
package nodebuildgo
import (
"bytes"
"encoding/json"
"errors"
"strings"
"time"
)
// Seat is the seat's name.
const Seat = "node-build-go"
const (
VerbCurrent = "current"
VerbPause = "pause"
VerbResume = "resume"
VerbDrop = "drop"
)
const (
AcceptDelivery = "delivery"
AcceptCheck = "check"
AcceptRecheck = "recheck"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop}
}
// AcceptSubjectDelivery is where delivery is sent.
const AcceptSubjectDelivery = "mesh.seat.node-build-go.accept.delivery"
// AcceptSubjectCheck is where check is sent.
const AcceptSubjectCheck = "mesh.seat.node-build-go.accept.check"
// AcceptSubjectRecheck is where recheck is sent.
const AcceptSubjectRecheck = "mesh.seat.node-build-go.accept.recheck"
const (
StateSteps = "steps"
StatePauses = "pauses"
StateToolchains = "toolchains"
)
// StepsByNodeIDKey is the key of one value of the state steps under the form "<node>.<id>".
func StepsByNodeIDKey(node, id string) string { return node + "." + id }
// ParseStepsByNodeIDKey reads the parts of a key of the form "<node>.<id>", in the order of the form; the last result is false for a key of another form.
func ParseStepsByNodeIDKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeStepsByNodeIDValue reads one value of the state steps under the form "<node>.<id>", refusing a field StepsByNodeIDValue does not know and any text after the value.
func DecodeStepsByNodeIDValue(raw []byte) (StepsByNodeIDValue, error) {
var v StepsByNodeIDValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByPausedNodeKey is the key of one value of the state pauses under the form "paused.<node>".
func PausesByPausedNodeKey(node string) string { return "paused." + node }
// ParsePausesByPausedNodeKey reads the parts of a key of the form "paused.<node>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByPausedNodeKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "paused.") {
return "", false
}
rest = rest[7:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByPausedNodeValue reads one value of the state pauses under the form "paused.<node>", refusing a field PausesByPausedNodeValue does not know and any text after the value.
func DecodePausesByPausedNodeValue(raw []byte) (PausesByPausedNodeValue, error) {
var v PausesByPausedNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByDroppedIDKey is the key of one value of the state pauses under the form "dropped.<id>".
func PausesByDroppedIDKey(id string) string { return "dropped." + id }
// ParsePausesByDroppedIDKey reads the parts of a key of the form "dropped.<id>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByDroppedIDKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "dropped.") {
return "", false
}
rest = rest[8:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByDroppedIDValue reads one value of the state pauses under the form "dropped.<id>", refusing a field PausesByDroppedIDValue does not know and any text after the value.
func DecodePausesByDroppedIDValue(raw []byte) (PausesByDroppedIDValue, error) {
var v PausesByDroppedIDValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByCapacityNodeKey is the key of one value of the state pauses under the form "capacity.<node>".
func PausesByCapacityNodeKey(node string) string { return "capacity." + node }
// ParsePausesByCapacityNodeKey reads the parts of a key of the form "capacity.<node>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByCapacityNodeKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "capacity.") {
return "", false
}
rest = rest[9:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByCapacityNodeValue reads one value of the state pauses under the form "capacity.<node>", refusing a field PausesByCapacityNodeValue does not know and any text after the value.
func DecodePausesByCapacityNodeValue(raw []byte) (PausesByCapacityNodeValue, error) {
var v PausesByCapacityNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// ToolchainsByNodeLanguageKey is the key of one value of the state toolchains under the form "<node>.<language>".
func ToolchainsByNodeLanguageKey(node, language string) string { return node + "." + language }
// ParseToolchainsByNodeLanguageKey reads the parts of a key of the form "<node>.<language>", in the order of the form; the last result is false for a key of another form.
func ParseToolchainsByNodeLanguageKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeToolchainsByNodeLanguageValue reads one value of the state toolchains under the form "<node>.<language>", refusing a field ToolchainsByNodeLanguageValue does not know and any text after the value.
func DecodeToolchainsByNodeLanguageValue(raw []byte) (ToolchainsByNodeLanguageValue, error) {
var v ToolchainsByNodeLanguageValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// AskArtifact is one artifact of a build ask: built from the fetched tree, or copied from an upstream pin.
type AskArtifact struct {
Artifact string `json:"artifact"`
From string `json:"from,omitempty"`
Seat string `json:"seat,omitempty"`
Version string `json:"version,omitempty"`
}
// BuildAnswer is a type of the contract.
type BuildAnswer struct {
Artifacts []BuiltArtifact `json:"artifacts"`
Imports []string `json:"imports,omitempty"`
OutOfStep []string `json:"out-of-step,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// BuiltArtifact is one artifact a build made: its digest and the reference it was published under.
type BuiltArtifact struct {
Artifact string `json:"artifact"`
Digest string `json:"digest"`
Reference string `json:"reference,omitempty"`
}
// Capacity is how many steps the node runs at once.
type Capacity struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
BuildHours string `json:"build-hours,omitempty"`
BuildHoursFault string `json:"build-hours-fault,omitempty"`
ByCpu int64 `json:"by-cpu,omitempty"`
Configured int64 `json:"configured"`
ConfiguredFrom string `json:"configured-from,omitempty"`
CoresPerStep float64 `json:"cores-per-step,omitempty"`
Effective int64 `json:"effective"`
Ineligible string `json:"ineligible,omitempty"`
OutsideHours bool `json:"outside-hours,omitempty"`
QuotaCores float64 `json:"quota-cores,omitempty"`
QuotaFrom string `json:"quota-from,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Why string `json:"why"`
}
// CheckAnswer is a type of the contract.
type CheckAnswer struct {
Fetch FetchAnswer `json:"fetch"`
Levels []LevelAnswer `json:"levels,omitempty"`
}
// ComposeAnswer is a type of the contract.
type ComposeAnswer struct {
Built bool `json:"built"`
Key string `json:"key,omitempty"`
// the compose-candidate verdict
Verdict any `json:"verdict,omitempty"`
}
// Drop is an ask a caller no longer waits for.
type Drop struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
By string `json:"by,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Why string `json:"why"`
}
// FetchBesideItem is a type of the contract.
type FetchBesideItem struct {
Commit string `json:"commit"`
Repository string `json:"repository"`
}
// FetchPackage is the TypeScript module's group package: the group's tagged version of the SDK ({name, version}), placed from the registry in each member whatever its lock names, or the group's package member ({repository, commit, ref}), packed by the fetch and served to the members in place of the registry's.
type FetchPackage struct {
Commit string `json:"commit,omitempty"`
Name string `json:"name,omitempty"`
Ref string `json:"ref,omitempty"`
Repository string `json:"repository,omitempty"`
Version string `json:"version,omitempty"`
}
// Fetch is what a build module's fetch tool is asked: the repository and the full commit, the pull request's ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, the module's directory and named paths, the mesh packages to build against, and the sibling repositories placed beside.
type Fetch struct {
// the trunk commit a merge preview merges onto
Base string `json:"base,omitempty"`
// the sibling repositories placed beside the fetched tree
Beside []FetchBesideItem `json:"beside,omitempty"`
// the full commit
Commit string `json:"commit"`
// the module's directory in the repository ("." for its root), with paths
Dir string `json:"dir,omitempty"`
// the TypeScript module's group package: the group's tagged version of the SDK ({name, version}), placed from the registry in each member whatever its lock names, or the group's package member ({repository, commit, ref}), packed by the fetch and served to the members in place of the registry's
Package *FetchPackage `json:"package,omitempty"`
// the version (a full commit) of each mesh package to build against, by its module path
Packages map[string]string `json:"packages,omitempty"`
// the paths the module names, relative to dir
Paths []string `json:"paths,omitempty"`
// the pull request's ref, when only its head carries the commit
Ref string `json:"ref,omitempty"`
// <owner>/<name>
Repository string `json:"repository"`
}
// FetchAnswer is what a build module's fetch tool answers, whole: the workspace it made, the commit in it, the module directories found; and, when the call gave a base, the merge preview (the trunk commit, the merge commit, the files that conflict, the paths the merge changes, the compiled programs among them, the tree of each module directory). A head that does not merge cleanly is an answer, not an error: merge is empty and conflicts names the files. The Go module adds the sibling repositories placed and the package versions taken; the TypeScript module the directories installed and refused and the group's package.
type FetchAnswer struct {
Base string `json:"base,omitempty"`
Beside []PlacedBeside `json:"beside,omitempty"`
Changed []string `json:"changed,omitempty"`
Commit string `json:"commit"`
Conflicts []string `json:"conflicts,omitempty"`
Group string `json:"group,omitempty"`
Installed []string `json:"installed,omitempty"`
Merge string `json:"merge,omitempty"`
Modules []string `json:"modules"`
Packages []TakenVersion `json:"packages,omitempty"`
Programs []Program `json:"programs,omitempty"`
Refused []FetchRefusal `json:"refused,omitempty"`
Trees map[string]ModuleTree `json:"trees,omitempty"`
Workspace string `json:"workspace"`
}
// FetchRefusal is a TypeScript module whose packages the fetch did not install, with why.
type FetchRefusal struct {
Module string `json:"module"`
Reason string `json:"reason"`
}
// LevelAnswerDigestNeedsItem is a type of the contract.
type LevelAnswerDigestNeedsItem struct {
Needs []string `json:"needs,omitempty"`
Package string `json:"package,omitempty"`
}
// LevelAnswerDigestPackagesItem is a type of the contract.
type LevelAnswerDigestPackagesItem struct {
Digest string `json:"digest"`
Package string `json:"package"`
}
// LevelAnswerDigest is a type of the contract.
type LevelAnswerDigest struct {
Beside []string `json:"beside,omitempty"`
JudgedBy string `json:"judged_by,omitempty"`
Level string `json:"level,omitempty"`
Needs []LevelAnswerDigestNeedsItem `json:"needs,omitempty"`
Packages []LevelAnswerDigestPackagesItem `json:"packages,omitempty"`
WithoutTests []string `json:"without_tests,omitempty"`
}
// LevelAnswerKeptItem is a type of the contract.
type LevelAnswerKeptItem struct {
Digest string `json:"digest,omitempty"`
Package string `json:"package,omitempty"`
Tests int64 `json:"tests,omitempty"`
}
// LevelAnswerUnmetItem is a type of the contract.
type LevelAnswerUnmetItem struct {
Needs []string `json:"needs,omitempty"`
Package string `json:"package,omitempty"`
}
// LevelAnswer is one level of a check ask: the digest's answer, the kept verdicts taken, one test result per test step run, and the packages the node could not test.
type LevelAnswer struct {
Digest *LevelAnswerDigest `json:"digest,omitempty"`
Judged string `json:"judged,omitempty"`
Kept []LevelAnswerKeptItem `json:"kept,omitempty"`
Level string `json:"level"`
Tests []any `json:"tests,omitempty"`
Unmet []LevelAnswerUnmetItem `json:"unmet,omitempty"`
}
// ModuleTree is the tree of one module directory in a merge preview: its git tree, the digest of its manifest, the lock files' digests and the digests of the named paths.
type ModuleTree struct {
Locks map[string]string `json:"locks,omitempty"`
Manifest string `json:"manifest"`
// no longer filled (ADR 0593 section 2); kept so a preview written before still reads
Packages []string `json:"packages,omitempty"`
Paths map[string]string `json:"paths,omitempty"`
Tree string `json:"tree"`
}
// Pause is whether the node takes no new ask.
type Pause struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
By string `json:"by,omitempty"`
Paused bool `json:"paused"`
// the layout version
V int64 `json:"v,omitempty"`
}
// PlacedBeside is a sibling repository placed as a plain directory under the workspace's beside directory.
type PlacedBeside struct {
Commit string `json:"commit"`
Dir string `json:"dir"`
Repository string `json:"repository"`
}
// Program is a changed file that is a compiled program (issue 1577): its path, its executable format, and the commit of the branch that added it when the merge's tree no longer holds it.
type Program struct {
Commit string `json:"commit,omitempty"`
// ELF, Mach-O or PE
Kind string `json:"kind"`
Path string `json:"path"`
}
// RunAnswer is what a run ask's step answers: whether this run built the program or took the one kept under its key, the key, the program's exit, the last line of its standard output and the first of its standard error.
type RunAnswer struct {
Built bool `json:"built"`
Exit int64 `json:"exit"`
Key string `json:"key"`
// raw when it is JSON, else a JSON string
Output any `json:"output,omitempty"`
Said string `json:"said,omitempty"`
}
// RunHead is one commit a run's program reads.
type RunHead struct {
Commit string `json:"commit"`
Repository string `json:"repository"`
}
// RunInput is a run's input by reference: the seat verb the asker serves it on (seat:<seat>.<verb>), the sha256 of its bytes and its size, at most 256 KiB.
type RunInput struct {
// 64 lowercase hex digits
Digest string `json:"digest"`
// bytes
Size int64 `json:"size"`
Verb string `json:"verb"`
}
// RunJob is a run ask's job: where its program is built, the heads it reads (each laid read-only at its repository's path), its input by reference, its arguments and what it is for.
type RunJob struct {
// the program's arguments, each a word or a flag
Args []string `json:"args,omitempty"`
// the commits the program reads, a repository at most once
Heads []RunHead `json:"heads"`
Input RunInput `json:"input"`
Program RunProgram `json:"program"`
// what the run is for, for a reader of the ask
Reader string `json:"reader,omitempty"`
}
// RunProgram is where a run's program is built: the repository and full commit fetched, the Go module's directory in it and the program's import path.
type RunProgram struct {
Commit string `json:"commit"`
Dir string `json:"dir"`
Package string `json:"package"`
Repository string `json:"repository"`
}
// Step is one step a build module runs on a node.
type Step struct {
// when the bus gives the ask again, for the state again (RFC 3339 time)
AgainAt *time.Time `json:"again-at,omitempty"`
// when (RFC 3339 time)
Ended *time.Time `json:"ended,omitempty"`
ID string `json:"id"`
Node string `json:"node"`
Owner string `json:"owner,omitempty"`
// true when the step ended on a fault that passes (a transport fault), so a failed end after the last run says so
Passing bool `json:"passing,omitempty"`
Phase string `json:"phase,omitempty"`
// when (RFC 3339 time)
PhaseAt *time.Time `json:"phase-at,omitempty"`
Reason string `json:"reason,omitempty"`
Result *StepResult `json:"result,omitempty"`
// which run of the ask this is, counted by the bus's delivery count (1 for the first)
Run int64 `json:"run,omitempty"`
// when (RFC 3339 time)
Started time.Time `json:"started"`
// running, again (ended on a transport fault, to be given again by the bus after again-at), passed, failed, refused or dropped (ended by the verb drop, its cause the reason)
State string `json:"state"`
Tool string `json:"tool"`
// the layout version
V int64 `json:"v,omitempty"`
What string `json:"what,omitempty"`
}
// StepAskBuild is a type of the contract.
type StepAskBuild struct {
Artifacts []AskArtifact `json:"artifacts"`
Fetch *Fetch `json:"fetch,omitempty"`
Fp string `json:"fp,omitempty"`
Module string `json:"module"`
Path string `json:"path,omitempty"`
Publish bool `json:"publish,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// StepAskCheck is a type of the contract.
type StepAskCheck struct {
Fetch Fetch `json:"fetch"`
Kept bool `json:"kept,omitempty"`
Levels []string `json:"levels"`
// the node names the check's tests run against
NodeNames []string `json:"node-names,omitempty"`
Packages []string `json:"packages,omitempty"`
Run string `json:"run,omitempty"`
Runner string `json:"runner,omitempty"`
RunnerWhen string `json:"runner_when,omitempty"`
// the toolchain the checker agreed for the language (ADR 0584 clause 2): a node on another declines the check
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// StepAskCompose is a type of the contract.
type StepAskCompose struct {
Dir string `json:"dir"`
Fetch Fetch `json:"fetch"`
Package string `json:"package"`
Reader string `json:"reader,omitempty"`
// the compose-candidate request, in one of two forms: the request as a JSON object, or, for one near the bus's message limit, a JSON string "gzip+base64:" followed by the base64 of the request object gzip-compressed; a holder that does not know the packed form refuses it, naming that it holds no request object
Request any `json:"request"`
}
// StepAsk is one ask of a build module.
type StepAsk struct {
Asker string `json:"asker"`
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Build *StepAskBuild `json:"build,omitempty"`
Check *StepAskCheck `json:"check,omitempty"`
Compose *StepAskCompose `json:"compose,omitempty"`
ID string `json:"id"`
// build, check or compose
Kind string `json:"kind"`
// go, typescript or image
Language string `json:"language"`
Needs []string `json:"needs,omitempty"`
// package to the tagged version a build pins
Packages map[string]string `json:"packages,omitempty"`
// a run: a program built from a change and run in the build seat's sandbox over the heads, its input asked of a verb of the asker's seat; the Go seat's check stream alone carries it, as a compose
Run *RunJob `json:"run,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
}
// StepResult is what a step answered, by the kind of ask: a build's artifacts, toolchain, imports and out-of-step modules; a check's fetch and levels; a compose's built, key and verdict; a run's built, key, exit, output and said; a declined ask's declined, needs and lacks. The fields of the kinds do not meet, so one layout holds the five.
type StepResult struct {
Artifacts []BuiltArtifact `json:"artifacts,omitempty"`
Built bool `json:"built,omitempty"`
// the holder declined the ask: its node lacks what the ask needs
Declined bool `json:"declined,omitempty"`
// a run's program's exit status
Exit int64 `json:"exit,omitempty"`
Fetch *FetchAnswer `json:"fetch,omitempty"`
Imports []string `json:"imports,omitempty"`
Key string `json:"key,omitempty"`
// what the holder's node lacks of it
Lacks []string `json:"lacks,omitempty"`
Levels []LevelAnswer `json:"levels,omitempty"`
// what the declined ask needs
Needs []string `json:"needs,omitempty"`
OutOfStep []string `json:"out-of-step,omitempty"`
// a run's program's last line of standard output: raw when it is JSON, else a JSON string
Output any `json:"output,omitempty"`
// a run's program's first line of standard error, or why the step could not run it
Said string `json:"said,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
// the compose-candidate verdict (the composer's own layout)
Verdict any `json:"verdict,omitempty"`
}
// TakenVersion is of a directory whose go.mod requires an asked mesh package, the version it is built against: the asked one, or go.mod's when it names a newer one, said.
type TakenVersion struct {
Asked string `json:"asked"`
Built string `json:"built"`
Dir string `json:"dir"`
Named string `json:"named"`
Package string `json:"package"`
Said string `json:"said,omitempty"`
Sum string `json:"sum,omitempty"`
}
// Toolchain is the toolchain a node reports.
type Toolchain struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
// go or typescript
Language string `json:"language"`
Recipe string `json:"recipe"`
// the layout version
V int64 `json:"v,omitempty"`
Version string `json:"version"`
}
// ToolchainUsed is the toolchain a build was made with: the language, the installed version and the build module's recipe.
type ToolchainUsed struct {
Language string `json:"language"`
Recipe string `json:"recipe"`
Version string `json:"version"`
}
// CurrentInput is what current takes.
type CurrentInput struct {
}
// CurrentAnswer is what current answers.
type CurrentAnswer = map[string]any
// PauseInput is what pause takes.
type PauseInput struct {
}
// PauseAnswer is what pause answers.
type PauseAnswer = map[string]any
// ResumeInput is what resume takes.
type ResumeInput struct {
}
// ResumeAnswer is what resume answers.
type ResumeAnswer = map[string]any
// DropInput is what drop takes.
type DropInput struct {
// who drops it
By string `json:"by,omitempty"`
// the ask's id
ID string `json:"id"`
// why the caller no longer waits
Why string `json:"why"`
}
// DropAnswer is what drop answers.
type DropAnswer = map[string]any
// DeliveryAccept is the body of delivery.
type DeliveryAccept = StepAsk
// CheckAccept is the body of check.
type CheckAccept = StepAsk
// RecheckAccept is the body of recheck.
type RecheckAccept = StepAsk
// StepsByNodeIDValue is one value of the state steps under the key <node>.<id>.
type StepsByNodeIDValue = Step
// PausesByPausedNodeValue is one value of the state pauses under the key paused.<node>.
type PausesByPausedNodeValue = Pause
// PausesByDroppedIDValue is one value of the state pauses under the key dropped.<id>.
type PausesByDroppedIDValue = Drop
// PausesByCapacityNodeValue is one value of the state pauses under the key capacity.<node>.
type PausesByCapacityNodeValue = Capacity
// ToolchainsByNodeLanguageValue is one value of the state toolchains under the key <node>.<language>.
type ToolchainsByNodeLanguageValue = Toolchain
@@ -1,88 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package nodebuildgo
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/node-build-go/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a running step", subject: "", given: "{\"id\":\"a1b2\",\"node\":\"ace\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}", wire: "{\"id\":\"a1b2\",\"node\":\"ace\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a paused node", subject: "", given: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@shanks\",\"paused\":true,\"v\":1}", wire: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@shanks\",\"paused\":true,\"v\":1}",
decode: func(b []byte) (any, error) {
var v PausesByPausedNodeValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a node's capacity", subject: "", given: "{\"configured\":2,\"effective\":2,\"v\":1,\"why\":\"the configured steps fit the cores\"}", wire: "{\"configured\":2,\"effective\":2,\"v\":1,\"why\":\"the configured steps fit the cores\"}",
decode: func(b []byte) (any, error) {
var v PausesByCapacityNodeValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a node's toolchain", subject: "", given: "{\"language\":\"go\",\"recipe\":\"1\",\"v\":1,\"version\":\"1.26.0\"}", wire: "{\"language\":\"go\",\"recipe\":\"1\",\"v\":1,\"version\":\"1.26.0\"}",
decode: func(b []byte) (any, error) {
var v ToolchainsByNodeLanguageValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a build ask", subject: "mesh.seat.node-build-go.accept.delivery", given: "{\"asker\":\"mesh-delivery-builder\",\"build\":{\"artifacts\":[{\"artifact\":\"go\"}],\"module\":\"nats\"},\"id\":\"a1b2\",\"kind\":\"build\",\"language\":\"go\"}", wire: "{\"asker\":\"mesh-delivery-builder\",\"build\":{\"artifacts\":[{\"artifact\":\"go\"}],\"module\":\"nats\"},\"id\":\"a1b2\",\"kind\":\"build\",\"language\":\"go\"}",
decode: func(b []byte) (any, error) { var v DeliveryAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-go\\.accept\\.delivery$")},
{name: "a check ask with its fetch, siblings and levels", subject: "mesh.seat.node-build-go.accept.check", given: "{\"asker\":\"mesh-delivery-checker\",\"at\":\"2026-11-05T10:00:00Z\",\"check\":{\"fetch\":{\"base\":\"89abcdef0123456789abcdef0123456789abcdef\",\"beside\":[{\"commit\":\"fedcba9876543210fedcba9876543210fedcba98\",\"repository\":\"novox/mesh-sdk\"}],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"packages\":{\"git.novox.be/novox/mesh-sdk/go\":\"fedcba9876543210fedcba9876543210fedcba98\"},\"ref\":\"refs/pull/7/head\",\"repository\":\"novox/mesh-catalog\"},\"kept\":true,\"levels\":[\"unit\",\"integration\"],\"node-names\":[\"ace\",\"g14\"],\"toolchain\":{\"language\":\"go\",\"recipe\":\"2\",\"version\":\"1.26.0\"}},\"id\":\"c3d4\",\"kind\":\"check\",\"language\":\"go\",\"v\":1}", wire: "{\"asker\":\"mesh-delivery-checker\",\"at\":\"2026-11-05T10:00:00Z\",\"check\":{\"fetch\":{\"base\":\"89abcdef0123456789abcdef0123456789abcdef\",\"beside\":[{\"commit\":\"fedcba9876543210fedcba9876543210fedcba98\",\"repository\":\"novox/mesh-sdk\"}],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"packages\":{\"git.novox.be/novox/mesh-sdk/go\":\"fedcba9876543210fedcba9876543210fedcba98\"},\"ref\":\"refs/pull/7/head\",\"repository\":\"novox/mesh-catalog\"},\"kept\":true,\"levels\":[\"unit\",\"integration\"],\"node-names\":[\"ace\",\"g14\"],\"toolchain\":{\"language\":\"go\",\"recipe\":\"2\",\"version\":\"1.26.0\"}},\"id\":\"c3d4\",\"kind\":\"check\",\"language\":\"go\",\"v\":1}",
decode: func(b []byte) (any, error) { var v CheckAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-go\\.accept\\.check$")},
{name: "a finished build step with its artifacts", subject: "", given: "{\"ended\":\"2026-11-05T10:03:00Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"result\":{\"artifacts\":[{\"artifact\":\"go\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"reference\":\"container-image-registry/nats/go@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}],\"imports\":[\"git.novox.be/novox/mesh-sdk/go\"],\"toolchain\":{\"language\":\"go\",\"recipe\":\"1\",\"version\":\"1.26.0\"}},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"build\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:03:00Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"result\":{\"artifacts\":[{\"artifact\":\"go\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"reference\":\"container-image-registry/nats/go@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}],\"imports\":[\"git.novox.be/novox/mesh-sdk/go\"],\"toolchain\":{\"language\":\"go\",\"recipe\":\"1\",\"version\":\"1.26.0\"}},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"build\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a finished check step with its levels", subject: "", given: "{\"ended\":\"2026-11-05T10:06:00Z\",\"id\":\"c3d4\",\"node\":\"ace\",\"result\":{\"fetch\":{\"base\":\"abcdef0123456789abcdef0123456789abcdef01\",\"changed\":[\"a.go\",\"modules/m/main.go\"],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"merge\":\"fedcba9876543210fedcba9876543210fedcba98\",\"modules\":[\".\"],\"trees\":{\"modules/m\":{\"locks\":{\"go.sum\":\"c5fc83c01e92404452b986527d239140ccf9a48b88e0c268fbf38c2e1429e9c9\"},\"manifest\":\"ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356\",\"tree\":\"1111111111111111111111111111111111111111\"}},\"workspace\":\"mvii1iwu5414e4\"},\"levels\":[{\"digest\":{\"level\":\"unit\",\"packages\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"package\":\"./modules/a\"}]},\"kept\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"package\":\"./modules/a\",\"tests\":12}],\"level\":\"unit\",\"tests\":[{\"package\":\"./modules/b\",\"pass\":true}],\"unmet\":[{\"needs\":[\"docker\"],\"package\":\"./modules/c\"}]}]},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:06:00Z\",\"id\":\"c3d4\",\"node\":\"ace\",\"result\":{\"fetch\":{\"base\":\"abcdef0123456789abcdef0123456789abcdef01\",\"changed\":[\"a.go\",\"modules/m/main.go\"],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"merge\":\"fedcba9876543210fedcba9876543210fedcba98\",\"modules\":[\".\"],\"trees\":{\"modules/m\":{\"locks\":{\"go.sum\":\"c5fc83c01e92404452b986527d239140ccf9a48b88e0c268fbf38c2e1429e9c9\"},\"manifest\":\"ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356\",\"tree\":\"1111111111111111111111111111111111111111\"}},\"workspace\":\"mvii1iwu5414e4\"},\"levels\":[{\"digest\":{\"level\":\"unit\",\"packages\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"package\":\"./modules/a\"}]},\"kept\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"package\":\"./modules/a\",\"tests\":12}],\"level\":\"unit\",\"tests\":[{\"package\":\"./modules/b\",\"pass\":true}],\"unmet\":[{\"needs\":[\"docker\"],\"package\":\"./modules/c\"}]}]},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a declined step", subject: "", given: "{\"id\":\"c3d5\",\"node\":\"ace\",\"result\":{\"declined\":true,\"lacks\":[\"docker\"],\"needs\":[\"docker\"]},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"refused\",\"tool\":\"check\",\"v\":1}", wire: "{\"id\":\"c3d5\",\"node\":\"ace\",\"result\":{\"declined\":true,\"lacks\":[\"docker\"],\"needs\":[\"docker\"]},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"refused\",\"tool\":\"check\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a finished check step whose head does not merge", subject: "", given: "{\"ended\":\"2026-11-05T10:01:00Z\",\"id\":\"c3d5\",\"node\":\"ace\",\"result\":{\"fetch\":{\"base\":\"abcdef0123456789abcdef0123456789abcdef01\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"conflicts\":[\"a.go\",\"sub/b.go\"],\"modules\":[\".\"],\"workspace\":\"mvii1iwz5050eb\"}},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:01:00Z\",\"id\":\"c3d5\",\"node\":\"ace\",\"result\":{\"fetch\":{\"base\":\"abcdef0123456789abcdef0123456789abcdef01\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"conflicts\":[\"a.go\",\"sub/b.go\"],\"modules\":[\".\"],\"workspace\":\"mvii1iwz5050eb\"}},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a run ask of the checking program over two heads", subject: "mesh.seat.node-build-go.accept.check", given: "{\"asker\":\"mesh-delivery-checker\",\"at\":\"2026-11-05T10:00:00Z\",\"id\":\"r5e6\",\"kind\":\"check\",\"language\":\"go\",\"run\":{\"args\":[\"-verdict\"],\"heads\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-delivery\"},{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\"}],\"input\":{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"size\":7,\"verb\":\"seat:mesh-delivery-checker.input\"},\"program\":{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"dir\":\"modules/mesh-delivery-checker\",\"package\":\"./cmd/mesh-checking-program\",\"repository\":\"novox/mesh-delivery\"},\"reader\":\"checking program of mesh-delivery head\"},\"v\":1}", wire: "{\"asker\":\"mesh-delivery-checker\",\"at\":\"2026-11-05T10:00:00Z\",\"id\":\"r5e6\",\"kind\":\"check\",\"language\":\"go\",\"run\":{\"args\":[\"-verdict\"],\"heads\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-delivery\"},{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\"}],\"input\":{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"size\":7,\"verb\":\"seat:mesh-delivery-checker.input\"},\"program\":{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"dir\":\"modules/mesh-delivery-checker\",\"package\":\"./cmd/mesh-checking-program\",\"repository\":\"novox/mesh-delivery\"},\"reader\":\"checking program of mesh-delivery head\"},\"v\":1}",
decode: func(b []byte) (any, error) { var v CheckAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-go\\.accept\\.check$")},
{name: "a finished run step whose program exited non-zero", subject: "", given: "{\"ended\":\"2026-11-05T10:01:00Z\",\"id\":\"r5e6\",\"node\":\"ace\",\"result\":{\"built\":true,\"exit\":2,\"key\":\"program-0123456789abcdef\",\"said\":\"the facts name no head\"},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"failed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:01:00Z\",\"id\":\"r5e6\",\"node\":\"ace\",\"result\":{\"built\":true,\"exit\":2,\"key\":\"program-0123456789abcdef\",\"said\":\"the facts name no head\"},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"failed\",\"tool\":\"check\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a step ended on a transport fault, given again by the bus", subject: "", given: "{\"again-at\":\"2026-11-05T10:01:30Z\",\"ended\":\"2026-11-05T10:00:30Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"passing\":true,\"reason\":\"fetching the commit: kex_exchange_identification: read: Connection reset by peer\",\"run\":1,\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"again\",\"tool\":\"build\",\"v\":1}", wire: "{\"again-at\":\"2026-11-05T10:01:30Z\",\"ended\":\"2026-11-05T10:00:30Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"passing\":true,\"reason\":\"fetching the commit: kex_exchange_identification: read: Connection reset by peer\",\"run\":1,\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"again\",\"tool\":\"build\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "an ask dropped by the caller that no longer waits", subject: "", given: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"mesh-delivery-builder\",\"v\":1,\"why\":\"a newer fingerprint supersedes it\"}", wire: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"mesh-delivery-builder\",\"v\":1,\"why\":\"a newer fingerprint supersedes it\"}",
decode: func(b []byte) (any, error) { var v PausesByDroppedIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "drop names the ask and why", subject: "", given: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}", wire: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}",
decode: func(b []byte) (any, error) { var v DropInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
-3
View File
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/nodebuildgo
go 1.26.0
@@ -1,678 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package nodebuildimage is the contract of the seat "node-build-image", defined whole (seats/node-build-image/seat.json): The image build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.
package nodebuildimage
import (
"bytes"
"encoding/json"
"errors"
"strings"
"time"
)
// Seat is the seat's name.
const Seat = "node-build-image"
const (
VerbCurrent = "current"
VerbPause = "pause"
VerbResume = "resume"
VerbDrop = "drop"
)
const (
AcceptDelivery = "delivery"
AcceptCheck = "check"
AcceptRecheck = "recheck"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop}
}
// AcceptSubjectDelivery is where delivery is sent.
const AcceptSubjectDelivery = "mesh.seat.node-build-image.accept.delivery"
// AcceptSubjectCheck is where check is sent.
const AcceptSubjectCheck = "mesh.seat.node-build-image.accept.check"
// AcceptSubjectRecheck is where recheck is sent.
const AcceptSubjectRecheck = "mesh.seat.node-build-image.accept.recheck"
const (
StateSteps = "steps"
StatePauses = "pauses"
StateToolchains = "toolchains"
)
// StepsByNodeIDKey is the key of one value of the state steps under the form "<node>.<id>".
func StepsByNodeIDKey(node, id string) string { return node + "." + id }
// ParseStepsByNodeIDKey reads the parts of a key of the form "<node>.<id>", in the order of the form; the last result is false for a key of another form.
func ParseStepsByNodeIDKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeStepsByNodeIDValue reads one value of the state steps under the form "<node>.<id>", refusing a field StepsByNodeIDValue does not know and any text after the value.
func DecodeStepsByNodeIDValue(raw []byte) (StepsByNodeIDValue, error) {
var v StepsByNodeIDValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByPausedNodeKey is the key of one value of the state pauses under the form "paused.<node>".
func PausesByPausedNodeKey(node string) string { return "paused." + node }
// ParsePausesByPausedNodeKey reads the parts of a key of the form "paused.<node>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByPausedNodeKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "paused.") {
return "", false
}
rest = rest[7:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByPausedNodeValue reads one value of the state pauses under the form "paused.<node>", refusing a field PausesByPausedNodeValue does not know and any text after the value.
func DecodePausesByPausedNodeValue(raw []byte) (PausesByPausedNodeValue, error) {
var v PausesByPausedNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByDroppedIDKey is the key of one value of the state pauses under the form "dropped.<id>".
func PausesByDroppedIDKey(id string) string { return "dropped." + id }
// ParsePausesByDroppedIDKey reads the parts of a key of the form "dropped.<id>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByDroppedIDKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "dropped.") {
return "", false
}
rest = rest[8:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByDroppedIDValue reads one value of the state pauses under the form "dropped.<id>", refusing a field PausesByDroppedIDValue does not know and any text after the value.
func DecodePausesByDroppedIDValue(raw []byte) (PausesByDroppedIDValue, error) {
var v PausesByDroppedIDValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByCapacityNodeKey is the key of one value of the state pauses under the form "capacity.<node>".
func PausesByCapacityNodeKey(node string) string { return "capacity." + node }
// ParsePausesByCapacityNodeKey reads the parts of a key of the form "capacity.<node>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByCapacityNodeKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "capacity.") {
return "", false
}
rest = rest[9:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByCapacityNodeValue reads one value of the state pauses under the form "capacity.<node>", refusing a field PausesByCapacityNodeValue does not know and any text after the value.
func DecodePausesByCapacityNodeValue(raw []byte) (PausesByCapacityNodeValue, error) {
var v PausesByCapacityNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// ToolchainsByNodeLanguageKey is the key of one value of the state toolchains under the form "<node>.<language>".
func ToolchainsByNodeLanguageKey(node, language string) string { return node + "." + language }
// ParseToolchainsByNodeLanguageKey reads the parts of a key of the form "<node>.<language>", in the order of the form; the last result is false for a key of another form.
func ParseToolchainsByNodeLanguageKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeToolchainsByNodeLanguageValue reads one value of the state toolchains under the form "<node>.<language>", refusing a field ToolchainsByNodeLanguageValue does not know and any text after the value.
func DecodeToolchainsByNodeLanguageValue(raw []byte) (ToolchainsByNodeLanguageValue, error) {
var v ToolchainsByNodeLanguageValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// AskArtifact is one artifact of a build ask: built from the fetched tree, or copied from an upstream pin.
type AskArtifact struct {
Artifact string `json:"artifact"`
From string `json:"from,omitempty"`
Seat string `json:"seat,omitempty"`
Version string `json:"version,omitempty"`
}
// BuildAnswer is a type of the contract.
type BuildAnswer struct {
Artifacts []BuiltArtifact `json:"artifacts"`
Imports []string `json:"imports,omitempty"`
OutOfStep []string `json:"out-of-step,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// BuiltArtifact is one artifact a build made: its digest and the reference it was published under.
type BuiltArtifact struct {
Artifact string `json:"artifact"`
Digest string `json:"digest"`
Reference string `json:"reference,omitempty"`
}
// Capacity is how many steps the node runs at once.
type Capacity struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
BuildHours string `json:"build-hours,omitempty"`
BuildHoursFault string `json:"build-hours-fault,omitempty"`
ByCpu int64 `json:"by-cpu,omitempty"`
Configured int64 `json:"configured"`
ConfiguredFrom string `json:"configured-from,omitempty"`
CoresPerStep float64 `json:"cores-per-step,omitempty"`
Effective int64 `json:"effective"`
Ineligible string `json:"ineligible,omitempty"`
OutsideHours bool `json:"outside-hours,omitempty"`
QuotaCores float64 `json:"quota-cores,omitempty"`
QuotaFrom string `json:"quota-from,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Why string `json:"why"`
}
// CheckAnswer is a type of the contract.
type CheckAnswer struct {
Fetch FetchAnswer `json:"fetch"`
Levels []LevelAnswer `json:"levels,omitempty"`
}
// ComposeAnswer is a type of the contract.
type ComposeAnswer struct {
Built bool `json:"built"`
Key string `json:"key,omitempty"`
// the compose-candidate verdict
Verdict any `json:"verdict,omitempty"`
}
// Drop is an ask a caller no longer waits for.
type Drop struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
By string `json:"by,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Why string `json:"why"`
}
// FetchBesideItem is a type of the contract.
type FetchBesideItem struct {
Commit string `json:"commit"`
Repository string `json:"repository"`
}
// FetchPackage is the TypeScript module's group package: the group's tagged version of the SDK ({name, version}), placed from the registry in each member whatever its lock names, or the group's package member ({repository, commit, ref}), packed by the fetch and served to the members in place of the registry's.
type FetchPackage struct {
Commit string `json:"commit,omitempty"`
Name string `json:"name,omitempty"`
Ref string `json:"ref,omitempty"`
Repository string `json:"repository,omitempty"`
Version string `json:"version,omitempty"`
}
// Fetch is what a build module's fetch tool is asked: the repository and the full commit, the pull request's ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, the module's directory and named paths, the mesh packages to build against, and the sibling repositories placed beside.
type Fetch struct {
// the trunk commit a merge preview merges onto
Base string `json:"base,omitempty"`
// the sibling repositories placed beside the fetched tree
Beside []FetchBesideItem `json:"beside,omitempty"`
// the full commit
Commit string `json:"commit"`
// the module's directory in the repository ("." for its root), with paths
Dir string `json:"dir,omitempty"`
// the TypeScript module's group package: the group's tagged version of the SDK ({name, version}), placed from the registry in each member whatever its lock names, or the group's package member ({repository, commit, ref}), packed by the fetch and served to the members in place of the registry's
Package *FetchPackage `json:"package,omitempty"`
// the version (a full commit) of each mesh package to build against, by its module path
Packages map[string]string `json:"packages,omitempty"`
// the paths the module names, relative to dir
Paths []string `json:"paths,omitempty"`
// the pull request's ref, when only its head carries the commit
Ref string `json:"ref,omitempty"`
// <owner>/<name>
Repository string `json:"repository"`
}
// FetchAnswer is what a build module's fetch tool answers, whole: the workspace it made, the commit in it, the module directories found; and, when the call gave a base, the merge preview (the trunk commit, the merge commit, the files that conflict, the paths the merge changes, the compiled programs among them, the tree of each module directory). A head that does not merge cleanly is an answer, not an error: merge is empty and conflicts names the files. The Go module adds the sibling repositories placed and the package versions taken; the TypeScript module the directories installed and refused and the group's package.
type FetchAnswer struct {
Base string `json:"base,omitempty"`
Beside []PlacedBeside `json:"beside,omitempty"`
Changed []string `json:"changed,omitempty"`
Commit string `json:"commit"`
Conflicts []string `json:"conflicts,omitempty"`
Group string `json:"group,omitempty"`
Installed []string `json:"installed,omitempty"`
Merge string `json:"merge,omitempty"`
Modules []string `json:"modules"`
Packages []TakenVersion `json:"packages,omitempty"`
Programs []Program `json:"programs,omitempty"`
Refused []FetchRefusal `json:"refused,omitempty"`
Trees map[string]ModuleTree `json:"trees,omitempty"`
Workspace string `json:"workspace"`
}
// FetchRefusal is a TypeScript module whose packages the fetch did not install, with why.
type FetchRefusal struct {
Module string `json:"module"`
Reason string `json:"reason"`
}
// LevelAnswerDigestNeedsItem is a type of the contract.
type LevelAnswerDigestNeedsItem struct {
Needs []string `json:"needs,omitempty"`
Package string `json:"package,omitempty"`
}
// LevelAnswerDigestPackagesItem is a type of the contract.
type LevelAnswerDigestPackagesItem struct {
Digest string `json:"digest"`
Package string `json:"package"`
}
// LevelAnswerDigest is a type of the contract.
type LevelAnswerDigest struct {
Beside []string `json:"beside,omitempty"`
JudgedBy string `json:"judged_by,omitempty"`
Level string `json:"level,omitempty"`
Needs []LevelAnswerDigestNeedsItem `json:"needs,omitempty"`
Packages []LevelAnswerDigestPackagesItem `json:"packages,omitempty"`
WithoutTests []string `json:"without_tests,omitempty"`
}
// LevelAnswerKeptItem is a type of the contract.
type LevelAnswerKeptItem struct {
Digest string `json:"digest,omitempty"`
Package string `json:"package,omitempty"`
Tests int64 `json:"tests,omitempty"`
}
// LevelAnswerUnmetItem is a type of the contract.
type LevelAnswerUnmetItem struct {
Needs []string `json:"needs,omitempty"`
Package string `json:"package,omitempty"`
}
// LevelAnswer is one level of a check ask: the digest's answer, the kept verdicts taken, one test result per test step run, and the packages the node could not test.
type LevelAnswer struct {
Digest *LevelAnswerDigest `json:"digest,omitempty"`
Judged string `json:"judged,omitempty"`
Kept []LevelAnswerKeptItem `json:"kept,omitempty"`
Level string `json:"level"`
Tests []any `json:"tests,omitempty"`
Unmet []LevelAnswerUnmetItem `json:"unmet,omitempty"`
}
// ModuleTree is the tree of one module directory in a merge preview: its git tree, the digest of its manifest, the lock files' digests and the digests of the named paths.
type ModuleTree struct {
Locks map[string]string `json:"locks,omitempty"`
Manifest string `json:"manifest"`
// no longer filled (ADR 0593 section 2); kept so a preview written before still reads
Packages []string `json:"packages,omitempty"`
Paths map[string]string `json:"paths,omitempty"`
Tree string `json:"tree"`
}
// Pause is whether the node takes no new ask.
type Pause struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
By string `json:"by,omitempty"`
Paused bool `json:"paused"`
// the layout version
V int64 `json:"v,omitempty"`
}
// PlacedBeside is a sibling repository placed as a plain directory under the workspace's beside directory.
type PlacedBeside struct {
Commit string `json:"commit"`
Dir string `json:"dir"`
Repository string `json:"repository"`
}
// Program is a changed file that is a compiled program (issue 1577): its path, its executable format, and the commit of the branch that added it when the merge's tree no longer holds it.
type Program struct {
Commit string `json:"commit,omitempty"`
// ELF, Mach-O or PE
Kind string `json:"kind"`
Path string `json:"path"`
}
// RunAnswer is what a run ask's step answers: whether this run built the program or took the one kept under its key, the key, the program's exit, the last line of its standard output and the first of its standard error.
type RunAnswer struct {
Built bool `json:"built"`
Exit int64 `json:"exit"`
Key string `json:"key"`
// raw when it is JSON, else a JSON string
Output any `json:"output,omitempty"`
Said string `json:"said,omitempty"`
}
// RunHead is one commit a run's program reads.
type RunHead struct {
Commit string `json:"commit"`
Repository string `json:"repository"`
}
// RunInput is a run's input by reference: the seat verb the asker serves it on (seat:<seat>.<verb>), the sha256 of its bytes and its size, at most 256 KiB.
type RunInput struct {
// 64 lowercase hex digits
Digest string `json:"digest"`
// bytes
Size int64 `json:"size"`
Verb string `json:"verb"`
}
// RunJob is a run ask's job: where its program is built, the heads it reads (each laid read-only at its repository's path), its input by reference, its arguments and what it is for.
type RunJob struct {
// the program's arguments, each a word or a flag
Args []string `json:"args,omitempty"`
// the commits the program reads, a repository at most once
Heads []RunHead `json:"heads"`
Input RunInput `json:"input"`
Program RunProgram `json:"program"`
// what the run is for, for a reader of the ask
Reader string `json:"reader,omitempty"`
}
// RunProgram is where a run's program is built: the repository and full commit fetched, the Go module's directory in it and the program's import path.
type RunProgram struct {
Commit string `json:"commit"`
Dir string `json:"dir"`
Package string `json:"package"`
Repository string `json:"repository"`
}
// Step is one step a build module runs on a node.
type Step struct {
// when the bus gives the ask again, for the state again (RFC 3339 time)
AgainAt *time.Time `json:"again-at,omitempty"`
// when (RFC 3339 time)
Ended *time.Time `json:"ended,omitempty"`
ID string `json:"id"`
Node string `json:"node"`
Owner string `json:"owner,omitempty"`
// true when the step ended on a fault that passes (a transport fault), so a failed end after the last run says so
Passing bool `json:"passing,omitempty"`
Phase string `json:"phase,omitempty"`
// when (RFC 3339 time)
PhaseAt *time.Time `json:"phase-at,omitempty"`
Reason string `json:"reason,omitempty"`
Result *StepResult `json:"result,omitempty"`
// which run of the ask this is, counted by the bus's delivery count (1 for the first)
Run int64 `json:"run,omitempty"`
// when (RFC 3339 time)
Started time.Time `json:"started"`
// running, again (ended on a transport fault, to be given again by the bus after again-at), passed, failed, refused or dropped (ended by the verb drop, its cause the reason)
State string `json:"state"`
Tool string `json:"tool"`
// the layout version
V int64 `json:"v,omitempty"`
What string `json:"what,omitempty"`
}
// StepAskBuild is a type of the contract.
type StepAskBuild struct {
Artifacts []AskArtifact `json:"artifacts"`
Fetch *Fetch `json:"fetch,omitempty"`
Fp string `json:"fp,omitempty"`
Module string `json:"module"`
Path string `json:"path,omitempty"`
Publish bool `json:"publish,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// StepAskCheck is a type of the contract.
type StepAskCheck struct {
Fetch Fetch `json:"fetch"`
Kept bool `json:"kept,omitempty"`
Levels []string `json:"levels"`
// the node names the check's tests run against
NodeNames []string `json:"node-names,omitempty"`
Packages []string `json:"packages,omitempty"`
Run string `json:"run,omitempty"`
Runner string `json:"runner,omitempty"`
RunnerWhen string `json:"runner_when,omitempty"`
// the toolchain the checker agreed for the language (ADR 0584 clause 2): a node on another declines the check
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// StepAskCompose is a type of the contract.
type StepAskCompose struct {
Dir string `json:"dir"`
Fetch Fetch `json:"fetch"`
Package string `json:"package"`
Reader string `json:"reader,omitempty"`
// the compose-candidate request, in one of two forms: the request as a JSON object, or, for one near the bus's message limit, a JSON string "gzip+base64:" followed by the base64 of the request object gzip-compressed; a holder that does not know the packed form refuses it, naming that it holds no request object
Request any `json:"request"`
}
// StepAsk is one ask of a build module.
type StepAsk struct {
Asker string `json:"asker"`
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Build *StepAskBuild `json:"build,omitempty"`
Check *StepAskCheck `json:"check,omitempty"`
Compose *StepAskCompose `json:"compose,omitempty"`
ID string `json:"id"`
// build, check or compose
Kind string `json:"kind"`
// go, typescript or image
Language string `json:"language"`
Needs []string `json:"needs,omitempty"`
// package to the tagged version a build pins
Packages map[string]string `json:"packages,omitempty"`
// a run: a program built from a change and run in the build seat's sandbox over the heads, its input asked of a verb of the asker's seat; the Go seat's check stream alone carries it, as a compose
Run *RunJob `json:"run,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
}
// StepResult is what a step answered, by the kind of ask: a build's artifacts, toolchain, imports and out-of-step modules; a check's fetch and levels; a compose's built, key and verdict; a run's built, key, exit, output and said; a declined ask's declined, needs and lacks. The fields of the kinds do not meet, so one layout holds the five.
type StepResult struct {
Artifacts []BuiltArtifact `json:"artifacts,omitempty"`
Built bool `json:"built,omitempty"`
// the holder declined the ask: its node lacks what the ask needs
Declined bool `json:"declined,omitempty"`
// a run's program's exit status
Exit int64 `json:"exit,omitempty"`
Fetch *FetchAnswer `json:"fetch,omitempty"`
Imports []string `json:"imports,omitempty"`
Key string `json:"key,omitempty"`
// what the holder's node lacks of it
Lacks []string `json:"lacks,omitempty"`
Levels []LevelAnswer `json:"levels,omitempty"`
// what the declined ask needs
Needs []string `json:"needs,omitempty"`
OutOfStep []string `json:"out-of-step,omitempty"`
// a run's program's last line of standard output: raw when it is JSON, else a JSON string
Output any `json:"output,omitempty"`
// a run's program's first line of standard error, or why the step could not run it
Said string `json:"said,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
// the compose-candidate verdict (the composer's own layout)
Verdict any `json:"verdict,omitempty"`
}
// TakenVersion is of a directory whose go.mod requires an asked mesh package, the version it is built against: the asked one, or go.mod's when it names a newer one, said.
type TakenVersion struct {
Asked string `json:"asked"`
Built string `json:"built"`
Dir string `json:"dir"`
Named string `json:"named"`
Package string `json:"package"`
Said string `json:"said,omitempty"`
Sum string `json:"sum,omitempty"`
}
// Toolchain is the toolchain a node reports.
type Toolchain struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
// go or typescript
Language string `json:"language"`
Recipe string `json:"recipe"`
// the layout version
V int64 `json:"v,omitempty"`
Version string `json:"version"`
}
// ToolchainUsed is the toolchain a build was made with: the language, the installed version and the build module's recipe.
type ToolchainUsed struct {
Language string `json:"language"`
Recipe string `json:"recipe"`
Version string `json:"version"`
}
// CurrentInput is what current takes.
type CurrentInput struct {
}
// CurrentAnswer is what current answers.
type CurrentAnswer = map[string]any
// PauseInput is what pause takes.
type PauseInput struct {
}
// PauseAnswer is what pause answers.
type PauseAnswer = map[string]any
// ResumeInput is what resume takes.
type ResumeInput struct {
}
// ResumeAnswer is what resume answers.
type ResumeAnswer = map[string]any
// DropInput is what drop takes.
type DropInput struct {
// who drops it
By string `json:"by,omitempty"`
// the ask's id
ID string `json:"id"`
// why the caller no longer waits
Why string `json:"why"`
}
// DropAnswer is what drop answers.
type DropAnswer = map[string]any
// DeliveryAccept is the body of delivery.
type DeliveryAccept = StepAsk
// CheckAccept is the body of check.
type CheckAccept = StepAsk
// RecheckAccept is the body of recheck.
type RecheckAccept = StepAsk
// StepsByNodeIDValue is one value of the state steps under the key <node>.<id>.
type StepsByNodeIDValue = Step
// PausesByPausedNodeValue is one value of the state pauses under the key paused.<node>.
type PausesByPausedNodeValue = Pause
// PausesByDroppedIDValue is one value of the state pauses under the key dropped.<id>.
type PausesByDroppedIDValue = Drop
// PausesByCapacityNodeValue is one value of the state pauses under the key capacity.<node>.
type PausesByCapacityNodeValue = Capacity
// ToolchainsByNodeLanguageValue is one value of the state toolchains under the key <node>.<language>.
type ToolchainsByNodeLanguageValue = Toolchain
@@ -1,74 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package nodebuildimage
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/node-build-image/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a running step", subject: "", given: "{\"id\":\"a1b2\",\"node\":\"ace\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}", wire: "{\"id\":\"a1b2\",\"node\":\"ace\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a paused node", subject: "", given: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@shanks\",\"paused\":true,\"v\":1}", wire: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@shanks\",\"paused\":true,\"v\":1}",
decode: func(b []byte) (any, error) {
var v PausesByPausedNodeValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a node's capacity", subject: "", given: "{\"configured\":2,\"effective\":2,\"v\":1,\"why\":\"the configured steps fit the cores\"}", wire: "{\"configured\":2,\"effective\":2,\"v\":1,\"why\":\"the configured steps fit the cores\"}",
decode: func(b []byte) (any, error) {
var v PausesByCapacityNodeValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a node's toolchain", subject: "", given: "{\"language\":\"go\",\"recipe\":\"1\",\"v\":1,\"version\":\"1.26.0\"}", wire: "{\"language\":\"go\",\"recipe\":\"1\",\"v\":1,\"version\":\"1.26.0\"}",
decode: func(b []byte) (any, error) {
var v ToolchainsByNodeLanguageValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a build ask", subject: "mesh.seat.node-build-image.accept.delivery", given: "{\"asker\":\"mesh-delivery-builder\",\"build\":{\"artifacts\":[{\"artifact\":\"go\"}],\"module\":\"nats\"},\"id\":\"a1b2\",\"kind\":\"build\",\"language\":\"go\"}", wire: "{\"asker\":\"mesh-delivery-builder\",\"build\":{\"artifacts\":[{\"artifact\":\"go\"}],\"module\":\"nats\"},\"id\":\"a1b2\",\"kind\":\"build\",\"language\":\"go\"}",
decode: func(b []byte) (any, error) { var v DeliveryAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-image\\.accept\\.delivery$")},
{name: "a step ended on a transport fault, given again by the bus", subject: "", given: "{\"again-at\":\"2026-11-05T10:01:30Z\",\"ended\":\"2026-11-05T10:00:30Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"passing\":true,\"reason\":\"fetching the commit: kex_exchange_identification: read: Connection reset by peer\",\"run\":1,\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"again\",\"tool\":\"build\",\"v\":1}", wire: "{\"again-at\":\"2026-11-05T10:01:30Z\",\"ended\":\"2026-11-05T10:00:30Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"passing\":true,\"reason\":\"fetching the commit: kex_exchange_identification: read: Connection reset by peer\",\"run\":1,\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"again\",\"tool\":\"build\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "an ask dropped by the caller that no longer waits", subject: "", given: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"mesh-delivery-builder\",\"v\":1,\"why\":\"a newer fingerprint supersedes it\"}", wire: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"mesh-delivery-builder\",\"v\":1,\"why\":\"a newer fingerprint supersedes it\"}",
decode: func(b []byte) (any, error) { var v PausesByDroppedIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "drop names the ask and why", subject: "", given: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}", wire: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}",
decode: func(b []byte) (any, error) { var v DropInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
-3
View File
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/nodebuildimage
go 1.26.0
@@ -1,678 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package nodebuildnode is the contract of the seat "node-build-node", defined whole (seats/node-build-node/seat.json): The Node build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.
package nodebuildnode
import (
"bytes"
"encoding/json"
"errors"
"strings"
"time"
)
// Seat is the seat's name.
const Seat = "node-build-node"
const (
VerbCurrent = "current"
VerbPause = "pause"
VerbResume = "resume"
VerbDrop = "drop"
)
const (
AcceptDelivery = "delivery"
AcceptCheck = "check"
AcceptRecheck = "recheck"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop}
}
// AcceptSubjectDelivery is where delivery is sent.
const AcceptSubjectDelivery = "mesh.seat.node-build-node.accept.delivery"
// AcceptSubjectCheck is where check is sent.
const AcceptSubjectCheck = "mesh.seat.node-build-node.accept.check"
// AcceptSubjectRecheck is where recheck is sent.
const AcceptSubjectRecheck = "mesh.seat.node-build-node.accept.recheck"
const (
StateSteps = "steps"
StatePauses = "pauses"
StateToolchains = "toolchains"
)
// StepsByNodeIDKey is the key of one value of the state steps under the form "<node>.<id>".
func StepsByNodeIDKey(node, id string) string { return node + "." + id }
// ParseStepsByNodeIDKey reads the parts of a key of the form "<node>.<id>", in the order of the form; the last result is false for a key of another form.
func ParseStepsByNodeIDKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeStepsByNodeIDValue reads one value of the state steps under the form "<node>.<id>", refusing a field StepsByNodeIDValue does not know and any text after the value.
func DecodeStepsByNodeIDValue(raw []byte) (StepsByNodeIDValue, error) {
var v StepsByNodeIDValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByPausedNodeKey is the key of one value of the state pauses under the form "paused.<node>".
func PausesByPausedNodeKey(node string) string { return "paused." + node }
// ParsePausesByPausedNodeKey reads the parts of a key of the form "paused.<node>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByPausedNodeKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "paused.") {
return "", false
}
rest = rest[7:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByPausedNodeValue reads one value of the state pauses under the form "paused.<node>", refusing a field PausesByPausedNodeValue does not know and any text after the value.
func DecodePausesByPausedNodeValue(raw []byte) (PausesByPausedNodeValue, error) {
var v PausesByPausedNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByDroppedIDKey is the key of one value of the state pauses under the form "dropped.<id>".
func PausesByDroppedIDKey(id string) string { return "dropped." + id }
// ParsePausesByDroppedIDKey reads the parts of a key of the form "dropped.<id>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByDroppedIDKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "dropped.") {
return "", false
}
rest = rest[8:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByDroppedIDValue reads one value of the state pauses under the form "dropped.<id>", refusing a field PausesByDroppedIDValue does not know and any text after the value.
func DecodePausesByDroppedIDValue(raw []byte) (PausesByDroppedIDValue, error) {
var v PausesByDroppedIDValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// PausesByCapacityNodeKey is the key of one value of the state pauses under the form "capacity.<node>".
func PausesByCapacityNodeKey(node string) string { return "capacity." + node }
// ParsePausesByCapacityNodeKey reads the parts of a key of the form "capacity.<node>", in the order of the form; the last result is false for a key of another form.
func ParsePausesByCapacityNodeKey(key string) (string, bool) {
rest := key
if !strings.HasPrefix(rest, "capacity.") {
return "", false
}
rest = rest[9:]
if rest == "" {
return "", false
}
v1 := rest
rest = ""
if rest != "" {
return "", false
}
return v1, true
}
// DecodePausesByCapacityNodeValue reads one value of the state pauses under the form "capacity.<node>", refusing a field PausesByCapacityNodeValue does not know and any text after the value.
func DecodePausesByCapacityNodeValue(raw []byte) (PausesByCapacityNodeValue, error) {
var v PausesByCapacityNodeValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// ToolchainsByNodeLanguageKey is the key of one value of the state toolchains under the form "<node>.<language>".
func ToolchainsByNodeLanguageKey(node, language string) string { return node + "." + language }
// ParseToolchainsByNodeLanguageKey reads the parts of a key of the form "<node>.<language>", in the order of the form; the last result is false for a key of another form.
func ParseToolchainsByNodeLanguageKey(key string) (string, string, bool) {
rest := key
v0, after0, found0 := strings.Cut(rest, ".")
if !found0 || v0 == "" {
return "", "", false
}
rest = after0
if rest == "" {
return "", "", false
}
v2 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v0, v2, true
}
// DecodeToolchainsByNodeLanguageValue reads one value of the state toolchains under the form "<node>.<language>", refusing a field ToolchainsByNodeLanguageValue does not know and any text after the value.
func DecodeToolchainsByNodeLanguageValue(raw []byte) (ToolchainsByNodeLanguageValue, error) {
var v ToolchainsByNodeLanguageValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// AskArtifact is one artifact of a build ask: built from the fetched tree, or copied from an upstream pin.
type AskArtifact struct {
Artifact string `json:"artifact"`
From string `json:"from,omitempty"`
Seat string `json:"seat,omitempty"`
Version string `json:"version,omitempty"`
}
// BuildAnswer is a type of the contract.
type BuildAnswer struct {
Artifacts []BuiltArtifact `json:"artifacts"`
Imports []string `json:"imports,omitempty"`
OutOfStep []string `json:"out-of-step,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// BuiltArtifact is one artifact a build made: its digest and the reference it was published under.
type BuiltArtifact struct {
Artifact string `json:"artifact"`
Digest string `json:"digest"`
Reference string `json:"reference,omitempty"`
}
// Capacity is how many steps the node runs at once.
type Capacity struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
BuildHours string `json:"build-hours,omitempty"`
BuildHoursFault string `json:"build-hours-fault,omitempty"`
ByCpu int64 `json:"by-cpu,omitempty"`
Configured int64 `json:"configured"`
ConfiguredFrom string `json:"configured-from,omitempty"`
CoresPerStep float64 `json:"cores-per-step,omitempty"`
Effective int64 `json:"effective"`
Ineligible string `json:"ineligible,omitempty"`
OutsideHours bool `json:"outside-hours,omitempty"`
QuotaCores float64 `json:"quota-cores,omitempty"`
QuotaFrom string `json:"quota-from,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Why string `json:"why"`
}
// CheckAnswer is a type of the contract.
type CheckAnswer struct {
Fetch FetchAnswer `json:"fetch"`
Levels []LevelAnswer `json:"levels,omitempty"`
}
// ComposeAnswer is a type of the contract.
type ComposeAnswer struct {
Built bool `json:"built"`
Key string `json:"key,omitempty"`
// the compose-candidate verdict
Verdict any `json:"verdict,omitempty"`
}
// Drop is an ask a caller no longer waits for.
type Drop struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
By string `json:"by,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
Why string `json:"why"`
}
// FetchBesideItem is a type of the contract.
type FetchBesideItem struct {
Commit string `json:"commit"`
Repository string `json:"repository"`
}
// FetchPackage is the TypeScript module's group package: the group's tagged version of the SDK ({name, version}), placed from the registry in each member whatever its lock names, or the group's package member ({repository, commit, ref}), packed by the fetch and served to the members in place of the registry's.
type FetchPackage struct {
Commit string `json:"commit,omitempty"`
Name string `json:"name,omitempty"`
Ref string `json:"ref,omitempty"`
Repository string `json:"repository,omitempty"`
Version string `json:"version,omitempty"`
}
// Fetch is what a build module's fetch tool is asked: the repository and the full commit, the pull request's ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, the module's directory and named paths, the mesh packages to build against, and the sibling repositories placed beside.
type Fetch struct {
// the trunk commit a merge preview merges onto
Base string `json:"base,omitempty"`
// the sibling repositories placed beside the fetched tree
Beside []FetchBesideItem `json:"beside,omitempty"`
// the full commit
Commit string `json:"commit"`
// the module's directory in the repository ("." for its root), with paths
Dir string `json:"dir,omitempty"`
// the TypeScript module's group package: the group's tagged version of the SDK ({name, version}), placed from the registry in each member whatever its lock names, or the group's package member ({repository, commit, ref}), packed by the fetch and served to the members in place of the registry's
Package *FetchPackage `json:"package,omitempty"`
// the version (a full commit) of each mesh package to build against, by its module path
Packages map[string]string `json:"packages,omitempty"`
// the paths the module names, relative to dir
Paths []string `json:"paths,omitempty"`
// the pull request's ref, when only its head carries the commit
Ref string `json:"ref,omitempty"`
// <owner>/<name>
Repository string `json:"repository"`
}
// FetchAnswer is what a build module's fetch tool answers, whole: the workspace it made, the commit in it, the module directories found; and, when the call gave a base, the merge preview (the trunk commit, the merge commit, the files that conflict, the paths the merge changes, the compiled programs among them, the tree of each module directory). A head that does not merge cleanly is an answer, not an error: merge is empty and conflicts names the files. The Go module adds the sibling repositories placed and the package versions taken; the TypeScript module the directories installed and refused and the group's package.
type FetchAnswer struct {
Base string `json:"base,omitempty"`
Beside []PlacedBeside `json:"beside,omitempty"`
Changed []string `json:"changed,omitempty"`
Commit string `json:"commit"`
Conflicts []string `json:"conflicts,omitempty"`
Group string `json:"group,omitempty"`
Installed []string `json:"installed,omitempty"`
Merge string `json:"merge,omitempty"`
Modules []string `json:"modules"`
Packages []TakenVersion `json:"packages,omitempty"`
Programs []Program `json:"programs,omitempty"`
Refused []FetchRefusal `json:"refused,omitempty"`
Trees map[string]ModuleTree `json:"trees,omitempty"`
Workspace string `json:"workspace"`
}
// FetchRefusal is a TypeScript module whose packages the fetch did not install, with why.
type FetchRefusal struct {
Module string `json:"module"`
Reason string `json:"reason"`
}
// LevelAnswerDigestNeedsItem is a type of the contract.
type LevelAnswerDigestNeedsItem struct {
Needs []string `json:"needs,omitempty"`
Package string `json:"package,omitempty"`
}
// LevelAnswerDigestPackagesItem is a type of the contract.
type LevelAnswerDigestPackagesItem struct {
Digest string `json:"digest"`
Package string `json:"package"`
}
// LevelAnswerDigest is a type of the contract.
type LevelAnswerDigest struct {
Beside []string `json:"beside,omitempty"`
JudgedBy string `json:"judged_by,omitempty"`
Level string `json:"level,omitempty"`
Needs []LevelAnswerDigestNeedsItem `json:"needs,omitempty"`
Packages []LevelAnswerDigestPackagesItem `json:"packages,omitempty"`
WithoutTests []string `json:"without_tests,omitempty"`
}
// LevelAnswerKeptItem is a type of the contract.
type LevelAnswerKeptItem struct {
Digest string `json:"digest,omitempty"`
Package string `json:"package,omitempty"`
Tests int64 `json:"tests,omitempty"`
}
// LevelAnswerUnmetItem is a type of the contract.
type LevelAnswerUnmetItem struct {
Needs []string `json:"needs,omitempty"`
Package string `json:"package,omitempty"`
}
// LevelAnswer is one level of a check ask: the digest's answer, the kept verdicts taken, one test result per test step run, and the packages the node could not test.
type LevelAnswer struct {
Digest *LevelAnswerDigest `json:"digest,omitempty"`
Judged string `json:"judged,omitempty"`
Kept []LevelAnswerKeptItem `json:"kept,omitempty"`
Level string `json:"level"`
Tests []any `json:"tests,omitempty"`
Unmet []LevelAnswerUnmetItem `json:"unmet,omitempty"`
}
// ModuleTree is the tree of one module directory in a merge preview: its git tree, the digest of its manifest, the lock files' digests and the digests of the named paths.
type ModuleTree struct {
Locks map[string]string `json:"locks,omitempty"`
Manifest string `json:"manifest"`
// no longer filled (ADR 0593 section 2); kept so a preview written before still reads
Packages []string `json:"packages,omitempty"`
Paths map[string]string `json:"paths,omitempty"`
Tree string `json:"tree"`
}
// Pause is whether the node takes no new ask.
type Pause struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
By string `json:"by,omitempty"`
Paused bool `json:"paused"`
// the layout version
V int64 `json:"v,omitempty"`
}
// PlacedBeside is a sibling repository placed as a plain directory under the workspace's beside directory.
type PlacedBeside struct {
Commit string `json:"commit"`
Dir string `json:"dir"`
Repository string `json:"repository"`
}
// Program is a changed file that is a compiled program (issue 1577): its path, its executable format, and the commit of the branch that added it when the merge's tree no longer holds it.
type Program struct {
Commit string `json:"commit,omitempty"`
// ELF, Mach-O or PE
Kind string `json:"kind"`
Path string `json:"path"`
}
// RunAnswer is what a run ask's step answers: whether this run built the program or took the one kept under its key, the key, the program's exit, the last line of its standard output and the first of its standard error.
type RunAnswer struct {
Built bool `json:"built"`
Exit int64 `json:"exit"`
Key string `json:"key"`
// raw when it is JSON, else a JSON string
Output any `json:"output,omitempty"`
Said string `json:"said,omitempty"`
}
// RunHead is one commit a run's program reads.
type RunHead struct {
Commit string `json:"commit"`
Repository string `json:"repository"`
}
// RunInput is a run's input by reference: the seat verb the asker serves it on (seat:<seat>.<verb>), the sha256 of its bytes and its size, at most 256 KiB.
type RunInput struct {
// 64 lowercase hex digits
Digest string `json:"digest"`
// bytes
Size int64 `json:"size"`
Verb string `json:"verb"`
}
// RunJob is a run ask's job: where its program is built, the heads it reads (each laid read-only at its repository's path), its input by reference, its arguments and what it is for.
type RunJob struct {
// the program's arguments, each a word or a flag
Args []string `json:"args,omitempty"`
// the commits the program reads, a repository at most once
Heads []RunHead `json:"heads"`
Input RunInput `json:"input"`
Program RunProgram `json:"program"`
// what the run is for, for a reader of the ask
Reader string `json:"reader,omitempty"`
}
// RunProgram is where a run's program is built: the repository and full commit fetched, the Go module's directory in it and the program's import path.
type RunProgram struct {
Commit string `json:"commit"`
Dir string `json:"dir"`
Package string `json:"package"`
Repository string `json:"repository"`
}
// Step is one step a build module runs on a node.
type Step struct {
// when the bus gives the ask again, for the state again (RFC 3339 time)
AgainAt *time.Time `json:"again-at,omitempty"`
// when (RFC 3339 time)
Ended *time.Time `json:"ended,omitempty"`
ID string `json:"id"`
Node string `json:"node"`
Owner string `json:"owner,omitempty"`
// true when the step ended on a fault that passes (a transport fault), so a failed end after the last run says so
Passing bool `json:"passing,omitempty"`
Phase string `json:"phase,omitempty"`
// when (RFC 3339 time)
PhaseAt *time.Time `json:"phase-at,omitempty"`
Reason string `json:"reason,omitempty"`
Result *StepResult `json:"result,omitempty"`
// which run of the ask this is, counted by the bus's delivery count (1 for the first)
Run int64 `json:"run,omitempty"`
// when (RFC 3339 time)
Started time.Time `json:"started"`
// running, again (ended on a transport fault, to be given again by the bus after again-at), passed, failed, refused or dropped (ended by the verb drop, its cause the reason)
State string `json:"state"`
Tool string `json:"tool"`
// the layout version
V int64 `json:"v,omitempty"`
What string `json:"what,omitempty"`
}
// StepAskBuild is a type of the contract.
type StepAskBuild struct {
Artifacts []AskArtifact `json:"artifacts"`
Fetch *Fetch `json:"fetch,omitempty"`
Fp string `json:"fp,omitempty"`
Module string `json:"module"`
Path string `json:"path,omitempty"`
Publish bool `json:"publish,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// StepAskCheck is a type of the contract.
type StepAskCheck struct {
Fetch Fetch `json:"fetch"`
Kept bool `json:"kept,omitempty"`
Levels []string `json:"levels"`
// the node names the check's tests run against
NodeNames []string `json:"node-names,omitempty"`
Packages []string `json:"packages,omitempty"`
Run string `json:"run,omitempty"`
Runner string `json:"runner,omitempty"`
RunnerWhen string `json:"runner_when,omitempty"`
// the toolchain the checker agreed for the language (ADR 0584 clause 2): a node on another declines the check
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
}
// StepAskCompose is a type of the contract.
type StepAskCompose struct {
Dir string `json:"dir"`
Fetch Fetch `json:"fetch"`
Package string `json:"package"`
Reader string `json:"reader,omitempty"`
// the compose-candidate request, in one of two forms: the request as a JSON object, or, for one near the bus's message limit, a JSON string "gzip+base64:" followed by the base64 of the request object gzip-compressed; a holder that does not know the packed form refuses it, naming that it holds no request object
Request any `json:"request"`
}
// StepAsk is one ask of a build module.
type StepAsk struct {
Asker string `json:"asker"`
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
Build *StepAskBuild `json:"build,omitempty"`
Check *StepAskCheck `json:"check,omitempty"`
Compose *StepAskCompose `json:"compose,omitempty"`
ID string `json:"id"`
// build, check or compose
Kind string `json:"kind"`
// go, typescript or image
Language string `json:"language"`
Needs []string `json:"needs,omitempty"`
// package to the tagged version a build pins
Packages map[string]string `json:"packages,omitempty"`
// a run: a program built from a change and run in the build seat's sandbox over the heads, its input asked of a verb of the asker's seat; the Go seat's check stream alone carries it, as a compose
Run *RunJob `json:"run,omitempty"`
// the layout version
V int64 `json:"v,omitempty"`
}
// StepResult is what a step answered, by the kind of ask: a build's artifacts, toolchain, imports and out-of-step modules; a check's fetch and levels; a compose's built, key and verdict; a run's built, key, exit, output and said; a declined ask's declined, needs and lacks. The fields of the kinds do not meet, so one layout holds the five.
type StepResult struct {
Artifacts []BuiltArtifact `json:"artifacts,omitempty"`
Built bool `json:"built,omitempty"`
// the holder declined the ask: its node lacks what the ask needs
Declined bool `json:"declined,omitempty"`
// a run's program's exit status
Exit int64 `json:"exit,omitempty"`
Fetch *FetchAnswer `json:"fetch,omitempty"`
Imports []string `json:"imports,omitempty"`
Key string `json:"key,omitempty"`
// what the holder's node lacks of it
Lacks []string `json:"lacks,omitempty"`
Levels []LevelAnswer `json:"levels,omitempty"`
// what the declined ask needs
Needs []string `json:"needs,omitempty"`
OutOfStep []string `json:"out-of-step,omitempty"`
// a run's program's last line of standard output: raw when it is JSON, else a JSON string
Output any `json:"output,omitempty"`
// a run's program's first line of standard error, or why the step could not run it
Said string `json:"said,omitempty"`
Toolchain *ToolchainUsed `json:"toolchain,omitempty"`
// the compose-candidate verdict (the composer's own layout)
Verdict any `json:"verdict,omitempty"`
}
// TakenVersion is of a directory whose go.mod requires an asked mesh package, the version it is built against: the asked one, or go.mod's when it names a newer one, said.
type TakenVersion struct {
Asked string `json:"asked"`
Built string `json:"built"`
Dir string `json:"dir"`
Named string `json:"named"`
Package string `json:"package"`
Said string `json:"said,omitempty"`
Sum string `json:"sum,omitempty"`
}
// Toolchain is the toolchain a node reports.
type Toolchain struct {
// when (RFC 3339 time)
At *time.Time `json:"at,omitempty"`
// go or typescript
Language string `json:"language"`
Recipe string `json:"recipe"`
// the layout version
V int64 `json:"v,omitempty"`
Version string `json:"version"`
}
// ToolchainUsed is the toolchain a build was made with: the language, the installed version and the build module's recipe.
type ToolchainUsed struct {
Language string `json:"language"`
Recipe string `json:"recipe"`
Version string `json:"version"`
}
// CurrentInput is what current takes.
type CurrentInput struct {
}
// CurrentAnswer is what current answers.
type CurrentAnswer = map[string]any
// PauseInput is what pause takes.
type PauseInput struct {
}
// PauseAnswer is what pause answers.
type PauseAnswer = map[string]any
// ResumeInput is what resume takes.
type ResumeInput struct {
}
// ResumeAnswer is what resume answers.
type ResumeAnswer = map[string]any
// DropInput is what drop takes.
type DropInput struct {
// who drops it
By string `json:"by,omitempty"`
// the ask's id
ID string `json:"id"`
// why the caller no longer waits
Why string `json:"why"`
}
// DropAnswer is what drop answers.
type DropAnswer = map[string]any
// DeliveryAccept is the body of delivery.
type DeliveryAccept = StepAsk
// CheckAccept is the body of check.
type CheckAccept = StepAsk
// RecheckAccept is the body of recheck.
type RecheckAccept = StepAsk
// StepsByNodeIDValue is one value of the state steps under the key <node>.<id>.
type StepsByNodeIDValue = Step
// PausesByPausedNodeValue is one value of the state pauses under the key paused.<node>.
type PausesByPausedNodeValue = Pause
// PausesByDroppedIDValue is one value of the state pauses under the key dropped.<id>.
type PausesByDroppedIDValue = Drop
// PausesByCapacityNodeValue is one value of the state pauses under the key capacity.<node>.
type PausesByCapacityNodeValue = Capacity
// ToolchainsByNodeLanguageValue is one value of the state toolchains under the key <node>.<language>.
type ToolchainsByNodeLanguageValue = Toolchain
@@ -1,78 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package nodebuildnode
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/node-build-node/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "a running step", subject: "", given: "{\"id\":\"a1b2\",\"node\":\"ace\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}", wire: "{\"id\":\"a1b2\",\"node\":\"ace\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a paused node", subject: "", given: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@shanks\",\"paused\":true,\"v\":1}", wire: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@shanks\",\"paused\":true,\"v\":1}",
decode: func(b []byte) (any, error) {
var v PausesByPausedNodeValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a node's capacity", subject: "", given: "{\"configured\":2,\"effective\":2,\"v\":1,\"why\":\"the configured steps fit the cores\"}", wire: "{\"configured\":2,\"effective\":2,\"v\":1,\"why\":\"the configured steps fit the cores\"}",
decode: func(b []byte) (any, error) {
var v PausesByCapacityNodeValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a node's toolchain", subject: "", given: "{\"language\":\"go\",\"recipe\":\"1\",\"v\":1,\"version\":\"1.26.0\"}", wire: "{\"language\":\"go\",\"recipe\":\"1\",\"v\":1,\"version\":\"1.26.0\"}",
decode: func(b []byte) (any, error) {
var v ToolchainsByNodeLanguageValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a build ask", subject: "mesh.seat.node-build-node.accept.delivery", given: "{\"asker\":\"mesh-delivery-builder\",\"build\":{\"artifacts\":[{\"artifact\":\"go\"}],\"module\":\"nats\"},\"id\":\"a1b2\",\"kind\":\"build\",\"language\":\"go\"}", wire: "{\"asker\":\"mesh-delivery-builder\",\"build\":{\"artifacts\":[{\"artifact\":\"go\"}],\"module\":\"nats\"},\"id\":\"a1b2\",\"kind\":\"build\",\"language\":\"go\"}",
decode: func(b []byte) (any, error) { var v DeliveryAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.accept\\.delivery$")},
{name: "a check ask with the group's tagged package", subject: "mesh.seat.node-build-node.accept.check", given: "{\"asker\":\"mesh-delivery-checker\",\"at\":\"2026-11-05T10:00:00Z\",\"check\":{\"fetch\":{\"base\":\"89abcdef0123456789abcdef0123456789abcdef\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"package\":{\"name\":\"@novox/mesh-sdk\",\"version\":\"0.1.15-feat-x.1\"},\"ref\":\"refs/pull/7/head\",\"repository\":\"novox/mesh-delivery\"},\"kept\":true,\"levels\":[\"unit\",\"integration\"],\"node-names\":[\"ace\",\"g14\"],\"toolchain\":{\"language\":\"typescript\",\"recipe\":\"1\",\"version\":\"26.12.0\"}},\"id\":\"c3d5\",\"kind\":\"check\",\"language\":\"typescript\",\"v\":1}", wire: "{\"asker\":\"mesh-delivery-checker\",\"at\":\"2026-11-05T10:00:00Z\",\"check\":{\"fetch\":{\"base\":\"89abcdef0123456789abcdef0123456789abcdef\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"package\":{\"name\":\"@novox/mesh-sdk\",\"version\":\"0.1.15-feat-x.1\"},\"ref\":\"refs/pull/7/head\",\"repository\":\"novox/mesh-delivery\"},\"kept\":true,\"levels\":[\"unit\",\"integration\"],\"node-names\":[\"ace\",\"g14\"],\"toolchain\":{\"language\":\"typescript\",\"recipe\":\"1\",\"version\":\"26.12.0\"}},\"id\":\"c3d5\",\"kind\":\"check\",\"language\":\"typescript\",\"v\":1}",
decode: func(b []byte) (any, error) { var v CheckAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.accept\\.check$")},
{name: "a finished check step of a TypeScript merge preview", subject: "", given: "{\"ended\":\"2026-11-05T10:01:00Z\",\"id\":\"c3d6\",\"node\":\"ace\",\"result\":{\"fetch\":{\"base\":\"abcdef0123456789abcdef0123456789abcdef01\",\"changed\":[\"modules/m/package.json\"],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"merge\":\"0123456789abcdef0123456789abcdef01234567\",\"modules\":[\"modules/m\"],\"trees\":{\"modules/m\":{\"manifest\":\"0581b699d9d05517e69b21f5cedbeb2eee8aba2b205280b561be731594d7feef\",\"tree\":\"0123456789abcdef0123456789abcdef01234567\"}},\"workspace\":\"mvii1sxt979f67\"}},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:01:00Z\",\"id\":\"c3d6\",\"node\":\"ace\",\"result\":{\"fetch\":{\"base\":\"abcdef0123456789abcdef0123456789abcdef01\",\"changed\":[\"modules/m/package.json\"],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"merge\":\"0123456789abcdef0123456789abcdef01234567\",\"modules\":[\"modules/m\"],\"trees\":{\"modules/m\":{\"manifest\":\"0581b699d9d05517e69b21f5cedbeb2eee8aba2b205280b561be731594d7feef\",\"tree\":\"0123456789abcdef0123456789abcdef01234567\"}},\"workspace\":\"mvii1sxt979f67\"}},\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a step ended on a transport fault, given again by the bus", subject: "", given: "{\"again-at\":\"2026-11-05T10:01:30Z\",\"ended\":\"2026-11-05T10:00:30Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"passing\":true,\"reason\":\"fetching the commit: kex_exchange_identification: read: Connection reset by peer\",\"run\":1,\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"again\",\"tool\":\"build\",\"v\":1}", wire: "{\"again-at\":\"2026-11-05T10:01:30Z\",\"ended\":\"2026-11-05T10:00:30Z\",\"id\":\"a1b2\",\"node\":\"ace\",\"passing\":true,\"reason\":\"fetching the commit: kex_exchange_identification: read: Connection reset by peer\",\"run\":1,\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"again\",\"tool\":\"build\",\"v\":1}",
decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "an ask dropped by the caller that no longer waits", subject: "", given: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"mesh-delivery-builder\",\"v\":1,\"why\":\"a newer fingerprint supersedes it\"}", wire: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"mesh-delivery-builder\",\"v\":1,\"why\":\"a newer fingerprint supersedes it\"}",
decode: func(b []byte) (any, error) { var v PausesByDroppedIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "drop names the ask and why", subject: "", given: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}", wire: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}",
decode: func(b []byte) (any, error) { var v DropInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
-3
View File
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/nodebuildnode
go 1.26.0
@@ -1,262 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package npmpackageregistry is the contract of the seat "npm-package-registry", defined whole (seats/npm-package-registry/seat.json): The mesh's npm packages: the npm registry protocol's read side, and publishing over the bus.
package npmpackageregistry
// Seat is the seat's name.
const Seat = "npm-package-registry"
const (
VerbPublish = "publish"
VerbPublishPart = "publish-part"
VerbVersions = "versions"
VerbRemove = "remove"
)
const (
EventPublished = "published"
EventRefused = "refused"
EventRemoved = "removed"
EventKept = "kept"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventPublished, EventRefused, EventRemoved, EventKept}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "npm-package-registry.events"
FamilyMaxAgeDays = 7
)
// SubjectPublished is where published is published.
const SubjectPublished = "mesh.seat.npm-package-registry.event.published"
// SubjectRefused is where refused is published.
const SubjectRefused = "mesh.seat.npm-package-registry.event.refused"
// SubjectRemoved is where removed is published.
const SubjectRemoved = "mesh.seat.npm-package-registry.event.removed"
// SubjectKept is where kept is published.
const SubjectKept = "mesh.seat.npm-package-registry.event.kept"
// Artifact is one published thing, as every registry event and answer names it.
type Artifact struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Artifact's kind.
const (
ArtifactKindPackage = "package"
ArtifactKindImage = "image"
ArtifactKindBundle = "bundle"
ArtifactKindArchive = "archive"
ArtifactKindUpstream = "upstream"
)
// Outcome is the body of published, refused and removed.
type Outcome struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// the module holding the seat that said it
Holder string `json:"holder"`
// what it is
Kind string `json:"kind"`
// the Go module path a Go package is fetched under, equal to name for a Go package (go-package-registry's published); empty for every other kind of artifact
Module string `json:"module,omitempty"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// why: a refusal's cause, a removal's (retention, tag-gone, by-hand), or why a removal was kept (shared-digest)
Reason string `json:"reason,omitempty"`
// the reference the seat answers: <registry>/<module>/<artifact>@sha256:<digest>, or <name>@<version> for a package (ADR 0605 §9)
Reference string `json:"reference,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// for kept: the other tags still naming its digest
Tags []string `json:"tags,omitempty"`
// the transfer it ends, when it ended one
Transfer string `json:"transfer,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Outcome's kind.
const (
OutcomeKindPackage = "package"
OutcomeKindImage = "image"
OutcomeKindBundle = "bundle"
OutcomeKindArchive = "archive"
OutcomeKindUpstream = "upstream"
)
// Part is one part of a transfer.
type Part struct {
// the part's digest, sha256:<hex>: an image's layer or config, a package's file, a bundle's blob
Digest string `json:"digest"`
// its size in bytes
Size int64 `json:"size"`
}
// PublishInput is what publish takes.
type PublishInput struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// every part's digest and size; none when the digest is already held
Parts []Part `json:"parts,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the transfer's name, the caller's own; the same name opens the same transfer again
Transfer string `json:"transfer"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of PublishInput's kind.
const (
PublishInputKindPackage = "package"
PublishInputKindImage = "image"
PublishInputKindBundle = "bundle"
PublishInputKindArchive = "archive"
PublishInputKindUpstream = "upstream"
)
// PublishAnswer is what publish answers.
type PublishAnswer struct {
// the digest is held already: nothing to send; the outcome follows as an event
Held bool `json:"held,omitempty"`
// the digests of the parts the holder lacks, to send by publish-part
Lacks []string `json:"lacks,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartInput is what publish-part takes.
type PublishPartInput struct {
// the chunk's bytes, base64 (at most 760 KiB before encoding)
Data string `json:"data"`
// this chunk is the part's last
Last bool `json:"last"`
// the part's digest
Part string `json:"part"`
// the chunk's place in its part, from 0
Sequence int64 `json:"sequence"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartAnswer is what publish-part answers.
type PublishPartAnswer struct {
// the part is whole and its bytes match its digest
Complete bool `json:"complete,omitempty"`
// the part
Part string `json:"part"`
// the chunks of the part held so far
Received int64 `json:"received,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// VersionsInput is what versions takes.
type VersionsInput struct {
// narrowed to one kind (optional)
Kind string `json:"kind,omitempty"`
// the name
Name string `json:"name"`
}
// VersionsAnswer is what versions answers.
type VersionsAnswer struct {
// the name
Name string `json:"name"`
// newest first
Versions []Artifact `json:"versions"`
}
// RemoveInput is what remove takes.
type RemoveInput struct {
// the digest (for a bundle, archive or copied base)
Digest string `json:"digest,omitempty"`
// the name
Name string `json:"name"`
// why it goes
Reason string `json:"reason"`
// the tag (for a tagged version)
Tag string `json:"tag,omitempty"`
// the version
Version string `json:"version,omitempty"`
}
// The values of RemoveInput's reason.
const (
RemoveInputReasonTagGone = "tag-gone"
RemoveInputReasonRetention = "retention"
)
// RemoveAnswer is what remove answers.
type RemoveAnswer struct {
Artifact *Artifact `json:"artifact,omitempty"`
// it stays whole, its tag and its bytes: the store cannot remove the tag alone while another tag names its digest (reason, tags)
Kept bool `json:"kept,omitempty"`
// why it was kept: shared-digest, another tag names its digest
Reason string `json:"reason,omitempty"`
// it is gone
Removed bool `json:"removed"`
// the other tags still naming its digest, when kept
Tags []string `json:"tags,omitempty"`
}
// The values of RemoveAnswer's reason.
const (
RemoveAnswerReasonSharedDigest = "shared-digest"
)
// PublishedEvent is the body of the event published.
type PublishedEvent = Outcome
// RefusedEvent is the body of the event refused.
type RefusedEvent = Outcome
// RemovedEvent is the body of the event removed.
type RemovedEvent = Outcome
// KeptEvent is the body of the event kept.
type KeptEvent = Outcome
// NpmPackageRegistryForm is the form of the provision npm-package-registry.
type NpmPackageRegistryForm struct {
// the read side's address
URL string `json:"url"`
}
@@ -1,66 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package npmpackageregistry
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/npm-package-registry/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "published on the seat's subject", subject: "mesh.seat.npm-package-registry.event.published", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.npm-package-registry\\.event\\.published$")},
{name: "refused on the seat's subject", subject: "mesh.seat.npm-package-registry.event.refused", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reason\":\"retention\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reason\":\"retention\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RefusedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.npm-package-registry\\.event\\.refused$")},
{name: "removed on the seat's subject", subject: "mesh.seat.npm-package-registry.event.removed", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reason\":\"retention\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reason\":\"retention\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RemovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.npm-package-registry\\.event\\.removed$")},
{name: "kept on the seat's subject: a tagged version sharing its digest stays, naming the tags on it", subject: "mesh.seat.npm-package-registry.event.kept", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reason\":\"shared-digest\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"gitea\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"reason\":\"shared-digest\",\"reference\":\"@novox/mesh-sdk@0.1.19\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}",
decode: func(b []byte) (any, error) { var v KeptEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.npm-package-registry\\.event\\.kept$")},
{name: "publish opens a transfer", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a field the reader does not know is dropped", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"later\":{\"x\":1},\"name\":\"@novox/mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "publish answers what it lacks", subject: "", given: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}", wire: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a chunk of a part", subject: "", given: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}", wire: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishPartInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the versions held", subject: "", given: "{\"name\":\"@novox/mesh-sdk\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"version\":\"0.1.19\"}]}", wire: "{\"name\":\"@novox/mesh-sdk\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"@novox/mesh-sdk\",\"version\":\"0.1.19\"}]}",
decode: func(b []byte) (any, error) { var v VersionsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a tagged version sharing its digest with another tag is kept, not removed", subject: "", given: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}", wire: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}",
decode: func(b []byte) (any, error) { var v RemoveAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/npmpackageregistry
go 1.26.0
@@ -1,486 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// Package ociartifactregistry is the contract of the seat "oci-artifact-registry", defined whole (seats/oci-artifact-registry/seat.json): The mesh's bundles and archives, by digest, in the one artifact store: the OCI distribution protocol's read side.
package ociartifactregistry
import (
"bytes"
"encoding/json"
"errors"
"strings"
)
// Seat is the seat's name.
const Seat = "oci-artifact-registry"
const (
VerbPublish = "publish"
VerbPublishPart = "publish-part"
VerbVersions = "versions"
VerbRemove = "remove"
VerbHold = "hold"
VerbRelease = "release"
VerbList = "list"
)
const (
EventPublished = "published"
EventRefused = "refused"
EventRemoved = "removed"
EventKept = "kept"
EventHeld = "held"
EventReleased = "released"
)
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove, VerbHold, VerbRelease, VerbList}
}
// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
return []string{EventPublished, EventRefused, EventRemoved, EventKept, EventHeld, EventReleased}
}
// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
Family = "oci-artifact-registry.events"
FamilyMaxAgeDays = 7
)
// SubjectPublished is where published is published.
const SubjectPublished = "mesh.seat.oci-artifact-registry.event.published"
// SubjectRefused is where refused is published.
const SubjectRefused = "mesh.seat.oci-artifact-registry.event.refused"
// SubjectRemoved is where removed is published.
const SubjectRemoved = "mesh.seat.oci-artifact-registry.event.removed"
// SubjectKept is where kept is published.
const SubjectKept = "mesh.seat.oci-artifact-registry.event.kept"
// SubjectHeld is where held is published.
const SubjectHeld = "mesh.seat.oci-artifact-registry.event.held"
// SubjectReleased is where released is published.
const SubjectReleased = "mesh.seat.oci-artifact-registry.event.released"
const (
StateHolds = "holds"
StateWindows = "windows"
)
// HoldsBySeatNameDigestKey is the key of one value of the state holds under the form "<seat>.<name>.<digest>".
func HoldsBySeatNameDigestKey(seat, name, digest string) string {
return seat + "." + name + "." + digest
}
// ParseHoldsBySeatNameDigestKey reads the parts of a key of the form "<seat>.<name>.<digest>", in the order of the form; the last result is false for a key of another form.
func ParseHoldsBySeatNameDigestKey(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, ".")
if !found2 || v2 == "" {
return "", "", "", false
}
rest = after2
if rest == "" {
return "", "", "", false
}
v4 := rest
rest = ""
if rest != "" {
return "", "", "", false
}
return v0, v2, v4, true
}
// DecodeHoldsBySeatNameDigestValue reads one value of the state holds under the form "<seat>.<name>.<digest>", refusing a field HoldsBySeatNameDigestValue does not know and any text after the value.
func DecodeHoldsBySeatNameDigestValue(raw []byte) (HoldsBySeatNameDigestValue, error) {
var v HoldsBySeatNameDigestValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// WindowsByCallerKey is the key of one value of the state windows under the form "<caller>".
func WindowsByCallerKey(caller string) string { return caller }
// ParseWindowsByCallerKey reads the parts of a key of the form "<caller>", in the order of the form; the last result is false for a key of another form.
func ParseWindowsByCallerKey(key string) (string, bool) {
rest := key
if rest == "" {
return "", false
}
v0 := rest
rest = ""
if rest != "" {
return "", false
}
return v0, true
}
// DecodeWindowsByCallerValue reads one value of the state windows under the form "<caller>", refusing a field WindowsByCallerValue does not know and any text after the value.
func DecodeWindowsByCallerValue(raw []byte) (WindowsByCallerValue, error) {
var v WindowsByCallerValue
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&v); err != nil {
return v, err
}
if dec.More() {
return v, errors.New("text after the value")
}
return v, nil
}
// Artifact is one published thing, as every registry event and answer names it.
type Artifact struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Artifact's kind.
const (
ArtifactKindPackage = "package"
ArtifactKindImage = "image"
ArtifactKindBundle = "bundle"
ArtifactKindArchive = "archive"
ArtifactKindUpstream = "upstream"
)
// Hold is the body of held and released.
type Hold struct {
// when, RFC 3339
At string `json:"at,omitempty"`
// the caller the holder proved
By string `json:"by,omitempty"`
// the digest
Digest string `json:"digest"`
// the module holding the seat
Holder string `json:"holder"`
// the name
Name string `json:"name"`
// why
Reason string `json:"reason,omitempty"`
}
// Listed is a type of the contract.
type Listed struct {
// for a manifest keeping one bundle or archive, the digest of that blob: what a reference names it by
Artifact string `json:"artifact,omitempty"`
// the manifest's digest, sha256:<hex>
Digest string `json:"digest"`
// a hold keeps it from retention
Held bool `json:"held"`
// it is an index, naming a manifest per platform
Index bool `json:"index"`
// for an index, the digests of the manifests it names
Platforms []string `json:"platforms,omitempty"`
// its bytes: its own content and every blob it names
Size int64 `json:"size"`
// the tags naming it, none for an untagged one
Tags []string `json:"tags,omitempty"`
}
// Outcome is the body of published, refused and removed.
type Outcome struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// the module holding the seat that said it
Holder string `json:"holder"`
// what it is
Kind string `json:"kind"`
// the Go module path a Go package is fetched under, equal to name for a Go package (go-package-registry's published); empty for every other kind of artifact
Module string `json:"module,omitempty"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// why: a refusal's cause, a removal's (retention, tag-gone, by-hand), or why a removal was kept (shared-digest)
Reason string `json:"reason,omitempty"`
// the reference the seat answers: <registry>/<module>/<artifact>@sha256:<digest>, or <name>@<version> for a package (ADR 0605 §9)
Reference string `json:"reference,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// for kept: the other tags still naming its digest
Tags []string `json:"tags,omitempty"`
// the transfer it ends, when it ended one
Transfer string `json:"transfer,omitempty"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of Outcome's kind.
const (
OutcomeKindPackage = "package"
OutcomeKindImage = "image"
OutcomeKindBundle = "bundle"
OutcomeKindArchive = "archive"
OutcomeKindUpstream = "upstream"
)
// Part is one part of a transfer.
type Part struct {
// the part's digest, sha256:<hex>: an image's layer or config, a package's file, a bundle's blob
Digest string `json:"digest"`
// its size in bytes
Size int64 `json:"size"`
}
// Repository is a type of the contract.
type Repository struct {
// each manifest it holds, by digest
Manifests []Listed `json:"manifests"`
// the repository
Name string `json:"name"`
}
// PublishInput is what publish takes.
type PublishInput struct {
// the source commit it was built from
Commit string `json:"commit,omitempty"`
// its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)
Digest string `json:"digest"`
// the build's fingerprint
Fingerprint string `json:"fingerprint,omitempty"`
// what it is
Kind string `json:"kind"`
// the package's, image's, bundle's or archive's name; a package's is its name in its own language (design 32): a Go package's the go.mod module path (git.novox.be/novox/mesh-sdk/go), an npm package's package.json's name (@novox/mesh-sdk)
Name string `json:"name"`
// every part's digest and size; none when the digest is already held
Parts []Part `json:"parts,omitempty"`
// the tag it carries, for a tagged version
Tag string `json:"tag,omitempty"`
// the transfer's name, the caller's own; the same name opens the same transfer again
Transfer string `json:"transfer"`
// the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone
Version string `json:"version,omitempty"`
}
// The values of PublishInput's kind.
const (
PublishInputKindPackage = "package"
PublishInputKindImage = "image"
PublishInputKindBundle = "bundle"
PublishInputKindArchive = "archive"
PublishInputKindUpstream = "upstream"
)
// PublishAnswer is what publish answers.
type PublishAnswer struct {
// the digest is held already: nothing to send; the outcome follows as an event
Held bool `json:"held,omitempty"`
// the digests of the parts the holder lacks, to send by publish-part
Lacks []string `json:"lacks,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartInput is what publish-part takes.
type PublishPartInput struct {
// the chunk's bytes, base64 (at most 760 KiB before encoding)
Data string `json:"data"`
// this chunk is the part's last
Last bool `json:"last"`
// the part's digest
Part string `json:"part"`
// the chunk's place in its part, from 0
Sequence int64 `json:"sequence"`
// the transfer
Transfer string `json:"transfer"`
}
// PublishPartAnswer is what publish-part answers.
type PublishPartAnswer struct {
// the part is whole and its bytes match its digest
Complete bool `json:"complete,omitempty"`
// the part
Part string `json:"part"`
// the chunks of the part held so far
Received int64 `json:"received,omitempty"`
// the transfer
Transfer string `json:"transfer"`
}
// VersionsInput is what versions takes.
type VersionsInput struct {
// narrowed to one kind (optional)
Kind string `json:"kind,omitempty"`
// the name
Name string `json:"name"`
}
// VersionsAnswer is what versions answers.
type VersionsAnswer struct {
// the name
Name string `json:"name"`
// newest first
Versions []Artifact `json:"versions"`
}
// RemoveInput is what remove takes.
type RemoveInput struct {
// the digest (for a bundle, archive or copied base)
Digest string `json:"digest,omitempty"`
// the name
Name string `json:"name"`
// why it goes
Reason string `json:"reason"`
// the tag (for a tagged version)
Tag string `json:"tag,omitempty"`
// the version
Version string `json:"version,omitempty"`
}
// The values of RemoveInput's reason.
const (
RemoveInputReasonTagGone = "tag-gone"
RemoveInputReasonRetention = "retention"
)
// RemoveAnswer is what remove answers.
type RemoveAnswer struct {
Artifact *Artifact `json:"artifact,omitempty"`
// it stays whole, its tag and its bytes: the store cannot remove the tag alone while another tag names its digest (reason, tags)
Kept bool `json:"kept,omitempty"`
// why it was kept: shared-digest, another tag names its digest
Reason string `json:"reason,omitempty"`
// it is gone
Removed bool `json:"removed"`
// the other tags still naming its digest, when kept
Tags []string `json:"tags,omitempty"`
}
// The values of RemoveAnswer's reason.
const (
RemoveAnswerReasonSharedDigest = "shared-digest"
)
// HoldInput is what hold takes.
type HoldInput struct {
// the digest
Digest string `json:"digest"`
// the name
Name string `json:"name"`
// which of the sweep's rules keeps it
Reason string `json:"reason"`
}
// HoldAnswer is what hold answers.
type HoldAnswer struct {
// it is held
Held bool `json:"held"`
// when the hold began, RFC 3339
Since string `json:"since,omitempty"`
}
// ReleaseInput is what release takes.
type ReleaseInput struct {
// the digest
Digest string `json:"digest"`
// the name
Name string `json:"name"`
// why it is let go
Reason string `json:"reason"`
}
// ReleaseAnswer is what release answers.
type ReleaseAnswer struct {
// a hold was let go; false when there was none
Released bool `json:"released"`
}
// ListInput is what list takes.
type ListInput struct {
// the repository, <module>/<artifact>; every repository of the seat when not given
Name string `json:"name,omitempty"`
}
// ListAnswer is what list answers.
type ListAnswer struct {
// each repository named, in order of its name
Repositories []Repository `json:"repositories"`
}
// PublishedEvent is the body of the event published.
type PublishedEvent = Outcome
// RefusedEvent is the body of the event refused.
type RefusedEvent = Outcome
// RemovedEvent is the body of the event removed.
type RemovedEvent = Outcome
// KeptEvent is the body of the event kept.
type KeptEvent = Outcome
// HeldEvent is the body of the event held.
type HeldEvent = Hold
// ReleasedEvent is the body of the event released.
type ReleasedEvent = Hold
// HoldsBySeatNameDigestValue is one value of the state holds under the key <seat>.<name>.<digest>.
type HoldsBySeatNameDigestValue struct {
By string `json:"by"`
Digest string `json:"digest"`
Kind string `json:"kind"`
Name string `json:"name"`
Seat string `json:"seat"`
// when (RFC 3339 time)
Since string `json:"since"`
Why string `json:"why,omitempty"`
}
// WindowsByCallerValueDroppedItem is a type of the contract.
type WindowsByCallerValueDroppedItem struct {
// when (RFC 3339 time)
At string `json:"at,omitempty"`
By string `json:"by,omitempty"`
Node string `json:"node"`
Why string `json:"why,omitempty"`
}
// WindowsByCallerValue is one value of the state windows under the key <caller>.
type WindowsByCallerValue struct {
// when it last closed (RFC 3339 time)
Closed string `json:"closed,omitempty"`
// retired nodes dropped by hand
Dropped []WindowsByCallerValueDroppedItem `json:"dropped,omitempty"`
// the nodes holding it open
Holding []string `json:"holding,omitempty"`
LastHolding []string `json:"last_holding,omitempty"`
// the caller whose window it is
Name string `json:"name"`
Open bool `json:"open,omitempty"`
// node to when it began to hold
Since map[string]string `json:"since,omitempty"`
// of each node holding the window, why it holds it
Why map[string]string `json:"why,omitempty"`
}
@@ -1,82 +0,0 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
package ociartifactregistry
import (
"encoding/json"
"reflect"
"regexp"
"testing"
)
// TestFixtures reads every fixture of seats/oci-artifact-registry/fixtures: each decodes into its type, a field the type does not
// know is dropped (ADR 0608 §6), and it reads back as its wire says; each subject named is the contract's.
func TestFixtures(t *testing.T) {
cases := []struct {
name, subject, given, wire string
decode func([]byte) (any, error)
subjectIs *regexp.Regexp
}{
{name: "published on the seat's subject", subject: "mesh.seat.oci-artifact-registry.event.published", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.oci-artifact-registry\\.event\\.published$")},
{name: "refused on the seat's subject", subject: "mesh.seat.oci-artifact-registry.event.refused", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RefusedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.oci-artifact-registry\\.event\\.refused$")},
{name: "removed on the seat's subject", subject: "mesh.seat.oci-artifact-registry.event.removed", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reason\":\"retention\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v RemovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.oci-artifact-registry\\.event\\.removed$")},
{name: "kept on the seat's subject: a tagged version sharing its digest stays, naming the tags on it", subject: "mesh.seat.oci-artifact-registry.event.kept", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reason\":\"shared-digest\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"holder\":\"distribution\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"reason\":\"shared-digest\",\"reference\":\"oci-artifact-registry/mesh-sdk/lib@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"tag\":\"0.1.19-feat-x.2\",\"tags\":[\"0.1.19\"],\"version\":\"0.1.19-feat-x.2\"}",
decode: func(b []byte) (any, error) { var v KeptEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.oci-artifact-registry\\.event\\.kept$")},
{name: "held on the seat's subject", subject: "mesh.seat.oci-artifact-registry.event.held", given: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}", wire: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}",
decode: func(b []byte) (any, error) { var v HeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.oci-artifact-registry\\.event\\.held$")},
{name: "released on the seat's subject", subject: "mesh.seat.oci-artifact-registry.event.released", given: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}", wire: "{\"at\":\"2026-11-04T12:00:00Z\",\"by\":\"mesh-artifact-sweep\",\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"holder\":\"distribution\",\"name\":\"mesh-sdk\",\"reason\":\"kept by the sweep's rule\"}",
decode: func(b []byte) (any, error) { var v ReleasedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.oci-artifact-registry\\.event\\.released$")},
{name: "a hold", subject: "", given: "{\"by\":\"operator@shanks\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"base\",\"name\":\"base\",\"seat\":\"oci-artifact-registry\",\"since\":\"2026-11-05T10:00:00Z\"}", wire: "{\"by\":\"operator@shanks\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"kind\":\"base\",\"name\":\"base\",\"seat\":\"oci-artifact-registry\",\"since\":\"2026-11-05T10:00:00Z\"}",
decode: func(b []byte) (any, error) {
var v HoldsBySeatNameDigestValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "an open window", subject: "", given: "{\"holding\":[\"ace\"],\"name\":\"mesh-delivery-builder\",\"open\":true,\"since\":{\"ace\":\"2026-11-05T10:00:00Z\"}}", wire: "{\"holding\":[\"ace\"],\"name\":\"mesh-delivery-builder\",\"open\":true,\"since\":{\"ace\":\"2026-11-05T10:00:00Z\"}}",
decode: func(b []byte) (any, error) { var v WindowsByCallerValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "publish opens a transfer", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a field the reader does not know is dropped", subject: "", given: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"bundle\",\"later\":{\"x\":1},\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}", wire: "{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"bundle\",\"name\":\"mesh-sdk\",\"parts\":[{\"digest\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"size\":1048576}],\"transfer\":\"t1\",\"version\":\"0.1.19\"}",
decode: func(b []byte) (any, error) { var v PublishInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "publish answers what it lacks", subject: "", given: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}", wire: "{\"lacks\":[\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\"],\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a chunk of a part", subject: "", given: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}", wire: "{\"data\":\"aGVsbG8=\",\"last\":true,\"part\":\"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"sequence\":0,\"transfer\":\"t1\"}",
decode: func(b []byte) (any, error) { var v PublishPartInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "the versions held", subject: "", given: "{\"name\":\"mesh-sdk\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"mesh-sdk\",\"version\":\"0.1.19\"}]}", wire: "{\"name\":\"mesh-sdk\",\"versions\":[{\"commit\":\"cccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"fingerprint\":\"f1\",\"kind\":\"package\",\"name\":\"mesh-sdk\",\"version\":\"0.1.19\"}]}",
decode: func(b []byte) (any, error) { var v VersionsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a release of what is not held answers released false", subject: "", given: "{\"released\":false}", wire: "{\"released\":false}",
decode: func(b []byte) (any, error) { var v ReleaseAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "a tagged version sharing its digest with another tag is kept, not removed", subject: "", given: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}", wire: "{\"kept\":true,\"reason\":\"shared-digest\",\"removed\":false,\"tags\":[\"0.1.19\"]}",
decode: func(b []byte) (any, error) { var v RemoveAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "list answers an untagged archive by the blob it keeps", subject: "", given: "{\"repositories\":[{\"manifests\":[{\"artifact\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":true,\"index\":false,\"size\":4096}],\"name\":\"mail/files\"}]}", wire: "{\"repositories\":[{\"manifests\":[{\"artifact\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":true,\"index\":false,\"size\":4096}],\"name\":\"mail/files\"}]}",
decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
if err != nil {
t.Errorf("%s: does not decode: %v", c.name, err)
continue
}
back, err := json.Marshal(v)
if err != nil {
t.Errorf("%s: does not encode: %v", c.name, err)
continue
}
var got, want any
if err := json.Unmarshal(back, &got); err != nil {
t.Fatal(err)
}
if err := json.Unmarshal([]byte(c.wire), &want); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: reads back as %s, want %s", c.name, back, c.wire)
}
if c.subjectIs != nil && !c.subjectIs.MatchString(c.subject) {
t.Errorf("%s: subject %q is not the contract's %s", c.name, c.subject, c.subjectIs)
}
}
}
@@ -1,3 +0,0 @@
module git.novox.be/novox/mesh-delivery/contracts/go/seats/ociartifactregistry
go 1.26.0
@@ -0,0 +1,162 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The seat mesh-wants' work queue read and steered by hand (design 47 H2 §777, the tools table; H-A-410): assigner_asks
// answers what waits on the seat's queue (read by the runtime without taking it) and what the assigner took and keeps
// dropped in its state taken; assigner_ask_drop ends one ask through the seat's act drop, written in the hand-act log first.
const (
asksTool = "assigner_asks"
askDropTool = "assigner_ask_drop"
)
// asksAnswerMost is the most an asks answer carries of the taken keys (§811: at most 768 KB with capped and total).
const asksAnswerMost = 768 << 10
// takenReader is what assigner_asks reads of the state taken (stdio.KeptState).
type takenReader interface {
Keys() ([]string, error)
Get(key string) (*stdio.StateEntry, error)
}
// asksOf is assigner_asks' answer: the asks on the seat's queue, each waiting, waiting again or held, the ids taken (key mesh-wants.<ask>) and the drops of
// asks not pulled yet (dropped.<ask>), each list cut at the answer's bound with capped and total.
func asksOf(waiting func(seat string) (stdio.Waiting, error), taken takenReader) (map[string]any, error) {
w, err := waiting(meshwants.Seat)
if err != nil {
return nil, fmt.Errorf("the asks waiting on the seat %s's work queue are not read: %w", meshwants.Seat, err)
}
keys, err := taken.Keys()
if err != nil {
return nil, fmt.Errorf("the state %s is not listed: %w", process.TakenState, err)
}
slices.Sort(keys)
// An ask the queue handed out and not acknowledged (again) is held when this holder took it, else it waits again after a
// nak (H-A-410's addenda): the bus says what it knows, the state taken the rest.
size := 0
waits := make([]map[string]any, 0, len(w.Asks))
for _, a := range w.Asks {
size += len(a.ID) + len(a.Module) + 64
state := "waiting"
if a.Again {
state = "waiting again"
if slices.Contains(keys, process.TakenKey(meshwants.Seat, a.ID)) {
state = "held"
}
}
waits = append(waits, map[string]any{"id": a.ID, "module": a.Module, "age_seconds": a.AgeSeconds, "state": state})
}
takenIDs, dropped := []string{}, []map[string]any{}
total, capped := 0, w.Capped
for _, k := range keys {
if id, ok := strings.CutPrefix(k, process.TakenKey(meshwants.Seat, "")); ok {
total++
if size += len(id) + 4; size > asksAnswerMost {
capped = true
continue
}
takenIDs = append(takenIDs, id)
continue
}
id, ok := strings.CutPrefix(k, droppedPrefix)
if !ok {
continue
}
total++
e, err := taken.Get(k)
if err != nil || e == nil {
continue
}
var d askDrop
if json.Unmarshal(e.Value, &d) != nil {
continue
}
if size += len(id) + len(d.By) + len(d.Why) + 64; size > asksAnswerMost {
capped = true
continue
}
dropped = append(dropped, map[string]any{"id": id, "by": d.By, "why": d.Why, "at": d.At})
}
return map[string]any{"waiting": waits, "taken": takenIDs, "dropped": dropped, "capped": capped, "total": total + len(w.Asks)}, nil
}
// asksTools are the module's tools of the seat's work queue.
func asksTools(waiting func(string) (stdio.Waiting, error), taken takenReader, ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
return []stdio.Tool{
{Name: asksTool, Description: "The asks of the seat mesh-wants' work queue (design 47 H2 §777): each one on it (its id, the module " +
"that asked it, its age and whether it waits, waits again after a hand-back or is held here), the ids the assigner took (kept for ask-taken-bound) and the drops of asks not pulled yet, " +
"cut at 768 KB with capped and total. Read-only.",
Input: schema(map[string]string{}, nil),
Run: func(map[string]any) (any, error) {
return asksOf(waiting, taken)
}},
{Name: askDropTool, Description: "End one ask of the seat mesh-wants by hand (design 47 H2 §777, §778): written in the hand-act log " +
"first, then the seat's act drop ends it: one running is cancelled, one waiting is ended when it is pulled; either ends " +
"its step could not run naming the drop and who asked it.",
Input: schema(map[string]string{"ask": "the ask's id", "why": "why the ask is ended"}, []string{"ask", "why"}),
Run: func(args map[string]any) (any, error) {
id, why := strings.TrimSpace(arg(args, "ask")), strings.TrimSpace(arg(args, "why"))
if id == "" || why == "" {
return nil, errors.New("name the ask and why it is ended")
}
by := stdio.CallerOf(args)
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: askDropTool + " " + id, Why: why + " (" + by + ")", Cause: "ask-drop"})
if err != nil {
return nil, fmt.Errorf("the hand act was not recorded, so nothing was dropped: %w", err)
}
raw, err := ask("seat:"+meshwants.Seat+"."+meshwants.VerbDrop, meshwants.DropInput{ID: id, By: askDropTool + " (" + by + ")", Why: why})
if err != nil {
return nil, err
}
var out map[string]any
if err := json.Unmarshal(raw, &out); err != nil {
return nil, fmt.Errorf("%s answered what is not JSON: %w", meshwants.VerbDrop, err)
}
out["hand-act"] = taken.Log
return out, nil
}},
}
}
// keepNowTool is the tool assigner_keep_now (design 47 H2 §813 (2); H-A-417): written in the hand-act log first, then the seat
// mesh-wants' act keep-now runs the keeping of the assignment graph's revisions at once in the assigner's process.
const keepNowTool = "assigner_keep_now"
func keepNowTools(ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
return []stdio.Tool{{Name: keepNowTool, Description: "Keep the assignment graph's revisions now (design 47 H2 §813 (2)): written in the " +
"hand-act log first, then the assigner keeps the pass's newest computed revision at once and answers the revision kept, or " +
"the fault the keeping met (a failed keeping runs again after keeping-retry; keeping-failed is raised at the third in a row).",
Input: schema(map[string]string{"why": "why the keeping runs now"}, []string{"why"}),
Run: func(args map[string]any) (any, error) {
why := strings.TrimSpace(arg(args, "why"))
if why == "" {
return nil, errors.New("say why the keeping runs now")
}
taken, err := meshhandactsclient.Recorder{Ask: ask}.Record(meshhandactsclient.Request{What: keepNowTool, Why: why + " (" + stdio.CallerOf(args) + ")", Cause: "keep-now"})
if err != nil {
return nil, fmt.Errorf("the hand act was not recorded, so nothing was kept: %w", err)
}
raw, err := ask("seat:"+meshwants.Seat+"."+meshwants.VerbKeepNow, meshwants.KeepNowInput{Why: why})
if err != nil {
return nil, err
}
var out map[string]any
if err := json.Unmarshal(raw, &out); err != nil {
return nil, fmt.Errorf("%s answered what is not JSON: %w", meshwants.VerbKeepNow, err)
}
out["hand-act"] = taken.Log
return out, nil
}}}
}
@@ -68,7 +68,7 @@ func TestTheAssignersAsksAreTheSeatMeshWantsAsks(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if v, err := meshwants.DecodeAsksByHoldModuleFingerprintValue(raw); err != nil || v.Asking != 2 {
if v, _, err := meshwants.DecodeAsksByHoldModuleFingerprintValue(raw); err != nil || v.Asking != 2 {
t.Errorf("the ask %s is not the seat's Ask: %+v, %v", raw, v, err)
}
}
@@ -15,6 +15,8 @@ import (
nec "git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
ne "git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The inputs of a composition run (design 47 G §354, §718, A-243, A-252): one request per candidate and machine, carrying that
@@ -72,28 +74,44 @@ type nodeInput struct {
// compositionInputs asks the machines of a step for their inputs.
type compositionInputs struct {
machines func(module, branch string) []string
// callFile asks a seat verb marked chunks, addressed to one node as `seat:<seat>.<verb>@<node>`, and answers the verb's answer with
// the whole file received added as its member `file`, base64 (process.Conn.CallFile; design 47 G A-237b, A-237c, A-249). The call
// token is the body's `call`.
callFile func(key string, body any) (json.RawMessage, error)
bound time.Duration
// callFile asks a seat verb marked chunks as a kept call (process.Conn.CallFileKept; design 47 H2 §775, H-A-405), addressed to
// one node as `seat:<seat>.<verb>@<node>`, carrying the ask's id and stopping at its bound, and answers the verb's answer with
// the whole file received added as its member `file`, base64 (design 47 G A-237b, A-237c, A-249). The call token is the
// body's `call`.
callFile func(ask process.KeptAsk, key string, body any) (json.RawMessage, error)
// bound is compose-ask-bound: how long a machine's compose-candidate is asked again through a transport fault (§775).
bound time.Duration
}
// of asks the machine node for its input with the candidate's key (§718): asked only by the composition step that starts the
// machine's composition run, once per candidate and machine. A node that is silent, unready or answers no input has Why set.
func (c *compositionInputs) of(ctx context.Context, node, candidate string) nodeInput {
// composeAskBoundSetting is the holder's bound on its compose-candidate asks (design 47 H2 §775): past it the machine gave no
// input, naming every call.
const (
composeAskBoundSetting = "compose-ask-bound"
defaultComposeAskBound = 10 * time.Second
)
// composeAskBound reads the setting compose-ask-bound (§781).
func composeAskBound() (time.Duration, error) {
d, err := stdio.SettingDuration(composeAskBoundSetting, defaultComposeAskBound)
if err != nil {
return 0, errors.New("the assigner's " + err.Error())
}
return d, nil
}
// composeAskID is the id of the compose-candidate ask of the step asked under stepAsk to node (H-A-405 (2)): one per node per
// step, so the engines' mesh-wide state taken keeps each apart, and a repeat to the same node carries the same id.
func composeAskID(stepAsk, node string) string { return stepAsk + "." + node }
// of asks the machine node for its input with the candidate's key (§718), as a kept call under the id of stepAsk, the step
// that starts the machine's composition run: asked once per candidate and machine, again only through a transport fault until
// compose-ask-bound (§775). A node that is silent past the bound, unready or answers no input has Why set.
func (c *compositionInputs) of(ctx context.Context, node, candidate, stepAsk string) nodeInput {
bound := c.bound
if bound <= 0 {
bound = nec.AnswerBound
bound = defaultComposeAskBound
}
return c.one(ctx, bound, node, candidate)
}
// one asks one node for its input.
func (c *compositionInputs) one(ctx context.Context, bound time.Duration, node, key string) nodeInput {
in := nodeInput{Node: node}
at, cancel := context.WithTimeout(ctx, bound)
defer cancel()
type reply struct {
raw json.RawMessage
err error
@@ -106,13 +124,14 @@ func (c *compositionInputs) one(ctx context.Context, bound time.Duration, node,
got <- reply{nil, err}
return
}
raw, err := c.callFile(composeCandidateKey+"@"+node, ne.ComposeCandidateInput{Candidate: key, Input: true, Call: hex.EncodeToString(bits[:])})
raw, err := c.callFile(process.KeptAsk{ID: composeAskID(stepAsk, node), Bound: bound}, composeCandidateKey+"@"+node,
ne.ComposeCandidateInput{Candidate: candidate, Input: true, Call: hex.EncodeToString(bits[:])})
got <- reply{raw, err}
}()
var raw json.RawMessage
select {
case <-at.Done():
in.Why = "no answer within its bound: " + at.Err().Error()
case <-ctx.Done():
in.Why = "its step's wait ended: " + context.Cause(ctx).Error()
return in
case r := <-got:
if r.err != nil {
@@ -5,6 +5,7 @@ import (
"encoding/base64"
"encoding/json"
"errors"
"git.novox.be/novox/mesh-sdk/go/process"
"regexp"
"strings"
"sync"
@@ -71,11 +72,12 @@ func TestAStepsInputsAreAskedOfEachMachine(t *testing.T) {
// the machines are asked side by side, so the record of what each was asked is guarded.
var mu sync.Mutex
asked := map[string]string{}
call := func(key string, body any) (json.RawMessage, error) {
asks := map[string]process.KeptAsk{}
call := func(ask process.KeptAsk, key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
key, node, _ := strings.Cut(key, "@") // addressed to one node (A-237b)
mu.Lock()
asked[node] = key + " " + string(raw)
asked[node], asks[node] = key+" "+string(raw), ask
mu.Unlock()
switch node {
case "g14":
@@ -98,6 +100,10 @@ func TestAStepsInputsAreAskedOfEachMachine(t *testing.T) {
if got[0].Node != "ace" || got[0].Why != "" || !strings.Contains(string(got[0].Body), "12345678901234567890") {
t.Errorf("ace: %+v", got[0])
}
// Design 47 H2 §775, H-A-405: each machine is asked as a kept call under the step's ask with the node, until compose-ask-bound.
if asks["ace"] != (process.KeptAsk{ID: "step-1.ace", Bound: time.Second}) || asks["g14"].ID != "step-1.g14" {
t.Errorf("the kept asks %+v", asks)
}
if !strings.Contains(got[1].Why, "no responders") || !strings.Contains(got[2].Why, "unready") || got[1].Body != nil || got[2].Body != nil {
t.Errorf("g14 and novox: %+v %+v", got[1], got[2])
}
@@ -115,7 +121,7 @@ func TestAStepsInputsAreAskedOfEachMachine(t *testing.T) {
func TestAStepsInputIsTheFileOfTheNodesChunks(t *testing.T) {
input := `{"n":12345678901234567890,"big":"` + strings.Repeat("x", 1<<20) + `"}`
file := base64.StdEncoding.EncodeToString([]byte(input))
call := func(key string, body any) (json.RawMessage, error) {
call := func(_ process.KeptAsk, key string, body any) (json.RawMessage, error) {
_, node, _ := strings.Cut(key, "@")
answer := `{"candidate":"run-r1","node":"` + node + `","verdict":"composed","modules":[],"own":{},"took":1,"v":1,"chunks":3`
if node == "g14" {
@@ -155,7 +161,7 @@ func gatherAll(c *compositionInputs, run meshwants.StepRun, away func(string) bo
continue
}
wg.Add(1)
go func() { defer wg.Done(); out[i] = c.of(context.Background(), node, key) }()
go func() { defer wg.Done(); out[i] = c.of(context.Background(), node, key, "step-1") }()
}
wg.Wait()
return out, nil
@@ -22,6 +22,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
)
@@ -55,6 +56,9 @@ type compositionRun struct {
keeper *inputKeeper
// call asks a seat verb held once for the mesh (process.Conn.CallKept).
call func(key string, body any) (json.RawMessage, error)
// callFile asks a seat verb held once for the mesh whose answer comes in chunks, as a kept call (process.Conn.CallFileKept),
// answering the verb's answer with the bytes received as its member `file`, base64: the validate step's seat-list (H-A-443).
callFile func(ask process.KeptAsk, key string, body any) (json.RawMessage, error)
// trunk is the trunk's catalog half as the assigner holds it.
trunk func() (mcc.Half, bool)
// newest is the newest catalog half the assigner's views hold of each watched branch (halves.views), and watched a module's
@@ -126,7 +130,7 @@ func (r *compositionRun) run(ctx context.Context, id string, step meshwants.Step
continue
}
if j.started {
go r.start(ctx, j.key, j.run, prep)
go r.start(ctx, j.key, j.run, prep, id)
}
keys = append(keys, j.key)
}
@@ -216,7 +220,7 @@ type runPrep struct {
seats []json.RawMessage
manifests map[string]composer.Manifest
none map[string]string
programOf func(node string) (buildstep.RunProgram, string, error)
programOf func(node string) (buildstep.RunProgram, string, map[string]string, error)
err error
}
@@ -241,9 +245,9 @@ func (p *runPrep) get(ctx context.Context) error {
return p.err
}
// start composes the machine of the run it started (§718): the node's input of this moment, its request kept once in `inputs`,
// start composes the machine of the run the step asked under stepAsk started (§718): the node's input of this moment, its request kept once in `inputs`,
// the composer program chosen and recorded with the request's digest, and one run ask put. A fault ends the run could not run.
func (r *compositionRun) start(ctx context.Context, key string, run meshwants.CompositionRun, prep *runPrep) {
func (r *compositionRun) start(ctx context.Context, key string, run meshwants.CompositionRun, prep *runPrep, stepAsk string) {
node, ask := run.Machine, run.Ask
end := func(said string) {
if _, err := r.runs.endRun(key, ask, meshwants.CompositionRunOutcomeCouldNotRun, said, nil); err != nil {
@@ -269,12 +273,12 @@ func (r *compositionRun) start(ctx context.Context, key string, run meshwants.Co
end(node + ": " + err.Error())
return
}
in := r.inputs.of(ctx, node, run.Candidate)
in := r.inputs.of(ctx, node, run.Candidate, stepAsk) // a kept call under the starting step's ask with the node (H-A-405)
if in.Why != "" {
end(node + " gave no composition input: " + in.Why)
return
}
program, engineFp, err := prep.programOf(node)
program, engineFp, pins, err := prep.programOf(node)
if err != nil {
end(node + ": " + err.Error())
return
@@ -317,7 +321,8 @@ func (r *compositionRun) start(ctx context.Context, key string, run meshwants.Co
return
}
a := buildstep.StepAsk{ID: ask, Kind: buildstep.AskCheck, Language: buildstep.AskGo, Asker: runAsker, At: r.now().UTC(),
Run: &buildstep.RunJob{Program: program, Heads: []buildstep.RunHead{}, Input: ref, Reader: "the composition of " + node + " by the node-engine at " + program.Commit}}
Run: &buildstep.RunJob{Program: program, Heads: []buildstep.RunHead{}, Input: ref, Reader: "the composition of " + node + " by the node-engine at " + program.Commit},
Packages: pins} // the composer is built against its entry's pins, as every build (H-A-203, H-A-192)
if err := r.put(ctx, a); err != nil {
end(node + ": its run ask " + ask + " is not put: " + err.Error())
}
@@ -732,53 +737,76 @@ func programOfEntry(e meshcatalog.CatalogEntry) (buildstep.RunProgram, error) {
return buildstep.RunProgram{Repository: e.Repository, Commit: e.Commit, Dir: dir, Package: composer.Package}, nil
}
// pinsOfEntry are the mesh packages' versions an entry pins, the ones it names with a version (H-A-203, H-A-183): the pins
// a run's program is built against, in the form the entry keeps and the builder sends. nil when it pins none.
func pinsOfEntry(e meshcatalog.CatalogEntry) map[string]string {
var out map[string]string
for path, version := range e.Packages {
if version == "" {
continue
}
if out == nil {
out = map[string]string{}
}
out[path] = version
}
return out
}
// programs answers, per machine, the composer its run builds and the node-engine fingerprint it was chosen from (A-226, A-243,
// A-252, §719): where the revision's node-engine entry differs from the trunk's, that build for every machine; else the build the
// machine's node-engine runs, as its `running` says, its entry read through mesh-catalog's `entry`; a machine whose node-engine's
// `running` is not heard gets the revision's entry, said (A-451).
func (r *compositionRun) programs(ctx context.Context, half mcc.Half) (func(node string) (buildstep.RunProgram, string, error), error) {
func (r *compositionRun) programs(ctx context.Context, half mcc.Half) (func(node string) (buildstep.RunProgram, string, map[string]string, error), error) {
engine, ok := nodeEngineEntry(half.Entries)
if !ok {
return nil, fmt.Errorf("the catalog revision %d holds no module claiming the seat %s", half.Revision.Revision, ne.Seat)
}
if trunk, ok := r.trunk(); !ok || func() bool { t, ok := nodeEngineEntry(trunk.Entries); return !ok || t.Fp != engine.Fp }() {
p, err := programOfEntry(engine)
return func(string) (buildstep.RunProgram, string, error) { return p, engine.Fp, err }, nil
return func(string) (buildstep.RunProgram, string, map[string]string, error) {
return p, engine.Fp, pinsOfEntry(engine), err
}, nil
}
var mu sync.Mutex
byFp := map[string]buildstep.RunProgram{}
return func(node string) (buildstep.RunProgram, string, error) {
type built struct {
program buildstep.RunProgram
pins map[string]string
}
byFp := map[string]built{}
return func(node string) (buildstep.RunProgram, string, map[string]string, error) {
running, ok := r.running(node, engine.Module)
if !ok || running.Fingerprint == "" {
r.logf("%s: no build of %s is heard running there, so its composer is the catalog revision's entry %s (A-451)", node,
engine.Module, engine.Fp)
p, err := programOfEntry(engine)
return p, engine.Fp, err
return p, engine.Fp, pinsOfEntry(engine), err
}
fp := running.Fingerprint
mu.Lock()
p, ok := byFp[fp]
b, ok := byFp[fp]
mu.Unlock()
if ok {
return p, fp, nil
return b.program, fp, b.pins, nil
}
what := "the entry of the node-engine's build " + fp + " is not read"
body, said, err := r.callRetry(ctx, entryVerbKey, meshcatalog.EntryInput{Fingerprint: fp})
if err != nil || body == nil {
return buildstep.RunProgram{}, fp, unreadErr(what, err, said)
return buildstep.RunProgram{}, fp, nil, unreadErr(what, err, said)
}
var a meshcatalog.EntryAnswer
if err := json.Unmarshal(body, &a); err != nil {
return buildstep.RunProgram{}, fp, fmt.Errorf("%s: %w", what, err)
return buildstep.RunProgram{}, fp, nil, fmt.Errorf("%s: %w", what, err)
}
p, err = programOfEntry(a.Entry)
p, err := programOfEntry(a.Entry)
if err != nil {
return p, fp, err
return p, fp, nil, err
}
pins := pinsOfEntry(a.Entry)
mu.Lock()
byFp[fp] = p
byFp[fp] = built{program: p, pins: pins}
mu.Unlock()
return p, fp, nil
return p, fp, pins, nil
}, nil
}
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"errors"
"git.novox.be/novox/mesh-sdk/go/process"
"maps"
"slices"
"strings"
@@ -53,7 +54,7 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
s := &runStand{asks: map[string]buildstep.StepAsk{}, requests: map[string]composer.Request{}}
engine := func(fp, commit string) meshcatalog.CatalogEntry {
return meshcatalog.CatalogEntry{Module: "engine", Fp: fp, Repository: "novox/mesh-host", Commit: commit, Path: ".", Serves: []string{ne.Seat + ".composition"},
Manifest: map[string]any{"module": "engine"}}
Manifest: map[string]any{"module": "engine"}, Packages: map[string]string{"git.novox.be/novox/mesh-sdk/go": "v0.1.25-" + fp, "git.novox.be/novox/x/go": ""}}
}
revisionCommit := commitE1
if revisionEngine != "src2:e1" {
@@ -103,7 +104,7 @@ func newRunStand(t *testing.T, revisionEngine, trunkEngine, seatDigest string) *
}
return nil, errors.New("no such verb " + key)
}
engines := func(key string, _ any) (json.RawMessage, error) {
engines := func(_ process.KeptAsk, key string, _ any) (json.RawMessage, error) {
_, node, _ := strings.Cut(key, "@") // addressed to one node (A-237b)
return json.RawMessage(`{"candidate":"main.7","node":"` + node + `","verdict":"composed","input":{"node":"` + node + `"},"modules":[],"own":{},"took":1,"v":1}`), nil
}
@@ -186,6 +187,13 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
if s.asks["g14"].Run.Program.Commit != commitE2 {
t.Errorf("g14's composer is built at %s, want the build its node-engine runs", s.asks["g14"].Run.Program.Commit)
}
// Each composer is built against the pins of the node-engine entry it is built from, a pin with no version left out
// (H-A-203, H-A-192).
for node, fp := range map[string]string{"ace": "src2:e1", "g14": "src2:e2"} {
if got := s.asks[node].Packages; len(got) != 1 || got["git.novox.be/novox/mesh-sdk/go"] != "v0.1.25-"+fp {
t.Errorf("%s's composer is built against the pins %v; want its entry's", node, got)
}
}
if req.Depth != composer.DepthCompose || req.BlameTries != 20 || len(req.Machines) != 1 || req.Machines[0] != "ace" || len(req.Cases) != 1 || req.Cases[0].Name != changeCase ||
string(req.Input) != `{"node":"ace"}` || len(req.Seats) != 1 || string(req.Seats[0]) != `{"seat":"s1"}` {
t.Errorf("the request of ace %+v", req)
@@ -631,7 +639,7 @@ func TestARerunMovesEveryReaderThatDidNotPass(t *testing.T) {
}
got := map[string]meshwants.StepEnded{}
for _, m := range []string{"a", "b", "d"} {
steps.take(context.Background(), "ask-"+m, step(m, false))
pullOne(steps, "ask-"+m, step(m, false))
e := <-ends
got[e.Module] = e
}
@@ -642,7 +650,7 @@ func TestARerunMovesEveryReaderThatDidNotPass(t *testing.T) {
mu.Lock()
fixed = true
mu.Unlock()
steps.take(context.Background(), "ask-a2", step("a", true))
pullOne(steps, "ask-a2", step("a", true))
moved := map[string]meshwants.StepEnded{}
for range 2 {
select {
@@ -126,7 +126,7 @@ func TestOneCompositionRunPerCandidateAndMachine(t *testing.T) {
from := b.journal.mark()
_, stop := b.startStoppable(t)
b.journal.await(t, from, "the composition step is heard on", "the composition step served", 30*time.Second)
b.journal.await(t, from, "the composition step is pulled from", "the composition step served", 30*time.Second)
select {
case <-b.seatListRead:
case <-time.After(30 * time.Second):
@@ -2,14 +2,11 @@ package main
import (
"context"
"encoding/json"
"errors"
"sync"
"time"
"github.com/nats-io/nats.go"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The composition step (design 47 G §22, §354, §63): the assigner takes the seat mesh-wants' accepted kind `step`, the
@@ -44,9 +41,18 @@ type compositionSteps struct {
logf func(string, ...any)
// ticks is a ticker of every d, its channel and its stop (time.NewTicker); nil is the clock's. A test hands its own.
ticks func(d time.Duration) (<-chan time.Time, func())
mu sync.Mutex
// stops ends the wait of a running step by its ask's id, when its pipeline is superseded or cancelled (leave).
stops map[string]context.CancelFunc
// taken is the state taken (stepqueue.go): each ask pulled is taken once by its id, for takenBound; the drops of asks not
// pulled yet are kept there too (H-A-404).
taken takenStore
takenBound time.Duration
// inProgress is how often a running step's pulled ask is said in progress: the seat definition's in-progress (§777).
inProgress func() time.Duration
mu sync.Mutex
// stops ends the wait of a running step by its ask's id, when its pipeline is superseded or cancelled (leave), or the ask is
// dropped (the cause an *askDrop).
stops map[string]context.CancelCauseFunc
// held are the messages pulled from the seat's work queue for each running step's ask, acknowledged once its end is said.
held map[string][]queueMsg
}
// progressEvery is how often a running composition step says its progress (design 47 G §496, A-262).
@@ -92,20 +98,6 @@ func (p *stepPhase) get() string {
return p.phase
}
// take takes one ask of the accepted kind `step` by its id and body: a step that is no composition or validate step, or an
// ask with no id, is left with a log line; one taken is run in its own goroutine and its end said.
func (c *compositionSteps) take(ctx context.Context, id string, data []byte) bool {
var run meshwants.StepRun
err := json.Unmarshal(data, &run)
how := c.howOf(run.Step, false)
if err != nil || id == "" || how == nil {
c.logf("a step ask that is no composition or validate step with an id is left: %v", err)
return false
}
go c.say1(ctx, id, run, how, "")
return true
}
// howOf is what runs a step, or judges it once taken up at the start: by its step, composition or validate; nil for another.
func (c *compositionSteps) howOf(step string, resumed bool) func(context.Context, string, meshwants.StepRun) stepOutcome {
switch {
@@ -124,16 +116,16 @@ func (c *compositionSteps) howOf(step string, resumed bool) func(context.Context
// say1 runs one step with how and says its end, naming in `shared` the runs it read (§723); again is, for an end said again, the
// ask of the run whose end makes it say again (sayEnd). A step whose wait was ended by its pipeline's supersede or cancel (leave)
// says nothing: the runner ended it already.
func (c *compositionSteps) say1(ctx context.Context, id string, run meshwants.StepRun, how func(context.Context, string, meshwants.StepRun) stepOutcome, again string) {
func (c *compositionSteps) say1(parent context.Context, id string, run meshwants.StepRun, how func(context.Context, string, meshwants.StepRun) stepOutcome, again string) {
started := c.now().UTC()
ctx, stopWait := context.WithCancel(ctx)
ctx, stopWait := context.WithCancelCause(parent)
c.mu.Lock()
if c.stops == nil {
c.stops = map[string]context.CancelFunc{}
c.stops = map[string]context.CancelCauseFunc{}
}
if c.stops[id] != nil { // the step asked under id is running already: it says its own end
c.mu.Unlock()
stopWait()
stopWait(nil)
return
}
c.stops[id] = stopWait
@@ -142,14 +134,25 @@ func (c *compositionSteps) say1(ctx context.Context, id string, run meshwants.St
c.mu.Lock()
delete(c.stops, id)
c.mu.Unlock()
stopWait()
stopWait(nil)
}()
phase := &stepPhase{phase: meshwants.StepProgressEventPhaseFetch}
stop := c.sayProgress(id, run.Asker, phase)
stopInProgress := c.inProgressEvery(id)
o := how(context.WithValue(ctx, phaseKey{}, phase), id, run)
stopInProgress()
stop()
if ctx.Err() != nil {
if parent.Err() != nil { // the assigner stops: its pulled asks are handed again to its next start
return
}
var d *askDrop
if errors.As(context.Cause(ctx), &d) { // dropped through the seat's drop (§778, H-A-401)
c.sayEnd(id, run, &started, stepOutcome{Outcome: meshwants.StepEndedOutcomeCouldNotRun, Said: d.Error(), Shared: o.Shared}, again)
return
}
c.logf("the composition step %s of %s says no end: its wait ended (%v)", id, run.Pipeline, context.Cause(ctx))
c.settle(id, true) // the runner ended it already: its ask is over
return
}
c.sayEnd(id, run, &started, o, again)
@@ -175,9 +178,13 @@ func (c *compositionSteps) sayEnd(id string, run meshwants.StepRun, started *tim
msgID = id + "." + again
}
if err := c.say(meshwants.EventStepEnded+"."+c.node, end, msgID); err != nil {
c.logf("saying the end of the composition step %s: %v", id, err)
c.logf("saying the end of the composition step %s: %v; its ask is handed again", id, err)
c.settle(id, false)
return
}
c.settle(id, true) // the ask's end is said: its pulled messages leave the seat's work queue (§777)
// One journal line per ask answered, in the one place it is answered (design 47 H2 §792).
c.logf("answered %s %s %s %s %s", id, run.Pipeline, run.Module, step, o.Outcome)
if c.ended != nil {
c.ended(id, run, ended)
}
@@ -210,7 +217,7 @@ func (c *compositionSteps) leave(ids []string) {
defer c.mu.Unlock()
for _, id := range ids {
if stop := c.stops[id]; stop != nil {
stop()
stop(nil)
}
}
}
@@ -243,21 +250,3 @@ func (c *compositionSteps) sayProgress(id, asker string, phase *stepPhase) (stop
}()
return func() { close(done); <-ended }
}
// stepAskID is an ask's id as the asker names it: its event id, else its message id.
func stepAskID(m *nats.Msg) string {
if id := m.Header.Get("x-event-id"); id != "" {
return id
}
return m.Header.Get(nats.MsgIdHdr)
}
// serveCompositionSteps hears the composition step asks on the seat mesh-wants' accept subject.
func serveCompositionSteps(ctx context.Context, conn process.Subscriber, c *compositionSteps) error {
sub, err := conn.Subscribe(meshwants.AcceptSubjectStep, func(m *nats.Msg) { c.take(ctx, stepAskID(m), m.Data) })
if err != nil {
return err
}
go func() { <-ctx.Done(); _ = sub.Drain() }()
return nil
}
@@ -106,7 +106,7 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
from := b.journal.mark()
b.start(t)
b.journal.await(t, from, "the composition step is heard on", "the composition step served", 30*time.Second)
b.journal.await(t, from, "the composition step is pulled from", "the composition step served", 30*time.Second)
b.journal.await(t, from, "n3 is away (machine-away)", "the machine-away of n3 heard", 30*time.Second)
select {
@@ -114,14 +114,8 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
case <-time.After(30 * time.Second):
t.Fatal("the assigner did not read the seat list within 30 s")
}
step, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.3.m", Step: meshwants.StepRunStepComposition, Module: "m", Branch: trunkBranch,
putStep(b.ctx, t, b.js, "step-ask-1", meshwants.StepRun{Pipeline: "main.3.m", Step: meshwants.StepRunStepComposition, Module: "m", Branch: trunkBranch,
Revision: 3, Commit: engineCommit, Fingerprint: "src2:m1"})
msg := nats.NewMsg(meshwants.AcceptSubjectStep)
msg.Header.Set("x-event-id", "step-ask-1")
msg.Data = step
if err := nc.PublishMsg(msg); err != nil {
t.Fatal(err)
}
// The stand-in Go build seat takes the run asks put under the assigner's name, reads each request by the verb input and says
// its end with the composer's verdict: n1 composes, n2 does not.
@@ -201,6 +195,7 @@ func TestTheCompositionStepComposesEachMachineThroughTheBuildSeat(t *testing.T)
t.Fatalf("the inputs stay kept past their step-ended: %v", keys)
}
}
queueEmpty(b.ctx, t, b.js) // the step's ask acknowledged at its end (design 47 H2 §777)
}
// readInput reads a run's input as a build seat does: the seat mesh-wants' verb input answers its digest and chunk count, then its
@@ -288,9 +283,37 @@ func TestTheValidateStepServedWholeRefusesAManifestProblemAndACycle(t *testing.T
}
t.Cleanup(func() { _ = ends.Unsubscribe() })
subscribed(t, nc)
// Design 47 H2 §777: a validate ask put while the assigner is stopped waits on the seat's work queue, and is taken (ask-taken)
// and ended after its start.
taken := make(chan *nats.Msg, 8)
takens, err := nc.ChanSubscribe(meshwants.SubjectAskTakenAll, taken)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = takens.Unsubscribe() })
subscribed(t, nc)
putStep(b.ctx, t, b.js, "validate-9", meshwants.StepRun{Pipeline: trunkBranch + ".9", Step: meshwants.StepRunStepValidate, Module: "a",
Branch: trunkBranch, Revision: 9, Commit: commit})
from := b.journal.mark()
b.start(t)
b.journal.await(t, from, "the composition step is heard on", "the steps served", 30*time.Second)
b.journal.await(t, from, "the composition step is pulled from", "the steps served", 30*time.Second)
select {
case m := <-taken:
var at meshwants.AskTakenEvent
if err := json.Unmarshal(m.Data, &at); err != nil || at.Ask != "validate-9" || at.Node != "n1" || at.At.IsZero() || m.Subject != meshwants.SubjectAskTaken("validate-9") {
t.Fatalf("ask-taken on %s = %+v, %v; want validate-9 taken on n1", m.Subject, at, err)
}
case <-time.After(30 * time.Second):
t.Fatal("no ask-taken within 30 s of the start for the ask put while the assigner was stopped")
}
select {
case e := <-ended:
if e.ID != "validate-9" || e.Outcome != meshwants.StepEndedOutcomeFailed || e.Said != reasonCycle+": a:x → b:y → a:x" {
t.Errorf("the validate step of a take-in making a cycle ended %+v", e)
}
case <-time.After(30 * time.Second):
t.Fatal("the validate ask put while the assigner was stopped said no end")
}
select {
case <-b.seatListRead:
case <-time.After(30 * time.Second):
@@ -306,12 +329,9 @@ func TestTheValidateStepServedWholeRefusesAManifestProblemAndACycle(t *testing.T
id := fmt.Sprintf("validate-%d", revision)
step, _ := json.Marshal(meshwants.StepRun{Pipeline: fmt.Sprintf("%s.%d", trunkBranch, revision), Step: meshwants.StepRunStepValidate, Module: module,
Branch: trunkBranch, Revision: revision, Commit: commit})
msg := nats.NewMsg(meshwants.AcceptSubjectStep)
msg.Header.Set("x-event-id", id)
msg.Data = step
if err := nc.PublishMsg(msg); err != nil {
t.Fatal(err)
}
var asked meshwants.StepRun
_ = json.Unmarshal(step, &asked)
putStep(b.ctx, t, b.js, id, asked)
if run != nil {
run()
}
@@ -342,6 +362,12 @@ func TestTheValidateStepServedWholeRefusesAManifestProblemAndACycle(t *testing.T
if err != nil || len(req.Cases) != 2 || req.Cases[0].Name != changeCase || req.Cases[1].Name != beforeCase {
t.Fatalf("the validator's request: %+v %v", req, err)
}
// The revision names no definitions: the request holds the trunk's seat list as seat-list handed it, named by its digest (H-A-443).
if list, digest := seatListBytes(); req.SeatList != digest {
t.Errorf("the validator's request names the seat list %q, want %q", req.SeatList, digest)
} else if got, _ := json.Marshal(req.Seats); string(got) != string(list) {
t.Errorf("the validator's request holds seats %d bytes long, not the seat list's %d", len(got), len(list))
}
v := composer.Verdict{V: composer.Version}
for _, c := range req.Cases {
reads := map[string]composer.ManifestRead{}
@@ -365,10 +391,8 @@ func TestTheValidateStepServedWholeRefusesAManifestProblemAndACycle(t *testing.T
if e := ask(8, "web", validator); e.Outcome != meshwants.StepEndedOutcomePassed {
t.Errorf("the validate step of a manifest with no problem ended %+v", e)
}
if e := ask(9, "a", nil); e.Outcome != meshwants.StepEndedOutcomeFailed || e.Said != reasonCycle+": a:x → b:y → a:x" {
t.Errorf("the validate step of a take-in making a cycle ended %+v", e)
}
if info, err := worker.Info(b.ctx); err != nil || info.NumPending != 0 {
t.Errorf("a validator is asked for the cycle: %+v %v", info, err)
}
queueEmpty(b.ctx, t, b.js) // every ask acknowledged at its end (§777)
}
@@ -3,15 +3,115 @@ package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"sync"
"testing"
"time"
"github.com/nats-io/nats.go"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// fakeMsg is one ask pulled from the seat's work queue, recording how it was settled.
type fakeMsg struct {
data []byte
h nats.Header
mu sync.Mutex
acks, naks, terms, inProgresss int
}
func (m *fakeMsg) Data() []byte { return m.data }
func (m *fakeMsg) Headers() nats.Header { return m.h }
func (m *fakeMsg) count(n *int) error { m.mu.Lock(); *n++; m.mu.Unlock(); return nil }
func (m *fakeMsg) Ack() error { return m.count(&m.acks) }
func (m *fakeMsg) Nak() error { return m.count(&m.naks) }
func (m *fakeMsg) Term() error { return m.count(&m.terms) }
func (m *fakeMsg) InProgress() error { return m.count(&m.inProgresss) }
func (m *fakeMsg) settled() (acks, naks, terms, progress int) {
m.mu.Lock()
defer m.mu.Unlock()
return m.acks, m.naks, m.terms, m.inProgresss
}
// fakeTaken is the state taken: its keys, each with its time to live, and a refusal of TakeOnce when refuse is set.
type fakeTaken struct {
mu sync.Mutex
values map[string][]byte
ttls map[string]time.Duration
refuse error
}
func newFakeTaken() *fakeTaken {
return &fakeTaken{values: map[string][]byte{}, ttls: map[string]time.Duration{}}
}
func (f *fakeTaken) TakeOnce(seat, ask string, bound time.Duration) (bool, error) {
f.mu.Lock()
defer f.mu.Unlock()
if f.refuse != nil {
return false, f.refuse
}
key := seat + "." + ask
if _, ok := f.values[key]; ok {
return false, nil
}
f.values[key], f.ttls[key] = []byte(`{}`), bound
return true, nil
}
func (f *fakeTaken) Get(key string) (*stdio.StateEntry, error) {
f.mu.Lock()
defer f.mu.Unlock()
v, ok := f.values[key]
if !ok {
return nil, nil
}
return &stdio.StateEntry{Key: key, Value: v}, nil
}
func (f *fakeTaken) RenewTTL(key string, value any, ttl time.Duration) (uint64, error) {
raw, err := json.Marshal(value)
f.mu.Lock()
defer f.mu.Unlock()
f.values[key], f.ttls[key] = raw, ttl
return 1, err
}
func (f *fakeTaken) Delete(key string) error {
f.mu.Lock()
defer f.mu.Unlock()
delete(f.values, key)
return nil
}
func (f *fakeTaken) Keys() ([]string, error) {
f.mu.Lock()
defer f.mu.Unlock()
var out []string
for k := range f.values {
out = append(out, k)
}
return out, nil
}
// pullOne hands c one ask pulled from the seat's work queue under id, with a state taken of its own when c has none.
func pullOne(c *compositionSteps, id string, body []byte) *fakeMsg {
if c.taken == nil {
c.taken = newFakeTaken()
}
m := &fakeMsg{data: body, h: nats.Header{}}
if id != "" {
m.h.Set("x-event-id", id)
}
c.pulled(context.Background(), m)
return m
}
// saidEvents keeps what a publisher says.
type saidEvents struct {
mu sync.Mutex
@@ -38,24 +138,34 @@ func TestTheCompositionStepIsTakenAndItsEndSaid(t *testing.T) {
said := newSaidEvents()
at := time.Date(2026, 11, 12, 9, 0, 0, 0, time.UTC)
var asked meshwants.StepRun
c := &compositionSteps{node: "n1", say: said.say, now: func() time.Time { return at }, logf: t.Logf,
var lines []string
var linesMu sync.Mutex
logf := func(f string, a ...any) {
linesMu.Lock()
lines = append(lines, fmt.Sprintf(f, a...))
linesMu.Unlock()
}
c := &compositionSteps{node: "n1", say: said.say, now: func() time.Time { return at }, logf: logf,
run: func(_ context.Context, id string, run meshwants.StepRun) stepOutcome {
asked = run
return stepOutcome{Outcome: meshwants.StepEndedOutcomeFailed, Said: "a and b own /etc/x", Warnings: []string{"n3 asleep"},
Shared: []meshwants.Shared{{Machine: "n1", Run: "main=2e4.n1", Ask: "run-1"}}}
}}
other, _ := json.Marshal(map[string]any{"pipeline": "main.4.m", "step": "build", "module": "m"})
if c.take(context.Background(), "ask-0", other) {
if m := pullOne(c, "ask-0", other); m.terms != 1 {
t.Fatal("a step ask of another step is taken")
}
body, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.4.m", Step: meshwants.StepRunStepComposition, Module: "m", Branch: "main",
Commit: "c0ffee", Revision: 4, Fingerprint: "fp1", Rerun: true, By: "lead@n1"})
if c.take(context.Background(), "", body) {
if m := pullOne(c, "", body); m.terms != 1 {
t.Fatal("a step ask with no id is taken")
}
if !c.take(context.Background(), "ask-1", body) {
if m := pullOne(c, "ask-1", body); m.terms != 0 {
t.Fatal("the composition step is not taken")
}
if e := <-said.heard; e != meshwants.EventAskTaken+".ask-1" { // said at the pull (H2 §777)
t.Fatalf("said %s first, want ask-taken", e)
}
select {
case <-said.heard:
case <-time.After(5 * time.Second):
@@ -73,6 +183,211 @@ func TestTheCompositionStepIsTakenAndItsEndSaid(t *testing.T) {
len(end.Shared) != 1 || end.Shared[0] != (meshwants.Shared{Machine: "n1", Run: "main=2e4.n1", Ask: "run-1"}) { // §723, §729
t.Fatalf("step-ended %+v", end)
}
// Design 47 H2 §792: the ask answered is one journal line, said where its end is said.
linesMu.Lock()
answered := slices.DeleteFunc(slices.Clone(lines), func(l string) bool { return !strings.HasPrefix(l, "answered ") })
linesMu.Unlock()
if !slices.Equal(answered, []string{"answered ask-1 main.4.m m composition failed"}) {
t.Errorf("the journal says %q, want one answered line", answered)
}
// Design 47 H2 §777, §775 (H-A-381, H-A-401, H-A-404): the asks of the seat's work queue, taken once by id, said ask-taken at
// the pull, in progress while they run, acknowledged once their end is said, and ended by the seat's drop.
t.Run("work queue", queueCases)
}
func queueCases(t *testing.T) {
at := time.Date(2026, 11, 22, 1, 0, 0, 0, time.UTC)
body, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.4.m", Step: meshwants.StepRunStepValidate, Module: "m", Branch: "main", Revision: 4})
type bed struct {
c *compositionSteps
said *saidEvents
taken *fakeTaken
runs chan string
release chan struct{}
tick chan time.Time
}
newBed := func() *bed {
b := &bed{said: newSaidEvents(), taken: newFakeTaken(), runs: make(chan string, 8), release: make(chan struct{}), tick: make(chan time.Time)}
b.said.heard = make(chan string, 16)
run := func(ctx context.Context, id string, _ meshwants.StepRun) stepOutcome {
b.runs <- id
select {
case <-b.release:
case <-ctx.Done():
}
return stepOutcome{Outcome: meshwants.StepEndedOutcomePassed}
}
b.c = &compositionSteps{node: "n1", say: b.said.say, now: func() time.Time { return at }, logf: t.Logf, taken: b.taken, takenBound: 10 * time.Minute,
validate: run, inProgress: func() time.Duration { return 20 * time.Second },
ticks: func(d time.Duration) (<-chan time.Time, func()) {
if d == 20*time.Second {
return b.tick, func() {}
}
return make(chan time.Time), func() {}
}}
return b
}
ended := func(t *testing.T, b *bed) meshwants.StepEnded {
t.Helper()
for {
select {
case e := <-b.said.heard:
if e == meshwants.EventStepEnded+".n1" {
b.said.mu.Lock()
defer b.said.mu.Unlock()
return b.said.said[e].(meshwants.StepEnded)
}
case <-time.After(5 * time.Second):
t.Fatal("no step-ended is said")
}
}
}
settledAt := func(t *testing.T, m *fakeMsg, acks int) {
t.Helper()
deadline := time.After(5 * time.Second)
for {
if a, _, _, _ := m.settled(); a == acks {
return
}
select {
case <-deadline:
t.Fatalf("the ask is acknowledged %d times, want %d", m.acks, acks)
case <-time.After(time.Millisecond):
}
}
}
t.Run("taken once, said, in progress, acknowledged at its end", func(t *testing.T) {
b := newBed()
m := pullOne(b.c, "ask-1", body)
if id := <-b.runs; id != "ask-1" {
t.Fatalf("ran %s", id)
}
b.said.mu.Lock()
taken, ok := b.said.said[meshwants.EventAskTaken+".ask-1"].(meshwants.AskTakenEvent)
takenID := b.said.ids[meshwants.EventAskTaken+".ask-1"]
b.said.mu.Unlock()
if !ok || taken.Ask != "ask-1" || taken.Node != "n1" || !taken.At.Equal(at) || takenID != "ask-1.taken" || b.taken.ttls["mesh-wants.ask-1"] != 10*time.Minute {
t.Fatalf("ask-taken %+v under %q, taken %v", taken, takenID, b.taken.ttls)
}
b.tick <- at
b.tick <- at
// handed again while it runs: held for the run, which answers both at its one end
again := pullOne(b.c, "ask-1", body)
if a, n, _, p := m.settled(); a != 0 || n != 0 || p < 1 {
t.Fatalf("before its end the ask is acked %d, nakked %d, in progress %d times", a, n, p)
}
close(b.release)
if e := ended(t, b); e.ID != "ask-1" || e.Outcome != meshwants.StepEndedOutcomePassed {
t.Fatalf("step-ended %+v", e)
}
settledAt(t, m, 1)
settledAt(t, again, 1)
select {
case id := <-b.runs:
t.Fatalf("the ask handed again ran again (%s)", id)
default:
}
})
t.Run("taken before is run again, said no ask-taken", func(t *testing.T) {
b := newBed()
_, _ = b.taken.TakeOnce(meshwants.Seat, "ask-2", time.Minute)
close(b.release)
m := pullOne(b.c, "ask-2", body)
<-b.runs
ended(t, b)
settledAt(t, m, 1)
b.said.mu.Lock()
_, said := b.said.said[meshwants.EventAskTaken+".ask-2"]
b.said.mu.Unlock()
if said {
t.Fatal("ask-taken is said again for an ask taken before")
}
})
t.Run("a refused take is handed again", func(t *testing.T) {
b := newBed()
b.taken.refuse = errors.New("no bus")
m := pullOne(b.c, "ask-3", body)
if _, n, _, _ := m.settled(); n != 1 || len(b.runs) != 0 {
t.Fatalf("nakked %d, ran %d", n, len(b.runs))
}
})
t.Run("dropped while it runs", func(t *testing.T) {
b := newBed()
m := pullOne(b.c, "ask-4", body)
<-b.runs
if _, err := b.c.dropAsk("n1.mesh-pipeline-runner", meshwants.DropInput{ID: "ask-4"}); err == nil {
t.Fatal("a drop with no why is taken")
}
a, err := b.c.dropAsk("n1.mesh-pipeline-runner", meshwants.DropInput{ID: "ask-4", Why: "its bound passed"})
if err != nil || a["held"] != true {
t.Fatalf("drop answered %v, %v", a, err)
}
e := ended(t, b)
if e.Outcome != meshwants.StepEndedOutcomeCouldNotRun || e.Said != "the ask was dropped by n1.mesh-pipeline-runner: its bound passed" {
t.Fatalf("step-ended %+v", e)
}
settledAt(t, m, 1)
})
t.Run("dropped before it was pulled", func(t *testing.T) {
b := newBed()
a, err := b.c.dropAsk("n1.mesh-pipeline-runner", meshwants.DropInput{ID: "ask-5", By: "the runner", Why: "its bound passed"})
if err != nil || a["held"] != false || b.taken.ttls["dropped.ask-5"] != 10*time.Minute {
t.Fatalf("drop answered %v, %v; taken %v", a, err, b.taken.ttls)
}
m := pullOne(b.c, "ask-5", body)
e := ended(t, b)
if e.ID != "ask-5" || e.Outcome != meshwants.StepEndedOutcomeCouldNotRun || e.Said != "the ask was dropped by the runner: its bound passed" {
t.Fatalf("step-ended %+v", e)
}
settledAt(t, m, 1)
if len(b.runs) != 0 {
t.Fatal("a dropped ask ran")
}
if v, _ := b.taken.Get("dropped.ask-5"); v != nil {
t.Fatal("the drop's key stays once its ask ended")
}
})
t.Run("the asks tools", func(t *testing.T) {
taken := newFakeTaken()
_, _ = taken.TakeOnce(meshwants.Seat, "ask-6", time.Minute)
_, _ = taken.RenewTTL("dropped.ask-7", askDrop{By: "the runner", Why: "its bound passed", At: at}, time.Minute)
waiting := func(seat string) (stdio.Waiting, error) {
if seat != meshwants.Seat {
t.Errorf("the waiting asks of %s are read", seat)
}
return stdio.Waiting{Asks: []stdio.WaitingAsk{{ID: "ask-8", Module: "mesh-delivery-pipeline", AgeSeconds: 3},
{ID: "ask-6", Module: "mesh-delivery-pipeline", Again: true}, {ID: "ask-9", Module: "mesh-delivery-pipeline", Again: true}}}, nil
}
var asked []string
ask := func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, key+" "+string(raw))
if strings.HasSuffix(key, "."+meshwants.VerbDrop) {
return json.RawMessage(`{"held":false}`), nil
}
return json.RawMessage(`{}`), nil
}
tools := map[string]stdio.Tool{}
for _, tool := range asksTools(waiting, taken, ask) {
tools[tool.Name] = tool
}
out, err := tools[asksTool].Run(map[string]any{})
a, _ := out.(map[string]any)
w, _ := a["waiting"].([]map[string]any)
d, _ := a["dropped"].([]map[string]any)
if err != nil || len(w) != 3 || w[0]["id"] != "ask-8" || w[0]["state"] != "waiting" || w[1]["state"] != "held" || w[2]["state"] != "waiting again" || !slices.Equal(a["taken"].([]string), []string{"ask-6"}) || len(d) != 1 ||
d[0]["id"] != "ask-7" || d[0]["by"] != "the runner" || a["total"] != 5 || a["capped"] != false {
t.Fatalf("assigner_asks answered %+v, %v", out, err)
}
if _, err := tools[askDropTool].Run(map[string]any{"ask": "ask-8"}); err == nil || len(asked) != 0 {
t.Fatalf("a drop with no why: %v, asked %v", err, asked)
}
out, err = tools[askDropTool].Run(map[string]any{"ask": "ask-8", "why": "stuck"})
if err != nil || len(asked) != 2 || !strings.HasPrefix(asked[0], "seat:mesh-hand-acts.hand-act ") || !strings.Contains(asked[0], askDropTool+" ask-8") ||
!strings.HasPrefix(asked[1], "seat:mesh-wants.drop ") || !strings.Contains(asked[1], `"id":"ask-8"`) || !strings.Contains(asked[1], `"why":"stuck"`) {
t.Fatalf("assigner_ask_drop answered %v, %v; asked %v", out, err, asked)
}
})
}
// Design 47 G §496, A-262: a running composition step says step-progress.<node> on every tick of its ticker, with the ask, its
@@ -98,9 +413,10 @@ func TestARunningCompositionStepSaysItsProgress(t *testing.T) {
}}
// A11/AC1 (design 47 H §752, H-A-88): with no callers in mesh-wants, the progress names the asker the step run carries.
body, _ := json.Marshal(meshwants.StepRun{Pipeline: "main.4", Step: meshwants.StepRunStepComposition, Module: "m", Branch: "main", Asker: "mesh-pipeline-runner"})
if !c.take(context.Background(), "ask-1", body) {
if m := pullOne(c, "ask-1", body); m.terms != 0 {
t.Fatal("the composition step is not taken")
}
<-said.heard // ask-taken, at the pull (H2 §777)
progress := meshwants.EventStepProgress + ".n1"
for range 2 {
tick <- at
@@ -149,7 +465,7 @@ func TestASupersededStepLeavesItsRuns(t *testing.T) {
}}
body := func(s meshwants.StepRun) []byte { raw, _ := json.Marshal(s); return raw }
for _, p := range []string{"main.3.a", "main.3.b"} {
if !c.take(context.Background(), "ask-"+p, body(step(p))) {
if m := pullOne(c, "ask-"+p, body(step(p))); m.terms != 0 {
t.Fatal("not taken")
}
}
@@ -15,7 +15,21 @@ import (
// fillOf is the store's fill now: its bytes and cap, when the bucket says them and has a cap.
func (g *graphKeeper) fillOf(ctx context.Context) (used, capacity int64, ok bool) {
f, is := g.objects.(assigngraph.Filler)
return fillIn(ctx, g.objects)
}
// passObjects is the store as the pass reads its fill: a handle of its own where one is given, so the pass's read never shares one
// with a keeping that runs beside it (design 47 H-A-261).
func (g *graphKeeper) passObjects() assigngraph.Objects {
if g.reads != nil {
return g.reads
}
return g.objects
}
// fillIn is the fill of the bucket o, when it says one and has a cap.
func fillIn(ctx context.Context, o assigngraph.Objects) (used, capacity int64, ok bool) {
f, is := o.(assigngraph.Filler)
if !is {
return 0, 0, false
}
@@ -35,13 +49,13 @@ func (p *passer) sayFill(event, about string, used, capacity int64, refused stri
// its cap), so a fill reached while the process was down is said too.
func (p *passer) fillAtStart(ctx context.Context) {
g := p.graph
used, capacity, ok := g.fillOf(ctx)
used, capacity, ok := fillIn(ctx, g.passObjects())
if !ok {
return
}
switch {
case used >= capacity:
g.full = true
g.setFull(true)
p.sayFill(meshwants.EventFull, "start", used, capacity, "the next revision")
case used*5 >= capacity*4:
p.sayFill(meshwants.EventFilling, "start", used, capacity, "")
@@ -52,20 +66,20 @@ func (p *passer) fillAtStart(ctx context.Context) {
// 80 % again. It answers true while the store is full.
func (p *passer) fullBefore(ctx context.Context, c assigngraph.Computed) bool {
g := p.graph
used, capacity, ok := g.fillOf(ctx)
used, capacity, ok := fillIn(ctx, g.passObjects())
if !ok {
return false
}
if g.full && used*5 < capacity*4 {
g.full = false
if g.isFull() && used*5 < capacity*4 {
g.setFull(false)
p.sayFill(meshwants.EventRoom, fmt.Sprint(used), used, capacity, "")
}
if used+assigngraph.NewBytes(ctx, g.objects, c) <= capacity {
g.full = false
if used+assigngraph.NewBytes(ctx, g.passObjects(), c) <= capacity {
g.setFull(false)
return false
}
if !g.full {
g.full = true
if !g.isFull() {
g.setFull(true)
p.sayFill(meshwants.EventFull, fmt.Sprint(used), used, capacity, "the next revision")
}
p.logf("the assignment graph revision is not kept: %s is full (%d of %d bytes), the last revision stays and no want is written until there is room", assigngraph.RevisionsObjects, used, capacity)
@@ -61,14 +61,14 @@ func TestTheAssignmentGraphStoreSaysFillingFullAndRoom(t *testing.T) {
if len(events) != 0 {
t.Fatalf("events %v", events)
}
o.base = 700
o.base, o.cap = 8500, 10000 // past 80 %, with room for the next revision, which the pass judges itself (H-A-261)
p.graph.started = false
p.keepGraph(ctx)
p.keepGraph(ctx) // a start again: its first pass judges the fill
if len(events) != 1 || events[0] != meshwants.EventFilling {
t.Fatalf("at the start past 80 %%: %v", events)
}
c := assigngraph.Computed{Revision: meshwants.AssignmentRevision{Entries: []meshwants.NodeEntryRef{}}}
o.base = 990
o.base, o.cap = 990, 1000
if !p.fullBefore(ctx, c) || !p.graph.full || events[len(events)-1] != meshwants.EventFull {
t.Fatalf("a revision that does not fit: events %v", events)
}
@@ -76,8 +76,15 @@ func TestTheAssignmentGraphStoreSaysFillingFullAndRoom(t *testing.T) {
if n := len(events); n != 2 {
t.Errorf("full is said once: %v", events)
}
// H-A-261: the verdict is the pass's own: with the store full the pass writes no want, though a revision is kept.
if held := p.keepGraph(ctx); held != heldFull {
t.Errorf("a pass with the store full answers %q, want %q", held, heldFull)
}
o.base = 100
if p.fullBefore(ctx, c) || p.graph.full || events[len(events)-1] != meshwants.EventRoom {
t.Errorf("room: events %v", events)
}
if held := p.keepGraph(ctx); held != "" {
t.Errorf("a pass with room and a revision kept answers %q, want the wants written", held)
}
}
@@ -5,17 +5,25 @@ import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"sync"
"time"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
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"
mcatc "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"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/views"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
)
// graphKeeper is the pass's assignment graph (design 47 G §292, A-67): per catalog revision taken in it computes the revision
@@ -24,11 +32,18 @@ import (
// that follows are written from the revision it holds.
type graphKeeper struct {
objects assigngraph.Objects
// reads is the same store through a handle of the pass's own, for the pass's read of its fill (graphfill.go); nil reads objects.
reads assigngraph.Objects
// halves is every followed branch's catalog graph revision held now.
halves func() map[string]mcc.Half
// last is the revision last computed, so a pass whose inputs did not change keeps and says nothing.
last meshwants.AssignmentRevision
has bool
halves func() map[string]mcatc.Half
// mu guards what the keeping writes and the pass reads: the revision kept, full, and the need handed over (design 47 H-A-259).
mu sync.Mutex
// handedRev is the revision last handed to the keeping, so a pass whose inputs did not change hands nothing; handed is false
// until one is, and again when its keeping failed or found the store full, so the next pass hands it again.
handedRev meshwants.AssignmentRevision
handed bool
// handedOnce says a revision was handed: the first carries the start's removal (H-A-261).
handedOnce bool
// kept is the revision the wants follow, and kept's source the trunk's source revision it carries; ok is false until one is kept.
kept meshwants.AssignmentRevision
source int64
@@ -38,58 +53,267 @@ type graphKeeper struct {
full, started bool
// revisions removes a revision that ceased to be current (revisions.go, H-A-86); nil keeps every revision.
revisions *revisionRemover
// computed is the revision computed by the last pass, with its entries: its edges.
computed assigngraph.Computed
// computed is the revision computed by the last pass, with its entries: its edges; hasComputed says a pass computed one.
computed assigngraph.Computed
hasComputed bool
// keepMu runs one keeping at a time, the pass's (keepOne) or one by hand (keepNow).
keepMu sync.Mutex
// The keeping off the pass loop (H-A-259): need is what waits to be kept, keeping says one runs; background runs it (nil: at
// once, in the caller), and wake makes a pass once a keeping changed what the pass reads.
need *keepNeed
keeping bool
background func(func())
wake func()
// A keeping that fails runs again after retry, keeping-retry, by after (time.AfterFunc; a test hands its own); failures
// counts the failures in a row, and keeping-failed is raised at the third (design 47 H2 §813 (2)).
retry time.Duration
after func(d time.Duration, f func())
failures int
}
// keepGraph computes the revision of this pass and keeps it when the pass's inputs differ from the last computed.
func (p *passer) keepGraph(ctx context.Context) {
// The keeping's setting and finding (design 47 H2 §813 (2); ADR 0682 §11: the holder's own deadline).
const (
keepingRetrySetting = "keeping-retry"
defaultKeepingRetry = 30 * time.Second
kindKeepingFailed = "keeping-failed"
// keepingFailedAt is the failures in a row that raise keeping-failed.
keepingFailedAt = 3
)
// keepingRetry reads the setting keeping-retry (§781).
func keepingRetry() (time.Duration, error) {
d, err := stdio.SettingDuration(keepingRetrySetting, defaultKeepingRetry)
if err != nil {
return 0, errors.New("the assigner's " + err.Error())
}
return d, nil
}
// keepNeed is one need of the keeping: a computed revision to keep (nil: none), and whether the revisions not current are judged.
type keepNeed struct {
c *assigngraph.Computed
judge bool
}
// keptNow is the revision the wants follow, with its trunk source, and whether one is kept.
func (g *graphKeeper) keptNow() (meshwants.AssignmentRevision, int64, bool) {
g.mu.Lock()
defer g.mu.Unlock()
return g.kept, g.source, g.ok
}
// isFull says the store did not hold the last revision handed over, so no want is written (design 47 G §181).
func (g *graphKeeper) isFull() bool {
g.mu.Lock()
defer g.mu.Unlock()
return g.full
}
func (g *graphKeeper) setFull(full bool) {
g.mu.Lock()
g.full = full
g.mu.Unlock()
}
// heldNoRevision is the pass's words while no assignment graph revision is kept: it writes no want (design 47 H-A-261).
const heldNoRevision = "held: no assignment graph revision is kept yet, so no want is written until the first keeping ends (H-A-261)"
// heldFull is the pass's words while the next revision does not fit its store (design 47 G §181).
const heldFull = "the assignment graph store is full: no want is written (design 47 G §181)"
// keepGraph computes the revision of this pass, judges the store's fill itself, and hands the revision to the keeping when the
// pass's inputs differ from the last handed. The keeping and the removing of revisions run off the pass loop, one at a time, and the
// pass never waits on them: it judges and writes the wants from the graph it holds (design 47 H-A-259). It answers why the pass
// writes no want, or "" when it writes them: none while the next revision does not fit the store (G §181), and none while no
// revision is kept (H-A-261), whose keeping wakes a pass when it ends.
func (p *passer) keepGraph(ctx context.Context) string {
g := p.graph
if g == nil || g.objects == nil || g.halves == nil {
return
return ""
}
c := assigngraph.Compute(p.graphInputs())
g.computed = c
g.mu.Lock()
g.computed, g.hasComputed = c, true
g.mu.Unlock()
for _, u := range c.Uncomputed {
if g.said != u {
g.said = u
p.logf("the assignment graph leaves out %s", u)
}
}
if !g.started {
if !g.started { // the first pass judges the fill once (graphfill.go)
g.started = true
p.fillAtStart(ctx)
}
if g.has && g.ok && assigngraph.Same(g.last, c.Revision) {
return
}
used, _, _ := g.fillOf(ctx)
if p.fullBefore(ctx, c) {
return
g.mu.Lock()
g.handed = false // handed once it fits
g.mu.Unlock()
return heldFull
}
rev, fresh, err := assigngraph.Keep(ctx, g.objects, c, meshwants.EventAssignmentRevision, p.clock())
if err != nil {
p.logf("the assignment graph revision is not kept, so no want is said as wanted until it is: %v", err)
return
g.mu.Lock()
same := g.handed && assigngraph.Same(g.handedRev, c.Revision)
first := !g.handedOnce
if !same {
g.handedRev, g.handed, g.handedOnce = c.Revision, true, true
}
g.last, g.has, g.kept, g.ok = c.Revision, true, rev, true
g.source = 0
for _, cat := range rev.Catalogs {
if cat.Branch == p.w.trunkName() {
g.source = cat.Source
g.mu.Unlock()
if !same {
// The start's removal of the revisions not current folds into the first keeping: it keeps the first pass's revision, then
// removes (H-A-261).
p.needKeeping(ctx, keepNeed{c: &c, judge: first})
}
if _, _, ok := g.keptNow(); !ok {
return heldNoRevision
}
return ""
}
// needKeeping hands a need to the keeping: one keeping runs at a time, and a need that comes while one runs is folded into the one
// that waits (the newest revision, and a judging asked by either), so it runs once more (design 47 H-A-259).
func (p *passer) needKeeping(ctx context.Context, n keepNeed) {
g := p.graph
g.mu.Lock()
if w := g.need; w != nil {
n.judge = n.judge || w.judge
if n.c == nil {
n.c = w.c
}
}
if !fresh {
g.need = &n
if g.keeping {
g.mu.Unlock()
return
}
p.fillingAfter(ctx, used)
if g.revisions != nil {
g.keeping = true
g.mu.Unlock()
run := func() {
for {
g.mu.Lock()
next := g.need
g.need = nil
if next == nil {
g.keeping = false
g.mu.Unlock()
return
}
g.mu.Unlock()
p.keepOne(ctx, *next)
}
}
if g.background != nil {
g.background(run)
return
}
run()
}
// keepOne keeps one computed revision, says assignment-revision for a revision kept now and removes the
// revisions that ceased to be current; it says its duration in the journal, and wakes a pass when it changed what the pass reads.
func (p *passer) keepOne(ctx context.Context, n keepNeed) {
g := p.graph
g.keepMu.Lock()
defer g.keepMu.Unlock()
start := time.Now()
changed := false
defer func() {
p.logf("the keeping of the assignment graph took %s", time.Since(start).Round(time.Millisecond))
if changed && g.background != nil && g.wake != nil {
g.wake()
}
}()
if n.c != nil {
_, _, had := g.keptNow()
fresh := p.keepRevision(ctx, *n.c)
_, _, has := g.keptNow()
n.judge = n.judge || fresh
changed = fresh || had != has // the first revision kept: the pass writes the wants it held (H-A-261)
}
if n.judge && g.revisions != nil {
g.revisions.judge() // the revision before ceased to be current
}
}
// keepRevision keeps c when the store holds it, and says whether a revision was kept now.
func (p *passer) keepRevision(ctx context.Context, c assigngraph.Computed) bool {
fresh, _ := p.keepRevisionOf(ctx, c)
return fresh
}
// keepRevisionOf is keepRevision answering the fault the keeping met too.
func (p *passer) keepRevisionOf(ctx context.Context, c assigngraph.Computed) (bool, error) {
g := p.graph
again := func() { // the next pass hands this revision again
g.mu.Lock()
g.handed = false
g.mu.Unlock()
}
used, _, _ := g.fillOf(ctx)
rev, fresh, err := assigngraph.Keep(ctx, g.objects, c, meshwants.EventAssignmentRevision, p.clock())
if err != nil {
again()
p.keepingFailed(ctx, c, err)
return false, err
}
p.keepingSucceeded()
var source int64
for _, cat := range rev.Catalogs {
if cat.Branch == p.w.trunkName() {
source = cat.Source
}
}
g.mu.Lock()
g.kept, g.ok, g.source = rev, true, source
g.mu.Unlock()
if !fresh {
return false, nil
}
p.fillingAfter(ctx, used)
id := fmt.Sprintf("%s-%s-%d", meshwants.EventAssignmentRevision, rev.Kind, rev.Revision)
if err := p.wantsSay(meshwants.EventAssignmentRevision, assigngraph.Event(rev), id); err != nil {
p.logf("the assignment revision %d is kept but not said: %v", rev.Revision, err)
}
return true, nil
}
// keepNow is the seat mesh-wants' act keep-now (design 47 H2 §813 (2); H-A-417): the keeping of the pass's newest computed
// revision, run at once, one at a time with the pass's; it answers the revision kept, or the fault the keeping met (a failed
// one is run again after keeping-retry, as every keeping is). The hand act is the tool's to write, before it calls.
func (p *passer) keepNow(ctx context.Context, in meshwants.KeepNowInput) (meshwants.KeepNowAnswer, error) {
g := p.graph
if strings.TrimSpace(in.Why) == "" {
return meshwants.KeepNowAnswer{}, errors.New("say why the keeping runs now")
}
if g == nil || g.objects == nil {
return meshwants.KeepNowAnswer{}, errors.New("the assigner keeps no assignment graph here")
}
g.mu.Lock()
c, ok := g.computed, g.hasComputed
g.mu.Unlock()
if !ok {
return meshwants.KeepNowAnswer{}, errors.New("no pass has computed an assignment graph revision yet")
}
g.keepMu.Lock()
defer g.keepMu.Unlock()
p.logf("the keeping of the assignment graph runs now by hand: %s", in.Why)
if _, err := p.keepRevisionOf(ctx, c); err != nil {
return meshwants.KeepNowAnswer{Fault: err.Error()}, nil
}
rev, _, _ := g.keptNow()
return meshwants.KeepNowAnswer{Revision: &rev}, nil
}
// keepNowVerb is the process's handler of the seat mesh-wants' act keep-now.
func keepNowVerb(ctx context.Context, p *passer) map[string]process.SeatHandler {
return map[string]process.SeatHandler{
meshwants.VerbKeepNow: func(_ string, raw json.RawMessage) (any, error) {
var in meshwants.KeepNowInput
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
return p.keepNow(ctx, in)
},
}
}
// graphInputs are what the pass's assignment graph is computed from: every followed branch's catalog half, the placements, each
@@ -147,14 +371,20 @@ func (p *passer) sayWanted(node, module, fp, pipeline string, removed bool) {
return
}
g := p.graph
if g == nil || !g.ok {
var kept meshwants.AssignmentRevision
var source int64
ok := false
if g != nil {
kept, source, ok = g.keptNow()
}
if !ok {
p.logf("the want of %s on %s is written, but no assignment graph revision is kept, so wanted is not said", module, node)
return
}
at := p.clock().UTC()
body := meshwants.WantedEvent{V: keys.Version, Node: node, Module: module, Fp: fp, Pipeline: pipeline, Removed: removed, Revision: g.kept.Revision, Source: g.source, At: &at}
body := meshwants.WantedEvent{V: keys.Version, Node: node, Module: module, Fp: fp, Pipeline: pipeline, Removed: removed, Revision: kept.Revision, Source: source, At: &at}
event := strings.TrimPrefix(meshwants.SubjectWanted(keys.EscapeName(node), keys.EscapeName(module)), "mesh.seat."+meshwants.Seat+".event.")
id := fmt.Sprintf("wanted.%s.%s.%s.%t.%d.%s", keys.EscapeName(node), keys.EscapeName(module), fp, removed, g.kept.Revision, at.Format(time.RFC3339Nano))
id := fmt.Sprintf("wanted.%s.%s.%s.%t.%d.%s", keys.EscapeName(node), keys.EscapeName(module), fp, removed, kept.Revision, at.Format(time.RFC3339Nano))
if err := p.wantsSay(event, body, id); err != nil {
p.logf("wanted of %s on %s is not said: %v", module, node, err)
}
@@ -185,7 +415,7 @@ func (p *passer) namedBuild(module, trunkFP string, unreleased ...bool) func(fp
// the mesh-sdk merge moved its fingerprint).
return p.w.released.withParts(module, p.w.ends.madeOf(module, fp))
}
if p.graph == nil || !p.graph.ok {
if _, _, kept := p.graphKept(); !kept {
p.unheardRelease(module, fp, "no assignment graph revision is kept yet, so no release is looked up")
return assign.KeptBuild{}, false
}
@@ -212,3 +442,71 @@ func (p *passer) unheardRelease(module, fp, why string) {
p.logf("the release of %s at fingerprint %s is not heard: %s; its wants and candidates carry no version and no parts", module, fp, why)
}
}
// graphKept is the revision the wants follow, with its trunk source, and whether one is kept; with no graph kept, none is.
func (p *passer) graphKept() (meshwants.AssignmentRevision, int64, bool) {
if p.graph == nil {
return meshwants.AssignmentRevision{}, 0, false
}
return p.graph.keptNow()
}
// keepingFailed marks the keeping of c wanted again after keeping-retry (design 47 H2 §813 (2)): run then unless a newer
// revision was handed meanwhile, whose own keeping runs. The third failure in a row raises keeping-failed (scope module).
func (p *passer) keepingFailed(ctx context.Context, c assigngraph.Computed, err error) {
g := p.graph
g.mu.Lock()
g.failures++
n, retry, after := g.failures, g.retry, g.after
g.mu.Unlock()
if retry <= 0 {
retry = defaultKeepingRetry
}
if after == nil {
after = func(d time.Duration, f func()) { time.AfterFunc(d, f) }
}
p.logf("the assignment graph revision is not kept (%d in a row), so no want is said as wanted until it is; kept again in %s: %v", n, retry, err)
if n == keepingFailedAt && p.findings.Put != nil {
if err := p.findings.Put(keepingFailedFinding(n, err).Finding(p.clock())); err != nil {
p.logf("the finding %s is not written: %v", kindKeepingFailed, err)
}
}
after(retry, func() {
g.mu.Lock()
newer := g.handed && !assigngraph.Same(g.handedRev, c.Revision)
if !newer {
g.handedRev, g.handed = c.Revision, true
}
g.mu.Unlock()
if !newer {
p.needKeeping(ctx, keepNeed{c: &c})
}
})
}
// keepingSucceeded ends a run of failures: keeping-failed, raised at the third, is cleared.
func (p *passer) keepingSucceeded() {
g := p.graph
g.mu.Lock()
n := g.failures
g.failures = 0
g.mu.Unlock()
if n >= keepingFailedAt && p.findings.Delete != nil {
o := keepingFailedFinding(n, nil)
if err := p.findings.Delete(views.FindingKey(o.Scope, assign.KeyID(o.ID), o.Kind)); err != nil {
p.logf("the finding %s is not deleted: %v", kindKeepingFailed, err)
}
}
}
// keepingFailedFinding is keeping-failed of the assigner on this node, after n failures in a row (design 47 H2 §813 (2)).
func keepingFailedFinding(n int, err error) assign.Observed {
summary := fmt.Sprintf("the keeping of the assignment graph revisions failed %d times in a row", n)
if err != nil {
summary += ": " + err.Error()
}
return assign.Observed{Scope: mcc.ScopeModule, ID: assignment.Module() + "." + thisNode, Kind: kindKeepingFailed,
Severity: mcseat.FindingSeverityWarning, Summary: summary, Headline: "The assignment graph is not kept",
Explanation: summary + ". No want is said as wanted until a keeping succeeds; it is run again after keeping-retry.",
Source: "assigner." + kindKeepingFailed}
}
@@ -3,17 +3,24 @@ package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"sync"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
mwc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"mesh-delivery-assigner/internal/assign"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/buckets"
)
@@ -88,6 +95,35 @@ func TestTheWantsAreSaidWantedFromTheKeptAssignmentGraphRevision(t *testing.T) {
if err := json.Unmarshal(events[len(events)-1].body, &w); err != nil || len(events) != 3 || !w.Removed || w.Fp != fpTest {
t.Errorf("a removing want said %+v (%v), %d events", w, err, len(events))
}
// Design 47 H2 §813 (1), H-A-416: a want carries its run, its pipeline's source in decimal, or the newest source held for a
// want of no pipeline; it is written by compare-and-set refusing a lower run, and one that differs only by its run stands.
t.Run("a want's run", func(t *testing.T) {
wkey, _ := mwc.WantKey("g14", "db")
stored := func() mwc.Want { w, _ := mwc.DecodeWant(kv.values[wkey]); return w }
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.2", Pipeline: "main.12", Rank: 1})
if w := stored(); w.Run != "12" || w.Pipeline != "main.12" {
t.Fatalf("the want of pipeline main.12 is %+v, want run 12", w)
}
puts := kv.puts
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.1", Pipeline: "main.11", Rank: 1})
if w := stored(); w.Run != "12" || w.Version != "0.1.2" || kv.puts != puts {
t.Errorf("a want of a lower run replaced %+v (%d writes)", w, kv.puts-puts)
}
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.2", Pipeline: "main.12", Rank: 1})
if kv.puts != puts {
t.Error("a want that stands was written again")
}
skey, _ := mwc.WantKey("shanks", "db")
p.putWant(ctx, "shanks", "db", mwc.Want{Fp: fpTest, Put: true, Words: "put: by hand"})
if w, _ := mwc.DecodeWant(kv.values[skey]); w.Run != "9" {
t.Errorf("a put's want is %+v, want the newest source held, 9", w)
}
// a placement's build after the delivery of run 12: the newest source held for it is the want's own, never refused
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.0"})
if w := stored(); w.Run != "12" || w.Version != "0.1.0" {
t.Errorf("a placement's want after run 12 is %+v, want it written at run 12", w)
}
})
// A-201, A-235: a run's candidate catalog revision, read whole through the seat's verb revision, keeps the run's assignment
// graph under candidate.<group>.<heads> in place of its branch's half; it says nothing and writes no want, a try's candidate
@@ -132,3 +168,202 @@ func TestTheWantsAreSaidWantedFromTheKeptAssignmentGraphRevision(t *testing.T) {
t.Errorf("dropping the run's candidate dropped trunk: %v", err)
}
}
// blockedObjects is an object bucket whose listing waits while a gate stands: a keeping that does not end until it is opened.
type blockedObjects struct {
memObjects
mu sync.Mutex
gate chan struct{}
}
func (b *blockedObjects) Names(ctx context.Context) ([]string, error) {
b.mu.Lock()
gate := b.gate
b.mu.Unlock()
if gate != nil {
<-gate
}
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Names(ctx)
}
func (b *blockedObjects) Put(ctx context.Context, name string, data []byte) error {
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Put(ctx, name, data)
}
func (b *blockedObjects) Get(ctx context.Context, name string) ([]byte, error) {
b.mu.Lock()
defer b.mu.Unlock()
return b.memObjects.Get(ctx, name)
}
// block stands a gate, opened by the function it answers.
func (b *blockedObjects) block() func() {
gate := make(chan struct{})
b.mu.Lock()
b.gate = gate
b.mu.Unlock()
return func() {
b.mu.Lock()
b.gate = nil
b.mu.Unlock()
close(gate)
}
}
// Design 47 H-A-259, H-A-261: the keeping of the assignment graph runs off the pass loop. At the start, while the first keeping is
// blocked, a pass returns and writes no want; the keeping's end wakes a pass, which writes the passed pipeline's want. Later, while a
// keeping of new inputs is blocked, a pass writes the wants from the revision it holds, and a pass of the same inputs hands nothing
// more. Each pass and each keeping says its duration.
func TestAPassWritesWantsWhileAKeepingIsBlocked(t *testing.T) {
fp := mcc.SourcePrefix2 + strings.Repeat("a", 64)
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, time.Now())
var mu sync.Mutex
var journal strings.Builder
p.logf = func(f string, a ...any) { mu.Lock(); fmt.Fprintf(&journal, f+"\n", a...); mu.Unlock() }
said := func(words string) bool {
mu.Lock()
defer mu.Unlock()
return strings.Contains(journal.String(), words)
}
mdigest := strings.Repeat("e", 64)
mod, _ := mcc.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fp, Manifest: mdigest, Repository: "novox/web", Commit: strings.Repeat("1", 40), Path: mcc.RootPath})
putModuleRaw(p.w, trunkBranch, "web", mod)
p.w.manifests[mdigest] = parsed{module: "web", manifest: catalogue.Manifest{Module: "web"}}
placeOn(t, p.w, "ace", "web")
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk = p.w.trunkName
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "0.1.2", 1, mpr.StepResultOutcomePassed)))
objects := &blockedObjects{memObjects: memObjects{}}
var kept sync.WaitGroup
woke := make(chan struct{}, 8)
half := mcc.Half{Revision: meshcatalog.CatalogRevision{Branch: trunkBranch, Kind: "trunk", Revision: 4, Source: 9,
Entries: []meshcatalog.EntryRef{{Module: "web", Digest: "sha256:" + strings.Repeat("a", 64)}}},
Entries: map[string]meshcatalog.CatalogEntry{"web": {Module: "web", Fp: fp}}}
p.graph = &graphKeeper{objects: objects, halves: func() map[string]mcc.Half { return map[string]mcc.Half{trunkBranch: half} },
background: func(f func()) { kept.Go(f) }, wake: func() { woke <- struct{}{} }}
pass := func() {
t.Helper()
done := make(chan struct{})
go func() { p.pass(context.Background()); close(done) }()
select {
case <-done:
case <-time.After(10 * time.Second):
t.Fatal("the pass waits on the keeping of the assignment graph")
}
}
wantOf := func(node string) (mwc.Want, error) {
key, _ := mwc.WantKey(node, "web")
return mwc.DecodeWant(wantsKV.values[key])
}
open := objects.block()
t.Cleanup(func() { // the keeping ends before the test does, and says its duration
objects.mu.Lock()
standing := objects.gate != nil
objects.mu.Unlock()
if standing {
open()
}
kept.Wait()
if !said("the keeping of the assignment graph took ") {
t.Error("the keeping does not say its duration")
}
})
pass() // the start: the first keeping is blocked
if _, err := wantOf("ace"); err == nil {
t.Error("a pass at the start wrote a want before an assignment graph revision is kept")
}
open()
select {
case <-woke:
case <-time.After(10 * time.Second):
t.Fatal("the first keeping's end wakes no pass")
}
pass()
if w, err := wantOf("ace"); err != nil || w.Fp != fp || w.Version != "0.1.2" {
t.Errorf("the want of web on ace = %+v (%v), want the passed version once a revision is kept", w, err)
}
open = objects.block() // a keeping of new inputs is blocked
placeOn(t, p.w, "g14", "web")
pass()
pass() // the same inputs again
if w, err := wantOf("g14"); err != nil || w.Fp != fp || w.Version != "0.1.2" {
t.Errorf("the want of web on g14 = %+v (%v), want the passed version while a keeping is blocked", w, err)
}
p.graph.mu.Lock()
keeping, waiting := p.graph.keeping, p.graph.need
p.graph.mu.Unlock()
if !keeping || waiting != nil {
t.Errorf("keeping %v, need waiting %+v: the pass of the same inputs handed its revision again", keeping, waiting)
}
if !said("the pass took ") {
t.Error("the pass does not say its duration")
}
open()
kept.Wait()
// Design 47 H2 §813 (2): a keeping that fails runs again after keeping-retry with no pass, raising keeping-failed at the third
// failure in a row, cleared at the next that succeeds.
t.Run("a failed keeping runs again", func(t *testing.T) {
failing := &failingObjects{blockedObjects: objects, fail: 3}
var retries []time.Duration
var put []mcseat.Finding
var deleted []string
p.findings = assign.Findings{Put: func(f mcseat.Finding) error { put = append(put, f); return nil },
Delete: func(key string) error { deleted = append(deleted, key); return nil }}
p.graph.objects, p.graph.background, p.graph.retry = failing, nil, 30*time.Second
p.graph.after = func(d time.Duration, f func()) { retries = append(retries, d); f() }
placeOn(t, p.w, "shanks", "web") // new inputs: a keeping is handed
pass()
if len(retries) != 3 || retries[0] != 30*time.Second || len(put) != 1 || put[0].Kind != kindKeepingFailed || put[0].Scope != "module" ||
len(deleted) != 1 || !strings.Contains(deleted[0], kindKeepingFailed) || p.graph.failures != 0 {
t.Fatalf("retries %v, raised %+v, cleared %v, failures %d", retries, put, deleted, p.graph.failures)
}
if _, _, ok := p.graph.keptNow(); !ok || failing.fail != 0 {
t.Fatal("the revision is not kept once the store takes it")
}
// keep-now (H-A-417): the keeping by hand answers the revision kept, or the fault met; it needs a why.
if _, err := p.keepNow(context.Background(), meshwants.KeepNowInput{}); err == nil {
t.Error("a keeping by hand with no why runs")
}
if a, err := p.keepNow(context.Background(), meshwants.KeepNowInput{Why: "the store was full"}); err != nil || a.Revision == nil || a.Fault != "" {
t.Errorf("keep-now answered %+v, %v; want the revision kept", a, err)
}
failing.fail, retries = 2, nil
p.graph.after = func(d time.Duration, _ func()) { retries = append(retries, d) }
placeOn(t, p.w, "novox", "web") // a new revision, whose keeping the store refuses at the pass and again by hand
pass()
if a, err := p.keepNow(context.Background(), meshwants.KeepNowInput{Why: "again"}); err != nil || a.Revision != nil || !strings.Contains(a.Fault, "the store answers nothing") || len(retries) != 2 {
t.Errorf("keep-now on a refusing store answered %+v, %v, retries %v; want the fault and a retry", a, err, retries)
}
var asked []string
tool := keepNowTools(func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, key+" "+string(raw))
return json.RawMessage(`{}`), nil
})[0]
if _, err := tool.Run(map[string]any{"why": "by hand"}); err != nil || len(asked) != 2 || !strings.HasPrefix(asked[0], "seat:mesh-hand-acts.hand-act ") ||
asked[1] != `seat:mesh-wants.keep-now {"why":"by hand"}` {
t.Errorf("assigner_keep_now: %v, asked %v", err, asked)
}
})
}
// failingObjects refuses the next fail puts, then is objects.
type failingObjects struct {
*blockedObjects
fail int
}
func (f *failingObjects) Put(ctx context.Context, name string, data []byte) error {
if f.fail > 0 {
f.fail--
return errors.New("the store answers nothing")
}
return f.blockedObjects.Put(ctx, name, data)
}
@@ -37,6 +37,10 @@ type halves struct {
// settled is told once when the first watched branch's first view is answered, for the first pass to wait on.
settled chan<- struct{}
told bool
// regMu orders the registrations told to registered: the ones held when it is set, then each change (H-A-270 (3)).
regMu sync.Mutex
registered func(reg meshcatalog.Registration, gone bool)
}
// follow makes the branch follower on the reader; the reader's start asks the first views.
@@ -50,6 +54,15 @@ func (h *halves) follow() error {
h.changed(branch, module, entry, deleted)
}
b.Adopted = h.adopted
// The one handler of registration-changed is the follower's (H-A-270 (3)): the pipeline ends are told each change from it,
// never from a second handler on the hub.
reconcile := b.Registrations.Follower.Changed
b.Registrations.Follower.Changed = func(module string, value json.RawMessage, gone bool, at time.Time) {
if reconcile != nil {
reconcile(module, value, gone, at)
}
h.tellRegistration(module, value, gone)
}
h.mu.Lock()
h.branches = b
h.mu.Unlock()
@@ -215,3 +228,39 @@ func (h *halves) watchedOf(module string) []string {
slices.SortStableFunc(out, func(x, y string) int { return strings.Compare(keys.EscapeName(x), keys.EscapeName(y)) })
return out
}
// tellRegistration tells registered of one registration the follower holds now, or of one removed.
func (h *halves) tellRegistration(module string, value json.RawMessage, gone bool) {
h.regMu.Lock()
defer h.regMu.Unlock()
if h.registered == nil {
return
}
reg := meshcatalog.Registration{Module: module}
if !gone {
if err := json.Unmarshal(value, &reg); err != nil {
h.logf("the registration of %s does not read: %v", module, err)
return
}
}
h.registered(reg, gone)
}
// followRegistrations tells registered of every registration the branch follower holds and then of each change it takes
// (design 47 G §353): the registrations are followed once, by the follower's one handler of registration-changed (H-A-270
// (3)). It says false when no follower is made.
func (h *halves) followRegistrations(registered func(meshcatalog.Registration, bool)) bool {
h.mu.Lock()
b := h.branches
h.mu.Unlock()
if b == nil || b.Registrations == nil {
return false
}
h.regMu.Lock()
defer h.regMu.Unlock()
h.registered = registered
for _, reg := range b.Registrations.All() {
registered(reg, false)
}
return true
}
@@ -53,6 +53,7 @@ func TestAMeshThatNamesNoBranchSettlesTheAssignersFirstPass(t *testing.T) {
// Design 47 H-A-143, H-A-144, G §532: a module's watched branches are its registration's, in its order; once registrations are held a
// module none names has none; before the first registrations the gate's source's branches stand in, in the source's order.
// H-A-270 (3): the pipeline ends are told the registrations by the same follower, whether set before its first view or after.
func TestAModulesWatchedBranchesAreItsRegistrations(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
@@ -81,11 +82,23 @@ func TestAModulesWatchedBranchesAreItsRegistrations(t *testing.T) {
if err := h.follow(); err != nil {
t.Fatal(err)
}
var live, held []string
if !h.followRegistrations(func(reg seat.Registration, gone bool) { live = append(live, reg.Module) }) {
t.Fatal("no follower of the registrations")
}
for _, f := range reader.Followers()[:2] { // the registrations and the gate's source
if err := f.Start(ctx); err != nil {
t.Fatal(err)
}
}
h.followRegistrations(func(reg seat.Registration, gone bool) { held = append(held, reg.Module) })
var regs []string
for _, r := range tc.regs {
regs = append(regs, r.Module)
}
if !slices.Equal(live, regs) || !slices.Equal(held, regs) {
t.Errorf("the ends were told %v at the first view and %v held, want %v", live, held, regs)
}
if got := h.watchedOf(tc.module); !slices.Equal(got, tc.want) {
t.Errorf("the watched branches of %s are %v, want %v", tc.module, got, tc.want)
}
@@ -12,6 +12,7 @@ import (
"git.novox.be/novox/mesh-sdk/go/keys"
"io"
"maps"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
"mesh-delivery-assigner/internal/puts"
@@ -49,6 +50,7 @@ import (
mdseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/announce"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/buscompose"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/process"
@@ -176,7 +178,7 @@ func startBed(t *testing.T, leaveOut string) *bed {
continue
}
cfg := jetstream.KeyValueConfig{Bucket: name, History: 5}
if name == plc.PulsesBucket() || name == buckets.CompositionRuns() {
if name == plc.PulsesBucket() || name == buckets.CompositionRuns() || name == buckets.Taken() {
cfg.History, cfg.LimitMarkerTTL = 1, time.Minute // a time to live per key, as the controller makes it (key-ttl)
}
kv, err := js.CreateKeyValue(ctx, cfg)
@@ -190,6 +192,11 @@ func startBed(t *testing.T, leaveOut string) *bed {
if _, err := js.CreateObjectStore(ctx, jetstream.ObjectStoreConfig{Bucket: catalogue.BusName("mesh-delivery-assigner", catalogue.StateObjectsName(buckets.InputsState))}); err != nil {
t.Fatal(err)
}
// The assignment graph revisions' object store, which the grants part makes from the manifest's objects: no want is written
// before a revision is kept in it (design 47 H-A-261).
if _, err := js.CreateObjectStore(ctx, jetstream.ObjectStoreConfig{Bucket: catalogue.ObjectsBucket("mesh-delivery-assigner", assigngraph.RevisionsObjects)}); err != nil {
t.Fatal(err)
}
// The builder's module log, as the runtime raises it (ADR 0297): the running commits are read from it (ADR 0571 clause 1).
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: buscompose.LogStreamName(builds.BuilderModule, builds.BuilderLog),
Subjects: []string{buscompose.LogSubject(builds.BuilderModule, builds.BuilderLog) + ".>"}, AllowDirect: true}); err != nil {
@@ -200,6 +207,9 @@ func startBed(t *testing.T, leaveOut string) *bed {
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: "EVENTS", Subjects: []string{"mesh.mod.*.event.>", "mesh.seat.*.event.>"}}); err != nil {
t.Fatal(err)
}
// The seat mesh-wants' work queue and its one worker, as the broker derives them from the seat's definition (design 47 H2
// §777); the assigner pulls its step asks from it.
seatQueue(ctx, t, js)
// The node-engine seat's stream of `running`, kept last per subject, which the assigner hears the health of what runs from (§520).
if _, err := js.CreateStream(ctx, keptStream(nodeengine.StreamRunning, nodeengine.SubjectRunningAll, jetstream.StreamConfig{MaxMsgsPerSubject: 1})); err != nil {
t.Fatal(err)
@@ -874,6 +884,14 @@ func TestWantsAreWrittenAndNoDifferenceIs(t *testing.T) {
if _, err := b.buckets[engineReadsBucket()].Get(b.ctx, "shanks"); err == nil {
t.Error("the state engine-reads holds a key of shanks, whose engine said nothing")
}
// H-A-270 (3): registration-changed has one handler, the catalog half's follower, so the start's hub refuses no overlap.
b.journal.await(t, 0, "the kept seat events heard", "the hub started", time.Second)
b.journal.mu.Lock()
overlap := strings.Contains(b.journal.text.String(), "a message has one taker")
b.journal.mu.Unlock()
if overlap {
t.Error("the start's hub refused a handler that overlaps another: a message has one taker")
}
}
// subscribed returns once the server holds every subscription nc made: nats.go sends a SUB from its flusher, after
@@ -1924,7 +1942,9 @@ func awaitKept(t *testing.T, b *bed, stream string, n uint64) {
// serveSeatList answers the seat mesh-catalog's verb seat-definitions as the indexer does (ADR 0636 §4): with no seat, every
// trunk seat with its digest; with one, its definition resolved, from the mesh-sdk test copy of every definition. The channel
// it answers is closed once every listed seat's definition was asked, the end of a reader's first read.
// it answers is closed once every listed seat's definition was asked, the end of a reader's first read. It also answers the
// chunked read verb seat-list as the indexer does (design 47 H2 H-A-443): the definitions as one JSON array sorted by seat,
// its sha256 and size, then the bytes on the call's chunk subjects (seatListBytes).
func serveSeatList(t *testing.T, nc *nats.Conn) <-chan struct{} {
t.Helper()
var mu sync.Mutex
@@ -1967,5 +1987,94 @@ func serveSeatList(t *testing.T, nc *nats.Conn) <-chan struct{} {
}
t.Cleanup(func() { _ = sub.Unsubscribe() })
}
list, digest := seatListBytes()
hand := func(m *nats.Msg) {
var in meshcatalog.SeatListInput
_ = json.Unmarshal(m.Data, &in)
send := buscalls.SeatChunks{Seat: meshcatalog.Seat, Verb: meshcatalog.VerbSeatList, Call: in.Call}
chunks := int64((len(list) + buscalls.SeatChunkBytes - 1) / buscalls.SeatChunkBytes)
raw, _ := json.Marshal(map[string]any{"result": meshcatalog.SeatListAnswer{Digest: digest, Size: int64(len(list)), Chunks: chunks}, "node": "n0"})
_ = m.Respond(raw)
go func() { _ = send.Send(nc, list, buscalls.SeatAckWithin, t.Logf) }()
}
for _, subject := range []string{"mesh.seat." + meshcatalog.Seat + ".tool." + meshcatalog.VerbSeatList, "mesh.seat." + meshcatalog.Seat + ".call." + meshcatalog.VerbSeatList + ".*"} {
sub, err := nc.Subscribe(subject, hand)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = sub.Unsubscribe() })
}
return read
}
// seatListBytes are the bed's seat list as the verb seat-list hands it: every definition of the mesh-sdk test copy as one JSON
// array sorted by seat, and its sha256 (H-A-441 (a)).
func seatListBytes() ([]byte, string) {
defs := slices.Clone(seatlisttest.Definitions())
slices.SortFunc(defs, func(a, b seatdef.Definition) int { return strings.Compare(a.Seat, b.Seat) })
list := make([]json.RawMessage, 0, len(defs))
for _, d := range defs {
raw, _ := json.Marshal(d)
list = append(list, raw)
}
raw, _ := json.Marshal(list)
return raw, seatListDigest(raw)
}
// seatQueue makes the seat mesh-wants' work queue and its one shared worker from the seat's definition, as the broker derives
// them (design 47 H2 §777).
func seatQueue(ctx context.Context, t *testing.T, js jetstream.JetStream) {
t.Helper()
raw, err := os.ReadFile(filepath.Join("..", "..", "..", "mesh-delivery-contracts", "seats", meshwants.Seat, "seat.json"))
if err != nil {
t.Fatal(err)
}
def, err := seatdef.Parse(raw)
if err != nil {
t.Fatal(err)
}
stream, worker, ok, err := buscompose.SeatQueue(meshwants.Seat, def.Accepts)
if err != nil || !ok {
t.Fatalf("the seat's work queue: %v %v", ok, err)
}
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: stream.Name, Subjects: stream.Subjects, Retention: jetstream.WorkQueuePolicy,
MaxAge: time.Duration(stream.MaxAge) * time.Second, MaxMsgs: int64(stream.MaxMsgs), Duplicates: time.Duration(stream.DuplicatesSeconds) * time.Second}); err != nil {
t.Fatal(err)
}
if _, err := js.CreateOrUpdateConsumer(ctx, stream.Name, jetstream.ConsumerConfig{Durable: worker.Name, FilterSubjects: worker.Filters, AckPolicy: jetstream.AckExplicitPolicy,
AckWait: time.Duration(worker.AckWaitSeconds) * time.Second, MaxDeliver: worker.MaxDeliver, MaxAckPending: worker.MaxAckPending}); err != nil {
t.Fatal(err)
}
}
// putStep puts one step ask on the seat mesh-wants' work queue under id, as the runner puts it (design 47 H2 §777).
func putStep(ctx context.Context, t *testing.T, js jetstream.JetStream, id string, step meshwants.StepRun) {
t.Helper()
msg := nats.NewMsg(meshwants.AcceptSubjectStep)
msg.Header.Set("x-event-id", id)
msg.Header.Set(nats.MsgIdHdr, id)
msg.Data, _ = json.Marshal(step)
if _, err := js.PublishMsg(ctx, msg); err != nil {
t.Fatalf("the ask %s is not put on the seat's work queue: %v", id, err)
}
}
// queueEmpty fails t unless the seat mesh-wants' worker holds no ask, waiting or unacknowledged (design 47 H2 §777).
func queueEmpty(ctx context.Context, t *testing.T, js jetstream.JetStream) {
t.Helper()
deadline := time.Now().Add(10 * time.Second)
for {
c, err := js.Consumer(ctx, buscompose.SeatQueueStreamName(meshwants.Seat), buscompose.SeatQueueWorkerName(meshwants.Seat))
if err != nil {
t.Fatal(err)
}
info, err := c.Info(ctx)
if err == nil && info.NumPending == 0 && info.NumAckPending == 0 {
return
}
if time.Now().After(deadline) {
t.Fatalf("the seat's worker holds asks after their ends: %+v %v", info, err)
}
time.Sleep(20 * time.Millisecond)
}
}
@@ -14,8 +14,10 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/buscompose"
"io"
"log"
"maps"
"mesh-delivery-assigner/internal/assigngraph"
"mesh-delivery-assigner/internal/assignment"
"mesh-delivery-assigner/internal/buckets"
@@ -23,6 +25,7 @@ import (
"os/signal"
"slices"
"strings"
"sync/atomic"
"syscall"
"time"
@@ -89,7 +92,7 @@ func ownBuckets() []string {
return []string{buckets.Asks(), buckets.Differences(),
buckets.Puts(), buckets.Wants(), plc.AssignmentsBucket(), plc.ProposalsBucket(),
plc.CandidatesBucket(), plc.PulsesBucket(), assign.FindingsBucket(), assign.PoliciesBucket(), plc.SeatHoldersBucket(),
engineReadsBucket(), retiredBucket(), copiesBucket(), writtenBucket(), buckets.Waits(), buckets.PutWaits(), buckets.Inputs(), buckets.CompositionRuns()}
engineReadsBucket(), retiredBucket(), copiesBucket(), writtenBucket(), buckets.Waits(), buckets.PutWaits(), buckets.Inputs(), buckets.CompositionRuns(), buckets.Taken()}
}
// engineReadsState is the assigner's state of what each node's engine says it reads (design 47 H-A-104), one key `<node>`
@@ -136,6 +139,7 @@ var keptStates = []announce.State{
{Name: buckets.PutWaitsState, Readable: true}, // the put waits said (putwaits.go, design 47 G A-211)
{Name: buckets.InputsState, Readable: true}, // read by the tool process alone: the verb input and assigner_inputs (design 47 G §354)
{Name: buckets.CompositionRunsState, Readable: true}, // the composition runs, read by the process and its tools (design 47 G §719, A-468c)
{Name: process.TakenState, Readable: true}, // the asks of the seat mesh-wants taken once, and their drops (design 47 H2 §775, §777)
}
// kvSet is every bucket the assigner opened, by name.
@@ -613,7 +617,14 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
p.publishWants = wantsPublisher(ctx, js, thisNode)
if iv != nil && iv.h != nil {
objects := newBusObjects(js, process.Account{Node: thisNode, Module: assignment.Module()}, assigngraph.RevisionsObjects)
p.graph = &graphKeeper{objects: objects, halves: iv.h.views}
// The keeping and removing of revisions runs off the pass loop, and a keeping that changed what the pass reads wakes
// one (design 47 H-A-259).
retry, err := keepingRetry()
if err != nil {
return err
}
p.graph = &graphKeeper{objects: objects, halves: iv.h.views, background: func(f func()) { go f() }, wake: wake, retry: retry,
reads: newBusObjects(js, process.Account{Node: thisNode, Module: assignment.Module()}, assigngraph.RevisionsObjects)}
keep := func(ctx context.Context, ev meshcatalog.CatalogRevisionEvent) error {
return p.keepCandidate(ctx, iv.call, ev)
}
@@ -628,7 +639,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
// The revisions that are not current are removed when one ceases to be current and once now (revisions.go,
// design 47 H §764, H-A-86).
p.graph.revisions = &revisionRemover{ctx: ctx, objects: objects, inUse: inUseOf(w), logf: logger.Printf}
p.graph.revisions.judge()
// The start's removal of the revisions not current folds into the first pass's keeping (H-A-261).
}
}
// The node-engine seat's manifest-reads-changed, for one node (design 47 H-A-104): its words are written into the state
@@ -646,12 +657,12 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
p.ends = newPipelineEnds(kvEnds{ctx, kv}, wake, logger.Printf)
p.ends.trunk = w.trunkName
p.ends.runEnded = func(group string) error { return p.dropCandidate(ctx, group) }
err := hearEnds(hub, p.ends)
if err == nil && bus != nil {
err = followRegistrations(ctx, hub, bus.Call, p.ends)
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)
}
if err != nil {
logger.Printf("a pipeline's end or a registration is not heard, so the wants keep the trunk-only form until the assigner starts again: %v", err)
// The registrations come from the catalog half's one follower, its one handler of registration-changed (H-A-270 (3)).
if iv == nil || iv.h == nil || !iv.h.followRegistrations(p.ends.registered) {
logger.Printf("the registrations are not followed, so the wants keep the trunk-only form until the assigner starts again: the catalog half is not followed")
}
}
hearReleases(ctx, js, w, wake, findings, logger.Printf) // version-released, machine-away and machine-back
@@ -664,10 +675,25 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
}
// The composition step (design 47 G §22, §354): the seat mesh-wants' accepted kind step, run by one run ask per machine.
if bus != nil && js != nil && inputs != nil && p.publishWants != nil && runs != nil {
run := &compositionRun{runs: runs, inputs: &compositionInputs{machines: w.machinesOf, callFile: bus.CallFile}, keeper: inputs, reads: &compositionReads{}, call: bus.CallKept,
askBound, err := composeAskBound()
if err != nil {
return err
}
run := &compositionRun{runs: runs, inputs: &compositionInputs{machines: w.machinesOf, callFile: bus.CallFileKept, bound: askBound}, keeper: inputs, reads: &compositionReads{}, call: bus.CallKept, callFile: bus.CallFileKept,
trunk: trunkOf(iv, w.trunkName), newest: iv.newestOf(), watched: iv.watchedOf, assigned: w.assignedOn, assignment: w.assignmentOf, findings: findings, running: w.runningOf, away: func(machine string) bool { return w.awayNow()[machine] }, put: runAskPublisher(js), ask: bus.CallFile, now: time.Now, logf: logger.Printf}
// The seat's work queue (design 47 H2 §777): pulled through its one worker, each ask taken once in the state taken.
takenBound, err := askTakenBound()
if err != nil {
return err
}
var ackWait atomic.Int64 // the worker's ack wait, read when it is bound
ackWait.Store(int64(buscompose.SeatQueueDefaultAckWait))
steps := &compositionSteps{node: thisNode, say: p.publishWants, run: run.run, resume: run.resume,
validate: run.validate, resumeValidate: run.resumeValidate, ended: runs.stepEnded, now: time.Now, logf: logger.Printf}
validate: run.validate, resumeValidate: run.resumeValidate, ended: runs.stepEnded, now: time.Now, logf: logger.Printf,
takenBound: takenBound, inProgress: inProgressOf(seatlist.Definition(gate.Reader, meshwants.Seat), func() time.Duration { return time.Duration(ackWait.Load()) })}
if e, ok := bus.(emitting); ok {
steps.taken = e.State(process.TakenState)
}
move := steps.move(ctx) // the readers a rerun carried (§727, A-470d)
runs.moved.Store(&move)
// The state's watch wakes the steps waiting on a run and hears a bound's expiry; the runs standing at the start are taken up
@@ -682,9 +708,14 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
_, err := meshhandactsclient.Recorder{Ask: bus.Call}.Record(q)
return err
}
stopVerbs, err := e.AnswerSeat(meshwants.Seat, seatlist.Definition(gate.Reader, meshwants.Seat), compositionVerbs(runs, steps, record))
verbs := compositionVerbs(runs, steps, record)
maps.Copy(verbs, dropVerb(steps)) // the seat's act drop (§778, H-A-404)
if p.graph != nil {
maps.Copy(verbs, keepNowVerb(ctx, p)) // the keeping by hand (§813 (2), H-A-417)
}
stopVerbs, err := e.AnswerSeat(meshwants.Seat, seatlist.Definition(gate.Reader, meshwants.Seat), verbs)
if err != nil {
logger.Printf("the verbs %s and %s are not answered until the assigner starts again: %v", meshwants.VerbCompositions, meshwants.VerbCompositionsDrop, err)
logger.Printf("the verbs %s, %s and %s are not answered until the assigner starts again: %v", meshwants.VerbCompositions, meshwants.VerbCompositionsDrop, meshwants.VerbDrop, err)
} else {
go func() { <-ctx.Done(); stopVerbs() }()
}
@@ -697,10 +728,10 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
}
p.ends.left.Store(&left)
}
if err := serveCompositionSteps(ctx, nc, steps); err != nil {
logger.Printf("the composition step is not heard, so no composition step runs until the assigner starts again: %v", err)
} else {
logger.Printf("the composition step is heard on %s", meshwants.AcceptSubjectStep)
if steps.taken == nil {
logger.Printf("the state %s is not bound, so no composition step is pulled until the assigner starts again", process.TakenState)
} else if err := serveStepQueue(ctx, nc, js, steps, func(d time.Duration) { ackWait.Store(int64(d)) }); err != nil {
logger.Printf("the composition step is not pulled, so no composition step runs until the assigner starts again: %v", err)
}
}
if bus != nil {
@@ -88,6 +88,43 @@ func (b *busObjects) Names(ctx context.Context) ([]string, error) {
return names, nil
}
// PutDescribed stores data under name with the entry's module and fingerprint in its metadata, which the listing says (assigngraph.Describer,
// design 47 H-A-259).
func (b *busObjects) PutDescribed(ctx context.Context, name string, data []byte, module, fp string) error {
o, err := b.open(ctx)
if err != nil {
return err
}
_, err = o.Put(ctx, jetstream.ObjectMeta{Name: name, Metadata: map[string]string{entryModuleMeta: module, entryFpMeta: fp}}, bytes.NewReader(data))
return err
}
// Described is every object with the module and fingerprint its metadata says, in one listing.
func (b *busObjects) Described(ctx context.Context) ([]assigngraph.Described, error) {
o, err := b.open(ctx)
if err != nil {
return nil, err
}
infos, err := o.List(ctx)
if errors.Is(err, jetstream.ErrNoObjectsFound) {
return []assigngraph.Described{}, nil
}
if err != nil {
return nil, err
}
out := make([]assigngraph.Described, 0, len(infos))
for _, i := range infos {
out = append(out, assigngraph.Described{Name: i.Name, Module: i.Metadata[entryModuleMeta], Fp: i.Metadata[entryFpMeta]})
}
return out, nil
}
// The metadata keys of an entry object's module and fingerprint.
const (
entryModuleMeta = "module"
entryFpMeta = "fp"
)
// Delete removes the object of that name; one not held is no error (design 47 G §579: a revision nothing pins is removed).
func (b *busObjects) Delete(ctx context.Context, name string) error {
o, err := b.open(ctx)
@@ -7,8 +7,10 @@ import (
"errors"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"mesh-delivery-assigner/internal/buckets"
"reflect"
"slices"
"sort"
"strconv"
"strings"
"time"
@@ -21,6 +23,8 @@ import (
"git.novox.be/novox/mesh-sdk/go/seatlist"
"sync"
"github.com/nats-io/nats.go/jetstream"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-sdk/go/catalogue"
@@ -141,13 +145,14 @@ func (p *passer) clock() time.Time {
}
func (p *passer) pass(ctx context.Context) {
start := time.Now()
defer func() { p.logf("the pass took %s", time.Since(start).Round(time.Millisecond)) }() // design 47 H-A-259
p.assignmentsSeat(ctx)
p.keepGraph(ctx)
if p.graph == nil || !p.graph.full { // a full assignment graph store keeps the last revision and writes no new want (design 47 G §181)
if held := p.keepGraph(ctx); held == "" {
p.wants(ctx)
p.sayPass(ctx, "judged")
} else {
p.sayPass(ctx, "the assignment graph store is full: no want is written (design 47 G §181)")
p.sayPass(ctx, held) // a full store keeps the last revision (design 47 G §181); none kept yet writes no want (H-A-261)
}
p.puts(ctx)
p.nodeWants(ctx)
@@ -302,11 +307,93 @@ func (p *passer) putWant(ctx context.Context, node, module string, want mwc.Want
fp = before.Fp
}
}
if p.written(ctx, buckets.Wants(), key, func() ([]byte, error) { return mwc.EncodeWant(want) }) {
if p.wantWritten(ctx, node, module, key, want) {
p.sayWanted(node, module, fp, want.Pipeline, want.Removed)
}
}
// runOf is the run a want carries (design 47 H2 §813 (1); H-A-355 (1), H-A-416): the source revision of the pipeline that
// released it, `<branch>.<source>`, in decimal; for a want of no pipeline (a put, a placement's build, a removal) the newest
// source the assigner holds for it: the trunk's source of its kept assignment graph revision, or the run of the want written
// (held) when that is newer, so a person's put or placement after a delivery is never refused as older; "" when it holds none.
func (p *passer) runOf(want mwc.Want, held *mwc.Want) string {
if i := strings.LastIndexByte(want.Pipeline, '.'); i >= 0 {
if n, err := strconv.ParseInt(want.Pipeline[i+1:], 10, 64); err == nil && n > 0 {
return strconv.FormatInt(n, 10)
}
}
var newest int64
if p.graph != nil {
if _, source, ok := p.graph.keptNow(); ok {
newest = source
}
}
if held != nil {
newest = max(newest, runNumber(held.Run))
}
if newest <= 0 {
return ""
}
return strconv.FormatInt(newest, 10)
}
// runNumber is a want's run as a number, 0 for none.
func runNumber(run string) int64 {
n, _ := strconv.ParseInt(run, 10, 64)
return n
}
// wantWritten writes the want of module on node under key by compare-and-set, carrying its run (design 47 H2 §813 (1)): a want
// that differs from the one written only by its run is not written again (its run stays, so a node never composes again for
// it), and one whose run is lower than the run written is refused, said in the journal. It answers whether it wrote.
func (p *passer) wantWritten(ctx context.Context, node, module, key string, want mwc.Want) bool {
var held *mwc.Want
if raw := p.w.value(buckets.Wants(), key); raw != nil {
if h, err := mwc.DecodeWant(raw); err == nil {
held = &h
}
}
want.Run = p.runOf(want, held)
if held != nil {
same := *held
same.Run = want.Run
if reflect.DeepEqual(same, want) {
want.Run = held.Run // it stands: nothing is written
} else if runNumber(held.Run) > runNumber(want.Run) {
p.logf("the want of %s on %s is not written: its run %q is lower than the run %q written (§813 (1))", module, node, want.Run, held.Run)
return false
}
}
value, err := mwc.EncodeWant(want)
if err != nil {
p.logf("%s %s is not written: %v", buckets.Wants(), key, err)
return false
}
if held := p.w.value(buckets.Wants(), key); held != nil && bytes.Equal(held, value) {
return false
}
kv := p.kvs[buckets.Wants()]
entry, err := kv.Get(ctx, key)
switch {
case errors.Is(err, jetstream.ErrKeyNotFound):
_, err = kv.Create(ctx, key, value)
case err == nil:
if h, derr := mwc.DecodeWant(entry.Value()); derr == nil && runNumber(h.Run) > runNumber(want.Run) {
p.logf("the want of %s on %s is not written: its run %q is lower than the run %q written (§813 (1))", module, node, want.Run, h.Run)
return false
}
_, err = kv.Update(ctx, key, value, entry.Revision())
}
if err != nil {
if !errors.Is(err, context.Canceled) {
p.logf("%s %s could not be written: %v; the next pass writes it again", buckets.Wants(), key, err)
}
return false
}
p.w.put(buckets.Wants(), key, value)
return true
}
// staleAsk says why the hold, restore or record ask at key (read as the SDK reads it) is about something the trunk has left
// behind, or "" when it is not: a module no longer on the trunk, a fingerprint that is no longer the module's trunk fingerprint,
// or, for a record ask, a composition the module's node no longer waits on. A backup ask, and a revert ask (design 47 G §710), is stale when the module's want on its
@@ -7,6 +7,7 @@ import (
"errors"
"fmt"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/buckets"
"mesh-delivery-assigner/internal/puts"
"os"
@@ -56,6 +57,7 @@ func (m *memKV) Put(_ context.Context, key string, value []byte) (uint64, error)
func (m *memKV) Create(_ context.Context, key string, value []byte, _ ...jetstream.KVCreateOpt) (uint64, error) {
m.values[key] = value
m.puts++ // a write that reaches the bucket (the wants' compare-and-set, design 47 H2 §813 (1))
return uint64(len(m.values)), nil
}
@@ -252,6 +254,7 @@ func (m *memKV) Update(_ context.Context, key string, value []byte, revision uin
return 0, errors.New("wrong last sequence")
}
m.values[key] = value
m.puts++
return uint64(len(value)), nil
}
@@ -295,6 +298,9 @@ func (b *fakeBus) CallOn(node, key string, body any) (json.RawMessage, error) {
}
func (b *fakeBus) CallKept(key string, body any) (json.RawMessage, error) { return b.Call(key, body) }
func (b *fakeBus) CallFile(key string, body any) (json.RawMessage, error) { return b.Call(key, body) }
func (b *fakeBus) CallFileKept(_ process.KeptAsk, key string, body any) (json.RawMessage, error) {
return b.Call(key, body)
}
func (b *fakeBus) Emit(eventType string, body any) error {
b.events = append(b.events, fmt.Sprintf("%s %+v", eventType, body))
return nil
@@ -14,7 +14,6 @@ import (
"github.com/nats-io/nats.go/jetstream"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
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"
@@ -161,22 +160,33 @@ 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. It says whether any key changed.
// 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.
func (e *pipelineEnds) take(p mpr.PipelineEnded) (bool, error) {
if p.Outcome != mpr.PipelineEndedOutcomePassed || p.Run != "" {
return false, nil
}
changed := false
var kept []tierMover
versioned := map[string]bool{}
defer func() {
if err := e.startTiers(p.Pipeline, kept); err != nil {
if err := e.startTiers(p.Pipeline, p.Source, kept, versioned); err != nil {
e.logf("the tier progress of %s is not written: %v", p.Pipeline, err)
}
}()
for _, m := range p.Movers {
if m.Version == "" || m.Fingerprint == "" || !moverPassed(m) {
if m.Fingerprint == "" || !moverPassed(m) {
continue
}
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.
e.logf("%s: %s passed with no version yet: taken again when its version is written", p.Pipeline, m.Module)
// It holds its tier in the progress until its version is written (H-A-277 (1)).
kept = append(kept, tierMover{Module: m.Module, Fp: m.Fingerprint, Tier: max(m.Tier, 1), NoVersion: true})
continue
}
versioned[m.Module] = true
key := endKey(m.Module, p.Branch)
for {
raw, rev, err := e.st.get(key)
@@ -372,32 +382,3 @@ func (e *pipelineEnds) registered(reg mpcat.Registration, gone bool) {
}
e.wake()
}
// followRegistrations follows the registrations through the seat mesh-catalog (design 47 G §353): a first view of its verb
// and each registration-changed on the hub. It returns when the hub's handler is registered; the first view is asked on its own
// goroutine.
func followRegistrations(ctx context.Context, hub *process.EventHub, call mcc.Call, e *pipelineEnds) error {
regs := mcc.NewRegistrations(call)
regs.Follower.Logf = e.logf
regs.Follower.Changed = func(module string, value json.RawMessage, gone bool, _ time.Time) {
reg := mpcat.Registration{Module: module}
if !gone {
_ = json.Unmarshal(value, &reg)
}
e.registered(reg, gone)
}
if err := hub.Handle(mpcat.SubjectRegistrationChanged, func(m jetstream.Msg) {
if err := regs.Hear(ctx, m.Data()); err != nil {
e.logf("%s: %v", m.Subject(), err)
}
_ = m.Ack()
}); err != nil {
return err
}
go func() {
if err := regs.Start(ctx); err != nil && ctx.Err() == nil {
e.logf("the first view of the registrations is not answered: %v", err)
}
}()
return nil
}
@@ -141,7 +141,8 @@ 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.
// 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.
func TestAPassWritesTheWantOfThePassedVersion(t *testing.T) {
fp := meshcatalogclient.SourcePrefix2 + strings.Repeat("a", 64)
for _, passed := range []bool{false, true} {
@@ -154,9 +155,15 @@ func TestAPassWritesTheWantOfThePassedVersion(t *testing.T) {
p.w.manifests[mdigest] = parsed{module: "web", manifest: catalogue.Manifest{Module: "web", Requires: []string{"database"}}}
placeOn(t, p.w, "g14", "web")
placeOn(t, p.w, "ace", "web")
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
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.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") {
t.Errorf("an end naming no version wrote %d wants and said %q", len(wantsKV.values), journal)
}
_, _ = p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("web", fp, "0.1.2", 2, mpr.StepResultOutcomePassed)))
}
p.wants(context.Background())
@@ -21,6 +21,7 @@ import (
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
)
@@ -44,6 +45,8 @@ type caller interface {
CallKept(key string, body any) (json.RawMessage, error)
// CallFile is Call of a verb marked chunks, its answer read whole (process.Conn.CallFile; design 47 G A-291).
CallFile(key string, body any) (json.RawMessage, error)
// CallFileKept is CallFile as a kept call carrying its ask's id, until its bound (process.Conn.CallFileKept; H2 §775).
CallFileKept(ask process.KeptAsk, key string, body any) (json.RawMessage, error)
Emit(eventType string, body any) error
}
@@ -2,6 +2,7 @@ package main
import (
"context"
"encoding/json"
"fmt"
"slices"
"strconv"
@@ -53,7 +54,7 @@ func trunkRevision(name string) (int64, bool) {
// remove removes each kept revision that is not current, and then the entries no kept revision or candidate lists and no want or
// running build names (design 47 G §179).
func (k *revisionRemover) remove() error {
names, err := k.objects.Names(k.ctx)
names, described, err := k.listing()
if err != nil {
return err
}
@@ -107,7 +108,7 @@ func (k *revisionRemover) remove() error {
if !ok || listed[digest] {
continue
}
e, err := assigngraph.ReadEntry(k.ctx, k.objects, digest)
e, err := k.entryOf(n, digest, described)
if err != nil {
return err
}
@@ -138,3 +139,46 @@ func inUseOf(w *world) func(module, fp string) bool {
return false
}
}
// listing is every object's name in one read and, where the bucket says them, each entry object's module and fingerprint by name
// (design 47 H-A-259); nil described where the bucket says none.
func (k *revisionRemover) listing() ([]string, map[string]assigngraph.Described, error) {
d, ok := k.objects.(assigngraph.Describer)
if !ok {
names, err := k.objects.Names(k.ctx)
return names, nil, err
}
listed, err := d.Described(k.ctx)
if err != nil {
return nil, nil, err
}
names := make([]string, 0, len(listed))
described := make(map[string]assigngraph.Described, len(listed))
for _, l := range listed {
names = append(names, l.Name)
described[l.Name] = l
}
return names, described, nil
}
// entryOf is the module and fingerprint of the entry object name: as the listing says them, with no read; an entry put before the
// listing said them is read once and put again with them, so no later judging reads it (design 47 H-A-259).
func (k *revisionRemover) entryOf(name, digest string, described map[string]assigngraph.Described) (meshwants.AssignmentEntry, error) {
if l, ok := described[name]; ok && l.Module != "" && l.Fp != "" {
return meshwants.AssignmentEntry{Module: l.Module, Fp: l.Fp}, nil
}
data, err := k.objects.Get(k.ctx, name)
if err != nil {
return meshwants.AssignmentEntry{}, fmt.Errorf("the entry %s: %w", digest, err)
}
var e meshwants.AssignmentEntry
if err := json.Unmarshal(data, &e); err != nil {
return e, fmt.Errorf("the entry %s: %w", digest, err)
}
if described != nil {
if err := assigngraph.PutEntry(k.ctx, k.objects, name, data, e); err != nil {
k.logf("the entry %s is not put again with its module and fingerprint, so the next judging reads it again: %v", digest, err)
}
}
return e, nil
}
@@ -3,6 +3,7 @@ package main
import (
"context"
"encoding/json"
"strings"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
@@ -12,42 +13,98 @@ import (
func (m memObjects) Delete(_ context.Context, name string) error { delete(m, name); return nil }
// describedObjects is memObjects whose listing says each entry's module and fingerprint (assigngraph.Describer), counting the
// entry objects read.
type describedObjects struct {
memObjects
meta map[string][2]string
reads int
}
func (d *describedObjects) Get(ctx context.Context, name string) ([]byte, error) {
if strings.HasPrefix(name, "entry.") {
d.reads++
}
return d.memObjects.Get(ctx, name)
}
func (d *describedObjects) PutDescribed(_ context.Context, name string, data []byte, module, fp string) error {
d.memObjects[name], d.meta[name] = data, [2]string{module, fp}
return nil
}
func (d *describedObjects) Described(context.Context) ([]assigngraph.Described, error) {
var out []assigngraph.Described
for n := range d.memObjects {
out = append(out, assigngraph.Described{Name: n, Module: d.meta[n][0], Fp: d.meta[n][1]})
}
return out, nil
}
// Design 47 H §764, H-A-86: with the gate's pins gone, an assignment graph revision that is not current is removed, with the
// entries no kept revision or candidate lists and no want or running build names; the current revision, the entries it lists,
// a running build's entry and a run's kept candidate with its entries stay.
// H-A-259: where the listing says each entry's module and fingerprint, the judging reads no entry object; an entry put before it
// said them is read once and put again with them.
func TestARevisionNotCurrentIsRemoved(t *testing.T) {
objects := memObjects{}
entry := func(module, fp string) string {
e := meshwants.AssignmentEntry{Node: "n1", Module: module, Fp: fp}
d := assigngraph.EntryDigest(e)
raw, _ := json.Marshal(e)
objects[assigngraph.EntryObject(d)] = raw
return d
}
shared, old, running, cand := entry("a", "fp-a"), entry("b", "fp-b1"), entry("c", "fp-c1"), entry("d", "fp-d2")
revision := func(n int64, digests ...string) {
rev := meshwants.AssignmentRevision{Revision: n}
for _, d := range digests {
rev.Entries = append(rev.Entries, meshwants.NodeEntryRef{Node: "n1", Digest: d})
for _, listed := range []string{"plain", "described", "described-later"} {
objects := memObjects{}
described := &describedObjects{memObjects: objects, meta: map[string][2]string{}}
entry := func(module, fp string) string {
e := meshwants.AssignmentEntry{Node: "n1", Module: module, Fp: fp}
d := assigngraph.EntryDigest(e)
raw, _ := json.Marshal(e)
objects[assigngraph.EntryObject(d)] = raw
if listed == "described" {
described.meta[assigngraph.EntryObject(d)] = [2]string{module, fp}
}
return d
}
raw, _ := json.Marshal(rev)
objects[assigngraph.TrunkObject(n)] = raw
}
candRaw, _ := json.Marshal(meshwants.AssignmentRevision{Revision: 1, Kind: "candidate", Group: "run-7", Heads: "h1",
Entries: []meshwants.NodeEntryRef{{Node: "n1", Module: "d", Digest: cand}}})
objects[assigngraph.CandidateObject("run-7", "h1")] = candRaw
revision(1, shared, old, running)
revision(2, shared, old)
revision(3, shared)
k := &revisionRemover{ctx: context.Background(), objects: objects, logf: t.Logf,
inUse: func(module, fp string) bool { return module == "c" && fp == "fp-c1" }}
k.judge()
has := func(name string) bool { _, ok := objects[name]; return ok }
for name, want := range map[string]bool{assigngraph.TrunkObject(1): false, assigngraph.TrunkObject(2): false, assigngraph.TrunkObject(3): true,
assigngraph.EntryObject(old): false, assigngraph.EntryObject(running): true, assigngraph.EntryObject(shared): true,
assigngraph.EntryObject(cand): true, assigngraph.CandidateObject("run-7", "h1"): true} {
if has(name) != want {
t.Errorf("%s kept = %v, want %v", name, has(name), want)
shared, old, running, cand := entry("a", "fp-a"), entry("b", "fp-b1"), entry("c", "fp-c1"), entry("d", "fp-d2")
revision := func(n int64, digests ...string) {
rev := meshwants.AssignmentRevision{Revision: n}
for _, d := range digests {
rev.Entries = append(rev.Entries, meshwants.NodeEntryRef{Node: "n1", Digest: d})
}
raw, _ := json.Marshal(rev)
objects[assigngraph.TrunkObject(n)] = raw
}
candRaw, _ := json.Marshal(meshwants.AssignmentRevision{Revision: 1, Kind: "candidate", Group: "run-7", Heads: "h1",
Entries: []meshwants.NodeEntryRef{{Node: "n1", Module: "d", Digest: cand}}})
objects[assigngraph.CandidateObject("run-7", "h1")] = candRaw
revision(1, shared, old, running)
revision(2, shared, old)
revision(3, shared)
var o revisionObjects = objects
if listed != "plain" {
o = described
}
k := &revisionRemover{ctx: context.Background(), objects: o, logf: t.Logf,
inUse: func(module, fp string) bool { return module == "c" && fp == "fp-c1" }}
k.judge()
has := func(name string) bool { _, ok := objects[name]; return ok }
for name, want := range map[string]bool{assigngraph.TrunkObject(1): false, assigngraph.TrunkObject(2): false, assigngraph.TrunkObject(3): true,
assigngraph.EntryObject(old): false, assigngraph.EntryObject(running): true, assigngraph.EntryObject(shared): true,
assigngraph.EntryObject(cand): true, assigngraph.CandidateObject("run-7", "h1"): true} {
if has(name) != want {
t.Errorf("%s: %s kept = %v, want %v", listed, name, has(name), want)
}
}
switch listed {
case "described":
if described.reads != 0 {
t.Errorf("described: the judging read %d entry objects, want none", described.reads)
}
case "described-later":
if described.meta[assigngraph.EntryObject(running)] != [2]string{"c", "fp-c1"} {
t.Errorf("described-later: the entry in use is not put again with its module and fingerprint: %v", described.meta)
}
reads := described.reads
revision(4, shared)
k.judge()
if described.reads != reads {
t.Errorf("described-later: a second judging read %d entry objects again", described.reads-reads)
}
}
}
}
@@ -0,0 +1,318 @@
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"sync"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/buscompose"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// **The seat mesh-wants takes its asks from a work queue and says ask-taken** (design 47 H2 §777, §775, §778; ADR 0525 §2,
// §6; ADR 0668 §2; H-A-381, H-A-401, H-A-404): the broker derives the seat's stream and its one shared worker from the seat's
// definition; the assigner pulls every ask waiting at once, takes each once by its id in its state taken (key
// <seat>.<ask>, for ask-taken-bound), says ask-taken at the pull, sends in-progress while the step runs and acknowledges an
// ask once it said the ask's end. An ask put while the assigner is down waits on the stream. The seat's act drop ends an ask
// its caller no longer waits for: one running here is cancelled, one not pulled yet is kept in taken as dropped.<ask> for
// ask-taken-bound, and either ends its step could not run naming the drop and who asked it.
// askTakenBoundSetting is the setting the taken key's time to live is (H-A-381 (2)): the holder never receives the
// caller's bound, so the largest caller's, the runner's ask-unanswered-bound, is its default.
const (
askTakenBoundSetting = "ask-taken-bound"
defaultAskTakenBound = 10 * time.Minute
)
// droppedPrefix keys a drop of an ask not pulled yet in the state taken (H-A-404).
const droppedPrefix = "dropped."
// takenStore is the state taken (process.State): an ask taken once by its id, and the drops of asks not pulled yet.
type takenStore interface {
TakeOnce(seat, ask string, bound time.Duration) (bool, error)
Get(key string) (*stdio.StateEntry, error)
RenewTTL(key string, value any, ttl time.Duration) (uint64, error)
Delete(key string) error
}
// queueMsg is what the steps read of a message pulled from the seat's work queue (jetstream.Msg).
type queueMsg interface {
Data() []byte
Headers() nats.Header
Ack() error
Nak() error
Term() error
InProgress() error
}
// askDrop is one drop of an ask: who asked it, why and when; the cause of a running step's end.
type askDrop struct {
By string `json:"by,omitempty"`
Why string `json:"why"`
At time.Time `json:"at"`
}
func (d *askDrop) Error() string {
by := d.By
if by == "" {
by = "its asker"
}
return fmt.Sprintf("the ask was dropped by %s: %s", by, d.Why)
}
// askIDOf is the ask's id a put carries: its event id, else its message id.
func askIDOf(h nats.Header) string {
if id := h.Get("x-event-id"); id != "" {
return id
}
return h.Get(nats.MsgIdHdr)
}
// pulled handles one ask pulled from the seat's work queue: an ask that is no composition or validate step with an id is
// terminated, said; one dropped before it was pulled ends could not run naming the drop; one running here already (handed
// again while it runs) is held for that run, which acknowledges it at its end; any other is taken once by its id (ask-taken
// said the first time) and run, in progress while it runs. A repeat of an id taken before that runs here no longer is run
// again against the runs as they stand (H-A-381 (1), H-A-401): its composition runs are joined, never run twice.
func (c *compositionSteps) pulled(ctx context.Context, m queueMsg) {
id := askIDOf(m.Headers())
var run meshwants.StepRun
err := json.Unmarshal(m.Data(), &run)
how := c.howOf(run.Step, false)
if err != nil || id == "" || how == nil {
c.logf("a step ask on the seat %s's work queue that is no composition or validate step with an id is ended: %v", meshwants.Seat, err)
_ = m.Term()
return
}
if d := c.droppedBefore(id); d != nil {
c.hold(id, m)
c.logf("the ask %s (%s) was dropped before it was pulled: %v", id, run.Pipeline, d)
c.sayEnd(id, run, nil, stepOutcome{Outcome: meshwants.StepEndedOutcomeCouldNotRun, Said: d.Error()}, "")
if err := c.taken.Delete(droppedPrefix + id); err != nil {
c.logf("the drop of the ask %s cannot be deleted from the state %s: %v", id, process.TakenState, err)
}
return
}
if c.running(id) {
c.hold(id, m)
c.logf("the ask %s (%s) was handed again while it runs here: its run answers it", id, run.Pipeline)
return
}
first, err := c.taken.TakeOnce(meshwants.Seat, id, c.takenBound)
if err != nil {
c.logf("the ask %s (%s) is not taken, the state %s refused it: %v; it is handed again", id, run.Pipeline, process.TakenState, err)
_ = m.Nak()
return
}
c.hold(id, m)
if first {
at := c.now().UTC()
if err := c.say(meshwants.EventAskTaken+"."+id, meshwants.AskTakenEvent{Ask: id, Node: c.node, At: at}, id+".taken"); err != nil {
c.logf("saying ask-taken of %s: %v", id, err)
}
} else {
c.logf("the ask %s (%s) was taken before: it is run again against its composition runs as they stand", id, run.Pipeline)
}
go c.say1(ctx, id, run, how, "")
}
// hold keeps m for the step asked under id: acknowledged once its end is said, in progress while it runs.
func (c *compositionSteps) hold(id string, m queueMsg) {
c.mu.Lock()
defer c.mu.Unlock()
if c.held == nil {
c.held = map[string][]queueMsg{}
}
c.held[id] = append(c.held[id], m)
}
// settle acknowledges (ack) or hands again (nak) every message held for id.
func (c *compositionSteps) settle(id string, ack bool) {
c.mu.Lock()
ms := c.held[id]
delete(c.held, id)
c.mu.Unlock()
for _, m := range ms {
if ack {
_ = m.Ack()
} else {
_ = m.Nak()
}
}
}
// inProgressEvery says every message held for id in progress every d, until the returned stop is called.
func (c *compositionSteps) inProgressEvery(id string) (stop func()) {
every := time.Duration(0)
if c.inProgress != nil {
every = c.inProgress()
}
if every <= 0 {
return func() {}
}
ticks := c.ticks
if ticks == nil {
ticks = func(d time.Duration) (<-chan time.Time, func()) { t := time.NewTicker(d); return t.C, t.Stop }
}
tick, stopTicks := ticks(every)
done, ended := make(chan struct{}), make(chan struct{})
go func() {
defer close(ended)
defer stopTicks()
for {
select {
case <-done:
return
case <-tick:
c.mu.Lock()
ms := append([]queueMsg(nil), c.held[id]...)
c.mu.Unlock()
for _, m := range ms {
_ = m.InProgress()
}
}
}
}()
return func() { close(done); <-ended }
}
// droppedBefore is the drop kept for an ask not pulled yet, nil for none.
func (c *compositionSteps) droppedBefore(id string) *askDrop {
if c.taken == nil {
return nil
}
e, err := c.taken.Get(droppedPrefix + id)
if err != nil {
c.logf("whether the ask %s was dropped cannot be read from the state %s: %v; it is taken", id, process.TakenState, err)
return nil
}
if e == nil {
return nil
}
var d askDrop
if json.Unmarshal(e.Value, &d) != nil {
return nil
}
return &d
}
// dropAsk is the seat's act drop (§778, H-A-404): a step running here for the ask is cancelled with the drop as its cause and
// ends could not run naming it; one not running here is kept in taken as dropped.<ask> for ask-taken-bound, so its pull ends
// it the same way. It answers whether the ask was held here.
func (c *compositionSteps) dropAsk(caller string, in meshwants.DropInput) (meshwants.DropAnswer, error) {
id, why := strings.TrimSpace(in.ID), strings.TrimSpace(in.Why)
if id == "" || why == "" {
return nil, errors.New("give the ask's id and why it is dropped")
}
by := strings.TrimSpace(in.By)
if by == "" {
by = caller
}
d := &askDrop{By: by, Why: why, At: c.now().UTC()}
c.mu.Lock()
stop := c.stops[id]
c.mu.Unlock()
if stop != nil {
stop(d)
c.logf("the ask %s running here is dropped: %v", id, d)
return meshwants.DropAnswer{"held": true}, nil
}
if c.taken == nil {
return nil, fmt.Errorf("the state %s is not bound, so the drop of %s cannot be kept", process.TakenState, id)
}
if _, err := c.taken.RenewTTL(droppedPrefix+id, d, c.takenBound); err != nil {
return nil, fmt.Errorf("writing the drop of %s in the state %s: %w", id, process.TakenState, err)
}
c.logf("the ask %s, not running here, is kept dropped until it is pulled: %v", id, d)
return meshwants.DropAnswer{"held": false}, nil
}
// dropVerb is the process's handler of the seat mesh-wants' act drop.
func dropVerb(c *compositionSteps) map[string]process.SeatHandler {
return map[string]process.SeatHandler{
meshwants.VerbDrop: func(caller string, raw json.RawMessage) (any, error) {
var in meshwants.DropInput
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
return c.dropAsk(caller, in)
},
}
}
// inProgressOf is the seat's in-progress as its definition names it, once the seat list is read; before, a third of the
// worker's ack wait, which the broker derived from the same definition (60 s and 20 s, §777; H-A-401).
func inProgressOf(def func() (seatdef.Definition, bool), ackWait func() time.Duration) func() time.Duration {
return func() time.Duration {
if d, ok := def(); ok {
if _, worker, ok, err := buscompose.SeatQueue(meshwants.Seat, d.Accepts); err == nil && ok && worker.InProgressSeconds > 0 {
return time.Duration(worker.InProgressSeconds) * time.Second
}
}
return ackWait() / 3
}
}
// serveStepQueue pulls the seat's work queue through its one shared worker, every ask waiting at once (at most the worker's
// max ack pending), once the broker made it: a worker not there yet is said, and bound when the bus says it was created.
func serveStepQueue(ctx context.Context, conn process.Subscriber, js jetstream.JetStream, c *compositionSteps, ackWait func(time.Duration)) error {
stream, worker := buscompose.SeatQueueStreamName(meshwants.Seat), buscompose.SeatQueueWorkerName(meshwants.Seat)
var once sync.Once
bind := func() bool {
cons, err := js.Consumer(ctx, stream, worker)
if err != nil {
return false
}
bound := false
once.Do(func() {
bound = true
info := cons.CachedInfo()
if info != nil && info.Config.AckWait > 0 {
ackWait(info.Config.AckWait)
}
pending := 1000
if info != nil && info.Config.MaxAckPending > 0 {
pending = info.Config.MaxAckPending
}
cc, err := cons.Consume(func(m jetstream.Msg) { c.pulled(ctx, m) }, jetstream.PullMaxMessages(pending))
if err != nil {
c.logf("the seat %s's work queue %s is not pulled: %v", meshwants.Seat, worker, err)
return
}
c.logf("the composition step is pulled from %s on %s", worker, stream)
go func() { <-ctx.Done(); cc.Stop() }()
})
return bound
}
if bind() {
return nil
}
c.logf("the seat %s's work queue %s on %s is not there yet: its asks wait on it, and it is pulled when the bus says it was created", meshwants.Seat, worker, stream)
sub, err := conn.Subscribe("$JS.EVENT.ADVISORY.CONSUMER.CREATED."+stream+"."+worker, func(*nats.Msg) { go bind() })
if err != nil {
return fmt.Errorf("hearing the creation of the seat %s's work queue: %w", meshwants.Seat, err)
}
go func() { <-ctx.Done(); _ = sub.Unsubscribe() }()
if bind() { // made between the first look and the subscription
_ = sub.Unsubscribe()
}
return nil
}
// askTakenBound reads the setting ask-taken-bound (§781).
func askTakenBound() (time.Duration, error) {
d, err := stdio.SettingDuration(askTakenBoundSetting, defaultAskTakenBound)
if err != nil {
return 0, errors.New("the assigner's " + err.Error())
}
return d, nil
}
@@ -4,6 +4,7 @@ import (
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strings"
"time"
@@ -40,13 +41,18 @@ type tierMover struct {
Module string `json:"module"`
Fp string `json:"fp"`
Tier int64 `json:"tier"`
// NoVersion is a passed mover whose version is not yet written: its tier does not run until it is (H-A-277 (1)).
NoVersion bool `json:"no-version,omitempty"`
}
// tierProgress is a pipeline's tier progress (H-A-56): the tier whose wants are written, since when, and the movers.
// tierProgress is a pipeline's tier progress (H-A-56): the tier whose wants are written, since when, the movers, and the source
// revision its pipeline-ended names, said in pipeline-wanted beside the key's revision (design 47 H-A-214, H-A-216); zero in a
// value kept before the field, read as the key's number.
type tierProgress struct {
Tier int64 `json:"tier"`
Since time.Time `json:"since"`
Movers []tierMover `json:"movers"`
Source int64 `json:"source,omitempty"`
}
// tierKey is the key of pipeline's tier progress; pipeline is the runner's key `<branch>.<source>`, its branch escaped.
@@ -58,24 +64,53 @@ func isTierKey(key string) bool {
return strings.HasPrefix(key, tierPrefix) && strings.Count(key, ".") == 2
}
// startTiers writes the tier progress of a passed pipeline whose movers' versions are now kept, its first tier the lowest of
// theirs, since now. A pipeline heard again writes nothing.
func (e *pipelineEnds) startTiers(pipeline string, movers []tierMover) error {
if len(movers) == 0 {
return nil
}
first := movers[0].Tier
for _, m := range movers {
first = min(first, m.Tier)
}
value, err := json.Marshal(tierProgress{Tier: first, Since: e.clock().UTC(), Movers: movers})
if err != nil {
// startTiers writes the tier progress of a passed pipeline, holding every passed mover, versioned or not, its first tier the
// lowest of theirs, since now (H-A-277 (1)). A pipeline heard again adds to the progress that stands each mover it does not hold,
// at the mover's tier, and marks versioned each held mover whose version is now written (H-A-270, H-A-273): its want is written
// when the progress reaches its tier, or at once when that tier ran already, never out of tier order.
func (e *pipelineEnds) startTiers(pipeline string, source int64, movers []tierMover, versioned map[string]bool) error {
for {
t, rev, ok := e.tiersOf(pipeline)
if !ok {
if len(movers) == 0 {
return nil
}
first := movers[0].Tier
for _, m := range movers {
first = min(first, m.Tier)
}
t = tierProgress{Tier: first, Since: e.clock().UTC(), Source: source}
}
moved := false
for i := range t.Movers {
if t.Movers[i].NoVersion && versioned[t.Movers[i].Module] {
t.Movers[i].NoVersion, moved = false, true
}
}
for _, m := range movers {
if !slices.ContainsFunc(t.Movers, func(h tierMover) bool { return h.Module == m.Module }) {
t.Movers, moved = append(t.Movers, m), true
}
}
if !moved {
return nil
}
value, err := json.Marshal(t)
if err != nil {
return err
}
err = e.st.swap(tierKey(pipeline), value, rev)
if errors.Is(err, errSwapped) {
if _, _, held := e.tiersOf(pipeline); !ok && !held {
return nil // a key that stands but does not read is left as it is
}
continue
}
if err == nil && ok {
e.logf("pipeline %s: a mover whose version came after its end is taken into the tier progress", pipeline)
}
return err
}
if err := e.st.swap(tierKey(pipeline), value, 0); err != nil && !errors.Is(err, errSwapped) {
return err
}
return nil
}
func (e *pipelineEnds) clock() time.Time {
@@ -131,7 +166,7 @@ func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []st
continue
}
pipeline := strings.TrimPrefix(key, tierPrefix)
branchEsc, source, _ := strings.Cut(pipeline, ".")
branchEsc, number, _ := strings.Cut(pipeline, ".")
branch, err := keys.UnescapeName(branchEsc)
if err != nil {
continue
@@ -144,7 +179,7 @@ func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []st
notRunning := p.notRunning(n, placedOn, pipeline, branch, t, t.Tier)
late := !now.Before(t.Since.Add(bound))
if late {
p.tierLate(pipeline, branch, source, t, notRunning)
p.tierLate(pipeline, branch, number, t, notRunning)
break
}
if len(notRunning) > 0 {
@@ -165,10 +200,10 @@ func (p *passer) tiers(n assign.Nodes, placedOn func(module, branch string) []st
p.logf("the tier progress %s is not deleted: %v", key, err)
break
}
p.sayPipelineWanted(pipeline, branch, source, meshwants.PipelineWantedOutcomeRunning, nil)
p.sayPipelineWanted(pipeline, branch, number, t.Source, meshwants.PipelineWantedOutcomeRunning, nil)
break
}
value, err := json.Marshal(tierProgress{Tier: later, Since: now, Movers: t.Movers})
value, err := json.Marshal(tierProgress{Tier: later, Since: now, Movers: t.Movers, Source: t.Source})
if err == nil {
err = p.ends.st.swap(key, value, rev)
}
@@ -193,6 +228,18 @@ func (p *passer) notRunning(n assign.Nodes, placedOn func(module, branch string)
if m.Tier != tier {
continue
}
if m.NoVersion {
// A mover whose version is not yet written holds its tier, under the tier bound (H-A-277 (1)).
machines := []string{}
for _, node := range placedOn(m.Module, branch) {
if online, known := n.Online[node]; !known || online {
machines = append(machines, node)
}
}
sort.Strings(machines)
out = append(out, meshwants.NotRunning{Module: m.Module, Machines: machines})
continue
}
if end, ok := p.ends.endOf(m.Module, branch); !ok || end.Pipeline != pipeline {
continue // a later pipeline moved it
}
@@ -217,7 +264,7 @@ func (p *passer) notRunning(n assign.Nodes, placedOn func(module, branch string)
// tierLate ends a pipeline's delivery at a tier past tier-bound: the finding tier-late is raised and pipeline-wanted says tier-late,
// once each; the finding clears once the late movers run or a later pipeline moved them. The progress stays, so no later tier is
// written, until no later tier's mover is kept at this pipeline any more.
func (p *passer) tierLate(pipeline, branch, source string, t tierProgress, notRunning []meshwants.NotRunning) {
func (p *passer) tierLate(pipeline, branch, number string, t tierProgress, notRunning []meshwants.NotRunning) {
o := tierLateFinding(pipeline, t.Tier, notRunning)
key := views.FindingKey(o.Scope, assign.KeyID(o.ID), o.Kind)
if len(notRunning) > 0 {
@@ -231,7 +278,7 @@ func (p *passer) tierLate(pipeline, branch, source string, t tierProgress, notRu
p.said[key+".raised"] = true
delete(p.said, key+".cleared")
p.logf("pipeline %s: tier %d is late (tier-bound %s): %s; no later tier is written", pipeline, t.Tier, p.tierBoundOf(), o.Summary)
p.sayPipelineWanted(pipeline, branch, source, meshwants.PipelineWantedOutcomeTierLate, notRunning)
p.sayPipelineWanted(pipeline, branch, number, t.Source, meshwants.PipelineWantedOutcomeTierLate, notRunning)
}
} else if !p.said[key+".cleared"] {
if p.findings.Delete != nil {
@@ -271,11 +318,16 @@ func tierLateFinding(pipeline string, tier int64, notRunning []meshwants.NotRunn
Source: "assigner." + kindTierLate}
}
// sayPipelineWanted says the seat mesh-wants' pipeline-wanted of pipeline, once (its id the pipeline and the outcome).
func (p *passer) sayPipelineWanted(pipeline, branch, source, outcome string, notRunning []meshwants.NotRunning) {
var src int64
_, _ = fmt.Sscan(source, &src)
body := meshwants.PipelineWantedEvent{V: keys.Version, Pipeline: pipeline, Branch: branch, Source: src, Outcome: outcome, NotRunning: notRunning}
// sayPipelineWanted says the seat mesh-wants' pipeline-wanted of pipeline, once (its id the pipeline and the outcome): its
// revision the number of the pipeline's key `<branch>.<revision>`, its source the one the pipeline-ended named (design 47
// H-A-214, H-A-216), the key's number for a progress kept before it held one.
func (p *passer) sayPipelineWanted(pipeline, branch, number string, source int64, outcome string, notRunning []meshwants.NotRunning) {
var revision int64
_, _ = fmt.Sscan(number, &revision)
if source <= 0 {
source = revision
}
body := meshwants.PipelineWantedEvent{V: keys.Version, Pipeline: pipeline, Branch: branch, Source: source, Revision: revision, Outcome: outcome, NotRunning: notRunning}
event := meshwants.EventPipelineWanted + "." + pipeline
if err := p.wantsSay(event, body, "pipeline-wanted."+pipeline+"."+outcome); err != nil {
p.logf("pipeline-wanted of %s is not said: %v", pipeline, err)
@@ -62,8 +62,11 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
p.w.mu.Unlock()
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk, p.ends.now = p.w.trunkName, func() time.Time { return now }
if _, err := p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("db", db, "0.2.0", 1, mpr.StepResultOutcomePassed),
mover("web", web, "0.1.2", 2, mpr.StepResultOutcomePassed))); err != nil {
// The pipeline of revision 5 (its key's number) of source 4: a re-pin's revision (H-A-213, H-A-216).
e := ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, mover("db", db, "0.2.0", 1, mpr.StepResultOutcomePassed),
mover("web", web, "0.1.2", 2, mpr.StepResultOutcomePassed))
e.Source = 4
if _, err := p.ends.take(e); err != nil {
t.Fatal(err)
}
wanted := func(node, module string) bool {
@@ -88,7 +91,7 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
raw, _ = json.Marshal(nodeengine.Running{Node: "g14", Module: "web", Fingerprint: web})
_ = p.w.hearRunning("running.g14.web", raw)
p.wants(context.Background())
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeRunning || len(findings) != 0 {
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeRunning || said[0].Revision != 5 || said[0].Source != 4 || len(findings) != 0 {
t.Errorf("every tier runs: said %+v, findings %v", said, findings)
}
if _, _, ok := p.ends.tiersOf(trunkBranch + ".5"); ok {
@@ -108,11 +111,100 @@ func TestAPipelinesWantsAreWrittenTierByTier(t *testing.T) {
if !ok || !strings.Contains(f.Summary, "db on g14") || strings.Contains(f.Summary, "ace") {
t.Errorf("tier-late is not raised naming db on g14 alone: %v", findings)
}
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeTierLate || len(said[0].NotRunning) != 1 || said[0].NotRunning[0].Module != "db" {
t.Errorf("pipeline-wanted tier-late is not said once: %+v", said)
if len(said) != 1 || said[0].Outcome != meshwants.PipelineWantedOutcomeTierLate || len(said[0].NotRunning) != 1 || said[0].NotRunning[0].Module != "db" ||
said[0].Revision != 5 || said[0].Source != 4 {
t.Errorf("pipeline-wanted tier-late is not said once, naming revision 5 of source 4: %+v", said)
}
// A tier progress kept before it held its source says the key's number as both (H-A-216).
p.sayPipelineWanted(trunkBranch+".5", trunkBranch, "5", 0, meshwants.PipelineWantedOutcomeRunning, nil)
if len(said) != 2 || said[1].Revision != 5 || said[1].Source != 5 {
t.Errorf("a progress with no source: said %+v, want revision and source 5", said)
}
if wanted("g14", "web") || wanted("ace", "web") {
t.Error("a consumer's want is written after its provider's tier was late")
}
}
}
// H-A-270, H-A-273, H-A-277 (1): a pipeline's tier progress holds every passed mover, versioned or not, and a tier with a mover
// whose version is not yet written does not run until it is: no later tier is wanted out of order. When the lowest tier's version
// comes last, nothing is wanted before it; with db (1) and api (3) versioned and web (2) late, api is wanted only once web runs.
func TestALateMoverHoldsItsTier(t *testing.T) {
type step struct {
versions map[string]string // a pipeline-ended taken, each mover's version ("": none yet)
runs string // or: this module runs on g14
wanted string // then: the modules wanted, in order of the list
}
for _, c := range []struct {
name string
steps []step
}{
{"the lowest tier's version comes last", []step{
{versions: map[string]string{"db": "", "web": "0.1.2", "api": "0.3.0"}, wanted: ""},
{versions: map[string]string{"db": "0.2.0", "web": "0.1.2", "api": "0.3.0"}, wanted: "db"},
{runs: "db", wanted: "db,web"},
{runs: "web", wanted: "db,web,api"},
}},
{"a middle tier's version comes late", []step{
{versions: map[string]string{"db": "0.2.0", "web": "", "api": "0.3.0"}, wanted: "db"},
{runs: "db", wanted: "db"},
{versions: map[string]string{"db": "0.2.0", "web": "0.1.2", "api": "0.3.0"}, wanted: "db,web"},
{runs: "web", wanted: "db,web,api"},
}},
} {
t.Run(c.name, func(t *testing.T) {
fps := map[string]string{}
tiers := map[string]int64{"db": 1, "web": 2, "api": 3}
for i, m := range []string{"db", "web", "api"} {
fps[m] = meshcatalogclient.SourcePrefix2 + strings.Repeat(string(rune('a'+i)), 64)
}
start := time.Date(2026, 11, 21, 4, 0, 0, 0, time.UTC)
now := start
wantsKV := &memKV{values: map[string][]byte{}}
p := newPasser(kvSet{buckets.Wants(): wantsKV, buckets.Asks(): &memKV{values: map[string][]byte{}}}, start)
p.now = func() time.Time { return now }
p.say = func(oc.Condition) error { return nil }
p.publishWants = func(string, any, string) error { return nil }
for i, m := range []string{"db", "web", "api"} {
digest := strings.Repeat(string(rune('1'+i)), 64)
mod, _ := meshcatalogclient.EncodeModule(meshcatalog.ModulesByModuleValue{Fp2: fps[m], Manifest: digest, Repository: "novox/" + m, Commit: strings.Repeat("1", 40), Path: meshcatalogclient.RootPath})
putModuleRaw(p.w, trunkBranch, m, mod)
p.w.manifests[digest] = parsed{module: m, manifest: catalogue.Manifest{Module: m}}
}
placeOn(t, p.w, "g14", "db", "web", "api")
p.w.mu.Lock()
p.w.runningHeard = true
p.w.mu.Unlock()
p.ends = newPipelineEnds(newMemEnds(), func() {}, t.Logf)
p.ends.trunk, p.ends.now = p.w.trunkName, func() time.Time { return now }
for i, s := range c.steps {
if s.versions != nil {
var movers []mpr.MoverEnded
for _, m := range []string{"db", "web", "api"} {
movers = append(movers, mover(m, fps[m], s.versions[m], tiers[m], mpr.StepResultOutcomePassed))
}
if _, err := p.ends.take(ended(trunkBranch, 5, mpr.PipelineEndedOutcomePassed, movers...)); err != nil {
t.Fatal(err)
}
} else {
raw, _ := json.Marshal(nodeengine.Running{Node: "g14", Module: s.runs, Fingerprint: fps[s.runs]})
if err := p.w.hearRunning("running.g14."+s.runs, raw); err != nil {
t.Fatal(err)
}
}
now = now.Add(time.Minute)
p.wants(context.Background())
var got []string
for _, m := range []string{"db", "web", "api"} {
key, _ := mwc.WantKey("g14", m)
if _, ok := wantsKV.values[key]; ok {
got = append(got, m)
}
}
if strings.Join(got, ",") != s.wanted {
t.Fatalf("step %d: wanted %v, want %q", i+1, got, s.wanted)
}
}
})
}
}
@@ -22,6 +22,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/catalogkey"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seatlist"
"git.novox.be/novox/mesh-sdk/go/stateobjects"
"mesh-delivery-assigner/internal/buckets"
@@ -416,6 +417,9 @@ func serveTools() error {
tools = append(tools, whyTools(runtimeStore{})...)
tools = append(tools, askAgainTools(runtimeStore{}, stdio.Ask, time.Now)...)
tools = append(tools, wantDropTools(runtimeStore{}, stdio.Ask)...)
tools = append(tools, asksTools(stdio.QueueWaiting, stdio.State(process.TakenState), stdio.Ask)...) // the seat's work queue (§777)
tools = append(tools, keepNowTools(stdio.Ask)...)
tools = append(tools, validateBeforeTools(runtimeStore{})...) // what a validate step did not count (§814) // the keeping by hand (§813 (2))
return stdio.Serve("", tools)
}

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