kernel

package
v1.0.0-alpha.21 Latest Latest
Warning

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

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

Documentation

Overview

Package kernel exposes the OPM runtime as a single struct, Kernel.

Kernel owns its *cue.Context for its entire lifetime and threads cross-cutting dependencies (logger, tracer, clock) through every operation. Downstream binaries (CLI, controller, Crossplane function) construct one Kernel per goroutine and call methods on it instead of importing the individual loader / module / compile / validate packages.

Goroutine safety

A single Kernel is NOT safe for concurrent use across its own method calls. The owned *cue.Context is driven single-threaded — sharing one Kernel between goroutines can cause data races inside CUE evaluation. Callers that need concurrency MUST construct one Kernel per goroutine.

Under the CUE v0.17 toolchain, a *materialize.MaterializedPlatform materialized once by one Kernel is safe to be read concurrently by many per-goroutine Kernels' Kernel.Compile calls — with no mutex and no re-materialization. This holds because the compile pipeline builds every value it constructs in the caller Kernel's own *cue.Context and only cross-*reads* the shared platform (it looks up and fills from the platform's Package, never mutating it). This is the materialize-once-reuse-many model the Platform-CR design depends on.

The two facts compose: keep one Kernel per goroutine, but share a single materialized platform across all of them read-only.

One-Kernel-per-goroutine example 

func renderAll(ctx context.Context, paths []string) error {
    var wg sync.WaitGroup
    errs := make(chan error, len(paths))
    for _, p := range paths {
        wg.Add(1)
        go func(path string) {
            defer wg.Done()
            k := kernel.New() // one Kernel per goroutine
            if _, _, err := k.LoadModulePackage(ctx, path, loaderfile.LoadOptions{}); err != nil {
                errs <- err
            }
        }(p)
    }
    wg.Wait()
    close(errs)
    for err := range errs {
        if err != nil {
            return err
        }
    }
    return nil
}

Concurrent rendering against a shared platform

One Kernel materializes a platform once; N goroutines each construct their own Kernel and Compile a distinct instance against that single shared platform. Per ADR-002 the speedup is real but sub-linear — the CUE evaluator is allocator-bound and plateaus around four cores — so share for correctness and memory footprint, not for linear throughput. 

func renderConcurrent(ctx context.Context, shared *materialize.MaterializedPlatform, rels []*module.Instance) error {
    var wg sync.WaitGroup
    errs := make(chan error, len(rels))
    for _, inst := range rels {
        wg.Add(1)
        go func(inst *module.Instance) {
            defer wg.Done()
            k := kernel.New() // one Kernel per goroutine
            if _, err := k.Compile(ctx, kernel.CompileInput{
                ModuleInstance: inst,
                Platform:      shared, // materialized once elsewhere, read-only here
                RuntimeName:   "opm-operator",
            }); err != nil {
                errs <- err
            }
        }(inst)
    }
    wg.Wait()
    close(errs)
    for err := range errs {
        if err != nil {
            return err
        }
    }
    return nil
}

Phase methods

The kernel exposes four phase-explicit methods that mirror the OPM pipeline. Each accepts a phase-specific input struct and returns a phase-appropriate result:

  • Kernel.Validate — Tier-2 schema validation of values against the module's `#config`. Returns nil or an error wrapped with `module %q:` framing whose underlying tree is walkable as cuelang.org/go/cue/errors.Error.
  • Kernel.Match — component / transformer pairing. Returns *MatchPlan without executing any transformer.
  • Kernel.Plan — Validate + Match + summaries. Returns *PlanResult; does NOT produce rendered values. This is the verb every frontend's "plan" / "preview" subcommand wants.
  • Kernel.Compile — full pipeline (Validate + Match + Execute). Returns *CompileResult containing rendered values plus provenance. This is the terminal output and the verb every frontend's "apply" / "render" subcommand wants.

CLI subcommands map naturally onto these methods (vet → Validate, match → Match, plan → Plan, apply → Compile).

Configuration validation

Three primitives form the validation surface:

All three return CUE-native errors. Walk them via cuelang.org/go/cue/errors.Errors / cuelang.org/go/cue/errors.Positions, or print via cuelang.org/go/cue/errors.Print. Presentation belongs to the frontend — the kernel does not ship a formatter.

Typed convenience methods on the kernel resolve `#config` for the caller: Kernel.ValidateModuleValues / Kernel.ValidateInstanceValues (plus their `Partial` and `Detailed` counterparts) take a *module.Module or *module.Instance and delegate to the corresponding primitive.

Advanced: CueContext accessor

Kernel.CueContext returns the underlying *cue.Context for callers that need to build [cue.Value]s outside the kernel (typically tests). Values built with this context are safe to pass back into Kernel methods. Most callers should not need this.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Clock 

type Clock interface {
	Now() time.Time
}

Clock is the kernel's view of wall-clock time. The interface is intentionally minimal: future slices may consult Clock.Now for deterministic rendering when render becomes time-dependent. Pass a fake Clock via WithClock in tests that need to pin time.

type CompileInput 

type CompileInput struct {
	// ModuleInstance supplies instance-level metadata and components.
	// Required.
	ModuleInstance *module.Instance

	// Values is the user-supplied values cue.Value to validate. Optional;
	// the zero cue.Value skips validation.
	Values cue.Value

	// Platform is the materialized platform whose #composedTransformers and
	// #matchers index drive the matcher. Required. Callers MUST Materialize a
	// *platform.Platform before invoking these phases.
	Platform *materialize.MaterializedPlatform

	// RuntimeName identifies the runtime executing this compile (e.g.
	// "opm-cli", "opm-controller"). MUST be non-empty.
	RuntimeName string
}

CompileInput is the input for Kernel.Compile. The instance artifact is the sole module-side handle: the `#config` schema and module-level metadata are reachable via `ModuleInstance.ConfigSchema()` and the binding's `Paths().ModuleMetadata`.

type CompileResult 

type CompileResult = compile.CompileResult

CompileResult is the result of Kernel.Compile.

type Kernel 

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

Kernel is the public anchor type for the OPM runtime. It owns a *cue.Context for its lifetime and carries the cross-cutting dependencies (logger, tracer, clock, schema cache) used by every kernel operation.

Kernel is NOT safe for concurrent use across method calls — see the package documentation for the one-Kernel-per-goroutine pattern.

The Kernel owns exactly one *schema.Cache for its lifetime. Long- running consumers (operator, server) MUST keep the Kernel alive across operations to reuse the in-process schema cache; constructing a fresh Kernel per request pays the schema-fetch cost on every cold disk cache. The CUE module cache on disk is shared across Kernels.

func New 

func New(opts ...Option) *Kernel

New constructs a Kernel with default dependencies and applies the supplied options. Defaults are:

  • cue.Context: a fresh cuecontext.New
  • Logger: a no-op *slog.Logger (writes are discarded)
  • Tracer: a no-op OpenTelemetry tracer
  • Clock: wall-clock time via time.Now
  • SchemaCache: a fresh *schema.Cache backed by zero-value schema.OCILoader; resolves opmodel.dev/core@v2 against CUE_REGISTRY / CUE_CACHE_DIR from the process environment

New never returns nil. The returned Kernel is NOT safe for concurrent use across method calls.

New does NOT trigger a schema load. The first Kernel method that needs the schema invokes [Cache.Get] internally, which performs the fetch lazily.

func (*Kernel) AcquireModuleFromRegistry 

func (k *Kernel) AcquireModuleFromRegistry(ctx context.Context, modPath, version string) (*module.Module, error)

AcquireModuleFromRegistry loads a #Module published in an OCI registry (same fetch + main-module staging + shape gate as Kernel.LoadModuleFromRegistry) and returns a decoded *module.Module whose staged source (module.Source) is populated, so the module can be reused as the main module of a follow-on build — notably by Kernel.SynthesizeInstance, which stages the instance inside the module's own root so the module's already-tidied cue.mod/module.cue drives transitive dependency resolution. Unlike the two-step Kernel.LoadModuleFromRegistry → Kernel.NewModuleFromValue path (which discards the staged source at the cue.Value boundary), this single call preserves it without a second registry fetch.

func (*Kernel) Compile 

func (k *Kernel) Compile(ctx context.Context, in CompileInput) (*CompileResult, error)

Compile runs the full pipeline (Validate + Match + Execute) and returns a *CompileResult containing rendered values, component summaries, unmatched FQNs, and warnings.

The Tier-2 #config schema validation is sourced from the embedded #module reference on `in.ModuleInstance.Package` (see module.Instance.ConfigSchema). No standalone `*module.Module` is required.

func (*Kernel) CueContext 

func (k *Kernel) CueContext() *cue.Context

CueContext returns the *cue.Context owned by this Kernel.

Advanced: most callers do not need this. Use it only when building [cue.Value]s outside the kernel (typically tests or programmatic CUE construction). Values built with this context are safe to pass back into Kernel methods. The same *cue.Context is returned for the lifetime of the Kernel.

func (*Kernel) LoadInstancePackage 

func (k *Kernel) LoadInstancePackage(_ context.Context, dirPath string, opts loaderfile.LoadOptions) (cue.Value, error)

LoadInstancePackage loads a #ModuleInstance CUE package from a directory using the kernel's *cue.Context. See loaderfile.LoadInstancePackage.

Was: LoadReleasePackage

func (*Kernel) LoadModuleFromRegistry added in v0.5.0 

func (k *Kernel) LoadModuleFromRegistry(ctx context.Context, modPath, version string) (cue.Value, error)

LoadModuleFromRegistry loads a #Module published in an OCI registry by its major-qualified path (e.g. "example.com/modules/hello@v0") and version (e.g. "v0.0.2"), using the kernel's *cue.Context and configured registry (set via WithRegistry, inheriting CUE_REGISTRY from the process environment when unset). It returns the raw module cue.Value; callers decode it via Kernel.NewModuleFromValue, mirroring Kernel.LoadModulePackage's two-step load→decode contract. See loaderregistry.LoadModulePackage.

func (*Kernel) LoadModulePackage 

func (k *Kernel) LoadModulePackage(_ context.Context, dirPath string, opts loaderfile.LoadOptions) (cue.Value, error)

LoadModulePackage loads a module CUE package from a directory using the kernel's *cue.Context. See loaderfile.LoadModulePackage.

func (*Kernel) LoadPlatformPackage 

func (k *Kernel) LoadPlatformPackage(_ context.Context, dirPath string, opts loaderfile.LoadOptions) (cue.Value, error)

LoadPlatformPackage loads a #Platform CUE package from a directory using the kernel's *cue.Context. See loaderfile.LoadPlatformPackage.

func (*Kernel) LoadSourceFromBytes 

func (k *Kernel) LoadSourceFromBytes(origin, name string, b []byte) (Source, error)

LoadSourceFromBytes compiles b into a Source with cue.Filename(origin) baked into the resulting cue.Value, so that any subsequent validation error positions carry origin via token.Pos.Filename.

Returns an error if compilation fails (the returned Source is the zero value in that case).

func (*Kernel) LoadSourceFromFile 

func (k *Kernel) LoadSourceFromFile(path string) (Source, error)

LoadSourceFromFile reads a values file from disk, compiles it via cuelang.org/go/cue/load.Instances (which populates cue.Filename automatically with the file's absolute path), and returns a Source whose Origin matches the absolute path so per-position diagnostics remain consistent with the file the user wrote.

Auto-unwrap: if the loaded value has a top-level `values:` field that exists and reports no error, that field is returned as the Source.Value. Otherwise the whole evaluated file value is returned.

Name defaults to the basename.

func (*Kernel) LoadSourceFromString 

func (k *Kernel) LoadSourceFromString(origin, name, s string) (Source, error)

LoadSourceFromString is the [string]-input mirror of Kernel.LoadSourceFromBytes.

func (*Kernel) Match 

func (k *Kernel) Match(_ context.Context, in MatchInput) (*MatchPlan, error)

Match produces a *MatchPlan describing matched and non-matched component / transformer pairs. It does NOT execute any transformer.

func (*Kernel) Materialize 

func (k *Kernel) Materialize(ctx context.Context, p *platform.Platform) (*materialize.MaterializedPlatform, error)

Materialize realizes a #Platform's path-keyed catalog subscriptions into a sealed *materialize.MaterializedPlatform, delegating to opm/materialize with the kernel's configured registry (WithRegistry) and owned *cue.Context.

It performs registry I/O (version enumeration + OCI pulls) and is explicit and caller-driven: the kernel holds no materialize cache (Principle I). Long-running consumers that want memoization wire their own cache via opm/materialize/cache; short-lived ones rely on CUE's on-disk module cache.

Adding this method does not change the signatures of the existing phase methods (Validate, Match, Plan, Compile), which still take *platform.Platform in this slice.

func (*Kernel) NewInstanceFromValue 

func (k *Kernel) NewInstanceFromValue(v cue.Value) (*module.Instance, error)

NewInstanceFromValue builds a typed *module.Instance from a raw cue.Value. See module.NewInstanceFromValue.

Was: NewReleaseFromValue

func (*Kernel) NewModuleFromValue 

func (k *Kernel) NewModuleFromValue(v cue.Value) (*module.Module, error)

NewModuleFromValue builds a typed *module.Module from a raw cue.Value. See module.NewModuleFromValue.

func (*Kernel) NewPlatformFromValue 

func (k *Kernel) NewPlatformFromValue(v cue.Value) (*platform.Platform, error)

NewPlatformFromValue builds a typed *platform.Platform from a raw cue.Value. See platform.NewPlatformFromValue.

func (*Kernel) Plan 

func (k *Kernel) Plan(ctx context.Context, in PlanInput) (*PlanResult, error)

Plan runs Validate + Match + Execute (dry-run) and returns a *PlanResult containing component summaries, unmatched components, the full match diagnosis, and warnings. It does NOT return rendered values. Like Compile, Plan fails on unresolved demands (0010 D28) — via [*oerrors.UnresolvedDemandsError] — and on unmatched components; only Kernel.Match returns the diagnosis without failing on it.

Internally Plan reuses [Compile] and discards the rendered slice. This keeps Plan and Compile pinned to a single execution path so a Plan that succeeds gives the caller strong confidence that a subsequent Compile will also succeed.

func (*Kernel) ProcessModuleInstance 

func (k *Kernel) ProcessModuleInstance(_ context.Context, spec cue.Value, mod module.Module, values cue.Value) (*module.Instance, error)

ProcessModuleInstance validates the supplied values, fills them into the instance spec, asserts the result is fully concrete, decodes instance metadata via opm/schema, and returns a constructed *module.Instance.

The instance spec carries its source #Module inside the CUE package; the schema for value validation is read from spec via schema.Module + schema.Config. mod is supplied for fallback diagnostics (instance name when metadata.name is not yet concrete) and is not retained on the returned Instance — the source module remains reachable through Instance.Package.

values is a single, pre-unified cue.Value — layering is performed by callers via Kernel.ValidateConfigDetailed before this call. The zero cue.Value is treated as "no values supplied": validation is skipped, no fill is performed, and the spec must already be concrete on every required field.

Was: ProcessModuleRelease

func (*Kernel) SchemaCache 

func (k *Kernel) SchemaCache() *schema.Cache

SchemaCache returns the *schema.Cache owned by this Kernel. The same pointer is returned for the lifetime of the Kernel; callers MAY hold it across operations to ensure cache reuse.

Calling SchemaCache does NOT trigger a schema load. Only the first schema.Cache.Get invocation contacts CUE; the load is lazy and memoized.

Typical use: pass to synth.InstanceInput.SchemaCache before calling instance synthesis, or read schema.Cache.ResolvedVersion for diagnostics after a schema-touching operation has run.

func (*Kernel) SynthesizeInstance 

func (k *Kernel) SynthesizeInstance(ctx context.Context, in synth.InstanceInput) (*module.Instance, error)

SynthesizeInstance builds a *module.Instance from typed in-memory inputs. This is the recommended entry point for callers that hold a Module and need a fully validated instance — it mirrors how Kernel.LoadInstancePackage is the recommended entry point for the file-driven path.

SynthesizeInstance chains synth.Instance (which unifies inputs against the version binding's #ModuleInstance schema and lets CUE derive uuid, components, auto-secrets, and standard labels) into Kernel.ProcessModuleInstance (which validates supplied values against the module's #config, fills them into the spec, enforces concreteness, and decodes instance metadata).

The Kernel's *cue.Context threads through both steps so the resulting *module.Instance.Package is reachable through cue lookups using the same runtime. Callers that explicitly want the helper-level primitive — for example, a test that wants the spec value before concreteness enforcement — should call synth.Instance directly with Kernel.CueContext and then invoke Kernel.ProcessModuleInstance themselves.

in.Values is passed through to Kernel.ProcessModuleInstance unchanged. The zero cue.Value means "no values supplied"; Kernel.ProcessModuleInstance then fails the concreteness check unless every #config field has a default. synth.Instance never falls back to Module.debugValues — frontends that want a debug-values overlay layer it on the caller side.

Was: SynthesizeRelease

func (*Kernel) SynthesizePlatform added in v0.3.0 

func (k *Kernel) SynthesizePlatform(_ context.Context, in synth.PlatformInput) (*platform.Platform, error)

SynthesizePlatform builds a *platform.Platform from typed in-memory inputs. This is the recommended entry point for callers that hold platform configuration as typed data — an operator reconciling a Platform CRD spec, a CLI assembling subscriptions from flags — and is the synthesis peer of Kernel.LoadPlatformPackage on the file-driven path.

SynthesizePlatform chains synth.Platform (which unifies inputs against the resolved #Platform schema) into platform.NewPlatformFromValue (which decodes the platform metadata and stores the value as the platform's Package). It returns the pre-materialize *platform.Platform twin.

It does NOT call Kernel.Materialize: resolving the platform's #registry subscriptions into a *MaterializedPlatform performs registry I/O and stays an explicit, separate, caller-driven step (Principle I / design D14). The returned Package carries #registry as authored with #composedTransformers / #matchers unset.

The Kernel owns the schema cache; callers MUST NOT need to thread it through explicitly. If in.SchemaCache is set it is honored (a test may pin a different one), otherwise it defaults to the kernel-owned cache.

ctx is unused today — synthesis touches no I/O the caller could cancel (synth.Platform uses the Kernel's *cue.Context; NewPlatformFromValue takes none). It is part of the signature for parity with Kernel.SynthesizeInstance and so a future materialize-aware variant can honor cancellation without an API break. Keep it.

func (*Kernel) Validate 

func (k *Kernel) Validate(_ context.Context, in ValidateInput) error

Validate performs Tier-2 schema validation of ValidateInput.Values against the module's `#config` schema. It does NOT perform matching, execution, or finalization.

Returns nil on success. On failure the returned error wraps the raw CUE error tree with the module name as a `module %q:` prefix; callers can reach the underlying cuelang.org/go/cue/errors.Error tree via errors.As / cuelang.org/go/cue/errors.Errors for structured access.

func (*Kernel) ValidateConfig 

func (k *Kernel) ValidateConfig(schema cue.Value, values cue.Value) (cue.Value, error)

ValidateConfig is the kernel's primitive Tier-2 validation entry point. It unifies values with schema, runs the closed-schema disallowed-field walk, and asserts concreteness via cue.Concrete(true).

Returns the unified cue.Value on success and the zero value on failure. The returned error is the raw CUE error tree; walk it via cuelang.org/go/cue/errors.Errors / cuelang.org/go/cue/errors.Positions, or print it via cuelang.org/go/cue/errors.Print. Presentation is outside the kernel's contract — frontends own their own formatting.

values is a single, pre-merged cue.Value. Layered inputs flow through Kernel.ValidateConfigDetailed; partial-mode validation flows through Kernel.ValidateConfigPartial. Module-name framing is the caller's responsibility — wrap with fmt.Errorf if a context prefix is required.

The zero cue.Value is treated as "no values": ValidateConfig returns (zero, nil) without running any schema check.

func (*Kernel) ValidateConfigDetailed 

func (k *Kernel) ValidateConfigDetailed(schema cue.Value, sources []Source, opts ...ValidateOption) (cue.Value, error)

ValidateConfigDetailed unifies an ordered slice of Source values, then validates the merged value against schema. Per-source attribution flows through token.Pos.Filename, populated from cue.Filename(Origin) at the time each Source.Value was compiled — see Kernel.LoadSourceFromFile, Kernel.LoadSourceFromBytes, and Kernel.LoadSourceFromString for constructors that bake the filename for you.

Without options the merged value must be concrete (every required field set). With Partial in opts, concreteness is not enforced; the merged value is checked only for type errors, constraint violations, and disallowed fields under closed schemas.

Returns the merged cue.Value on success and the zero value on failure. The returned error is the raw CUE error tree; walk it via cuelang.org/go/cue/errors.Errors and cuelang.org/go/cue/errors.Positions, or print it via cuelang.org/go/cue/errors.Print. Presentation is outside the kernel's contract — frontends own their own formatting.

Empty sources, a zero schema, or a merged value that does not exist all short-circuit to (zero, nil) — the "no values supplied" path documented across the kernel's validation surface.

func (*Kernel) ValidateConfigPartial 

func (k *Kernel) ValidateConfigPartial(schema cue.Value, values cue.Value) (cue.Value, error)

ValidateConfigPartial validates partial values against schema without requiring every schema field to be concrete. It catches type errors, disallowed fields, and pattern/regex violations on fields that ARE set, but does NOT flag fields that are missing entirely.

Used for CLI lint subcommands, IDE/LSP live feedback, admission webhooks, and any callsite that intentionally validates a draft slice of the full configuration.

The zero cue.Value (no values) is treated as success.

func (*Kernel) ValidateInstanceValues 

func (k *Kernel) ValidateInstanceValues(r *module.Instance, values cue.Value) (cue.Value, error)

ValidateInstanceValues is a typed shortcut for Kernel.ValidateConfig(r.ConfigSchema(), values). It resolves the embedded source module's #config schema for the caller.

Was: ValidateReleaseValues

func (*Kernel) ValidateInstanceValuesDetailed 

func (k *Kernel) ValidateInstanceValuesDetailed(r *module.Instance, sources []Source, opts ...ValidateOption) (cue.Value, error)

ValidateInstanceValuesDetailed is the layered counterpart of Kernel.ValidateInstanceValues — see Kernel.ValidateConfigDetailed.

Was: ValidateReleaseValuesDetailed

func (*Kernel) ValidateInstanceValuesPartial 

func (k *Kernel) ValidateInstanceValuesPartial(r *module.Instance, values cue.Value) (cue.Value, error)

ValidateInstanceValuesPartial is the partial-mode counterpart of Kernel.ValidateInstanceValues.

Was: ValidateReleaseValuesPartial

func (*Kernel) ValidateModuleValues 

func (k *Kernel) ValidateModuleValues(m *module.Module, values cue.Value) (cue.Value, error)

ValidateModuleValues is a typed shortcut for Kernel.ValidateConfig(m.ConfigSchema(), values). It exists so callers holding a *module.Module reach the validation surface without looking up the #config schema themselves.

func (*Kernel) ValidateModuleValuesDetailed 

func (k *Kernel) ValidateModuleValuesDetailed(m *module.Module, sources []Source, opts ...ValidateOption) (cue.Value, error)

ValidateModuleValuesDetailed is the layered counterpart of Kernel.ValidateModuleValues — see Kernel.ValidateConfigDetailed.

func (*Kernel) ValidateModuleValuesPartial 

func (k *Kernel) ValidateModuleValuesPartial(m *module.Module, values cue.Value) (cue.Value, error)

ValidateModuleValuesPartial is the partial-mode counterpart of Kernel.ValidateModuleValues.

type MatchInput 

type MatchInput struct {
	// ModuleInstance supplies the components value via
	// [module.Instance.MatchComponents]. Required.
	ModuleInstance *module.Instance

	// Platform is the materialized platform whose #composedTransformers and
	// #matchers index drive the matcher. Required. Callers MUST Materialize a
	// *platform.Platform before invoking these phases.
	Platform *materialize.MaterializedPlatform
}

MatchInput is the input for Kernel.Match. The instance artifact is the sole module-side handle: the source module, when needed, is reachable via `ModuleInstance.Package` at the binding's `Paths().Module`.

type MatchPlan 

type MatchPlan = compile.MatchPlan

MatchPlan is the result of Kernel.Match.

type Option 

type Option func(*Kernel)

Option configures a Kernel at construction time. Options compose via the functional-options pattern; new options can be added in MINOR instances without breaking existing call sites.

func WithClock 

func WithClock(c Clock) Option

WithClock overrides the kernel's Clock. Use a fake clock in tests that need time pinned to a specific instant.

func WithLogger 

func WithLogger(l *slog.Logger) Option

WithLogger overrides the kernel's internal *slog.Logger. The logger is used for kernel-internal diagnostics only; it is intentionally not exposed back to callers.

func WithRegistry 

func WithRegistry(registry string) Option

WithRegistry sets the OCI registry mapping (CUE_REGISTRY syntax, e.g. "opmodel.dev=ghcr.io/open-platform-model") used for catalog resolution during Kernel.Materialize. The materialize flow uses the same mapping when it resolves opmodel.dev/core for the schema.

Omitting this option (or passing an empty string) inherits CUE_REGISTRY from the process environment; the kernel applies no built-in default registry — the same stance as the schema loader. The mapping is never written back to the process environment; it is plumbed into the load configuration for the operation only.

func WithSchemaLoader 

func WithSchemaLoader(l schema.Loader) Option

WithSchemaLoader configures the schema.Loader used to populate the kernel's *schema.Cache. Omitting this option defaults to a zero-value schema.OCILoader that resolves opmodel.dev/core@v2 via CUE_REGISTRY / CUE_CACHE_DIR from the process environment.

The Kernel wraps the supplied Loader in a fresh Cache; callers cannot inject a pre-built Cache. This guarantees one Kernel = one Cache, so no two Kernels accidentally share memoization. Multi-Kernel cache sharing is intentionally not exposed and may be added later as a non-breaking addition.

A nil Loader is ignored (the default OCILoader applies).

func WithTracer 

func WithTracer(t trace.Tracer) Option

WithTracer overrides the kernel's internal OpenTelemetry trace.Tracer. The tracer is used to emit spans for kernel operations once those slices land; in this slice it is a passive slot.

type PlanInput 

type PlanInput struct {
	// ModuleInstance supplies instance-level metadata and components.
	// Required.
	ModuleInstance *module.Instance

	// Values is the user-supplied values cue.Value to validate. Optional;
	// the zero cue.Value skips validation.
	Values cue.Value

	// Platform is the materialized platform whose #composedTransformers and
	// #matchers index drive the matcher. Required. Callers MUST Materialize a
	// *platform.Platform before invoking these phases.
	Platform *materialize.MaterializedPlatform

	// RuntimeName identifies the runtime executing this plan (e.g.
	// "opm-cli", "opm-controller"). MUST be non-empty.
	RuntimeName string
}

PlanInput is the input for Kernel.Plan. The instance artifact is the sole module-side handle: the `#config` schema and module-level metadata are reachable via `ModuleInstance.ConfigSchema()` and the binding's `Paths().ModuleMetadata`.

type PlanResult 

type PlanResult struct {
	// MatchPlan is the raw match outcome, exposed so callers can inspect
	// per-(component, transformer) details without re-running Match.
	MatchPlan *MatchPlan

	// Components is the per-component summary, sorted by name.
	Components []compile.ComponentSummary

	// Unmatched is the list of component FQNs with no matching transformer.
	Unmatched []string

	// Warnings is a list of human-readable advisory messages (e.g.
	// unhandled traits). A non-empty Warnings slice does NOT indicate
	// failure.
	Warnings []string
}

PlanResult is the result of Kernel.Plan.

type Source 

type Source struct {
	// Value is the raw values payload for this source.
	//
	// Value MUST have been compiled with [cue.Filename](Origin) for
	// per-source attribution to flow into errors. Use one of
	// [Kernel.LoadSourceFromFile], [Kernel.LoadSourceFromBytes], or
	// [Kernel.LoadSourceFromString] to construct a Source whose Value
	// satisfies this contract automatically. Hand-built Sources MUST set
	// the filename themselves when compiling.
	Value cue.Value

	// Name is the human-friendly label shown in UI. Examples:
	// "user values", "ConfigMap/foo", "instance overlay".
	Name string

	// Origin is the stable identifier for machine-readable correlation
	// (file path, K8s object reference, composition input key). It MUST
	// match the [cue.Filename] used when Value was compiled, so error
	// positions report Origin via [token.Pos.Filename].
	Origin string
}

Source is one labeled values input for Kernel.ValidateConfigDetailed.

A Source pairs a values payload with caller-supplied identity so that per-position diagnostics flowing out of CUE error trees carry the originating source's filename. The library does not invent a Go-typed wrapper around CUE's error attribution — instead, it relies on token.Pos.Filename, populated from cue.Filename at compile time.

type ValidateInput 

type ValidateInput struct {
	// Module supplies the `#config` schema via its Package. Required.
	Module *module.Module

	// ModuleInstance provides the instance context (name, namespace) used
	// in diagnostic messages. Required.
	ModuleInstance *module.Instance

	// Values is the user-supplied values cue.Value to validate. The zero
	// cue.Value is treated as "no values" and Validate returns nil without
	// running schema checks.
	Values cue.Value
}

ValidateInput is the input for Kernel.Validate.

type ValidateOption 

type ValidateOption func(*validateConfig)

ValidateOption configures Kernel.ValidateConfigDetailed. Options compose via the functional-options pattern; new options can be added in MINOR instances without breaking existing call sites.

The type is named ValidateOption (rather than the more terse Option) to avoid collision with Option, the kernel-construction option type.

func Partial 

func Partial() ValidateOption

Partial returns a ValidateOption that skips the concreteness check on the merged value passed to Kernel.ValidateConfigDetailed.

With Partial: type errors, constraint violations on fields that ARE set, and disallowed-field errors (under closed schemas) all still surface. Missing required fields do NOT surface — concrete validation is the only pass that flags them, and Partial disables it.

Use Partial for callers that intentionally validate incomplete drafts: CLI lint subcommands, IDE/LSP live feedback, admission webhooks that see only one of several values sources.

Source Files

View all Source files

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.