Merge pull request 'publishconformance: the cases every package holder is held to for a publish with a digest and no parts (A-490, A-490a)' (#258) from fix/gitea-publish-by-digest into main

This commit was merged in pull request #258.
This commit is contained in:
2026-11-19 21:40:02 +00:00
@@ -0,0 +1,146 @@
// Package publishconformance holds the cases every holder of a registry seat's `publish` is held to, so that two holders of
// one contract cannot each read it their own way (novox/hq design 47 G A-73, A-417, A-490): a publish with a version, a
// digest and no parts is the builder's publish again. A holder holding what the digest names under the name says it published
// (it moves nothing, or, where the bytes sit in the artifact store, as distribution's A-417 takes them, tags them); a holder
// that holds none of it, or holds the version under another digest, refuses it as not stored, naming the digest, and says it
// refused (A-490, A-490a). The cases live here beside the build modules' conformance kit (design 47 G §680, A-490a). A
// holder's own test runs Run over its own test bed, for every seat it fills.
package publishconformance
import (
"strings"
"testing"
)
// Name, Version and Digest are what the cases publish.
const (
Name = "novox/example"
Version = "0.1.0"
Digest = "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
// Other is a digest the holder holds under the version in the case where it holds another; it does not contain Digest.
Other = "sha256:fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
)
// Outcome is what a holder did with a publish: whether the transfer ended with it, how many parts it asked for, the event
// it said on its seat (published or refused) with its reason, and the error it answered.
type Outcome struct {
Ended bool
Lacks int
Event string
Reason string
Err error
}
// Bed is one holder under test, fresh for a case.
type Bed struct {
// Hold makes the holder hold the digest under Name at Version, as the builder's reservation of Version would find it.
Hold func(digest string)
// Publish sends the publish of name at version with the digest and no parts, and reports what the holder did.
Publish func(name, version, digest string) Outcome
}
// Run runs the cases over beds made by fresh.
func Run(t *testing.T, fresh func(t *testing.T) Bed) {
t.Helper()
t.Run("a publish with a digest and no parts is published when the holder holds it", func(t *testing.T) {
b := fresh(t)
b.Hold(Digest)
o := b.Publish(Name, Version, Digest)
if o.Err != nil || !o.Ended || o.Lacks != 0 || o.Event != "published" {
t.Fatalf("a held digest answered %+v; want ended, no part lacked, published said", o)
}
})
t.Run("a publish with a digest and no parts is refused as not stored, naming the digest, when the holder holds none", func(t *testing.T) {
b := fresh(t)
o := b.Publish(Name, Version, Digest)
if o.Err == nil || !strings.Contains(o.Err.Error(), "not stored") || !strings.Contains(o.Err.Error(), Digest) {
t.Fatalf("a digest not held answered %+v; want the error to say not stored and name %s", o, Digest)
}
if o.Event != "refused" || !strings.Contains(o.Reason, "not stored") || !strings.Contains(o.Reason, Digest) || o.Lacks != 0 || !o.Ended {
t.Errorf("a digest not held answered %+v; want refused said with the digest in its reason, ended, no part lacked", o)
}
})
t.Run("a publish with a digest and no parts is refused as not stored, naming the digest, when the holder holds the version under another digest", func(t *testing.T) {
b := fresh(t)
b.Hold(Other)
o := b.Publish(Name, Version, Digest)
if o.Err == nil || !strings.Contains(o.Err.Error(), "not stored") || !strings.Contains(o.Err.Error(), Digest) {
t.Fatalf("another digest held answered %+v; want the error to say not stored and name %s", o, Digest)
}
if o.Event != "refused" || !strings.Contains(o.Reason, "not stored") || !strings.Contains(o.Reason, Digest) || o.Lacks != 0 || !o.Ended {
t.Errorf("another digest held answered %+v; want refused said as not stored with the digest, ended, no part lacked", o)
}
})
}
// What the builder's reservation holds of the artifact a case publishes.
type Reservation int
const (
// NoDigestYet is an artifact whose build has not recorded its digest (the build runs, design 47 G §369, A-415).
NoDigestYet Reservation = iota + 1
// SameDigest is the digest of the file the case publishes.
SameDigest
// OtherDigest is another digest.
OtherDigest
)
// ReservedBed is one holder under test for the one-part publish a build module makes while it builds, fresh for a case. The
// holder's check asks the builder's reservation through its real Reserved check; the bed answers as the builder's verb `reserved`
// does.
type ReservedBed struct {
// Reserve makes the builder hold the case's name at its version as reserved, its artifact as r says. A case that never calls
// it has the builder hold no reservation.
Reserve func(r Reservation)
// Hold makes the holder hold the case's name at its version under another digest than the file's, as the first publish of it
// stored (A-490, A-490j): a second publish with another digest is refused as the holder holds the first.
Hold func()
// PublishWhole sends the one-part publish of the case's file (its own digest) and reports what the holder did.
PublishWhole func() Outcome
}
// RunReserved runs the cases of a publish made while the build runs, over beds made by fresh (design 47 G A-490j): the builder
// records a build's digests only when it ends, so a reserved artifact naming no digest yet takes the publish while the holder's own refusal of a version it holds under another digest stands. Package holders only: an image holder is no case of it (A-490j).
func RunReserved(t *testing.T, fresh func(t *testing.T) ReservedBed) {
t.Helper()
for _, c := range []struct {
name string
reserve Reservation // 0: nothing reserved
held bool // the holder holds the version under another digest already
ok bool
words string
}{
{name: "reserved, no digest yet: published", reserve: NoDigestYet, ok: true},
{name: "reserved with the digest: published", reserve: SameDigest, ok: true},
{name: "reserved with no digest yet, the version held under another digest: refused, nothing published", reserve: NoDigestYet, held: true, words: "is published with"},
{name: "reserved for another digest: refused, naming the reservation", reserve: OtherDigest, words: "did not reserve"},
{name: "nothing reserved: refused", words: "did not"},
} {
t.Run("a one-part publish while the build runs, "+c.name, func(t *testing.T) {
b := fresh(t)
if c.reserve != 0 {
b.Reserve(c.reserve)
}
if c.held {
b.Hold()
}
o := b.PublishWhole()
if c.held {
// Refused whether it ends with an error or only with the event refused, and never said published.
if o.Event != "refused" || !strings.Contains(o.Reason, c.words) {
t.Fatalf("answered %+v; want refused with %q in its reason, and nothing published", o, c.words)
}
return
}
if c.ok {
if o.Err != nil || o.Event != "published" {
t.Fatalf("answered %+v; want no error and published said", o)
}
return
}
if o.Err == nil || o.Event == "published" || !strings.Contains(o.Err.Error()+o.Reason, c.words) {
t.Fatalf("answered %+v; want refused, with %q in its words, and nothing published", o, c.words)
}
})
}
}