diff --git a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/registrations_test.go b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/registrations_test.go index 647ecc1e2..08ebacb21 100644 --- a/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/registrations_test.go +++ b/modules/mesh-delivery-contracts/go/clients/meshcatalogclient/registrations_test.go @@ -40,7 +40,7 @@ func (f *fakeRegistrations) call(key string, body any) (json.RawMessage, error) if name, ok := strings.CutPrefix(m, "source.novox."); ok { // A source-only registration names no module and no path (design 47 H2 §815). a.Registrations = append(a.Registrations, seat.Registration{Version: v, Origin: "novox/" + name, Branches: []string{"main"}, - Check: &seat.SourceCheck{Seat: "node-build-go", Step: "unit"}}) + Check: &seat.SourceCheck{Step: "unit"}}) continue } a.Registrations = append(a.Registrations, seat.Registration{Module: m, Version: v, Origin: "novox/" + m, Path: "module.json", Branches: []string{"main"}}) diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go index e801f0222..1744be5f1 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go @@ -23,7 +23,7 @@ const FormBuildStep = 2 // whose fields changed while its forms did not (design 47 H2 §780). const ( generatedForms = "1 build-step:2" - generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckRunAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=a49b1cbd0c12 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" + generatedFieldsDigest = "AnswerAnswer=a3b42bd5e791 AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckRunAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c InstallAsk=9f965aa5b30b KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=75190430d510 StepAsk=a22b1f717fc3 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=14b484f0ffa2 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" ) const ( @@ -33,6 +33,7 @@ const ( VerbDrop = "drop" VerbKeptArtifact = "kept-artifact" VerbSteps = "steps" + VerbAnswer = "answer" VerbOutput = "output" ) @@ -54,7 +55,7 @@ const ( // 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, VerbKeptArtifact, VerbSteps, VerbOutput} + return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop, VerbKeptArtifact, VerbSteps, VerbAnswer, VerbOutput} } // Events is every event published on the seat's subject: a new copy each call. @@ -561,12 +562,14 @@ type FetchRefusal struct { Reason string `json:"reason"` } -// InstallAsk is an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest. +// InstallAsk is the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers. type InstallAsk struct { // who asked it Asker string `json:"asker"` // the commit the lock is read at Commit string `json:"commit"` + // the module's build-input fingerprint at the commit + Fingerprint string `json:"fingerprint"` // the ask's id ID string `json:"id"` // the package lock's text at the commit @@ -727,15 +730,15 @@ type RunProgram struct { type Step struct { // when the bus gives the ask again, for the state again (RFC 3339 time) AgainAt *time.Time `json:"again-at,omitempty"` + // the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer + AnswerObject string `json:"answer-object,omitempty"` // when (RFC 3339 time) Ended *time.Time `json:"ended,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). - Form int64 `json:"form,omitempty"` - ID string `json:"id"` - Node string `json:"node"` - // the name of the object in the build module's outputs store that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb output - OutputObject string `json:"output-object,omitempty"` - Owner string `json:"owner,omitempty"` + Form int64 `json:"form,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"` @@ -800,7 +803,9 @@ type StepAsk struct { Check *StepAskCheck `json:"check,omitempty"` Compose *StepAskCompose `json:"compose,omitempty"` ID string `json:"id"` - // build, check, compose or step + // the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version + Install *InstallAsk `json:"install,omitempty"` + // build, check, compose, step or install Kind string `json:"kind"` // go, typescript or image Language string `json:"language"` @@ -819,7 +824,9 @@ type StepAsk struct { // StepEnded is an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548). type StepEnded struct { - // for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) + // the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer + AnswerObject string `json:"answer-object,omitempty"` + // for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2)) Archive string `json:"archive,omitempty"` Artifact string `json:"artifact,omitempty"` // the ask's id, by which a reader takes only its own asks @@ -849,11 +856,9 @@ type StepEnded struct { // never passed for a step that ran nothing Outcome string `json:"outcome"` // the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) - Output string `json:"output,omitempty"` - // the name of the object that holds the run's answer, kept by the build seat's holder, when the answer is over what the event carries (design 47 G A-254); read through the verb output - OutputObject string `json:"output-object,omitempty"` - Pipeline string `json:"pipeline,omitempty"` - Rerun bool `json:"rerun,omitempty"` + Output string `json:"output,omitempty"` + Pipeline string `json:"pipeline,omitempty"` + Rerun bool `json:"rerun,omitempty"` // why it failed or could not run, naming the part not heard Said string `json:"said,omitempty"` Started *time.Time `json:"started,omitempty"` @@ -927,7 +932,7 @@ type StepResult struct { // StepRun is one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip. type StepRun struct { - // the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) + // the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2)) Archive string `json:"archive,omitempty"` // the artifact reference, : Artifact string `json:"artifact"` @@ -1145,6 +1150,24 @@ type StepsAnswer struct { Steps []DetectedStep `json:"steps,omitempty"` } +// AnswerInput is what answer takes. +type AnswerInput struct { + // the ask's id, the `answer-object` of its step key or its step-ended naming it + Ask string `json:"ask"` + // 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements + Call string `json:"call"` +} + +// AnswerAnswer is what answer answers. +type AnswerAnswer struct { + // the ask's id + Ask string `json:"ask"` + // how many chunks are sent; 0 when this node keeps no answer of that ask + Chunks int64 `json:"chunks"` + // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). + Form int64 `json:"form,omitempty"` +} + // OutputInput is what output takes. type OutputInput struct { // the ask's id @@ -1272,6 +1295,15 @@ func DecodeStepsAnswer(raw []byte) (StepsAnswer, int, error) { return v, formRead(raw), nil } +// DecodeAnswerAnswer reads a AnswerAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780). +func DecodeAnswerAnswer(raw []byte) (AnswerAnswer, int, error) { + var v AnswerAnswer + if err := json.Unmarshal(raw, &v); err != nil { + return v, 0, err + } + return v, formRead(raw), nil +} + // DecodeOutputAnswer reads a OutputAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780). func DecodeOutputAnswer(raw []byte) (OutputAnswer, int, error) { var v OutputAnswer diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go index 0456d014c..5447adb4e 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go @@ -19,7 +19,7 @@ func TestFixtures(t *testing.T) { }{ {name: "a unit step ended passed on its node, with its counts and what it carried", subject: "mesh.seat.node-build-go.event.step-ended.anchor", given: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"carried\":[{\"digest\":\"sha256:bbbb\",\"level\":\"unit\",\"package\":\"./modules/nats/a\"}],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"ended\":\"2026-11-10T10:02:00Z\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5e\",\"kept\":[{\"digest\":\"sha256:cccc\",\"level\":\"unit\",\"package\":\"./modules/nats/b\"}],\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"started\":\"2026-11-10T10:00:00Z\",\"step\":\"unit\",\"tests\":{\"unit\":14},\"v\":1}", wire: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"carried\":[{\"digest\":\"sha256:bbbb\",\"level\":\"unit\",\"package\":\"./modules/nats/a\"}],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"ended\":\"2026-11-10T10:02:00Z\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5e\",\"kept\":[{\"digest\":\"sha256:cccc\",\"level\":\"unit\",\"package\":\"./modules/nats/b\"}],\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"started\":\"2026-11-10T10:00:00Z\",\"step\":\"unit\",\"tests\":{\"unit\":14},\"v\":1}", decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-go\\.event\\.step-ended\\.[^.*> ]+$")}, - {name: "an integration step that could not run, naming the part not heard", subject: "mesh.seat.node-build-go.event.step-ended.home-server", given: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"output-object\":\"mesh-build-go_sent-objects/m2kx9a1b3c4d5f\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", wire: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"output-object\":\"mesh-build-go_sent-objects/m2kx9a1b3c4d5f\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", + {name: "an integration step that could not run, naming the part not heard", subject: "mesh.seat.node-build-go.event.step-ended.home-server", given: "{\"answer-object\":\"answer.m2kx9a1b3c4d5f\",\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", wire: "{\"answer-object\":\"answer.m2kx9a1b3c4d5f\",\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-go\\.event\\.step-ended\\.[^.*> ]+$")}, {name: "a node's toolchain reported", subject: "mesh.seat.node-build-go.event.toolchain-reported.anchor", given: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"language\":\"go\",\"node\":\"anchor\",\"recipe\":\"1\",\"version\":\"1.26.0\"}", wire: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"language\":\"go\",\"node\":\"anchor\",\"recipe\":\"1\",\"version\":\"1.26.0\"}", decode: func(b []byte) (any, error) { var v ToolchainReportedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-go\\.event\\.toolchain-reported\\.[^.*> ]+$")}, @@ -97,7 +97,7 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a check's step whose answer is kept as an object (G A-290)", subject: "", given: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", + {name: "a check's step whose answer is kept as an object (G A-290)", subject: "", given: "{\"answer-object\":\"answer.c3d4e5f6a7b8c9\",\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"answer-object\":\"answer.c3d4e5f6a7b8c9\",\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"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: "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}, @@ -123,6 +123,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "steps answers a drop that the hand-act log refused", subject: "", given: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", wire: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "answer asks a step's kept end by its ask, naming the call of its chunks", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", + decode: func(b []byte) (any, error) { var v AnswerInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "answer answers how many chunks carry the kept end", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", + decode: func(b []byte) (any, error) { var v AnswerAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "output asks a step's output by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\"}", decode: func(b []byte) (any, error) { var v OutputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "output answers the last 64 KB, the size and the failing tests with their words", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go index c4672c283..5d2ecb30f 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go @@ -23,7 +23,7 @@ const FormBuildStep = 2 // whose fields changed while its forms did not (design 47 H2 §780). const ( generatedForms = "1 build-step:2" - generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=a49b1cbd0c12 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" + generatedFieldsDigest = "AnswerAnswer=a3b42bd5e791 AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c InstallAsk=9f965aa5b30b KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=75190430d510 StepAsk=a22b1f717fc3 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=14b484f0ffa2 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" ) const ( @@ -33,6 +33,7 @@ const ( VerbDrop = "drop" VerbKeptArtifact = "kept-artifact" VerbSteps = "steps" + VerbAnswer = "answer" VerbOutput = "output" ) @@ -53,7 +54,7 @@ const ( // 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, VerbKeptArtifact, VerbSteps, VerbOutput} + return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop, VerbKeptArtifact, VerbSteps, VerbAnswer, VerbOutput} } // Events is every event published on the seat's subject: a new copy each call. @@ -559,12 +560,14 @@ type FetchRefusal struct { Reason string `json:"reason"` } -// InstallAsk is an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest. +// InstallAsk is the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers. type InstallAsk struct { // who asked it Asker string `json:"asker"` // the commit the lock is read at Commit string `json:"commit"` + // the module's build-input fingerprint at the commit + Fingerprint string `json:"fingerprint"` // the ask's id ID string `json:"id"` // the package lock's text at the commit @@ -725,15 +728,15 @@ type RunProgram struct { type Step struct { // when the bus gives the ask again, for the state again (RFC 3339 time) AgainAt *time.Time `json:"again-at,omitempty"` + // the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer + AnswerObject string `json:"answer-object,omitempty"` // when (RFC 3339 time) Ended *time.Time `json:"ended,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). - Form int64 `json:"form,omitempty"` - ID string `json:"id"` - Node string `json:"node"` - // the name of the object in the build module's outputs store that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb output - OutputObject string `json:"output-object,omitempty"` - Owner string `json:"owner,omitempty"` + Form int64 `json:"form,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"` @@ -798,7 +801,9 @@ type StepAsk struct { Check *StepAskCheck `json:"check,omitempty"` Compose *StepAskCompose `json:"compose,omitempty"` ID string `json:"id"` - // build, check, compose or step + // the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version + Install *InstallAsk `json:"install,omitempty"` + // build, check, compose, step or install Kind string `json:"kind"` // go, typescript or image Language string `json:"language"` @@ -817,7 +822,9 @@ type StepAsk struct { // StepEnded is an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548). type StepEnded struct { - // for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) + // the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer + AnswerObject string `json:"answer-object,omitempty"` + // for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2)) Archive string `json:"archive,omitempty"` Artifact string `json:"artifact,omitempty"` // the ask's id, by which a reader takes only its own asks @@ -847,11 +854,9 @@ type StepEnded struct { // never passed for a step that ran nothing Outcome string `json:"outcome"` // the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) - Output string `json:"output,omitempty"` - // the name of the object that holds the run's answer, kept by the build seat's holder, when the answer is over what the event carries (design 47 G A-254); read through the verb output - OutputObject string `json:"output-object,omitempty"` - Pipeline string `json:"pipeline,omitempty"` - Rerun bool `json:"rerun,omitempty"` + Output string `json:"output,omitempty"` + Pipeline string `json:"pipeline,omitempty"` + Rerun bool `json:"rerun,omitempty"` // why it failed or could not run, naming the part not heard Said string `json:"said,omitempty"` Started *time.Time `json:"started,omitempty"` @@ -925,7 +930,7 @@ type StepResult struct { // StepRun is one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip. type StepRun struct { - // the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) + // the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2)) Archive string `json:"archive,omitempty"` // the artifact reference, : Artifact string `json:"artifact"` @@ -1143,6 +1148,24 @@ type StepsAnswer struct { Steps []DetectedStep `json:"steps,omitempty"` } +// AnswerInput is what answer takes. +type AnswerInput struct { + // the ask's id, the `answer-object` of its step key or its step-ended naming it + Ask string `json:"ask"` + // 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements + Call string `json:"call"` +} + +// AnswerAnswer is what answer answers. +type AnswerAnswer struct { + // the ask's id + Ask string `json:"ask"` + // how many chunks are sent; 0 when this node keeps no answer of that ask + Chunks int64 `json:"chunks"` + // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). + Form int64 `json:"form,omitempty"` +} + // OutputInput is what output takes. type OutputInput struct { // the ask's id @@ -1267,6 +1290,15 @@ func DecodeStepsAnswer(raw []byte) (StepsAnswer, int, error) { return v, formRead(raw), nil } +// DecodeAnswerAnswer reads a AnswerAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780). +func DecodeAnswerAnswer(raw []byte) (AnswerAnswer, int, error) { + var v AnswerAnswer + if err := json.Unmarshal(raw, &v); err != nil { + return v, 0, err + } + return v, formRead(raw), nil +} + // DecodeOutputAnswer reads a OutputAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780). func DecodeOutputAnswer(raw []byte) (OutputAnswer, int, error) { var v OutputAnswer diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go index a65434fc2..97913d4fd 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go @@ -19,7 +19,7 @@ func TestFixtures(t *testing.T) { }{ {name: "a lint step ended passed on its node", subject: "mesh.seat.node-build-image.event.step-ended.anchor", given: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"ended\":\"2026-11-10T10:02:00Z\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5e\",\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"started\":\"2026-11-10T10:00:00Z\",\"step\":\"lint\",\"v\":1}", wire: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"ended\":\"2026-11-10T10:02:00Z\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5e\",\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"started\":\"2026-11-10T10:00:00Z\",\"step\":\"lint\",\"v\":1}", decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-image\\.event\\.step-ended\\.[^.*> ]+$")}, - {name: "a lint step that could not run, naming the part not heard", subject: "mesh.seat.node-build-image.event.step-ended.home-server", given: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"output-object\":\"mesh-build-go_sent-objects/m2kx9a1b3c4d5f\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"lint\",\"v\":1}", wire: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"output-object\":\"mesh-build-go_sent-objects/m2kx9a1b3c4d5f\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"lint\",\"v\":1}", + {name: "a lint step that could not run, naming the part not heard", subject: "mesh.seat.node-build-image.event.step-ended.home-server", given: "{\"answer-object\":\"answer.m2kx9a1b3c4d5f\",\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"lint\",\"v\":1}", wire: "{\"answer-object\":\"answer.m2kx9a1b3c4d5f\",\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"lint\",\"v\":1}", decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-image\\.event\\.step-ended\\.[^.*> ]+$")}, {name: "a node's toolchain reported", subject: "mesh.seat.node-build-image.event.toolchain-reported.anchor", given: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"language\":\"go\",\"node\":\"anchor\",\"recipe\":\"1\",\"version\":\"1.26.0\"}", wire: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"language\":\"go\",\"node\":\"anchor\",\"recipe\":\"1\",\"version\":\"1.26.0\"}", decode: func(b []byte) (any, error) { var v ToolchainReportedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-image\\.event\\.toolchain-reported\\.[^.*> ]+$")}, @@ -79,7 +79,7 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a check's step whose answer is kept as an object (G A-290)", subject: "", given: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", + {name: "a check's step whose answer is kept as an object (G A-290)", subject: "", given: "{\"answer-object\":\"answer.c3d4e5f6a7b8c9\",\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"answer-object\":\"answer.c3d4e5f6a7b8c9\",\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"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: "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}, @@ -105,6 +105,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "steps answers a drop that the hand-act log refused", subject: "", given: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", wire: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "answer asks a step's kept end by its ask, naming the call of its chunks", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", + decode: func(b []byte) (any, error) { var v AnswerInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "answer answers how many chunks carry the kept end", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", + decode: func(b []byte) (any, error) { var v AnswerAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "output asks a step's output by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\"}", decode: func(b []byte) (any, error) { var v OutputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "output answers the last 64 KB, the size and the failing tests with their words", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go index 3a7717686..7a73d14f6 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go @@ -23,7 +23,7 @@ const FormBuildStep = 2 // whose fields changed while its forms did not (design 47 H2 §780). const ( generatedForms = "1 build-step:2" - generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c InstallAccept=6c42a0d3fe6d InstallAsk=7a855a79d290 KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=a49b1cbd0c12 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" + generatedFieldsDigest = "AnswerAnswer=a3b42bd5e791 AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c InstallAccept=ef89c6962ae4 InstallAsk=9f965aa5b30b KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=75190430d510 StepAsk=a22b1f717fc3 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=14b484f0ffa2 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" ) const ( @@ -33,6 +33,7 @@ const ( VerbDrop = "drop" VerbKeptArtifact = "kept-artifact" VerbSteps = "steps" + VerbAnswer = "answer" VerbOutput = "output" ) @@ -54,7 +55,7 @@ const ( // 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, VerbKeptArtifact, VerbSteps, VerbOutput} + return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop, VerbKeptArtifact, VerbSteps, VerbAnswer, VerbOutput} } // Events is every event published on the seat's subject: a new copy each call. @@ -563,12 +564,14 @@ type FetchRefusal struct { Reason string `json:"reason"` } -// InstallAsk is an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest. +// InstallAsk is the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers. type InstallAsk struct { // who asked it Asker string `json:"asker"` // the commit the lock is read at Commit string `json:"commit"` + // the module's build-input fingerprint at the commit + Fingerprint string `json:"fingerprint"` // the ask's id ID string `json:"id"` // the package lock's text at the commit @@ -729,15 +732,15 @@ type RunProgram struct { type Step struct { // when the bus gives the ask again, for the state again (RFC 3339 time) AgainAt *time.Time `json:"again-at,omitempty"` + // the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer + AnswerObject string `json:"answer-object,omitempty"` // when (RFC 3339 time) Ended *time.Time `json:"ended,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). - Form int64 `json:"form,omitempty"` - ID string `json:"id"` - Node string `json:"node"` - // the name of the object in the build module's outputs store that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb output - OutputObject string `json:"output-object,omitempty"` - Owner string `json:"owner,omitempty"` + Form int64 `json:"form,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"` @@ -802,7 +805,9 @@ type StepAsk struct { Check *StepAskCheck `json:"check,omitempty"` Compose *StepAskCompose `json:"compose,omitempty"` ID string `json:"id"` - // build, check, compose or step + // the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version + Install *InstallAsk `json:"install,omitempty"` + // build, check, compose, step or install Kind string `json:"kind"` // go, typescript or image Language string `json:"language"` @@ -821,7 +826,9 @@ type StepAsk struct { // StepEnded is an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548). type StepEnded struct { - // for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) + // the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer + AnswerObject string `json:"answer-object,omitempty"` + // for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2)) Archive string `json:"archive,omitempty"` Artifact string `json:"artifact,omitempty"` // the ask's id, by which a reader takes only its own asks @@ -851,11 +858,9 @@ type StepEnded struct { // never passed for a step that ran nothing Outcome string `json:"outcome"` // the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) - Output string `json:"output,omitempty"` - // the name of the object that holds the run's answer, kept by the build seat's holder, when the answer is over what the event carries (design 47 G A-254); read through the verb output - OutputObject string `json:"output-object,omitempty"` - Pipeline string `json:"pipeline,omitempty"` - Rerun bool `json:"rerun,omitempty"` + Output string `json:"output,omitempty"` + Pipeline string `json:"pipeline,omitempty"` + Rerun bool `json:"rerun,omitempty"` // why it failed or could not run, naming the part not heard Said string `json:"said,omitempty"` Started *time.Time `json:"started,omitempty"` @@ -929,7 +934,7 @@ type StepResult struct { // StepRun is one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip. type StepRun struct { - // the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) + // the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2)) Archive string `json:"archive,omitempty"` // the artifact reference, : Artifact string `json:"artifact"` @@ -1147,6 +1152,24 @@ type StepsAnswer struct { Steps []DetectedStep `json:"steps,omitempty"` } +// AnswerInput is what answer takes. +type AnswerInput struct { + // the ask's id, the `answer-object` of its step key or its step-ended naming it + Ask string `json:"ask"` + // 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements + Call string `json:"call"` +} + +// AnswerAnswer is what answer answers. +type AnswerAnswer struct { + // the ask's id + Ask string `json:"ask"` + // how many chunks are sent; 0 when this node keeps no answer of that ask + Chunks int64 `json:"chunks"` + // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). + Form int64 `json:"form,omitempty"` +} + // OutputInput is what output takes. type OutputInput struct { // the ask's id @@ -1185,7 +1208,7 @@ type DeliveryStepAccept = StepAsk type RecheckAccept = StepAsk // InstallAccept is the body of install. -type InstallAccept = InstallAsk +type InstallAccept = StepAsk // StepEndedEvent is the body of the event step-ended. type StepEndedEvent = StepEnded @@ -1274,6 +1297,15 @@ func DecodeStepsAnswer(raw []byte) (StepsAnswer, int, error) { return v, formRead(raw), nil } +// DecodeAnswerAnswer reads a AnswerAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780). +func DecodeAnswerAnswer(raw []byte) (AnswerAnswer, int, error) { + var v AnswerAnswer + if err := json.Unmarshal(raw, &v); err != nil { + return v, 0, err + } + return v, formRead(raw), nil +} + // DecodeOutputAnswer reads a OutputAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780). func DecodeOutputAnswer(raw []byte) (OutputAnswer, int, error) { var v OutputAnswer diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go index 3ce1d185d..a55579a37 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go @@ -19,7 +19,7 @@ func TestFixtures(t *testing.T) { }{ {name: "a unit step ended passed on its node, with its counts and what it carried", subject: "mesh.seat.node-build-node.event.step-ended.anchor", given: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"carried\":[{\"digest\":\"sha256:bbbb\",\"level\":\"unit\",\"package\":\"./modules/nats/a\"}],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"ended\":\"2026-11-10T10:02:00Z\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5e\",\"kept\":[{\"digest\":\"sha256:cccc\",\"level\":\"unit\",\"package\":\"./modules/nats/b\"}],\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"started\":\"2026-11-10T10:00:00Z\",\"step\":\"unit\",\"tests\":{\"unit\":14},\"v\":1}", wire: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"carried\":[{\"digest\":\"sha256:bbbb\",\"level\":\"unit\",\"package\":\"./modules/nats/a\"}],\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"ended\":\"2026-11-10T10:02:00Z\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5e\",\"kept\":[{\"digest\":\"sha256:cccc\",\"level\":\"unit\",\"package\":\"./modules/nats/b\"}],\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"started\":\"2026-11-10T10:00:00Z\",\"step\":\"unit\",\"tests\":{\"unit\":14},\"v\":1}", decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.event\\.step-ended\\.[^.*> ]+$")}, - {name: "an integration step that could not run, naming the part not heard", subject: "mesh.seat.node-build-node.event.step-ended.home-server", given: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"output-object\":\"mesh-build-go_sent-objects/m2kx9a1b3c4d5f\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", wire: "{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"output-object\":\"mesh-build-go_sent-objects/m2kx9a1b3c4d5f\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", + {name: "an integration step that could not run, naming the part not heard", subject: "mesh.seat.node-build-node.event.step-ended.home-server", given: "{\"answer-object\":\"answer.m2kx9a1b3c4d5f\",\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", wire: "{\"answer-object\":\"answer.m2kx9a1b3c4d5f\",\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5f\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-10T10:02:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d5f\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"could not run\",\"pipeline\":\"main.12.nats\",\"said\":\"the sandbox could not fetch novox/mesh-sdk\",\"step\":\"integration\",\"v\":1}", decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.event\\.step-ended\\.[^.*> ]+$")}, {name: "a node's toolchain reported", subject: "mesh.seat.node-build-node.event.toolchain-reported.anchor", given: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"language\":\"go\",\"node\":\"anchor\",\"recipe\":\"1\",\"version\":\"1.26.0\"}", wire: "{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"language\":\"go\",\"node\":\"anchor\",\"recipe\":\"1\",\"version\":\"1.26.0\"}", decode: func(b []byte) (any, error) { var v ToolchainReportedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.event\\.toolchain-reported\\.[^.*> ]+$")}, @@ -87,9 +87,9 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a check's step whose answer is kept as an object (G A-290)", subject: "", given: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", + {name: "a check's step whose answer is kept as an object (G A-290)", subject: "", given: "{\"answer-object\":\"answer.c3d4e5f6a7b8c9\",\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"answer-object\":\"answer.c3d4e5f6a7b8c9\",\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"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: "an install ask names the module's package lock at the commit", subject: "mesh.seat.node-build-node.accept.install", given: "{\"asker\":\"mesh-delivery-pipeline\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"id\":\"m2kx9a1b3c4d61\",\"lock\":\"{\\\"name\\\":\\\"mesh-forge\\\",\\\"lockfileVersion\\\":3,\\\"packages\\\":{}}\",\"module\":\"mesh-forge\",\"pipeline\":\"main.12.mesh-forge\"}", wire: "{\"asker\":\"mesh-delivery-pipeline\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"id\":\"m2kx9a1b3c4d61\",\"lock\":\"{\\\"name\\\":\\\"mesh-forge\\\",\\\"lockfileVersion\\\":3,\\\"packages\\\":{}}\",\"module\":\"mesh-forge\",\"pipeline\":\"main.12.mesh-forge\"}", + {name: "an install ask is a StepAsk of the kind install naming the module's package lock at the commit (H-A-403)", subject: "mesh.seat.node-build-node.accept.install", given: "{\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-22T00:56:00Z\",\"id\":\"m2kx9a1b3c4d61\",\"install\":{\"asker\":\"mesh-delivery-pipeline\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d61\",\"lock\":\"{\\\"name\\\":\\\"mesh-forge\\\",\\\"lockfileVersion\\\":3,\\\"packages\\\":{}}\",\"module\":\"mesh-forge\",\"pipeline\":\"main.12.mesh-forge\"},\"kind\":\"install\",\"language\":\"node\",\"v\":1,\"version\":\"0.1.4\"}", wire: "{\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-22T00:56:00Z\",\"id\":\"m2kx9a1b3c4d61\",\"install\":{\"asker\":\"mesh-delivery-pipeline\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d61\",\"lock\":\"{\\\"name\\\":\\\"mesh-forge\\\",\\\"lockfileVersion\\\":3,\\\"packages\\\":{}}\",\"module\":\"mesh-forge\",\"pipeline\":\"main.12.mesh-forge\"},\"kind\":\"install\",\"language\":\"node\",\"v\":1,\"version\":\"0.1.4\"}", decode: func(b []byte) (any, error) { var v InstallAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.accept\\.install$")}, {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}, @@ -115,6 +115,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "steps answers a drop that the hand-act log refused", subject: "", given: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", wire: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "answer asks a step's kept end by its ask, naming the call of its chunks", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", + decode: func(b []byte) (any, error) { var v AnswerInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "answer answers how many chunks carry the kept end", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", + decode: func(b []byte) (any, error) { var v AnswerAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "output asks a step's output by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\"}", decode: func(b []byte) (any, error) { var v OutputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "output answers the last 64 KB, the size and the failing tests with their words", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", diff --git a/modules/mesh-delivery-contracts/parts/build-step.json b/modules/mesh-delivery-contracts/parts/build-step.json index 15d99a353..a93030f8f 100644 --- a/modules/mesh-delivery-contracts/parts/build-step.json +++ b/modules/mesh-delivery-contracts/parts/build-step.json @@ -262,6 +262,49 @@ }, "class": "act" }, + { + "name": "answer", + "class": "read", + "description": "A step's answer by its ask, when the step's key or a run's step-ended names it as `answer-object` because the answer is over what the steps state's value or the event carries (design 47 H2 H-A-412): the kept end's bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the answer is of any size. An answer inline in the key or the event is never asked here; a run's test output is the verb output's.", + "input": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id, the `answer-object` of its step key or its step-ended naming it", + "minLength": 1 + }, + "call": { + "type": "string", + "description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements", + "minLength": 1 + } + }, + "required": [ + "ask", + "call" + ] + }, + "answer": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id" + }, + "chunks": { + "type": "integer", + "minimum": 0, + "description": "how many chunks are sent; 0 when this node keeps no answer of that ask" + } + }, + "required": [ + "ask", + "chunks" + ] + }, + "chunks": true + }, { "name": "output", "class": "read", @@ -326,7 +369,7 @@ }, "kind": { "type": "string", - "description": "build, check, compose or step" + "description": "build, check, compose, step or install" }, "language": { "type": "string", @@ -471,6 +514,10 @@ "step": { "$ref": "#/defs/StepRun", "description": "a pipeline step: lint, unit tests or integration tests of one artifact at one commit, sent by the runner as the accepted kind step (design 47 *The steps and who serves them*)" + }, + "install": { + "$ref": "#/defs/InstallAsk", + "description": "the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version" } }, "required": [ @@ -707,9 +754,9 @@ "result": { "$ref": "#/defs/StepResult" }, - "output-object": { + "answer-object": { "type": "string", - "description": "the name of the object in the build module's outputs store that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb output" + "description": "the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer" }, "what": { "type": "string" @@ -1604,7 +1651,7 @@ }, "archive": { "type": "string", - "description": "the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800)" + "description": "the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2))" } }, "required": [ @@ -1700,9 +1747,9 @@ "type": "string", "description": "the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254)" }, - "output-object": { + "answer-object": { "type": "string", - "description": "the name of the object that holds the run's answer, kept by the build seat's holder, when the answer is over what the event carries (design 47 G A-254); read through the verb output" + "description": "the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer" }, "rerun": { "type": "boolean" @@ -1733,7 +1780,7 @@ }, "archive": { "type": "string", - "description": "for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800)" + "description": "for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2))" } }, "required": [ @@ -1950,7 +1997,7 @@ }, "InstallAsk": { "type": "object", - "description": "an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest", + "description": "the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers", "properties": { "id": { "type": "string", @@ -1971,6 +2018,10 @@ "type": "string", "description": "the commit the lock is read at" }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint at the commit" + }, "lock": { "type": "string", "description": "the package lock's text at the commit" @@ -1982,6 +2033,7 @@ "pipeline", "module", "commit", + "fingerprint", "lock" ] } diff --git a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/events.json b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/events.json index 23456255e..a874e9bd9 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/events.json @@ -56,7 +56,7 @@ "node": "home-server", "outcome": "could not run", "said": "the sandbox could not fetch novox/mesh-sdk", - "output-object": "mesh-build-go_sent-objects/m2kx9a1b3c4d5f", + "answer-object": "answer.m2kx9a1b3c4d5f", "at": "2026-11-10T10:02:00Z" } }, diff --git a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/states.json b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/states.json index e18506ba8..393f6081f 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/states.json +++ b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/states.json @@ -555,7 +555,7 @@ "state": "passed", "started": "2026-11-05T10:00:00Z", "ended": "2026-11-05T10:05:00Z", - "output-object": "output.c3d4e5f6a7b8c9" + "answer-object": "answer.c3d4e5f6a7b8c9" } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json index cd999db56..ff85c1731 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json @@ -125,6 +125,22 @@ "error": "the hand-act log refused: nothing was deleted" } }, + { + "name": "answer asks a step's kept end by its ask, naming the call of its chunks", + "of": "verb:answer.input", + "given": { + "ask": "m2kx9a1b3c4d5f", + "call": "0123456789abcdef0123456789abcdef" + } + }, + { + "name": "answer answers how many chunks carry the kept end", + "of": "verb:answer.answer", + "given": { + "ask": "m2kx9a1b3c4d5f", + "chunks": 3 + } + }, { "name": "output asks a step's output by its ask", "of": "verb:output.input", diff --git a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/events.json b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/events.json index b3022da17..beb81c309 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/events.json @@ -39,7 +39,7 @@ "node": "home-server", "outcome": "could not run", "said": "the sandbox could not fetch novox/mesh-sdk", - "output-object": "mesh-build-go_sent-objects/m2kx9a1b3c4d5f", + "answer-object": "answer.m2kx9a1b3c4d5f", "at": "2026-11-10T10:02:00Z" } }, diff --git a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/states.json b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/states.json index e350a8bc6..35a482ce5 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/states.json +++ b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/states.json @@ -215,7 +215,7 @@ "state": "passed", "started": "2026-11-05T10:00:00Z", "ended": "2026-11-05T10:05:00Z", - "output-object": "output.c3d4e5f6a7b8c9" + "answer-object": "answer.c3d4e5f6a7b8c9" } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json index cd999db56..ff85c1731 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json @@ -125,6 +125,22 @@ "error": "the hand-act log refused: nothing was deleted" } }, + { + "name": "answer asks a step's kept end by its ask, naming the call of its chunks", + "of": "verb:answer.input", + "given": { + "ask": "m2kx9a1b3c4d5f", + "call": "0123456789abcdef0123456789abcdef" + } + }, + { + "name": "answer answers how many chunks carry the kept end", + "of": "verb:answer.answer", + "given": { + "ask": "m2kx9a1b3c4d5f", + "chunks": 3 + } + }, { "name": "output asks a step's output by its ask", "of": "verb:output.input", diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json index 68de83c59..8525beb23 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json @@ -56,7 +56,7 @@ "node": "home-server", "outcome": "could not run", "said": "the sandbox could not fetch novox/mesh-sdk", - "output-object": "mesh-build-go_sent-objects/m2kx9a1b3c4d5f", + "answer-object": "answer.m2kx9a1b3c4d5f", "at": "2026-11-10T10:02:00Z" } }, diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json index 9e6a0e660..a15867145 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json @@ -312,20 +312,30 @@ "state": "passed", "started": "2026-11-05T10:00:00Z", "ended": "2026-11-05T10:05:00Z", - "output-object": "output.c3d4e5f6a7b8c9" + "answer-object": "answer.c3d4e5f6a7b8c9" } }, { - "name": "an install ask names the module's package lock at the commit", + "name": "an install ask is a StepAsk of the kind install naming the module's package lock at the commit (H-A-403)", "of": "accept:install", "subject": "mesh.seat.node-build-node.accept.install", "given": { + "v": 1, "id": "m2kx9a1b3c4d61", + "kind": "install", + "language": "node", "asker": "mesh-delivery-pipeline", - "pipeline": "main.12.mesh-forge", - "module": "mesh-forge", - "commit": "0123456789abcdef0123456789abcdef01234567", - "lock": "{\"name\":\"mesh-forge\",\"lockfileVersion\":3,\"packages\":{}}" + "at": "2026-11-22T00:56:00Z", + "version": "0.1.4", + "install": { + "id": "m2kx9a1b3c4d61", + "asker": "mesh-delivery-pipeline", + "pipeline": "main.12.mesh-forge", + "module": "mesh-forge", + "commit": "0123456789abcdef0123456789abcdef01234567", + "fingerprint": "fp-0123", + "lock": "{\"name\":\"mesh-forge\",\"lockfileVersion\":3,\"packages\":{}}" + } } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json index cd999db56..ff85c1731 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json @@ -125,6 +125,22 @@ "error": "the hand-act log refused: nothing was deleted" } }, + { + "name": "answer asks a step's kept end by its ask, naming the call of its chunks", + "of": "verb:answer.input", + "given": { + "ask": "m2kx9a1b3c4d5f", + "call": "0123456789abcdef0123456789abcdef" + } + }, + { + "name": "answer answers how many chunks carry the kept end", + "of": "verb:answer.answer", + "given": { + "ask": "m2kx9a1b3c4d5f", + "chunks": 3 + } + }, { "name": "output asks a step's output by its ask", "of": "verb:output.input", diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/seat.json b/modules/mesh-delivery-contracts/seats/node-build-node/seat.json index 3b62223b0..b49cbaa98 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/seat.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/seat.json @@ -49,7 +49,7 @@ { "name": "install", "body": { - "$ref": "#/defs/InstallAsk" + "$ref": "#/defs/StepAsk" } } ], diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts index 7fc49e132..039d741d0 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts @@ -13,6 +13,7 @@ export declare const verbs: { readonly drop: "drop"; readonly keptArtifact: "kept-artifact"; readonly steps: "steps"; + readonly answer: "answer"; readonly output: "output"; }; @@ -115,6 +116,8 @@ export declare function detectedStepsByModuleArtifactKey(module: string, artifac /** The parts of a key of the form ".", or undefined for a key of another form. */ export declare function parseDetectedStepsByModuleArtifactKey(_key: string): { module: string; artifact: string } | undefined; +export type AnswerAnswer = buildStep.AnswerAnswer; +export type AnswerInput = buildStep.AnswerInput; export type AskArtifact = buildStep.AskArtifact; export type AskTaken = buildStep.AskTaken; export type AskTakenEvent = buildStep.AskTakenEvent; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.js b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.js index f9118fb5c..8b89fb011 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.js @@ -11,6 +11,7 @@ export const verbs = { drop: "drop", keptArtifact: "kept-artifact", steps: "steps", + answer: "answer", output: "output", }; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts index 54c748d85..079836868 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts @@ -9,6 +9,7 @@ export declare const verbs: { readonly drop: "drop"; readonly keptArtifact: "kept-artifact"; readonly steps: "steps"; + readonly answer: "answer"; readonly output: "output"; }; @@ -214,12 +215,14 @@ export interface FetchRefusal { "reason": string; } -/** an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest */ +/** the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers */ export interface InstallAsk { /** who asked it */ "asker": string; /** the commit the lock is read at */ "commit": string; + /** the module's build-input fingerprint at the commit */ + "fingerprint": string; /** the ask's id */ "id": string; /** the package lock's text at the commit */ @@ -373,12 +376,12 @@ export interface RunProgram { export interface Step { /** when the bus gives the ask again, for the state again (RFC 3339 time) */ "again-at"?: string; + /** the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer */ + "answer-object"?: string; /** when (RFC 3339 time) */ "ended"?: string; "id": string; "node": string; - /** the name of the object in the build module's outputs store that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb output */ - "output-object"?: string; "owner"?: string; /** true when the step ended on a fault that passes (a transport fault), so a failed end after the last run says so */ "passing"?: boolean; @@ -441,7 +444,9 @@ export interface StepAsk { "check"?: StepAskCheck; "compose"?: StepAskCompose; "id": string; - /** build, check, compose or step */ + /** the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version */ + "install"?: InstallAsk; + /** build, check, compose, step or install */ "kind": string; /** go, typescript or image */ "language": string; @@ -460,7 +465,9 @@ export interface StepAsk { /** an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548) */ export interface StepEnded { - /** for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) */ + /** the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer */ + "answer-object"?: string; + /** for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2)) */ "archive"?: string; "artifact"?: string; /** the ask's id, by which a reader takes only its own asks */ @@ -491,8 +498,6 @@ export interface StepEnded { "outcome": "passed" | "failed" | "nothing to run" | "could not run"; /** the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) */ "output"?: string; - /** the name of the object that holds the run's answer, kept by the build seat's holder, when the answer is over what the event carries (design 47 G A-254); read through the verb output */ - "output-object"?: string; "pipeline"?: string; "rerun"?: boolean; /** why it failed or could not run, naming the part not heard */ @@ -544,7 +549,7 @@ export interface StepResult { /** one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip */ export interface StepRun { - /** the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) */ + /** the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2)) */ "archive"?: string; /** the artifact reference, : */ "artifact": string; @@ -739,6 +744,24 @@ export interface StepsAnswer { "steps"?: DetectedStep[]; } +/** is what answer takes. */ +export interface AnswerInput { + /** the ask's id, the `answer-object` of its step key or its step-ended naming it */ + "ask": string; + /** 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements */ + "call": string; +} + +/** is what answer answers. */ +export interface AnswerAnswer { + /** the ask's id */ + "ask": string; + /** how many chunks are sent; 0 when this node keeps no answer of that ask */ + "chunks": number; + /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ + "form"?: number; +} + /** is what output takes. */ export interface OutputInput { /** the ask's id */ diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.js b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.js index 2d91b9b63..b9d7f08fd 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.js +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.js @@ -9,6 +9,7 @@ export const verbs = { drop: "drop", keptArtifact: "kept-artifact", steps: "steps", + answer: "answer", output: "output", }; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts index dd2aece20..4ef94e064 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts @@ -13,6 +13,7 @@ export declare const verbs: { readonly drop: "drop"; readonly keptArtifact: "kept-artifact"; readonly steps: "steps"; + readonly answer: "answer"; readonly output: "output"; }; @@ -112,6 +113,8 @@ export declare function detectedStepsByModuleArtifactKey(module: string, artifac /** The parts of a key of the form ".", or undefined for a key of another form. */ export declare function parseDetectedStepsByModuleArtifactKey(_key: string): { module: string; artifact: string } | undefined; +export type AnswerAnswer = buildStep.AnswerAnswer; +export type AnswerInput = buildStep.AnswerInput; export type AskArtifact = buildStep.AskArtifact; export type AskTaken = buildStep.AskTaken; export type AskTakenEvent = buildStep.AskTakenEvent; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.js b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.js index 869093bcc..5c4dfbc7b 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.js @@ -11,6 +11,7 @@ export const verbs = { drop: "drop", keptArtifact: "kept-artifact", steps: "steps", + answer: "answer", output: "output", }; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts index 54c748d85..079836868 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts @@ -9,6 +9,7 @@ export declare const verbs: { readonly drop: "drop"; readonly keptArtifact: "kept-artifact"; readonly steps: "steps"; + readonly answer: "answer"; readonly output: "output"; }; @@ -214,12 +215,14 @@ export interface FetchRefusal { "reason": string; } -/** an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest */ +/** the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers */ export interface InstallAsk { /** who asked it */ "asker": string; /** the commit the lock is read at */ "commit": string; + /** the module's build-input fingerprint at the commit */ + "fingerprint": string; /** the ask's id */ "id": string; /** the package lock's text at the commit */ @@ -373,12 +376,12 @@ export interface RunProgram { export interface Step { /** when the bus gives the ask again, for the state again (RFC 3339 time) */ "again-at"?: string; + /** the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer */ + "answer-object"?: string; /** when (RFC 3339 time) */ "ended"?: string; "id": string; "node": string; - /** the name of the object in the build module's outputs store that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb output */ - "output-object"?: string; "owner"?: string; /** true when the step ended on a fault that passes (a transport fault), so a failed end after the last run says so */ "passing"?: boolean; @@ -441,7 +444,9 @@ export interface StepAsk { "check"?: StepAskCheck; "compose"?: StepAskCompose; "id": string; - /** build, check, compose or step */ + /** the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version */ + "install"?: InstallAsk; + /** build, check, compose, step or install */ "kind": string; /** go, typescript or image */ "language": string; @@ -460,7 +465,9 @@ export interface StepAsk { /** an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548) */ export interface StepEnded { - /** for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) */ + /** the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer */ + "answer-object"?: string; + /** for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2)) */ "archive"?: string; "artifact"?: string; /** the ask's id, by which a reader takes only its own asks */ @@ -491,8 +498,6 @@ export interface StepEnded { "outcome": "passed" | "failed" | "nothing to run" | "could not run"; /** the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) */ "output"?: string; - /** the name of the object that holds the run's answer, kept by the build seat's holder, when the answer is over what the event carries (design 47 G A-254); read through the verb output */ - "output-object"?: string; "pipeline"?: string; "rerun"?: boolean; /** why it failed or could not run, naming the part not heard */ @@ -544,7 +549,7 @@ export interface StepResult { /** one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip */ export interface StepRun { - /** the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) */ + /** the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2)) */ "archive"?: string; /** the artifact reference, : */ "artifact": string; @@ -739,6 +744,24 @@ export interface StepsAnswer { "steps"?: DetectedStep[]; } +/** is what answer takes. */ +export interface AnswerInput { + /** the ask's id, the `answer-object` of its step key or its step-ended naming it */ + "ask": string; + /** 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements */ + "call": string; +} + +/** is what answer answers. */ +export interface AnswerAnswer { + /** the ask's id */ + "ask": string; + /** how many chunks are sent; 0 when this node keeps no answer of that ask */ + "chunks": number; + /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ + "form"?: number; +} + /** is what output takes. */ export interface OutputInput { /** the ask's id */ diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.js b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.js index 2d91b9b63..b9d7f08fd 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.js +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.js @@ -9,6 +9,7 @@ export const verbs = { drop: "drop", keptArtifact: "kept-artifact", steps: "steps", + answer: "answer", output: "output", }; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts index e66be3015..fe5f6f723 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts @@ -13,6 +13,7 @@ export declare const verbs: { readonly drop: "drop"; readonly keptArtifact: "kept-artifact"; readonly steps: "steps"; + readonly answer: "answer"; readonly output: "output"; }; @@ -115,6 +116,8 @@ export declare function detectedStepsByModuleArtifactKey(module: string, artifac /** The parts of a key of the form ".", or undefined for a key of another form. */ export declare function parseDetectedStepsByModuleArtifactKey(_key: string): { module: string; artifact: string } | undefined; +export type AnswerAnswer = buildStep.AnswerAnswer; +export type AnswerInput = buildStep.AnswerInput; export type AskArtifact = buildStep.AskArtifact; export type AskTaken = buildStep.AskTaken; export type AskTakenEvent = buildStep.AskTakenEvent; @@ -201,7 +204,7 @@ export type DeliveryStepAccept = StepAsk; export type RecheckAccept = StepAsk; /** is the body of install. */ -export type InstallAccept = InstallAsk; +export type InstallAccept = StepAsk; /** is one value of the state steps under the key ... */ export type StepsByAskerNodeIDValue = Step; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js index 52c7ee72d..d8e6a1fe3 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js @@ -11,6 +11,7 @@ export const verbs = { drop: "drop", keptArtifact: "kept-artifact", steps: "steps", + answer: "answer", output: "output", }; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts index 54c748d85..079836868 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts @@ -9,6 +9,7 @@ export declare const verbs: { readonly drop: "drop"; readonly keptArtifact: "kept-artifact"; readonly steps: "steps"; + readonly answer: "answer"; readonly output: "output"; }; @@ -214,12 +215,14 @@ export interface FetchRefusal { "reason": string; } -/** an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest */ +/** the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers */ export interface InstallAsk { /** who asked it */ "asker": string; /** the commit the lock is read at */ "commit": string; + /** the module's build-input fingerprint at the commit */ + "fingerprint": string; /** the ask's id */ "id": string; /** the package lock's text at the commit */ @@ -373,12 +376,12 @@ export interface RunProgram { export interface Step { /** when the bus gives the ask again, for the state again (RFC 3339 time) */ "again-at"?: string; + /** the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer */ + "answer-object"?: string; /** when (RFC 3339 time) */ "ended"?: string; "id": string; "node": string; - /** the name of the object in the build module's outputs store that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb output */ - "output-object"?: string; "owner"?: string; /** true when the step ended on a fault that passes (a transport fault), so a failed end after the last run says so */ "passing"?: boolean; @@ -441,7 +444,9 @@ export interface StepAsk { "check"?: StepAskCheck; "compose"?: StepAskCompose; "id": string; - /** build, check, compose or step */ + /** the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version */ + "install"?: InstallAsk; + /** build, check, compose, step or install */ "kind": string; /** go, typescript or image */ "language": string; @@ -460,7 +465,9 @@ export interface StepAsk { /** an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548) */ export interface StepEnded { - /** for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) */ + /** the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer */ + "answer-object"?: string; + /** for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2)) */ "archive"?: string; "artifact"?: string; /** the ask's id, by which a reader takes only its own asks */ @@ -491,8 +498,6 @@ export interface StepEnded { "outcome": "passed" | "failed" | "nothing to run" | "could not run"; /** the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) */ "output"?: string; - /** the name of the object that holds the run's answer, kept by the build seat's holder, when the answer is over what the event carries (design 47 G A-254); read through the verb output */ - "output-object"?: string; "pipeline"?: string; "rerun"?: boolean; /** why it failed or could not run, naming the part not heard */ @@ -544,7 +549,7 @@ export interface StepResult { /** one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip */ export interface StepRun { - /** the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) */ + /** the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2)) */ "archive"?: string; /** the artifact reference, : */ "artifact": string; @@ -739,6 +744,24 @@ export interface StepsAnswer { "steps"?: DetectedStep[]; } +/** is what answer takes. */ +export interface AnswerInput { + /** the ask's id, the `answer-object` of its step key or its step-ended naming it */ + "ask": string; + /** 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements */ + "call": string; +} + +/** is what answer answers. */ +export interface AnswerAnswer { + /** the ask's id */ + "ask": string; + /** how many chunks are sent; 0 when this node keeps no answer of that ask */ + "chunks": number; + /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ + "form"?: number; +} + /** is what output takes. */ export interface OutputInput { /** the ask's id */ diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.js b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.js index 2d91b9b63..b9d7f08fd 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.js +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.js @@ -9,6 +9,7 @@ export const verbs = { drop: "drop", keptArtifact: "kept-artifact", steps: "steps", + answer: "answer", output: "output", }; diff --git a/modules/mesh-delivery-sdk/buildstep/ask.go b/modules/mesh-delivery-sdk/buildstep/ask.go index 2e256a6fa..23ca15d49 100644 --- a/modules/mesh-delivery-sdk/buildstep/ask.go +++ b/modules/mesh-delivery-sdk/buildstep/ask.go @@ -31,6 +31,9 @@ const ( // AskStep is a pipeline step the runner sends (novox/hq design 47 *The steps and who serves them*: the accepted kind // step on the stream check, after delivery and before recheck). AskStep = "step" + // AskInstall is the Node build seat's install of a module's npm tree (design 47 H2 §800, H-A-403): its own queue on + // node-build-node alone, the Go and image build seats never install. + AskInstall = "install" ) // AskKinds are the queues of a build seat, in the order a holder pulls them (ADR 0536 §4): delivery, check and recheck, @@ -39,7 +42,16 @@ const ( var AskKinds = []string{AskDelivery, AskCheck, AskRecheck} // askBodyKinds are the kinds an ask's body names: a queue's, or step. -var askBodyKinds = []string{AskDelivery, AskCheck, AskStep, AskRecheck} +var askBodyKinds = []string{AskDelivery, AskCheck, AskStep, AskRecheck, AskInstall} + +// AskQueues are the queues a language's build seat pulls, in the order its holder pulls them: AskKinds, and install on +// node-build-node alone (H-A-403). +func AskQueues(language string) []string { + if language == AskNode { + return append(slices.Clone(AskKinds), AskInstall) + } + return AskKinds +} // The languages of the build seats: each is one build module's (mesh-build-) and one seat's // (node-build-). @@ -105,14 +117,14 @@ const ( func checkAskKind(kind string) error { if !slices.Contains(askBodyKinds, kind) { - return fmt.Errorf("buildstep: the ask kind %q is not delivery, check, step or recheck", kind) + return fmt.Errorf("buildstep: the ask kind %q is not delivery, check, step, recheck or install", kind) } return nil } -func checkAskQueue(queue string) error { - if !slices.Contains(AskKinds, queue) { - return fmt.Errorf("buildstep: the queue %q is not delivery, check or recheck", queue) +func checkAskQueue(language, queue string) error { + if !slices.Contains(AskQueues(language), queue) { + return fmt.Errorf("buildstep: the queue %q is not one of %s's (%s)", queue, language, strings.Join(AskQueues(language), ", ")) } return nil } @@ -152,7 +164,7 @@ func AskSubject(language, queue string) (string, error) { if err != nil { return "", err } - if err := checkAskQueue(queue); err != nil { + if err := checkAskQueue(language, queue); err != nil { return "", err } return "mesh.seat." + seat + ".accept." + queue, nil @@ -209,7 +221,7 @@ func AskWorker(language, kind string) (string, error) { if err != nil { return "", err } - if err := checkAskQueue(kind); err != nil { + if err := checkAskQueue(language, kind); err != nil { return "", err } return stream + "_" + strings.ToUpper(kind) + "_worker", nil @@ -280,6 +292,10 @@ type StepAsk struct { // Step is a pipeline step the runner sends as the accepted kind step (novox/hq ADR 0666 §7): lint or tests of one // artifact. Step *StepRun `json:"step,omitempty"` + // Install is the install job the runner sends as the accepted kind install of node-build-node (design 47 H2 §800, + // H-A-403): the module's npm tree its package lock names, published as the module's archive :node-modules + // under the ask's Version. + Install *InstallAsk `json:"install,omitempty"` // Needs are what a check's tests need of the holder's node (CheckNeed); a holder lacking one declines the ask. Needs []string `json:"needs,omitempty"` // Packages pin the mesh packages a build or a check builds against. @@ -373,6 +389,10 @@ type CheckJob struct { // Toolchain is the toolchain the checker agreed for the language (ADR 0584 clause 2): a holder whose node reports // another version declines the check. Toolchain *ToolchainUsed `json:"toolchain,omitempty"` + // Archive is the install archive a pipeline step's ask names (StepRun.Archive, design 47 H2 §800), which the step run + // hands each test call as its argument archive for the build module to unpack into the workspace. A check ask names + // none, so it is no part of the ask's form. + Archive string `json:"-"` } // ComposeJob asks one compose-candidate build. @@ -464,14 +484,18 @@ func (a StepAsk) check() error { return fmt.Errorf("buildstep: the ask %s names no time", a.ID) } jobs := 0 - for _, set := range []bool{a.Build != nil, a.Check != nil, a.Compose != nil, a.Run != nil, a.Step != nil} { + for _, set := range []bool{a.Build != nil, a.Check != nil, a.Compose != nil, a.Run != nil, a.Step != nil, a.Install != nil} { if set { jobs++ } } switch { case jobs != 1: - return fmt.Errorf("buildstep: the ask %s holds a build, a check, a compose, a run or a step, exactly one", a.ID) + return fmt.Errorf("buildstep: the ask %s holds a build, a check, a compose, a run, a step or an install, exactly one", a.ID) + case (a.Install != nil) != (a.Kind == AskInstall): + return fmt.Errorf("buildstep: the ask %s is sent as %s and holds an install, or not: the accepted kind install carries an install alone", a.ID, a.Kind) + case a.Install != nil && a.Language != AskNode: + return fmt.Errorf("buildstep: the ask %s is an install of the %s seat: node-build-node alone installs (H-A-403)", a.ID, a.Language) case a.Compose != nil && (a.Kind != AskCheck || a.Language != AskGo): return fmt.Errorf("buildstep: the ask %s is a compose, which the Go seat's check stream alone carries", a.ID) case a.Run != nil && (a.Kind != AskCheck || a.Language != AskGo): @@ -508,6 +532,8 @@ func (a StepAsk) check() error { return a.Run.check(a.ID) case a.Step != nil: return a.Step.check(a.ID) + case a.Install != nil: + return a.Install.check(a) } return a.Check.check(a.ID) } diff --git a/modules/mesh-delivery-sdk/buildstep/ask_test.go b/modules/mesh-delivery-sdk/buildstep/ask_test.go index 7220baca4..f65616775 100644 --- a/modules/mesh-delivery-sdk/buildstep/ask_test.go +++ b/modules/mesh-delivery-sdk/buildstep/ask_test.go @@ -55,12 +55,20 @@ func stepAsk() StepAsk { Kept: []KeptResult{{Package: "./modules/nats/a", Digest: "sha256:bbbb", Level: StepUnit}}}} } +// installAsk is an install of the Node build seat (design 47 H2 §800, H-A-403). +func installAsk() StepAsk { + return StepAsk{ID: testAskID, Kind: AskInstall, Language: AskNode, Asker: "mesh-delivery-pipeline", Version: "0.1.4", + At: time.Date(2026, 11, 10, 10, 0, 0, 0, time.UTC), + Install: &InstallAsk{ID: testAskID, Asker: "mesh-delivery-pipeline", Pipeline: "main.12.gitea", Module: "gitea", Commit: testCommit, + Fingerprint: "fp-0123", Lock: `{"lockfileVersion":3}`}} +} + // The ask the three build seats share is one neutral form: it round-trips, and every ill-formed ask is refused, // naming what is wrong (the rules of the old delivery.StepAsk, now the shared runner's). func TestAskCheckAndRoundTrip(t *testing.T) { headless := runAsk() // a run whose program reads only its input names no head (design 47 G §712, A-238) headless.Run.Heads = nil - for _, a := range []StepAsk{goodBuild(), goodCheck(), runAsk(), headless, stepAsk()} { + for _, a := range []StepAsk{goodBuild(), goodCheck(), runAsk(), headless, stepAsk(), installAsk()} { raw, err := EncodeStepAsk(a) if err != nil { t.Fatal(err) @@ -123,7 +131,7 @@ func TestAskCheckAndRoundTrip(t *testing.T) { edit func(*StepAsk) want string }{ - {"run beside a check", func(a *StepAsk) { a.Check = goodCheck().Check }, "or a step, exactly one"}, + {"run beside a check", func(a *StepAsk) { a.Check = goodCheck().Check }, "exactly one"}, {"run on the delivery stream", func(a *StepAsk) { a.Kind = AskDelivery }, "is a run"}, {"run on the Node seat", func(a *StepAsk) { a.Language = AskNode }, "is a run"}, {"run at a short commit", func(a *StepAsk) { a.Run.Program.Commit = "0123456" }, "no full commit"}, @@ -166,6 +174,31 @@ func TestAskCheckAndRoundTrip(t *testing.T) { t.Errorf("%s: %v, want %q", c.name, err, c.want) } } + // H-A-403: an install is the accepted kind install of the Node seat alone, its job naming its ask, a pipeline, a module + // at a full commit and fingerprint and a lock, under the version its archive is published with. + for _, c := range []struct { + name string + edit func(*StepAsk) + want string + }{ + {"install on the Go seat", func(a *StepAsk) { a.Language = AskGo }, "node-build-node alone installs"}, + {"install sent as a check", func(a *StepAsk) { a.Kind = AskCheck }, "carries an install alone"}, + {"install beside a step", func(a *StepAsk) { a.Step = stepAsk().Step }, "exactly one"}, + {"install of another ask", func(a *StepAsk) { a.Install.ID = "m2kx9a1b3c4d5f" }, "not its ask's"}, + {"install with no version", func(a *StepAsk) { a.Version = "" }, "names no version"}, + {"install with no lock", func(a *StepAsk) { a.Install.Lock = " " }, "no package lock"}, + {"install with no fingerprint", func(a *StepAsk) { a.Install.Fingerprint = "" }, "no build-input fingerprint"}, + {"install at a branch", func(a *StepAsk) { a.Install.Commit = "main" }, "no full commit"}, + } { + a := installAsk() + c.edit(&a) + if _, err := EncodeStepAsk(a); err == nil || !strings.Contains(err.Error(), c.want) { + t.Errorf("%s: %v, want %q", c.name, err, c.want) + } + } + if e, err := EndOf(installAsk(), "ace", OutcomePassed); err != nil || e.Step != StepInstall || e.Module != "gitea" || e.Fingerprint != "fp-0123" { + t.Errorf("the install's end: %+v, %v", e, err) + } if a := stepAsk(); !a.Step.Skips("./modules/nats/a", "sha256:bbbb") || a.Step.Skips("./modules/nats/a", "sha256:cccc") { t.Error("a kept result skips its package at its digest and level only") } @@ -281,6 +314,13 @@ func TestAskSubjectsStreamsAndKeys(t *testing.T) { if got, _ := AskWorker(AskGo, AskCheck); got != "SEAT_NODE_BUILD_GO_CHECK_worker" { t.Errorf("worker %q", got) } + // H-A-403: install is a queue of node-build-node alone. + if got, err := AskWorker(AskNode, AskInstall); got != "SEAT_NODE_BUILD_NODE_INSTALL_worker" || err != nil { + t.Errorf("install worker %q %v", got, err) + } + if _, err := AskSubject(AskGo, AskInstall); err == nil { + t.Error("the Go seat has an install queue") + } if got, _ := AskStream(AskImage); got != "SEAT_NODE_BUILD_IMAGE" { t.Errorf("stream %q", got) } @@ -552,9 +592,6 @@ func TestTheThreeSeatsFixturesFitTheNeutralForms(t *testing.T) { for _, f := range fixtures { t.Run(seat+"/"+f.Name, func(t *testing.T) { switch { - case f.Of == "accept:install": - seen++ - strict(t, f.Given, &InstallAsk{}) case strings.HasPrefix(f.Of, "accept:"): seen++ strict(t, f.Given, &StepAsk{}) diff --git a/modules/mesh-delivery-sdk/buildstep/pipelinestep.go b/modules/mesh-delivery-sdk/buildstep/pipelinestep.go index ae45a6ea8..6c7413153 100644 --- a/modules/mesh-delivery-sdk/buildstep/pipelinestep.go +++ b/modules/mesh-delivery-sdk/buildstep/pipelinestep.go @@ -44,11 +44,12 @@ const StepEndedVersion = 1 // StepEndedInlineMost is the most bytes of a run's answer a step-ended carries inline as `output`: the bus's message limit // less the room its headers take and 16 KiB for the end's other fields. An answer over it is kept by the holder as an object, -// which `output-object` names and the seat's verb `output` answers (design 47 G A-254). +// which `answer-object` names and the seat's verb `answer` answers (design 47 G A-254, H2 H-A-412). const StepEndedInlineMost = (1 << 20) - (8 << 10) - (16 << 10) -// OutputObjectName is the name of the object a build seat's holder keeps a run's answer in, by the ask's id. -func OutputObjectName(ask string) string { return "output." + ask } +// AnswerObjectName is the name of the object a build seat's holder keeps a step's end over what its key or event carries +// in, by the ask's id, in its steps objects (design 47 H2 H-A-412 addendum). +func AnswerObjectName(ask string) string { return "answer." + ask } // KeptResult is a package's passing result at the digest of what its tests read (ADR 0666 §8). type KeptResult struct { @@ -80,8 +81,8 @@ type StepRun struct { Kept []KeptResult `json:"kept,omitempty"` Rerun bool `json:"rerun,omitempty"` By string `json:"by,omitempty"` - // Archive is the install archive object the Go build module unpacks into the workspace before the step (design 47 - // H2 §800). + // Archive is the reference of the install archive in the artifact store, which the Go build module fetches and + // unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2)). Archive string `json:"archive,omitempty"` } @@ -141,12 +142,12 @@ type StepEnded struct { Kept []KeptResult `json:"kept,omitempty"` Said string `json:"said,omitempty"` Output string `json:"output,omitempty"` - OutputObject string `json:"output-object,omitempty"` + AnswerObject string `json:"answer-object,omitempty"` // NotRun are the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 // §800). NotRun []NotRun `json:"not-run,omitempty"` - // Archive is, for an install, the name of the archive object in the holder's outputs that holds the installed tree - // (design 47 H2 §800). + // Archive is, for an install, the reference the installed tree's archive was published under in the artifact store + // (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2)). Archive string `json:"archive,omitempty"` Rerun bool `json:"rerun,omitempty"` By string `json:"by,omitempty"` @@ -155,27 +156,77 @@ type StepEnded struct { At time.Time `json:"at,omitzero"` } +// FailingTest is a failing test and its words, as a run's output names it (design 47 H2 §791). +type FailingTest struct { + Test string `json:"test"` + Words string `json:"words,omitempty"` +} + +// OutputAnswer is what a build seat's verb output answers (design 47 H2 §791, H-A-367 (1), H-A-412): the ask, the run's +// test output's last 64 KB, its whole size and the failing tests with their words, or NoLongerKept once the output is past +// the outputs objects' max-age. +type OutputAnswer struct { + Ask string `json:"ask"` + Output string `json:"output,omitempty"` + Size int `json:"size,omitempty"` + Failing []FailingTest `json:"failing,omitempty"` + NoLongerKept bool `json:"no-longer-kept,omitempty"` +} + // NotRun is a test that did not run and why (design 47 H2 §800). type NotRun struct { Test string `json:"test"` Reason string `json:"reason"` } -// InstallAsk is an ask of the kind install the seat node-build-node accepts (design 47 H2 §800): the npm tree a -// module's package lock names, kept as an archive in the holder's outputs under the lock's digest. +// InstallAsk is the job of an ask of the kind install the seat node-build-node accepts (design 47 H2 §800, H-A-403): the +// npm tree a module's package lock names, installed with no install scripts and published to the artifact store as the +// module's archive :node-modules under the ask's version, which the builder's reservation covers. type InstallAsk struct { ID string `json:"id"` Asker string `json:"asker"` Pipeline string `json:"pipeline"` Module string `json:"module"` Commit string `json:"commit"` + // Fingerprint is the module's build-input fingerprint at the commit (H-A-403). + Fingerprint string `json:"fingerprint"` // Lock is the package lock's text at the commit. Lock string `json:"lock"` } +// InstallArtifact is the artifact the install archive of module is published as (H-A-403): :node-modules. +func InstallArtifact(module string) string { return module + ":node-modules" } + +func (i InstallAsk) check(a StepAsk) error { + switch { + case i.ID != a.ID || i.Asker != a.Asker: + return fmt.Errorf("buildstep: the install ask %s names the id %q and the asker %q, not its ask's", a.ID, i.ID, i.Asker) + case i.Pipeline == "": + return fmt.Errorf("buildstep: the install ask %s names no pipeline", a.ID) + case !askCommitOK.MatchString(i.Commit): + return fmt.Errorf("buildstep: the install ask %s names no full commit (%q)", a.ID, i.Commit) + case i.Fingerprint == "": + return fmt.Errorf("buildstep: the install ask %s names no build-input fingerprint", a.ID) + case strings.TrimSpace(i.Lock) == "": + return fmt.Errorf("buildstep: the install ask %s holds no package lock", a.ID) + case a.Version == "": + return fmt.Errorf("buildstep: the install ask %s names no version, so its archive could be published under no reservation (H-A-373, H-A-403)", a.ID) + } + if err := meshkeys.CheckName("module", i.Module); err != nil { + return fmt.Errorf("the install ask %s: %w", a.ID, err) + } + return nil +} + // EndOf is the end of the step a holds, on node, with outcome: the ask's names copied, so the runner can match the ask, // the commit and the fingerprint (ADR 0666 §21). func EndOf(a StepAsk, node, outcome string) (StepEnded, error) { + if i := a.Install; i != nil { + // An install's end names its pipeline, the step install, its module, commit and fingerprint (H-A-379, H-A-403). + e := StepEnded{V: StepEndedVersion, ID: a.ID, Asker: a.Asker, Ask: a.ID, Pipeline: i.Pipeline, Step: StepInstall, Module: i.Module, + Commit: i.Commit, Fingerprint: i.Fingerprint, Node: node, Outcome: outcome} + return e, e.check() + } if a.Step == nil { return StepEnded{}, fmt.Errorf("buildstep: the ask %s is no pipeline step", a.ID) } @@ -192,7 +243,7 @@ func (e StepEnded) check() error { if err := checkNode(e.Node); err != nil { return err } - if e.Output != "" && e.OutputObject != "" { + if e.Output != "" && e.AnswerObject != "" { return fmt.Errorf("buildstep: the end of %s carries its answer inline and as an object", e.ID) } if e.Pipeline == "" { diff --git a/modules/mesh-delivery-sdk/buildstep/stepoutput.go b/modules/mesh-delivery-sdk/buildstep/stepoutput.go index 7145c121a..382975d1d 100644 --- a/modules/mesh-delivery-sdk/buildstep/stepoutput.go +++ b/modules/mesh-delivery-sdk/buildstep/stepoutput.go @@ -9,41 +9,46 @@ import ( "fmt" ) -// OutputVerb is the verb of a build seat that answers a step's answer kept as an object (design 47 G A-254, A-290). +// OutputVerb is the verb of a build seat that answers a run's test output kept in its outputs objects (design 47 H2 §791, +// H-A-367 (1), H-A-412): the output's last 64 KB, its size, the failing tests with their words, or no longer kept. const OutputVerb = "output" +// AnswerVerb is the verb of a build seat that answers, in chunks, a step's end kept as an object because it is over what the +// steps state's value or the event carries (design 47 G A-254, A-290; H2 H-A-412 addendum): the object `answer-object` names. +const AnswerVerb = "answer" + // AskVerb asks a seat verb as the runtime calls it (stdio.Ask): the key `seat:.[@]` and the body in, the // verb's answer out. A verb marked chunks is asked by the plain call, and the runtime hands the whole file in `file` (A-249). type AskVerb func(key string, body any) (json.RawMessage, error) // ReadOutput is the answer a build seat's step-ended carries (design 47 G A-254): its inline `output`, else the object -// `output-object` names, read through the verb `output` of the seat of language on the node that ran the ask. Every asker of a +// `answer-object` names, read through the verb `answer` of the seat of language on the node that ran the ask. Every asker of a // run reads the answer this way, whichever build seat ran it; none reads the seat's step state. func (e StepEnded) ReadOutput(language string, ask AskVerb) ([]byte, error) { - if e.OutputObject == "" { + if e.AnswerObject == "" { return []byte(e.Output), nil } - return readObject(language, e.Node, e.Ask, e.OutputObject, ask) + return readObject(language, e.Node, e.Ask, e.AnswerObject, ask) } // Whole is the step with its answer whole (design 47 G A-290): a step whose key names its answer as the object -// `output-object`, its value being over what the steps state holds, has it read through the verb `output` of the seat of +// `answer-object`, its value being over what the steps state holds, has it read through the verb `answer` of the seat of // language on the step's node, and put back where the key holds the answer itself: a run's (run true) as its run answer's // output, any other's as its result. A step whose key holds its answer is answered as it is. Every reader of a step's answer // reads it so, the checker and the builder alike (no step reads passed in one place and failed in another). func (s Step) Whole(language string, run bool, ask AskVerb) (Step, error) { - if s.OutputObject == "" { + if s.AnswerObject == "" { return s, nil } - body, err := readObject(language, s.Node, s.ID, s.OutputObject, ask) + body, err := readObject(language, s.Node, s.ID, s.AnswerObject, ask) if err != nil { return s, err } if !run { if !json.Valid(body) { - return s, fmt.Errorf("buildstep: the answer %s of the ask %s is not JSON", s.OutputObject, s.ID) + return s, fmt.Errorf("buildstep: the answer %s of the ask %s is not JSON", s.AnswerObject, s.ID) } - s.Result, s.OutputObject = json.RawMessage(body), "" + s.Result, s.AnswerObject = json.RawMessage(body), "" return s, nil } var answer RunAnswer @@ -55,26 +60,26 @@ func (s Step) Whole(language string, run bool, ask AskVerb) (Step, error) { answer.Output = json.RawMessage(body) raw, err := json.Marshal(answer) if err != nil { - return s, fmt.Errorf("buildstep: the run answer of the ask %s with its output %s: %w", s.ID, s.OutputObject, err) + return s, fmt.Errorf("buildstep: the run answer of the ask %s with its output %s: %w", s.ID, s.AnswerObject, err) } - s.Result, s.OutputObject = raw, "" + s.Result, s.AnswerObject = raw, "" return s, nil } -// readObject reads the object a build seat's holder on node keeps of the ask askID through the seat's verb `output`. +// readObject reads the object a build seat's holder on node keeps of the ask askID through the seat's verb `answer`. func readObject(language, node, askID, object string, ask AskVerb) ([]byte, error) { seat, err := BuildSeat(language) if err != nil { return nil, err } if ask == nil { - return nil, errors.New("buildstep: the answer is in the output object " + object + ", which this reader has no verb to read") + return nil, errors.New("buildstep: the answer is in the answer object " + object + ", which this reader has no verb to read") } var call [16]byte if _, err := rand.Read(call[:]); err != nil { return nil, err } - raw, err := ask("seat:"+seat+"."+OutputVerb+"@"+node, map[string]any{"ask": askID, "call": hex.EncodeToString(call[:])}) + raw, err := ask("seat:"+seat+"."+AnswerVerb+"@"+node, map[string]any{"ask": askID, "call": hex.EncodeToString(call[:])}) if err != nil { return nil, fmt.Errorf("buildstep: asking %s for the answer %s of the ask %s: %w", seat, object, askID, err) } @@ -84,10 +89,10 @@ func readObject(language, node, askID, object string, ask AskVerb) ([]byte, erro Chunks int `json:"chunks"` } if err := json.Unmarshal(raw, &got); err != nil { - return nil, fmt.Errorf("buildstep: the verb output of %s answered no answer for %s: %w", seat, askID, err) + return nil, fmt.Errorf("buildstep: the verb answer of %s answered no answer for %s: %w", seat, askID, err) } if got.Ask != askID { - return nil, fmt.Errorf("buildstep: the verb output of %s answered the ask %q, asked %s", seat, got.Ask, askID) + return nil, fmt.Errorf("buildstep: the verb answer of %s answered the ask %q, asked %s", seat, got.Ask, askID) } if got.File == "" { return nil, fmt.Errorf("buildstep: %s on %s keeps no answer of the ask %s", seat, node, askID) diff --git a/modules/mesh-delivery-sdk/buildstep/stepoutput_test.go b/modules/mesh-delivery-sdk/buildstep/stepoutput_test.go index b0b4f0375..98381b328 100644 --- a/modules/mesh-delivery-sdk/buildstep/stepoutput_test.go +++ b/modules/mesh-delivery-sdk/buildstep/stepoutput_test.go @@ -29,12 +29,12 @@ func TestStepEndedReadOutput(t *testing.T) { fail string }{ {name: "inline", end: StepEnded{Ask: ask, Node: "ace", Output: `{"a":1}`}, want: `{"a":1}`}, - {name: "an object is read through the verb on its node", end: StepEnded{Ask: ask, Node: "ace", OutputObject: OutputObjectName(ask)}, - ask: verb(`{"ask":"`+ask+`","file":"eyJhIjoxfQ=="}`, nil), want: `{"a":1}`, wantKey: "seat:node-build-go.output@ace"}, - {name: "no answer kept", end: StepEnded{Ask: ask, Node: "ace", OutputObject: "o"}, ask: verb(`{"ask":"`+ask+`","chunks":0}`, nil), fail: "keeps no answer"}, - {name: "another ask's answer", end: StepEnded{Ask: ask, Node: "ace", OutputObject: "o"}, ask: verb(`{"ask":"x","file":"e30="}`, nil), fail: "answered the ask"}, - {name: "the verb fails", end: StepEnded{Ask: ask, Node: "ace", OutputObject: "o"}, ask: verb(``, errors.New("no seat")), fail: "no seat"}, - {name: "no verb", end: StepEnded{Ask: ask, Node: "ace", OutputObject: "o"}, fail: "no verb"}, + {name: "an object is read through the verb on its node", end: StepEnded{Ask: ask, Node: "ace", AnswerObject: AnswerObjectName(ask)}, + ask: verb(`{"ask":"`+ask+`","file":"eyJhIjoxfQ=="}`, nil), want: `{"a":1}`, wantKey: "seat:node-build-go.answer@ace"}, + {name: "no answer kept", end: StepEnded{Ask: ask, Node: "ace", AnswerObject: "o"}, ask: verb(`{"ask":"`+ask+`","chunks":0}`, nil), fail: "keeps no answer"}, + {name: "another ask's answer", end: StepEnded{Ask: ask, Node: "ace", AnswerObject: "o"}, ask: verb(`{"ask":"x","file":"e30="}`, nil), fail: "answered the ask"}, + {name: "the verb fails", end: StepEnded{Ask: ask, Node: "ace", AnswerObject: "o"}, ask: verb(``, errors.New("no seat")), fail: "no seat"}, + {name: "no verb", end: StepEnded{Ask: ask, Node: "ace", AnswerObject: "o"}, fail: "no verb"}, } { t.Run(c.name, func(t *testing.T) { key, body = "", nil @@ -57,7 +57,7 @@ func TestStepEndedReadOutput(t *testing.T) { // A step-ended names its answer inline or as an object, never both. func TestStepEndedRefusesAnswerTwice(t *testing.T) { - e := StepEnded{ID: "m2kx9a1b3c4d5f", Ask: "m2kx9a1b3c4d5f", Asker: "a", Node: "ace", Outcome: OutcomePassed, Output: "1", OutputObject: "o"} + e := StepEnded{ID: "m2kx9a1b3c4d5f", Ask: "m2kx9a1b3c4d5f", Asker: "a", Node: "ace", Outcome: OutcomePassed, Output: "1", AnswerObject: "o"} if _, err := EncodeStepEnded(e); err == nil || !strings.Contains(err.Error(), "inline and as an object") { t.Fatalf("err %v", err) } @@ -75,7 +75,7 @@ func TestStepWholeReadsTheObjectItsKeyNames(t *testing.T) { } } b64 := func(s string) string { return base64.StdEncoding.EncodeToString([]byte(s)) } - named := Step{ID: ask, Node: "ace", State: StepPassed, OutputObject: OutputObjectName(ask)} + named := Step{ID: ask, Node: "ace", State: StepPassed, AnswerObject: AnswerObjectName(ask)} for _, c := range []struct { name string step Step @@ -100,10 +100,10 @@ func TestStepWholeReadsTheObjectItsKeyNames(t *testing.T) { } return } - if err != nil || string(got.Result) != c.want || got.OutputObject != "" { - t.Fatalf("got %s (object %q), %v; want %s", got.Result, got.OutputObject, err, c.want) + if err != nil || string(got.Result) != c.want || got.AnswerObject != "" { + t.Fatalf("got %s (object %q), %v; want %s", got.Result, got.AnswerObject, err, c.want) } - if c.ask != nil && key != "seat:node-build-go.output@ace" { + if c.ask != nil && key != "seat:node-build-go.answer@ace" { t.Fatalf("asked %q", key) } }) diff --git a/modules/mesh-delivery-sdk/buildstep/steps.go b/modules/mesh-delivery-sdk/buildstep/steps.go index 33a4fa3a9..2f718f2c9 100644 --- a/modules/mesh-delivery-sdk/buildstep/steps.go +++ b/modules/mesh-delivery-sdk/buildstep/steps.go @@ -49,11 +49,11 @@ type Step struct { Ended time.Time `json:"ended,omitzero"` Reason string `json:"reason,omitempty"` Result json.RawMessage `json:"result,omitempty"` - // OutputObject names the object in the build module's outputs store (OutputObjectName) that holds the step's answer - // when the whole value would be over what the steps state holds (design 47 G A-290): a check's whole answer, Result - // then empty; a run's output, Result the run's answer without it. A reader reads the answer through the seat's verb - // output (Step.Answer). - OutputObject string `json:"output-object,omitempty"` + // AnswerObject names the object in the build module's steps objects (AnswerObjectName) that holds the step's answer + // when the whole value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole + // answer, Result then empty; a run's output, Result the run's answer without it. A reader reads the answer through the + // seat's verb answer (Step.Whole). + AnswerObject string `json:"answer-object,omitempty"` What string `json:"what,omitempty"` Phase string `json:"phase,omitempty"` PhaseAt time.Time `json:"phase-at,omitzero"` diff --git a/modules/mesh-delivery-sdk/steprun/askrun.go b/modules/mesh-delivery-sdk/steprun/askrun.go index 74577abd8..c37dae07d 100644 --- a/modules/mesh-delivery-sdk/steprun/askrun.go +++ b/modules/mesh-delivery-sdk/steprun/askrun.go @@ -48,6 +48,11 @@ type AskSteps struct { // Has says whether this node has a need a package's tests declare (sdkstep.AskNeeds, issue 890); a package needing // what it lacks is not tested here but named in the level's Unmet, for the asker to place. Nil has nothing. Has func(need string) bool + // Install is the Node build module's install body for an install ask (design 47 H2 §800, H-A-403): it takes the + // module, commit, fingerprint, pipeline, the package lock's text, the artifact :node-modules and the ask's + // version, installs the tree with no install scripts, publishes its archive to the artifact store under that version and + // answers {"archive": }. Nil ends every install ask could not run. + Install StepFunc // Lint is the module's lint body for a pipeline step lint (novox/hq ADR 0666 §7): it takes the workspace and the // module's directory and answers a LintAnswer. Nil ends every lint step as nothing to run. Lint StepFunc @@ -55,6 +60,9 @@ type AskSteps struct { // event step-ended on that node's subject (sdkstep.StepEndedSubject), under the ask's id. Nil runs no step ask. Node string SayStep func(end sdkstep.StepEnded) error + // Outputs are the holder's outputs objects (OutputsStore), where a test step keeps its run's output as `.` (design 47 H2 §791, H-A-412), which the seat's verb output reads (OutputTool). Nil keeps none, said in the journal. + Outputs OutputObjects } // A-489b (G-22-lead-answers-2.md): SaysItsEnds is nil when these steps can be asked a pipeline step and say its end: a node to name in the end and a SayStep to @@ -78,7 +86,7 @@ func RunAsk(ctx context.Context, steps AskSteps, ask sdkstep.StepAsk) (any, erro job.Fetch = withPackages(job.Fetch, ask.Packages) return steps.build(ctx, job, ask.Version) } - if ask.Step != nil { + if ask.Step != nil || ask.Install != nil { return steps.runStep(ctx, ask) } if ask.Check != nil { @@ -314,6 +322,13 @@ func (s AskSteps) build(ctx context.Context, job sdkstep.BuildJob, version strin } func (s AskSteps) check(ctx context.Context, job sdkstep.CheckJob) (any, error) { + return s.checkTexts(ctx, job, nil) +} + +// checkTexts is check, the text of each level's test answers (their member `output`) taken out of them and written to +// text, nil dropping it (design 47 H2 H-A-412 third addendum): a run's text is a test step's output alone, kept in the +// outputs objects, and a check ask's answer keeps none. +func (s AskSteps) checkTexts(ctx context.Context, job sdkstep.CheckJob, text *strings.Builder) (any, error) { if _, err := s.onToolchain(ctx, job.Toolchain); err != nil { return nil, err } @@ -340,7 +355,7 @@ func (s AskSteps) check(ctx context.Context, job sdkstep.CheckJob) (any, error) // 2026-11-02: "A failed check shows only its first fault"). for _, level := range job.Levels { la := sdkstep.LevelAnswer{Level: level} - _, err := s.level(ctx, job, level, f, runner, &la) + _, err := s.level(ctx, job, level, f, runner, &la, text) answer.Levels = append(answer.Levels, la) if err != nil { // The fetch merged: its answer is kept on the failed step's end, so the checker previews the merge and judges its @@ -352,7 +367,7 @@ func (s AskSteps) check(ctx context.Context, job sdkstep.CheckJob) (any, error) } // level runs one level of a check ask and says whether it passed. -func (s AskSteps) level(ctx context.Context, job sdkstep.CheckJob, level string, f fetched, runner string, la *sdkstep.LevelAnswer) (bool, error) { +func (s AskSteps) level(ctx context.Context, job sdkstep.CheckJob, level string, f fetched, runner string, la *sdkstep.LevelAnswer, text *strings.Builder) (bool, error) { withRunner := func(args map[string]any) map[string]any { if runner != "" { args["runner"] = runner @@ -360,6 +375,9 @@ func (s AskSteps) level(ctx context.Context, job sdkstep.CheckJob, level string, if len(job.NodeNames) > 0 { args[sdkstep.NodeNamesArg] = job.NodeNames // the names check's (ADR 0567 §12) } + if job.Archive != "" { + args["archive"] = job.Archive // the install archive the build module unpacks (design 47 H2 §800) + } return args } test := func(args map[string]any) (bool, error) { @@ -378,6 +396,7 @@ func (s AskSteps) level(ctx context.Context, job sdkstep.CheckJob, level string, if err != nil { return false, err } + r = takeText(r, text) la.Tests = append(la.Tests, r) var t struct { Passed bool `json:"passed"` @@ -604,3 +623,25 @@ func changesTestIn(changed []string, dir string) bool { } return false } + +// takeText is a test answer without its member `output`, the level's text, which it writes to text (nil drops it): design 47 +// H2 H-A-412 third addendum. An answer with no text, or that is no object, is answered as it is. +func takeText(r json.RawMessage, text *strings.Builder) json.RawMessage { + var m map[string]json.RawMessage + if json.Unmarshal(r, &m) != nil { + return r + } + out, ok := m["output"] + if !ok { + return r + } + var t string + if json.Unmarshal(out, &t) == nil && text != nil { + text.WriteString(t) + } + delete(m, "output") + if stripped, err := json.Marshal(m); err == nil { + return stripped + } + return r +} diff --git a/modules/mesh-delivery-sdk/steprun/askrun_test.go b/modules/mesh-delivery-sdk/steprun/askrun_test.go index f868984f2..5201560d8 100644 --- a/modules/mesh-delivery-sdk/steprun/askrun_test.go +++ b/modules/mesh-delivery-sdk/steprun/askrun_test.go @@ -210,6 +210,17 @@ test {"level":"integration","packages":["x/pkg/a"],"workspace":"/w"}` t.Fatalf("a level that errors: answer %+v, err %v; want the fetch and the unit level beside the error", out, err) } + // Design 47 H2 H-A-412 third addendum: a check ask's answer keeps none of the level's text, its test answers' `output`. + steps = r.steps() + steps.Test = func(context.Context, map[string]any) (any, error) { + return map[string]any{"passed": true, "tests": 1, "output": "=== RUN TestA\n--- PASS: TestA\n"}, nil + } + out, err = RunAsk(context.Background(), steps, ask(sdkstep.CheckJob{Levels: []string{sdkstep.LevelUnit}, Fetch: sdkstep.Fetch{Repository: "novox/x", Commit: runCommit}})) + if lv := out.(sdkstep.CheckAnswer).Levels; err != nil || len(lv) != 1 || len(lv[0].Tests) == 0 || strings.Contains(string(lv[0].Tests[0]), "output") || + !strings.Contains(string(lv[0].Tests[0]), `"passed":true`) { + t.Fatalf("a check's answer %+v, %v; want its test answers without their text", out, err) + } + // ADR 0567 §12: a check's node names reach the digest and test tools, for the names check (a kept verdict misses when // they change). r.calls = nil @@ -418,6 +429,13 @@ func TestASeatsAskTypeRunsAsTheNeutralAsk(t *testing.T) { // runs its one level as a check of it, carries the packages the runner kept at their digest, keeps what it passed, says // its counts, and says its end once on its own node; a level with no tests ends nothing to run, a fault of the source // could not run, and a transport fault or an end that could not be said is handed back unsaid, to be given again. +// installOf is an install ask of the Node seat (H-A-403). +func installOf() sdkstep.StepAsk { + id := sdkstep.NewID() + return sdkstep.StepAsk{ID: id, Kind: sdkstep.AskInstall, Language: sdkstep.AskNode, Asker: "mesh-delivery-pipeline", At: time.Now(), Version: "0.1.4", + Install: &sdkstep.InstallAsk{ID: id, Asker: "mesh-delivery-pipeline", Pipeline: "main.12.m", Module: "m", Commit: runCommit, Fingerprint: "fp-1", Lock: "{}"}} +} + func TestRunAskRunsAPipelineStepAndSaysItsEnd(t *testing.T) { type said struct{ ends []sdkstep.StepEnded } stepOf := func(step string, kept ...sdkstep.KeptResult) sdkstep.StepAsk { @@ -439,6 +457,15 @@ func TestRunAskRunsAPipelineStepAndSaysItsEnd(t *testing.T) { kept []string passing bool // the error is a transport fault noTests bool // the level holds no test, as the test body says it + test map[string]any + run int // which run of the ask this is (the step's Run), 0 outside a puller + notRun []sdkstep.NotRun + saidOpen string // the end's said opens with these words + archive string // the step's install archive, which every test call names + install StepFunc + arch string // the archive the end names + text string // the run's output kept as . (design 47 H2 §791), "" for none checked + failing []sdkstep.FailingTest }{ {name: "unit: the kept package carried, the other tested and kept", ask: stepOf(sdkstep.StepUnit, sdkstep.KeptResult{Package: "x/a", Digest: "d-a", Level: "unit"}), digests: map[string]string{"x/a": "d-a", "x/b": "d-b"}, tests: map[string]bool{"x/b": true}, outcome: sdkstep.OutcomePassed, counts: 1, carried: []string{"x/a"}, kept: []string{"x/b"}}, @@ -453,18 +480,64 @@ func TestRunAskRunsAPipelineStepAndSaysItsEnd(t *testing.T) { {name: "the source cannot be fetched: could not run", ask: stepOf(sdkstep.StepUnit), fetchErr: Refuse("no commit %s", runCommit), outcome: sdkstep.OutcomeCouldNotRun}, {name: "a transport fault: unsaid, given again", ask: stepOf(sdkstep.StepUnit), fetchErr: &sdkstep.Passing{Err: errors.New("no responders")}, passing: true}, {name: "the end cannot be said: given again", ask: stepOf(sdkstep.StepLint), sayErr: errors.New("bus down"), passing: true}, + // Design 47 H2 §800: the tests that did not run are carried into the end, the level passing. + {name: "not run: passed, listed", ask: stepOf(sdkstep.StepUnit), digests: map[string]string{"x/b": "d-b"}, outcome: sdkstep.OutcomePassed, counts: 2, kept: []string{"x/b"}, + test: map[string]any{"passed": true, "tests": 2, "not-run": []sdkstep.NotRun{{Test: "x/b TestBwrap", Reason: "no bwrap"}}}, + notRun: []sdkstep.NotRun{{Test: "x/b TestBwrap", Reason: "no bwrap"}}}, + // §800, H-A-368: a starved setup runs again; its third run ends could not run, never failed. + {name: "a starved setup: given again", ask: stepOf(sdkstep.StepIntegration), digests: map[string]string{"x/b": "d-b"}, run: 2, passing: true, + test: map[string]any{"passed": false, "tests": 1, "bound": 600, "failed": []sdkstep.Failure{{Package: "x/b", Test: "TestT", Cause: "mesh: setup starved: a bus for this test did not come up within 5m0s"}}}}, + {name: "a starved setup's third run: could not run", ask: stepOf(sdkstep.StepIntegration), digests: map[string]string{"x/b": "d-b"}, run: 3, outcome: sdkstep.OutcomeCouldNotRun, + test: map[string]any{"passed": false, "tests": 1, "bound": 600, "failed": []sdkstep.Failure{{Package: "x/b", Test: "TestT", Cause: "mesh: setup starved: a bus for this test did not come up within 5m0s"}}}, + saidOpen: "the bus did not answer in setup within 5m0s under load"}, + {name: "a starved setup beside an assertion: failed", ask: stepOf(sdkstep.StepIntegration), digests: map[string]string{"x/b": "d-b"}, run: 1, outcome: sdkstep.OutcomeFailed, counts: 2, + test: map[string]any{"passed": false, "tests": 2, "why": "2 failed", "failed": []sdkstep.Failure{{Package: "x/b", Test: "TestT", Cause: "mesh: setup starved: words"}, {Package: "x/b", Test: "TestU", Cause: "got 1, want 2"}}}}, + // §791, H-A-412: the level's text is kept as the run's output ., its header naming the failing tests. + {name: "failed with its text: the output kept with its failing tests", ask: stepOf(sdkstep.StepUnit), digests: map[string]string{"x/b": "d-b"}, outcome: sdkstep.OutcomeFailed, counts: 1, + test: map[string]any{"passed": false, "tests": 1, "why": "1 failed", "output": "--- FAIL: TestU\n u_test.go:9: got 1, want 2\n", + "failed": []sdkstep.Failure{{Package: "x/b", Test: "TestU", Cause: "u_test.go:9: got 1, want 2"}}}, + text: "--- FAIL: TestU\n u_test.go:9: got 1, want 2\n", failing: []sdkstep.FailingTest{{Test: "x/b TestU", Words: "u_test.go:9: got 1, want 2"}}}, + // §800: the install archive the step names reaches the test calls, for the build module to unpack. + {name: "integration with an install archive: the test calls name it", ask: stepOf(sdkstep.StepIntegration), digests: map[string]string{"x/b": "d-b"}, tests: map[string]bool{"x/b": true}, + outcome: sdkstep.OutcomePassed, counts: 1, kept: []string{"x/b"}, archive: "oci-artifact-registry://gitea/npm-tree:0.1.4"}, + // H-A-403, H-A-399 (2): an install publishes its archive under the ask's version and its end names the reference. + {name: "install: passed, naming its archive", ask: installOf(), outcome: sdkstep.OutcomePassed, arch: "oci-artifact-registry://m/node-modules:0.1.4", + install: func(_ context.Context, args map[string]any) (any, error) { + if args["artifact"] != "m:node-modules" || args["version"] != "0.1.4" || args["lock"] != "{}" { + return nil, fmt.Errorf("the install was asked %v", args) + } + return map[string]any{"archive": "oci-artifact-registry://m/node-modules:0.1.4"}, nil + }}, + {name: "install answering no archive: could not run", ask: installOf(), outcome: sdkstep.OutcomeCouldNotRun, saidOpen: "the install answered no archive", + install: func(context.Context, map[string]any) (any, error) { return map[string]any{}, nil }}, + {name: "install with no install body: could not run", ask: installOf(), outcome: sdkstep.OutcomeCouldNotRun, saidOpen: "this build module installs nothing"}, + // §799: a fetch met away on the third run ends the step failed with its why. + {name: "a fetch fault's third run: failed, fetch:", ask: stepOf(sdkstep.StepUnit), run: 3, outcome: sdkstep.OutcomeFailed, + fetchErr: &sdkstep.Passing{Err: errors.New("fetch: git fetch: status 502")}, saidOpen: "fetch: git fetch"}, } { r := &recorder{fetch: map[string]any{"workspace": "/w"}, tests: row.tests, digests: row.digests} s := r.steps() if row.fetchErr != nil { s.Fetch = func(context.Context, map[string]any) (any, error) { return nil, row.fetchErr } } - s.Lint, s.Node = row.lint, "ace" + s.Lint, s.Node, s.Install = row.lint, "ace", row.install + outputs := fakeOutputs{m: map[string][]byte{}} + s.Outputs = outputs if row.noTests { s.Test = func(context.Context, map[string]any) (any, error) { return map[string]any{"passed": true, "tests": 0, "no_tests": true}, nil } } + if row.test != nil { + s.Test = func(context.Context, map[string]any) (any, error) { return row.test, nil } + } + if row.archive != "" { + row.ask.Step.Archive = row.archive + } + ctx := context.Background() + if row.run > 0 { + ctx = context.WithValue(ctx, phaseKey{}, &phases{step: sdkstep.Step{Run: row.run}}) + } var got said s.SayStep = func(e sdkstep.StepEnded) error { if row.sayErr != nil { @@ -473,7 +546,7 @@ func TestRunAskRunsAPipelineStepAndSaysItsEnd(t *testing.T) { got.ends = append(got.ends, e) return nil } - out, err := RunAsk(context.Background(), s, row.ask) + out, err := RunAsk(ctx, s, row.ask) if row.passing { if !sdkstep.IsPassing(err) || len(got.ends) != 0 { t.Errorf("%s: %v, said %+v; want a transport fault, nothing said", row.name, err, got.ends) @@ -510,6 +583,23 @@ func TestRunAskRunsAPipelineStepAndSaysItsEnd(t *testing.T) { if _, err := sdkstep.EncodeStepEnded(e); err != nil { t.Errorf("%s: the end does not encode: %v", row.name, err) } + for _, c := range r.calls { + if strings.HasPrefix(c, "test ") && row.archive != "" && !strings.Contains(c, `"archive":"`+row.archive+`"`) { + t.Errorf("%s: the test call %s names no archive %s", row.name, c, row.archive) + } + } + if e.Archive != row.arch { + t.Errorf("%s: the end names the archive %q, want %q", row.name, e.Archive, row.arch) + } + if !slices.Equal(e.NotRun, row.notRun) || !strings.HasPrefix(e.Said, row.saidOpen) { + t.Errorf("%s: not run %+v said %q, want %+v and said opening %q", row.name, e.NotRun, e.Said, row.notRun, row.saidOpen) + } + if row.text != "" { + o, err := readOutput(outputs, "ace", row.ask.ID, nil) + if err != nil || o.Output != row.text || o.Size != len(row.text) || !slices.Equal(o.Failing, row.failing) { + t.Errorf("%s: the output kept answers %+v, %v; want %q with its size and failing %+v", row.name, o, err, row.text, row.failing) + } + } } } diff --git a/modules/mesh-delivery-sdk/steprun/conformance/conformance.go b/modules/mesh-delivery-sdk/steprun/conformance/conformance.go index e3f8ade3c..17f9d6110 100644 --- a/modules/mesh-delivery-sdk/steprun/conformance/conformance.go +++ b/modules/mesh-delivery-sdk/steprun/conformance/conformance.go @@ -6,7 +6,7 @@ // // A catalogue check (mesh-catalog checks/failurekit) refuses a build module with a test step whose tests do not call Run, // and any build module whose tests do not call LeftRunning, the kit's case of steps a previous process left running -// (leftrunning.go, issue 1890). +// (leftrunning.go, issue 1890). SeatVerbs (forms.go) is the case of the build-step part's form 2 (design 47 H2, H-A-421). package conformance import ( @@ -284,13 +284,26 @@ func judgePassing(c PassingCase, failed Failed) string { // A-489b: StepEnds is the case every build module runs on the steps it asks with: a pipeline step ask must be able to say its end // (steprun.AskSteps.SaysItsEnds), or the module would refuse every step ask the runner sends, as mesh-build-node did on its // first live pipeline (design 47 G §24). A catalogue check (failurekit) refuses a build module whose tests do not call it. +// +// H-A-421 (i): the steps must also keep a run's output (AskSteps.Outputs, design 47 H2 §791), or every run's output is lost. func StepEnds(t *testing.T, steps steprun.AskSteps) { t.Helper() - if err := steps.SaysItsEnds(); err != nil { - t.Errorf("the build module's steps cannot say a step's end: %v", err) + for _, p := range stepEnds(steps) { + t.Error(p) } } +func stepEnds(steps steprun.AskSteps) []string { + var problems []string + if err := steps.SaysItsEnds(); err != nil { + problems = append(problems, fmt.Sprintf("the build module's steps cannot say a step's end: %v", err)) + } + if steps.Outputs == nil { + problems = append(problems, "the build module's steps keep no outputs (AskSteps.Outputs): a run's output is never kept in its outputs objects") + } + return problems +} + // A-489c: RunsCounted is the case every build module runs on its puller (A-489a): the poison rule and a transport fault's run count the // runs the module's steps state says started, so the puller is built with Prior over the module's own read of that state. The // module builds its puller with read as its steps state's read; a step key it holds with a started run must count as that run. diff --git a/modules/mesh-delivery-sdk/steprun/conformance/conformance_test.go b/modules/mesh-delivery-sdk/steprun/conformance/conformance_test.go index 51c33107c..d2c4c76a5 100644 --- a/modules/mesh-delivery-sdk/steprun/conformance/conformance_test.go +++ b/modules/mesh-delivery-sdk/steprun/conformance/conformance_test.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "errors" + "slices" "strings" "testing" "time" @@ -11,6 +12,8 @@ import ( buildrun "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildrun" sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep" "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun" + stdio "git.novox.be/novox/mesh-sdk/go" + "git.novox.be/novox/mesh-sdk/go/buscalls" ) // The failure contract (issue 1901): the SDK's own parsers keep it on every captured case of the kit (1901/AC6); the @@ -166,9 +169,14 @@ func TestTheFailureContract(t *testing.T) { t.Errorf("1901/AC4: failures = %+v, want the timeout's panic as the cause", got) } res := steprun.ReadGoTest(`{"Action":"run","Package":"m/a","Test":"TestA"} +{"Action":"output","Package":"m/a","Test":"TestA","Output":" a_test.go:41: NOT RUN: no bwrap installed where this check runs\n"} +{"Action":"output","Package":"m/a","Test":"TestA","Output":"--- SKIP: TestA (0.00s)\n"} {"Action":"skip","Package":"m/a","Test":"TestA","Elapsed":0} {"Action":"run","Package":"m/b","Test":"TestB"} {"Action":"pass","Package":"m/b","Test":"TestB","Elapsed":0} +{"Action":"run","Package":"m/b","Test":"TestC"} +{"Action":"output","Package":"m/b","Test":"TestC","Output":" b_test.go:7: short mode\n"} +{"Action":"skip","Package":"m/b","Test":"TestC","Elapsed":0} {"Action":"pass","Package":"m/a","Elapsed":0} {"Action":"pass","Package":"m/b","Elapsed":0} `, ".") @@ -176,8 +184,12 @@ func TestTheFailureContract(t *testing.T) { for _, p := range res.Packages { got[p.Package] = p.Skipped } - if res.Skipped != 1 || got["m/a"] != 1 || got["m/b"] != 0 { - t.Errorf("skipped = %d, per package %v, want 1 with m/a 1 and m/b 0", res.Skipped, got) + if res.Skipped != 2 || got["m/a"] != 1 || got["m/b"] != 1 { + t.Errorf("skipped = %d, per package %v, want 2 with m/a 1 and m/b 1", res.Skipped, got) + } + // Design 47 H2 §800: a skip whose words open "NOT RUN:" is a test not run, with its reason; another skip is none. + if want := []sdkstep.NotRun{{Test: "m/a TestA", Reason: "no bwrap installed where this check runs"}}; !slices.Equal(res.NotRun, want) { + t.Errorf("not run = %+v, want %+v", res.NotRun, want) } }) } @@ -194,7 +206,85 @@ func TestStepEndsRefusesStepsThatCannotSayTheirEnd(t *testing.T) { t.Errorf("%s: SaysItsEnds = %v, want refused %v", c.name, c.s.SaysItsEnds(), c.bad) } } - StepEnds(t, steprun.AskSteps{Node: "n", SayStep: say}) + StepEnds(t, steprun.AskSteps{Node: "n", SayStep: say, Outputs: kitObjects{}}) + if p := stepEnds(steprun.AskSteps{Node: "n", SayStep: say}); len(p) != 1 || !strings.Contains(p[0], "keep no outputs") { + t.Errorf("steps with no outputs: %q, want refused for it (H-A-421 (i))", p) + } + + // H-A-421: SeatVerbs passes the SDK's own seat tools and steps wired to one outputs store, and refuses each form missing. + wired := func(seat string, o steprun.OutputObjects, install bool) ([]stdio.Tool, steprun.AskSteps) { + p := &steprun.Puller{Node: "kitnode", Capacity: func() int { return 1 }} + steps := steprun.AskSteps{Node: "kitnode", SayStep: say, Outputs: o} + if install { + steps.Install = func(context.Context, map[string]any) (any, error) { return nil, errors.New("the module's own install") } + } + ended := func(string) (time.Time, bool, error) { return time.Time{}, false, nil } + tools := append(steprun.SeatTools(seat, "kit", p), steprun.OutputTool(seat, "kitnode", o, ended), steprun.AnswerTool(seat, steprun.ReadAnswerFrom(o))) + return tools, steps + } + for _, c := range []struct { + name, seat, problem string + install bool + change func(tools []stdio.Tool, steps *steprun.AskSteps) []stdio.Tool + }{ + {name: "the Go seat, wired", seat: "node-build-go"}, + {name: "the Node seat with its install, wired", seat: "node-build-node", install: true}, + {name: "an install on the Go seat", seat: "node-build-go", install: true, problem: "only node-build-node accepts the kind install"}, + {name: "no outputs", seat: "node-build-go", problem: "keep no outputs", change: func(tools []stdio.Tool, steps *steprun.AskSteps) []stdio.Tool { + steps.Outputs = nil + return tools + }}, + {name: "steps and output on two stores", seat: "node-build-go", problem: "want its output kept", change: func(tools []stdio.Tool, steps *steprun.AskSteps) []stdio.Tool { + steps.Outputs = kitObjects{} + return tools + }}, + {name: "output of form 1", seat: "node-build-go", problem: "want the ask alone", change: func(tools []stdio.Tool, _ *steprun.AskSteps) []stdio.Tool { + for i := range tools { + if tools[i].Name == "node-build-go.output" { + tools[i].Input = map[string]any{"required": []string{"ask", "call"}, "properties": map[string]any{"ask": nil, "call": nil}} + } + } + return tools + }}, + {name: "no answer verb", seat: "node-build-go", problem: "serve no node-build-go.answer", change: func(tools []stdio.Tool, _ *steprun.AskSteps) []stdio.Tool { + return slices.DeleteFunc(tools, func(t stdio.Tool) bool { return t.Name == "node-build-go.answer" }) + }}, + {name: "current of form 1", seat: "node-build-go", problem: "answers no takes", change: func(tools []stdio.Tool, _ *steprun.AskSteps) []stdio.Tool { + for i := range tools { + if tools[i].Name == "node-build-go.current" { + tools[i].Run = func(map[string]any) (any, error) { return map[string]any{"node": "kitnode", "capacity": 1}, nil } + } + } + return tools + }}, + } { + tools, steps := wired(c.seat, kitObjects{}, c.install) + if c.change != nil { + tools = c.change(tools, &steps) + } + p := JudgeSeatVerbs(c.seat, tools, steps) + if c.problem == "" && len(p) > 0 || c.problem != "" && !slices.ContainsFunc(p, func(s string) bool { return strings.Contains(s, c.problem) }) { + t.Errorf("%s: problems %q, want %q", c.name, p, c.problem) + } + } + tools, steps := wired("node-build-image", kitObjects{}, false) + SeatVerbs(t, "node-build-image", tools, steps) +} + +// kitObjects is an outputs store in memory; each value is its own store. +type kitObjects map[string][]byte + +func (k kitObjects) Put(name string, data []byte, _ string) (buscalls.ObjectInfo, error) { + k[name] = data + return buscalls.ObjectInfo{Name: name}, nil +} + +func (k kitObjects) Get(name string) (buscalls.ObjectData, error) { + d, ok := k[name] + if !ok { + return buscalls.ObjectData{}, errors.New("object not found") + } + return buscalls.ObjectData{Data: d}, nil } // A puller built without Prior, or with one that does not read the module's steps state, fails the case. diff --git a/modules/mesh-delivery-sdk/steprun/conformance/forms.go b/modules/mesh-delivery-sdk/steprun/conformance/forms.go new file mode 100644 index 000000000..81a09e079 --- /dev/null +++ b/modules/mesh-delivery-sdk/steprun/conformance/forms.go @@ -0,0 +1,212 @@ +package conformance + +import ( + "context" + "encoding/json" + "fmt" + "slices" + "testing" + "time" + + "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep" + "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/steprun" + stdio "git.novox.be/novox/mesh-sdk/go" +) + +// SeatVerbs is the case every build module runs on its seat tools and the steps it asks with (design 47 H2 §791, §800, +// §801; H-A-421): it judges the build-step part's form 2 as the module serves it. current answers the node, whether it +// takes asks, since when, its capacity and the asks it runs, each with its asker; output takes the ask alone and answers a +// run's output, or refuses an ask never run here; answer takes the ask and the call of its chunks. A pipeline step is run +// through steps, their fetch and test bodies stood in by the kit's (a test answer holding the level's text in `output`, a +// NOT RUN skip and a failure, the step 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 kept as `.` in the module's outputs objects, read back through +// its verb output. With steps.Install set (node-build-node alone), an install ask must end passed naming its archive, the +// install body stood in by the kit's. +func SeatVerbs(t *testing.T, seat string, tools []stdio.Tool, steps steprun.AskSteps) { + t.Helper() + for _, p := range JudgeSeatVerbs(seat, tools, steps) { + t.Error(p) + } +} + +// The kit's pipeline step: its text, its failure, its test not run and its archive. +const ( + kitText = "=== RUN TestKit\n kit_test.go:7: got 1, want 2\n--- FAIL: TestKit (0.00s)\n" + kitArchive = "oci-artifact-registry://kit/node-modules:0.1.1" + kitCommit = "0123456789abcdef0123456789abcdef01234567" +) + +var ( + kitNotRun = buildstep.NotRun{Test: "kit/m TestBwrap", Reason: "no bwrap where this check runs"} + kitFailure = buildstep.Failure{Package: "kit/m", Test: "TestKit", Cause: "kit_test.go:7: got 1, want 2"} +) + +// JudgeSeatVerbs is what SeatVerbs fails a build module for: nothing when its seat verbs and steps keep the part's form 2. +func JudgeSeatVerbs(seat string, tools []stdio.Tool, steps steprun.AskSteps) []string { + var problems []string + bad := func(format string, args ...any) { problems = append(problems, fmt.Sprintf(format, args...)) } + language, err := buildstep.AskLanguageOfSeat(seat) + if err != nil { + return []string{err.Error()} + } + tool := func(verb string) *stdio.Tool { + for i := range tools { + if tools[i].Name == seat+"."+verb { + return &tools[i] + } + } + bad("the seat tools serve no %s.%s", seat, verb) + return nil + } + current, output, answer := tool("current"), tool(buildstep.OutputVerb), tool(buildstep.AnswerVerb) + if current != nil { + problems = append(problems, judgeCurrent(*current, steps.Node)...) + } + if answer != nil && !slices.Equal(required(*answer), []string{"ask", "call"}) { + bad("%s.answer takes %v, want the ask and the call of its chunks", seat, required(*answer)) + } + if output != nil { + if req := required(*output); !slices.Equal(req, []string{"ask"}) || hasProperty(*output, "call") { + bad("%s.output takes %v, want the ask alone (form 2: no call, no chunks)", seat, req) + } + if got, err := output.Run(map[string]any{"ask": buildstep.NewID()}); err == nil { + bad("%s.output answers an ask never run here (%v), want it refused", seat, got) + } + } + if steps.Outputs == nil { + bad("the steps keep no outputs (AskSteps.Outputs): a run's output is never kept") + } + problems = append(problems, judgeStep(seat, language, steps, output)...) + if steps.Install != nil { + problems = append(problems, judgeInstall(seat, steps)...) + } + return problems +} + +// judgeCurrent runs current and judges its answer's form 2 fields. +func judgeCurrent(current stdio.Tool, node string) []string { + got, err := current.Run(map[string]any{}) + if err != nil { + return []string{fmt.Sprintf("%s: %v", current.Name, err)} + } + var c map[string]json.RawMessage + if raw, err := json.Marshal(got); err != nil || json.Unmarshal(raw, &c) != nil { + return []string{fmt.Sprintf("%s answers no object: %v", current.Name, got)} + } + var problems []string + for _, k := range []string{"node", "takes", "since", "capacity", "asks"} { + if _, ok := c[k]; !ok { + problems = append(problems, fmt.Sprintf("%s answers no %s (form 2): %v", current.Name, k, got)) + } + } + var n string + if json.Unmarshal(c["node"], &n); n != node { + problems = append(problems, fmt.Sprintf("%s names the node %q, want %q", current.Name, n, node)) + } + var asks []map[string]any + _ = json.Unmarshal(c["asks"], &asks) + for _, a := range asks { + if a["asker"] == nil { + problems = append(problems, fmt.Sprintf("%s answers an ask with no asker: %v", current.Name, a)) + } + } + return problems +} + +// judgeStep runs the kit's pipeline step through steps and judges its end and its kept output. +func judgeStep(seat, language string, steps steprun.AskSteps, output *stdio.Tool) []string { + var problems []string + bad := func(format string, args ...any) { problems = append(problems, fmt.Sprintf(format, args...)) } + var archives []any + var ends []buildstep.StepEnded + steps.Fetch = func(context.Context, map[string]any) (any, error) { + return map[string]any{"workspace": "/kit", "commit": kitCommit, "modules": []string{"modules/kit"}}, nil + } + steps.Digest, steps.Toolchain, steps.Kept, steps.Release, steps.Has = nil, nil, nil, nil, nil + steps.Test = func(_ context.Context, args map[string]any) (any, error) { + archives = append(archives, args["archive"]) + return map[string]any{"passed": false, "tests": 2, "why": "1 failed", "output": kitText, + "not-run": []buildstep.NotRun{kitNotRun}, "failed": []buildstep.Failure{kitFailure}}, nil + } + steps.SayStep = func(e buildstep.StepEnded) error { ends = append(ends, e); return nil } + id := buildstep.NewID() + ask := buildstep.StepAsk{ID: id, Kind: buildstep.AskStep, Language: language, Asker: "mesh-delivery-pipeline", At: time.Now(), + Step: &buildstep.StepRun{Pipeline: "main.1.kit", Step: buildstep.StepUnit, Module: "kit", Artifact: "kit:program", Commit: kitCommit, + Fingerprint: "fp-kit", Archive: kitArchive, Fetch: buildstep.Fetch{Repository: "novox/kit", Commit: kitCommit, Dir: "modules/kit"}}} + if _, err := steprun.RunAsk(context.Background(), steps, ask); err != nil { + return []string{fmt.Sprintf("the kit's pipeline step: %v", err)} + } + if len(ends) != 1 { + return []string{fmt.Sprintf("the kit's pipeline step said %d ends, want one", len(ends))} + } + e := ends[0] + if e.Outcome != buildstep.OutcomeFailed || !slices.Equal(e.NotRun, []buildstep.NotRun{kitNotRun}) { + bad("the kit's pipeline step ended %s with not-run %+v, want failed with %+v", e.Outcome, e.NotRun, kitNotRun) + } + if len(archives) == 0 || slices.ContainsFunc(archives, func(a any) bool { return a != kitArchive }) { + bad("the step's archive %s did not reach every test call: %v", kitArchive, archives) + } + if output == nil { + return problems + } + got, err := output.Run(map[string]any{"ask": id}) + raw, _ := json.Marshal(got) + var o buildstep.OutputAnswer + if err != nil || json.Unmarshal(raw, &o) != nil { + return append(problems, fmt.Sprintf("%s.output of the step run (%s): %v, %v; want its output kept as . in the outputs objects", seat, id, got, err)) + } + want := []buildstep.FailingTest{{Test: "kit/m TestKit", Words: kitFailure.Cause}} + if o.Ask != id || o.Output != kitText || o.Size != len(kitText) || !slices.Equal(o.Failing, want) || o.NoLongerKept { + bad("%s.output of the step run answers %+v, want the ask, its text, its size %d and failing %+v", seat, o, len(kitText), want) + } + return problems +} + +// judgeInstall runs an install ask through steps, the install body stood in by the kit's, and judges its end. +func judgeInstall(seat string, steps steprun.AskSteps) []string { + if seat != "node-build-node" { + return []string{fmt.Sprintf("%s installs (AskSteps.Install set): only node-build-node accepts the kind install", seat)} + } + var ends []buildstep.StepEnded + steps.Install = func(_ context.Context, args map[string]any) (any, error) { + if args["lock"] != "{}" || args["artifact"] != buildstep.InstallArtifact("kit") || args["version"] != "0.1.1" { + return nil, fmt.Errorf("the install was asked %v", args) + } + return map[string]any{"archive": kitArchive}, nil + } + steps.SayStep = func(e buildstep.StepEnded) error { ends = append(ends, e); return nil } + id := buildstep.NewID() + ask := buildstep.StepAsk{ID: id, Kind: buildstep.AskInstall, Language: buildstep.AskNode, Asker: "mesh-delivery-pipeline", At: time.Now(), Version: "0.1.1", + Install: &buildstep.InstallAsk{ID: id, Asker: "mesh-delivery-pipeline", Pipeline: "main.1.kit", Module: "kit", Commit: kitCommit, Fingerprint: "fp-kit", Lock: "{}"}} + if _, err := steprun.RunAsk(context.Background(), steps, ask); err != nil { + return []string{fmt.Sprintf("the kit's install: %v", err)} + } + if len(ends) != 1 || ends[0].Outcome != buildstep.OutcomePassed || ends[0].Archive != kitArchive { + return []string{fmt.Sprintf("the kit's install said %+v, want one end passed naming the archive %s", ends, kitArchive)} + } + return nil +} + +// required is the sorted names a tool's input requires. +func required(t stdio.Tool) []string { + var out []string + switch r := t.Input["required"].(type) { + case []string: + out = append(out, r...) + case []any: + for _, s := range r { + if s, ok := s.(string); ok { + out = append(out, s) + } + } + } + slices.Sort(out) + return out +} + +// hasProperty says whether a tool's input names the property name. +func hasProperty(t stdio.Tool, name string) bool { + props, _ := t.Input["properties"].(map[string]any) + _, ok := props[name] + return ok +} diff --git a/modules/mesh-delivery-sdk/steprun/gotest.go b/modules/mesh-delivery-sdk/steprun/gotest.go index cd6d3aaa7..45f4f2a6a 100644 --- a/modules/mesh-delivery-sdk/steprun/gotest.go +++ b/modules/mesh-delivery-sdk/steprun/gotest.go @@ -41,6 +41,9 @@ type GoTest struct { Skipped int Times []TestTime Failed []sdkstep.Failure + // NotRun are the skipped tests whose words open "NOT RUN:", each with its reason (design 47 H2 §800, H-A-294): a test + // lacking tooling its step does not give, counted apart from passed and failed. A skip with other words is none. + NotRun []sdkstep.NotRun // Elapsed is the slowest package's running time in seconds. Elapsed float64 // Noise is the lines that were no event: what go said when it could not run the tests at all. @@ -163,6 +166,9 @@ func (r *goReader) event(ev goEvent) { if ev.Action == "skip" { r.res.Skipped++ p.Skipped++ + if why, ok := notRunWords(r.testOut[key]); ok { + r.res.NotRun = append(r.res.NotRun, sdkstep.NotRun{Test: ev.Package + " " + ev.Test, Reason: why}) + } } r.res.Times = append(r.res.Times, TestTime{Package: ev.Package, Test: ev.Test, Elapsed: ev.Elapsed}) if ev.Action == "fail" { @@ -179,6 +185,19 @@ func (r *goReader) event(ev goEvent) { } } +// notRunOpens opens the words of a test that says it did not run (design 47 H2 §800): `t.Skip("NOT RUN: ")`. +const notRunOpens = "NOT RUN:" + +// notRunWords is the reason a skipped test's output gives after "NOT RUN:", the first such line's, and whether it said one. +func notRunWords(lines []string) (string, bool) { + for _, l := range lines { + if why, ok := strings.CutPrefix(goErrorWords(l), notRunOpens); ok { + return sdkstep.CutLine(strings.TrimSpace(why)), true + } + } + return "", false +} + // subtestFailed says a failure of test under pkg was already reported for one of its subtests (they end first), each with // a cause of its own, and the test reported no error and no runtime cause (a subtest's panic) of its own. func (r *goReader) subtestFailed(pkg, test string) bool { diff --git a/modules/mesh-delivery-sdk/steprun/narrate_test.go b/modules/mesh-delivery-sdk/steprun/narrate_test.go index a8c1500b2..b777b0857 100644 --- a/modules/mesh-delivery-sdk/steprun/narrate_test.go +++ b/modules/mesh-delivery-sdk/steprun/narrate_test.go @@ -15,13 +15,15 @@ import ( ) // CAT-NR1: a build's publish on a seat says asked, waiting on the seat (on every tick of NarrateEvery while the holder -// has not answered), and stored or refused, each as the ask's phase written to its running step key. +// has not answered), and stored or refused, each as the ask's phase written to its running step key. Design 47 H2 +// H-A-373: a Go package or a bundle with no version is refused before the seat is asked; an archive publishes by digest. func TestABuildNarratesItsPublishOnASeat(t *testing.T) { digest := "sha256:" + strings.Repeat("c", 64) for name, c := range map[string]struct { - answer error - ticks int - want []string + answer error + ticks int + seat, kind, version string + want []string }{ "stored": {want: []string{ "asked go-package-registry: publish of mod 1.2.3 at " + digest, @@ -34,6 +36,15 @@ func TestABuildNarratesItsPublishOnASeat(t *testing.T) { "waiting on go-package-registry: publish of mod 1.2.3 at " + digest + ", 5m0s since asked", "waiting on go-package-registry: publish of mod 1.2.3 at " + digest + ", 10m0s since asked", "stored on go-package-registry: publish of mod 1.2.3 at " + digest + " (0 of its 1 parts sent, the rest held)"}}, + "a Go package with no version, refused": {version: "-", answer: errors.New("never asked"), want: []string{ + "asked go-package-registry: publish of mod at " + digest, + "refused by go-package-registry: publish of mod at " + digest + ": go-package-registry's publish of mod (package) names no version: a Go package and every bundle publish under the version the ask reserved"}}, + "a Node bundle with no version, refused": {seat: NpmSeat, kind: "bundle", version: "-", answer: errors.New("never asked"), want: []string{ + "asked npm-package-registry: publish of mod at " + digest, + "refused by npm-package-registry: publish of mod at " + digest + ": npm-package-registry's publish of mod (bundle) names no version: a Go package and every bundle publish under the version the ask reserved"}}, + "an archive by its digest, stored": {seat: ArtifactSeat, kind: "archive", version: "-", want: []string{ + "asked oci-artifact-registry: publish of mod at " + digest, + "stored on oci-artifact-registry: publish of mod at " + digest + " (0 of its 1 parts sent, the rest held)"}}, } { t.Run(name, func(t *testing.T) { clock := time.Date(2026, 11, 4, 16, 0, 0, 0, time.UTC) @@ -72,7 +83,17 @@ func TestABuildNarratesItsPublishOnASeat(t *testing.T) { } ctx := context.WithValue(context.Background(), phaseKey{}, ph) done := make(chan error, 1) - go func() { done <- PublishOne(ctx, call, GoSeat, "mod", "package", "1.2.3", digest, "t", []byte("x")) }() + seat, kind, version := GoSeat, "package", "1.2.3" + if c.seat != "" { + seat = c.seat + } + if c.kind != "" { + kind = c.kind + } + if c.version == "-" { + version = "" + } + go func() { done <- PublishOne(ctx, call, seat, "mod", kind, version, digest, "t", []byte("x")) }() line := func() { select { case <-wrote: diff --git a/modules/mesh-delivery-sdk/steprun/outputs.go b/modules/mesh-delivery-sdk/steprun/outputs.go index f7e34988a..d7a4323cd 100644 --- a/modules/mesh-delivery-sdk/steprun/outputs.go +++ b/modules/mesh-delivery-sdk/steprun/outputs.go @@ -1,44 +1,172 @@ package steprun import ( + "bytes" + "encoding/json" + "errors" "fmt" + "time" + "unicode/utf8" + sdkstep "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/catalogue" ) -// OutputsStore is the local name of the object store a build seat's holder keeps a run's answer in when it is over what -// step-ended carries inline (design 47 G A-254): the steps state's own objects store, `steps-objects`, which the holder's manifest -// `requires` asks for with its steps state (design 47 G A-313). -var OutputsStore = catalogue.StateObjectsName("steps") +// OutputsStore is the local name of the object store a build seat's holder keeps a run's output in (design 47 H2 §791, +// §820): its `outputs` objects, which the holder's manifest `requires` with their cap and max-age, and which the seat's verb +// output reads (H-A-399 (1)). +const OutputsStore = "outputs" -// OutputObjects is the object store of OutputsStore as a holder uses it (mesh-sdk busstate.ObjectsOf(OutputsStore)). +// AnswersStore is the local name of the object store a build seat's holder keeps a step's end in when it is over what the +// steps state's value or step-ended carries (design 47 H2 H-A-412 addendum): the steps state's own objects store, +// `steps-objects`, which the holder's manifest `requires` with its steps state, and which the seat's verb answer reads. +var AnswersStore = catalogue.StateObjectsName("steps") + +// OutputObjects is an object store as a holder uses it (mesh-sdk busstate.ObjectsOf(OutputsStore), or of AnswersStore). type OutputObjects interface { Put(name string, data []byte, description string) (buscalls.ObjectInfo, error) Get(name string) (buscalls.ObjectData, error) } -// KeepOutputIn is a holder's Puller.KeepOutput over its store of outputs. -func KeepOutputIn(o OutputObjects) func(object string, body []byte) error { +// KeepAnswerIn is a holder's Puller.KeepAnswer over its store of answers (AnswersStore). +func KeepAnswerIn(o OutputObjects) func(object string, body []byte) error { return func(object string, body []byte) error { if o == nil { - return fmt.Errorf("this module keeps no %s store", OutputsStore) + return fmt.Errorf("this module keeps no %s store", AnswersStore) } - _, err := o.Put(object, body, "a run's answer, named by its step-ended") + _, err := o.Put(object, body, "a step's end over what its key or step-ended carries, named by it") return err } } -// ReadOutputFrom is a holder's read of a kept answer for OutputTool over its store of outputs. -func ReadOutputFrom(o OutputObjects) func(object string) ([]byte, error) { +// ReadAnswerFrom is a holder's read of a kept end for AnswerTool over its store of answers (AnswersStore). +func ReadAnswerFrom(o OutputObjects) func(object string) ([]byte, error) { return func(object string) ([]byte, error) { if o == nil { - return nil, fmt.Errorf("this module keeps no %s store", OutputsStore) + return nil, fmt.Errorf("this module keeps no %s store", AnswersStore) } got, err := o.Get(object) if err != nil { - return nil, fmt.Errorf("the answer %s in the %s store: %w", object, OutputsStore, err) + return nil, fmt.Errorf("the answer %s in the %s store: %w", object, AnswersStore, err) } return got.Data, nil } } + +// OutputsMaxAge is the outputs objects' max-age (design 47 H2 §820: 7 days), past which the bus removes a run's output and +// the verb output answers it no longer kept. +const OutputsMaxAge = 7 * 24 * time.Hour + +// OutputTail is how much of a run's output the verb output answers: its last 64 KB (design 47 H2 §791). +const OutputTail = 64 << 10 + +// outputHeader is the header a run's output object holds beside its text (design 47 H2 H-A-412 (1)): the text's size and the +// failing tests with their words taken from the level's results, so the verb output answers them without reading the text +// again. The object is the header's JSON on its first line, then the text. +type outputHeader struct { + Size int `json:"size"` + Failing []sdkstep.FailingTest `json:"failing,omitempty"` +} + +// keepOutput writes a run's test output as the object `.` in the outputs objects (design 47 H2 §791, +// H-A-412): the header of its size and failing tests, then the text. +func keepOutput(o OutputObjects, node, ask, text string, failing []sdkstep.FailingTest) error { + if o == nil { + return fmt.Errorf("this module keeps no %s store", OutputsStore) + } + name, err := sdkstep.StepKey(node, ask) + if err != nil { + return err + } + head, err := json.Marshal(outputHeader{Size: len(text), Failing: failing}) + if err != nil { + return err + } + _, err = o.Put(name, append(append(head, '\n'), text...), "a run's test output, named by its step key") + return err +} + +// EndedHere is the verb output's read of this node's steps state (design 47 H2 H-A-412 second addendum (b)): whether a key +// of keys holds the ask's step on node, and when it ended (zero while it runs). keys and get read the holder's steps state. +func EndedHere(node string, keys func() ([]string, error), get func(key string) (json.RawMessage, error)) func(ask string) (time.Time, bool, error) { + return func(ask string) (time.Time, bool, error) { + if keys == nil || get == nil { + return time.Time{}, false, errors.New("this module reads no steps state") + } + all, err := keys() + if err != nil { + return time.Time{}, false, fmt.Errorf("the steps state's keys: %w", err) + } + for _, k := range all { + if _, n, id, perr := sdkstep.ParseStepKey(k); perr != nil || n != node || id != ask { + continue + } + raw, err := get(k) + if err != nil { + return time.Time{}, false, fmt.Errorf("the step key %s: %w", k, err) + } + if raw == nil { + continue + } + step, err := sdkstep.DecodeStep(raw) + if err != nil { + return time.Time{}, false, fmt.Errorf("the step key %s: %w", k, err) + } + if !sdkstep.Ended(step) { + return time.Time{}, true, nil + } + return step.Ended, true, nil + } + return time.Time{}, false, nil + } +} + +// readOutput answers the verb output for ask (design 47 H2 §791, H-A-412): from the object `.`, the text's last +// OutputTail bytes, its size and failing tests from the header; with no object, no longer kept when this node's steps key +// shows the ask ended here more than OutputsMaxAge ago, and refused otherwise, naming why (an ask never run here, or one +// whose output this node did not keep). +func readOutput(o OutputObjects, node, ask string, ended func(ask string) (time.Time, bool, error)) (sdkstep.OutputAnswer, error) { + if o == nil { + return sdkstep.OutputAnswer{}, fmt.Errorf("this module keeps no %s store", OutputsStore) + } + name, err := sdkstep.StepKey(node, ask) + if err != nil { + return sdkstep.OutputAnswer{}, err + } + got, gerr := o.Get(name) + if gerr == nil { + return outputOf(ask, got.Data) + } + if ended == nil { + return sdkstep.OutputAnswer{}, fmt.Errorf("the output %s in the %s store: %w", name, OutputsStore, gerr) + } + at, here, err := ended(ask) + switch { + case err != nil: + return sdkstep.OutputAnswer{}, fmt.Errorf("the output %s is not in the %s store (%v), and this node's steps state cannot say why: %w", name, OutputsStore, gerr, err) + case !here: + return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s never ran on %s: no step key of it here", ask, node) + case !at.IsZero() && now().Sub(at) > OutputsMaxAge: + return sdkstep.OutputAnswer{Ask: ask, NoLongerKept: true}, nil + default: + return sdkstep.OutputAnswer{}, fmt.Errorf("the ask %s ran on %s, and its output is not in the %s store: %w", ask, node, OutputsStore, gerr) + } +} + +// outputOf is the verb output's answer from an output object's bytes: its header and the text's last OutputTail bytes, +// cut at a whole character. +func outputOf(ask string, data []byte) (sdkstep.OutputAnswer, error) { + line, text, ok := bytes.Cut(data, []byte{'\n'}) + var h outputHeader + if !ok || json.Unmarshal(line, &h) != nil { + return sdkstep.OutputAnswer{}, fmt.Errorf("the output of the ask %s holds no header", ask) + } + if len(text) > OutputTail { + text = text[len(text)-OutputTail:] + for len(text) > 0 && !utf8.RuneStart(text[0]) { + text = text[1:] + } + } + return sdkstep.OutputAnswer{Ask: ask, Output: string(text), Size: h.Size, Failing: h.Failing}, nil +} diff --git a/modules/mesh-delivery-sdk/steprun/outputs_test.go b/modules/mesh-delivery-sdk/steprun/outputs_test.go index 92c49d590..7e26a5e03 100644 --- a/modules/mesh-delivery-sdk/steprun/outputs_test.go +++ b/modules/mesh-delivery-sdk/steprun/outputs_test.go @@ -1,10 +1,14 @@ package steprun import ( + "encoding/json" "errors" + "slices" "strings" "testing" + "time" + sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep" "git.novox.be/novox/mesh-sdk/go/buscalls" ) @@ -22,22 +26,77 @@ func (f fakeOutputs) Get(name string) (buscalls.ObjectData, error) { return buscalls.ObjectData{Data: d}, nil } -// Design 47 G A-254: what a holder keeps through KeepOutputIn it reads again through ReadOutputFrom; with no store both refuse by name. +// Design 47 G A-254: what a holder keeps through KeepAnswerIn it reads again through ReadAnswerFrom; with no store both refuse by name. func TestOutputsKeptAreRead(t *testing.T) { st := fakeOutputs{m: map[string][]byte{}} - if err := KeepOutputIn(st)("output.a1", []byte("x")); err != nil { + if err := KeepAnswerIn(st)("answer.a1", []byte("x")); err != nil { t.Fatal(err) } - if got, err := ReadOutputFrom(st)("output.a1"); err != nil || string(got) != "x" { + if got, err := ReadAnswerFrom(st)("answer.a1"); err != nil || string(got) != "x" { t.Fatalf("read %q, %v", got, err) } - if _, err := ReadOutputFrom(st)("output.none"); err == nil { + if _, err := ReadAnswerFrom(st)("answer.none"); err == nil { t.Fatal("an absent answer was read") } - if err := KeepOutputIn(nil)("o", nil); err == nil || !strings.Contains(err.Error(), "steps-objects") { - t.Fatalf("no store kept an answer, or did not name the steps state's objects store: %v", err) + // Design 47 H2 H-A-412 addendum: a kept end is in the steps state's own objects, not in the `outputs` objects. + if err := KeepAnswerIn(nil)("o", nil); err == nil || !strings.Contains(err.Error(), "no steps-objects store") { + t.Fatalf("no store kept an answer, or did not name the steps objects: %v", err) } - if _, err := ReadOutputFrom(nil)("o"); err == nil { + if _, err := ReadAnswerFrom(nil)("o"); err == nil { t.Fatal("no store read an answer") } + + // Design 47 H2 §791, H-A-412: the verb output answers a run's output `.` from its header and its text's last + // 64 KB; with no object, no longer kept once this node's steps key shows the ask ended more than the max-age ago, and + // refused for an ask never run here or one whose output this node did not keep. + was := now + defer func() { now = was }() + at := time.Date(2026, 11, 22, 1, 0, 0, 0, time.UTC) + now = func() time.Time { return at } + long := strings.Repeat("x", OutputTail) + "the end\n" + failing := []sdkstep.FailingTest{{Test: "x/b TestU", Words: "got 1, want 2"}} + out := fakeOutputs{m: map[string][]byte{}} + if err := keepOutput(out, "ace", "a1", long, failing); err != nil { + t.Fatal(err) + } + step := func(ended time.Time) json.RawMessage { + raw, _ := sdkstep.EncodeStep(sdkstep.Step{ID: "a2", Tool: "step", Node: "ace", State: sdkstep.StepPassed, Started: ended, Ended: ended}) + return raw + } + steps := map[string]json.RawMessage{"mesh-delivery-pipeline.ace.a2": step(at.Add(-OutputsMaxAge - time.Hour)), "mesh-delivery-pipeline.ace.a3": step(at.Add(-time.Hour)), + "mesh-delivery-pipeline.g14.a4": step(at.Add(-OutputsMaxAge - time.Hour))} + keys := func() ([]string, error) { + return slices.Collect(func(y func(string) bool) { + for k := range steps { + y(k) + } + }), nil + } + tool := OutputTool("node-build-go", "ace", out, EndedHere("ace", keys, func(k string) (json.RawMessage, error) { return steps[k], nil })) + if tool.Name != "node-build-go.output" { + t.Fatalf("name %q", tool.Name) + } + for _, c := range []struct { + ask, fail string + want sdkstep.OutputAnswer + }{ + {ask: "a1", want: sdkstep.OutputAnswer{Ask: "a1", Output: long[len(long)-OutputTail:], Size: len(long), Failing: failing}}, + {ask: "a2", want: sdkstep.OutputAnswer{Ask: "a2", NoLongerKept: true}}, + {ask: "a3", fail: "ran on ace, and its output is not in the outputs store"}, + {ask: "a4", fail: "never ran on ace"}, + {ask: "a5", fail: "never ran on ace"}, + {fail: "asked for no ask"}, + } { + got, err := tool.Run(map[string]any{"ask": c.ask}) + if c.fail != "" { + if err == nil || !strings.Contains(err.Error(), c.fail) { + t.Errorf("output of %q: %+v, %v; want refused saying %q", c.ask, got, err, c.fail) + } + continue + } + o, _ := got.(sdkstep.OutputAnswer) + if err != nil || o.Ask != c.want.Ask || o.Output != c.want.Output || o.Size != c.want.Size || !slices.Equal(o.Failing, c.want.Failing) || o.NoLongerKept != c.want.NoLongerKept { + t.Errorf("output of %q: %+v, %v; want %+v", c.ask, got, err, c.want) + } + } } diff --git a/modules/mesh-delivery-sdk/steprun/phase.go b/modules/mesh-delivery-sdk/steprun/phase.go index 72d384656..f3a5e40a1 100644 --- a/modules/mesh-delivery-sdk/steprun/phase.go +++ b/modules/mesh-delivery-sdk/steprun/phase.go @@ -72,3 +72,14 @@ func (r *phases) phase() string { defer r.mu.Unlock() return r.step.Phase } + +// runOf is the run of its ask that ctx belongs to (the step's Run, the bus's count of runs that started), 0 outside an +// ask's run. +func runOf(ctx context.Context) int { + if r, ok := ctx.Value(phaseKey{}).(*phases); ok && r != nil { + r.mu.Lock() + defer r.mu.Unlock() + return r.step.Run + } + return 0 +} diff --git a/modules/mesh-delivery-sdk/steprun/publish.go b/modules/mesh-delivery-sdk/steprun/publish.go index 945a5f630..1d9495003 100644 --- a/modules/mesh-delivery-sdk/steprun/publish.go +++ b/modules/mesh-delivery-sdk/steprun/publish.go @@ -96,6 +96,13 @@ func PublishFault(err error) error { } func publishParts(ctx context.Context, call SeatCall, seat string, in reg.PublishInput, ps []parts.Part) (parts.Sent, error) { + // Design 47 H2 H-A-373: a publish on the Go package registry seat, and every bundle's, names the version the ask + // reserved; one by its digest alone marks no reservation, so it is refused before the seat is asked. An archive may + // still publish by its digest where no version is reserved for it. + if in.Version == "" && (seat == GoSeat || in.Kind == reg.PublishInputKindBundle) { + return parts.Sent{}, fmt.Errorf("%s's publish of %s (%s) names no version: a Go package and every bundle publish under the version the ask reserved", + seat, in.Name, in.Kind) + } switch seat { case ImageSeat: s, err := imageclient.Publish(ctx, imageclient.Call(call), in, ps) diff --git a/modules/mesh-delivery-sdk/steprun/pull.go b/modules/mesh-delivery-sdk/steprun/pull.go index b35a30ad0..aa755bbb0 100644 --- a/modules/mesh-delivery-sdk/steprun/pull.go +++ b/modules/mesh-delivery-sdk/steprun/pull.go @@ -83,10 +83,10 @@ type Puller struct { // every ProgressEvery while it runs, step-ended when an ask outside a pipeline ends (design 47 G §496, §602). Nil says // none, a test's. ProgressEvery defaults to DefaultProgressEvery. Say func(event string, body any, id string) error - // KeepOutput keeps a step's answer over what its key holds in the steps state (a check's or a run's, design 47 G A-290) - // as the object named object, which the key and a run's step-ended name and the seat's verb `output` answers (A-254); a - // holder keeps it in the object store its manifest requires. Nil keeps none: such an answer ends the ask failed, saying so. - KeepOutput func(object string, body []byte) error + // KeepAnswer keeps a step's answer over what its key holds in the steps state (a check's or a run's, design 47 G A-290) + // as the object named object, which the key and a run's step-ended name and the seat's verb `answer` answers (A-254); a + // holder keeps it in its steps objects (AnswersStore, H-A-412). Nil keeps none: such an answer ends the ask failed, saying so. + KeepAnswer func(object string, body []byte) error // Prior says how many runs of the ask under a step key started before (the Run of the step the key holds, PriorRuns; 0 for // none), so the poison rule and the transport fault's run count only runs that started, never an ask given back before it // ran. Nil counts the bus's deliveries (a test's). @@ -172,6 +172,11 @@ type Puller struct { // declined are the kinds whose worker handed an ask this node declined, left out of the pulls without a wait until // the next pull's wait ends. declined map[string]bool + // takesWhy and takesAt are what the last judgement found keeps the puller from taking asks ("" for none) and since when + // (takesSince), once hasTakes. + takesWhy string + takesAt time.Time + hasTakes bool // turn is the kind the next pull asks first (next): the kinds take turns, so a queue that never empties holds back none. turn int } @@ -267,12 +272,45 @@ func (p *Puller) InHand() int { return p.inHand } -// RunningAsk is an ask a puller runs now, as its seat's current verb says it. +// RunningAsk is an ask a puller runs now, as its seat's current verb says it: the part's CurrentAsk (design 47 H2 §801), +// whoever asked it. type RunningAsk struct { ID string `json:"id"` Kind string `json:"kind"` Module string `json:"module,omitempty"` Started time.Time `json:"started"` + Asker string `json:"asker"` +} + +// The reasons a holder takes no ask, as the seat's verb current says them (design 47 H2 §801, H-A-367 (2)). +const ( + NotTakingPaused = "paused" + NotTakingCapacity0 = "capacity 0" + NotTakingUnhealthy = "unhealthy" +) + +// whyNot is why the puller takes no ask by c, "" when it takes them: paused, its node unable to run the seat's asks +// (Eligible, unhealthy), or a capacity of 0. +func (p *Puller) whyNot(c sdkstep.Capacity) string { + switch { + case p.Paused(): + return NotTakingPaused + case c.Ineligible != "": + return NotTakingUnhealthy + case c.Effective <= 0: + return NotTakingCapacity0 + } + return "" +} + +// takesSince is since when the puller takes asks, or takes none for why, as it judged them: the first judgement that met why. +func (p *Puller) takesSince(why string) time.Time { + p.mu.Lock() + defer p.mu.Unlock() + if !p.hasTakes || p.takesWhy != why { + p.takesWhy, p.takesAt, p.hasTakes = why, now().UTC(), true + } + return p.takesAt } // Running are the asks the puller runs now, oldest first. @@ -295,7 +333,9 @@ func (p *Puller) room() bool { // roomNow is room, with the capacity and the asks in hand it was judged on. func (p *Puller) roomNow() (ok bool, capacity, inHand int) { - capacity = p.CapacityDetail().Effective + c := p.CapacityDetail() + capacity = c.Effective + p.takesSince(p.whyNot(c)) // each judgement keeps since when the holder takes asks or not (§801) p.mu.Lock() defer p.mu.Unlock() return !p.paused && p.inHand < capacity, capacity, p.inHand @@ -535,9 +575,10 @@ func (p *Puller) next(ctx context.Context, wait time.Duration) (*Pulled, error) p.mu.Lock() declined, start := p.declined, p.turn p.mu.Unlock() - for i := range sdkstep.AskKinds { - at := (start + i) % len(sdkstep.AskKinds) - kind := sdkstep.AskKinds[at] + queues := sdkstep.AskQueues(p.Language) + for i := range queues { + at := (start + i) % len(queues) + kind := queues[at] if declined[kind] { continue } @@ -545,7 +586,7 @@ func (p *Puller) next(ctx context.Context, wait time.Duration) (*Pulled, error) if err != nil || msg != nil { if msg != nil { p.mu.Lock() - p.turn = (at + 1) % len(sdkstep.AskKinds) + p.turn = (at + 1) % len(queues) p.mu.Unlock() } return withKind(msg, kind), err @@ -672,7 +713,7 @@ func (p *Puller) endUnrun(msg *Pulled, ask sdkstep.StepAsk, key string, step sdk why = fmt.Errorf("the ask is on its last delivery (%d) and no run of it started: it is out of its deliveries and run no more", msg.Delivered) } p.logf("the ask %s is ended on %s: %v", ask.ID, p.Node, why) - if _, ferr := finish(p.Put, p.KeepOutput, key, step, nil, why, p.Logf); ferr != nil { + if _, ferr := finish(p.Put, p.KeepAnswer, key, step, nil, why, p.Logf); ferr != nil { p.logf("the end of the ask %s could not be written on %s, so it is given back: %v", ask.ID, p.Node, ferr) _ = msg.Nak() return @@ -731,15 +772,18 @@ func (p *Puller) take(ctx context.Context, msg *Pulled) { return } module := "" - if ask.Build != nil { + switch { + case ask.Build != nil: module = ask.Build.Module + case ask.Install != nil: + module = ask.Install.Module } p.mu.Lock() p.inHand++ if p.running == nil { p.running = map[string]RunningAsk{} } - p.running[ask.ID] = RunningAsk{ID: ask.ID, Kind: ask.Kind, Module: module, Started: step.Started} + p.running[ask.ID] = RunningAsk{ID: ask.ID, Kind: ask.Kind, Module: module, Started: step.Started, Asker: askerOf(msg, ask)} p.mu.Unlock() p.logf("the %s ask %s starts on %s: %s", ask.Kind, ask.ID, p.Node, step.What) p.say("ask-taken", askTaken{Ask: ask.ID, Asker: askerOf(msg, ask), Node: p.Node, At: now().UTC()}, "ask-taken."+ask.ID) @@ -835,7 +879,7 @@ func (p *Puller) run(ctx context.Context, msg *Pulled, ask sdkstep.StepAsk, key p.logf("the ask %s ended on a transport fault and its step could not be written again (%v): it ends failed", ask.ID, aerr) } } - written, ferr := finish(p.Put, p.KeepOutput, key, step, result, err, p.Logf) + written, ferr := finish(p.Put, p.KeepAnswer, key, step, result, err, p.Logf) if ferr != nil { // No end was written: the ask is not acknowledged as done, so the stream gives it again and a run that can // write its end (or the poison rule, issue 1907) ends it where its asker sees it (issue 1930). @@ -845,7 +889,7 @@ func (p *Puller) run(ctx context.Context, msg *Pulled, ask sdkstep.StepAsk, key } // step-ended says the end the key holds (design 47 G A-290): its outcome, and the answer only when the key kept it, so no // step reads passed in one place and failed in another. - if len(written.Result) == 0 && written.OutputObject == "" { + if len(written.Result) == 0 && written.AnswerObject == "" { result = nil } outcome := "passed" @@ -854,9 +898,9 @@ func (p *Puller) run(ctx context.Context, msg *Pulled, ask sdkstep.StepAsk, key if len(outcome) > 300 { outcome = outcome[:300] + "..." } - p.sayEnded(msg, ask, sdkstep.OutcomeFailed, written.Reason, result, written.OutputObject) + p.sayEnded(msg, ask, sdkstep.OutcomeFailed, written.Reason, result, written.AnswerObject) } else { - p.sayEnded(msg, ask, sdkstep.OutcomePassed, "", result, written.OutputObject) + p.sayEnded(msg, ask, sdkstep.OutcomePassed, "", result, written.AnswerObject) } p.logf("the %s ask %s ended on %s after %s, in its phase %q; %s%s", ask.Kind, ask.ID, p.Node, now().Sub(step.Started).Round(time.Second), step.Phase, outcome, stepOutcomeWords(result)) @@ -1055,11 +1099,11 @@ func (p *Puller) say(event string, body any, id string) { // sayEnded says step-ended for an ask outside a pipeline, whatever its asker (design 47 G §602): a pipeline step's end is // its run's own (AskSteps.SayStep). The end of a run carries the run's answer (A-254): the last line of its program's -// standard output, inline as `output` up to sdkstep.StepEndedInlineMost, else as `output-object`, the object kept, the step's -// key naming it (design 47 G A-290: finish kept it with KeepOutput, so it is not put twice); a program that exits other than 0 +// standard output, inline as `output` up to sdkstep.StepEndedInlineMost, else as `answer-object`, the object kept, the step's +// key naming it (design 47 G A-290: finish kept it with KeepAnswer, so it is not put twice); a program that exits other than 0 // ends failed with its answer carried. func (p *Puller) sayEnded(msg *Pulled, ask sdkstep.StepAsk, outcome, said string, result any, kept string) { - if p.Say == nil || ask.Step != nil { + if p.Say == nil || ask.Step != nil || ask.Install != nil { return } end := sdkstep.StepEnded{ID: ask.ID, Asker: askerOf(msg, ask), Ask: ask.ID, Node: p.Node, Outcome: outcome, At: now().UTC()} @@ -1070,7 +1114,7 @@ func (p *Puller) sayEnded(msg *Pulled, ask sdkstep.StepAsk, outcome, said string if len(ans.Output) <= sdkstep.StepEndedInlineMost { end.Output = string(ans.Output) } else if kept != "" { - end.OutputObject = kept + end.AnswerObject = kept } else { outcome, said = sdkstep.OutcomeFailed, fmt.Sprintf("the run's answer is %d bytes, over what the end carries, and no object of it was kept", len(ans.Output)) } diff --git a/modules/mesh-delivery-sdk/steprun/pull_bus.go b/modules/mesh-delivery-sdk/steprun/pull_bus.go index 4053993a3..882c5055d 100644 --- a/modules/mesh-delivery-sdk/steprun/pull_bus.go +++ b/modules/mesh-delivery-sdk/steprun/pull_bus.go @@ -141,7 +141,7 @@ func DeclareAskWorkers(ctx context.Context, js jetstream.JetStream, language str Retention: jetstream.WorkQueuePolicy}); err != nil { return fmt.Errorf("the stream %s: %w", stream, err) } - for _, kind := range sdkstep.AskKinds { + for _, kind := range sdkstep.AskQueues(language) { worker, _ := sdkstep.AskWorker(language, kind) subject, _ := sdkstep.AskSubject(language, kind) // Two workers whose filters do not overlap: main's subject and the asker's, `.` (design 47 G §544). diff --git a/modules/mesh-delivery-sdk/steprun/pull_integration_test.go b/modules/mesh-delivery-sdk/steprun/pull_integration_test.go index a8e01162e..e2e196552 100644 --- a/modules/mesh-delivery-sdk/steprun/pull_integration_test.go +++ b/modules/mesh-delivery-sdk/steprun/pull_integration_test.go @@ -220,35 +220,45 @@ func TestAnAskThatMetTheNetworkIsGivenAgainAndADroppedOneIsEnded(t *testing.T) { func contains(s, sub string) bool { return strings.Contains(s, sub) } // Design 47 G §544: main's worker takes an ask put on main's subject and the named worker one put on the asker's, the two -// filters not overlapping. +// filters not overlapping. H2 H-A-403: the Node build seat's install is a queue of its own, its two workers declared too. func TestTheTwoWorkersTakeTheTwoFormsOfTheAcceptSubject(t *testing.T) { - js := askBus(t, 30*time.Second) - stream, _ := sdkstep.AskStream(sdkstep.AskGo) - worker, _ := sdkstep.AskWorker(sdkstep.AskGo, sdkstep.AskDelivery) - named, _ := sdkstep.AskNamedWorker(sdkstep.AskGo, sdkstep.AskDelivery) - main, _ := sdkstep.AskSubject(sdkstep.AskGo, sdkstep.AskDelivery) - for _, subject := range []string{main, main + ".mesh-builds"} { - if _, err := js.Publish(context.Background(), subject, []byte("{}")); err != nil { - t.Fatal(err) - } - } - for name, want := range map[string]string{worker: main, named: main + ".mesh-builds"} { - c, err := js.Consumer(context.Background(), stream, name) - if err != nil { - t.Fatal(err) - } - batch, err := c.Fetch(2, jetstream.FetchMaxWait(time.Second)) - if err != nil { - t.Fatal(err) - } - var got []string - for m := range batch.Messages() { - got = append(got, m.Subject()) - _ = m.Ack() - } - if len(got) != 1 || got[0] != want { - t.Errorf("%s took %v, want only %s", name, got, want) - } + for _, row := range []struct{ language, kind string }{ + {sdkstep.AskGo, sdkstep.AskDelivery}, + {sdkstep.AskNode, sdkstep.AskInstall}, + } { + t.Run(row.language+"/"+row.kind, func(t *testing.T) { + js := askBus(t, 30*time.Second) + if err := DeclareAskWorkers(context.Background(), js, row.language, 30*time.Second); err != nil { + t.Fatal(err) + } + stream, _ := sdkstep.AskStream(row.language) + worker, _ := sdkstep.AskWorker(row.language, row.kind) + named, _ := sdkstep.AskNamedWorker(row.language, row.kind) + main, _ := sdkstep.AskSubject(row.language, row.kind) + for _, subject := range []string{main, main + ".mesh-builds"} { + if _, err := js.Publish(context.Background(), subject, []byte("{}")); err != nil { + t.Fatal(err) + } + } + for name, want := range map[string]string{worker: main, named: main + ".mesh-builds"} { + c, err := js.Consumer(context.Background(), stream, name) + if err != nil { + t.Fatal(err) + } + batch, err := c.Fetch(2, jetstream.FetchMaxWait(time.Second)) + if err != nil { + t.Fatal(err) + } + var got []string + for m := range batch.Messages() { + got = append(got, m.Subject()) + _ = m.Ack() + } + if len(got) != 1 || got[0] != want { + t.Errorf("%s took %v, want only %s", name, got, want) + } + } + }) } } @@ -279,7 +289,7 @@ func TestACheckAnswerOverTheStepsStateIsKeptAndReadBackWhole(t *testing.T) { publishAsk(t, js, a) p := &Puller{Source: &JetStreamAsks{JS: js, Language: sdkstep.AskGo}, Language: sdkstep.AskGo, Node: "ace", Put: put, Capacity: func() int { return 1 }, PullWait: 100 * time.Millisecond, - KeepOutput: func(object string, body []byte) error { _, err := objects.PutBytes(ctx, object, body); return err }, + KeepAnswer: func(object string, body []byte) error { _, err := objects.PutBytes(ctx, object, body); return err }, Run: func(context.Context, sdkstep.StepAsk) (any, error) { return answer, nil }} go p.Pull(ctx) key, _ := askKey(a, "ace") @@ -292,14 +302,14 @@ func TestACheckAnswerOverTheStepsStateIsKeptAndReadBackWhole(t *testing.T) { step, err = sdkstep.DecodeStep(e.Value()) return err == nil && sdkstep.Ended(step) }) - if step.State != sdkstep.StepPassed || step.OutputObject != sdkstep.OutputObjectName(a.ID) || len(step.Result) != 0 { - t.Fatalf("the key ended %s (%s) naming %q with %d bytes of result, want passed, naming the object and no result", step.State, step.Reason, step.OutputObject, len(step.Result)) + if step.State != sdkstep.StepPassed || step.AnswerObject != sdkstep.AnswerObjectName(a.ID) || len(step.Result) != 0 { + t.Fatalf("the key ended %s (%s) naming %q with %d bytes of result, want passed, naming the object and no result", step.State, step.Reason, step.AnswerObject, len(step.Result)) } verb := func(k string, body any) (json.RawMessage, error) { - if k != "seat:node-build-go.output@ace" { + if k != "seat:node-build-go.answer@ace" { return nil, fmt.Errorf("asked %s", k) } - data, err := objects.GetBytes(ctx, sdkstep.OutputObjectName(body.(map[string]any)["ask"].(string))) + data, err := objects.GetBytes(ctx, sdkstep.AnswerObjectName(body.(map[string]any)["ask"].(string))) if err != nil { return nil, err } diff --git a/modules/mesh-delivery-sdk/steprun/pull_test.go b/modules/mesh-delivery-sdk/steprun/pull_test.go index bb514f3a9..4c7af288c 100644 --- a/modules/mesh-delivery-sdk/steprun/pull_test.go +++ b/modules/mesh-delivery-sdk/steprun/pull_test.go @@ -133,6 +133,15 @@ func TestPullKindsTakeTurns(t *testing.T) { if want := []string{sdkstep.AskDelivery, sdkstep.AskCheck, sdkstep.AskDelivery}; len(order) != 3 || order[0] != want[0] || order[1] != want[1] || order[2] != want[2] { t.Fatalf("order = %v, want %v", order, want) } + // H-A-403: the Node seat's holder pulls install, its own queue, beside the others. + nsrc := NewFakeAsks() + if err := nsrc.PublishAsk(installOf()); err != nil { + t.Fatal(err) + } + np := &Puller{Source: nsrc, Language: sdkstep.AskNode, Node: "shanks", Put: newSteps().put, Capacity: func() int { return 1 }, + PullWait: 10 * time.Millisecond, Run: func(context.Context, sdkstep.StepAsk) (any, error) { return nil, nil }} + go np.Pull(ctx) + waitFor(t, "the install acked", func() bool { a, _, _ := nsrc.Fates(); return len(a) == 1 }) } // 1887/A2a, 1887/AC-pull: given capacity 2 and three asks waiting, two run and the third waits, and it starts when diff --git a/modules/mesh-delivery-sdk/steprun/run_output_test.go b/modules/mesh-delivery-sdk/steprun/run_output_test.go index 5ca62908b..3736ccddc 100644 --- a/modules/mesh-delivery-sdk/steprun/run_output_test.go +++ b/modules/mesh-delivery-sdk/steprun/run_output_test.go @@ -14,7 +14,7 @@ import ( ) // Design 47 G A-254, A-290: a build seat's step-ended of a run carries the run's answer, the last line of its program's standard -// output: inline as `output` up to the event bound, else as `output-object`, the object the holder keeps, which the verb `output` +// output: inline as `output` up to the event bound, else as `answer-object`, the object the holder keeps, which the verb `output` // answers. The step's key holds the answer only within what the steps state holds per value: over it, a check's whole answer or a // run's output is the object output. the key names, kept once; the key and step-ended always say the same outcome, a run // whose program exited other than 0 failed in both, its answer kept (A-290). @@ -62,7 +62,7 @@ func TestStepEndedOfARunCarriesItsAnswer(t *testing.T) { kept, keeps := map[string][]byte{}, 0 p := &Puller{Source: src, Language: sdkstep.AskGo, Node: "shanks", Put: st.put, Capacity: func() int { return 1 }, PullWait: 10 * time.Millisecond, Heartbeat: time.Hour, Say: sy.say, - KeepOutput: func(object string, body []byte) error { + KeepAnswer: func(object string, body []byte) error { mu.Lock() defer mu.Unlock() keeps++ @@ -100,28 +100,28 @@ func TestStepEndedOfARunCarriesItsAnswer(t *testing.T) { } mu.Lock() defer mu.Unlock() - name := sdkstep.OutputObjectName(a.ID) + name := sdkstep.AnswerObjectName(a.ID) if c.objectKept { - if end["output-object"] != name || end["output"] != nil || string(kept[name]) != big { - t.Fatalf("end %v and kept %d bytes, want the object %s holding the whole answer and no inline output", end["output-object"], len(kept[name]), name) + if end["answer-object"] != name || end["output"] != nil || string(kept[name]) != big { + t.Fatalf("end %v and kept %d bytes, want the object %s holding the whole answer and no inline output", end["answer-object"], len(kept[name]), name) } - } else if end["output-object"] != nil { - t.Fatalf("an object %v was named, want none", end["output-object"]) + } else if end["answer-object"] != nil { + t.Fatalf("an object %v was named, want none", end["answer-object"]) } switch { case c.keyObject == "": - if step.OutputObject != "" || (c.keepErr == nil && keeps != 0) { - t.Fatalf("the key names %q and %d objects were kept, want none", step.OutputObject, keeps) + if step.AnswerObject != "" || (c.keepErr == nil && keeps != 0) { + t.Fatalf("the key names %q and %d objects were kept, want none", step.AnswerObject, keeps) } case c.check: var whole map[string]any - if step.OutputObject != name || len(step.Result) != 0 || keeps != 1 || json.Unmarshal(kept[name], &whole) != nil || whole["fetch"] == nil { - t.Fatalf("the key names %q with result %.80s, %d keeps; want the object %s holding the whole check answer, kept once", step.OutputObject, step.Result, keeps, name) + if step.AnswerObject != name || len(step.Result) != 0 || keeps != 1 || json.Unmarshal(kept[name], &whole) != nil || whole["fetch"] == nil { + t.Fatalf("the key names %q with result %.80s, %d keeps; want the object %s holding the whole check answer, kept once", step.AnswerObject, step.Result, keeps, name) } default: var rest sdkstep.RunAnswer - if step.OutputObject != name || keeps != 1 || string(kept[name]) != c.keyObject || json.Unmarshal(step.Result, &rest) != nil || rest.Output != nil || rest.Key != c.answer.Key { - t.Fatalf("the key names %q with result %.80s, %d keeps; want the object %s holding the output, kept once, and the run answer without it", step.OutputObject, step.Result, keeps, name) + if step.AnswerObject != name || keeps != 1 || string(kept[name]) != c.keyObject || json.Unmarshal(step.Result, &rest) != nil || rest.Output != nil || rest.Key != c.answer.Key { + t.Fatalf("the key names %q with result %.80s, %d keeps; want the object %s holding the output, kept once, and the run answer without it", step.AnswerObject, step.Result, keeps, name) } } }) diff --git a/modules/mesh-delivery-sdk/steprun/seat_tools.go b/modules/mesh-delivery-sdk/steprun/seat_tools.go index 1c423783d..ac61321e8 100644 --- a/modules/mesh-delivery-sdk/steprun/seat_tools.go +++ b/modules/mesh-delivery-sdk/steprun/seat_tools.go @@ -3,6 +3,7 @@ package steprun import ( "encoding/base64" "errors" + "time" sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep" stdio "git.novox.be/novox/mesh-sdk/go" @@ -18,9 +19,15 @@ func SeatTools(seat, what string, p *Puller) []stdio.Tool { Run: func(map[string]any) (any, error) { return run() }} } current := func() (any, error) { + // The part's current at form 2 (design 47 H2 §801, H-A-367 (2)): whether it takes asks, why not since when, its + // capacity and every ask it runs, whoever asked it. c := p.CapacityDetail() - return map[string]any{"node": p.Node, "capacity": c.Effective, "capacity_why": c.Why, "capacity_detail": c, - "running": p.Running(), "paused": p.Paused()}, nil + why := p.whyNot(c) + out := map[string]any{"node": p.Node, "takes": why == "", "since": p.takesSince(why), "capacity": c.Effective, "asks": p.Running()} + if why != "" { + out["why-not"] = why + } + return out, nil } drop := stdio.Tool{Name: seat + ".drop", Description: "End an " + what + " ask its caller no longer waits for: it is kept as dropped on this node " + "(so a bus that gives it again has it refused), and a step running here for it is ended, written refused naming who dropped it and why.", @@ -36,9 +43,8 @@ func SeatTools(seat, what string, p *Puller) []stdio.Tool { return map[string]any{}, nil }} return []stdio.Tool{drop, - verb("current", "The "+what+" asks this node runs now (each one's id, kind and when it started), its build capacity (the configured one, "+ - "bounded by the cores its node's build slice gives over the cores a step needs) and why, "+ - "and whether it is paused.", current), + verb("current", "Whether this node takes "+what+" asks now and why not (paused, capacity 0, unhealthy) since when, its build capacity, "+ + "and every ask it runs (its id, kind, module, when it started and who asked it), whoever asked it.", current), verb("pause", "Take no new "+what+" ask on this node until resumed; an ask running here ends in its place. Kept "+ "across a restart (the node's pause key).", func() (any, error) { if err := p.Pause("the seat's pause verb"); err != nil { @@ -55,22 +61,22 @@ func SeatTools(seat, what string, p *Puller) []stdio.Tool { } } -// OutputTool serves `.output` (design 47 G A-254, A-257): a run's answer by its ask, as the object the holder keeps it in -// (sdkstep.OutputObjectName), read with read, which answers nil for none. The verb's answer is marked chunks: the bundle answers -// the whole answer as the member `file` (base64) and the tool runner sends it in chunks and answers their count; an ask -// whose answer this node does not keep answers no chunks. -func OutputTool(seat string, read func(object string) ([]byte, error)) stdio.Tool { - return stdio.Tool{Name: seat + ".output", - Description: "A run's answer by its ask, when its step-ended named it as an output-object: the answer's bytes in chunks, of any size.", +// AnswerTool serves `.answer` (design 47 G A-254, A-257; H2 H-A-412 addendum): a step's end over what its key or +// step-ended carries, by its ask, as the object the holder keeps it in (sdkstep.AnswerObjectName), read with read, which +// answers nil for none. The verb's answer is marked chunks: the bundle answers the whole end as the member `file` (base64) +// and the tool runner sends it in chunks and answers their count; an ask whose end this node does not keep answers no chunks. +func AnswerTool(seat string, read func(object string) ([]byte, error)) stdio.Tool { + return stdio.Tool{Name: seat + "." + sdkstep.AnswerVerb, + Description: "A step's answer by its ask, when its step key or step-ended named it as an answer-object: the kept end's bytes in chunks, of any size.", Input: map[string]any{"type": "object", "required": []string{"ask", "call"}, "properties": map[string]any{ "ask": map[string]any{"type": "string", "description": "the ask's id"}, "call": map[string]any{"type": "string", "description": "the subject token of this send's chunks"}}}, Run: func(args map[string]any) (any, error) { ask, _ := args["ask"].(string) if ask == "" { - return nil, errors.New("the verb output is asked for no ask") + return nil, errors.New("the verb answer is asked for no ask") } - body, err := read(sdkstep.OutputObjectName(ask)) + body, err := read(sdkstep.AnswerObjectName(ask)) if err != nil { return nil, err } @@ -80,3 +86,22 @@ func OutputTool(seat string, read func(object string) ([]byte, error)) stdio.Too return map[string]any{"ask": ask, "file": base64.StdEncoding.EncodeToString(body)}, nil }} } + +// OutputTool serves `.output` at the part's form 2 (design 47 H2 §791, H-A-367 (1), H-A-412): a run's test output by +// its ask, from the object `.` in the outputs objects o: its last 64 KB, its size and the failing tests with their +// words; no-longer-kept once ended (EndedHere over the holder's steps state) shows the ask ended on node more than the +// objects' max-age ago; an ask never run here is refused, naming it. +func OutputTool(seat, node string, o OutputObjects, ended func(ask string) (time.Time, bool, error)) stdio.Tool { + return stdio.Tool{Name: seat + "." + sdkstep.OutputVerb, + Description: "A run's test output by its ask: the output's last 64 KB, its size and the failing tests with their words, " + + "or no longer kept once past the outputs objects' max-age (7 days). An ask that never ran on this node is refused.", + Input: map[string]any{"type": "object", "required": []string{"ask"}, "properties": map[string]any{ + "ask": map[string]any{"type": "string", "description": "the ask's id"}}}, + Run: func(args map[string]any) (any, error) { + ask, _ := args["ask"].(string) + if ask == "" { + return nil, errors.New("the verb output is asked for no ask") + } + return readOutput(o, node, ask, ended) + }} +} diff --git a/modules/mesh-delivery-sdk/steprun/seat_tools_test.go b/modules/mesh-delivery-sdk/steprun/seat_tools_test.go index ddd615da7..e4c82b057 100644 --- a/modules/mesh-delivery-sdk/steprun/seat_tools_test.go +++ b/modules/mesh-delivery-sdk/steprun/seat_tools_test.go @@ -32,11 +32,13 @@ func TestSeatToolsCurrentPauseResume(t *testing.T) { waitFor(t, "the ask running", func() bool { return p.InHand() == 1 }) out, _ := tools["node-build-go.current"](nil) cur := out.(map[string]any) - running := cur["running"].([]RunningAsk) - if len(running) != 1 || running[0].ID != a.ID || running[0].Module != "m" || cur["capacity"] != 1 || cur["paused"] != false { + // Design 47 H2 §801: current answers whether it takes asks, since when, and every ask it runs with its asker. + running := cur["asks"].([]RunningAsk) + if len(running) != 1 || running[0].ID != a.ID || running[0].Module != "m" || running[0].Asker != a.Asker || cur["capacity"] != 1 || + cur["takes"] != true || cur["why-not"] != nil || cur["since"].(time.Time).IsZero() { t.Fatalf("current = %+v", cur) } - if out, err := tools["node-build-go.pause"](nil); err != nil || out.(map[string]any)["paused"] != true { + if out, err := tools["node-build-go.pause"](nil); err != nil || out.(map[string]any)["why-not"] != "paused" || out.(map[string]any)["takes"] != false { t.Fatalf("pause = %v, %v", out, err) } close(release) @@ -49,14 +51,33 @@ func TestSeatToolsCurrentPauseResume(t *testing.T) { t.Fatal(err) } waitFor(t, "the ask taken after the resume", func() bool { return src.Waiting(sdkstep.AskDelivery) == 0 }) + // §801: a node at capacity 0 takes none for capacity 0, one its module finds unable to run the seat's asks for unhealthy. + for _, c := range []struct { + p *Puller + want string + }{ + {&Puller{Node: "ace", Language: sdkstep.AskGo, Capacity: func() int { return 0 }}, NotTakingCapacity0}, + {&Puller{Node: "ace", Language: sdkstep.AskGo, Capacity: func() int { return 2 }, Eligible: func() string { return "no /dev/net/tun" }}, NotTakingUnhealthy}, + } { + var cur map[string]any + for _, tool := range SeatTools("node-build-go", "Go", c.p) { + if tool.Name == "node-build-go.current" { + out, _ := tool.Run(nil) + cur = out.(map[string]any) + } + } + if cur["why-not"] != c.want || cur["takes"] != false { + t.Errorf("current = %+v, want why-not %q", cur, c.want) + } + } } -// Design 47 G A-254: `.output` answers a run's answer by its ask as the whole file (base64), which the tool runner sends in +// Design 47 G A-254, H2 H-A-412 addendum: `.answer` answers a step's kept end by its ask as the whole file (base64), which the tool runner sends in // chunks (A-257); an ask this node keeps no answer of answers no chunks. -func TestOutputToolAnswersTheKeptAnswer(t *testing.T) { - kept := map[string][]byte{sdkstep.OutputObjectName("a1"): []byte(`{"verdict":"x"}`)} - tool := OutputTool("node-build-go", func(object string) ([]byte, error) { return kept[object], nil }) - if tool.Name != "node-build-go.output" { +func TestAnswerToolAnswersTheKeptAnswer(t *testing.T) { + kept := map[string][]byte{sdkstep.AnswerObjectName("a1"): []byte(`{"verdict":"x"}`)} + tool := AnswerTool("node-build-go", func(object string) ([]byte, error) { return kept[object], nil }) + if tool.Name != "node-build-go.answer" { t.Fatalf("name %q", tool.Name) } got, err := tool.Run(map[string]any{"ask": "a1", "call": "c"}) diff --git a/modules/mesh-delivery-sdk/steprun/step.go b/modules/mesh-delivery-sdk/steprun/step.go index 84a0f87bd..d172d76b6 100644 --- a/modules/mesh-delivery-sdk/steprun/step.go +++ b/modules/mesh-delivery-sdk/steprun/step.go @@ -21,7 +21,7 @@ import ( type Put func(key string, value any) (uint64, error) // Keep keeps a step's answer that is over what the steps state holds per value as the object named object in the build -// module's outputs store (design 47 G A-290), the object the seat's verb output answers: Puller.KeepOutput, KeepOutputIn. +// module's steps objects (design 47 G A-290, H2 H-A-412), the object the seat's verb answer answers: Puller.KeepAnswer, KeepAnswerIn. type Keep func(object string, body []byte) error // EndAttempts and EndRetry bound how a step's end is written: a write that fails is tried again, since the end @@ -122,7 +122,7 @@ func finish(put Put, keep Keep, key string, step sdkstep.Step, result any, err e if step.Reason != "" { why = fmt.Sprintf("the step ended %s (%s), and its end could not be written: %v", ended, step.Reason, werr) } - step.State, step.Reason, step.Result, step.OutputObject = sdkstep.StepFailed, why, nil, "" + step.State, step.Reason, step.Result, step.AnswerObject = sdkstep.StepFailed, why, nil, "" if ferr := writeEnd(put, key, step); ferr != nil { if logf != nil { logf("the failed end of the step %s could not be written either: %v", key, ferr) @@ -134,7 +134,7 @@ func finish(put Put, keep Keep, key string, step sdkstep.Step, result any, err e // keepOver is step as its key keeps it (design 47 G A-290): a value within what the steps state holds per value // (kvlimit.ModuleStateValueBytes less the headers' room) keeps its answer itself; over it, the answer is kept with keep as the -// object sdkstep.OutputObjectName(step.ID), which the key names as its output-object: a run's output, the key keeping the +// object sdkstep.AnswerObjectName(step.ID), which the key names as its answer-object: a run's output, the key keeping the // run answer without it, else the whole answer, the key's result then empty. A step whose answer cannot be kept ends failed, // saying why, with no answer, so it never reads passed where its answer is lost. func keepOver(keep Keep, step sdkstep.Step, result any) sdkstep.Step { @@ -142,7 +142,7 @@ func keepOver(keep Keep, step sdkstep.Step, result any) sdkstep.Step { if err != nil || len(step.Result) == 0 || kvlimit.Check("steps", "", len(raw), kvlimit.ModuleStateValueBytes) == nil { return step } - object, body, rest := sdkstep.OutputObjectName(step.ID), []byte(step.Result), json.RawMessage(nil) + object, body, rest := sdkstep.AnswerObjectName(step.ID), []byte(step.Result), json.RawMessage(nil) if ans, ok := runAnswerIn(result); ok { body, ans.Output = ans.Output, nil if rest, err = json.Marshal(ans); err != nil { @@ -162,7 +162,7 @@ func keepOver(keep Keep, step sdkstep.Step, result any) sdkstep.Step { if err := keep(object, body); err != nil { return lost(fmt.Sprintf("the step's answer makes its value %d bytes, over what the steps state holds, and could not be kept as the object %s: %v", len(raw), object, err)) } - step.Result, step.OutputObject = rest, object + step.Result, step.AnswerObject = rest, object return step } @@ -187,7 +187,7 @@ func runAnswerIn(result any) (sdkstep.RunAnswer, bool) { // again writes the step as given again after a transport fault: the state again with the run's cause, and when the bus gives // the ask again (ADR 0664 §1). The key is not ended: its asker keeps waiting on it. func again(put Put, key string, step sdkstep.Step, err error, delay time.Duration) error { - step.State, step.Reason, step.Passing, step.Result, step.OutputObject = sdkstep.StepAgain, err.Error(), true, nil, "" + step.State, step.Reason, step.Passing, step.Result, step.AnswerObject = sdkstep.StepAgain, err.Error(), true, nil, "" step.Ended, step.AgainAt = time.Time{}, now().UTC().Add(delay) return writeEnd(put, key, step) } diff --git a/modules/mesh-delivery-sdk/steprun/steprun.go b/modules/mesh-delivery-sdk/steprun/steprun.go index 7cd29e6e2..1b3eebf66 100644 --- a/modules/mesh-delivery-sdk/steprun/steprun.go +++ b/modules/mesh-delivery-sdk/steprun/steprun.go @@ -6,8 +6,10 @@ import ( "errors" "fmt" "strings" + "time" sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep" + stdio "git.novox.be/novox/mesh-sdk/go" ) // **A pipeline step, run and said** (novox/hq ADR 0666 §7, §8, §17, §21; design 47 *Pipeline steps and the policy*, @@ -41,7 +43,16 @@ func (s AskSteps) runStep(ctx context.Context, ask sdkstep.StepAsk) (any, error) return nil, Refuse("%v", err) } if err := s.stepOutcome(ctx, ask, &end); err != nil { - return nil, err + if !sdkstep.IsPassing(err) || runOf(ctx) < sdkstep.AskRuns { + return nil, err + } + // Its last run met a transport fault (design 47 H2 §799, §800): the step ends here and its end is said, a starved + // setup could-not-run, never failed, a fetch or a publish met away failed with the why it opens with. + end.Outcome, end.Said = sdkstep.OutcomeFailed, err.Error() + if errors.Is(err, errSetupStarved) { + end.Outcome = sdkstep.OutcomeCouldNotRun + } + end.Tests, end.Carried, end.Kept, end.NotRun = nil, nil, nil, nil } if err := s.SayStep(end); err != nil { return nil, &sdkstep.Passing{Err: fmt.Errorf("the end of the step %s could not be said: %w", ask.ID, err)} @@ -52,7 +63,9 @@ func (s AskSteps) runStep(ctx context.Context, ask sdkstep.StepAsk) (any, error) // stepOutcome runs the step into end; the error it answers is one that keeps the end unsaid. func (s AskSteps) stepOutcome(ctx context.Context, ask sdkstep.StepAsk, end *sdkstep.StepEnded) error { var err error - if ask.Step.Step == sdkstep.StepLint { + if ask.Install != nil { + err = s.installStep(ctx, ask, end) + } else if ask.Step.Step == sdkstep.StepLint { err = s.lintStep(ctx, *ask.Step, end) } else { err = s.testStep(ctx, ask, end) @@ -70,6 +83,33 @@ func (s AskSteps) stepOutcome(ctx context.Context, ask sdkstep.StepAsk, end *sdk } } +// installStep runs the module's install body and names the archive it published in the end (design 47 H2 §800, H-A-399 +// (2), H-A-403); an install that answers no archive could not run. +func (s AskSteps) installStep(ctx context.Context, ask sdkstep.StepAsk, end *sdkstep.StepEnded) error { + if s.Install == nil { + return fmt.Errorf("this build module installs nothing") + } + i := ask.Install + Phase(ctx, "install") + out, err := s.Install(ctx, map[string]any{"module": i.Module, "commit": i.Commit, "fingerprint": i.Fingerprint, "pipeline": i.Pipeline, + "lock": i.Lock, "artifact": sdkstep.InstallArtifact(i.Module), "version": ask.Version}) + if err != nil { + return err + } + r, err := raw(out) + if err != nil { + return err + } + var a struct { + Archive string `json:"archive"` + } + if err := json.Unmarshal(r, &a); err != nil || a.Archive == "" { + return fmt.Errorf("the install answered no archive: %s", r) + } + end.Outcome, end.Archive = sdkstep.OutcomePassed, a.Archive + return nil +} + // lintStep fetches the heads and runs the module's lint body over the artifact's tree. func (s AskSteps) lintStep(ctx context.Context, run sdkstep.StepRun, end *sdkstep.StepEnded) error { if s.Lint == nil { @@ -124,8 +164,10 @@ func (s AskSteps) testStep(ctx context.Context, ask sdkstep.StepAsk, end *sdkste } return 0, false, nil } - job := sdkstep.CheckJob{Fetch: *withPackages(&run.Fetch, ask.Packages), Levels: []string{level}, Kept: true, Toolchain: run.Toolchain} - out, err := s.check(ctx, job) + job := sdkstep.CheckJob{Fetch: *withPackages(&run.Fetch, ask.Packages), Levels: []string{level}, Kept: true, Toolchain: run.Toolchain, Archive: run.Archive} + // The level's text, taken out of its test answers, is the run's output (design 47 H2 H-A-412). + var text strings.Builder + out, err := s.checkTexts(ctx, job, &text) if err != nil { return err } @@ -147,25 +189,43 @@ func (s AskSteps) testStep(ctx context.Context, ask sdkstep.StepAsk, end *sdkste } tests, passed, ran := 0, true, false var why []string + var failed []sdkstep.Failure + bound := 0.0 for _, t := range la.Tests { var tr struct { Passed bool `json:"passed"` Tests int `json:"tests"` NoTests bool `json:"no_tests"` Why string `json:"why"` + // NotRun are the tests that did not run, with their reasons (design 47 H2 §800): the part's not-run, read by + // the build module's reader (ReadGoTest's NotRun). + NotRun []sdkstep.NotRun `json:"not-run"` + Failed []sdkstep.Failure `json:"failed"` + // Bound is the level's bound in seconds, the setup bound being half of it (H-A-368). + Bound float64 `json:"bound"` } if err := json.Unmarshal(t, &tr); err != nil { return fmt.Errorf("the %s level answered what is no test result: %w", level, err) } tests += tr.Tests ran = ran || (!tr.NoTests && tr.Tests > 0) || !tr.Passed + end.NotRun = append(end.NotRun, tr.NotRun...) + bound = max(bound, tr.Bound) if !tr.Passed { passed = false + failed = append(failed, tr.Failed...) if tr.Why != "" { why = append(why, tr.Why) } } } + s.keepRunOutput(ask.ID, text.String(), failed) + if !passed && starvedOnly(failed) { + // Design 47 H2 §800, H-A-368: a setup whose wait on the bus passed its bound runs again by §799's delays, never + // failed; the third such run ends could-not-run (runStep). + end.NotRun = nil + return &sdkstep.Passing{Err: fmt.Errorf("%w %s under load (%s)", errSetupStarved, setupBound(bound), firstOf(failed[0].Cause))} + } for _, k := range la.Kept { end.Carried = append(end.Carried, keptOf(run, k.Package, k.Digest)) } @@ -198,6 +258,42 @@ func (s AskSteps) testStep(ctx context.Context, ask sdkstep.StepAsk, end *sdkste return nil } +// keepRunOutput keeps a test step's level text as the run's output `.` in the outputs objects, with the +// header of the failing tests and their words from the level's results (design 47 H2 §791, H-A-412 (1)). A holder that +// keeps no outputs, or a write that fails, is said in the journal: the step's end stands on the results. +func (s AskSteps) keepRunOutput(ask, text string, failed []sdkstep.Failure) { + var failing []sdkstep.FailingTest + for _, f := range failed { + failing = append(failing, sdkstep.FailingTest{Test: strings.TrimSpace(f.Package + " " + f.Test), Words: f.Cause}) + } + if err := keepOutput(s.Outputs, s.Node, ask, text, failing); err != nil && s.Logf != nil { + s.Logf("the output of the ask %s could not be kept: %v", ask, err) + } +} + +// errSetupStarved opens the why of a level whose every failure is a starved setup (design 47 H2 §800): its words are the +// could-not-run end's at the third run. +var errSetupStarved = errors.New("the bus did not answer in setup within") + +// starvedOnly says a level failed only by starved setups: every failure's words open stdio.SetupStarved (H-A-368). An +// assertion that fails is never `again` (§800), so one such failure among them makes the level failed. +func starvedOnly(failed []sdkstep.Failure) bool { + for _, f := range failed { + if !strings.HasPrefix(strings.TrimSpace(f.Cause), stdio.SetupStarved) { + return false + } + } + return len(failed) > 0 +} + +// setupBound is the setup bound of a level bound in seconds: half of it, 30 s when the level names none (H-A-368). +func setupBound(levelSeconds float64) time.Duration { + if levelSeconds <= 0 { + return 30 * time.Second + } + return time.Duration(levelSeconds * float64(time.Second) / 2).Round(time.Second) +} + func keptOf(run sdkstep.StepRun, pkg, digest string) sdkstep.KeptResult { return sdkstep.KeptResult{Package: pkg, Digest: digest, Level: run.Step, Toolchain: run.Toolchain, Pipeline: run.Pipeline} }