diff --git a/modules/mesh-delivery-contracts/go/seats/containerimageregistry/contract.go b/modules/mesh-delivery-contracts/go/seats/containerimageregistry/contract.go index 26ea4d9ac..0e49186c0 100644 --- a/modules/mesh-delivery-contracts/go/seats/containerimageregistry/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/containerimageregistry/contract.go @@ -51,6 +51,32 @@ func Verbs() []string { return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove, VerbMirror, VerbTags, VerbHold, VerbRelease, VerbList} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbPublish: + return "Open a transfer, naming the artifact and the digest of every part; answers the digests the holder lacks, which the caller then sends by publish-part. A transfer already open answers the parts held, so a cut transfer goes on from there. With no parts and a version, the held digest is published under that version and nothing is stored (the trunk's claim)." + case VerbPublishPart: + return "Send one chunk of one part of an open transfer; the last chunk of the last part ends the transfer, and the holder hashes what it received, asks builder_versions, stores it and says published or refused. A chunk's message stays under the bus's largest message (1 MiB), so at most 760 KiB of data, base64." + case VerbVersions: + return "The versions the seat holds of one name, newest first: each one's version, tag, digest, kind and when it was published." + case VerbRemove: + return "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base, which the artifact sweep's holder asks; the caller is not judged (design 47 H2 §813 (7)). Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry." + case VerbMirror: + return "Copy an outside image into the store by its pinned digest; emits published or refused." + case VerbTags: + return "The tags of one image and the digest each names." + case VerbHold: + return "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 §2); never an image of the holder's own. Emits held." + case VerbRelease: + return "Let a hold go; emits released. A release of what is not held answers released false and emits nothing, never an error: the outcome asked holds already. By hand only through the holder's own tool, the operator's session as the proved caller, recorded as a hand act." + case VerbList: + return "What the store holds of one repository, or of every repository the seat holds when none is named: every image manifest and index, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 §3)." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPublished, EventRefused, EventRemoved, EventKept, EventHeld, EventReleased} diff --git a/modules/mesh-delivery-contracts/go/seats/git/contract.go b/modules/mesh-delivery-contracts/go/seats/git/contract.go index 1eb6a5164..8e7f35f24 100644 --- a/modules/mesh-delivery-contracts/go/seats/git/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/git/contract.go @@ -57,6 +57,42 @@ func Verbs() []string { return []string{VerbPull, VerbBranch, VerbOpenPulls, VerbTags, VerbTrees, VerbFile, VerbContains, VerbStatuses, VerbStatus, VerbComment, VerbView, VerbNote, VerbMergePull, VerbTag} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbPull: + return "One pull request, by its repository and number or by its merge commit: its number, base, head branch, head, merge commit, author and state; for an open one, also what the forge would merge now (merging). A pull request the forge does not hold answers an error naming it." + case VerbBranch: + return "A branch's head (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found." + case VerbOpenPulls: + return "Every open pull request of every repository, its head and base, the statuses its base's protection requires and those its head has." + case VerbTags: + return "A repository's tags, a page at a time, newest first; the page's bound is said, and more when another page exists." + case VerbTrees: + return "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part. A directory named in files or paths that the commit does not hold answers the error kind not-found (design 47 H2 §796)." + case VerbFile: + return "One file at one commit, branch or tag, decoded; a file over 512 KiB is refused. An absent file is answered absent only when the forge said so." + case VerbContains: + return "Whether one commit contains another: an ancestor of it, or the same." + case VerbStatuses: + return "The statuses a commit carries, the newest of each context." + case VerbStatus: + return "Set a commit status. An act: its id is the caller's, and the same id said again sets it again to the same." + case VerbComment: + return "Add a comment to a pull request. The comment carries the act's id, and an id the pull request already holds is skipped (held)." + case VerbView: + return "Keep the delivery's one view comment on a pull request: made the first time, edited in place after; it carries the act's id, and an id already held is skipped (held)." + case VerbNote: + return "Append one line to a commit's note under refs/notes/mesh-plan. The line carries the act's id, and an id the note already holds is skipped (held)." + case VerbMergePull: + return "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H §734, §735, §766; ADR 0682 §1, §2). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit." + case VerbTag: + return "Write the git tag of a released version, /vMAJOR.MINOR.PATCH for a Go package (design 47 H2 §796), at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPullUpdated, EventPullMerged, EventPullClosed, EventForgePull, EventForgeStatus, EventForgeDelete, EventRepoWritable, EventBranchMoved, EventMergeCalled} diff --git a/modules/mesh-delivery-contracts/go/seats/gopackageregistry/contract.go b/modules/mesh-delivery-contracts/go/seats/gopackageregistry/contract.go index 851052cfa..6d632d989 100644 --- a/modules/mesh-delivery-contracts/go/seats/gopackageregistry/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/gopackageregistry/contract.go @@ -43,6 +43,22 @@ func Verbs() []string { return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbPublish: + return "Open a transfer, naming the artifact and the digest of every part; answers the digests the holder lacks, which the caller then sends by publish-part. A transfer already open answers the parts held, so a cut transfer goes on from there. With no parts and a version, the held digest is published under that version and nothing is stored (the trunk's claim)." + case VerbPublishPart: + return "Send one chunk of one part of an open transfer; the last chunk of the last part ends the transfer, and the holder hashes what it received, asks builder_versions, stores it and says published or refused. A chunk's message stays under the bus's largest message (1 MiB), so at most 760 KiB of data, base64." + case VerbVersions: + return "The versions the seat holds of one name, newest first: each one's version, tag, digest, kind and when it was published." + case VerbRemove: + return "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base, which the artifact sweep's holder asks; the caller is not judged (design 47 H2 §813 (7)). Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPublished, EventRefused, EventRemoved, EventKept} diff --git a/modules/mesh-delivery-contracts/go/seats/meshartifactsweep/contract.go b/modules/mesh-delivery-contracts/go/seats/meshartifactsweep/contract.go index 3d143027f..7cb3db962 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshartifactsweep/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshartifactsweep/contract.go @@ -39,6 +39,24 @@ func Verbs() []string { return []string{VerbArtifacts, VerbHeld, VerbCollect, VerbMirrors, VerbImages} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbArtifacts: + return "Every artifact the mesh made that lives in its artifact store, each with its repository, digest, kind (image or archive) and state: kept, and why (a want names it, or one of the five newest builds of its module in the builder's log), eligible (made, kept for no reason, not yet let go), or unrecorded (in the store and named by nothing the mesh made: never removed). Reads only." + case VerbHeld: + return "Whether the artifact store holds each reference given, asked with one HEAD each: held, gone (the store answered 404) or unknown with why. The builder asks it before it reuses a done key. Reads only." + case VerbCollect: + return "The artifact store's sweep, now: what is eligible is let go of. Without confirm a dry run: what would be let go, nothing held or deleted. With confirm and why: every kept archive held first, then each eligible artifact let go of, oldest first, an index with the platform manifests no kept index names, each deletion recorded in the hand-act log. Bounded by most (500 by default, at most 5000) and 45 seconds; what is left is said. Never touches a digest the mesh did not make." + case VerbMirrors: + return "The bases the mesh copied into its artifact store, each kept (a kept build stood on it), eligible (only builds no longer kept stood on it) or unrecorded (no build the builder's log holds stood on it: never removed), by what the builder's log says each build stood on. Records nothing by hand." + case VerbImages: + return "Every container image one machine's want and have name, each with the resources naming it: what the machine keeps when it prunes its images. Reads only." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventArtifactsGone} diff --git a/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go b/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go index b6392f0f8..25373ac6a 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshbuilds/contract.go @@ -45,6 +45,20 @@ func Verbs() []string { return []string{VerbReserved, VerbPublished, VerbDrop} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbReserved: + return "A module's reserved version with each artifact's digest, for a registry holder deciding whether to publish; asked by the module or by a package's name in its ecosystem (design 47 G section 369, section 478; design 51, Publishing)." + case VerbPublished: + return "Whether an artifact built at a build fingerprint is published, from the builder's reservations and the registries' record, for the pipeline runner writing a mover's wait on a package: a package published before the wait was written is read, not waited for (design 47 H-A-326, H-A-328, H-A-274)." + case VerbDrop: + return "End an ask on the seat's work queue for a caller that no longer waits for it (its step ended by its bound): one waiting is ended dropped when it is pulled, one taken is cancelled; both end the step dropped, naming who dropped it and why, so no holder works on it after (design 47 H2 §778; ADR 0664 §4)." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPackagePublished, EventToolchainAgreed, EventStepEnded, EventAskTaken, EventVersionReserved} diff --git a/modules/mesh-delivery-contracts/go/seats/meshcatalog/contract.go b/modules/mesh-delivery-contracts/go/seats/meshcatalog/contract.go index 19cadc72e..d216d02d2 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshcatalog/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshcatalog/contract.go @@ -59,6 +59,46 @@ func Verbs() []string { return []string{VerbModules, VerbModule, VerbProvides, VerbDependents, VerbSeatDefinitions, VerbSeatList, VerbRevision, VerbRegistrations, VerbRegister, VerbPolicy, VerbWatch, VerbUnwatch, VerbVersions, VerbOutdated, VerbInput, VerbEntry} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbModules: + return "Every module the trunk holds, each with its repository, its directory there, the merge commit it was last changed at and its fingerprint (or why it has none): the catalog of the mesh, read from its holder's state. Reads only." + case VerbModule: + return "One module whole: its repository, directory, commit and fingerprint, and its manifest as the trunk holds it. Older versions are in its repository's history. Reads only." + case VerbProvides: + return "Which modules provide a provision (a module provides its own name too) and which require it, from the module graph's provision edges. Reads only." + case VerbDependents: + return "The modules whose build edges reach a module, directly or through others (a base, a mesh package it publishes, the build module that builds them): what a change of it builds again, from the module graph. Reads only." + case VerbSeatDefinitions: + return "The seat list (ADR 0636 §4): with no seat, every trunk seat with its digest and the revision of the list; with a seat, that trunk definition resolved with the parts it includes. Reads only." + case VerbSeatList: + return "The seat list the mesh holds, as one object in the holder's objects seat-lists, one object per digest (design 47 H2 §814): the manifest validator program takes it by address, so a run by hand reads what the live validate reads. Reads only." + case VerbRevision: + return "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530)." + case VerbRegistrations: + return "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811)." + case VerbRegister: + return "Register a module whole, as an authorising ask of tier approve naming every value; written only on its warrant, a Decline or an expiry writes nothing. Refuses a watched branch the forge does not protect, read through the seat git's branch, and code review as a required step until forge accounts are bound to bus identities (ADR 0666 sections 2, 3, 22)." + case VerbPolicy: + return "Change one module's step statuses, or one artifact's, as an authorising ask naming each moved status on its own line; refuses code review as required (ADR 0666 sections 2, 22)." + case VerbWatch: + return "Add a watched branch to a module's registration, as an authorising ask; refuses a branch the forge does not protect, naming it (ADR 0666 sections 2, 3)." + case VerbUnwatch: + return "Remove a watched branch from a module's registration, as an authorising ask (ADR 0666 section 2)." + case VerbVersions: + return "A module's released versions, each artifact's digest, the source revision built and its edge entries; a reserved version is not in it (design 47 G section 349)." + case VerbOutdated: + return "Every entry behind, by the part's digest: its module and version or build, the kind, the dependency with its watched branch and source revision, what was recorded and what is newest, and the act; may be asked for one dependency (design 47 G section 375)." + case VerbInput: + return "A step's input by its digest, as the indexer keeps it for a validation step it asked a build seat to run (design 47 G section 354): its fields, then the 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 input is of any size." + case VerbEntry: + return "One catalog graph entry by its fingerprint, so a build older than the newest is read by the fingerprint its want names (design 47 G section 443)." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventSeatDefinitionChanged, EventSeatDefinitionRemoved, EventCatalogRevision, EventFilling, EventFull, EventRoom, EventRegistrationChanged, EventVersionReleased, EventVersionsFilled} diff --git a/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go b/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go index 89487ec9b..93579d021 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshdelivery/contract.go @@ -47,6 +47,24 @@ func Verbs() []string { return []string{VerbDeliveries, VerbShow, VerbSource, VerbStalled, VerbRecovery} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbDeliveries: + return "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group. Filtered by repository, module, outcome and since while it reads, at most 768 KB a page, capped saying the rest is read from the cursor next (design 47 H2 §811)." + case VerbShow: + return "One delivery or group whole: its delivery plan (what it builds, what each machine receives, what is not an ordinary send), every transition with when and why, the machine steps of its walk, its group and its order." + case VerbSource: + return "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source. in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the merge call that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690)." + case VerbStalled: + return "Every delivery held past its state's bound, with the transition the table lets healer H2 take for it, or none." + case VerbRecovery: + return "Mark a merge its author names a recovery: the commit and why; the delivery record is marked recovery with the caller the runtime proves, and recovery-merged is said (design 47 G section 305)." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventOwed, EventRecordOpened, EventRecordEnded, EventFilling, EventFull, EventRoom, EventSourceMoved, EventRecoveryMerged} diff --git a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go index 4067876f5..4b4d21351 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go @@ -14,13 +14,13 @@ const Seat = "mesh-pipeline-runner" // Form is the form of the seat's values, events and answers this contract was generated at (design 47 H2 §780): // a reader of a value of another form says "form N, this reader knows M". -const Form = 5 +const Form = 6 // The forms and the digest of the fields this contract was generated from: the generator's compare fails a definition // whose fields changed while its forms did not (design 47 H2 §780). const ( - generatedForms = "5" - generatedFieldsDigest = "AcceptAnswer=224df0394653 Accepted=d2b011e5090f AskAgainAnswer=224df0394653 CancelAnswer=a0dcc32b3f57 EndAgainAnswer=a0dcc32b3f57 Fill=7a76c9ceb157 FillingEvent=5bd4df78ed84 FullEvent=5bd4df78ed84 KeptAnswer=dfe0d48bc169 KeptByLevelDigestValue=f06c90f7da7f KeptResult=af5f81f189b7 ListAnswer=75717fd670a7 LogEntry=b059967b2ae4 Member=8a103baec01f Mover=5db376275bcf MoverEnded=4b35095f6829 Pipeline=2663792125bf PipelineEnded=523f8fc0fe41 PipelineEndedEvent=cb44007f7173 PipelineEndedPhases=9d1c33ce4cc4 PipelineEndedPhasesBuild=a08d49692a09 PipelineEndedPhasesComposition=a08d49692a09 PipelineEndedPhasesIntegration=a08d49692a09 PipelineEndedPhasesLint=a08d49692a09 PipelineEndedPhasesUnit=a08d49692a09 PipelineEndedPhasesValidate=a08d49692a09 PipelineStarted=a3d000f095db PipelineStartedEvent=eaa401af4117 PipelinesByBranchRevisionUnfinishedModuleValue=693580eed498 PipelinesByBranchRevisionValue=693580eed498 PipelinesByBranchRunRunValue=693580eed498 PipelinesByBranchSourcePublishedPackageVersionValue=693580eed498 PipelinesByStepsPipelineMoverValue=94de99db7816 PlaceAnswer=a0dcc32b3f57 PlaceUnfinishedAnswer=ed94ced4513a Published=d9af3024dacc QueueByQueueNextValue=765a2918a728 QueueByRunningPipelineValue=ed94ced4513a QueueByWaitingSequenceValue=99605298ae13 RePinnedEvent=92fd04bfa6d3 RerunAnswer=9b7efd0df344 ReviewAnswer=f397b8965179 RoomEvent=5bd4df78ed84 RunAnswer=96bd45aa2e62 RunStarted=b280617410c3 RunStartedEvent=0767a9358fa3 Shared=c981cf6aa860 SharedAskedBy=c9b30cc4d0d0 ShowAnswer=ab5b72044ab6 StandsAnswer=0afa3693bf3b StartAnswer=ed94ced4513a StepEndedEvent=799020642c19 StepEvent=64f18c40ed5d StepLogByPipelineValue=ffdde090a101 StepResult=0dac0e15d017 StepStartedEvent=799020642c19 TestCounts=9c1332427159 TestRun=ca5a87f3b6b8 TestRunPackage=a7d30558470d TestRunReader=c9b30cc4d0d0 TestRunsAnswer=7ab81a45ca33 TestRunsDropAnswer=8ee70b35469d ToolchainUsed=43b6d42376fb Wait=21e4ee7a3ef1 WaitEndedEvent=2bf6d38041c0 WaitHeldEvent=2bf6d38041c0 Waiting=ed94ced4513a WhyCarriedAnswer=8e2fcea6479f Widening=e2790a307466" + generatedForms = "6" + generatedFieldsDigest = "AcceptAnswer=224df0394653 Accepted=d2b011e5090f AskAgainAnswer=224df0394653 CancelAnswer=a0dcc32b3f57 EndAgainAnswer=a0dcc32b3f57 FailedStep=cd7184342136 Fill=7a76c9ceb157 FillingEvent=5bd4df78ed84 FullEvent=5bd4df78ed84 KeptAnswer=dfe0d48bc169 KeptByLevelDigestValue=f06c90f7da7f KeptResult=af5f81f189b7 ListAnswer=284210b3c054 LogEntry=b059967b2ae4 Member=8a103baec01f Mover=5db376275bcf MoverEnded=4b35095f6829 MoverRow=b61f41d131a3 Pipeline=2663792125bf PipelineEnded=523f8fc0fe41 PipelineEndedEvent=cb44007f7173 PipelineEndedPhases=9d1c33ce4cc4 PipelineEndedPhasesBuild=a08d49692a09 PipelineEndedPhasesComposition=a08d49692a09 PipelineEndedPhasesIntegration=a08d49692a09 PipelineEndedPhasesLint=a08d49692a09 PipelineEndedPhasesUnit=a08d49692a09 PipelineEndedPhasesValidate=a08d49692a09 PipelineRow=64600be410e9 PipelineStarted=a3d000f095db PipelineStartedEvent=eaa401af4117 PipelinesByBranchRevisionUnfinishedModuleValue=693580eed498 PipelinesByBranchRevisionValue=693580eed498 PipelinesByBranchRunRunValue=693580eed498 PipelinesByBranchSourcePublishedPackageVersionValue=693580eed498 PipelinesByStepsPipelineMoverValue=94de99db7816 PlaceAnswer=a0dcc32b3f57 PlaceUnfinishedAnswer=ed94ced4513a Published=d9af3024dacc QueueByQueueNextValue=765a2918a728 QueueByRunningPipelineValue=ed94ced4513a QueueByWaitingSequenceValue=99605298ae13 RePinnedEvent=92fd04bfa6d3 RerunAnswer=9b7efd0df344 ReviewAnswer=f397b8965179 RoomEvent=5bd4df78ed84 RunAnswer=96bd45aa2e62 RunStarted=b280617410c3 RunStartedEvent=0767a9358fa3 Shared=c981cf6aa860 SharedAskedBy=c9b30cc4d0d0 ShowAnswer=48b8cecc529a StandsAnswer=0afa3693bf3b StartAnswer=ed94ced4513a StepEndedEvent=799020642c19 StepEvent=64f18c40ed5d StepLogByPipelineValue=ffdde090a101 StepResult=0dac0e15d017 StepStartedEvent=799020642c19 TestCounts=9c1332427159 TestRun=ca5a87f3b6b8 TestRunPackage=a7d30558470d TestRunReader=c9b30cc4d0d0 TestRunsAnswer=7ab81a45ca33 TestRunsDropAnswer=8ee70b35469d ToolchainUsed=43b6d42376fb Wait=21e4ee7a3ef1 WaitEndedEvent=2bf6d38041c0 WaitHeldEvent=2bf6d38041c0 Waiting=ed94ced4513a WhyCarriedAnswer=8e2fcea6479f Widening=e2790a307466" ) const ( @@ -62,6 +62,48 @@ func Verbs() []string { return []string{VerbRun, VerbStart, VerbShow, VerbList, VerbStands, VerbWhyCarried, VerbKept, VerbReview, VerbRerun, VerbAccept, VerbCancel, VerbEndAgain, VerbPlace, VerbPlaceUnfinished, VerbAskAgain, VerbTestRuns, VerbTestRunsDrop} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbRun: + return "The run on request of one or more members, each a module at a named commit, through their pipelines; delivers nothing, replacing the checker's try (ADR 0666 section 18). Says run-started." + case VerbStart: + return "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log." + case VerbShow: + return "One pipeline: naming a mover, its steps alone; with no mover, each mover's row (its module, outcome and failed step), never every step of every mover, or the steps of any mover the step and state filters hold; and its step log, with the stores' fill (design 47 H2 §789, H-A-376). Reads only." + case VerbList: + return "The pipelines and runs of a module, a branch or a commit, newest first: by default one short row per pipeline, the newest 20 (its key, call, start, end, outcome, movers' count and first failed or could-not-run step with its module and why); the whole pipelines, each record with its movers and steps counted, never its steps (show gives those), only with full and a limit (design 47 H2 H-A-376). Reads only." + case VerbStands: + return "What stands still, and since when: each step not ended and each wait held. Reads only." + case VerbWhyCarried: + return "Where a step's result was carried from, with the kept results it rests on. Reads only." + case VerbKept: + return "The kept results, by digest, package or level, with the store's fill. Reads only." + case VerbReview: + return "A code review's result for a commit and fingerprint, taken from the reviewer's account and refused from the commit's author (ADR 0666 section 22)." + case VerbRerun: + return "One step again; its step-ended says it is a rerun and the caller the runtime proved. Written in the hand-act log." + case VerbAccept: + return "A failed optional step accepted, with who and why, in the hand-act log." + case VerbCancel: + return "A pipeline ended cancelled, its waiting asks dropped by each build seat's drop. Written in the hand-act log." + case VerbEndAgain: + return "A running pipeline's end judged once more, as at a step's end: it ends when it can, failed as soon as it can no longer pass (design 47 H §746, H-A-163, H-A-164). Written in the hand-act log." + case VerbPlace: + return "A waiting pipeline placed ahead of its turn, its steps asked now; written in the hand-act log (design 47 H §748, H-A-53)." + case VerbPlaceUnfinished: + return "A mover kept in the state unfinished put in a pipeline of its own at once, keyed ..unfinished.; written in the hand-act log (design 47 H2 §786, H-A-398)." + case VerbAskAgain: + return "A declined approval step asked again (ADR 0666 section 10). Written in the hand-act log." + case VerbTestRuns: + return "Each test run the runner keeps (design 47 G §728): its packages read from its output object, ask, node, readers, outcome and counts, and the state's fill against its cap; with candidate, level, digest or module, only those." + case VerbTestRunsDrop: + return "Drop one test run by hand (design 47 G §728): the act and why are written in the hand-act log first, then the run's ask is dropped, each reader ended could not run naming the drop, and the key deleted with the run's output object." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPipelineStarted, EventPipelineEnded, EventRunStarted, EventStepStarted, EventStepEnded, EventWaitHeld, EventWaitEnded, EventRePinned, EventFilling, EventFull, EventRoom} @@ -499,6 +541,28 @@ type Accepted struct { Why string `json:"why"` } +// FailedStep is the first step of a pipeline or mover that failed or could not run, with its module and why (design 47 H2 H-A-376). +type FailedStep struct { + Artifact string `json:"artifact,omitempty"` + Module string `json:"module"` + // the step's outcome: failed, could not run or did not build + Outcome string `json:"outcome"` + Step string `json:"step"` + Why string `json:"why,omitempty"` +} + +// The values of FailedStep's step. +const ( + FailedStepStepValidate = "validate" + FailedStepStepBuild = "build" + FailedStepStepLint = "lint" + FailedStepStepUnit = "unit" + FailedStepStepIntegration = "integration" + FailedStepStepComposition = "composition" + FailedStepStepReview = "review" + FailedStepStepApproval = "approval" +) + // Fill is a store's fill against its cap. type Fill struct { At *time.Time `json:"at,omitempty"` @@ -632,6 +696,23 @@ type MoverEnded struct { Widens []Widening `json:"widens,omitempty"` } +// MoverRow is one mover of a pipeline in show's short form (design 47 H2 H-A-376). +type MoverRow struct { + Failed *FailedStep `json:"failed,omitempty"` + Module string `json:"module"` + // waiting for a mover with no step placed; running while a required step is open; failed once a required step did not pass; superseded for one a newer pipeline took out + Outcome string `json:"outcome"` +} + +// The values of MoverRow's outcome. +const ( + MoverRowOutcomeWaiting = "waiting" + MoverRowOutcomeRunning = "running" + MoverRowOutcomePassed = "passed" + MoverRowOutcomeFailed = "failed" + MoverRowOutcomeSuperseded = "superseded" +) + // Pipeline is one pipeline of one take-in, its movers the take-in's entries, as the runner keeps it in its state pipelines by compare-and-set (design 47 H §746). type Pipeline struct { // the watched branch, or the branch of a run on request @@ -798,6 +879,31 @@ const ( PipelineEndedOutcomeCancelled = "cancelled" ) +// PipelineRow is one pipeline in list's short form (design 47 H2 H-A-376). +type PipelineRow struct { + // the merge call whose source revision the take-in took in + Call string `json:"call,omitempty"` + Ended *time.Time `json:"ended,omitempty"` + Failed *FailedStep `json:"failed,omitempty"` + // how many movers the pipeline has + MoverCount int64 `json:"mover-count"` + Outcome string `json:"outcome"` + // the pipeline's key + Pipeline string `json:"pipeline"` + Started *time.Time `json:"started,omitempty"` +} + +// The values of PipelineRow's outcome. +const ( + PipelineRowOutcomeWaiting = "waiting" + PipelineRowOutcomeRunning = "running" + PipelineRowOutcomePassed = "passed" + PipelineRowOutcomeFailed = "failed" + PipelineRowOutcomeRefused = "refused" + PipelineRowOutcomeSuperseded = "superseded" + PipelineRowOutcomeCancelled = "cancelled" +) + // PipelineStarted is a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52). type PipelineStarted struct { At *time.Time `json:"at,omitempty"` @@ -1146,7 +1252,7 @@ type StartAnswer struct { // ShowInput is what show takes. type ShowInput struct { - // a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187) + // a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187); with neither mover, step nor state the answer holds each mover's row (design 47 H2 H-A-376) Mover string `json:"mover,omitempty"` // the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779, §789) Next string `json:"next,omitempty"` @@ -1178,10 +1284,12 @@ type ShowAnswer struct { // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). Form int64 `json:"form,omitempty"` Log []LogEntry `json:"log,omitempty"` + // each mover's row, when show names no mover, step or state (design 47 H2 H-A-376) + Movers []MoverRow `json:"movers,omitempty"` // the cursor of the next page, opaque; empty at the end (design 47 H2 §779) Next string `json:"next,omitempty"` Pipeline Pipeline `json:"pipeline"` - // how many steps the filters hold in all (design 47 H2 §789) + // how many steps the filters hold in all, or how many movers for the movers' rows (design 47 H2 §789, H-A-376) Total int64 `json:"total,omitempty"` } @@ -1189,6 +1297,9 @@ type ShowAnswer struct { type ListInput struct { Branch string `json:"branch,omitempty"` Commit string `json:"commit,omitempty"` + // answer the whole pipelines in place of the rows, with a limit (design 47 H2 H-A-376) + Full bool `json:"full,omitempty"` + // at most this many, newest first; the rows default to 20, and full needs one (design 47 H2 H-A-376) Limit int64 `json:"limit,omitempty"` Module string `json:"module,omitempty"` Run string `json:"run,omitempty"` @@ -1198,8 +1309,11 @@ type ListInput struct { type ListAnswer struct { Fill *Fill `json:"fill,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). - Form int64 `json:"form,omitempty"` - Pipelines []Pipeline `json:"pipelines"` + Form int64 `json:"form,omitempty"` + // the whole pipelines, only with full (design 47 H2 H-A-376) + Pipelines []Pipeline `json:"pipelines,omitempty"` + // one short row per pipeline, without full (design 47 H2 H-A-376) + Rows []PipelineRow `json:"rows,omitempty"` } // StandsInput is what stands takes. diff --git a/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go b/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go index e83bbf8e2..e661349ab 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go @@ -60,6 +60,32 @@ func Verbs() []string { return []string{VerbUpgrade, VerbBus, VerbRevision, VerbEntry, VerbDifference, VerbInput, VerbCompositions, VerbCompositionsDrop, VerbDrop} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbUpgrade: + return "Whether each module's new builds wait for a person: its policy (roll, together or record) and where it comes from (a person, the module, the bus, its irreplaceable data, the default); the bus is never rolled. With module, that one; with module, policy and why, a person's choice for it, recorded as a hand act; with policy default, the choice taken back. With compare, each node's own composition and the assigner's findings." + case VerbBus: + return "What a bus upgrade would do: the fingerprint of the bus module each node runs against the indexer's newest, and the last bus steps from the hand-act log and the assigner's puts of the bus. Read-only: the step itself is the put on the operator's warrant." + case VerbRevision: + return "The assignment half of the revision view (ADR 0656 §6): one assignment graph revision, named by its own number and naming its inputs, with its entries' digests; the trunk's newest when none is named, or a candidate's for its group and heads. Reads only." + case VerbEntry: + return "One entry of an assignment graph revision whole, by its digest or by its node and module in a revision, with the seat rule that gave each edge. Reads only." + case VerbDifference: + return "A change's graph difference, which is its delivery: two kept revisions compared, or a candidate's newest against trunk's newest, with the changed module versions, the touched nodes and the order as tiers. Reads only." + case VerbInput: + return "A step's input by its digest, as the assigner keeps it for the composition step it asked a build seat to run (design 47 G section 354): its fields, then the 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 input is of any size." + case VerbCompositions: + return "Each composition run the assigner keeps (design 47 G §728): its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap; with candidate or machine, only those." + case VerbCompositionsDrop: + return "Drop one composition run by hand (design 47 G §728): the act and why are written in the hand-act log first, then the run's ask is dropped, each reader ended could not run naming the drop, and the key deleted." + case VerbDrop: + return "End an ask on the seat's work queue for a caller that no longer waits for it (its step ended by its bound): one waiting is ended dropped when it is pulled, one taken is cancelled; both end the step dropped, naming who dropped it and why, so no holder works on it after (design 47 H2 §778; ADR 0664 §4)." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPolicyChanged, EventAssignmentRevision, EventDifference, EventWanted, EventPipelineWanted, EventWaitHeld, EventWaitEnded, EventFilling, EventFull, EventRoom, EventStepEnded, EventStepProgress, EventAskTaken} diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go index bc85bbf36..0e554b75d 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go @@ -58,6 +58,30 @@ func Verbs() []string { return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop, VerbKeptArtifact, VerbSteps, VerbAnswer, VerbOutput} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbCurrent: + return "What this node's holder takes and runs (design 47 H2 §801, H-A-367 (2)): whether it takes asks and why not (paused, capacity 0, unhealthy) since when, its capacity, and every ask it runs, whoever asked it (the builder's delivery asks included)." + case VerbPause: + return "Take no new ask on this node until resumed; an ask running here ends in its place. Kept across a restart of the build module. A capacity of 0 is the lasting way to keep a node from building." + case VerbResume: + return "Take asks again on this node." + case VerbDrop: + return "End an ask this node holds for a caller that no longer waits for it: a step not yet running is ended dropped when the bus gives it, one running is cancelled; both end the step dropped, naming who dropped it and why. Writes dropped. in the pauses state; the build module removes the key when it has acted." + case VerbKeptArtifact: + return "The one build this node keeps instead of storing it through the seat oci-artifact-registry: the new build of that seat's holder, when the running holder refused or did not answer the store (design 47 *The artifact store's holder takes its own new build even when its seat is the one broken*). Answers where the bytes are, as an object by their digest on the bus (the old objects form, ADR 0619 §2), never in the answer; the node-engine checks what it fetched against the digest and applies nothing that differs. A module that claims no oci-artifact-registry is refused by name, so a store outage never becomes a delivery from build nodes; so is a build this node no longer keeps, or keeps under another digest." + case VerbSteps: + return "Which pipeline steps an artifact can run, found by its language's convention (design 47 *Pipeline steps and the policy*): lint always, unit and integration tests where its packages hold them. Kept by the artifact's fingerprint; again finds them anew. With drop and why it deletes the artifact's kept key instead, writes the act in the hand-act log of the seat mesh-hand-acts first (a log that refuses deletes nothing and answers error), and answers dropped (design 47 G section 463, section 480)." + case VerbAnswer: + return "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." + case VerbOutput: + return "A step's output by its ask (design 47 H2 §791, H-A-367 (1)): the output's last 64 KB, its size, the failing tests with their words, or no longer kept once past the outputs objects' max-age. Asked by the runner's runner_step_output of the holder on the node the step key names." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventStepEnded, EventToolchainReported, EventStepProgress, EventAskTaken} diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go index 58001b46b..a9f455217 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go @@ -57,6 +57,30 @@ func Verbs() []string { return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop, VerbKeptArtifact, VerbSteps, VerbAnswer, VerbOutput} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbCurrent: + return "What this node's holder takes and runs (design 47 H2 §801, H-A-367 (2)): whether it takes asks and why not (paused, capacity 0, unhealthy) since when, its capacity, and every ask it runs, whoever asked it (the builder's delivery asks included)." + case VerbPause: + return "Take no new ask on this node until resumed; an ask running here ends in its place. Kept across a restart of the build module. A capacity of 0 is the lasting way to keep a node from building." + case VerbResume: + return "Take asks again on this node." + case VerbDrop: + return "End an ask this node holds for a caller that no longer waits for it: a step not yet running is ended dropped when the bus gives it, one running is cancelled; both end the step dropped, naming who dropped it and why. Writes dropped. in the pauses state; the build module removes the key when it has acted." + case VerbKeptArtifact: + return "The one build this node keeps instead of storing it through the seat oci-artifact-registry: the new build of that seat's holder, when the running holder refused or did not answer the store (design 47 *The artifact store's holder takes its own new build even when its seat is the one broken*). Answers where the bytes are, as an object by their digest on the bus (the old objects form, ADR 0619 §2), never in the answer; the node-engine checks what it fetched against the digest and applies nothing that differs. A module that claims no oci-artifact-registry is refused by name, so a store outage never becomes a delivery from build nodes; so is a build this node no longer keeps, or keeps under another digest." + case VerbSteps: + return "Which pipeline steps an artifact can run, found by its language's convention (design 47 *Pipeline steps and the policy*): lint always, unit and integration tests where its packages hold them. Kept by the artifact's fingerprint; again finds them anew. With drop and why it deletes the artifact's kept key instead, writes the act in the hand-act log of the seat mesh-hand-acts first (a log that refuses deletes nothing and answers error), and answers dropped (design 47 G section 463, section 480)." + case VerbAnswer: + return "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." + case VerbOutput: + return "A step's output by its ask (design 47 H2 §791, H-A-367 (1)): the output's last 64 KB, its size, the failing tests with their words, or no longer kept once past the outputs objects' max-age. Asked by the runner's runner_step_output of the holder on the node the step key names." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventStepEnded, EventToolchainReported, EventStepProgress, EventAskTaken} diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go index dc17437a1..5ad230739 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go @@ -58,6 +58,30 @@ func Verbs() []string { return []string{VerbCurrent, VerbPause, VerbResume, VerbDrop, VerbKeptArtifact, VerbSteps, VerbAnswer, VerbOutput} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbCurrent: + return "What this node's holder takes and runs (design 47 H2 §801, H-A-367 (2)): whether it takes asks and why not (paused, capacity 0, unhealthy) since when, its capacity, and every ask it runs, whoever asked it (the builder's delivery asks included)." + case VerbPause: + return "Take no new ask on this node until resumed; an ask running here ends in its place. Kept across a restart of the build module. A capacity of 0 is the lasting way to keep a node from building." + case VerbResume: + return "Take asks again on this node." + case VerbDrop: + return "End an ask this node holds for a caller that no longer waits for it: a step not yet running is ended dropped when the bus gives it, one running is cancelled; both end the step dropped, naming who dropped it and why. Writes dropped. in the pauses state; the build module removes the key when it has acted." + case VerbKeptArtifact: + return "The one build this node keeps instead of storing it through the seat oci-artifact-registry: the new build of that seat's holder, when the running holder refused or did not answer the store (design 47 *The artifact store's holder takes its own new build even when its seat is the one broken*). Answers where the bytes are, as an object by their digest on the bus (the old objects form, ADR 0619 §2), never in the answer; the node-engine checks what it fetched against the digest and applies nothing that differs. A module that claims no oci-artifact-registry is refused by name, so a store outage never becomes a delivery from build nodes; so is a build this node no longer keeps, or keeps under another digest." + case VerbSteps: + return "Which pipeline steps an artifact can run, found by its language's convention (design 47 *Pipeline steps and the policy*): lint always, unit and integration tests where its packages hold them. Kept by the artifact's fingerprint; again finds them anew. With drop and why it deletes the artifact's kept key instead, writes the act in the hand-act log of the seat mesh-hand-acts first (a log that refuses deletes nothing and answers error), and answers dropped (design 47 G section 463, section 480)." + case VerbAnswer: + return "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." + case VerbOutput: + return "A step's output by its ask (design 47 H2 §791, H-A-367 (1)): the output's last 64 KB, its size, the failing tests with their words, or no longer kept once past the outputs objects' max-age. Asked by the runner's runner_step_output of the holder on the node the step key names." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventStepEnded, EventToolchainReported, EventStepProgress, EventAskTaken} diff --git a/modules/mesh-delivery-contracts/go/seats/npmpackageregistry/contract.go b/modules/mesh-delivery-contracts/go/seats/npmpackageregistry/contract.go index f040a1268..594e71009 100644 --- a/modules/mesh-delivery-contracts/go/seats/npmpackageregistry/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/npmpackageregistry/contract.go @@ -43,6 +43,22 @@ func Verbs() []string { return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbPublish: + return "Open a transfer, naming the artifact and the digest of every part; answers the digests the holder lacks, which the caller then sends by publish-part. A transfer already open answers the parts held, so a cut transfer goes on from there. With no parts and a version, the held digest is published under that version and nothing is stored (the trunk's claim)." + case VerbPublishPart: + return "Send one chunk of one part of an open transfer; the last chunk of the last part ends the transfer, and the holder hashes what it received, asks builder_versions, stores it and says published or refused. A chunk's message stays under the bus's largest message (1 MiB), so at most 760 KiB of data, base64." + case VerbVersions: + return "The versions the seat holds of one name, newest first: each one's version, tag, digest, kind and when it was published." + case VerbRemove: + return "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base, which the artifact sweep's holder asks; the caller is not judged (design 47 H2 §813 (7)). Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPublished, EventRefused, EventRemoved, EventKept} diff --git a/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go b/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go index 0aeea3ac0..e327ef168 100644 --- a/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go @@ -49,6 +49,28 @@ func Verbs() []string { return []string{VerbPublish, VerbPublishPart, VerbVersions, VerbRemove, VerbHold, VerbRelease, VerbList} } +// VerbDescription is a verb's description as the seat's definition says it, "" for a verb the seat does not serve or +// does not describe (design 47 H2 H-A-449). +func VerbDescription(verb string) string { + switch verb { + case VerbPublish: + return "Open a transfer, naming the artifact and the digest of every part; answers the digests the holder lacks, which the caller then sends by publish-part. A transfer already open answers the parts held, so a cut transfer goes on from there. With no parts and a version, the held digest is published under that version and nothing is stored (the trunk's claim)." + case VerbPublishPart: + return "Send one chunk of one part of an open transfer; the last chunk of the last part ends the transfer, and the holder hashes what it received, asks builder_versions, stores it and says published or refused. A chunk's message stays under the bus's largest message (1 MiB), so at most 760 KiB of data, base64." + case VerbVersions: + return "The versions the seat holds of one name, newest first: each one's version, tag, digest, kind and when it was published." + case VerbRemove: + return "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base, which the artifact sweep's holder asks; the caller is not judged (design 47 H2 §813 (7)). Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry." + case VerbHold: + return "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 §2); never an image of the holder's own. Emits held." + case VerbRelease: + return "Let a hold go; emits released. A release of what is not held answers released false and emits nothing, never an error: the outcome asked holds already. By hand only through the holder's own tool, the operator's session as the proved caller, recorded as a hand act." + case VerbList: + return "What the store holds of one repository, or of every repository the seat holds when none is named: every manifest keeping one bundle or archive, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 §3). Filtered by name or module while it reads and paged by the cursor next, at most 768 KB a page, capped saying the rest is read from next (design 47 H2 §779, §811, §813 (7))." + } + return "" +} + // Events is every event published on the seat's subject: a new copy each call. func Events() []string { return []string{EventPublished, EventRefused, EventRemoved, EventKept, EventHeld, EventReleased} diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json index 0a05b98ba..7c49d7d1c 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json @@ -86,7 +86,7 @@ }, { "name": "show", - "description": "One pipeline whole: its record with every mover's steps (one mover's steps alone when it names the mover) and its step log, with the stores' fill. Reads only.", + "description": "One pipeline: naming a mover, its steps alone; with no mover, each mover's row (its module, outcome and failed step), never every step of every mover, or the steps of any mover the step and state filters hold; and its step log, with the stores' fill (design 47 H2 §789, H-A-376). Reads only.", "input": { "type": "object", "properties": { @@ -96,7 +96,7 @@ }, "mover": { "type": "string", - "description": "a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187)" + "description": "a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187); with neither mover, step nor state the answer holds each mover's row (design 47 H2 H-A-376)" }, "step": { "type": "string", @@ -149,11 +149,18 @@ }, "total": { "type": "integer", - "description": "how many steps the filters hold in all (design 47 H2 §789)" + "description": "how many steps the filters hold in all, or how many movers for the movers' rows (design 47 H2 §789, H-A-376)" }, "next": { "type": "string", "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" + }, + "movers": { + "type": "array", + "items": { + "$ref": "#/defs/MoverRow" + }, + "description": "each mover's row, when show names no mover, step or state (design 47 H2 H-A-376)" } }, "required": [ @@ -164,7 +171,7 @@ }, { "name": "list", - "description": "The pipelines and runs of a module, a branch or a commit, newest first, with the store's fill: each pipeline's record with its movers and steps counted, never its steps (show gives those). Reads only.", + "description": "The pipelines and runs of a module, a branch or a commit, newest first: by default one short row per pipeline, the newest 20 (its key, call, start, end, outcome, movers' count and first failed or could-not-run step with its module and why); the whole pipelines, each record with its movers and steps counted, never its steps (show gives those), only with full and a limit (design 47 H2 H-A-376). Reads only.", "input": { "type": "object", "properties": { @@ -181,26 +188,37 @@ "type": "string" }, "limit": { - "type": "integer" + "type": "integer", + "description": "at most this many, newest first; the rows default to 20, and full needs one (design 47 H2 H-A-376)" + }, + "full": { + "type": "boolean", + "description": "answer the whole pipelines in place of the rows, with a limit (design 47 H2 H-A-376)" } } }, "answer": { "type": "object", "properties": { + "rows": { + "type": "array", + "items": { + "$ref": "#/defs/PipelineRow" + }, + "description": "one short row per pipeline, without full (design 47 H2 H-A-376)" + }, "pipelines": { "type": "array", "items": { "$ref": "#/defs/Pipeline" - } + }, + "description": "the whole pipelines, only with full (design 47 H2 H-A-376)" }, "fill": { "$ref": "#/defs/Fill" } }, - "required": [ - "pipelines" - ] + "required": [] }, "class": "read" }, @@ -2208,7 +2226,117 @@ "required": [ "pipeline" ] + }, + "FailedStep": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ] + }, + "artifact": { + "type": "string" + }, + "outcome": { + "type": "string", + "description": "the step's outcome: failed, could not run or did not build" + }, + "why": { + "type": "string" + } + }, + "description": "the first step of a pipeline or mover that failed or could not run, with its module and why (design 47 H2 H-A-376)", + "required": [ + "module", + "step", + "outcome" + ] + }, + "PipelineRow": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "call": { + "type": "string", + "description": "the merge call whose source revision the take-in took in" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "outcome": { + "type": "string", + "enum": [ + "waiting", + "running", + "passed", + "failed", + "refused", + "superseded", + "cancelled" + ] + }, + "mover-count": { + "type": "integer", + "description": "how many movers the pipeline has" + }, + "failed": { + "$ref": "#/defs/FailedStep" + } + }, + "description": "one pipeline in list's short form (design 47 H2 H-A-376)", + "required": [ + "pipeline", + "outcome", + "mover-count" + ] + }, + "MoverRow": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "outcome": { + "type": "string", + "enum": [ + "waiting", + "running", + "passed", + "failed", + "superseded" + ], + "description": "waiting for a mover with no step placed; running while a required step is open; failed once a required step did not pass; superseded for one a newer pipeline took out" + }, + "failed": { + "$ref": "#/defs/FailedStep" + } + }, + "description": "one mover of a pipeline in show's short form (design 47 H2 H-A-376)", + "required": [ + "module", + "outcome" + ] } }, - "form": 5 + "form": 6 } diff --git a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts index 02eb103dd..9a8f438e6 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts @@ -165,6 +165,16 @@ export interface Accepted { "why": string; } +/** the first step of a pipeline or mover that failed or could not run, with its module and why (design 47 H2 H-A-376) */ +export interface FailedStep { + "artifact"?: string; + "module": string; + /** the step's outcome: failed, could not run or did not build */ + "outcome": string; + "step": "validate" | "build" | "lint" | "unit" | "integration" | "composition" | "review" | "approval"; + "why"?: string; +} + /** a store's fill against its cap */ export interface Fill { "at"?: string; @@ -258,6 +268,14 @@ export interface MoverEnded { "widens"?: Widening[]; } +/** one mover of a pipeline in show's short form (design 47 H2 H-A-376) */ +export interface MoverRow { + "failed"?: FailedStep; + "module": string; + /** waiting for a mover with no step placed; running while a required step is open; failed once a required step did not pass; superseded for one a newer pipeline took out */ + "outcome": "waiting" | "running" | "passed" | "failed" | "superseded"; +} + /** one pipeline of one take-in, its movers the take-in's entries, as the runner keeps it in its state pipelines by compare-and-set (design 47 H §746) */ export interface Pipeline { /** the watched branch, or the branch of a run on request */ @@ -402,6 +420,20 @@ export interface PipelineEnded { "why"?: string; } +/** one pipeline in list's short form (design 47 H2 H-A-376) */ +export interface PipelineRow { + /** the merge call whose source revision the take-in took in */ + "call"?: string; + "ended"?: string; + "failed"?: FailedStep; + /** how many movers the pipeline has */ + "mover-count": number; + "outcome": "waiting" | "running" | "passed" | "failed" | "refused" | "superseded" | "cancelled"; + /** the pipeline's key */ + "pipeline": string; + "started"?: string; +} + /** a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52) */ export interface PipelineStarted { "at"?: string; @@ -675,7 +707,7 @@ export interface StartAnswer { /** is what show takes. */ export interface ShowInput { - /** a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187) */ + /** a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187); with neither mover, step nor state the answer holds each mover's row (design 47 H2 H-A-376) */ "mover"?: string; /** the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779, §789) */ "next"?: string; @@ -695,10 +727,12 @@ export interface ShowAnswer { /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ "form"?: number; "log"?: LogEntry[]; + /** each mover's row, when show names no mover, step or state (design 47 H2 H-A-376) */ + "movers"?: MoverRow[]; /** the cursor of the next page, opaque; empty at the end (design 47 H2 §779) */ "next"?: string; "pipeline": Pipeline; - /** how many steps the filters hold in all (design 47 H2 §789) */ + /** how many steps the filters hold in all, or how many movers for the movers' rows (design 47 H2 §789, H-A-376) */ "total"?: number; } @@ -706,6 +740,9 @@ export interface ShowAnswer { export interface ListInput { "branch"?: string; "commit"?: string; + /** answer the whole pipelines in place of the rows, with a limit (design 47 H2 H-A-376) */ + "full"?: boolean; + /** at most this many, newest first; the rows default to 20, and full needs one (design 47 H2 H-A-376) */ "limit"?: number; "module"?: string; "run"?: string; @@ -716,7 +753,10 @@ export interface ListAnswer { "fill"?: Fill; /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ "form"?: number; - "pipelines": Pipeline[]; + /** the whole pipelines, only with full (design 47 H2 H-A-376) */ + "pipelines"?: Pipeline[]; + /** one short row per pipeline, without full (design 47 H2 H-A-376) */ + "rows"?: PipelineRow[]; } /** is what stands takes. */ diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel.go index 122f174f3..2304f84a8 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel.go @@ -4,6 +4,7 @@ import ( "encoding/json" "errors" "fmt" + "math" "strings" seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner" @@ -62,7 +63,8 @@ func (in CancelInput) run(list func(seat.ListInput) (seat.ListAnswer, error), as if branch == "" { branch = "main" } - listed := seat.ListInput{} + // Every pipeline's record, read whole in this program, not over the bus (list's full needs a limit, H-A-376). + listed := seat.ListInput{Full: true, Limit: math.MaxInt64} if in.BelowSource != nil { listed.Branch = branch } @@ -119,7 +121,8 @@ func (in CancelInput) afterUnanswered(name string, asked error, list func(seat.L if branch == "" { branch = "main" } - listed := seat.ListInput{} + // Every pipeline's record, read whole in this program, not over the bus (list's full needs a limit, H-A-376). + listed := seat.ListInput{Full: true, Limit: math.MaxInt64} if in.BelowSource != nil { listed.Branch = branch } diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel_test.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel_test.go index 3dca06ce3..6061f0b20 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel_test.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/cancel_test.go @@ -18,6 +18,10 @@ func TestCancelTool(t *testing.T) { all := []seat.Pipeline{pl("main.1.a", "main", "running", 1), pl("main.2.b", "main", "running", 5), pl("main.1.c", "main", "passed", 1), pl("x.1.d", "x", "running", 1)} list := func(in seat.ListInput) (seat.ListAnswer, error) { + // Design 47 H2 H-A-376: the rows answer no source; cancel reads the whole pipelines, every one. + if !in.Full || in.Limit < int64(len(all)) { + return seat.ListAnswer{}, nil + } var out []seat.Pipeline for _, p := range all { if in.Branch == "" || p.Branch == in.Branch { diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go index 5285e15dd..6404b644a 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main.go @@ -82,7 +82,8 @@ func Tools(r pipeline.Reads) []stdio.Tool { var out []stdio.Tool for _, v := range seat.Verbs() { if run, ok := runs[v]; ok { - out = append(out, stdio.Tool{Name: seat.Seat + "." + v, Run: run}) + // Each described as the seat's definition says it, read from its contract (design 47 H2 H-A-376, H-A-449). + out = append(out, stdio.Tool{Name: seat.Seat + "." + v, Description: seat.VerbDescription(v), Run: run}) } } return out diff --git a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go index b697cbb05..c8392a828 100644 --- a/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go +++ b/modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline-tools/main_test.go @@ -9,6 +9,7 @@ import ( "testing" "time" + seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner" stdio "git.novox.be/novox/mesh-sdk/go" "git.novox.be/novox/mesh-sdk/go/views" @@ -27,6 +28,10 @@ func TestTools(t *testing.T) { var names []string for _, tl := range Tools(pipeline.Reads{Pipelines: none{}, Kept: none{}}) { names = append(names, tl.Name) + // Design 47 H2 H-A-376, H-A-449: each seat verb's tool is described as the seat's definition says it. + if v := strings.TrimPrefix(tl.Name, seat.Seat+"."); tl.Description == "" || tl.Description != seat.VerbDescription(v) { + t.Errorf("the tool %s is described %q, want the seat's description of %s", tl.Name, tl.Description, v) + } } for _, tl := range FirstViewTools("the-runner", stdio.State(views.StatusState), nil, nil) { names = append(names, tl.Name) diff --git a/modules/mesh-delivery-pipeline/internal/pipeline/read.go b/modules/mesh-delivery-pipeline/internal/pipeline/read.go index 4a6b9b7ba..0dc31a785 100644 --- a/modules/mesh-delivery-pipeline/internal/pipeline/read.go +++ b/modules/mesh-delivery-pipeline/internal/pipeline/read.go @@ -5,7 +5,9 @@ package pipeline import ( "encoding/base64" "encoding/json" + "errors" "fmt" + "slices" "sort" "strconv" "strings" @@ -68,6 +70,24 @@ func (r Reads) Show(in seat.ShowInput) (seat.ShowAnswer, error) { if m != "" && !Moves(p, m) { return seat.ShowAnswer{}, fmt.Errorf("the pipeline %s does not move %s", in.Pipeline, m) } + if m == "" && in.Step == "" && in.State == "" { + // Naming neither a mover nor a filter, show answers each mover's row, never every step of every mover (design 47 H2 + // H-A-376), in pages as the steps are. + rows := MoverRows(p) + p.Steps = []seat.StepResult{} + a := seat.ShowAnswer{Pipeline: p, Fill: fills, Total: int64(len(rows)), Movers: []seat.MoverRow{}} + size := sizeOf(a) + for i := from; i < len(rows); i++ { + n := sizeOf(rows[i]) + 1 + if size+n > MaxAnswer && len(a.Movers) > 0 { + a.Capped, a.Next = true, pageCursor(i) + break + } + size += n + a.Movers = append(a.Movers, rows[i]) + } + return a, nil + } held := []seat.StepResult{} for _, s := range p.Steps { if (m == "" || s.Module == m) && (in.Step == "" || s.Step == in.Step) && (in.State == "" || s.Outcome == in.State) { @@ -177,28 +197,99 @@ func StepWord(outcome string) string { return "not-run" } -// List is the pipelines and runs of a module, a branch, a commit or a run, newest started first, at most Limit when it -// names one (§83): each one's record with its movers and steps counted, its steps empty (H-A-191). +// ListRows is how many rows list answers when it names no limit (design 47 H2 H-A-376): the newest 20. +const ListRows = 20 + +// failedKind says an outcome is a step's failure: failed, could not run or did not build. +func failedKind(outcome string) bool { + return outcome == seat.StepResultOutcomeFailed || outcome == seat.StepResultOutcomeCouldNotRun || outcome == seat.StepResultOutcomeDidNotBuild +} + +// firstFailed is the first required step of steps that failed or could not run, with its module and why; nil for none +// (design 47 H2 H-A-376). +func firstFailed(steps []seat.StepResult) *seat.FailedStep { + for _, s := range steps { + if s.Status == seat.StepResultStatusRequired && failedKind(s.Outcome) { + return &seat.FailedStep{Module: s.Module, Step: s.Step, Artifact: s.Artifact, Outcome: s.Outcome, Why: s.Why} + } + } + return nil +} + +// MoverRows is each mover of p in show's short form (design 47 H2 H-A-376), in the movers' order: its module, its outcome +// (superseded for one a newer pipeline took out; waiting for one with no step placed; failed once a required step did not +// pass; running while a required step is open; else passed) and its first failed step. +func MoverRows(p seat.Pipeline) []seat.MoverRow { + out := make([]seat.MoverRow, 0, len(p.Movers)) + for _, m := range p.Movers { + steps := stepsOf(p, m.Module) + row := seat.MoverRow{Module: m.Module, Outcome: seat.MoverRowOutcomePassed, Failed: firstFailed(steps)} + running, failed := false, false + for _, s := range steps { + switch { + case s.Status != seat.StepResultStatusRequired: + case open(s), s.Outcome == seat.StepResultOutcomeWaiting: + running = true + case !stepPassed(s): + failed = true + } + } + switch { + case slices.Contains(p.Superseded, m.Module): + row.Outcome = seat.MoverRowOutcomeSuperseded + case len(steps) == 0: + row.Outcome = seat.MoverRowOutcomeWaiting + case failed: + row.Outcome = seat.MoverRowOutcomeFailed + case running: + row.Outcome = seat.MoverRowOutcomeRunning + } + out = append(out, row) + } + return out +} + +// List is the pipelines and runs of a module, a branch, a commit or a run, newest started first (§83): by default one +// short row per pipeline, the newest ListRows or Limit (design 47 H2 H-A-376); with Full and a Limit each one's record with +// its movers and steps counted, its steps empty (H-A-191). func (r Reads) List(in seat.ListInput) (seat.ListAnswer, error) { + if in.Full && in.Limit <= 0 { + return seat.ListAnswer{}, errors.New("list answers the whole pipelines only with a limit") + } all, err := r.pipelines() if err != nil { return seat.ListAnswer{}, err } out := []seat.Pipeline{} + steps := map[string][]seat.StepResult{} for _, p := range all { if (in.Module == "" || Moves(p, in.Module)) && (in.Branch == "" || p.Branch == in.Branch) && (in.Commit == "" || movesCommit(p, in.Commit)) && (in.Run == "" || p.Run == in.Run) { - // Each pipeline's record with its movers and steps counted, never its steps: show gives those (H-A-191). + // Each pipeline's record with its movers and steps counted, never its steps: show gives those (H-A-191); a row + // names its first failed step (H-A-376). + steps[p.Pipeline] = p.Steps p.MoverCount, p.StepCount = int64(len(p.Movers)), int64(len(p.Steps)) p.Steps, p.Unlogged = []seat.StepResult{}, nil out = append(out, p) } } sort.SliceStable(out, func(i, j int) bool { return startedOf(out[i]).After(startedOf(out[j])) }) - if in.Limit > 0 && int64(len(out)) > in.Limit { - out = out[:in.Limit] + limit := in.Limit + if limit <= 0 { + limit = ListRows } - return seat.ListAnswer{Pipelines: out}, nil + if int64(len(out)) > limit { + out = out[:limit] + } + if in.Full { + return seat.ListAnswer{Pipelines: out}, nil + } + rows := make([]seat.PipelineRow, 0, len(out)) + for _, p := range out { + rows = append(rows, seat.PipelineRow{Pipeline: p.Pipeline, Call: p.Call, Started: p.Started, Ended: p.Ended, Outcome: p.Outcome, + MoverCount: p.MoverCount, Failed: firstFailed(steps[p.Pipeline])}) + } + return seat.ListAnswer{Rows: rows}, nil } // Stands is every step that has started and not ended, with what it waits on and since when (§75, §83): the watchman diff --git a/modules/mesh-delivery-pipeline/internal/pipeline/read_test.go b/modules/mesh-delivery-pipeline/internal/pipeline/read_test.go index 58f4f3ac2..5324528af 100644 --- a/modules/mesh-delivery-pipeline/internal/pipeline/read_test.go +++ b/modules/mesh-delivery-pipeline/internal/pipeline/read_test.go @@ -65,11 +65,16 @@ func TestReads(t *testing.T) { Step: seat.StepResultStepBuild, Status: "required", Outcome: seat.StepResultOutcomePassed}, {Module: "delta", Step: seat.StepResultStepApproval, Status: "required", Outcome: seat.StepResultOutcomeWaiting, On: seat.WaitOnPerson, Started: &t2}}, Unlogged: []seat.LogEntry{{Pipeline: "next.8", Module: "delta", Step: seat.StepResultStepBuild, What: seat.LogEntryWhatEnded, At: t1}}}) + // A pipeline that failed: list's row names its first failed step (design 47 H2 H-A-376). + put(t, pipes, "gone.2", seat.Pipeline{Pipeline: "gone.2", Branch: "gone", Call: "call-2", Outcome: seat.PipelineOutcomeFailed, Started: &t0, Ended: &t1, + Movers: []seat.Mover{{Module: "zeta", Commit: "g2"}}, Steps: []seat.StepResult{ + {Module: "zeta", Step: seat.StepResultStepLint, Artifact: "zeta:program", Status: "optional", Outcome: seat.StepResultOutcomeFailed}, + {Module: "zeta", Step: seat.StepResultStepUnit, Artifact: "zeta:program", Status: "required", Outcome: seat.StepResultOutcomeCouldNotRun, Why: "its node lacks node-build-node"}}}) put(t, kept, "unit.sha256-aa", seat.KeptResult{Level: "unit", Digest: "sha256-aa", Package: "alpha/x"}) put(t, kept, "integration.sha256-bb", seat.KeptResult{Level: "integration", Digest: "sha256-bb", Package: "alpha/y"}) r := Reads{Pipelines: pipes, Kept: kept} - names := func(ps []seat.Pipeline) string { + names := func(ps []seat.PipelineRow) string { var s []string for _, p := range ps { s = append(s, p.Pipeline) @@ -81,10 +86,15 @@ func TestReads(t *testing.T) { got func() (string, error) want string }{ - {"show answers the pipeline whole", func() (string, error) { + // Design 47 H2 H-A-376: naming no mover, show answers each mover's row and never its steps. + {"show naming no mover answers each mover's row", func() (string, error) { a, err := r.Show(seat.ShowInput{Pipeline: "main.7.alpha"}) - return fmt.Sprint(a.Pipeline.Movers[0].Module, " ", len(a.Pipeline.Steps)), err - }, "alpha 3"}, + return fmt.Sprint(a.Pipeline.Movers[0].Module, " ", len(a.Pipeline.Steps), " ", a.Movers, " ", a.Total), err + }, "alpha 0 [{ alpha running}] 1"}, + {"show's row of a mover names its first failed step", func() (string, error) { + a, err := r.Show(seat.ShowInput{Pipeline: "gone.2"}) + return fmt.Sprint(a.Movers[0].Outcome, " ", *a.Movers[0].Failed), err + }, "failed {zeta:program zeta could not run unit its node lacks node-build-node}"}, // design 47 H2 §791: a step's output is read where its build seat's holder keeps it, on the node its step key names. {"a step's output is where its holder ran its ask", func() (string, error) { at, err := r.StepOutputs("main.7.alpha", "alpha", seat.StepResultStepLint) @@ -98,14 +108,14 @@ func TestReads(t *testing.T) { _, err := r.Show(seat.ShowInput{Pipeline: "main.9.alpha"}) return "", err }, `error: no pipeline "main.9.alpha" in pipelines`}, - {"show composes a pipeline's steps from its mover keys, in its movers' order (H-A-187)", func() (string, error) { + {"show composes its movers' rows from its mover keys, in its movers' order (H-A-187)", func() (string, error) { a, err := r.Show(seat.ShowInput{Pipeline: "next.8"}) var s []string - for _, st := range a.Pipeline.Steps { - s = append(s, st.Module+" "+st.Step) + for _, m := range a.Movers { + s = append(s, m.Module+" "+m.Outcome) } return strings.Join(s, ", "), err - }, "delta build, delta approval, epsilon build"}, + }, "delta running, epsilon passed"}, {"show naming a mover answers its steps alone", func() (string, error) { a, err := r.Show(seat.ShowInput{Pipeline: "next.8", Mover: "epsilon"}) var s []string @@ -119,7 +129,7 @@ func TestReads(t *testing.T) { return "", err }, "error: the pipeline next.8 does not move alpha"}, {"list names a pipeline, never a mover key, its record with its movers and steps counted and no step (H-A-191)", func() (string, error) { - a, err := r.List(seat.ListInput{Branch: "next"}) + a, err := r.List(seat.ListInput{Branch: "next", Full: true, Limit: 5}) var s []string for _, p := range a.Pipelines { s = append(s, fmt.Sprintf("%s %d movers %d steps, %d steps and %d unlogged answered", p.Pipeline, p.MoverCount, p.StepCount, @@ -129,16 +139,36 @@ func TestReads(t *testing.T) { }, "next.8 2 movers 3 steps, 0 steps and 0 unlogged answered"}, {"list by module, newest first", func() (string, error) { a, err := r.List(seat.ListInput{Module: "alpha"}) - return names(a.Pipelines), err + return names(a.Rows), err }, "beta.3.alpha main.7.alpha"}, {"list by commit", func() (string, error) { a, err := r.List(seat.ListInput{Commit: "c7"}) - return names(a.Pipelines), err + return names(a.Rows), err }, "main.7.gamma main.7.alpha"}, {"list by branch with a limit", func() (string, error) { a, err := r.List(seat.ListInput{Branch: "main", Limit: 1}) - return names(a.Pipelines), err + return names(a.Rows), err }, "main.7.gamma"}, + // Design 47 H2 H-A-376: a row is the pipeline's key, call, start, end, outcome, movers' count and first failed step; + // the whole pipelines are answered only with full and a limit; with no limit the rows are the newest 20. + {"list's row of a failed pipeline", func() (string, error) { + a, err := r.List(seat.ListInput{Branch: "gone"}) + raw, _ := json.Marshal(a.Rows) + return fmt.Sprint(string(raw), " ", len(a.Pipelines)), err + }, `[{"call":"call-2","ended":"2026-11-11T10:01:00Z","failed":{"artifact":"zeta:program","module":"zeta","outcome":"could not run","step":"unit","why":"its node lacks node-build-node"},"mover-count":1,"outcome":"failed","pipeline":"gone.2","started":"2026-11-11T10:00:00Z"}] 0`}, + {"list's full needs a limit", func() (string, error) { + _, err := r.List(seat.ListInput{Full: true}) + return "", err + }, "error: list answers the whole pipelines only with a limit"}, + {"list answers the newest 20 rows by default", func() (string, error) { + many := memKept{} + for i := range 25 { + at := t0.Add(time.Duration(i) * time.Minute) + put(t, many, fmt.Sprintf("main.%d", i), seat.Pipeline{Pipeline: fmt.Sprintf("main.%d", i), Branch: "main", Outcome: seat.PipelineOutcomePassed, Started: &at}) + } + a, err := Reads{Pipelines: many, Kept: memKept{}}.List(seat.ListInput{}) + return fmt.Sprint(len(a.Rows), " ", a.Rows[0].Pipeline, " ", a.Rows[19].Pipeline), err + }, "20 main.24 main.5"}, {"stands names a waiting step and since when", func() (string, error) { a, err := r.Stands() var s []string @@ -293,13 +323,13 @@ func TestAPipelineIsReadInParts(t *testing.T) { if err != nil || a.Total != 13 || len(a.Pipeline.Steps) != 13 || a.Pipeline.Steps[0].Module != "module-0003" { t.Fatalf("the failed unit steps: total %d, %d steps, %v", a.Total, len(a.Pipeline.Steps), err) } - // The whole record is larger than one answer: it is read in pages, each under 768 KB, every step once. + // The steps a filter holds are larger than one answer: they are read in pages, each under 768 KB, every step once. big := Reads{Pipelines: record(1000), Kept: memKept{}} seen, pages, next := 0, 0, "" for { - a, err := big.Show(seat.ShowInput{Pipeline: "main.9", Next: next}) + a, err := big.Show(seat.ShowInput{Pipeline: "main.9", State: seat.StepResultOutcomePassed, Next: next}) raw, _ := json.Marshal(a) - if err != nil || len(raw) > MaxAnswer || a.Total != 6000 { + if err != nil || len(raw) > MaxAnswer || a.Total != 5900 { t.Fatalf("page %d: %d bytes, total %d, %v", pages, len(raw), a.Total, err) } seen, pages = seen+len(a.Pipeline.Steps), pages+1 @@ -308,8 +338,13 @@ func TestAPipelineIsReadInParts(t *testing.T) { } next = a.Next } - if seen != 6000 || pages < 2 { - t.Fatalf("pages %d read %d steps, want every one of 6000 over more than one page", pages, seen) + if seen != 5900 || pages < 2 { + t.Fatalf("pages %d read %d steps, want every one of 5900 over more than one page", pages, seen) + } + // Design 47 H2 H-A-376: naming no mover and no filter, show answers 1,000 movers' rows in one answer and no step. + if a, err := big.Show(seat.ShowInput{Pipeline: "main.9"}); err != nil || len(a.Movers) != 1000 || len(a.Pipeline.Steps) != 0 || a.Capped || + a.Movers[3].Outcome != seat.MoverRowOutcomeFailed || a.Movers[3].Failed == nil || a.Movers[3].Failed.Step != seat.StepResultStepUnit { + t.Fatalf("the movers' rows: %d rows, %d steps, capped %v, %v", len(a.Movers), len(a.Pipeline.Steps), a.Capped, err) } if _, err := big.Show(seat.ShowInput{Pipeline: "main.9", Next: "not-a-cursor"}); err == nil { t.Fatal("a cursor show never answered is refused") diff --git a/modules/mesh-delivery-sdk/seatgen/gogen.go b/modules/mesh-delivery-sdk/seatgen/gogen.go index 1005cfd86..970044d02 100644 --- a/modules/mesh-delivery-sdk/seatgen/gogen.go +++ b/modules/mesh-delivery-sdk/seatgen/gogen.go @@ -177,6 +177,22 @@ func writeList(b *bytes.Buffer, fn, prefix, what string, names []string) { b.WriteString("}\n}\n\n") } +// writeVerbDescriptions writes VerbDescription, each verb's description as the seat's definition says it, so a tools +// program serving the seat's verbs as tools describes each from the one copy (design 47 H2 H-A-449). +func writeVerbDescriptions(b *bytes.Buffer, verbs []seatdef.Verb) { + if len(verbs) == 0 { + return + } + b.WriteString("// VerbDescription is a verb's description as the seat's definition says it, \"\" for a verb the seat does not serve or\n// does not describe (design 47 H2 H-A-449).\nfunc VerbDescription(verb string) string {\n\tswitch verb {\n") + for _, v := range verbs { + if v.Description == "" { + continue + } + fmt.Fprintf(b, "\tcase Verb%s:\n\t\treturn %q\n", ident(v.Name), v.Description) + } + b.WriteString("\t}\n\treturn \"\"\n}\n\n") +} + // goWhole is a whole seat's package: its names, subjects and types, and the test of its fixtures. func goWhole(m *Module, d seatdef.Definition) ([]byte, []byte, error) { fromPart := map[string]string{} @@ -198,6 +214,7 @@ func goWhole(m *Module, d seatdef.Definition) ([]byte, []byte, error) { writeNames(&b, "Accept", acceptNames(d.Accepts)) writeNames(&b, "Event", seatdef.MessageNames(d.Events)) writeList(&b, "Verbs", "Verb", "every verb the seat serves, in its definition's order", seatdef.VerbNames(d.Verbs)) + writeVerbDescriptions(&b, d.Verbs) writeList(&b, "Events", "Event", "every event published on the seat's subject", seatdef.MessageNames(d.Events)) if f := d.Family; f != nil { fmt.Fprintf(&b, "// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.\nconst (\n\tFamily = %q\n\tFamilyMaxAgeDays = %d\n)\n\n", f.Name, f.MaxAgeDays) diff --git a/modules/mesh-delivery-sdk/seatgen/layout_test.go b/modules/mesh-delivery-sdk/seatgen/layout_test.go index 140ee9069..e48420b9d 100644 --- a/modules/mesh-delivery-sdk/seatgen/layout_test.go +++ b/modules/mesh-delivery-sdk/seatgen/layout_test.go @@ -70,6 +70,11 @@ func TestEachSeatDefinedWholeIsAGoModuleOfItsOwn(t *testing.T) { } } } + // Design 47 H2 H-A-449: a verb's description reaches a tools program from the contract, the definition's one copy. + if src := string(files["go/seats/aregistry/contract.go"]); !strings.Contains(src, "func VerbDescription(verb string) string") || + !strings.Contains(src, "case VerbHold:\n\t\treturn \"What the registry holds. Reads only.\"") || strings.Contains(src, "case VerbPeek:") { + t.Errorf("a-registry's contract describes its verbs as %q", src[strings.Index(src, "func Verbs()"):][:400]) + } for _, seat := range []string{"aregistry", "bregistry"} { src := string(files["go/seats/"+seat+"/contract.go"]) if !strings.Contains(src, "type Ref struct") || !strings.Contains(src, "type PublishedEvent") { diff --git a/modules/mesh-delivery-sdk/seatgen/testdata/contracts/seats/a-registry/seat.json b/modules/mesh-delivery-sdk/seatgen/testdata/contracts/seats/a-registry/seat.json index d719b537f..ab7a68aa6 100644 --- a/modules/mesh-delivery-sdk/seatgen/testdata/contracts/seats/a-registry/seat.json +++ b/modules/mesh-delivery-sdk/seatgen/testdata/contracts/seats/a-registry/seat.json @@ -1,5 +1,5 @@ {"format":1,"seat":"a-registry","scope":"mesh","grain":"whole","domain":"Module","decision":"ADR 1","includes":["registry"], - "verbs":[{"name":"hold","class":"read","input":{"type":"object"},"answer":{"type":"object"}}, + "verbs":[{"name":"hold","description":"What the registry holds. Reads only.","class":"read","input":{"type":"object"},"answer":{"type":"object"}}, {"name":"peek","input":{"type":"object"},"answer":{"$ref":"#/bodies/Finding"}}], "accepts":[ {"name":"step","stream":"check","body":{"type":"object","properties":{"id":{"type":"string"}}}},