From 6f4e85c656526181f3f6b3f46e25b66f466485d1 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 16:12:27 +0100 Subject: [PATCH 1/2] distribution: versions on the artifact seat answers the blob a reference names The node-engine resolves a want's version to an archive's digest through oci-artifact-registry's verb versions and fetches /blobs/ by it. The holder answered the tag's manifest digest, so shanks asked claude-code/files' manifest as a blob and got 404 (claude-code 0.1.17). On the artifact seat versions now answers the manifest's one blob, the digest the reference and the event published carry; the image seat keeps the manifest digest. Builds: design 47 G A-430a (G-22-lead-answers-2), design 51 *One contract* (the seats' events carry the digest), the seat's contract Artifact and Listed.artifact --- .../cmd/distribution-tools/contract.go | 4 ++-- .../internal/holder/holder_test.go | 15 ++++++++++++ modules/distribution/internal/holder/oci.go | 23 +++++++++++++++++++ modules/distribution/internal/holder/verbs.go | 13 +++++++++++ 4 files changed, 53 insertions(+), 2 deletions(-) diff --git a/modules/distribution/cmd/distribution-tools/contract.go b/modules/distribution/cmd/distribution-tools/contract.go index 4fe26822a..b8937f4d0 100644 --- a/modules/distribution/cmd/distribution-tools/contract.go +++ b/modules/distribution/cmd/distribution-tools/contract.go @@ -40,11 +40,11 @@ func partAnswer(in reg.PublishPartInput, a holder.PublishAnswer) reg.PublishPart return reg.PublishPartAnswer{Transfer: in.Transfer, Part: in.Part, Received: in.Sequence + 1, Complete: a.Ended} } -// versionsAnswer is `versions`: each version with the digest the store holds under it. +// versionsAnswer is `versions`: each version with the digest its reference names (holder.Verbs.VersionDigest). func versionsAnswer(v *holder.Verbs, kind string, a holder.VersionsAnswer) reg.VersionsAnswer { out := reg.VersionsAnswer{Name: a.Name, Versions: []reg.Artifact{}} for _, ver := range a.Versions { - d, _ := v.Catalog.Digest(a.Name, ver) + d, _ := v.VersionDigest(a.Seat, a.Name, ver) out.Versions = append(out.Versions, reg.Artifact{Name: a.Name, Version: ver, Digest: d, Kind: kind}) } return out diff --git a/modules/distribution/internal/holder/holder_test.go b/modules/distribution/internal/holder/holder_test.go index bec32edc6..b4eef37bc 100644 --- a/modules/distribution/internal/holder/holder_test.go +++ b/modules/distribution/internal/holder/holder_test.go @@ -109,6 +109,9 @@ func (c *fakeCatalog) Versions(name string) ([]string, error) { func (c *fakeCatalog) Digest(name, version string) (string, error) { return c.tags[name+":"+version], nil } +func (c *fakeCatalog) Blob(name, version string) (string, error) { + return c.tags[name+":"+version], nil +} // Remove deletes by the digest, as the store does: every tag naming the digest goes with it. func (c *fakeCatalog) Remove(name, version string) error { @@ -709,6 +712,18 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) { if err := json.Unmarshal(store.manifests["m/tools:0.1.4"], &man); err != nil || len(man.Layers) != 1 || man.Layers[0].Size != int64(len(blob)) || man.Layers[0].Digest != digestOf(blob) { t.Errorf("the version's manifest %s, want one layer of %d bytes", store.manifests["m/tools:0.1.4"], len(blob)) } + // `versions` answers the digest the version's reference names and its published carries (design 47 G A-430a): on the + // artifact seat the blob, which the node-engine fetches as /blobs/, never the manifest's own digest. + v := &Verbs{Holder: b.h, Catalog: &OCI{Base: base}} + for _, c := range []struct{ seat, version, want string }{ + {ArtifactSeat, "0.1.4", digestOf(blob)}, + {ImageSeat, "0.1.4", digestOf(store.manifests["m/tools:0.1.4"])}, + {ArtifactSeat, "0.1.9", ""}, + } { + if got, err := v.VersionDigest(c.seat, "m/tools", c.version); err != nil || got != c.want { + t.Errorf("VersionDigest(%s, m/tools, %s) = %q, %v, want %q", c.seat, c.version, got, err, c.want) + } + } gone := "sha256:" + strings.Repeat("e", 64) _, err = b.h.Publish(ArtifactSeat, "x.mesh-delivery-builder", PublishRequest{Name: "m/tools", Version: "0.1.5", Kind: KindBundle, Digest: gone, Transfer: "republish-m-0-1-5-tools"}) if err == nil || !strings.Contains(err.Error(), "not stored: ") || !strings.Contains(err.Error(), gone) || store.manifests["m/tools:0.1.5"] != nil || diff --git a/modules/distribution/internal/holder/oci.go b/modules/distribution/internal/holder/oci.go index 65abad32f..7959bb7ab 100644 --- a/modules/distribution/internal/holder/oci.go +++ b/modules/distribution/internal/holder/oci.go @@ -273,6 +273,29 @@ func (o *OCI) Digest(name, version string) (string, error) { return resp.Header.Get("Docker-Content-Digest"), nil } +// Blob is the one blob the manifest name holds at version keeps (Manifest.Holder's shape): a bundle's or an archive's, +// what its reference names. Empty when none is held at version, or the manifest keeps no single blob. +func (o *OCI) Blob(name, version string) (string, error) { + resp, b, err := o.do(http.MethodGet, "/v2/"+name+"/manifests/"+version, "", nil, mediaManifest) + if err != nil { + return "", err + } + if resp.StatusCode == http.StatusNotFound { + return "", nil + } + if resp.StatusCode != http.StatusOK { + return "", fmt.Errorf("the store answered %d for %s:%s", resp.StatusCode, name, version) + } + m, err := ParseManifest(b) + if err != nil { + return "", fmt.Errorf("the manifest of %s:%s cannot be read: %w", name, version, err) + } + if !m.Holder() { + return "", nil + } + return m.Layers[0], nil +} + // ErrNoTagAlone is a store that cannot delete a tag alone. registry 2.8.3, the store's pinned image, is one: its // DeleteManifest (distribution v2.8.3 registry/handlers/manifests.go) ignores a tag reference and deletes the empty // digest, whose check fails, answered 400 DIGEST_INVALID; registry 3 untags alone. diff --git a/modules/distribution/internal/holder/verbs.go b/modules/distribution/internal/holder/verbs.go index 113697d9d..d8ccb239b 100644 --- a/modules/distribution/internal/holder/verbs.go +++ b/modules/distribution/internal/holder/verbs.go @@ -19,6 +19,9 @@ type Catalog interface { Versions(name string) ([]string, error) // Digest is the digest name holds at version, empty when none. Digest(name, version string) (string, error) + // Blob is the one blob the manifest name holds at version keeps, for a bundle or an archive: the digest its reference + // names and its published event carries. Empty when none is held, or the manifest is not of that shape. + Blob(name, version string) (string, error) // Remove deletes name at version by its manifest's digest, every tag naming that digest with it; the store's // collector frees its blobs. Remove(name, version string) error @@ -112,6 +115,16 @@ func (v *Verbs) Versions(seat, caller, name string) (VersionsAnswer, error) { return VersionsAnswer{Seat: seat, Name: name, Versions: got}, nil } +// VersionDigest is the digest `versions` answers for name at version on seat: the one an artifact's reference names and +// its event `published` carries (the contract's Artifact), so a node-engine fetches the bytes by it (design 47 G A-430a): +// on the artifact seat a bundle's or an archive's blob, on the image seat the image's manifest. Empty when none is held. +func (v *Verbs) VersionDigest(seat, name, version string) (string, error) { + if seat == ArtifactSeat { + return v.Catalog.Blob(name, version) + } + return v.Catalog.Digest(name, version) +} + // RemoveRequest is `remove`: a tagged version, or with the reason retention an untagged one by its digest. type RemoveRequest struct { Name string `json:"name"` -- 2.54.0 From b68de8f1863c00680936a968045a9444d9c0eef6 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 16:20:00 +0100 Subject: [PATCH 2/2] distribution: test versions' digest per seat; say why a version has none Review round 1: versionsAnswer's choice of digest per seat had no test. TestTheVerbsSpeakTheSeatsContract now holds it, with a store whose blob and manifest digests differ. OCI.Blob refuses a manifest that keeps no single blob, naming its layers, and versions says that in the journal: the contract's answer has no field for why. Notes for H2: OCI.Held (oci.go) compares the tag's manifest digest with a bundle's or an archive's blob digest, the same kind as this fault; versions answers kind "" since the tool reads a kind its input does not take. Builds: design 47 G A-430a (G-22-lead-answers-2), design 51 *One contract* --- .../cmd/distribution-tools/contract.go | 6 +++++- .../cmd/distribution-tools/contract_test.go | 14 ++++++++++++++ .../distribution/internal/holder/holder_test.go | 5 +++++ modules/distribution/internal/holder/oci.go | 4 ++-- modules/distribution/internal/holder/verbs.go | 2 +- 5 files changed, 27 insertions(+), 4 deletions(-) diff --git a/modules/distribution/cmd/distribution-tools/contract.go b/modules/distribution/cmd/distribution-tools/contract.go index b8937f4d0..6e4e08f1b 100644 --- a/modules/distribution/cmd/distribution-tools/contract.go +++ b/modules/distribution/cmd/distribution-tools/contract.go @@ -44,7 +44,11 @@ func partAnswer(in reg.PublishPartInput, a holder.PublishAnswer) reg.PublishPart func versionsAnswer(v *holder.Verbs, kind string, a holder.VersionsAnswer) reg.VersionsAnswer { out := reg.VersionsAnswer{Name: a.Name, Versions: []reg.Artifact{}} for _, ver := range a.Versions { - d, _ := v.VersionDigest(a.Seat, a.Name, ver) + d, err := v.VersionDigest(a.Seat, a.Name, ver) + if err != nil { + // The contract's answer has no field for why; the version is answered with no digest and the reason said here. + logf("versions: %s %s on %s answers no digest: %v", a.Name, ver, a.Seat, err) + } out.Versions = append(out.Versions, reg.Artifact{Name: a.Name, Version: ver, Digest: d, Kind: kind}) } return out diff --git a/modules/distribution/cmd/distribution-tools/contract_test.go b/modules/distribution/cmd/distribution-tools/contract_test.go index 1ed66b9f2..9fadaf0bc 100644 --- a/modules/distribution/cmd/distribution-tools/contract_test.go +++ b/modules/distribution/cmd/distribution-tools/contract_test.go @@ -12,6 +12,12 @@ import ( "distribution/internal/holder" ) +// twoDigests is a store whose every version's manifest digest and blob differ. +type twoDigests struct{ holder.Catalog } + +func (twoDigests) Digest(string, string) (string, error) { return "sha256:manifest", nil } +func (twoDigests) Blob(string, string) (string, error) { return "sha256:blob", nil } + func jsonFields(v any) map[string]bool { out := map[string]bool{} t := reflect.TypeOf(v) @@ -59,6 +65,14 @@ func TestTheVerbsSpeakTheSeatsContract(t *testing.T) { if a := publishAnswer(holder.PublishAnswer{Transfer: "t", Missing: []string{"sha256:bb"}}); !reflect.DeepEqual(a.Lacks, []string{"sha256:bb"}) || a.Held { t.Errorf("publish answers %+v", a) } + // versions answers the digest a reference names (design 47 G A-430a): the blob on the artifact seat, the manifest on the image seat. + cat := twoDigests{} + for _, c := range []struct{ seat, want string }{{holder.ArtifactSeat, "sha256:blob"}, {holder.ImageSeat, "sha256:manifest"}} { + got := versionsAnswer(&holder.Verbs{Catalog: cat}, "", holder.VersionsAnswer{Seat: c.seat, Name: "m/files", Versions: []string{"0.1.7"}}) + if len(got.Versions) != 1 || got.Versions[0].Digest != c.want || got.Versions[0].Version != "0.1.7" { + t.Errorf("versions on %s answers %+v, want digest %s", c.seat, got.Versions, c.want) + } + } if r, err := partOf(reg.PublishPartInput{Transfer: "t", Part: "sha256:bb", Data: "aGk=", Last: true}); err != nil || string(r.Data) != "hi" || r.Digest != "sha256:bb" { t.Errorf("publish-part read %+v, %v", r, err) } diff --git a/modules/distribution/internal/holder/holder_test.go b/modules/distribution/internal/holder/holder_test.go index b4eef37bc..9f2f0f77e 100644 --- a/modules/distribution/internal/holder/holder_test.go +++ b/modules/distribution/internal/holder/holder_test.go @@ -724,6 +724,11 @@ func TestTheHolderOfTheTwoImageSeats(t *testing.T) { t.Errorf("VersionDigest(%s, m/tools, %s) = %q, %v, want %q", c.seat, c.version, got, err, c.want) } } + // A manifest that keeps no single blob answers no digest and says why. + store.manifests["m/tools:0.2.0"] = []byte(`{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","config":{"mediaType":"application/vnd.oci.image.config.v1+json","digest":"sha256:c"},"layers":[{"digest":"sha256:a"},{"digest":"sha256:b"}]}`) + if got, err := v.VersionDigest(ArtifactSeat, "m/tools", "0.2.0"); got != "" || err == nil || !strings.Contains(err.Error(), "2 layers") { + t.Errorf("VersionDigest of a manifest of two layers = %q, %v, want no digest and why", got, err) + } gone := "sha256:" + strings.Repeat("e", 64) _, err = b.h.Publish(ArtifactSeat, "x.mesh-delivery-builder", PublishRequest{Name: "m/tools", Version: "0.1.5", Kind: KindBundle, Digest: gone, Transfer: "republish-m-0-1-5-tools"}) if err == nil || !strings.Contains(err.Error(), "not stored: ") || !strings.Contains(err.Error(), gone) || store.manifests["m/tools:0.1.5"] != nil || diff --git a/modules/distribution/internal/holder/oci.go b/modules/distribution/internal/holder/oci.go index 7959bb7ab..a721376ce 100644 --- a/modules/distribution/internal/holder/oci.go +++ b/modules/distribution/internal/holder/oci.go @@ -274,7 +274,7 @@ func (o *OCI) Digest(name, version string) (string, error) { } // Blob is the one blob the manifest name holds at version keeps (Manifest.Holder's shape): a bundle's or an archive's, -// what its reference names. Empty when none is held at version, or the manifest keeps no single blob. +// what its reference names. Empty when none is held at version; an error naming why when the manifest keeps no single blob. func (o *OCI) Blob(name, version string) (string, error) { resp, b, err := o.do(http.MethodGet, "/v2/"+name+"/manifests/"+version, "", nil, mediaManifest) if err != nil { @@ -291,7 +291,7 @@ func (o *OCI) Blob(name, version string) (string, error) { return "", fmt.Errorf("the manifest of %s:%s cannot be read: %w", name, version, err) } if !m.Holder() { - return "", nil + return "", fmt.Errorf("the manifest of %s:%s keeps %d layers under a %q configuration, not one blob", name, version, len(m.Layers), m.ConfigMedia) } return m.Layers[0], nil } diff --git a/modules/distribution/internal/holder/verbs.go b/modules/distribution/internal/holder/verbs.go index d8ccb239b..5451e1382 100644 --- a/modules/distribution/internal/holder/verbs.go +++ b/modules/distribution/internal/holder/verbs.go @@ -20,7 +20,7 @@ type Catalog interface { // Digest is the digest name holds at version, empty when none. Digest(name, version string) (string, error) // Blob is the one blob the manifest name holds at version keeps, for a bundle or an archive: the digest its reference - // names and its published event carries. Empty when none is held, or the manifest is not of that shape. + // names and its published event carries. Empty when none is held; an error when the manifest keeps no single blob. Blob(name, version string) (string, error) // Remove deletes name at version by its manifest's digest, every tag naming that digest with it; the store's // collector frees its blobs. -- 2.54.0