Documentation
¶
Overview ¶
Package synth builds OPM artifact CUE values from in-memory typed inputs by unifying caller-supplied identity (name, namespace, module reference, values, labels, annotations) against the schema definition resolved through the caller-supplied *schema.Cache.
Synth is a peer of opm/helper/loader, not a subpackage of it. The loader tree (opm/helper/loader/file, opm/helper/loader/bytes) reads existing artifact bytes from a source — filesystem or byte buffer. Synthesis is creation from typed inputs: there is no file to parse, no bytes to decode. Co-locating synth under loader would conflate verbs and force every reader to ignore the package doc when interpreting the package path. Keeping them as peers makes each verb legible at a glance.
Recommended entry point: (*kernel.Kernel).SynthesizeRelease. It chains synth.Release into Kernel.ProcessModuleRelease so a caller building a release from typed inputs gets a fully validated, concrete *module.Release in one call. Call synth.Release directly only when there is no *Kernel on hand (rare; mostly unit-testing transformer behaviour in tight loops).
Schema source of truth: synth.Release never reimplements derivations the CUE schema already owns (UUID stamping, components fan-out from #components, auto-secrets injection, standard label stamping). Every derived field flows through unification with the #ModuleRelease definition obtained from in.SchemaCache.Get(ctx); the schema package itself is resolved by the Cache's underlying Loader (typically schema.OCILoader against CUE_REGISTRY).
Boundary scope: synth helpers live under opm/helper/ because they are opinionated frontend conveniences. Frontends MAY bypass them and unify against the schema themselves; nothing in synth is part of the kernel contract.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrMissingModule is returned when ReleaseInput.Module is nil. ErrMissingModule = errors.New("synth.Release: Module is required") // ErrMissingName is returned when ReleaseInput.Name is empty. ErrMissingName = errors.New("synth.Release: Name is required") // ErrMissingNamespace is returned when ReleaseInput.Namespace is empty. ErrMissingNamespace = errors.New("synth.Release: Namespace is required") // ErrMissingSchemaCache is returned when ReleaseInput.SchemaCache is // nil. Callers typically pass kernel.SchemaCache() from their Kernel. ErrMissingSchemaCache = errors.New("synth.Release: SchemaCache is required") // SchemaCache resolves but does not expose #ModuleRelease. ErrSchemaUnavailable = errors.New("synth.Release: schema unavailable") )
Sentinel errors. Frontends inspecting the failure surface match on these via errors.Is. Synthesis-time errors all wrap one of these so callers can distinguish "you forgot a required field" from "the schema is broken."
Functions ¶
func Release ¶
Release builds a #ModuleRelease CUE value by unifying ReleaseInput against the #ModuleRelease definition obtained from the caller-supplied SchemaCache.
The function does NOT validate values against #config and does NOT enforce concreteness. Both responsibilities live downstream in Kernel.ProcessModuleRelease, which the Kernel.SynthesizeRelease wrapper chains onto this call. See package doc for the recommended entry point.
The returned cue.Value carries every schema-derived field automatically: metadata.uuid is computed by uuid.SHA1, components is fanned from the unified module, opm-secrets is added when #Secret instances are present, and the standard module-release.opmodel.dev/{name,uuid} labels are stamped. Release stamps only the caller-supplied fields and lets CUE derive the rest.
Types ¶
type ReleaseInput ¶
type ReleaseInput struct {
// Module is the source #Module the release deploys. Required.
Module *module.Module
// Name is the release name (metadata.name). Required. Must satisfy the
// schema's #NameType regex; violations surface as a CUE unification error
// from Release.
Name string
// Namespace is the target namespace (metadata.namespace). Required.
Namespace string
// SchemaCache supplies the OPM core schema used to unify against
// #ModuleRelease. REQUIRED. Typically the value of
// kernel.SchemaCache() from the caller's Kernel — passing the
// kernel's cache preserves the one-Cache-per-process invariant and
// avoids a duplicate schema fetch. Release returns an error when
// this field is nil.
SchemaCache *schema.Cache
// Values is the caller-supplied configuration value unified against the
// module's #config. The zero cue.Value signals "no values supplied" — the
// schema's values path is left unfilled and concreteness is enforced
// downstream by Kernel.ProcessModuleRelease. Release NEVER falls back to
// Module.debugValues; that is a frontend policy concern.
Values cue.Value
// Labels and Annotations layer over the schema's stamped
// module-release.opmodel.dev/{name,uuid} labels. CUE unification merges
// caller-supplied entries with schema-stamped ones; caller-supplied keys
// MUST NOT collide with the schema's reserved keys.
Labels map[string]string
Annotations map[string]string
}
ReleaseInput is the typed input carried into Release. Required fields: Module, Name, Namespace, SchemaCache. Optional fields are filled into the release only when present (non-nil / non-empty / non-zero); empty values do not displace schema-derived fields.
Source Files