referenceForms gains config-lines and config-json; textNeeds also finds the exact token ${config-json}, which holds no colon.
Builds: design 42 zfs-owns-zfs §4, §3, §9; answers A-13, A-15, A-24, A-25
491 lines
17 KiB
Go
491 lines
17 KiB
Go
package catalogue
|
|
|
|
import (
|
|
"bytes"
|
|
_ "embed"
|
|
"encoding/json"
|
|
"reflect"
|
|
"regexp"
|
|
"slices"
|
|
"sort"
|
|
"strings"
|
|
)
|
|
|
|
// A reader capability is one thing of a manifest a reader of manifests (a node-engine) can read (novox/hq ADR 0614 §4):
|
|
// a manifest word, a form, or a seat name of the shared contract it is built with. Each is a string of one of three
|
|
// kinds:
|
|
//
|
|
// - `word:<path>`, a key the lenient decoder reads, by its path of keys from the top of the manifest: `word:claims`,
|
|
// `word:claims.serves`. The key of a map (a setting's name, a requirement's) is no part of a path, and an entry of
|
|
// a list is read as the list: `word:settings.default`, `word:provides.credential`.
|
|
// - `form:<name>`, a form a manifest may be written in: the config form (`form:config`, ADR 0348 §1) and each
|
|
// reference form a value may hold, `${<name>:…}` (`form:setting`, `form:dir`).
|
|
// - `seat:<name>`, a seat of the contract's seat table, as a manifest names one in a claim, a use, an invoke or a
|
|
// bucket's share.
|
|
//
|
|
// ManifestReads is what this contract reads; ManifestNeeds what one manifest's own words, forms and seat names need;
|
|
// BaselineManifestReads what a node-engine that states none is read as stating. What a module's build reads once it
|
|
// runs is never asked.
|
|
const (
|
|
ReadWord = "word:"
|
|
ReadForm = "form:"
|
|
ReadSeat = "seat:"
|
|
)
|
|
|
|
// referenceForms are the reference forms a manifest's values may hold, `${<name>:…}`, as this contract fills them. A new
|
|
// reference form is added here in the change that teaches the contract to read it, so a node-engine built with it
|
|
// states it (ADR 0612 §2's new reference form is one).
|
|
var referenceForms = []string{"access", "backup", "bound", "collected", "config", "config-json", "config-lines",
|
|
"consumer", "consumers", "contribution", "dir", "machine", "port", "seat", "secret", "setting"}
|
|
|
|
// ifConfigWord is the reader capability for a resource's `if-config` (IfConfigField).
|
|
const ifConfigWord = ReadWord + "resources." + IfConfigField
|
|
|
|
// configJSONToken is the reference form `${config-json}` whole: it holds no colon, so textNeeds's search for `${<form>:`
|
|
// does not find it (design 42 zfs-owns-zfs, answer A-25).
|
|
const configJSONToken = "${config-json}"
|
|
|
|
// ReferenceFormSeat names the reference form a registry seat answers for a build's artifact,
|
|
// `<seat>/<module>/<artifact>@sha256:<digest>` (novox/hq ADR 0605 §9; the registry clients' reference forms), as the reader capability
|
|
// `form:seat-reference` a node-engine built with this contract states (ADR 0618 §1, ADR 0624 §1): the builder writes it
|
|
// into a build key only for the nodes whose engines state it. The older reference forms a node-engine read before any
|
|
// stated what it reads are the baseline's; they are the builder's to name (delivery's artifact forms).
|
|
const ReferenceFormSeat = "seat-reference"
|
|
|
|
// artifactReferenceForms are the reference forms of a build's artifacts this contract reads beyond the baseline's.
|
|
var artifactReferenceForms = []string{ReferenceFormSeat}
|
|
|
|
// ReferenceFormSeatReach names how a node-engine built with this contract fills `${seat:<seat>:reach}`, as the reader
|
|
// capability `form:seat-reach` (novox/hq ADR 0632 §1): from the seat holder placement names and the listen its manifest
|
|
// opens to the mesh, the store's three seats among them, never from a module serving the retired provision
|
|
// artifact-store. An engine before it filled the store's reach only from that provision, so a manifest naming a seat's
|
|
// reach, and the store holder's own manifest, need it and are held from a node whose engine does not state it
|
|
// (ManifestNeeds).
|
|
const ReferenceFormSeatReach = "seat-reach"
|
|
|
|
// storeHolderSeat is the seat whose holder's own manifest needs form:seat-reach (novox/hq ADR 0632 §2): the one seat
|
|
// name this contract reads a rule by, and the one seat name of the package-list test's exceptions (S-8).
|
|
const storeHolderSeat = "container-image-registry"
|
|
|
|
// claimsAtMesh says whether a manifest claims seat at the mesh's scope (a claim with no scope is the seat's own). The
|
|
// store holder's own manifest, a claim of storeHolderSeat, needs form:seat-reach this way (ADR 0632 §2): read
|
|
// on every node, it leaves an engine before the reading without the old way to find the store, so it is held from every
|
|
// node whose engine does not state it.
|
|
func claimsAtMesh(top map[string]any, seat string) bool {
|
|
for _, c := range asList(top["claims"]) {
|
|
obj, _ := c.(map[string]any)
|
|
name, _ := obj["name"].(string)
|
|
scope, _ := obj["scope"].(string)
|
|
if hs, ok := SeatNamed(name); ok && hs.Name == seat && (scope == "" || scope == ScopeMesh) {
|
|
return true
|
|
}
|
|
}
|
|
return false
|
|
}
|
|
|
|
// ofSeatReach is a manifest's value naming a seat's reach, `${seat:<seat>:reach}`.
|
|
var ofSeatReach = regexp.MustCompile(`\$\{seat:[a-z0-9][a-z0-9-]*:reach\}`)
|
|
|
|
// manifestTopWords are the top-level keys Manifest.UnmarshalJSON reads apart from the fields of manifestFields: each
|
|
// read whole, its inside a map of the module's own names (requirements, local names) and values, no words of the
|
|
// contract's beneath it. `requires` and `config` are read as their fields are (manifestNeeds).
|
|
var manifestTopWords = []string{"secrets", "contributes", OptionalRequiresKey, RequireSharesKey}
|
|
|
|
// wireKeys are the keys of a block whose decoder reads its object by keys of its own, not by its fields' tags (its
|
|
// UnmarshalJSON): the keys as that decoder reads them, none of them a block.
|
|
var wireKeys = map[reflect.Type][]string{
|
|
reflect.TypeOf(OfferIdentity{}): {"max", "in"},
|
|
reflect.TypeOf(DataBackup{}): {"dump", "into"},
|
|
reflect.TypeOf(OwnSecret{}): {"path", "taken", "issued-by", "prompt", "owner"},
|
|
}
|
|
|
|
// ManifestReads is every reader capability of this contract, sorted: what a node-engine built with it states in its
|
|
// node record (delivery.NodeRecord.ManifestReads).
|
|
func ManifestReads() []string {
|
|
set := map[string]bool{}
|
|
for _, w := range contractWords() {
|
|
set[ReadWord+w] = true
|
|
}
|
|
for _, f := range referenceForms {
|
|
set[ReadForm+f] = true
|
|
}
|
|
for _, f := range artifactReferenceForms {
|
|
set[ReadForm+f] = true
|
|
}
|
|
set[ReadForm+ReferenceFormSeatReach] = true
|
|
set[ifConfigWord] = true
|
|
for _, s := range Seats() {
|
|
set[ReadSeat+s.Name] = true
|
|
}
|
|
return sortedSet(set)
|
|
}
|
|
|
|
// baselineManifestReads is the baseline, generated once from mesh-sdk f02f142 (the contract every node-engine ran
|
|
// before any stated what it reads) by ManifestReads as this file computes it: one reader capability a line.
|
|
//
|
|
//go:embed manifest_reads_baseline.txt
|
|
var baselineManifestReads string
|
|
|
|
// BaselineManifestReads is what a node-engine that states no reader capability is read as stating (novox/hq ADR 0614
|
|
// §4): the words, forms and seat names of the shared contract as it stood before any node-engine stated them.
|
|
func BaselineManifestReads() []string {
|
|
var out []string
|
|
for _, line := range strings.Split(baselineManifestReads, "\n") {
|
|
if line = strings.TrimSpace(line); line != "" {
|
|
out = append(out, line)
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
// StatedManifestReads is what a node-engine's statement is read as: stated itself, or the baseline when it states none
|
|
// (an engine built before the statement existed).
|
|
func StatedManifestReads(stated []string) []string {
|
|
if len(stated) == 0 {
|
|
return BaselineManifestReads()
|
|
}
|
|
return stated
|
|
}
|
|
|
|
// MissingManifestReads is each of needs that stated, read as StatedManifestReads reads it, lacks: sorted, nil when it
|
|
// lacks none.
|
|
func MissingManifestReads(needs, stated []string) []string {
|
|
have := map[string]bool{}
|
|
for _, s := range StatedManifestReads(stated) {
|
|
have[s] = true
|
|
}
|
|
var missing []string
|
|
for _, n := range needs {
|
|
if !have[n] {
|
|
missing = append(missing, n)
|
|
}
|
|
}
|
|
sort.Strings(missing)
|
|
return slices.Compact(missing)
|
|
}
|
|
|
|
// ManifestNeeds is every reader capability a manifest's own words, forms and seat names need, sorted, read as the
|
|
// lenient decoder walks the manifest: only what this contract knows is named, since what it does not know is set aside
|
|
// (Manifest.SetAside). An error is only bytes that are no JSON object.
|
|
func ManifestNeeds(raw []byte) ([]string, error) {
|
|
var top map[string]any
|
|
dec := json.NewDecoder(bytes.NewReader(raw))
|
|
dec.UseNumber()
|
|
if err := dec.Decode(&top); err != nil {
|
|
return nil, err
|
|
}
|
|
used := map[string]bool{}
|
|
textNeeds(raw, used)
|
|
if claimsAtMesh(top, storeHolderSeat) {
|
|
used[ReadForm+ReferenceFormSeatReach] = true
|
|
}
|
|
for _, r := range asList(top["resources"]) {
|
|
if obj, ok := r.(map[string]any); ok {
|
|
if _, has := obj[IfConfigField]; has {
|
|
used[ifConfigWord] = true
|
|
}
|
|
}
|
|
}
|
|
if _, has := top[ConfigField]; has || takesConfigKey.Match(raw) {
|
|
used[ReadForm+"config"] = true
|
|
}
|
|
words := map[string]bool{}
|
|
fields := structFields(reflect.TypeOf(manifestFields{}))
|
|
for _, k := range sortedAnyKeys(top) {
|
|
v := top[k]
|
|
switch {
|
|
case k == ConfigField:
|
|
// The config form is the settings form's words under another key (config.go).
|
|
words[SettingsField] = true
|
|
walkValue(v, fields[SettingsField].Type, SettingsField, words)
|
|
case k == "requires":
|
|
words[k] = true
|
|
for _, e := range asList(v) {
|
|
obj, isObj := e.(map[string]any)
|
|
if !isObj {
|
|
continue
|
|
}
|
|
if _, bus := obj["storage"]; bus {
|
|
// A bus-state entry of `requires` (BusStateEntry): the stored form's `bus-state`.
|
|
words[BusStateField] = true
|
|
walkValue(obj, reflect.TypeOf(BusStateEntry{}), BusStateField, words)
|
|
continue
|
|
}
|
|
walkValue(obj, reflect.TypeOf(requirementForm{}), k, words)
|
|
}
|
|
case slices.Contains(manifestTopWords, k):
|
|
words[k] = true
|
|
default:
|
|
if f, known := fields[k]; known {
|
|
words[k] = true
|
|
walkValue(v, f.Type, k, words)
|
|
}
|
|
}
|
|
}
|
|
for w := range words {
|
|
used[ReadWord+w] = true
|
|
}
|
|
for _, s := range seatNamesUsed(top) {
|
|
used[ReadSeat+s] = true
|
|
}
|
|
return sortedSet(used), nil
|
|
}
|
|
|
|
// seatNamesUsed is each seat of the contract's table the manifest names: in a claim, a use, an invoke of a seat's verb,
|
|
// and a bucket's share with a seat.
|
|
func seatNamesUsed(top map[string]any) []string {
|
|
known := map[string]bool{}
|
|
for _, s := range Seats() {
|
|
known[s.Name] = true
|
|
}
|
|
set := map[string]bool{}
|
|
add := func(name string) {
|
|
if known[name] {
|
|
set[name] = true
|
|
}
|
|
}
|
|
for _, c := range asList(top["claims"]) {
|
|
if obj, ok := c.(map[string]any); ok {
|
|
name, _ := obj["name"].(string)
|
|
add(name)
|
|
}
|
|
}
|
|
for _, u := range asList(top["uses"]) {
|
|
name, _ := u.(string)
|
|
add(name)
|
|
}
|
|
for _, i := range asList(top["invokes"]) {
|
|
text, _ := i.(string)
|
|
if seat, _, ok := SeatInvoke(text); ok {
|
|
add(seat)
|
|
}
|
|
}
|
|
for _, r := range asList(top["requires"]) {
|
|
obj, _ := r.(map[string]any)
|
|
for _, share := range asList(obj["shares"]) {
|
|
text, _ := share.(string)
|
|
if seat, ok := strings.CutPrefix(text, "seat:"); ok {
|
|
add(seat)
|
|
}
|
|
}
|
|
}
|
|
return sortedSet(set)
|
|
}
|
|
|
|
// contractWords is every word of this contract, by path (ReadWord): the fields of manifestFields, the keys the
|
|
// manifest's own decoder reads beside them, and the long form of a requirement.
|
|
func contractWords() []string {
|
|
set := map[string]bool{}
|
|
walkType(reflect.TypeOf(manifestFields{}), "", set, map[reflect.Type]bool{})
|
|
set["requires"] = true
|
|
walkType(reflect.TypeOf(requirementForm{}), "requires", set, map[reflect.Type]bool{})
|
|
for _, w := range manifestTopWords {
|
|
set[w] = true
|
|
}
|
|
return sortedSet(set)
|
|
}
|
|
|
|
// walkType adds every word of t at path to set: a struct's fields by their keys, a list's and a map's elements as
|
|
// themselves; onPath stops a type that holds itself.
|
|
func walkType(t reflect.Type, path string, set map[string]bool, onPath map[reflect.Type]bool) {
|
|
t = deref(t)
|
|
if keys, custom := wireKeys[t]; custom {
|
|
for _, k := range keys {
|
|
set[joinWord(path, k)] = true
|
|
}
|
|
return
|
|
}
|
|
switch t.Kind() {
|
|
case reflect.Struct:
|
|
if onPath[t] {
|
|
return
|
|
}
|
|
onPath[t] = true
|
|
defer delete(onPath, t)
|
|
for name, f := range structFields(t) {
|
|
word := joinWord(path, name)
|
|
set[word] = true
|
|
walkType(f.Type, word, set, onPath)
|
|
}
|
|
case reflect.Slice, reflect.Array, reflect.Map:
|
|
if t.Elem().Kind() == reflect.Uint8 {
|
|
return // bytes: a value, never a block
|
|
}
|
|
walkType(t.Elem(), path, set, onPath)
|
|
}
|
|
}
|
|
|
|
// walkValue adds to used every word of t that v, a value decoded from JSON, has at path.
|
|
func walkValue(v any, t reflect.Type, path string, used map[string]bool) {
|
|
t = deref(t)
|
|
if keys, custom := wireKeys[t]; custom {
|
|
obj, _ := v.(map[string]any)
|
|
for _, k := range keys {
|
|
if _, has := obj[k]; has {
|
|
used[joinWord(path, k)] = true
|
|
}
|
|
}
|
|
return
|
|
}
|
|
switch t.Kind() {
|
|
case reflect.Struct:
|
|
obj, isObj := v.(map[string]any)
|
|
if !isObj {
|
|
return // a short form (a name for an offer): no words inside it
|
|
}
|
|
fields := structFields(t)
|
|
for _, k := range sortedAnyKeys(obj) {
|
|
f, known := fields[k]
|
|
if !known {
|
|
continue // set aside by the decoder, so no word of this contract
|
|
}
|
|
word := joinWord(path, k)
|
|
used[word] = true
|
|
walkValue(obj[k], f.Type, word, used)
|
|
}
|
|
case reflect.Slice, reflect.Array:
|
|
if t.Elem().Kind() == reflect.Uint8 {
|
|
return
|
|
}
|
|
for _, item := range asList(v) {
|
|
walkValue(item, t.Elem(), path, used)
|
|
}
|
|
case reflect.Map:
|
|
obj, _ := v.(map[string]any)
|
|
for _, k := range sortedAnyKeys(obj) {
|
|
walkValue(obj[k], t.Elem(), path, used)
|
|
}
|
|
}
|
|
}
|
|
|
|
// structFields are a struct's fields by the key the JSON decoder reads each by: its tag's name, else its own name; an
|
|
// untagged embedded struct's fields as the struct's own; never one tagged "-" or unexported.
|
|
func structFields(t reflect.Type) map[string]reflect.StructField {
|
|
out := map[string]reflect.StructField{}
|
|
for i := 0; i < t.NumField(); i++ {
|
|
f := t.Field(i)
|
|
tag := f.Tag.Get("json")
|
|
name, _, _ := strings.Cut(tag, ",")
|
|
if name == "-" {
|
|
continue
|
|
}
|
|
if f.Anonymous && name == "" && deref(f.Type).Kind() == reflect.Struct {
|
|
for k, inner := range structFields(deref(f.Type)) {
|
|
if _, shadowed := out[k]; !shadowed {
|
|
out[k] = inner
|
|
}
|
|
}
|
|
continue
|
|
}
|
|
if !f.IsExported() {
|
|
continue
|
|
}
|
|
if name == "" {
|
|
name = f.Name
|
|
}
|
|
out[name] = f
|
|
}
|
|
return out
|
|
}
|
|
|
|
// untaggedBlocks are the struct types among the contract's words whose fields carry no key of their own and which
|
|
// wireKeys does not name: their words would be the Go names, which no decoder reads. A row keeps it empty.
|
|
func untaggedBlocks() []string {
|
|
seen := map[reflect.Type]bool{}
|
|
var out []string
|
|
var walk func(t reflect.Type)
|
|
walk = func(t reflect.Type) {
|
|
t = deref(t)
|
|
if seen[t] {
|
|
return
|
|
}
|
|
seen[t] = true
|
|
if _, custom := wireKeys[t]; custom {
|
|
return
|
|
}
|
|
switch t.Kind() {
|
|
case reflect.Struct:
|
|
for i := 0; i < t.NumField(); i++ {
|
|
f := t.Field(i)
|
|
if f.IsExported() && !f.Anonymous && f.Tag.Get("json") == "" {
|
|
out = append(out, t.String())
|
|
break
|
|
}
|
|
}
|
|
for _, f := range structFields(t) {
|
|
walk(f.Type)
|
|
}
|
|
case reflect.Slice, reflect.Array, reflect.Map:
|
|
walk(t.Elem())
|
|
}
|
|
}
|
|
walk(reflect.TypeOf(manifestFields{}))
|
|
walk(reflect.TypeOf(requirementForm{}))
|
|
sort.Strings(out)
|
|
return out
|
|
}
|
|
|
|
func deref(t reflect.Type) reflect.Type {
|
|
for t.Kind() == reflect.Pointer {
|
|
t = t.Elem()
|
|
}
|
|
return t
|
|
}
|
|
|
|
func joinWord(path, key string) string {
|
|
if path == "" {
|
|
return key
|
|
}
|
|
return path + "." + key
|
|
}
|
|
|
|
func asList(v any) []any {
|
|
list, _ := v.([]any)
|
|
return list
|
|
}
|
|
|
|
// textNeeds adds the reference forms a manifest's or a template's text writes to used: a form the engine fills in a
|
|
// file's text is read there whether the text is inline or in a template file.
|
|
func textNeeds(text []byte, used map[string]bool) {
|
|
for _, f := range referenceForms {
|
|
if bytes.Contains(text, []byte("${"+f+":")) {
|
|
used[ReadForm+f] = true
|
|
}
|
|
}
|
|
if bytes.Contains(text, []byte(configJSONToken)) {
|
|
used[ReadForm+"config-json"] = true
|
|
}
|
|
if ofSeatReach.Match(text) {
|
|
used[ReadForm+ReferenceFormSeatReach] = true
|
|
}
|
|
}
|
|
|
|
// ModuleNeeds is ManifestNeeds of a module whose files take their text from templates (template.go): what the manifest
|
|
// needs and what each template's text writes, by template path (TemplatePaths), sorted. A module's needs are both: an
|
|
// engine renders the template's text as it renders inline content, so a template naming ${seat:x:reach} needs the
|
|
// reading as the same content inline does, though the manifest itself is unchanged (novox/hq ADR 0632 §2). A template
|
|
// named and not given is no need; the reader of the files says it could not read one.
|
|
func ModuleNeeds(raw []byte, templates map[string]string) ([]string, error) {
|
|
needs, err := ManifestNeeds(raw)
|
|
if err != nil || len(templates) == 0 {
|
|
return needs, err
|
|
}
|
|
used := map[string]bool{}
|
|
for _, n := range needs {
|
|
used[n] = true
|
|
}
|
|
for _, text := range templates {
|
|
textNeeds([]byte(text), used)
|
|
}
|
|
return sortedSet(used), nil
|
|
}
|
|
|
|
func sortedSet(set map[string]bool) []string {
|
|
out := make([]string, 0, len(set))
|
|
for k := range set {
|
|
out = append(out, k)
|
|
}
|
|
sort.Strings(out)
|
|
return out
|
|
}
|