Documentation ¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AsArray ¶
func AsArray(sch VersionedCueSchema) [][]VersionedCueSchema
AsArray collates all VersionedCueSchema in a Family into a two-dimensional array. The outer array index corresponds to major version number and inner array index to minor version number.
func WrapCUEError ¶
WrapCUEError is a wrapper for cueErrors that occur and are not self explanatory. If an error is of type cueErr, then iterate through the error array, export line number and filename, otherwise return usual error.
Types ¶
type CueSchema ¶
type CueSchema interface { // Validate checks that the resource is correct with respect to the schema. Validate(Resource) error // Migrate transforms a Resource into a new Resource that is correct with // respect to its Successor schema. It returns the transformed resource, // the schema to which the resource now conforms, and any errors that // may have occurred during the migration. // // No migration occurs and the input Resource is returned in two cases: // // - The migration encountered an error; the third return is non-nil. // - There exists no schema to migrate to; the second and third return are nil. // // Note that the returned schema is always a VersionedCueSchema. This // reflects a key design invariant of the system: all migrations, whether // they begin from a schema inside or outside of the Family, must land // somewhere on a Family's sequence of schemata. Migrate(Resource) (Resource, VersionedCueSchema, error) // Successor returns the VersionedCueSchema to which this CueSchema can migrate a // Resource. Successor() VersionedCueSchema // CUE returns the cue.Value representing the actual schema. CUE() cue.Value }
CueSchema represents a single, complete CUE-based schema that can perform operations on Resources.
All CueSchema MUST EITHER:
- Be a VersionedCueSchema, and be the latest version in the latest lineage in a Family
- Return non-nil from Successor(), and a procedure to Migrate() a Resource to that successor schema
By definition, VersionedCueSchema are within a lineage. As long as lineage backwards compatibility invariants hold, migration to a VersionedCueSchema to a successor schema in their lineage is trivial: simply unify the Resource with the successor schema.
type Resource ¶
type Resource struct { Value interface{} Name string }
A Resource represents a concrete data object - e.g., JSON representing a dashboard.
This type mostly exists to improve readability for users. Having a type that differentiates cue.Value that represent a schema from cue.Value that represent a concrete object is quite helpful. It also gives us a working type for a resource that can be reused across multiple calls, so that re-parsing isn't necessary.
TODO this is a terrible way to do this, refactor
func ApplyDefaults ¶
ApplyDefaults returns a new, concrete copy of the Resource with all paths that are 1) missing in the Resource AND 2) specified by the schema, filled with default values specified by the schema.
type SearchOption ¶
type SearchOption sso
SearchOption indicates how far along a chain of schemas an operation should proceed.
func Exact ¶
func Exact(maj, min int) SearchOption
Exact will find the schema with the exact major and minor version number provided.
func Latest ¶
func Latest() SearchOption
Latest indicates that traversal will continue to the newest schema in the newest lineage.
func LatestInCurrentMajor ¶
func LatestInCurrentMajor() SearchOption
LatestInCurrentMajor will find the newest schema having the same major version as the schema from which the search begins.
func LatestInMajor ¶
func LatestInMajor(maj int) SearchOption
LatestInMajor will find the latest schema within the provided major version lineage. If no lineage exists corresponding to the provided number, traversal will terminate with an error.
type VersionedCueSchema ¶
type VersionedCueSchema interface { CueSchema // Version reports the major and minor versions of the schema. Version() (major, minor int) }
VersionedCueSchema are CueSchema that are part of a backwards-compatible versioned lineage.
func Find ¶
func Find(s VersionedCueSchema, opt SearchOption) VersionedCueSchema
Find traverses the chain of VersionedCueSchema until the criteria in the SearchOption is met.
If no schema is found that fulfills the criteria, nil is returned. Latest() and LatestInCurrentMajor() will always succeed, unless the input schema is nil.
func SearchAndValidate ¶
func SearchAndValidate(s VersionedCueSchema, v interface{}) (VersionedCueSchema, error)
SearchAndValidate traverses the family of schemas reachable from the provided VersionedCueSchema. For each schema, it attempts to validate the provided value, which may be a byte slice representing valid JSON (TODO YAML), a Go struct, or cue.Value. If providing a cue.Value that is not fully concrete, the result is undefined.
Traversal is performed from the newest schema to the oldest. However, because newer VersionedCueSchema have no way of directly accessing their predecessors (they form a singly-linked list), the oldest possible schema should always be provided - typically, the one returned from the family loader function.
Failure to validate against any schema in the family is indicated by a non-nil error return. Success is indicated by a non-nil VersionedCueSchema. If successful, the returned VersionedCueSchema will be the first one against which the provided resource passed validation.