diff --git a/modules/mesh-delivery-sdk/publishconformance/publishconformance.go b/modules/mesh-delivery-sdk/publishconformance/publishconformance.go new file mode 100644 index 00000000..33658320 --- /dev/null +++ b/modules/mesh-delivery-sdk/publishconformance/publishconformance.go @@ -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) + } + }) + } +}