engine

package
v0.30.0 Latest Latest
Warning

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

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

Documentation

Overview

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

Index

Constants

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 GetEnv added in v0.13.0 

func GetEnv() map[string]string

GetEnv returns a map of all environment variables.

func IsFileUrl added in v0.20.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) 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 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) ([][]string, error)

GetConfigDoc extracts the config structure from the module.

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) 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 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) 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 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
}

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.