D4a: the registry's list takes module and a cursor, and pages at 768 KB

oci-artifact-registry's list filters by module beside name while it reads,
continues from the opaque cursor next and answers capped and total; the
seat's form rises to 2. The shared remove no longer judges its caller for a
retention removal.

Builds: design 47 H2 §779, §811, §813 (7); H-A-350 DMC-10
This commit is contained in:
2026-11-22 00:02:21 +01:00
parent 4749c686eb
commit ac99946fcb
6 changed files with 83 additions and 8 deletions
@@ -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, <module>/*, applied while reading (design 47 H2 §813 (7))
Module string `json:"module,omitempty"`
// the repository, <module>/<artifact>; 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.
@@ -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))
@@ -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: <registry>/<module>/<artifact>@sha256:<digest>, or <name>@<version> for a package (ADR 0605 \u00a79)"
"description": "the reference the seat answers: <registry>/<module>/<artifact>@sha256:<digest>, or <name>@<version> for a package (ADR 0605 §9)"
},
"reason": {
"type": "string",
@@ -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"
}
}
]
@@ -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, <module>/<artifact>; every repository of the seat when not given"
},
"module": {
"type": "string",
"description": "only the repositories of this module, <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
}
@@ -154,16 +154,26 @@ export interface ReleaseAnswer {
/** is what list takes. */
export interface ListInput {
/** only the repositories of this module, <module>/*, applied while reading (design 47 H2 §813 (7)) */
"module"?: string;
/** the repository, <module>/<artifact>; 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. */