diff --git a/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go b/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go index 8c68e1310..0aeea3ac0 100644 --- a/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract.go @@ -13,7 +13,7 @@ const Seat = "oci-artifact-registry" // 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 = 1 +const Form = 2 // FormRegistry is the form of what the part registry adds. const FormRegistry = 1 @@ -21,8 +21,8 @@ const FormRegistry = 1 // 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 = "1 registry:1" - generatedFieldsDigest = "Artifact=79361e4ab1cd HeldEvent=b6d4c12500df Hold=c5a97a2f2d5a HoldAnswer=7d536ccb729f HoldsBySeatNameDigestValue=db093998a869 KeptEvent=ec3ef89ef8a7 ListAnswer=ca49dd7f20ee Listed=b9f1d1232e64 Outcome=1e66f7bf6725 PublishAnswer=a0df0b922e1e PublishPartAnswer=aebe3c6c89e9 PublishedEvent=ec3ef89ef8a7 RefusedEvent=ec3ef89ef8a7 ReleaseAnswer=d30bd6000a16 ReleasedEvent=b6d4c12500df RemoveAnswer=bccb5a322d69 RemovedEvent=ec3ef89ef8a7 Repository=740e54e0b3b0 VersionsAnswer=47e11ca2aea9 WindowsByCallerValue=23d9294dde92 WindowsByCallerValueDroppedItem=d748f0e58825" + generatedForms = "2 registry:1" + generatedFieldsDigest = "Artifact=79361e4ab1cd HeldEvent=b6d4c12500df Hold=c5a97a2f2d5a HoldAnswer=7d536ccb729f HoldsBySeatNameDigestValue=db093998a869 KeptEvent=ec3ef89ef8a7 ListAnswer=ffc9dd135c75 Listed=b9f1d1232e64 Outcome=1e66f7bf6725 PublishAnswer=a0df0b922e1e PublishPartAnswer=aebe3c6c89e9 PublishedEvent=ec3ef89ef8a7 RefusedEvent=ec3ef89ef8a7 ReleaseAnswer=d30bd6000a16 ReleasedEvent=b6d4c12500df RemoveAnswer=bccb5a322d69 RemovedEvent=ec3ef89ef8a7 Repository=740e54e0b3b0 VersionsAnswer=47e11ca2aea9 WindowsByCallerValue=23d9294dde92 WindowsByCallerValueDroppedItem=d748f0e58825" ) const ( @@ -436,16 +436,26 @@ type ReleaseAnswer struct { // ListInput is what list takes. type ListInput struct { + // only the repositories of this module, /*, applied while reading (design 47 H2 §813 (7)) + Module string `json:"module,omitempty"` // the repository, /; every repository of the seat when not given Name string `json:"name,omitempty"` + // the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779) + Next string `json:"next,omitempty"` } // ListAnswer is what list answers. type ListAnswer struct { + // yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811) + Capped bool `json:"capped,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). Form int64 `json:"form,omitempty"` + // the cursor of the next page, opaque; empty at the end (design 47 H2 §779) + Next string `json:"next,omitempty"` // each repository named, in order of its name Repositories []Repository `json:"repositories"` + // how many repositories the filters hold in all (design 47 H2 §811) + Total int64 `json:"total,omitempty"` } // PublishedEvent is the body of the event published. diff --git a/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract_test.go b/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract_test.go index 2ca6d5680..becff93af 100644 --- a/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/ociartifactregistry/contract_test.go @@ -53,6 +53,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RemoveAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "list answers an untagged archive by the blob it keeps", subject: "", given: "{\"repositories\":[{\"manifests\":[{\"artifact\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":true,\"index\":false,\"size\":4096}],\"name\":\"mail/files\"}]}", wire: "{\"repositories\":[{\"manifests\":[{\"artifact\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":true,\"index\":false,\"size\":4096}],\"name\":\"mail/files\"}]}", decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "list asks one module's repositories from a cursor", subject: "", given: "{\"module\":\"mail\",\"next\":\"c-4182\"}", wire: "{\"module\":\"mail\",\"next\":\"c-4182\"}", + decode: func(b []byte) (any, error) { var v ListInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "list answers a capped page with the cursor of the next", subject: "", given: "{\"capped\":true,\"next\":\"c-4183\",\"repositories\":[{\"manifests\":[{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":false,\"index\":false,\"size\":4096}],\"name\":\"mail/files\"}],\"total\":3}", wire: "{\"capped\":true,\"next\":\"c-4183\",\"repositories\":[{\"manifests\":[{\"digest\":\"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"held\":false,\"index\":false,\"size\":4096}],\"name\":\"mail/files\"}],\"total\":3}", + decode: func(b []byte) (any, error) { var v ListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/modules/mesh-delivery-contracts/parts/registry.json b/modules/mesh-delivery-contracts/parts/registry.json index dd6669b60..671d4b4d6 100644 --- a/modules/mesh-delivery-contracts/parts/registry.json +++ b/modules/mesh-delivery-contracts/parts/registry.json @@ -193,7 +193,7 @@ }, { "name": "remove", - "description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base by the artifact sweep's holder. 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.", + "description": "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.", "input": { "type": "object", "properties": { @@ -406,7 +406,7 @@ }, "reference": { "type": "string", - "description": "the reference the seat answers: //@sha256:, or @ for a package (ADR 0605 \u00a79)" + "description": "the reference the seat answers: //@sha256:, or @ for a package (ADR 0605 §9)" }, "reason": { "type": "string", diff --git a/modules/mesh-delivery-contracts/seats/oci-artifact-registry/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/oci-artifact-registry/fixtures/verbs.json index 039c38b6d..ea035c6fb 100644 --- a/modules/mesh-delivery-contracts/seats/oci-artifact-registry/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/oci-artifact-registry/fixtures/verbs.json @@ -134,5 +134,35 @@ } ] } + }, + { + "name": "list asks one module's repositories from a cursor", + "of": "verb:list.input", + "given": { + "module": "mail", + "next": "c-4182" + } + }, + { + "name": "list answers a capped page with the cursor of the next", + "of": "verb:list.answer", + "given": { + "repositories": [ + { + "name": "mail/files", + "manifests": [ + { + "digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "index": false, + "size": 4096, + "held": false + } + ] + } + ], + "capped": true, + "total": 3, + "next": "c-4183" + } } ] diff --git a/modules/mesh-delivery-contracts/seats/oci-artifact-registry/seat.json b/modules/mesh-delivery-contracts/seats/oci-artifact-registry/seat.json index a4fda9152..4dfaf4549 100644 --- a/modules/mesh-delivery-contracts/seats/oci-artifact-registry/seat.json +++ b/modules/mesh-delivery-contracts/seats/oci-artifact-registry/seat.json @@ -12,7 +12,7 @@ "verbs": [ { "name": "hold", - "description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 \u00a72); never an image of the holder's own. Emits held.", + "description": "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.", "input": { "type": "object", "properties": { @@ -94,13 +94,21 @@ }, { "name": "list", - "description": "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 \u00a73).", + "description": "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)).", "input": { "type": "object", "properties": { "name": { "type": "string", "description": "the repository, /; every repository of the seat when not given" + }, + "module": { + "type": "string", + "description": "only the repositories of this module, /*, applied while reading (design 47 H2 §813 (7))" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } } }, @@ -113,6 +121,18 @@ "$ref": "#/defs/Repository" }, "description": "each repository named, in order of its name" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)" + }, + "total": { + "type": "integer", + "description": "how many repositories the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" } }, "required": [ @@ -376,5 +396,6 @@ } ] } - ] + ], + "form": 2 } diff --git a/modules/mesh-delivery-contracts/ts/seats/ociartifactregistry/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/ociartifactregistry/index.d.ts index 573a2b837..099d9bfa1 100644 --- a/modules/mesh-delivery-contracts/ts/seats/ociartifactregistry/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/ociartifactregistry/index.d.ts @@ -154,16 +154,26 @@ export interface ReleaseAnswer { /** is what list takes. */ export interface ListInput { + /** only the repositories of this module, /*, applied while reading (design 47 H2 §813 (7)) */ + "module"?: string; /** the repository, /; every repository of the seat when not given */ "name"?: string; + /** the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779) */ + "next"?: string; } /** is what list answers. */ export interface ListAnswer { + /** yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811) */ + "capped"?: boolean; /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ "form"?: number; + /** the cursor of the next page, opaque; empty at the end (design 47 H2 §779) */ + "next"?: string; /** each repository named, in order of its name */ "repositories": Repository[]; + /** how many repositories the filters hold in all (design 47 H2 §811) */ + "total"?: number; } /** is the body of the event held. */