engine

package
v0.34.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 29, 2026 License: Apache-2.0 Imports: 58 Imported by: 0

Documentation

Overview

Package engine manages the acquisition and compilation of Timoni's CUE modules.

Index

Constants

View Source 
const (
	// UpdateLevelNone leaves module references without an update attribute untouched.
	UpdateLevelNone string = "none"

	// UpdateLevelPatch updates module references without an update attribute
	// to the newest patch version of the current minor version.
	UpdateLevelPatch string = "patch"

	// UpdateLevelMinor updates module references without an update attribute
	// to the newest minor version of the current major version.
	UpdateLevelMinor string = "minor"

	// UpdateLevelMajor updates module references without an update attribute
	// to the newest version.
	UpdateLevelMajor string = "major"
)
View Source 
const (
	DefaultDevelVersion = "0.0.0-devel"
)

Variables

This section is empty.

Functions

func CopyDir added in v0.30.0 

func CopyDir(srcDir string, dstDir string, resolveSymlinks bool) (err error)

CopyDir copies the given directory to the destination directory, while excluding files that match the timoni.ignore patterns. When resolveSymlinks is true, symbolic links are resolved and their targets copied in place of the links, otherwise symlinks are skipped.

func ExtractStringFromFile added in v0.15.0 

func ExtractStringFromFile(ctx *cue.Context, filePath, exprPath string) (string, error)

func ExtractValueFromBytes added in v0.3.0 

func ExtractValueFromBytes(ctx *cue.Context, data []byte, expr string) (cue.Value, error)

ExtractValueFromBytes compiles data and returns the value at expr or an error.

func ExtractValueFromFile added in v0.0.4 

func ExtractValueFromFile(ctx *cue.Context, filePath, expr string) (cue.Value, error)

ExtractValueFromFile compiles the given file and returns the CUE value that matches the given expression.

func FormatConfigCUE added in v0.33.0 

func FormatConfigCUE(fields []ConfigField) (string, error)

FormatConfigCUE renders the config fields as a CUE definition named #Config, preserving the field documentation, the optional and required markers, the defaults and the type constraints.

func GetEnv added in v0.13.0 

func GetEnv() map[string]string

GetEnv returns a map of all environment variables.

func IsCRD added in v0.34.0 

func IsCRD(object *unstructured.Unstructured) bool

IsCRD returns true if the object is a Kubernetes CustomResourceDefinition.

func IsFileURL added in v0.33.0 

func IsFileURL(url string) bool

IsFileURL returns true if the given URL is a file URL.

func IsOCIUrl added in v0.20.0 

func IsOCIUrl(url string) bool

IsOCIUrl returns true if the given URL is an OCI URL.

func MergeValue added in v0.0.4 

func MergeValue(overlay, base cue.Value) (cue.Value, error)

MergeValue merges the given overlay on top of the base CUE value. New fields from the overlay are added to the base and existing fields are overridden with the overlay values.

func NewVirtualRoot added in v0.30.0 

func NewVirtualRoot() string

NewVirtualRoot returns an OS-native absolute path that does not exist on the host filesystem and is never created, for use as the root directory of CUE loads backed entirely by load.Config.Overlay. Overlay entries shadow the host filesystem but paths without an entry fall through to it, so the root must be guaranteed absent from disk.

func ReadIgnoreFile added in v0.6.0 

func ReadIgnoreFile(moduleRoot string) ([]string, error)

ReadIgnoreFile returns the module ignore patterns or an input error.

Types

type BundleBuilder added in v0.4.0 

type BundleBuilder struct {
	// contains filtered or unexported fields
}

BundleBuilder compiles CUE definitions to Go Bundle objects.

func NewBundleBuilder added in v0.4.0 

func NewBundleBuilder(ctx *cue.Context, files []string) *BundleBuilder

NewBundleBuilder creates a BundleBuilder for the given module and package.

func (*BundleBuilder) Build added in v0.4.0 

func (b *BundleBuilder) Build(workspace string) (cue.Value, error)

Build builds a CUE instance for the specified workspace and returns the CUE value. The workspace files are served to the CUE loader as in-memory overlays. A workspace must be initialised with InitWorkspace before calling this function.

func (*BundleBuilder) GetBundle added in v0.5.0 

func (b *BundleBuilder) GetBundle(v cue.Value) (*apiv1.Bundle, error)

GetBundle returns a Bundle from the bundle CUE value.

func (*BundleBuilder) InitWorkspace added in v0.9.0 

func (b *BundleBuilder) InitWorkspace(workspace string, runtimeValues map[string]string) error

InitWorkspace loads the bundle definitions into the in-memory workspace identified by the given name, sets the bundle schema, and then it injects the runtime values based on @timoni() attributes. Nothing is written to disk; the workspace files are kept in memory and served to the CUE loader as overlays. A workspace must be initialised before calling Build.

func (*BundleBuilder) SetWorkdir added in v0.31.0 

func (b *BundleBuilder) SetWorkdir(dir string)

SetWorkdir sets the directory from which the CUE loader discovers the cue.mod module root, enabling imports in the bundle definitions. When unset, the loader uses the process working directory.

func (*BundleBuilder) WorkspaceDir added in v0.30.0 

func (b *BundleBuilder) WorkspaceDir(workspace string) string

WorkspaceDir returns the virtual directory under which the workspace files are laid out. The directory does not exist on disk; it serves as the base for rendering error positions relative.

type BundleUpdater added in v0.34.0 

type BundleUpdater struct {
	// contains filtered or unexported fields
}

BundleUpdater updates the module versions and digests referenced in bundle files according to the update policies declared with @timoni(update:...) attributes. The literals are rewritten both in the entry files and in the package files of the CUE module that the entry files import.

func NewBundleUpdater added in v0.34.0 

func NewBundleUpdater(ctx *cue.Context, files []string) *BundleUpdater

NewBundleUpdater creates a BundleUpdater for the given bundle files.

func (*BundleUpdater) Apply added in v0.34.0 

func (u *BundleUpdater) Apply(plan *UpdatePlan) error

Apply rewrites the version and digest literals with the planned changes and rebuilds the bundle to verify that the result is a valid bundle.

func (*BundleUpdater) Format added in v0.34.0 

func (u *BundleUpdater) Format(file string) ([]byte, error)

Format returns the formatted content of the given entry or package file from its current syntax tree.

func (*BundleUpdater) Load added in v0.34.0 

func (u *BundleUpdater) Load() error

Load parses the bundle files and builds the bundle value. CUE files are kept as syntax trees so that their literals can be rewritten, YAML and JSON files are read-only and only contribute to the bundle value. The package files of the CUE module imported by the entry files are loaded as well, so that the module references they define can be updated.

func (*BundleUpdater) Plan added in v0.34.0 

func (u *BundleUpdater) Plan(ctx context.Context, lister ModuleVersionLister) (*UpdatePlan, error)

Plan computes the module reference changes for the bundle instances by listing the module versions with the given lister and selecting the version according to the update policy of each instance. The digest of the selected version is resolved only for the instances pinning one. Instances sharing the same version literal are updated together and must reference the same module repository with the same policy. Errors listing or selecting the versions are collected for all the instances and returned along with the changes of the other instances.

func (*BundleUpdater) SetLevel added in v0.34.0 

func (u *BundleUpdater) SetLevel(level string) error

SetLevel sets the update level applied to the module references that don't declare an update attribute. Must be one of the UpdateLevel* values.

func (*BundleUpdater) SetWorkdir added in v0.34.0 

func (u *BundleUpdater) SetWorkdir(dir string)

SetWorkdir sets the directory from which the CUE loader discovers the cue.mod module root, enabling imports in the bundle definitions.

func (*BundleUpdater) Source added in v0.34.0 

func (u *BundleUpdater) Source(file string) ([]byte, error)

Source returns the content of the given entry or package file as read from disk when the bundle was loaded.

func (*BundleUpdater) Value added in v0.34.0 

func (u *BundleUpdater) Value() cue.Value

Value returns the bundle value built from the current state of the files.

type CRDValidator added in v0.34.0 

type CRDValidator struct {
	// contains filtered or unexported fields
}

CRDValidator validates custom resources against the schemas of their CustomResourceDefinitions with the Kubernetes API server admission checks: OpenAPI schema validation, embedded resource metadata, list map and set uniqueness, and the CEL validation rules (x-kubernetes-validations). Schemas are registered per group, version and kind, and the last registration for a kind version wins.

func NewCRDValidator added in v0.34.0 

func NewCRDValidator() *CRDValidator

NewCRDValidator returns an empty CRDValidator.

func (*CRDValidator) AddCRD added in v0.34.0 

func (v *CRDValidator) AddCRD(crd *unstructured.Unstructured) error

AddCRD registers the schema of every version of the given CustomResourceDefinition, replacing schemas previously registered for the same kind versions. A version whose schema cannot be compiled is registered with the compilation error, reported by Validate for every object of that kind version.

func (*CRDValidator) AddCRDs added in v0.34.0 

func (v *CRDValidator) AddCRDs(objects []*unstructured.Unstructured) error

AddCRDs registers the schemas of the CustomResourceDefinitions found in the given objects, ignoring objects of any other kind.

func (*CRDValidator) AddPackages added in v0.34.0 

func (v *CRDValidator) AddPackages(packages []ModuleImport) error

AddPackages registers the CRD schemas embedded by 'timoni mod vendor crd' in the given CUE packages, ignoring packages without an embedded schema.

func (*CRDValidator) HasSchema added in v0.34.0 

func (v *CRDValidator) HasSchema(gvk schema.GroupVersionKind) bool

HasSchema returns true if a schema is registered for the given kind version.

func (*CRDValidator) Validate added in v0.34.0 

func (v *CRDValidator) Validate(ctx context.Context, object *unstructured.Unstructured) []error

Validate checks the object against the schema registered for its kind version and returns one error per violation, sorted by field path. A copy of the object goes through the API server admission steps for a create request: the status is dropped when the CRD declares the status subresource, unknown fields are pruned unless the CRD preserves them, and the defaults declared in the schema are applied. The pruned fields are reported as violations. The CEL rules are evaluated only when the OpenAPI schema validation reports no blocking errors, and transition rules that reference oldSelf are skipped unless they set optionalOldSelf.

type ConfigField added in v0.33.0 

type ConfigField struct {
	// Path is the CUE path of the field relative to the config root.
	Path cue.Path
	// Type is the CUE expression constraining the field, without its default.
	Type string
	// Default is the JSON encoding of the field's default or concrete value.
	Default string
	// Doc is the field documentation, one line per comment line.
	Doc string
	// Optional is true for fields declared with `?`.
	Optional bool
	// Required is true for fields declared with `!`.
	Required bool
	// NoDoc is true for fields commented with `// +nodoc`.
	NoDoc bool
}

ConfigField describes one field of a module's #Config schema.

func (ConfigField) Key added in v0.33.0 

func (f ConfigField) Key() string

Key returns the field path in the `a: b: c:` form used by the config table, without the optional and required markers.

type HealthCheck added in v0.29.0 

type HealthCheck struct {
	// Name is the health check's key under 'timoni: healthChecks:'.
	Name string

	// GroupKind of the target resources; an empty Kind makes the
	// check apply to every kind in the group.
	GroupKind schema.GroupKind
	// contains filtered or unexported fields
}

HealthCheck holds a module-defined CUE readiness evaluation for the Kubernetes resources matching its GroupKind.

func (*HealthCheck) Evaluate added in v0.29.0 

func (hc *HealthCheck) Evaluate(object map[string]any) (HealthStatus, error)

Evaluate fills the health check's #object with the live object content and evaluates the inProgress, failed and current expressions in order, returning the status of the first expression yielding true, or HealthStatusInProgress when none does. Expressions that cannot be evaluated because the referenced fields are missing from the live object count as false; any other evaluation failure returns an error.

type HealthStatus added in v0.29.0 

type HealthStatus string

HealthStatus is the outcome of a HealthCheck evaluation. 

const (
	// HealthStatusCurrent means the resource is ready.
	HealthStatusCurrent HealthStatus = "Current"

	// HealthStatusInProgress means the resource is still reconciling.
	HealthStatusInProgress HealthStatus = "InProgress"

	// HealthStatusFailed means the resource reached a terminal failure state.
	HealthStatusFailed HealthStatus = "Failed"
)

type Importer added in v0.14.0 

type Importer struct {
	// contains filtered or unexported fields
}

Importer generates CUE definitions from Kubernetes CRDs using the OpenAPI v3 spec.

func NewImporter added in v0.14.0 

func NewImporter(ctx *cue.Context, header string) *Importer

NewImporter creates an Importer for the given CUE context.

func (*Importer) Generate added in v0.14.0 

func (imp *Importer) Generate(crdData []byte) (map[string][]byte, error)

Generate takes a multi-doc YAML containing Kubernetes CRDs and returns the CUE definitions generated from the OpenAPI spec. The resulting key value pairs, contain a unique identifier in the format `<group>/<kind>/<version>` and the contents of the CUE definition.

type IntermediateCRD added in v0.13.0 

type IntermediateCRD struct {
	// The original unmodified CRD YAML, after conversion to a cue.Value.
	Original cue.Value
	Props    struct {
		Spec struct {
			Group string `json:"group"`
			Names struct {
				Kind     string `json:"kind"`
				ListKind string `json:"listKind"`
				Plural   string `json:"plural"`
				Singular string `json:"singular"`
			} `json:"names"`
			Scope string `json:"scope"`
		} `json:"spec"`
	}

	// All the schemas in the original CRD, converted to CUE representation.
	Schemas []VersionedSchema
}

IntermediateCRD is an intermediate representation of CRD YAML. It contains the original CRD YAML input, a subset of useful naming-related fields, and an extracted list of the version schemas in the CRD, having been converted from OpenAPI to CUE.

type ModuleBuilder added in v0.0.4 

type ModuleBuilder struct {
	// contains filtered or unexported fields
}

ModuleBuilder compiles CUE definitions to Kubernetes objects.

func NewModuleBuilder added in v0.0.4 

func NewModuleBuilder(ctx *cue.Context, name, namespace, moduleRoot, pkgName string) *ModuleBuilder

NewModuleBuilder creates a ModuleBuilder for the given module and package.

func (*ModuleBuilder) Build added in v0.0.4 

func (b *ModuleBuilder) Build(tags ...string) (cue.Value, error)

Build builds the Timoni instance for the specified module and returns its CUE value. If the instance validation fails, the returned error may represent more than one error, retrievable with errors.Errors.

func (*ModuleBuilder) GetAPIVersion added in v0.0.6 

func (b *ModuleBuilder) GetAPIVersion(value cue.Value) (string, error)

GetAPIVersion returns the list of API version of the Timoni's CUE definition.

func (*ModuleBuilder) GetApplySets added in v0.0.5 

func (b *ModuleBuilder) GetApplySets(value cue.Value) ([]ResourceSet, error)

GetApplySets returns the list of Kubernetes unstructured objects to be applied in steps.

func (*ModuleBuilder) GetConfigDoc added in v0.20.0 

func (b *ModuleBuilder) GetConfigDoc(value cue.Value) ([]ConfigField, error)

GetConfigDoc extracts the fields of the module's #Config schema from the built module value. A field is listed when it is declared in the module itself (outside cue.mod) or carries a default, and its children are listed when it is a struct without a default. The fields injected by Timoni at apply time are skipped.

func (*ModuleBuilder) GetContainerImages added in v0.15.0 

func (b *ModuleBuilder) GetContainerImages(value cue.Value) ([]string, error)

GetContainerImages extracts the container images referenced in the instance config values.

func (*ModuleBuilder) GetDefaultValues added in v0.0.4 

func (b *ModuleBuilder) GetDefaultValues() (string, error)

GetDefaultValues extracts the values from the module's root values.cue, preferring the in-memory overlay set with OverlayValuesFile or OverlayValuesFileWithDefaults over the file on disk.

func (*ModuleBuilder) GetHealthChecks added in v0.29.0 

func (b *ModuleBuilder) GetHealthChecks(value cue.Value) ([]*HealthCheck, error)

GetHealthChecks extracts the custom health checks declared by the module under 'timoni: healthChecks:'. It returns nil when the field is absent and errors on duplicate GroupKind targets.

func (*ModuleBuilder) GetImports added in v0.34.0 

func (b *ModuleBuilder) GetImports() ([]ModuleImport, error)

GetImports returns the CUE packages imported, directly or transitively, by the module package compiled with Build.

func (*ModuleBuilder) GetModuleName added in v0.0.4 

func (b *ModuleBuilder) GetModuleName() (string, error)

GetModuleName returns the module name as defined in 'cue.mod/module.cue'.

func (*ModuleBuilder) OverlaySchemaFile added in v0.30.0 

func (b *ModuleBuilder) OverlaySchemaFile() error

OverlaySchemaFile generates the module's instance schema as an in-memory file passed to the loader at build time, leaving the module directory untouched so it can be shared between instances.

func (*ModuleBuilder) OverlayValuesFile added in v0.30.0 

func (b *ModuleBuilder) OverlayValuesFile(overlays [][]byte) error

OverlayValuesFile merges the given values overlays into the module's root values.cue as an in-memory file passed to the loader at build time, leaving the module directory untouched so it can be shared between instances.

func (*ModuleBuilder) OverlayValuesFileWithDefaults added in v0.30.0 

func (b *ModuleBuilder) OverlayValuesFileWithDefaults(val cue.Value) error

OverlayValuesFileWithDefaults merges the module's root values.cue with the supplied value into an in-memory file passed to the loader at build time, leaving the module directory untouched so it can be shared between instances.

func (*ModuleBuilder) SetVersionInfo added in v0.12.0 

func (b *ModuleBuilder) SetVersionInfo(moduleVersion, kubeVersion string)

SetVersionInfo allows setting the Timoni module version and Kubernetes version, which are injected at build time as optional CUE tags.

type ModuleImport added in v0.34.0 

type ModuleImport struct {
	// Path is the import path of the package.
	Path string
	// Value is the compiled package.
	Value cue.Value
}

ModuleImport is a CUE package imported by a module.

type ModuleVersionLister added in v0.34.0 

type ModuleVersionLister interface {
	// ListVersions returns the module versions, newest first,
	// along with the latest tag when present.
	ListVersions(ctx context.Context, repository string) ([]string, error)

	// ResolveDigest returns the digest of the given module version.
	ResolveDigest(ctx context.Context, repository, version string) (string, error)
}

ModuleVersionLister lists the versions published in a module repository and resolves their digests.

type OCIModuleVersionLister added in v0.34.0 

type OCIModuleVersionLister struct {
	Opts []crane.Option
}

OCIModuleVersionLister lists the module versions from an OCI repository.

func (*OCIModuleVersionLister) ListVersions added in v0.34.0 

func (l *OCIModuleVersionLister) ListVersions(ctx context.Context, repository string) ([]string, error)

ListVersions lists the semver tags of the module repository.

func (*OCIModuleVersionLister) ResolveDigest added in v0.34.0 

func (l *OCIModuleVersionLister) ResolveDigest(_ context.Context, repository, version string) (string, error)

ResolveDigest resolves the digest of the module version tag.

type ResourceSet added in v0.0.5 

type ResourceSet struct {

	// Name of the object list.
	Name string `json:"name"`

	// Objects holds the list of Kubernetes objects.
	// +optional
	Objects []*unstructured.Unstructured `json:"objects,omitempty"`
}

ResourceSet is a named list of Kubernetes resource objects.

func GetResources added in v0.0.5 

func GetResources(value cue.Value) ([]ResourceSet, error)

GetResources converts the CUE value to a list of ResourceSets. If objects in multiple resource lists are found invalid, the returned error aggregates the failures of all lists, retrievable with errors.Unwrap.

type RuntimeBuilder added in v0.13.0 

type RuntimeBuilder struct {
	// contains filtered or unexported fields
}

RuntimeBuilder compiles CUE definitions to Go Runtime objects.

func NewRuntimeBuilder added in v0.13.0 

func NewRuntimeBuilder(ctx *cue.Context, files []string) *RuntimeBuilder

NewRuntimeBuilder creates a RuntimeBuilder for the given module and package.

func (*RuntimeBuilder) Build added in v0.13.0 

func (b *RuntimeBuilder) Build(workspace string) (cue.Value, error)

Build builds a CUE instance for the specified workspace and returns the CUE value. The workspace files are served to the CUE loader as in-memory overlays. A workspace must be initialised with InitWorkspace before calling this function.

func (*RuntimeBuilder) GetRuntime added in v0.13.0 

func (b *RuntimeBuilder) GetRuntime(v cue.Value) (*apiv1.Runtime, error)

GetRuntime returns a Runtime from the specified CUE value.

func (*RuntimeBuilder) InitWorkspace added in v0.13.0 

func (b *RuntimeBuilder) InitWorkspace(workspace string) error

InitWorkspace extracts the runtime definitions into the in-memory workspace identified by the given name. Nothing is written to disk; the workspace files are kept in memory and served to the CUE loader as overlays. A workspace must be initialised before calling Build.

func (*RuntimeBuilder) SetWorkdir added in v0.31.0 

func (b *RuntimeBuilder) SetWorkdir(dir string)

SetWorkdir sets the directory from which the CUE loader discovers the cue.mod module root, enabling imports in the runtime definitions. When unset, the loader uses the process working directory.

func (*RuntimeBuilder) WorkspaceDir added in v0.30.0 

func (b *RuntimeBuilder) WorkspaceDir(workspace string) string

WorkspaceDir returns the virtual directory under which the workspace files are laid out. The directory does not exist on disk; it serves as the base for rendering error positions relative.

type RuntimeInjector added in v0.13.0 

type RuntimeInjector struct {
	// contains filtered or unexported fields
}

RuntimeInjector injects field values in CUE files based on @timoni() attributes.

func NewRuntimeInjector added in v0.13.0 

func NewRuntimeInjector(ctx *cue.Context) *RuntimeInjector

NewRuntimeInjector creates an RuntimeInjector for the given context.

func (*RuntimeInjector) Inject added in v0.13.0 

func (in *RuntimeInjector) Inject(node ast.Node, vars map[string]string) ([]byte, error)

Inject searches for Timoni's attributes and sets the CUE field value to the runtime value. If an attribute does not match any runtime value, the CUE field is left untouched.

func (*RuntimeInjector) ListAttributes added in v0.13.0 

func (in *RuntimeInjector) ListAttributes(f *ast.File) map[string]string

type UpdateChange added in v0.34.0 

type UpdateChange struct {
	Instances   []string
	Repository  string
	FromVersion string
	ToVersion   string
	FromDigest  string
	ToDigest    string

	// Files are the paths of the bundle files holding the rewritten literals.
	Files []string
	// contains filtered or unexported fields
}

UpdateChange records a module reference change for the instances whose version is defined by the same literal.

type UpdatePlan added in v0.34.0 

type UpdatePlan struct {
	Changes []*UpdateChange
	Skipped []*UpdateSkip
}

UpdatePlan holds the module reference changes computed for a bundle.

type UpdatePolicy added in v0.34.0 

type UpdatePolicy struct {
	// Policy is one of the apiv1.UpdatePolicy* values.
	Policy string

	// Constraint is the semver constraint of the semver policy.
	Constraint string
}

UpdatePolicy describes how the version of a module reference is selected.

type UpdateSkip added in v0.34.0 

type UpdateSkip struct {
	Instance   string
	Repository string
	Reason     string
}

UpdateSkip records an instance excluded from the update and the reason.

type ValuesBuilder added in v0.0.4 

type ValuesBuilder struct {
	// contains filtered or unexported fields
}

ValuesBuilder compiles and merges values files.

func NewValuesBuilder added in v0.0.4 

func NewValuesBuilder(ctx *cue.Context) *ValuesBuilder

NewValuesBuilder creates a ValuesBuilder for the given context.

func (*ValuesBuilder) MergeValues added in v0.0.4 

func (b *ValuesBuilder) MergeValues(overlays [][]byte, base string) (cue.Value, error)

MergeValues merges the given overlays in order using the base as the starting point.

type VersionedSchema added in v0.13.0 

type VersionedSchema struct {
	// The contents of the `spec.versions[].name`
	Version string
	// The contents of `spec.versions[].schema.openAPIV3Schema`, after conversion of the OpenAPI
	// schema to native CUE constraints.
	Schema cue.Value
	// The CRD manifest reduced to this version.
	CRD cue.Value
}

VersionedSchema is an intermediate form of a single versioned schema from a CRD (an element in `spec.versions`), converted to CUE.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.