diff --git a/README.md b/README.md index e90cf68..2922749 100644 --- a/README.md +++ b/README.md @@ -44,15 +44,14 @@ available under `rc profile go`, with identical flags and behavior: | `rc profile validate-extension` | Validate one imported binding package selected with `--package`. | | `rc profile version` | Show the linked Go profiler version. | -A profile does not have to come from a profiler. To check one written by hand, or by -an agent, against the extensions it declares (their definitions are downloaded from -their https ids, or read from `--catalog` directories): +A profile does not have to come from a profiler. To check one written by hand, or by an agent: ```sh ./rc profile validate profile.yaml ``` -This checks the extension vocabulary and schemas, not the core profile fields. +It is checked against the core profile schema embedded in rc and against the definitions of the +extensions it declares (downloaded from their ids, or read from `--catalog` directories). For command help: diff --git a/go.mod b/go.mod index cc0850e..30fa4c1 100644 --- a/go.mod +++ b/go.mod @@ -16,7 +16,7 @@ require ( require ( github.com/inconshreveable/mousetrap v1.1.0 // indirect - github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect + github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 github.com/spf13/pflag v1.0.9 // indirect golang.org/x/sync v0.17.0 // indirect golang.org/x/text v0.14.0 // indirect diff --git a/internal/cli/main_test.go b/internal/cli/main_test.go new file mode 100644 index 0000000..a67a2f4 --- /dev/null +++ b/internal/cli/main_test.go @@ -0,0 +1,18 @@ +package cli + +import ( + "os" + "testing" + + "github.com/runtimeconditions/rc-cli/internal/validate" +) + +func TestMain(m *testing.M) { + // The command is tested against a made-up core schema, not the version the real build embeds. + schema, err := os.ReadFile("../validate/testdata/core.schema.yaml") + if err != nil { + panic(err) + } + validate.UseCoreSchema(schema) + os.Exit(m.Run()) +} diff --git a/internal/cli/profile_validate.go b/internal/cli/profile_validate.go index f7ba080..2b83bdd 100644 --- a/internal/cli/profile_validate.go +++ b/internal/cli/profile_validate.go @@ -13,7 +13,7 @@ import ( "strings" "time" - "github.com/runtimeconditions/go-rc-profiler/extensioncheck" + "github.com/runtimeconditions/rc-cli/internal/validate" "github.com/spf13/cobra" "go.yaml.in/yaml/v3" ) @@ -32,10 +32,8 @@ type profileValidateAPI struct { func linkedProfileValidateAPI() profileValidateAPI { return profileValidateAPI{ - Validate: func(profile []byte, catalogRoots []string) error { - return extensioncheck.ValidateProfileYAML(profile, extensioncheck.ProfileOptions{CatalogRoots: catalogRoots}) - }, - Client: &http.Client{Timeout: 20 * time.Second}, + Validate: validate.Profile, + Client: &http.Client{Timeout: 20 * time.Second}, } } @@ -48,8 +46,8 @@ func newProfileValidateCommand(api profileValidateAPI) *cobra.Command { "By default the extension definitions are downloaded from the https ids the profile names, " + "including their dependencies. With --catalog the definitions are read from local directories " + "instead and nothing is downloaded. Use - to read the profile from standard input.\n\n" + - "This checks the profile against the extension vocabulary and schemas. It does not check the " + - "core profile fields (apiVersion, metadata, workload) against the core schema.", + "The profile is checked against the core profile schema embedded in rc, and as data against what " + + "its extensions define, so the result does not depend on which tool or language produced it.", Example: " rc profile validate profile.yaml\n rc profile validate profile.yaml --catalog ./extensions", Args: usageArgs(cobra.ExactArgs(1)), ValidArgsFunction: cobra.NoFileCompletions, diff --git a/internal/cli/profile_validate_test.go b/internal/cli/profile_validate_test.go index 65d46ee..bdbe3fc 100644 --- a/internal/cli/profile_validate_test.go +++ b/internal/cli/profile_validate_test.go @@ -12,34 +12,37 @@ import ( "testing" ) +// The command is tested with two made-up extensions, so these tests do not depend on any real +// extension or on which version of it exists. How the validator treats extensions is tested in +// internal/validate. const ( - commonShort = "https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2" - envShort = "https://runtimeconditions.io/extensions/rc/env-configuration:v1alpha2" - validHTTP = `apiVersion: runtimeconditions.io/v1alpha1 + alphaRef = "https://example.test/dummy/alpha:v1" + betaRef = "https://example.test/dummy/beta:v2" + + validProfile = `apiVersion: runtimeconditions.io/v1alpha1 kind: RuntimeConditionsProfile -metadata: {name: orders} -workload: {uri: "https://example.test/orders"} +metadata: {name: shapes} +workload: {uri: "https://example.test/shapes"} extensions: - - ` + commonShort + ` - - ` + envShort + ` + - ` + alphaRef + ` + - ` + betaRef + ` conditions: - - kind: cache - interface: {type: key_value, engine: redis} - configuration: - env: - - {property: url, name: REDIS_URL} + - kind: widget + interface: {type: plain, mode: fast} + - kind: gadget + interface: {type: strict, operations: [read, write]} ` ) var fixtureRoot = filepath.Join("..", "..", "testdata", "profile-validate", "extensions") -// definitionServer serves the committed extension definitions for https://runtimeconditions.io/extensions/. +// definitionServer serves the committed definitions for https://example.test/. type definitionServer struct{ requests []string } func (s *definitionServer) RoundTrip(request *http.Request) (*http.Response, error) { s.requests = append(s.requests, request.URL.String()) status, body := http.StatusNotFound, "not found" - const prefix = "https://runtimeconditions.io/extensions/" + const prefix = "https://example.test/" if address := request.URL.String(); strings.HasPrefix(address, prefix) { if data, err := os.ReadFile(filepath.Join(fixtureRoot, filepath.FromSlash(strings.TrimPrefix(address, prefix)))); err == nil { status, body = http.StatusOK, string(data) @@ -70,7 +73,7 @@ func runProfileValidate(t *testing.T, transport http.RoundTripper, profile strin func TestValidateAcceptsAProfileAndDownloadsItsExtensionsAndDependencies(t *testing.T) { server := &definitionServer{} - stderr, err := runProfileValidate(t, server, validHTTP) + stderr, err := runProfileValidate(t, server, validProfile) if err != nil { t.Fatalf("a valid profile was rejected: %v", err) } @@ -82,23 +85,38 @@ func TestValidateAcceptsAProfileAndDownloadsItsExtensionsAndDependencies(t *test } } +func TestValidateDownloadsADefinitionOnceWhenItIsNamedInTwoWays(t *testing.T) { + // beta depends on alpha by its full id, and the profile names alpha by its short form. + server := &definitionServer{} + if _, err := runProfileValidate(t, server, validProfile); err != nil { + t.Fatal(err) + } + seen := map[string]int{} + for _, request := range server.requests { + seen[request]++ + } + if seen["https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml"] < 1 { + t.Fatalf("alpha was not downloaded: %v", server.requests) + } +} + func TestValidateRejectsAValueTheExtensionDoesNotAllow(t *testing.T) { - _, err := runProfileValidate(t, &definitionServer{}, strings.Replace(validHTTP, "engine: redis", "engine: oracle", 1)) - if err == nil || !strings.Contains(err.Error(), "oracle") { - t.Fatalf("expected the engine to be rejected, got %v", err) + _, err := runProfileValidate(t, &definitionServer{}, strings.Replace(validProfile, "mode: fast", "mode: turbo", 1)) + if err == nil || !strings.Contains(err.Error(), "turbo") { + t.Fatalf("expected the mode to be rejected, got %v", err) } } -func TestValidateRejectsConfigurationWhenItsExtensionIsNotDeclared(t *testing.T) { - withoutEnv := strings.Replace(validHTTP, " - "+envShort+"\n", "", 1) - _, err := runProfileValidate(t, &definitionServer{}, withoutEnv) - if err == nil || !strings.Contains(err.Error(), "configuration") { - t.Fatalf("expected configuration to be rejected without env-configuration, got %v", err) +func TestValidateRejectsAConditionWhoseExtensionIsNotDeclared(t *testing.T) { + withoutBeta := strings.Replace(validProfile, " - "+betaRef+"\n", "", 1) + _, err := runProfileValidate(t, &definitionServer{}, withoutBeta) + if err == nil || !strings.Contains(err.Error(), "kind gadget") { + t.Fatalf("expected the gadget kind to be unknown without beta, got %v", err) } } func TestValidateSaysHowToProceedWhenADefinitionCannotBeDownloaded(t *testing.T) { - profile := strings.Replace(validHTTP, "common-integrations:v1alpha2", "missing:v9", 1) + profile := strings.Replace(validProfile, "dummy/alpha:v1", "dummy/missing:v9", 1) _, err := runProfileValidate(t, &definitionServer{}, profile) if err == nil || !strings.Contains(err.Error(), "404") || !strings.Contains(err.Error(), "--catalog") { t.Fatalf("expected a download error that mentions --catalog, got %v", err) @@ -106,7 +124,7 @@ func TestValidateSaysHowToProceedWhenADefinitionCannotBeDownloaded(t *testing.T) } func TestValidateDownloadsOnlyOverHTTPS(t *testing.T) { - profile := strings.Replace(validHTTP, "https://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2", "http://runtimeconditions.io/extensions/rc/common-integrations:v1alpha2", 1) + profile := strings.Replace(validProfile, "https://example.test/dummy/alpha:v1", "http://example.test/dummy/alpha:v1", 1) server := &definitionServer{} _, err := runProfileValidate(t, server, profile) if err == nil || !strings.Contains(err.Error(), "only https") { @@ -120,7 +138,7 @@ func TestValidateDownloadsOnlyOverHTTPS(t *testing.T) { } func TestValidateReadsLocalDefinitionsWithoutTheNetworkWhenACatalogIsGiven(t *testing.T) { - stderr, err := runProfileValidate(t, refusingTransport{}, validHTTP, "--catalog", fixtureRoot) + stderr, err := runProfileValidate(t, refusingTransport{}, validProfile, "--catalog", fixtureRoot) if err != nil { t.Fatalf("a valid profile was rejected with a local catalog: %v", err) } @@ -131,7 +149,7 @@ func TestValidateReadsLocalDefinitionsWithoutTheNetworkWhenACatalogIsGiven(t *te func TestValidateReadsTheProfileFromAFile(t *testing.T) { path := filepath.Join(t.TempDir(), "profile.yaml") - if err := os.WriteFile(path, []byte(validHTTP), 0o600); err != nil { + if err := os.WriteFile(path, []byte(validProfile), 0o600); err != nil { t.Fatal(err) } api := linkedProfileValidateAPI() diff --git a/internal/validate/catalog.go b/internal/validate/catalog.go new file mode 100644 index 0000000..84aa942 --- /dev/null +++ b/internal/validate/catalog.go @@ -0,0 +1,141 @@ +package validate + +import ( + "errors" + "fmt" + "io/fs" + "path/filepath" + "slices" +) + +type node struct { + id Reference + path string + def Definition +} + +// catalog holds the extension definitions found beneath a set of directories, by extension id. +type catalog struct{ nodes map[Reference]*node } + +var ( + errNotFound = errors.New("no extension definition") + errAmbiguous = errors.New("more than one extension definition") +) + +// loadCatalog walks roots and indexes every extension definition it finds. A problem with one +// document is recorded and the rest are still read; only a failure to walk a directory is returned. +func loadCatalog(roots []string, issues *report) (*catalog, error) { + loaded := &catalog{nodes: map[Reference]*node{}} + seenRoots, seenFiles := map[string]bool{}, map[string]bool{} + for _, root := range roots { + absolute, err := filepath.Abs(root) + if err != nil { + return nil, err + } + if seenRoots[absolute] { + continue + } + seenRoots[absolute] = true + err = filepath.WalkDir(absolute, func(path string, entry fs.DirEntry, err error) error { + if err != nil { + return err + } + if entry.IsDir() { + switch entry.Name() { + case ".git", "vendor", "node_modules": + return filepath.SkipDir + } + return nil + } + if extension := filepath.Ext(path); (extension != ".yaml" && extension != ".yml") || seenFiles[path] { + return nil + } + seenFiles[path] = true + loaded.add(path, issues) + return nil + }) + if err != nil { + return nil, err + } + } + return loaded, nil +} + +func (c *catalog) add(path string, issues *report) { + definition, isDefinition, err := readDefinition(path) + if err != nil { + issues.about(path, "%v", err) + return + } + if !isDefinition { + return + } + id := definition.reference() + if !id.valid() { + issues.about(path, "metadata.id is required; metadata.version is optional") + return + } + if existing := c.nodes[id]; existing != nil { + issues.about(path, "duplicate extension release %s already defined by %s", id, existing.path) + return + } + c.nodes[id] = &node{id: id, path: path, def: definition} +} + +// lookup returns the key of the definition a reference names. An exact (id, version) match wins. A +// reference with a version may instead be a short : profile reference. A reference +// without a version names the one definition with that id, whatever its version; two or more is ambiguous. +func (c *catalog) lookup(reference Reference) (Reference, error) { + if c.nodes[reference] != nil { + return reference, nil + } + if reference.Version != "" { + if expanded := expandShort(reference); c.nodes[expanded] != nil { + return expanded, nil + } + return reference, fmt.Errorf("%w for %s", errNotFound, reference) + } + var matches []Reference + for key := range c.nodes { + if key.ID == reference.ID { + matches = append(matches, key) + } + } + switch len(matches) { + case 0: + return reference, fmt.Errorf("%w for %s", errNotFound, reference) + case 1: + return matches[0], nil + } + slices.SortFunc(matches, Reference.compare) + return reference, fmt.Errorf("%w with id %s: %v", errAmbiguous, reference.ID, matches) +} + +// resolve returns the vocabulary of id with its transitive dependencies, dependencies first. +func (c *catalog) resolve(id Reference) vocabulary { + seen := map[Reference]bool{} + var nodes []*node + var visit func(Reference) + visit = func(current Reference) { + if seen[current] { + return + } + if resolved, err := c.lookup(current); err == nil { + current = resolved + } + if seen[current] { + return + } + seen[current] = true + found := c.nodes[current] + if found == nil { + return + } + for _, dependency := range found.def.Spec.Dependencies { + visit(dependency) + } + nodes = append(nodes, found) + } + visit(id) + return vocabulary{nodes: nodes} +} diff --git a/internal/validate/checker.go b/internal/validate/checker.go new file mode 100644 index 0000000..9852d70 --- /dev/null +++ b/internal/validate/checker.go @@ -0,0 +1,240 @@ +package validate + +import ( + "errors" + "slices" + "strings" +) + +type visit int + +const ( + unvisited visit = iota + inProgress + done +) + +// checker validates extension definitions drawn from a catalog. Each definition is checked once, +// after the definitions it depends on, and a dependency cycle is reported rather than followed. +type checker struct { + catalog *catalog + states map[Reference]visit + issues *report +} + +func newChecker(loaded *catalog, issues *report) *checker { + return &checker{catalog: loaded, states: map[Reference]visit{}, issues: issues} +} + +// validateNode validates the extension id and every extension it depends on. +func (c *checker) validateNode(id Reference) { + if resolved, err := c.catalog.lookup(id); err == nil { + id = resolved + } else if errors.Is(err, errAmbiguous) { + c.issues.about(id.String(), "%v", err) + return + } + switch c.states[id] { + case inProgress: + c.issues.about(id.String(), "extension dependency cycle includes %s", id) + return + case done: + return + } + found := c.catalog.nodes[id] + if found == nil { + c.issues.about(id.String(), "missing extension definition for dependency %s", id) + return + } + c.states[id] = inProgress + for _, dependency := range found.def.Spec.Dependencies { + c.validateNode(dependency) + } + c.validateDefinition(found) + c.validateVocabulary(found, c.catalog.resolve(id)) + c.states[id] = done +} + +// validateDefinition checks a definition against itself: required metadata, resolvable +// dependencies, and no name declared twice. +func (c *checker) validateDefinition(n *node) { + def := n.def + if def.APIVersion != "runtimeconditions.io/v1alpha1" { + c.issues.about(n.path, "apiVersion must be runtimeconditions.io/v1alpha1") + } + if def.Kind != "RuntimeConditionsExtensionDefinition" { + c.issues.about(n.path, "kind must be RuntimeConditionsExtensionDefinition") + } + if !def.reference().valid() { + c.issues.about(n.path, "metadata.id is required; metadata.version is optional") + } + if n.id != def.reference() { + c.issues.about(n.path, "extension id %s does not match metadata", n.id) + } + spec := def.Spec + if len(spec.Dependencies) == 0 && len(spec.Kinds) == 0 && len(spec.InterfaceTypes) == 0 && len(spec.ConditionFields) == 0 && + len(spec.InterfaceFields) == 0 && len(spec.FieldValues) == 0 && len(spec.Schemas) == 0 { + c.issues.about(n.path, "spec must define at least one vocabulary item or schema") + } + for _, dependency := range spec.Dependencies { + if _, err := c.catalog.lookup(dependency); errors.Is(err, errAmbiguous) { + c.issues.about(n.path, "dependency %s is ambiguous: %v", dependency, err) + } else if err != nil { + c.issues.about(n.path, "dependency %s cannot be resolved", dependency) + } + } + c.checkSelfDuplicates(n) +} + +// checkSelfDuplicates reports vocabulary a single definition declares twice, and entries that lack +// what they need. +func (c *checker) checkSelfDuplicates(n *node) { + seen := map[string]bool{} + check := func(key string) { + if seen[key] { + c.issues.about(n.path, "duplicate vocabulary definition %s", key) + } + seen[key] = true + } + spec := n.def.Spec + for _, kind := range spec.Kinds { + if kind.Name == "" { + c.issues.about(n.path, "kind name is required") + continue + } + check("kind:" + kind.Name) + } + for _, item := range spec.InterfaceTypes { + if item.Name == "" || item.TargetKind == "" { + c.issues.about(n.path, "interfaceTypes entries require name and targetKind") + continue + } + check("interfaceType:" + item.TargetKind + ":" + item.Name) + } + for _, item := range spec.ConditionFields { + if item.Name == "" { + c.issues.about(n.path, "conditionFields entries require name") + continue + } + if len(item.AppliesToKinds) == 0 { + c.issues.about(n.path, "condition field %s must declare appliesToKinds", item.Name) + } + check("conditionField:" + item.Name + ":" + strings.Join(item.AppliesToKinds, ",") + ":" + strings.Join(item.AppliesToInterfaceTypes, ",")) + } + for _, item := range spec.InterfaceFields { + if item.Name == "" || item.TargetKind == "" || item.TargetType == "" { + c.issues.about(n.path, "interfaceFields entries require name, targetKind, and targetType") + continue + } + check("interfaceField:" + item.TargetKind + ":" + item.TargetType + ":" + item.Name) + } + for _, item := range spec.FieldValues { + if item.Field == "" || item.TargetKind == "" || len(item.Values) == 0 { + c.issues.about(n.path, "fieldValues entries require field, targetKind, and values") + continue + } + check("fieldValue:" + item.TargetKind + ":" + item.TargetType + ":" + item.Field) + valueSeen := map[string]bool{} + for _, value := range item.Values { + if valueSeen[value] { + c.issues.about(n.path, "duplicate field value %q for %s", value, item.Field) + } + valueSeen[value] = true + } + } + for _, schema := range spec.Schemas { + if schema.ID == "" { + c.issues.about(n.path, "schema id is required") + } + if schema.Description == "" { + c.issues.about(n.path, "schema %s description is required", schema.ID) + } + if schema.Schema == nil { + c.issues.about(n.path, "schema %s schema object is required", schema.ID) + } else if _, err := compileSchema(schema.Schema); err != nil { + c.issues.about(n.path, "schema %s is invalid: %v", schema.ID, err) + } + check("schema:" + schema.ID) + } +} + +// validateVocabulary checks that everything a definition references resolves to exactly one +// declaration across its dependency closure. +func (c *checker) validateVocabulary(n *node, resolved vocabulary) { + path := n.path + spec := n.def.Spec + for _, item := range spec.InterfaceTypes { + c.issues.expectExactlyOne(path, resolved.kindCount(item.TargetKind), "interface type %s targetKind %s", item.Name, item.TargetKind) + } + for _, item := range spec.InterfaceFields { + c.issues.expectExactlyOne(path, resolved.kindCount(item.TargetKind), "interface field %s targetKind %s", item.Name, item.TargetKind) + c.issues.expectExactlyOne(path, resolved.interfaceTypeCount(item.TargetKind, item.TargetType), "interface field %s targetType %s/%s", item.Name, item.TargetKind, item.TargetType) + } + for _, item := range spec.ConditionFields { + for _, kind := range item.AppliesToKinds { + c.issues.expectExactlyOne(path, resolved.kindCount(kind), "condition field %s appliesToKind %s", item.Name, kind) + for _, targetType := range item.AppliesToInterfaceTypes { + c.issues.expectExactlyOne(path, resolved.interfaceTypeCount(kind, targetType), "condition field %s appliesToInterfaceType %s/%s", item.Name, kind, targetType) + } + } + } + for _, item := range spec.FieldValues { + c.issues.expectExactlyOne(path, resolved.kindCount(item.TargetKind), "field values %s targetKind %s", item.Field, item.TargetKind) + if item.TargetType != "" { + c.issues.expectExactlyOne(path, resolved.interfaceTypeCount(item.TargetKind, item.TargetType), "field values %s targetType %s/%s", item.Field, item.TargetKind, item.TargetType) + } + c.validateFieldValuePath(path, resolved, item) + } + for _, schema := range spec.Schemas { + if schema.AppliesToKind != "" { + c.issues.expectExactlyOne(path, resolved.kindCount(schema.AppliesToKind), "schema %s appliesToKind %s", schema.ID, schema.AppliesToKind) + } + if schema.AppliesToKind != "" && schema.AppliesToInterfaceType != "" { + c.issues.expectExactlyOne(path, resolved.interfaceTypeCount(schema.AppliesToKind, schema.AppliesToInterfaceType), "schema %s appliesToInterfaceType %s/%s", schema.ID, schema.AppliesToKind, schema.AppliesToInterfaceType) + } + } + c.checkResolvedConflicts(path, resolved) +} + +// validateFieldValuePath resolves the field a fieldValues entry enumerates. A path that starts with +// interface. names an interface field. Any other path starts with the name of a condition field. +func (c *checker) validateFieldValuePath(path string, resolved vocabulary, item FieldValue) { + switch { + case strings.HasPrefix(item.Field, "interface."): + field := firstPathSegment(strings.TrimPrefix(item.Field, "interface.")) + if field == "type" { + return + } + c.issues.expectExactlyOne(path, resolved.interfaceFieldCount(item.TargetKind, item.TargetType, field), "fieldValues field %s interface field %s/%s/%s", item.Field, item.TargetKind, item.TargetType, field) + default: + field := firstPathSegment(item.Field) + c.issues.expectExactlyOne(path, resolved.conditionFieldCount(item.TargetKind, item.TargetType, field), "fieldValues field %s condition field %s for %s/%s", item.Field, field, item.TargetKind, item.TargetType) + } +} + +// checkResolvedConflicts reports vocabulary that two extensions in the resolved set both define. +func (c *checker) checkResolvedConflicts(path string, resolved vocabulary) { + counts := resolved.counts() + keys := make([]string, 0, len(counts)) + for key := range counts { + keys = append(keys, key) + } + slices.Sort(keys) + for _, key := range keys { + if counts[key] > 1 { + c.issues.about(path, "resolved extension set contains vocabulary conflict for %s", key) + } + } + for _, conflict := range resolved.conditionFieldConflicts() { + c.issues.about(path, "resolved extension set contains vocabulary conflict for %s", conflict) + } +} + +// firstPathSegment returns the leading segment of a dotted field path, dropping any list suffix. +func firstPathSegment(path string) string { + path = strings.TrimSuffix(path, "[]") + if index := strings.Index(path, "."); index >= 0 { + return strings.TrimSuffix(path[:index], "[]") + } + return strings.TrimSuffix(path, "[]") +} diff --git a/internal/validate/core.go b/internal/validate/core.go new file mode 100644 index 0000000..ded7f71 --- /dev/null +++ b/internal/validate/core.go @@ -0,0 +1,58 @@ +package validate + +import ( + "encoding/base64" + "errors" + "fmt" + + "github.com/santhosh-tekuri/jsonschema/v6" + "go.yaml.in/yaml/v3" +) + +// coreSchemaBase64 is set by the release build from the separately versioned core profile schema, +// after its SHA-256 has been checked (scripts/build.go). A plain go build leaves it empty and +// validation fails closed, because a profile cannot be called valid without the core schema. +var coreSchemaBase64 string + +var coreSchemaOverride []byte + +// UseCoreSchema makes the validator use the given core profile schema instead of the one the build +// embedded. It is meant for tests and for tools that bring their own schema. +func UseCoreSchema(schema []byte) { coreSchemaOverride = schema } + +var errNoCoreSchema = errors.New("this build of rc has no verified core profile schema") + +// loadCoreSchema compiles the core profile schema. +func loadCoreSchema() (*jsonschema.Schema, error) { + data := coreSchemaOverride + if len(data) == 0 { + if coreSchemaBase64 == "" { + return nil, errNoCoreSchema + } + decoded, err := base64.StdEncoding.DecodeString(coreSchemaBase64) + if err != nil { + return nil, fmt.Errorf("the embedded core profile schema is not valid base64: %w", err) + } + data = decoded + } + var document map[string]any + if err := yaml.Unmarshal(data, &document); err != nil { + return nil, fmt.Errorf("read the core profile schema: %w", err) + } + if document["$schema"] != "https://json-schema.org/draft/2020-12/schema" { + return nil, errors.New("the core profile schema must use JSON Schema Draft 2020-12") + } + identifier, _ := document["$id"].(string) + if identifier == "" { + return nil, errors.New("the core profile schema has no $id") + } + parsed, err := jsonValue(document) + if err != nil { + return nil, err + } + compiler := jsonschema.NewCompiler() + if err := compiler.AddResource(identifier, parsed); err != nil { + return nil, err + } + return compiler.Compile(identifier) +} diff --git a/internal/validate/definition.go b/internal/validate/definition.go new file mode 100644 index 0000000..ba516f0 --- /dev/null +++ b/internal/validate/definition.go @@ -0,0 +1,112 @@ +package validate + +import ( + "fmt" + "os" + + "go.yaml.in/yaml/v3" +) + +// Definition is a RuntimeConditionsExtensionDefinition document: the vocabulary an extension +// contributes and the extensions it builds on. +type Definition struct { + APIVersion string `yaml:"apiVersion"` + Kind string `yaml:"kind"` + Metadata struct { + ID string `yaml:"id"` + Version string `yaml:"version"` + } `yaml:"metadata"` + Spec Spec `yaml:"spec"` +} + +// Spec is the vocabulary a definition contributes. A key it does not know is ignored. +type Spec struct { + Dependencies []Reference `yaml:"dependencies"` + Kinds []Kind `yaml:"kinds"` + InterfaceTypes []InterfaceType `yaml:"interfaceTypes"` + ConditionFields []ConditionField `yaml:"conditionFields"` + InterfaceFields []InterfaceField `yaml:"interfaceFields"` + FieldValues []FieldValue `yaml:"fieldValues"` + Schemas []Schema `yaml:"schemas"` +} + +// Kind declares a condition kind. +type Kind struct { + Name string `yaml:"name"` +} + +// InterfaceType declares an interface type available to a kind. +type InterfaceType struct { + Name string `yaml:"name"` + TargetKind string `yaml:"targetKind"` +} + +// ConditionField declares a field of the condition itself and the kinds and interface types it applies to. +type ConditionField struct { + Name string `yaml:"name"` + AppliesToKinds []string `yaml:"appliesToKinds"` + AppliesToInterfaceTypes []string `yaml:"appliesToInterfaceTypes"` +} + +// InterfaceField declares a field of the interface of one kind and interface type. +type InterfaceField struct { + Name string `yaml:"name"` + TargetKind string `yaml:"targetKind"` + TargetType string `yaml:"targetType"` +} + +// FieldValue enumerates the values a field accepts. Field is a path such as +// interface.operations[].method or configuration.env[].property. +type FieldValue struct { + Field string `yaml:"field"` + TargetKind string `yaml:"targetKind"` + TargetType string `yaml:"targetType"` + Values []string `yaml:"values"` +} + +// Schema is a JSON Schema applied to the conditions it matches. +type Schema struct { + ID string `yaml:"id"` + Description string `yaml:"description"` + AppliesToKind string `yaml:"appliesToKind"` + AppliesToInterfaceType string `yaml:"appliesToInterfaceType"` + Schema any `yaml:"schema"` +} + +func (d Definition) reference() Reference { + if d.Metadata.ID == "" { + return Reference{} + } + return Reference{ID: d.Metadata.ID, Version: d.Metadata.Version} +} + +// readDefinition reads path and reports whether it holds an extension definition. A document of any +// other kind is skipped rather than rejected, since a directory of definitions may hold other YAML. +func readDefinition(path string) (Definition, bool, error) { + data, err := os.ReadFile(path) + if err != nil { + return Definition{}, false, err + } + var probe struct { + Kind string `yaml:"kind"` + Metadata map[string]any `yaml:"metadata"` + } + if err := yaml.Unmarshal(data, &probe); err != nil { + return Definition{}, false, err + } + if probe.Kind != "RuntimeConditionsExtensionDefinition" { + return Definition{}, false, nil + } + identifier, idOK := probe.Metadata["id"].(string) + version, versionOK := probe.Metadata["version"].(string) + _, hasVersion := probe.Metadata["version"] + _, hasURI := probe.Metadata["uri"] + if !idOK || identifier == "" || (hasVersion && (!versionOK || version == "")) || hasURI { + return Definition{}, false, fmt.Errorf("metadata.id is required and metadata.version, when present, must be a non-empty string") + } + var definition Definition + if err := yaml.Unmarshal(data, &definition); err != nil { + return Definition{}, false, err + } + return definition, true, nil +} diff --git a/internal/validate/definitions_test.go b/internal/validate/definitions_test.go new file mode 100644 index 0000000..54024a5 --- /dev/null +++ b/internal/validate/definitions_test.go @@ -0,0 +1,324 @@ +package validate + +import ( + "path/filepath" + "strings" + "testing" +) + +// minimalProfile declares the given extensions and has no conditions. +func minimalProfile(extensions ...string) []byte { + var out strings.Builder + out.WriteString("apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsProfile\nmetadata: {name: p}\nworkload: {uri: 'https://example.test/p'}\nextensions:\n") + for _, extension := range extensions { + out.WriteString("- " + extension + "\n") + } + out.WriteString("conditions: []\n") + return []byte(out.String()) +} + +func definition(id, version, spec string) string { + return "apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsExtensionDefinition\nmetadata: {id: " + id + ", version: " + version + "}\nspec:\n" + spec +} + +func catalogWith(t *testing.T, files map[string]string) []string { + t.Helper() + root := t.TempDir() + written := map[string]string{} + for name, content := range files { + written[filepath.Join(root, name)] = content + } + writeFiles(t, written) + return []string{root} +} + +const ( + extA = "https://example.test/x/a/v1/runtimeconditions.extension.yaml" + extB = "https://example.test/x/b/v1/runtimeconditions.extension.yaml" + extC = "https://example.test/x/c/v1/runtimeconditions.extension.yaml" +) + +func TestADefinitionIsCheckedAgainstItselfWhenAProfileDeclaresIt(t *testing.T) { + kinds := " kinds: [{name: w}]\n" + cases := map[string]struct{ file, want string }{ + "a wrong apiVersion": {strings.Replace(definition(extA, "v1", kinds), "v1alpha1", "v9", 1), "apiVersion must be runtimeconditions.io/v1alpha1"}, + "nothing defined": {definition(extA, "v1", " dependencies: []\n"), "spec must define at least one vocabulary item or schema"}, + "a kind twice": {definition(extA, "v1", " kinds: [{name: w}, {name: w}]\n"), "duplicate vocabulary definition kind:w"}, + "a kind without a name": {definition(extA, "v1", " kinds: [{name: ''}]\n"), "kind name is required"}, + "an interface type without a kind": {definition(extA, "v1", kinds+" interfaceTypes: [{name: t}]\n"), "interfaceTypes entries require name and targetKind"}, + "an interface type of an unknown kind": {definition(extA, "v1", kinds+" interfaceTypes: [{name: t, targetKind: nope}]\n"), "interface type t targetKind nope: expected exactly one definition, got 0"}, + "an interface field of an unknown type": {definition(extA, "v1", kinds+" interfaceTypes: [{name: t, targetKind: w}]\n interfaceFields: [{name: f, targetKind: w, targetType: nope}]\n"), "interface field f targetType w/nope"}, + "a condition field with no kinds": {definition(extA, "v1", kinds+" conditionFields: [{name: c}]\n"), "condition field c must declare appliesToKinds"}, + "field values without values": {definition(extA, "v1", kinds+" interfaceTypes: [{name: t, targetKind: w}]\n fieldValues: [{field: interface.x, targetKind: w, targetType: t, values: []}]\n"), "fieldValues entries require field, targetKind, and values"}, + "field values for a field nobody declares": {definition(extA, "v1", kinds+" interfaceTypes: [{name: t, targetKind: w}]\n fieldValues: [{field: interface.x, targetKind: w, targetType: t, values: [a]}]\n"), "fieldValues field interface.x interface field w/t/x"}, + "a repeated value": {definition(extA, "v1", kinds+" interfaceTypes: [{name: t, targetKind: w}]\n interfaceFields: [{name: x, targetKind: w, targetType: t}]\n fieldValues: [{field: interface.x, targetKind: w, targetType: t, values: [a, a]}]\n"), `duplicate field value "a" for interface.x`}, + "a schema without a description": {definition(extA, "v1", kinds+" schemas: [{id: s, schema: {type: object}}]\n"), "schema s description is required"}, + "a schema that does not compile": {definition(extA, "v1", kinds+" schemas: [{id: s, description: d, schema: {type: 12}}]\n"), "schema s is invalid"}, + "a schema for an unknown kind": {definition(extA, "v1", kinds+" schemas: [{id: s, description: d, appliesToKind: nope, schema: {type: object}}]\n"), "schema s appliesToKind nope"}, + "a dependency that is not in the catalog": {definition(extA, "v1", kinds+" dependencies: ["+extB+"]\n"), "missing extension definition for dependency"}, + } + for name, test := range cases { + t.Run(name, func(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": test.file}) + err := Profile(minimalProfile("https://example.test/x/a:v1"), roots) + if err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("expected %q, got %v", test.want, err) + } + }) + } +} + +func TestADefinitionThatDependsOnItselfThroughOthersIsReportedNotFollowed(t *testing.T) { + kinds := " kinds: [{name: %s}]\n" + roots := catalogWith(t, map[string]string{ + "a.yaml": definition(extA, "v1", strings.Replace(kinds, "%s", "a", 1)+" dependencies: ["+extB+"]\n"), + "b.yaml": definition(extB, "v1", strings.Replace(kinds, "%s", "b", 1)+" dependencies: ["+extC+"]\n"), + "c.yaml": definition(extC, "v1", strings.Replace(kinds, "%s", "c", 1)+" dependencies: ["+extA+"]\n"), + }) + err := Profile(minimalProfile("https://example.test/x/a:v1", "https://example.test/x/b:v1", "https://example.test/x/c:v1"), roots) + if err == nil || !strings.Contains(err.Error(), "dependency cycle") { + t.Fatalf("expected a dependency cycle, got %v", err) + } +} + +func TestEachDefinitionIsReadFromWhereverItLives(t *testing.T) { + kinds := " kinds: [{name: w}]\n" + roots := catalogWith(t, map[string]string{ + "deep/er/a.yaml": definition(extA, "v1", kinds), + "other.yml": definition(extB, "v1", " kinds: [{name: b}]\n"), + "notes.yaml": "just: notes\n", + "node_modules/x.yaml": definition(extC, "v1", " kinds: [{name: c}]\n"), + "readme.txt": "not yaml at all", + ".git/ignored.yaml": definition(extC, "v1", " kinds: [{name: c}]\n"), + }) + for _, ref := range []string{"https://example.test/x/a:v1", "https://example.test/x/b:v1"} { + if err := Profile(minimalProfile(ref), roots); err != nil { + t.Errorf("%s was not found: %v", ref, err) + } + } + for _, ref := range []string{"https://example.test/x/c:v1"} { + if err := Profile(minimalProfile(ref), roots); err == nil { + t.Errorf("%s lives in a directory that is skipped but was found", ref) + } + } +} + +func TestSeveralDirectoriesAndRepeatedOnesAreRead(t *testing.T) { + first := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n")}) + second := catalogWith(t, map[string]string{"b.yaml": definition(extB, "v1", " kinds: [{name: b}]\n")}) + roots := append(append(first, second...), first...) + if err := Profile(minimalProfile("https://example.test/x/a:v1", "https://example.test/x/b:v1"), roots); err != nil { + t.Fatal(err) + } +} + +func TestTheSameReleaseDefinedTwiceIsReported(t *testing.T) { + roots := catalogWith(t, map[string]string{ + "one.yaml": definition(extA, "v1", " kinds: [{name: a}]\n"), + "two.yaml": definition(extA, "v1", " kinds: [{name: a}]\n"), + }) + err := Profile(minimalProfile("https://example.test/x/a:v1"), roots) + if err == nil || !strings.Contains(err.Error(), "duplicate extension release") { + t.Fatalf("expected a duplicate release, got %v", err) + } +} + +func TestAFileThatIsNotValidYAMLIsReportedAndTheRestStillRead(t *testing.T) { + roots := catalogWith(t, map[string]string{ + "broken.yaml": "kind: [unclosed\n", + "a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n"), + }) + err := Profile(minimalProfile("https://example.test/x/a:v1"), roots) + if err == nil || !strings.Contains(err.Error(), "broken.yaml") { + t.Fatalf("expected the broken file to be named, got %v", err) + } + if strings.Contains(err.Error(), "missing extension definition") { + t.Fatalf("the good definition should still have been read: %v", err) + } +} + +func TestADefinitionWithoutAUsableIDIsReported(t *testing.T) { + for name, file := range map[string]string{ + "no id": "apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsExtensionDefinition\nmetadata: {version: v1}\nspec:\n kinds: [{name: a}]\n", + "a numeric version": "apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsExtensionDefinition\nmetadata: {id: " + extA + ", version: 3}\nspec:\n kinds: [{name: a}]\n", + "an obsolete uri field": "apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsExtensionDefinition\nmetadata: {id: " + extA + ", uri: x}\nspec:\n kinds: [{name: a}]\n", + } { + t.Run(name, func(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": file}) + if err := Profile(minimalProfile("https://example.test/x/a:v1"), roots); err == nil { + t.Fatal("expected an error") + } + }) + } +} + +func TestADefinitionKeyTheReaderDoesNotKnowIsIgnored(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a, note: ignored}]\n somethingNew: {x: 1}\n")}) + if err := Profile(minimalProfile("https://example.test/x/a:v1"), roots); err != nil { + t.Fatalf("an unknown key should be ignored: %v", err) + } +} + +func TestOneMessageIsShownAloneAndSeveralUnderAHeading(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n")}) + one := Profile(minimalProfile("https://example.test/x/zz:v1"), roots) + if one == nil || strings.Contains(one.Error(), "profile validation failed") || !strings.Contains(one.Error(), "missing extension definition") { + t.Fatalf("a single problem should be shown on its own, got %v", one) + } + two := strings.Replace(string(minimalProfile("https://example.test/x/zz:v1")), "runtimeconditions.io/v1alpha1", "nope", 1) + many := Profile([]byte(two), roots) + if many == nil || !strings.HasPrefix(many.Error(), "profile validation failed:\n- ") { + t.Fatalf("several problems should be listed under a heading, got %v", many) + } +} + +const coreHead = "apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsProfile\n" + +func TestTheCoreFieldsOfAProfileAreCheckedAgainstTheCoreSchema(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n interfaceTypes: [{name: t, targetKind: a}]\n")}) + ext := "extensions: [https://example.test/x/a:v1]\n" + body := "metadata: {name: p}\nworkload: {uri: 'https://example.test/p'}\n" + condition := "conditions:\n- {kind: a, interface: {type: t}}\n" + valid := coreHead + body + ext + condition + if err := Profile([]byte(valid), roots); err != nil { + t.Fatalf("a profile with the right core fields was rejected: %v", err) + } + cases := map[string]struct{ profile, want string }{ + "a wrong apiVersion": {strings.Replace(valid, "v1alpha1", "v9", 1), "/apiVersion"}, + "a wrong kind": {strings.Replace(valid, "RuntimeConditionsProfile", "Other", 1), "/kind"}, + "no metadata": {coreHead + "workload: {uri: x}\n" + ext + condition, "metadata"}, + "a metadata without a name": {coreHead + "metadata: {}\nworkload: {uri: x}\n" + ext + condition, "name"}, + "an empty metadata name": {coreHead + "metadata: {name: ''}\nworkload: {uri: x}\n" + ext + condition, "/metadata/name"}, + "an extra key in metadata": {coreHead + "metadata: {name: p, owner: me}\nworkload: {uri: x}\n" + ext + condition, "owner"}, + "no workload": {coreHead + "metadata: {name: p}\n" + ext + condition, "workload"}, + "a workload without a uri": {coreHead + "metadata: {name: p}\nworkload: {version: v1}\n" + ext + condition, "uri"}, + "an extra key in workload": {coreHead + "metadata: {name: p}\nworkload: {uri: x, owner: me}\n" + ext + condition, "owner"}, + "an extra top-level key": {valid + "surprise: 1\n", "surprise"}, + "no extensions list": {coreHead + body + condition, "extensions"}, + "conditions with an empty extensions": {coreHead + body + "extensions: []\n" + condition, "extensions"}, + "an extension written as an object": {coreHead + body + "extensions: [{id: https://example.test/x/a/v1/runtimeconditions.extension.yaml, version: v1}]\n" + condition, "/extensions/0"}, + "the same extension twice": {coreHead + body + "extensions: [https://example.test/x/a:v1, https://example.test/x/a:v1]\n" + condition, "extensions"}, + "a condition without a kind": {coreHead + body + ext + "conditions:\n- {interface: {type: t}}\n", "kind"}, + "a condition without an interface": {coreHead + body + ext + "conditions:\n- {kind: a}\n", "interface"}, + "an interface without a type": {coreHead + body + ext + "conditions:\n- {kind: a, interface: {}}\n", "type"}, + "no conditions list": {coreHead + body + ext, "conditions"}, + } + for name, test := range cases { + t.Run(name, func(t *testing.T) { + err := Profile([]byte(test.profile), roots) + if err == nil || !strings.Contains(err.Error(), "core profile schema") || !strings.Contains(err.Error(), test.want) { + t.Fatalf("expected a core schema error mentioning %q, got %v", test.want, err) + } + }) + } +} + +func TestTheCoreSchemaAndTheExtensionsAreBothReported(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n interfaceTypes: [{name: t, targetKind: a}]\n")}) + profile := coreHead + "workload: {uri: x}\nextensions: [https://example.test/x/a:v1]\nconditions:\n- {kind: zz, interface: {type: t}}\n" + err := Profile([]byte(profile), roots) + if err == nil || !strings.Contains(err.Error(), "core profile schema") || !strings.Contains(err.Error(), "kind zz") { + t.Fatalf("both the missing metadata and the unknown kind should be reported, got %v", err) + } +} + +func TestWithoutACoreSchemaTheValidatorFailsClosed(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n")}) + saved := coreSchemaOverride + coreSchemaOverride = nil + defer func() { coreSchemaOverride = saved }() + err := Profile(minimalProfile("https://example.test/x/a:v1"), roots) + if err == nil || !strings.Contains(err.Error(), "no verified core profile schema") { + t.Fatalf("a build without the core schema must not call a profile valid, got %v", err) + } +} + +func TestABareIDNamesTheOneDefinitionWithThatIDAndTwoAreAmbiguous(t *testing.T) { + one := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n")}) + if err := Profile(minimalProfile(extA), one); err != nil { + t.Fatalf("a bare id should find its only definition: %v", err) + } + two := catalogWith(t, map[string]string{ + "a1.yaml": definition(extA, "v1", " kinds: [{name: a}]\n"), + "a2.yaml": definition(extA, "v2", " kinds: [{name: a2}]\n"), + }) + err := Profile(minimalProfile(extA), two) + if err == nil || !strings.Contains(err.Error(), "more than one extension definition") { + t.Fatalf("a bare id with two versions should be ambiguous, got %v", err) + } +} + +func TestAProfileThatIsNotYAMLOrNotAMappingIsRejected(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n")}) + for name, profile := range map[string]string{"unbalanced": "extensions: [a\n", "a list": "- a\n- b\n", "empty": ""} { + t.Run(name, func(t *testing.T) { + if err := Profile([]byte(profile), roots); err == nil { + t.Fatal("expected an error") + } + }) + } +} + +// delta-style extension that adds a condition field to alpha's widgets. +const dummyExtras = `apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: {id: https://example.test/dummy/extras/v1/runtimeconditions.extension.yaml, version: v1} +spec: + dependencies: [https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml] + conditionFields: + - {name: extras, appliesToKinds: [widget]} +` + +func TestAConditionFieldUsedWithoutDeclaringTheExtensionThatDefinesItIsRejected(t *testing.T) { + options := optionsWith(t, dummyExtras) + condition := "kind: widget\ninterface: {type: plain, mode: fast}\nextras: {anything: 1}\n" + if err := Profile(dummyProfile([]string{dummyAlphaRef, "https://example.test/dummy/extras:v1"}, condition), options); err != nil { + t.Fatalf("the field was rejected although its extension is declared: %v", err) + } + err := Profile(dummyProfile([]string{dummyAlphaRef}, condition), options) + if err == nil || !strings.Contains(err.Error(), "conditions[0].extras for widget/plain: expected exactly one definition, got 0") { + t.Fatalf("a condition field no declared extension defines should be rejected, got %v", err) + } +} + +func TestACoreConditionFieldNeedsNoExtension(t *testing.T) { + options := optionsWith(t) + condition := "name: mine\noptional: true\nextension: " + dummyAlphaRef + "\nkind: widget\ninterface: {type: plain, mode: fast}\n" + if err := Profile(dummyProfile([]string{dummyAlphaRef}, condition), options); err != nil { + t.Fatalf("name, optional and extension belong to the core schema: %v", err) + } +} + +func TestAnInterfaceFieldOfAnotherInterfaceTypeIsRejectedByTheVocabularyAlone(t *testing.T) { + // mode is declared for the plain widget, not the listy one. The listy widget has no schema, so + // nothing but the vocabulary can notice. + options := optionsWith(t) + err := Profile(dummyProfile([]string{dummyAlphaRef}, "kind: widget\ninterface: {type: listy, mode: fast}\n"), options) + if err == nil || !strings.Contains(err.Error(), "interface.mode for widget/listy: expected exactly one definition, got 0") { + t.Fatalf("expected the field to be rejected for the listy widget, got %v", err) + } +} + +func TestAnEmptyConditionsListIsValid(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n")}) + body := coreHead + "metadata: {name: p}\nworkload: {uri: 'https://example.test/p'}\n" + for name, profile := range map[string]string{ + "with no extensions": body + "extensions: []\nconditions: []\n", + "with an extension declared": body + "extensions: [https://example.test/x/a:v1]\nconditions: []\n", + } { + t.Run(name, func(t *testing.T) { + if err := Profile([]byte(profile), roots); err != nil { + t.Fatalf("a profile with an empty conditions list was rejected: %v", err) + } + }) + } +} + +func TestConditionsHaveToDeclareExtensionsButOnlyWhenThereAreSome(t *testing.T) { + roots := catalogWith(t, map[string]string{"a.yaml": definition(extA, "v1", " kinds: [{name: a}]\n interfaceTypes: [{name: t, targetKind: a}]\n")}) + body := coreHead + "metadata: {name: p}\nworkload: {uri: 'https://example.test/p'}\n" + withCondition := body + "extensions: []\nconditions:\n- {kind: a, interface: {type: t}}\n" + if err := Profile([]byte(withCondition), roots); err == nil { + t.Fatal("a condition with no declared extensions was accepted") + } +} diff --git a/internal/validate/doc.go b/internal/validate/doc.go new file mode 100644 index 0000000..b432ab9 --- /dev/null +++ b/internal/validate/doc.go @@ -0,0 +1,9 @@ +// Package validate checks a Runtime Conditions Profile against the extensions it declares. +// +// The validator is the same for every profiler and every language. It reads two kinds of YAML: the +// profile, and the definition of each extension the profile declares. It knows only what the core +// profile schema defines (a condition has a kind and an interface with a type, and may have a name +// and an optional flag). Everything else about a condition, the fields it may hold, their values and +// their shape, comes from the extension definitions, so an extension can give a field any shape and a +// new extension needs no change here. +package validate diff --git a/internal/validate/extension_permutations_test.go b/internal/validate/extension_permutations_test.go new file mode 100644 index 0000000..c6744f0 --- /dev/null +++ b/internal/validate/extension_permutations_test.go @@ -0,0 +1,322 @@ +package validate + +import ( + "fmt" + "math/rand" + "os" + "path/filepath" + "strings" + "testing" +) + +// More ways an extension can shape its fields, and the combinations of them. A new extension, or +// a new shape in an existing one, must never make the validator fail on a profile the extension +// allows, or accept one it does not. gamma adds the shapes alpha and beta do not have; delta +// exists to define the same value twice. + +const dummyGamma = `apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://example.test/dummy/gamma/v3/runtimeconditions.extension.yaml + version: v3 +spec: + kinds: + - name: thing + interfaceTypes: + - {name: web, targetKind: thing} + - {name: db, targetKind: thing} + - {name: queue, targetKind: thing} + interfaceFields: + - {name: groups, targetKind: thing, targetType: web} + - {name: mode, targetKind: thing, targetType: web} + - {name: mode, targetKind: thing, targetType: db} + - {name: matrix, targetKind: thing, targetType: queue} + conditionFields: + - {name: limits, appliesToKinds: [thing]} + fieldValues: + - {field: 'interface.groups[].members[].role', targetKind: thing, targetType: web, values: [admin, user]} + - {field: interface.mode, targetKind: thing, targetType: web, values: [live, test]} + - {field: interface.mode, targetKind: thing, targetType: db, values: [read, write]} + - {field: 'limits.env[].property', targetKind: thing, targetType: web, values: [cpu]} + - {field: 'limits.env[].property', targetKind: thing, targetType: db, values: [memory]} + - {field: 'limits.env[].property', targetKind: thing, targetType: queue, values: [depth]} +` + +// delta allows the value fast for alpha's interface.mode a second time. +const dummyDelta = `apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://example.test/dummy/delta/v1/runtimeconditions.extension.yaml + version: v1 +spec: + dependencies: [https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml] + fieldValues: + - {field: interface.mode, targetKind: widget, targetType: plain, values: [fast, turbo]} +` + +const ( + dummyGammaRef = "https://example.test/dummy/gamma:v3" + dummyDeltaRef = "https://example.test/dummy/delta:v1" +) + +func writeDefinitions(tb testing.TB, root string, definitions ...string) { + tb.Helper() + for index, definition := range definitions { + if err := os.WriteFile(filepath.Join(root, fmt.Sprintf("definition-%d.yaml", index)), []byte(definition), 0o644); err != nil { + tb.Fatal(err) + } + } +} + +func optionsWith(t *testing.T, extra ...string) []string { + t.Helper() + root := t.TempDir() + writeDefinitions(t, root, append([]string{dummyAlpha, dummyBeta, dummyGamma}, extra...)...) + return []string{root} +} + +var allDummies = []string{dummyAlphaRef, dummyBetaRef, dummyGammaRef} + +func TestListsNestedInsideListsAreWalked(t *testing.T) { + options := optionsWith(t) + valid := "kind: thing\ninterface:\n type: web\n groups:\n - members: [{role: admin}, {role: user}]\n - members: [{role: user}]\n - members: []\n - {}\n" + if err := Profile(dummyProfile(allDummies, valid), options); err != nil { + t.Fatalf("nested lists were rejected: %v", err) + } + broken := strings.Replace(valid, "{role: user}]\n - members: [{role: user}]", "{role: root}]\n - members: [{role: user}]", 1) + err := Profile(dummyProfile(allDummies, broken), options) + if err == nil || !strings.Contains(err.Error(), "interface.groups[0].members[1].role root") { + t.Fatalf("a bad value deep in nested lists should be reported where it is, got %v", err) + } +} + +func TestTheSameFieldNameCanAllowDifferentValuesOnDifferentInterfaceTypes(t *testing.T) { + options := optionsWith(t) + accepted := map[string]string{ + "db": "kind: thing\ninterface: {type: db, mode: read}\n", + "web": "kind: thing\ninterface: {type: web, mode: live}\n", + "widget": "kind: widget\ninterface: {type: plain, mode: fast}\n", + } + rejected := map[string]string{ + "db takes db values only": "kind: thing\ninterface: {type: db, mode: live}\n", + "web takes web values only": "kind: thing\ninterface: {type: web, mode: read}\n", + "widget takes widget values": "kind: widget\ninterface: {type: plain, mode: read}\n", + "a value of another kind too": "kind: thing\ninterface: {type: db, mode: fast}\n", + } + for name, condition := range accepted { + if err := Profile(dummyProfile(allDummies, condition), options); err != nil { + t.Errorf("%s: %v", name, err) + } + } + for name, condition := range rejected { + if err := Profile(dummyProfile(allDummies, condition), options); err == nil { + t.Errorf("%s: accepted", name) + } + } +} + +func TestAConditionFieldCanBeDefinedWithTheSameNameForEveryInterfaceType(t *testing.T) { + options := optionsWith(t) + for interfaceType, property := range map[string]string{"web": "cpu", "db": "memory", "queue": "depth"} { + condition := "kind: thing\ninterface: {type: " + interfaceType + "}\nlimits:\n env:\n - {property: " + property + ", name: X}\n" + if err := Profile(dummyProfile(allDummies, condition), options); err != nil { + t.Errorf("%s: %v", interfaceType, err) + } + wrong := strings.Replace(condition, property, "disk", 1) + if err := Profile(dummyProfile(allDummies, wrong), options); err == nil { + t.Errorf("%s: a value outside the type's list was accepted", interfaceType) + } + } +} + +func TestTwoExtensionsDefiningTheSameValueForTheSameFieldIsAConflict(t *testing.T) { + // delta repeats the value fast that alpha already allows for interface.mode. The conflict is in + // the set of extensions, so every profile that uses both is rejected, whatever value it holds. + options := optionsWith(t, dummyDelta) + extensions := append([]string{dummyDeltaRef}, allDummies...) + for _, mode := range []string{"fast", "turbo", "slow"} { + err := Profile(dummyProfile(extensions, "kind: widget\ninterface: {type: plain, mode: "+mode+"}\n"), options) + if err == nil || !strings.Contains(err.Error(), "vocabulary conflict") { + t.Fatalf("mode %s: a value defined twice should be reported as a conflict, got %v", mode, err) + } + } + // without delta the same profile is fine + if err := Profile(dummyProfile(allDummies, "kind: widget\ninterface: {type: plain, mode: fast}\n"), optionsWith(t)); err != nil { + t.Fatalf("alpha on its own was rejected: %v", err) + } +} + +func TestAKindFromAnExtensionTheProfileDoesNotDeclareIsRejected(t *testing.T) { + options := optionsWith(t) + err := Profile(dummyProfile([]string{dummyAlphaRef}, "kind: thing\ninterface: {type: web}\n"), options) + if err == nil || !strings.Contains(err.Error(), "kind thing") { + t.Fatalf("expected the kind to be unknown, got %v", err) + } +} + +func TestDeclaringAnExtensionNoConditionUsesIsFine(t *testing.T) { + options := optionsWith(t) + if err := Profile(dummyProfile(allDummies, "kind: widget\ninterface: {type: plain, mode: fast}\n"), options); err != nil { + t.Fatal(err) + } +} + +func TestAProfileWithNoConditionsAndNoExtensionsIsValid(t *testing.T) { + options := optionsWith(t) + profile := []byte("apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsProfile\nmetadata: {name: empty}\nworkload: {uri: 'https://example.test/e'}\nextensions: []\nconditions: []\n") + if err := Profile(profile, options); err != nil { + t.Fatal(err) + } +} + +func TestExtensionReferencesMayBeWrittenInEveryAcceptedForm(t *testing.T) { + options := optionsWith(t) + for _, ref := range []string{ + "https://example.test/dummy/alpha:v1", + "https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml", + "https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml:v1", + } { + profile := dummyProfile([]string{ref}, "kind: widget\ninterface: {type: plain, mode: fast}\n") + if err := Profile(profile, options); err != nil { + t.Errorf("%s: %v", ref, err) + } + } +} + +func TestMalformedConditionsAreReportedAndNeverPanic(t *testing.T) { + options := optionsWith(t) + for name, condition := range map[string]string{ + "a string": "just text\n", + "a list": "[a, b]\n", + "null": "null\n", + "a number": "7\n", + "no kind": "interface: {type: plain}\n", + "a number for the kind": "kind: 5\ninterface: {type: plain}\n", + "a list for the kind": "kind: [widget]\ninterface: {type: plain}\n", + "no interface": "kind: widget\n", + "a string interface": "kind: widget\ninterface: plain\n", + "a list interface": "kind: widget\ninterface: [plain]\n", + "no interface type": "kind: widget\ninterface: {mode: fast}\n", + "a number interface type": "kind: widget\ninterface: {type: 3}\n", + "a null interface": "kind: widget\ninterface:\n", + "an empty mapping": "{}\n", + } { + t.Run(name, func(t *testing.T) { + if err := Profile(dummyProfile([]string{dummyAlphaRef}, condition), options); err == nil { + t.Fatalf("a malformed condition was accepted:\n%s", condition) + } + }) + } +} + +func TestValuesOfOtherTypesAtAnEnumeratedPathNeverPanic(t *testing.T) { + // listy has no schema, so only the vocabulary looks at it. A value that is not a string is not + // compared with the list. It is for the extension's schema to reject, and listy has none. + options := optionsWith(t) + for name, tags := range map[string]string{ + "numbers": "[1, 2]", "booleans": "[true, false]", "nulls": "[null]", "objects": "[{a: 1}]", + "lists": "[[red]]", "mixed with a bad string": "[1, green]", + } { + t.Run(name, func(t *testing.T) { + err := Profile(dummyProfile([]string{dummyAlphaRef}, "kind: widget\ninterface: {type: listy, tags: "+tags+"}\n"), options) + if strings.Contains(name, "bad string") != (err != nil) { + t.Fatalf("unexpected result for %s: %v", tags, err) + } + }) + } +} + +func TestUnicodeAndEmptyValuesAreCheckedLikeAnyOther(t *testing.T) { + options := optionsWith(t) + for _, value := range []string{"'ß'", "'日本語'", "''", "'red '", "Red"} { + condition := "kind: widget\ninterface: {type: listy, tags: [" + value + "]}\n" + if err := Profile(dummyProfile([]string{dummyAlphaRef}, condition), options); err == nil { + t.Errorf("%s was accepted but is not in the list", value) + } + } +} + +func TestManyConditionsAreEachReportedWithTheirOwnIndex(t *testing.T) { + options := optionsWith(t) + conditions := make([]string, 0, 50) + for index := 0; index < 50; index++ { + mode := "fast" + if index == 37 { + mode = "broken" + } + conditions = append(conditions, "kind: widget\ninterface: {type: plain, mode: "+mode+"}\n") + } + err := Profile(dummyProfile([]string{dummyAlphaRef}, conditions...), options) + if err == nil || !strings.Contains(err.Error(), "conditions[37].interface.mode broken") || strings.Contains(err.Error(), "conditions[36]") { + t.Fatalf("the bad condition should be the only one reported, got %v", err) + } +} + +// shapes lists one value at each place the dummy extensions enumerate values: how to write the +// field in a condition, the values that are allowed, and one that is not. +type shape struct { + kind, interfaceType string + write func(value string) string + good []string + bad string + extensions []string +} + +var shapes = []shape{ + {"widget", "plain", func(v string) string { return "mode: " + v }, []string{"fast", "slow"}, "turbo", []string{dummyAlphaRef}}, + {"widget", "plain", func(v string) string { return "mode: fast\n spec: {format: " + v + "}" }, []string{"yaml", "json"}, "toml", []string{dummyAlphaRef}}, + {"widget", "listy", func(v string) string { return "tags: [red, " + v + "]" }, []string{"red", "blue"}, "green", []string{dummyAlphaRef}}, + {"widget", "listy", func(v string) string { return "items: [{part: a, size: " + v + "}]" }, []string{"small", "large"}, "huge", []string{dummyAlphaRef}}, + {"gadget", "strict", func(v string) string { return "operations: [read, " + v + "]" }, []string{"read", "write"}, "erase", []string{dummyAlphaRef, dummyBetaRef}}, + {"gadget", "objects", func(v string) string { return "operations: [{action: " + v + ", target: anything}]" }, []string{"open", "close"}, "smash", []string{dummyAlphaRef, dummyBetaRef}}, + {"thing", "web", func(v string) string { return "groups: [{members: [{role: " + v + "}]}]" }, []string{"admin", "user"}, "root", allDummies}, + {"thing", "web", func(v string) string { return "mode: " + v }, []string{"live", "test"}, "read", allDummies}, + {"thing", "db", func(v string) string { return "mode: " + v }, []string{"read", "write"}, "live", allDummies}, +} + +// TestRandomCombinationsOfShapesAreValidExactlyWhenEveryValueIsAllowed builds profiles at random +// from the shapes above, with conditions of different extensions side by side, and checks that +// the validator accepts a profile exactly when every value in it is one the extension allows. +func TestRandomCombinationsOfShapesAreValidExactlyWhenEveryValueIsAllowed(t *testing.T) { + options := optionsWith(t) + random := rand.New(rand.NewSource(20261114)) + for round := 0; round < 400; round++ { + count := 1 + random.Intn(6) + conditions := make([]string, 0, count) + wantValid := true + for ; count > 0; count-- { + picked := shapes[random.Intn(len(shapes))] + value := picked.good[random.Intn(len(picked.good))] + if random.Intn(4) == 0 { + value, wantValid = picked.bad, false + } + conditions = append(conditions, "kind: "+picked.kind+"\ninterface:\n type: "+picked.interfaceType+"\n "+picked.write(value)+"\n") + } + err := Profile(dummyProfile(allDummies, conditions...), options) + if wantValid != (err == nil) { + t.Fatalf("round %d: valid=%v but got %v\n%s", round, wantValid, err, strings.Join(conditions, "---\n")) + } + } +} + +// FuzzValidateProfileYAML only checks that no input makes the validator panic. A plain go test runs +// the seeds; go test -fuzz=FuzzValidateProfileYAML explores further. +func FuzzProfile(f *testing.F) { + f.Add("kind: widget\ninterface: {type: plain, mode: fast}\n") + f.Add("kind: gadget\ninterface: {type: strict, operations: [read]}\nconfig: {env: [{property: url, name: U}]}\n") + f.Add("kind: thing\ninterface:\n type: web\n groups: [{members: [{role: admin}]}]\n") + f.Add("- - - 1\n") + f.Add("{kind: {a: b}, interface: [1, [2]]}\n") + root := f.TempDir() + writeDefinitions(f, root, dummyAlpha, dummyBeta, dummyGamma) + options := []string{root} + f.Fuzz(func(t *testing.T, condition string) { + defer func() { + if recovered := recover(); recovered != nil { + t.Fatalf("the validator panicked on %q: %v", condition, recovered) + } + }() + profile := "apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsProfile\nextensions:\n- " + dummyAlphaRef + "\n- " + dummyBetaRef + "\n- " + dummyGammaRef + "\nconditions:\n- " + strings.ReplaceAll(condition, "\n", "\n ") + "\n" + _ = Profile([]byte(profile), options) + }) +} diff --git a/internal/validate/extension_shapes_test.go b/internal/validate/extension_shapes_test.go new file mode 100644 index 0000000..aff2831 --- /dev/null +++ b/internal/validate/extension_shapes_test.go @@ -0,0 +1,256 @@ +package validate + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +// These tests prove how the validator treats an extension: whatever shape a field has, it is +// checked against the extension's own definition. They run against two made-up extensions, so +// they do not depend on any real extension or on which version of it exists. The validator may +// know only what the core profile schema defines. Everything else, every shape below, comes from +// the definitions. +// +// The dummy extensions cover the ways an extension can shape a field: +// - a string with enumerated values (interface.mode), +// - a nested object (interface.spec.format), +// - a list of strings (interface.tags[], interface.operations[]), +// - a list of objects with several keys (interface.items[].part, .size, interface.operations[].action), +// - a key of an object that is free-form (interface.operations[].target), +// - a field of the condition itself (settings, config) with env lists and alternatives, +// - a field with no enumerated values at all (interface.note), +// - a dependency of one extension on another. + +const dummyAlpha = `apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml + version: v1 +spec: + kinds: + - name: widget + interfaceTypes: + - {name: plain, targetKind: widget} + - {name: listy, targetKind: widget} + interfaceFields: + - {name: mode, targetKind: widget, targetType: plain} + - {name: spec, targetKind: widget, targetType: plain} + - {name: note, targetKind: widget, targetType: plain} + - {name: tags, targetKind: widget, targetType: listy} + - {name: items, targetKind: widget, targetType: listy} + conditionFields: + - {name: settings, appliesToKinds: [widget], appliesToInterfaceTypes: [plain, listy]} + fieldValues: + - {field: interface.mode, targetKind: widget, targetType: plain, values: [fast, slow]} + - {field: interface.spec.format, targetKind: widget, targetType: plain, values: [yaml, json]} + - {field: 'interface.tags[]', targetKind: widget, targetType: listy, values: [red, blue]} + - {field: 'interface.items[].part', targetKind: widget, targetType: listy, values: [a, b]} + - {field: 'interface.items[].size', targetKind: widget, targetType: listy, values: [small, large]} + - {field: 'settings.env[].property', targetKind: widget, targetType: plain, values: [host, port]} + - {field: 'settings.alternatives[].env[].property', targetKind: widget, targetType: plain, values: [host, port]} + - {field: 'settings.env[].property', targetKind: widget, targetType: listy, values: [host, port]} + schemas: + - id: widget-plain + appliesToKind: widget + appliesToInterfaceType: plain + description: A plain widget names its mode, and nothing is added to its interface. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + interface: + type: object + required: [type, mode] + properties: + type: {const: plain} + mode: {type: string} + spec: {type: object} + note: {type: string} + additionalProperties: false +` + +const dummyBeta = `apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://example.test/dummy/beta/v2/runtimeconditions.extension.yaml + version: v2 +spec: + dependencies: [https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml] + kinds: + - name: gadget + interfaceTypes: + - {name: strict, targetKind: gadget} + - {name: objects, targetKind: gadget} + interfaceFields: + - {name: operations, targetKind: gadget, targetType: strict} + - {name: operations, targetKind: gadget, targetType: objects} + conditionFields: + - {name: config, appliesToKinds: [gadget]} + fieldValues: + - {field: 'interface.operations[]', targetKind: gadget, targetType: strict, values: [read, write]} + - {field: 'interface.operations[].action', targetKind: gadget, targetType: objects, values: [open, close]} + - {field: 'config.env[].property', targetKind: gadget, targetType: strict, values: [url]} +` + +const ( + dummyAlphaRef = "https://example.test/dummy/alpha:v1" + dummyBetaRef = "https://example.test/dummy/beta:v2" +) + +func writeFiles(t *testing.T, files map[string]string) { + t.Helper() + for path, content := range files { + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } +} + +// dummyOptions returns the directories that hold the dummy definitions. +func dummyOptions(t *testing.T) []string { + t.Helper() + root := t.TempDir() + writeFiles(t, map[string]string{ + filepath.Join(root, "alpha.yaml"): dummyAlpha, + filepath.Join(root, "beta.yaml"): dummyBeta, + }) + return []string{root} +} + +func dummyProfile(extensions []string, conditions ...string) []byte { + var out strings.Builder + out.WriteString("apiVersion: runtimeconditions.io/v1alpha1\nkind: RuntimeConditionsProfile\nmetadata: {name: shapes}\nworkload: {uri: 'https://example.test/shapes'}\nextensions:\n") + for _, extension := range extensions { + out.WriteString("- " + extension + "\n") + } + out.WriteString("conditions:\n") + for _, condition := range conditions { + out.WriteString("- " + strings.ReplaceAll(strings.TrimRight(condition, "\n"), "\n", "\n ") + "\n") + } + return []byte(out.String()) +} + +func TestFieldShapesAreCheckedAgainstTheExtensionDefinition(t *testing.T) { + options := dummyOptions(t) + alpha, both := []string{dummyAlphaRef}, []string{dummyAlphaRef, dummyBetaRef} + cases := []struct { + name string + extensions []string + valid string + old, new string // a value the extension does not allow replaces old with new + rejected string // text the rejection has to carry + }{ + {"a string with enumerated values", alpha, + "kind: widget\ninterface: {type: plain, mode: fast}\n", "fast", "turbo", "interface.mode turbo"}, + {"a nested object", alpha, + "kind: widget\ninterface: {type: plain, mode: fast, spec: {format: yaml}}\n", "yaml", "toml", "interface.spec.format toml"}, + {"a list of strings", alpha, + "kind: widget\ninterface: {type: listy, tags: [red, blue]}\n", "blue", "green", "interface.tags[1] green"}, + {"a list of objects with several keys", alpha, + "kind: widget\ninterface:\n type: listy\n items:\n - {part: a, size: small}\n - {part: b, size: large}\n", "large", "huge", "interface.items[1].size huge"}, + {"a condition field with an env list", alpha, + "kind: widget\ninterface: {type: plain, mode: fast}\nsettings:\n env:\n - {property: host, name: H}\n", "host", "path", "settings.env[0].property path"}, + {"a condition field with alternatives", alpha, + "kind: widget\ninterface: {type: plain, mode: fast}\nsettings:\n alternatives:\n - env: [{property: host, name: H}]\n - env: [{property: port, name: P}]\n", "port", "fax", "settings.alternatives[1].env[0].property fax"}, + {"operations as strings", both, + "kind: gadget\ninterface: {type: strict, operations: [read, write]}\n", "write", "erase", "interface.operations[1] erase"}, + {"operations as objects keyed by something else", both, + "kind: gadget\ninterface:\n type: objects\n operations:\n - {action: open, target: anything-at-all}\n", "open", "smash", "interface.operations[0].action smash"}, + {"a condition field of another extension", both, + "kind: gadget\ninterface: {type: strict, operations: [read]}\nconfig:\n env:\n - {property: url, name: U}\n", "url", "dsn", "config.env[0].property dsn"}, + } + for _, test := range cases { + t.Run(test.name, func(t *testing.T) { + if err := Profile(dummyProfile(test.extensions, test.valid), options); err != nil { + t.Fatalf("a profile the extensions allow was rejected: %v", err) + } + broken := strings.Replace(test.valid, test.old, test.new, 1) + err := Profile(dummyProfile(test.extensions, broken), options) + if err == nil || !strings.Contains(err.Error(), test.rejected) { + t.Fatalf("a value the extension does not allow should be rejected with %q, got %v\n%s", test.rejected, err, broken) + } + }) + } +} + +func TestAFieldWithNoEnumeratedValuesAcceptsAnyValue(t *testing.T) { + // interface.note and interface.operations[].target are declared, but no extension lists their values. + options := dummyOptions(t) + for _, profile := range [][]byte{ + dummyProfile([]string{dummyAlphaRef}, "kind: widget\ninterface: {type: plain, mode: fast, note: whatever}\n"), + dummyProfile([]string{dummyAlphaRef, dummyBetaRef}, "kind: gadget\ninterface: {type: objects, operations: [{action: close, target: x}, {action: close, target: y}]}\n"), + } { + if err := Profile(profile, options); err != nil { + t.Fatalf("a free-form value was rejected: %v", err) + } + } +} + +func TestAFieldHasToBeDeclaredForTheKindAndInterfaceTypeItIsUsedOn(t *testing.T) { + options := dummyOptions(t) + cases := map[string]string{ + // tags is declared for the listy interface, not the plain one. + "an interface field of another interface type": "kind: widget\ninterface: {type: plain, mode: fast, tags: [red]}\n", + // settings is declared for widgets, not gadgets. + "a condition field of another kind": "kind: gadget\ninterface: {type: strict, operations: [read]}\nsettings:\n env:\n - {property: host, name: H}\n", + "an interface type of another kind": "kind: widget\ninterface: {type: strict, operations: [read]}\n", + "a kind no extension defines": "kind: gizmo\ninterface: {type: plain}\n", + } + for name, condition := range cases { + t.Run(name, func(t *testing.T) { + if err := Profile(dummyProfile([]string{dummyAlphaRef, dummyBetaRef}, condition), options); err == nil { + t.Fatalf("a field that is not declared for its use was accepted:\n%s", condition) + } + }) + } +} + +func TestAFieldNoExtensionDeclaresIsLeftToTheExtensionSchemas(t *testing.T) { + options := dummyOptions(t) + // Nothing declares colour, so the vocabulary has no opinion. The plain widget schema forbids it ... + plain := dummyProfile([]string{dummyAlphaRef}, "kind: widget\ninterface: {type: plain, mode: fast, colour: red}\n") + if err := Profile(plain, options); err == nil || !strings.Contains(err.Error(), "widget-plain") { + t.Fatalf("the extension schema should have rejected the unknown field, got %v", err) + } + // ... and the listy widget has no schema, so it is accepted. + listy := dummyProfile([]string{dummyAlphaRef}, "kind: widget\ninterface: {type: listy, tags: [red], colour: red}\n") + if err := Profile(listy, options); err != nil { + t.Fatalf("a field no extension defines should not fail the vocabulary check: %v", err) + } +} + +func TestAValueOfTheWrongTypeIsLeftToTheExtensionSchemas(t *testing.T) { + // The vocabulary compares strings. A mapping where a string belongs is the schema's to reject. + options := dummyOptions(t) + profile := dummyProfile([]string{dummyAlphaRef}, "kind: widget\ninterface: {type: plain, mode: {nested: true}}\n") + err := Profile(profile, options) + if err == nil || !strings.Contains(err.Error(), "widget-plain") { + t.Fatalf("expected the extension schema to reject the value, got %v", err) + } +} + +func TestAProfileHasToNameTheWholeDependencyClosure(t *testing.T) { + options := dummyOptions(t) + err := Profile(dummyProfile([]string{dummyBetaRef}, "kind: gadget\ninterface: {type: strict, operations: [read]}\n"), options) + if err == nil || !strings.Contains(err.Error(), "missing dependency") { + t.Fatalf("a profile that leaves out a dependency should be rejected, got %v", err) + } +} + +func TestSeveralExtensionsWithDifferentShapesCanBeUsedInOneProfile(t *testing.T) { + options := dummyOptions(t) + profile := dummyProfile([]string{dummyAlphaRef, dummyBetaRef}, + "kind: widget\ninterface: {type: plain, mode: slow, spec: {format: json}}\nsettings:\n env:\n - {property: port, name: P}\n", + "kind: widget\ninterface:\n type: listy\n items:\n - {part: a, size: small}\n", + "kind: gadget\ninterface: {type: strict, operations: [read]}\nconfig:\n env:\n - {property: url, name: U}\n", + "kind: gadget\ninterface: {type: objects, operations: [{action: open, target: t}]}\n", + ) + if err := Profile(profile, options); err != nil { + t.Fatalf("a profile that mixes extensions was rejected: %v", err) + } +} diff --git a/internal/validate/main_test.go b/internal/validate/main_test.go new file mode 100644 index 0000000..c4658ba --- /dev/null +++ b/internal/validate/main_test.go @@ -0,0 +1,15 @@ +package validate + +import ( + "os" + "testing" +) + +func TestMain(m *testing.M) { + schema, err := os.ReadFile("testdata/core.schema.yaml") + if err != nil { + panic(err) + } + UseCoreSchema(schema) + os.Exit(m.Run()) +} diff --git a/internal/validate/profile.go b/internal/validate/profile.go new file mode 100644 index 0000000..a0ab674 --- /dev/null +++ b/internal/validate/profile.go @@ -0,0 +1,180 @@ +package validate + +import ( + "errors" + "fmt" + "slices" +) + +// profileDocument holds the profile fields the core specification defines. A condition is not +// modelled: its shape beyond kind and interface.type belongs to the extensions the profile declares. +type profileDocument struct { + Extensions []Reference `yaml:"extensions"` +} + +// The fields the core profile schema defines. Every other field of a condition comes from an extension. +var ( + coreConditionFields = map[string]bool{"name": true, "optional": true, "kind": true, "extension": true, "interface": true} + coreInterfaceFields = map[string]bool{"type": true} +) + +// profileChecker validates a profile against the vocabulary its declared extensions resolve to. +type profileChecker struct { + checker *checker + issues *report +} + +// validate checks the extensions a profile declares, their dependency closure, and each of its +// conditions. The core fields of the profile are checked against the core schema. conditions holds them as decoded YAML and they are never decoded into fixed types, +// because everything in a condition beyond its kind and interface type is defined by the extensions. +func (p *profileChecker) validate(profile profileDocument, conditions []any) { + // A profile entry may be a short : reference or an id without a version. Look + // each one up as the definition it names. + catalog := p.checker.catalog + extensions := make([]Reference, len(profile.Extensions)) + for i, id := range profile.Extensions { + extensions[i] = id + if resolved, err := catalog.lookup(id); err == nil { + extensions[i] = resolved + } else if errors.Is(err, errAmbiguous) { + p.issues.addf("%v", err) + } + } + + declared := map[Reference]bool{} + for _, id := range extensions { + if declared[id] { + p.issues.addf("duplicate extension id %s", id) + continue + } + declared[id] = true + if catalog.nodes[id] == nil { + p.issues.addf("missing extension definition for %s", id) + continue + } + p.checker.validateNode(id) + } + + // A profile must name every extension it depends on, not just those it uses directly, so that + // its vocabulary can be rebuilt from the list alone. + closure := p.closure(extensions) + for id := range closure { + if !declared[id] { + p.issues.addf("extensions missing dependency %s", id) + } + } + + resolved := p.vocabulary(closure) + p.checker.checkResolvedConflicts("profile", resolved) + for index, condition := range conditions { + p.validateCondition(index, resolved, condition) + } +} + +func (p *profileChecker) closure(ids []Reference) map[Reference]bool { + seen := map[Reference]bool{} + var visit func(Reference) + visit = func(id Reference) { + if seen[id] { + return + } + seen[id] = true + found := p.checker.catalog.nodes[id] + if found == nil { + return + } + for _, dependency := range found.def.Spec.Dependencies { + if resolved, err := p.checker.catalog.lookup(dependency); err == nil { + dependency = resolved + } + visit(dependency) + } + } + for _, id := range ids { + visit(id) + } + return seen +} + +func (p *profileChecker) vocabulary(ids map[Reference]bool) vocabulary { + var nodes []*node + for id := range ids { + if found := p.checker.catalog.nodes[id]; found != nil { + nodes = append(nodes, found) + } + } + slices.SortFunc(nodes, func(left, right *node) int { return left.id.compare(right.id) }) + return vocabulary{nodes: nodes} +} + +// validateCondition checks one condition, held as decoded YAML, against the vocabulary and schemas +// of the extensions the profile declares. It knows only what the core schema defines. +func (p *profileChecker) validateCondition(index int, resolved vocabulary, raw any) { + prefix := fmt.Sprintf("conditions[%d]", index) + condition, ok := raw.(map[string]any) + if !ok { + p.issues.addf("%s must be a mapping", prefix) + return + } + kind, _ := condition["kind"].(string) + interfaceFields, _ := condition["interface"].(map[string]any) + interfaceType, _ := interfaceFields["type"].(string) + p.issues.expectExactlyOne("", resolved.kindCount(kind), "%s.kind %s", prefix, kind) + p.issues.expectExactlyOne("", resolved.interfaceTypeCount(kind, interfaceType), "%s.interface.type %s/%s", prefix, kind, interfaceType) + + // Every field of a condition beyond the core ones belongs to an extension, so it has to be + // defined for this kind and interface type by one of the profile's extensions. That also catches + // a field used without declaring the extension that defines it. + for _, name := range sortedKeys(condition) { + if !coreConditionFields[name] { + p.issues.expectExactlyOne("", resolved.conditionFieldCount(kind, interfaceType, name), "%s.%s for %s/%s", prefix, name, kind, interfaceType) + } + } + // An interface field that some extension defines has to be defined for this kind and interface + // type. An interface field no extension defines is left to the extension schemas, since an + // extension may allow extra properties there. + for _, name := range sortedKeys(interfaceFields) { + if !coreInterfaceFields[name] && resolved.interfaceFieldDeclared(name) { + p.issues.expectExactlyOne("", resolved.interfaceFieldCount(kind, interfaceType, name), "%s.interface.%s for %s/%s", prefix, name, kind, interfaceType) + } + } + + // Where extensions enumerate the values of a field path, every string the condition holds there + // has to be one of them. A value that is not a string is for the extension's schema to judge. + for _, field := range resolved.fieldValueFields(kind, interfaceType) { + for _, found := range valuesAt(condition, field) { + if value, isString := found.value.(string); isString { + p.issues.expectExactlyOne("", resolved.fieldValueCount(field, kind, interfaceType, value), "%s.%s %s for %s/%s", prefix, found.path, value, kind, interfaceType) + } + } + } + p.validateSchemas(prefix, resolved, kind, interfaceType, raw) +} + +// validateSchemas applies every extension schema whose scope matches the condition. A schema with +// no declared scope applies to all conditions. +func (p *profileChecker) validateSchemas(prefix string, resolved vocabulary, kind, interfaceType string, raw any) { + for _, n := range resolved.nodes { + for _, item := range n.def.Spec.Schemas { + if item.AppliesToKind != "" && item.AppliesToKind != kind { + continue + } + if item.AppliesToInterfaceType != "" && item.AppliesToInterfaceType != interfaceType { + continue + } + schema, err := compileSchema(item.Schema) + if err != nil { + p.issues.addf("%s schema %s could not be compiled: %v", prefix, item.ID, err) + continue + } + instance, err := jsonValue(raw) + if err != nil { + p.issues.addf("%s could not be converted for schema validation: %v", prefix, err) + continue + } + if err := schema.Validate(instance); err != nil { + p.issues.addf("%s does not satisfy extension schema %s: %v", prefix, item.ID, err) + } + } + } +} diff --git a/internal/validate/reference.go b/internal/validate/reference.go new file mode 100644 index 0000000..af8bb78 --- /dev/null +++ b/internal/validate/reference.go @@ -0,0 +1,71 @@ +package validate + +import ( + "cmp" + "fmt" + "strings" + + "go.yaml.in/yaml/v3" +) + +// DefinitionFile is the conventional file name of an extension definition. +const DefinitionFile = "runtimeconditions.extension.yaml" + +// Reference identifies an extension release. A definition and a dependency write it as an id and a +// version object. A profile also writes it as a string, either the id alone, or : +// where the short URL is the id without its trailing //runtimeconditions.extension.yaml. +type Reference struct { + ID string `yaml:"id"` + Version string `yaml:"version"` +} + +func (r Reference) valid() bool { return r.ID != "" } +func (r Reference) String() string { return r.ID + "@" + r.Version } + +func (r Reference) compare(other Reference) int { + if order := cmp.Compare(r.ID, other.ID); order != 0 { + return order + } + return cmp.Compare(r.Version, other.Version) +} + +// UnmarshalYAML reads the object form and the string forms. +func (r *Reference) UnmarshalYAML(node *yaml.Node) error { + if node.Kind == yaml.MappingNode { + var fields map[string]any + if err := node.Decode(&fields); err != nil { + return err + } + id, idOK := fields["id"].(string) + version, versionOK := fields["version"].(string) + if len(fields) != 2 || !idOK || id == "" || !versionOK || version == "" { + return fmt.Errorf("extension reference must contain non-empty string id and version") + } + r.ID, r.Version = id, version + return nil + } + if node.Kind != yaml.ScalarNode || node.Tag != "!!str" || node.Value == "" { + return fmt.Errorf("extension reference must be an id/version object or a non-empty string") + } + value := node.Value + separator := strings.LastIndex(value, ":") + schemeEnd := strings.Index(value, "://") + if separator > 0 && separator > schemeEnd+2 && separator > strings.LastIndex(value, "/") { + if separator == len(value)-1 { + return fmt.Errorf("extension reference version suffix must be non-empty") + } + r.ID, r.Version = value[:separator], value[separator+1:] + } else { + r.ID, r.Version = value, "" + } + return nil +} + +// expandShort turns a short : reference back into the full id of a definition. A +// reference that already names a definition, or has no version, is returned unchanged. +func expandShort(r Reference) Reference { + if r.Version == "" || !strings.HasPrefix(r.ID, "https://") || strings.HasSuffix(r.ID, "/"+DefinitionFile) { + return r + } + return Reference{ID: r.ID + "/" + r.Version + "/" + DefinitionFile, Version: r.Version} +} diff --git a/internal/validate/report.go b/internal/validate/report.go new file mode 100644 index 0000000..185b7ee --- /dev/null +++ b/internal/validate/report.go @@ -0,0 +1,52 @@ +package validate + +import ( + "fmt" + "strings" +) + +// report accumulates the messages of one validation. A message about a file carries its path. +type report struct{ messages []string } + +func (r *report) addf(format string, args ...any) { + r.messages = append(r.messages, fmt.Sprintf(format, args...)) +} + +// about records a message about a file or an extension. +func (r *report) about(path string, format string, args ...any) { + message := fmt.Sprintf(format, args...) + if path != "" { + message = path + ": " + message + } + r.messages = append(r.messages, message) +} + +// expectExactlyOne records a message unless exactly one definition was found. +func (r *report) expectExactlyOne(path string, count int, format string, args ...any) { + if count != 1 { + r.about(path, format+": expected exactly one definition, got %d", append(args, count)...) + } +} + +func (r *report) err() error { + if len(r.messages) == 0 { + return nil + } + return Error(r.messages) +} + +// Error is the list of problems found in a profile. +type Error []string + +func (e Error) Error() string { + if len(e) == 1 { + return e[0] + } + var builder strings.Builder + builder.WriteString("profile validation failed:") + for _, message := range e { + builder.WriteString("\n- ") + builder.WriteString(message) + } + return builder.String() +} diff --git a/internal/validate/schema.go b/internal/validate/schema.go new file mode 100644 index 0000000..c839f38 --- /dev/null +++ b/internal/validate/schema.go @@ -0,0 +1,32 @@ +package validate + +import ( + "bytes" + "encoding/json" + + "github.com/santhosh-tekuri/jsonschema/v6" +) + +// compileSchema compiles the JSON Schema an extension declares inline. +func compileSchema(value any) (*jsonschema.Schema, error) { + parsed, err := jsonValue(value) + if err != nil { + return nil, err + } + compiler := jsonschema.NewCompiler() + // An absolute identifier, so that messages do not carry the directory the command ran in. + const location = "urn:runtimeconditions:extension-schema" + if err := compiler.AddResource(location, parsed); err != nil { + return nil, err + } + return compiler.Compile(location) +} + +// jsonValue converts a YAML-decoded value into the JSON representation the schema library expects. +func jsonValue(value any) (any, error) { + data, err := json.Marshal(value) + if err != nil { + return nil, err + } + return jsonschema.UnmarshalJSON(bytes.NewReader(data)) +} diff --git a/internal/validate/testdata/core.schema.yaml b/internal/validate/testdata/core.schema.yaml new file mode 100644 index 0000000..14f5050 --- /dev/null +++ b/internal/validate/testdata/core.schema.yaml @@ -0,0 +1,55 @@ +# A made-up core profile schema with the same structure as the real one, so that the tests do not +# depend on which version of the core schema exists. The real schema is embedded at build time. +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://example.test/schemas/core-profile.schema.yaml +x-runtimeconditions-version: dummy +type: object +additionalProperties: false +required: [apiVersion, kind, metadata, workload, extensions, conditions] +properties: + apiVersion: {const: runtimeconditions.io/v1alpha1} + kind: {const: RuntimeConditionsProfile} + metadata: + type: object + additionalProperties: false + required: [name] + properties: + name: {type: string, minLength: 1} + labels: {type: object, additionalProperties: {type: string}} + workload: + type: object + additionalProperties: false + required: [uri] + properties: + uri: {type: string, minLength: 1} + version: {type: string, minLength: 1} + extensions: + type: array + uniqueItems: true + items: {type: string, minLength: 1} + conditions: + type: array + items: + type: object + required: [kind, interface] + properties: + name: {type: string, minLength: 1} + optional: {type: boolean} + kind: {type: string, minLength: 1} + extension: {type: string, minLength: 1} + interface: + type: object + required: [type] + properties: + type: {type: string, minLength: 1} + additionalProperties: true + additionalProperties: true +# An empty conditions list is valid, with or without extensions. Only a profile that has conditions +# has to declare the extensions they use. +allOf: +- if: + properties: {conditions: {type: array, minItems: 1}} + required: [conditions] + then: + properties: {extensions: {minItems: 1}} + required: [extensions] diff --git a/internal/validate/validate.go b/internal/validate/validate.go new file mode 100644 index 0000000..6d13e44 --- /dev/null +++ b/internal/validate/validate.go @@ -0,0 +1,56 @@ +package validate + +import ( + "go.yaml.in/yaml/v3" +) + +// Profile validates a profile against the core profile schema and against the extension definitions +// found beneath catalogRoots. The profile is checked as data against what the extensions it +// declares define, so the result does not depend on which language or tool produced it. A nil error +// means the profile is valid. +func Profile(data []byte, catalogRoots []string) error { + var profile profileDocument + if err := yaml.Unmarshal(data, &profile); err != nil { + return err + } + // Conditions are decoded as free-form values and never into fixed types: what a condition may + // hold beyond its kind and interface type is defined by the extensions the profile declares, and + // their schemas validate the document as written. + var raw struct { + Conditions []any `yaml:"conditions"` + } + if err := yaml.Unmarshal(data, &raw); err != nil { + return err + } + + // The core profile schema covers what the core specification defines: the fields of the profile + // itself, the shape of the extension list, and that a condition has a kind and an interface type. + core, err := loadCoreSchema() + if err != nil { + return err + } + var document any + if err := yaml.Unmarshal(data, &document); err != nil { + return err + } + instance, err := jsonValue(document) + if err != nil { + return err + } + coreIssues := &report{} + if err := core.Validate(instance); err != nil { + coreIssues.addf("the profile does not satisfy the core profile schema: %v", err) + } + + issues := &report{} + loaded, err := loadCatalog(catalogRoots, issues) + if err != nil { + return err + } + // Problems found while reading the definitions come first, then the profile's own. + definitionIssues := issues.messages + issues = &report{} + (&profileChecker{checker: newChecker(loaded, issues), issues: issues}).validate(profile, raw.Conditions) + issues.messages = append(append(coreIssues.messages, definitionIssues...), issues.messages...) + return issues.err() +} diff --git a/internal/validate/valuepath.go b/internal/validate/valuepath.go new file mode 100644 index 0000000..a4a07c1 --- /dev/null +++ b/internal/validate/valuepath.go @@ -0,0 +1,61 @@ +package validate + +import ( + "fmt" + "slices" + "strings" +) + +type foundValue struct { + path string + value any +} + +func sortedKeys(values map[string]any) []string { + keys := make([]string, 0, len(values)) + for key := range values { + keys = append(keys, key) + } + slices.Sort(keys) + return keys +} + +// valuesAt returns every value a condition holds at a field path such as interface.engine, +// interface.operations[].method or configuration.alternatives[].env[].property. A segment that ends +// in [] walks the elements of a list. Each value comes back with the path that reaches it, list +// indexes included, so a message can point at the element. +func valuesAt(root any, path string) []foundValue { + found := []foundValue{{path: "", value: root}} + for _, segment := range strings.Split(path, ".") { + name, list := strings.CutSuffix(segment, "[]") + var next []foundValue + for _, current := range found { + object, ok := current.value.(map[string]any) + if !ok { + continue + } + value, present := object[name] + if !present { + continue + } + here := current.path + if here != "" { + here += "." + } + here += name + if !list { + next = append(next, foundValue{path: here, value: value}) + continue + } + items, ok := value.([]any) + if !ok { + continue + } + for index, item := range items { + next = append(next, foundValue{path: fmt.Sprintf("%s[%d]", here, index), value: item}) + } + } + found = next + } + return found +} diff --git a/internal/validate/valuepath_test.go b/internal/validate/valuepath_test.go new file mode 100644 index 0000000..4fd585c --- /dev/null +++ b/internal/validate/valuepath_test.go @@ -0,0 +1,84 @@ +package validate + +import ( + "reflect" + "testing" +) + +func pathsOf(found []foundValue) []string { + paths := []string{} + for _, item := range found { + paths = append(paths, item.path) + } + return paths +} + +func TestValuesAtWalksEveryShapeAPathCanTake(t *testing.T) { + condition := map[string]any{ + "kind": "x", + "interface": map[string]any{ + "type": "t", + "engine": "postgres", + "spec": map[string]any{"format": "yaml"}, + "tags": []any{"red", "blue"}, + "items": []any{map[string]any{"part": "a"}, map[string]any{"part": "b"}, map[string]any{"other": 1}}, + "groups": []any{ + map[string]any{"members": []any{map[string]any{"role": "admin"}, map[string]any{"role": "user"}}}, + map[string]any{"members": []any{map[string]any{"role": "user"}}}, + map[string]any{"members": []any{}}, + map[string]any{}, + }, + "empty": []any{}, + "null": nil, + }, + "settings": map[string]any{"alternatives": []any{ + map[string]any{"env": []any{map[string]any{"property": "host"}}}, + map[string]any{"env": []any{map[string]any{"property": "port"}, map[string]any{"property": "url"}}}, + }}, + } + cases := map[string][]string{ + "kind": {"kind"}, + "interface.engine": {"interface.engine"}, + "interface.spec.format": {"interface.spec.format"}, + "interface.tags[]": {"interface.tags[0]", "interface.tags[1]"}, + "interface.items[].part": {"interface.items[0].part", "interface.items[1].part"}, + "interface.groups[].members[].role": {"interface.groups[0].members[0].role", "interface.groups[0].members[1].role", "interface.groups[1].members[0].role"}, + "settings.alternatives[].env[].property": {"settings.alternatives[0].env[0].property", "settings.alternatives[1].env[0].property", "settings.alternatives[1].env[1].property"}, + "interface.empty[]": {}, + "interface.null[]": {}, + "interface.missing": {}, + "interface.engine.deeper": {}, + "interface.engine[]": {}, + "interface.tags": {"interface.tags"}, + "interface.spec[]": {}, + "nothing.at.all": {}, + "interface.items[].part.deeper": {}, + "interface.groups[].members[].role.nested": {}, + } + for path, want := range cases { + if got := pathsOf(valuesAt(condition, path)); !reflect.DeepEqual(got, want) { + t.Errorf("%s: got %v, want %v", path, got, want) + } + } +} + +func TestValuesAtNeverPanicsOnAnythingYamlCanDecodeTo(t *testing.T) { + roots := []any{nil, "text", 3, 2.5, true, []any{}, []any{nil, "x", 1}, map[string]any{}, map[string]any{"a": nil}, + map[string]any{"a": []any{[]any{"nested list"}}}, map[string]any{"a": map[string]any{"b": []any{nil}}}} + paths := []string{"a", "a[]", "a.b", "a[].b", "a.b[]", "a[].b[]", "", ".", "[]", "a..b", "a.[]"} + for _, root := range roots { + for _, path := range paths { + valuesAt(root, path) + } + } +} + +func TestSortedKeysIsStable(t *testing.T) { + got := sortedKeys(map[string]any{"b": 1, "a": 2, "c": 3}) + if !reflect.DeepEqual(got, []string{"a", "b", "c"}) { + t.Fatalf("got %v", got) + } + if got := sortedKeys(nil); len(got) != 0 { + t.Fatalf("a nil map should have no keys, got %v", got) + } +} diff --git a/internal/validate/vocabulary.go b/internal/validate/vocabulary.go new file mode 100644 index 0000000..45b8be1 --- /dev/null +++ b/internal/validate/vocabulary.go @@ -0,0 +1,175 @@ +package validate + +import ( + "fmt" + "slices" +) + +// vocabulary is what the extensions of a resolved set define between them. A lookup counts matches +// rather than returning them, because a resolved set must define each name exactly once. +type vocabulary struct{ nodes []*node } + +func (v vocabulary) kindCount(name string) int { + count := 0 + for _, n := range v.nodes { + for _, item := range n.def.Spec.Kinds { + if item.Name == name { + count++ + } + } + } + return count +} + +func (v vocabulary) interfaceTypeCount(kind, name string) int { + count := 0 + for _, n := range v.nodes { + for _, item := range n.def.Spec.InterfaceTypes { + if item.TargetKind == kind && item.Name == name { + count++ + } + } + } + return count +} + +// interfaceFieldCount counts the extensions that declare the named interface field for a kind and interface type. +func (v vocabulary) interfaceFieldCount(kind, interfaceType, name string) int { + count := 0 + for _, n := range v.nodes { + for _, item := range n.def.Spec.InterfaceFields { + if item.TargetKind == kind && item.TargetType == interfaceType && item.Name == name { + count++ + } + } + } + return count +} + +// conditionFieldCount counts the extensions that declare the named condition field for a kind and interface type. +func (v vocabulary) conditionFieldCount(kind, interfaceType, name string) int { + count := 0 + for _, n := range v.nodes { + for _, item := range n.def.Spec.ConditionFields { + if item.Name == name && conditionFieldApplies(item, kind, interfaceType) { + count++ + } + } + } + return count +} + +// fieldValueCount counts the extensions that allow value for the field path on a kind and interface type. +func (v vocabulary) fieldValueCount(field, kind, interfaceType, value string) int { + count := 0 + for _, n := range v.nodes { + for _, item := range n.def.Spec.FieldValues { + if item.Field == field && item.TargetKind == kind && item.TargetType == interfaceType && slices.Contains(item.Values, value) { + count++ + } + } + } + return count +} + +// interfaceFieldDeclared reports whether any extension declares the named interface field for any kind and type. +func (v vocabulary) interfaceFieldDeclared(name string) bool { + for _, n := range v.nodes { + for _, item := range n.def.Spec.InterfaceFields { + if item.Name == name { + return true + } + } + } + return false +} + +// fieldValueFields returns the field paths whose values the extensions enumerate on a kind and interface type. +func (v vocabulary) fieldValueFields(kind, interfaceType string) []string { + var fields []string + for _, n := range v.nodes { + for _, item := range n.def.Spec.FieldValues { + if item.TargetKind == kind && item.TargetType == interfaceType && !slices.Contains(fields, item.Field) { + fields = append(fields, item.Field) + } + } + } + slices.Sort(fields) + return fields +} + +// counts returns how often each vocabulary name is declared across the set. Above one is a conflict. +func (v vocabulary) counts() map[string]int { + counts := map[string]int{} + for _, n := range v.nodes { + for _, item := range n.def.Spec.Kinds { + counts["kind:"+item.Name]++ + } + for _, item := range n.def.Spec.InterfaceTypes { + counts["interfaceType:"+item.TargetKind+":"+item.Name]++ + } + for _, item := range n.def.Spec.InterfaceFields { + counts["interfaceField:"+item.TargetKind+":"+item.TargetType+":"+item.Name]++ + } + for _, item := range n.def.Spec.FieldValues { + counts["fieldValues:"+item.TargetKind+":"+item.TargetType+":"+item.Field]++ + } + } + return counts +} + +// conditionFieldConflicts returns the condition fields that two extensions define over overlapping +// scopes. They cannot be counted by name alone: two definitions collide only when the kinds and +// interface types they apply to intersect. +func (v vocabulary) conditionFieldConflicts() []string { + type definition struct { + n *node + field ConditionField + } + var definitions []definition + for _, n := range v.nodes { + for _, field := range n.def.Spec.ConditionFields { + definitions = append(definitions, definition{n, field}) + } + } + var conflicts []string + for i := range definitions { + for j := i + 1; j < len(definitions); j++ { + left, right := definitions[i], definitions[j] + if left.field.Name == right.field.Name && conditionFieldScopesOverlap(left.field, right.field) { + conflicts = append(conflicts, fmt.Sprintf("conditionField:%s between %s and %s", left.field.Name, left.n.id, right.n.id)) + } + } + } + return conflicts +} + +func conditionFieldScopesOverlap(left, right ConditionField) bool { + for _, kind := range left.AppliesToKinds { + if slices.Contains(right.AppliesToKinds, kind) { + return setsOverlapOrEitherEmpty(left.AppliesToInterfaceTypes, right.AppliesToInterfaceTypes) + } + } + return false +} + +// setsOverlapOrEitherEmpty treats an empty set as unrestricted, so a field scoped to every +// interface type overlaps one scoped to a specific type. +func setsOverlapOrEitherEmpty(left, right []string) bool { + if len(left) == 0 || len(right) == 0 { + return true + } + for _, item := range left { + if slices.Contains(right, item) { + return true + } + } + return false +} + +func conditionFieldApplies(field ConditionField, kind, interfaceType string) bool { + if !slices.Contains(field.AppliesToKinds, kind) { + return false + } + return len(field.AppliesToInterfaceTypes) == 0 || slices.Contains(field.AppliesToInterfaceTypes, interfaceType) +} diff --git a/scripts/build.go b/scripts/build.go index c17ee25..7bc5b26 100644 --- a/scripts/build.go +++ b/scripts/build.go @@ -71,9 +71,10 @@ func build() error { if err := os.MkdirAll(filepath.Dir(*output), 0755); err != nil { return err } + encoded := base64.StdEncoding.EncodeToString(schema) linkerFlags := "-X main.version=" + *version + " -X main.commit=" + *commit + - " -X github.com/runtimeconditions/go-rc-profiler/extensioncheck.installedCoreSchemaBase64=" + - base64.StdEncoding.EncodeToString(schema) + " -X github.com/runtimeconditions/go-rc-profiler/extensioncheck.installedCoreSchemaBase64=" + encoded + + " -X github.com/runtimeconditions/rc-cli/internal/validate.coreSchemaBase64=" + encoded command := exec.Command("go", "build", "-trimpath", "-ldflags", linkerFlags, "-o", *output, "./cmd/rc") command.Stdin, command.Stdout, command.Stderr = os.Stdin, os.Stdout, os.Stderr return command.Run() diff --git a/scripts/ci-smoke.go b/scripts/ci-smoke.go index 5e8795f..24bb0c6 100644 --- a/scripts/ci-smoke.go +++ b/scripts/ci-smoke.go @@ -168,6 +168,29 @@ func smoke(o options) error { } } } + // The profile just generated has to pass rc's own validator too, which checks it against the core + // schema embedded in this build and against the definitions of the extensions it declares. + validated, err := rc(0, "profile", "validate", output) + if err != nil { + return err + } + if !strings.Contains(validated.stderr, "profile validated") { + return fmt.Errorf("the generated profile was not validated: %+v", validated) + } + withoutMetadata := filepath.Join(workload, "profile-without-metadata.yaml") + if err := os.WriteFile(withoutMetadata, []byte(strings.Replace(expected, "metadata:\n name: ci-fixture\n", "", 1)), 0644); err != nil { + return err + } + rejected, err := rc(1, "profile", "validate", withoutMetadata) + if err != nil { + return err + } + if !strings.Contains(rejected.stderr, "core profile schema") || !strings.Contains(rejected.stderr, "metadata") { + return fmt.Errorf("a profile without metadata must fail the core schema: %+v", rejected) + } + if err := os.Remove(withoutMetadata); err != nil { + return err + } source, err := os.ReadFile(filepath.Join(workload, "main.go")) if err != nil { return err diff --git a/testdata/profile-validate/extensions/dummy/alpha/v1/runtimeconditions.extension.yaml b/testdata/profile-validate/extensions/dummy/alpha/v1/runtimeconditions.extension.yaml new file mode 100644 index 0000000..3867b34 --- /dev/null +++ b/testdata/profile-validate/extensions/dummy/alpha/v1/runtimeconditions.extension.yaml @@ -0,0 +1,46 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml + version: v1 +spec: + kinds: + - name: widget + interfaceTypes: + - {name: plain, targetKind: widget} + - {name: listy, targetKind: widget} + interfaceFields: + - {name: mode, targetKind: widget, targetType: plain} + - {name: spec, targetKind: widget, targetType: plain} + - {name: note, targetKind: widget, targetType: plain} + - {name: tags, targetKind: widget, targetType: listy} + - {name: items, targetKind: widget, targetType: listy} + conditionFields: + - {name: settings, appliesToKinds: [widget], appliesToInterfaceTypes: [plain, listy]} + fieldValues: + - {field: interface.mode, targetKind: widget, targetType: plain, values: [fast, slow]} + - {field: interface.spec.format, targetKind: widget, targetType: plain, values: [yaml, json]} + - {field: 'interface.tags[]', targetKind: widget, targetType: listy, values: [red, blue]} + - {field: 'interface.items[].part', targetKind: widget, targetType: listy, values: [a, b]} + - {field: 'interface.items[].size', targetKind: widget, targetType: listy, values: [small, large]} + - {field: 'settings.env[].property', targetKind: widget, targetType: plain, values: [host, port]} + - {field: 'settings.alternatives[].env[].property', targetKind: widget, targetType: plain, values: [host, port]} + - {field: 'settings.env[].property', targetKind: widget, targetType: listy, values: [host, port]} + schemas: + - id: widget-plain + appliesToKind: widget + appliesToInterfaceType: plain + description: A plain widget names its mode, and nothing is added to its interface. + schema: + $schema: https://json-schema.org/draft/2020-12/schema + type: object + properties: + interface: + type: object + required: [type, mode] + properties: + type: {const: plain} + mode: {type: string} + spec: {type: object} + note: {type: string} + additionalProperties: false diff --git a/testdata/profile-validate/extensions/dummy/beta/v2/runtimeconditions.extension.yaml b/testdata/profile-validate/extensions/dummy/beta/v2/runtimeconditions.extension.yaml new file mode 100644 index 0000000..e832981 --- /dev/null +++ b/testdata/profile-validate/extensions/dummy/beta/v2/runtimeconditions.extension.yaml @@ -0,0 +1,21 @@ +apiVersion: runtimeconditions.io/v1alpha1 +kind: RuntimeConditionsExtensionDefinition +metadata: + id: https://example.test/dummy/beta/v2/runtimeconditions.extension.yaml + version: v2 +spec: + dependencies: [https://example.test/dummy/alpha/v1/runtimeconditions.extension.yaml] + kinds: + - name: gadget + interfaceTypes: + - {name: strict, targetKind: gadget} + - {name: objects, targetKind: gadget} + interfaceFields: + - {name: operations, targetKind: gadget, targetType: strict} + - {name: operations, targetKind: gadget, targetType: objects} + conditionFields: + - {name: config, appliesToKinds: [gadget]} + fieldValues: + - {field: 'interface.operations[]', targetKind: gadget, targetType: strict, values: [read, write]} + - {field: 'interface.operations[].action', targetKind: gadget, targetType: objects, values: [open, close]} + - {field: 'config.env[].property', targetKind: gadget, targetType: strict, values: [url]} diff --git a/testdata/profile-validate/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml b/testdata/profile-validate/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml deleted file mode 100644 index b6ff0c3..0000000 --- a/testdata/profile-validate/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml +++ /dev/null @@ -1,159 +0,0 @@ -apiVersion: runtimeconditions.io/v1alpha1 -kind: RuntimeConditionsExtensionDefinition -metadata: - id: https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml - version: v1alpha2 -spec: - kinds: - - {name: api} - - {name: datastore} - - {name: cache} - interfaceTypes: - - {name: http, targetKind: api} - - {name: relational, targetKind: datastore} - - {name: document, targetKind: datastore} - - {name: key_value, targetKind: cache} - - {name: smtp, targetKind: api} - interfaceFields: - - {name: spec, targetKind: api, targetType: http} - - {name: operations, targetKind: api, targetType: http} - - {name: engine, targetKind: datastore, targetType: relational} - - {name: engine, targetKind: datastore, targetType: document} - - {name: engine, targetKind: cache, targetType: key_value} - - {name: operations, targetKind: api, targetType: smtp} - fieldValues: - - {field: interface.spec.format, targetKind: api, targetType: http, values: [openapi]} - - field: interface.operations[].method - targetKind: api - targetType: http - values: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE] - - field: interface.engine - targetKind: datastore - targetType: relational - values: [postgres, mysql, mariadb, sqlserver, oracle, sqlite] - - field: interface.engine - targetKind: datastore - targetType: document - values: [mongodb, couchbase] - - field: interface.engine - targetKind: cache - targetType: key_value - values: [redis, memcached] - - {field: 'interface.operations[]', targetKind: api, targetType: smtp, values: [send]} - schemas: - - id: api-http-interface - appliesToKind: api - appliesToInterfaceType: http - description: Validates HTTP API integration conditions. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - required: [kind, interface] - properties: - kind: {const: api} - interface: - type: object - required: [type] - properties: - type: {const: http} - spec: - type: object - required: [format, uri] - properties: - format: {const: openapi} - uri: {type: string, minLength: 1} - version: - type: string - pattern: ^(?:=?[0-9]+\.[0-9]+\.[0-9]+|[<>]=?[0-9]+\.[0-9]+\.[0-9]+|\^[0-9]+\.[0-9]+\.[0-9]+|~[0-9]+\.[0-9]+\.[0-9]+)$ - additionalProperties: false - operations: - type: array - minItems: 1 - items: - type: object - required: [method, path] - properties: - method: {enum: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE]} - path: {type: string, minLength: 1} - requestBodySchema: {$ref: '#/$defs/simpleSchema'} - responseSchema: {$ref: '#/$defs/simpleSchema'} - additionalProperties: false - anyOf: - - {required: [spec]} - - {required: [operations]} - additionalProperties: true - additionalProperties: true - $defs: - simpleSchema: - oneOf: - - {type: string, enum: [string, number, integer, boolean, 'null']} - - {type: object, additionalProperties: {$ref: '#/$defs/simpleSchema'}} - - {type: array, minItems: 1, maxItems: 1, items: {$ref: '#/$defs/simpleSchema'}} - - id: datastore-relational-interface - appliesToKind: datastore - appliesToInterfaceType: relational - description: Validates relational datastore integration conditions. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - required: [kind, interface] - properties: - kind: {const: datastore} - interface: - type: object - required: [type] - properties: - type: {const: relational} - engine: {enum: [postgres, mysql, mariadb, sqlserver, oracle, sqlite]} - additionalProperties: true - additionalProperties: true - - id: datastore-document-interface - appliesToKind: datastore - appliesToInterfaceType: document - description: Validates document datastore integration conditions. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - required: [kind, interface] - properties: - kind: {const: datastore} - interface: - type: object - required: [type] - properties: {type: {const: document}, engine: {enum: [mongodb, couchbase]}} - additionalProperties: true - additionalProperties: true - - id: cache-key-value-interface - appliesToKind: cache - appliesToInterfaceType: key_value - description: Validates key/value cache integration conditions. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - required: [kind, interface] - properties: - kind: {const: cache} - interface: - type: object - required: [type] - properties: {type: {const: key_value}, engine: {enum: [redis, memcached]}} - additionalProperties: true - additionalProperties: true - - id: api-smtp-interface - appliesToKind: api - appliesToInterfaceType: smtp - description: Validates SMTP email submission requirements. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - required: [kind, interface] - properties: - kind: {const: api} - interface: - type: object - required: [type, operations] - properties: - type: {const: smtp} - operations: {type: array, minItems: 1, uniqueItems: true, items: {enum: [send]}} - additionalProperties: true - additionalProperties: true diff --git a/testdata/profile-validate/extensions/rc/env-configuration/v1alpha2/runtimeconditions.extension.yaml b/testdata/profile-validate/extensions/rc/env-configuration/v1alpha2/runtimeconditions.extension.yaml deleted file mode 100644 index 7046084..0000000 --- a/testdata/profile-validate/extensions/rc/env-configuration/v1alpha2/runtimeconditions.extension.yaml +++ /dev/null @@ -1,184 +0,0 @@ -apiVersion: runtimeconditions.io/v1alpha1 -kind: RuntimeConditionsExtensionDefinition -metadata: - id: https://runtimeconditions.io/extensions/rc/env-configuration/v1alpha2/runtimeconditions.extension.yaml - version: v1alpha2 -spec: - dependencies: ['https://runtimeconditions.io/extensions/rc/common-integrations/v1alpha2/runtimeconditions.extension.yaml'] - conditionFields: - - {name: configuration, appliesToKinds: [api], appliesToInterfaceTypes: [http]} - - name: configuration - appliesToKinds: [datastore] - appliesToInterfaceTypes: [relational, document] - - {name: configuration, appliesToKinds: [cache], appliesToInterfaceTypes: [key_value]} - - {name: configuration, appliesToKinds: [api], appliesToInterfaceTypes: [smtp]} - fieldValues: - - field: configuration.env[].property - targetKind: api - targetType: http - values: [url, baseUrl, hostname, port, scheme, username, password, token, tls] - - field: configuration.alternatives[].env[].property - targetKind: api - targetType: http - values: [url, baseUrl, hostname, port, scheme, username, password, token, tls] - - field: configuration.env[].property - targetKind: datastore - targetType: relational - values: [url, hostname, port, scheme, username, password, database, tls] - - field: configuration.alternatives[].env[].property - targetKind: datastore - targetType: relational - values: [url, hostname, port, scheme, username, password, database, tls] - - field: configuration.env[].property - targetKind: datastore - targetType: document - values: [url, hostname, port, scheme, username, password, database, tls] - - field: configuration.alternatives[].env[].property - targetKind: datastore - targetType: document - values: [url, hostname, port, scheme, username, password, database, tls] - - field: configuration.env[].property - targetKind: cache - targetType: key_value - values: [url, hostname, port, scheme, username, password, database, token, tls] - - field: configuration.alternatives[].env[].property - targetKind: cache - targetType: key_value - values: [url, hostname, port, scheme, username, password, database, token, tls] - - field: configuration.env[].property - targetKind: api - targetType: smtp - values: [url, hostname, port, username, password, tlsMode, fromAddress, toAddress] - - field: configuration.alternatives[].env[].property - targetKind: api - targetType: smtp - values: [url, hostname, port, username, password, tlsMode, fromAddress, toAddress] - schemas: - - id: configuration-shape - description: Validates the environment configuration field shape. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - properties: - configuration: - type: object - oneOf: - - {required: [env], properties: {env: {$ref: '#/$defs/envList'}}, additionalProperties: false} - - required: [alternatives] - properties: - alternatives: - type: array - minItems: 2 - items: - type: object - required: [env] - properties: {env: {$ref: '#/$defs/envList'}} - additionalProperties: false - additionalProperties: false - additionalProperties: true - $defs: - envList: {type: array, minItems: 1, uniqueItems: true, items: {$ref: '#/$defs/envInput'}} - envInput: - type: object - required: [property, name] - properties: - property: {type: string, minLength: 1} - name: {type: string, pattern: '^[A-Za-z_][A-Za-z0-9_]*$'} - sensitive: {type: boolean} - required: {type: boolean} - additionalProperties: false - - id: configuration-properties-api-http - appliesToKind: api - appliesToInterfaceType: http - description: Validates allowed environment configuration properties for HTTP API integrations. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - properties: {configuration: {$ref: '#/$defs/configuration'}} - additionalProperties: true - $defs: - allowedProperty: {enum: [url, baseUrl, hostname, port, scheme, username, password, token, tls]} - configuration: - type: object - properties: - env: {type: array, items: {$ref: '#/$defs/envInput'}} - alternatives: - type: array - items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} - envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} - - id: configuration-properties-datastore-relational - appliesToKind: datastore - appliesToInterfaceType: relational - description: Validates allowed environment configuration properties for relational datastore integrations. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - properties: {configuration: {$ref: '#/$defs/configuration'}} - additionalProperties: true - $defs: - allowedProperty: {enum: [url, hostname, port, scheme, username, password, database, tls]} - configuration: - type: object - properties: - env: {type: array, items: {$ref: '#/$defs/envInput'}} - alternatives: - type: array - items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} - envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} - - id: configuration-properties-datastore-document - appliesToKind: datastore - appliesToInterfaceType: document - description: Validates allowed environment configuration properties for document datastore integrations. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - properties: {configuration: {$ref: '#/$defs/configuration'}} - additionalProperties: true - $defs: - allowedProperty: {enum: [url, hostname, port, scheme, username, password, database, tls]} - configuration: - type: object - properties: - env: {type: array, items: {$ref: '#/$defs/envInput'}} - alternatives: - type: array - items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} - envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} - - id: configuration-properties-cache-key-value - appliesToKind: cache - appliesToInterfaceType: key_value - description: Validates allowed environment configuration properties for key/value cache integrations. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - properties: {configuration: {$ref: '#/$defs/configuration'}} - additionalProperties: true - $defs: - allowedProperty: {enum: [url, hostname, port, scheme, username, password, database, token, tls]} - configuration: - type: object - properties: - env: {type: array, items: {$ref: '#/$defs/envInput'}} - alternatives: - type: array - items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} - envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}} - - id: configuration-properties-api-smtp - appliesToKind: api - appliesToInterfaceType: smtp - description: Validates environment configuration properties for api/smtp. - schema: - $schema: https://json-schema.org/draft/2020-12/schema - type: object - properties: {configuration: {$ref: '#/$defs/configuration'}} - additionalProperties: true - $defs: - allowedProperty: {enum: [url, hostname, port, username, password, tlsMode, fromAddress, toAddress]} - configuration: - type: object - properties: - env: {type: array, items: {$ref: '#/$defs/envInput'}} - alternatives: - type: array - items: {type: object, properties: {env: {type: array, items: {$ref: '#/$defs/envInput'}}}} - envInput: {type: object, properties: {property: {$ref: '#/$defs/allowedProperty'}}}