Documentation
¶
Overview ¶
Package loader is the kernel's one artifact-loading routine: it builds a single CUE package — from a directory or from an in-memory overlay — and runs the OPM artifact shape gate over the result, and it fetches a published #Module from an OCI registry through CUE's native module machinery.
The gate is the acquisition boundary's fast-fail structural check: it confirms an artifact carries the right concrete kind and the identity fields the schema never defaults, but deliberately stops short of full schema validation, which is the kernel's contract. "Concrete" is judged before default finalization: an identity field authored as a defaulted disjunction is refused, with the default named in the error. Single-sourcing the build and the gate here guarantees a directory-loaded artifact and a registry-loaded artifact are evaluated, gated and error-wrapped identically; the only difference between the entry points is where the package files come from.
It lives under opm/internal/ so it stays off the library's public SemVer surface (Principle VI, VII) while remaining importable by opm/kernel and the kernel's other internals. The sentinels it wraps are declared in opm/errors, the package a frontend can reach for errors.Is.
The package does not import opm/internal/synth: synthesis builds THROUGH LoadDir, never the other way round.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ModuleSpec = ArtifactSpec{ Label: "module", ExpectedKind: "Module", RequiredConcreteFields: []string{"metadata.name", "metadata.modulePath", "metadata.version"}, } InstanceSpec = ArtifactSpec{ Label: "instance", ExpectedKind: "ModuleInstance", RequiredConcreteFields: []string{"metadata.name", "metadata.namespace"}, ModuleRefs: []ModuleRef{{Path: "#module"}}, } // #Platform.#registry carries path-keyed #CatalogEntry values, each // embedding its catalog by import (enhancement 0019 D5). Core derives the // entry's `version` from the embedded catalog's stamped metadata, so an // entry that names no catalog (the retired subscription shape: a // `version` scalar and nothing else) is refused here as a missing // required field naming the entry. #registry is a definition, so no // root-level validation reaches it; the gate walks it explicitly. PlatformSpec = ArtifactSpec{ Label: "platform", ExpectedKind: "Platform", RequiredConcreteFields: []string{"metadata.name", "type"}, CompleteEntryMaps: []string{"#registry"}, } )
ModuleSpec, InstanceSpec, and PlatformSpec are the shape-gate definitions for the three artifacts the kernel acquires. The required field lists carry only the identity fields the schema never defaults — fields the schema fills in (or leaves as open `_`) are out of scope here and validated by the kernel.
Functions ¶
func FetchModule ¶
func FetchModule(ctx context.Context, cueCtx *cue.Context, modPath, version string, env []string) (cue.Value, *opmmodule.Source, error)
FetchModule loads a #Module published in an OCI registry, identified by its major-qualified module path (e.g. "example.com/modules/hello@v0") and version (e.g. "v0.0.2"), and returns the value built in cueCtx together with the staged source tree the build used, as the artifact opmmodule.Source in overlay mode: the deterministic synthetic Root every overlay key sits under, plus the Overlay carrying the module's .cue files (its own cue.mod/module.cue included, nothing else: the set cue/load reads). A consumer reuses it to build a follow-on package INSIDE the module's own main module — letting the module's already-tidied cue.mod/module.cue drive transitive resolution — without a second registry fetch (Principle V, CUE-native resolution). The returned Overlay is the build's own map; callers that mutate it (e.g. to overlay additional files) MUST clone it first.
It fetches the module's source via CUE's native module machinery (mod/modconfig) and loads it IN MEMORY AS THE MAIN MODULE: the fetched files are injected through load.Config.Overlay under a deterministic synthetic root, so the module's own cue.mod/module.cue drives transitive dependency resolution and its kind/metadata are evaluated at the package root. No wrapper package is synthesized and no temporary directory is written.
The built value is validated with the same module shape gate LoadDir runs for a directory (concrete kind == "Module"; concrete metadata.name, metadata.modulePath, metadata.version), wrapping the shared ErrInvalidPackage / ErrWrongKind / ErrMissingRequiredField sentinels, so a directory-acquired and a registry-acquired module fail identically. It does NOT perform full schema validation, which remains the kernel's contract.
env is the environment slice the fetch resolver and the load both consult — the kernel's CUE_REGISTRY mapping via [cueenv.Override], nil to read the process environment unchanged. The process environment is never mutated. Parse failures on caller input are wrapped rather than panicked.
func LoadDir ¶
func LoadDir(ctx *cue.Context, root, pkg string, overlay map[string][]byte, env []string, spec ArtifactSpec) (cue.Value, error)
LoadDir is the kernel's one evaluate-and-shape-gate step. It builds exactly one CUE package — pkg, relative to the module root at root — in ctx and runs the artifact shape gate described by spec over the result. The two source modes are selected by overlay:
- overlay == nil → on-disk package: load.Config.Dir is root and the files are read from the filesystem. root must exist and be a directory.
- overlay != nil → in-memory package: the overlay supplies the .cue files under root (its cue.mod/module.cue included; the set cue/load reads) and root doubles as the module root, so the staged cue.mod/module.cue drives transitive dependency resolution. This is how a registry-fetched module, a values-layered instance package and a synthesized instance package are all built.
pkg is a package path relative to root ("." or "" for the root package, "./sub" for a subdirectory). env, when non-nil, is the environment slice load.Config consults — the CUE_REGISTRY override the kernel plumbs through [cueenv.Override], never os.Setenv, so LoadDir is safe under concurrency.
Keeping this routine single-sourced guarantees an overlay-built artifact and an on-disk artifact are evaluated, shape-gated and error-wrapped identically: the only difference between the acquire verbs is where the package files come from.
Types ¶
type ArtifactSpec ¶
type ArtifactSpec struct {
Label string
ExpectedKind string
RequiredConcreteFields []string
ModuleRefs []ModuleRef
// CompleteEntryMaps lists paths to maps whose every entry must be
// complete: each regular field of each entry validates under
// cue.Concrete(true). An absent map passes. Used for #Platform.#registry,
// where core derives an entry's `version` from the catalog the entry
// embeds (enhancement 0019 D5), so an entry with no embedded catalog is
// incomplete exactly where the catalog would have completed it.
CompleteEntryMaps []string
}
ArtifactSpec describes the shape gate for one artifact type. ExpectedKind is the concrete kind literal the package must carry; RequiredConcreteFields are dotted paths to scalar identity fields that must be present and concrete; ModuleRefs point at embedded #Module values whose kind must in turn be "Module". Label names the artifact in filesystem-level error messages.
Source Files