blueprint

package
v0.17.6 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 32 Imported by: 0

Documentation

Overview

Package blueprint loads, validates, and evaluates workspace blueprint definitions. Blueprints are YAML documents that describe how a k8shell workspace pod should be configured. They support CEL template expressions, template inheritance (parent/child overriding), and hot-reloading via a filesystem watcher so changes take effect without restarting the server.

Index

Constants

This section is empty.

Variables

BlueprintsQueryDescriptor advertises which blueprint fields are queryable/sortable via QueryBlueprints, and which operators are valid on each. It is served as-is by a GetBlueprintsQuerySchema RPC and reused by QueryBlueprints to validate incoming payloads, so the advertised schema and its enforcement can never drift apart.

View Source
var ErrBlueprintNotFound = errors.New("blueprint not found")
View Source
var RequireDescription = false

RequireDescription controls whether validateDescriptionRequired rejects a blueprint with an empty or missing description. Disabled by default, so blueprints without one are allowed for now; flip to true once every blueprint in use has been given one. Description is never inherited from a Template regardless of this switch — see the "description" exclusion in mergeYAMLNodesWithTags (resolve.go).

Functions

func CanonicalizeRawBlueprint added in v0.16.0

func CanonicalizeRawBlueprint(data []byte) ([]byte, error)

CanonicalizeRawBlueprint re-serializes a raw blueprint YAML document so that every CEL expression is stored as a real `!cel`-tagged node rather than a plain string carrying a "!cel:" or "!cel " prefix (the forms a fetch/edit round-trip or a naive marshaller can leave behind). The document structure, key order and comments are otherwise preserved. Callers persisting a blueprint (e.g. CreateBlueprint/UpdateBlueprint) should store the result of this instead of the bytes they received, so the database always holds a document that evaluates correctly when loaded.

func NormalizeDNSLabel

func NormalizeDNSLabel(s string) string

NormalizeDNSLabel normalizes a string to be a valid DNS label / Helm release name: lowercase alphanumeric and hyphens, must start and end with alphanumeric, max 53 chars.

func ParseBlueprintMeta added in v0.16.0

func ParseBlueprintMeta(data []byte) (name, description, template string, isTemplate bool, err error)

ParseBlueprintMeta reads the identifying metadata — name, description, parent template and isTemplate — from a raw blueprint YAML document, applying the same top-level `blueprint:` unwrapping rule the loader uses. It does not validate the document (callers do that separately via ValidateRawBlueprint); it only extracts the fields the database row is keyed and filtered by.

Types

type BlueprintManager

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

BlueprintManager manages blueprints with lazy CEL evaluation.

func NewBlueprintManager

func NewBlueprintManager(opts LoadOptions) (*BlueprintManager, error)

NewBlueprintManager creates a new blueprint manager.

func (*BlueprintManager) Compose

func (bm *BlueprintManager) Compose(customBlueprint *models.CustomBlueprint, org string) (interface{}, error)

Compose merges a custom blueprint with its template and returns the result as a plain Go value (map/slice/scalar) ready for JSON or YAML serialisation. CEL expressions in the merged output are prefixed with "!cel:" for display.

func (*BlueprintManager) ComposeRaw

func (bm *BlueprintManager) ComposeRaw(customBlueprint *models.CustomBlueprint, org string) (*RawBlueprint, error)

Compose creates a new blueprint by merging a custom blueprint YAML with an existing template. org scopes the template lookup: an org-scoped template of that org shadows a global/file-based template of the same name, mirroring GetBlueprint.

func (*BlueprintManager) ComposeWithScope

func (bm *BlueprintManager) ComposeWithScope(customBlueprint *models.CustomBlueprint,
	scope *BlueprintScope) (*models.Blueprint, string, error)

ComposeWithScope merges a custom blueprint with its template, evaluates all CEL expressions using scope, decodes the result into a models.Blueprint, and validates it. It is the end-to-end path for provisioning with a custom blueprint. The returned revision is the content revision of the composed (unevaluated) blueprint, see RawBlueprint.Revision.

func (*BlueprintManager) GetAllBlueprints

func (bm *BlueprintManager) GetAllBlueprints(scope *BlueprintScope) (map[string]*models.Blueprint, error)

GetAllBlueprints evaluates all blueprints with the given scope.

func (*BlueprintManager) GetBlueprint

func (bm *BlueprintManager) GetBlueprint(name string, scope *BlueprintScope) (*models.Blueprint, error)

GetBlueprint evaluates CEL expressions for a specific blueprint with given scope.

func (*BlueprintManager) GetBlueprintChain

func (bm *BlueprintManager) GetBlueprintChain(org, name string) []string

GetBlueprintChain returns the inheritance chain for the given blueprint name, scoped by org the same way GetBlueprint is: an org-scoped blueprint of that org takes precedence over a global/file-based one of the same name. The chain is an ordered slice from the root ancestor to the blueprint itself, e.g. ["base", "git-dev", "dev"]. Returns nil if the blueprint is not found.

func (*BlueprintManager) GetBlueprintRevision added in v0.17.1

func (bm *BlueprintManager) GetBlueprintRevision(org, name string) string

GetBlueprintRevision returns the content revision of the given blueprint (see RawBlueprint.Revision), scoped by org the same way GetBlueprint is. Returns "" if the blueprint is not found.

func (*BlueprintManager) GetBlueprintTemplate added in v0.16.0

func (bm *BlueprintManager) GetBlueprintTemplate(org, name string) (string, error)

GetBlueprintTemplate returns the name of the immediate parent Template for the given blueprint name, or "" if it does not inherit from one. org scopes the lookup the same way GetBlueprint does. Returns ErrBlueprintNotFound if name is not a registered blueprint.

func (*BlueprintManager) GetBlueprintsSummary

func (bm *BlueprintManager) GetBlueprintsSummary() ([]*models.BlueprintSummary, error)

GetBlueprintsSummary returns a summary of every registered blueprint without evaluating CEL expressions: the file-based, global blueprints from the in-memory cache plus every org-scoped database blueprint read fresh from the backing store, so a row created or deleted out of band shows up immediately. Org names the organization an org-scoped blueprint belongs to (empty for a global one), IsGlobal is its inverse, and Template names the immediate parent template, if any.

func (*BlueprintManager) GetDefaultUserBlueprint

func (bm *BlueprintManager) GetDefaultUserBlueprint(user *models.User) (string, error)

GetDefaultUserBlueprint returns the name of the first non-template blueprint (in alphabetical order) that the user is authorised to use. It is used when no blueprint is specified explicitly in the userstr.

func (*BlueprintManager) GetRawBlueprint

func (bm *BlueprintManager) GetRawBlueprint(name string) (interface{}, error)

GetRawBlueprint returns the raw (unevaluated) YAML content of the named blueprint, fully merged with any inherited Template content. CEL expressions are returned with a "!cel:" prefix so callers can display the template source without triggering evaluation.

func (*BlueprintManager) GetRawBlueprintOwn added in v0.16.0

func (bm *BlueprintManager) GetRawBlueprintOwn(name string) (interface{}, error)

GetRawBlueprintOwn returns the raw (unevaluated) YAML content defined directly on the named blueprint, excluding any content inherited from its Template. A field present in GetRawBlueprint's output but absent here is inherited rather than set on this blueprint. CEL expressions are returned with a "!cel:" prefix, as in GetRawBlueprint.

func (*BlueprintManager) GetRawBlueprintScoped added in v0.16.0

func (bm *BlueprintManager) GetRawBlueprintScoped(org, name string) (merged, own interface{}, template, revision string, err error)

GetRawBlueprintScoped resolves name the same way GetRawBlueprint does, but when org is set it serves the org-scoped blueprint straight from the backing store (so a row changed or deleted out of band is reflected immediately), falling back to the file-based/global blueprint when org is empty or has no such row. It returns the fully merged content, the content defined directly on the blueprint (own), and the name of the immediate parent template, if any. CEL expressions are returned with a "!cel:" prefix, as in GetRawBlueprint.

func (*BlueprintManager) HasGlobalBlueprint added in v0.16.0

func (bm *BlueprintManager) HasGlobalBlueprint(name string) bool

HasGlobalBlueprint reports whether a file-based, global blueprint (template or not) named name is currently registered. Org-scoped database blueprints are not considered. Used to stop an org blueprint from being created under a name that a global blueprint already owns, which it would otherwise silently shadow for that org.

func (*BlueprintManager) ListBlueprintNames

func (bm *BlueprintManager) ListBlueprintNames() []string

ListBlueprintNames returns all available file-based, global blueprint names. Org-scoped database blueprints are excluded (see GetBlueprintsSummary).

func (*BlueprintManager) OrgBlueprintRevision added in v0.17.1

func (bm *BlueprintManager) OrgBlueprintRevision(ob *models.OrgBlueprint) (string, error)

OrgBlueprintRevision returns the revision ob would have once resolved against its template (see RawBlueprint.Revision), without registering it. Callers must NOT hold bm.mu.

func (*BlueprintManager) QueryBlueprints added in v0.16.0

func (bm *BlueprintManager) QueryBlueprints(payload *queryv1.Payload) ([]*models.BlueprintSummary, error)

QueryBlueprints returns a summary of every blueprint matching payload, as validated against BlueprintsQueryDescriptor and, independent of payload's own Filters, restricted to whatever payload.Obligations mandates (see blueprintObligationScope). It draws from the same backend-agnostic source as GetBlueprintsSummary — the in-memory file-based blueprints plus every org-scoped database blueprint, read fresh from the store — so a query is transparent to where a matched blueprint is actually stored, and applies payload's filters/sort/page over that merged set in memory.

func (*BlueprintManager) ReloadOrgBlueprints added in v0.16.0

func (bm *BlueprintManager) ReloadOrgBlueprints() error

ReloadOrgBlueprints refreshes the manager's merged file-plus-database view after an org blueprint is created, updated, or deleted, so the change is immediately visible to GetBlueprint. It reruns the full load pipeline (the same one a file watcher-triggered reload uses), since org and file-based blueprints share the same inheritance resolution and validation pass.

func (*BlueprintManager) ValidateRawBlueprint added in v0.16.0

func (bm *BlueprintManager) ValidateRawBlueprint(data []byte) ([]ValidationIssue, interface{}, error)

ValidateRawBlueprint validates a standalone blueprint YAML document without registering it in the manager. If the document references an existing template via `template:`, that template's already-resolved definition is merged in exactly as it would be for a blueprint loaded from disk.

The second return value is the raw (unevaluated) result of that merge — the same shape GetRawBlueprint returns for an already-registered blueprint, but for this standalone document — so an editor can preview the full inherited blueprint as the "own" fields are added, changed, or removed. It is only populated when the submission is valid (the first return value is empty): a caller should fix the reported issues first rather than being handed a preview built from an invalid document.

func (*BlueprintManager) ValidateRawBlueprintForOrg added in v0.16.0

func (bm *BlueprintManager) ValidateRawBlueprintForOrg(org string, data []byte) ([]ValidationIssue, interface{}, error)

ValidateRawBlueprintForOrg behaves like ValidateRawBlueprint but resolves a `template:` reference the way a stored org blueprint of org would: an org-scoped template of that name in org shadows a global template of the same name (see resolveTemplateParent). Pass org == "" for the plain, global-only behaviour.

type BlueprintScope

type BlueprintScope struct {
	User          *models.User              `yaml:"user"`
	WorkspaceName string                    `yaml:"workspaceName"`
	Metadata      *models.BlueprintMetadata `yaml:"metadata"`
}

BlueprintScope holds the runtime context passed to CEL template evaluation. It carries the authenticated user, the target workspace name, and blueprint metadata (repo coordinates, resolved blueprint name) so templates can conditionally configure resources per-user or per-repository.

func TestScope

func TestScope() *BlueprintScope

TestScope creates a minimal BlueprintScope for testing purposes.

func (*BlueprintScope) ToMap

func (bs *BlueprintScope) ToMap() (map[string]any, error)

ToMap serialises the scope to a plain map[string]any for CEL evaluation.

type LoadOptions

type LoadOptions struct {
	Dir         string
	Strategies  MergeStrategies
	EnableWatch bool

	// OrgStore, when set, supplies org-scoped blueprint definitions from the
	// database that are merged with the file-based blueprints loaded from
	// Dir. Nil disables org blueprint support entirely.
	OrgStore OrgBlueprintStore
}

LoadOptions contains configuration for loading blueprints.

type MergeStrategies

type MergeStrategies map[string]func(dst, src []interface{}) []interface{}

MergeStrategies allow custom list merging strategies per dotted path.

type OrgBlueprintStore added in v0.16.0

type OrgBlueprintStore interface {
	// ListAllBlueprints returns every org blueprint across every org. Called
	// on every (re)load, mirroring how loadRawBlueprints re-walks the file
	// tree on every reload.
	ListAllBlueprints() ([]*models.OrgBlueprint, error)
	// LookupBlueprint returns the org blueprint identified by (org, name), or
	// (nil, nil) when no such row exists. Used to serve org-scoped blueprints
	// straight from the database on every RPC, so a row created, changed or
	// deleted out of band is reflected without waiting for a full reload.
	LookupBlueprint(org, name string) (*models.OrgBlueprint, error)
}

OrgBlueprintStore supplies org-scoped blueprint definitions persisted in the database. An org-scoped lookup is served from the store on every RPC (see lookupOrgFromStore); an org blueprint takes precedence over a file-based blueprint of the same name for a user belonging to that org, while every other org sees only the file-based one. The file-based blueprints loaded from disk stay served from the in-memory cache.

type RawBlueprint

type RawBlueprint struct {
	Name             string
	Description      string
	Template         string
	IsTemplate       bool
	SourceFile       string
	Node             *yaml.Node // fully merged (own + inherited) content
	OwnNode          *yaml.Node // content defined directly on this blueprint, before merging with Template
	InheritanceChain []string   // ordered list of blueprint names from root ancestor to this blueprint

	// Revision is a short content hash of Node (see computeRevision). Since
	// Node includes everything inherited from the template chain, a change
	// to any ancestor that alters this blueprint's effective content also
	// changes its Revision.
	Revision string

	// CreatedAt and UpdatedAt record when the blueprint was first registered
	// and last changed. For a file-based blueprint both are set to the source
	// file's last-modified time (a file carries no separate creation record);
	// for an org blueprint loaded via OrgBlueprintStore they are the database
	// row's timestamps.
	CreatedAt time.Time
	UpdatedAt time.Time

	// Org is non-empty for a blueprint loaded from the database via
	// OrgBlueprintStore (see orgstore.go), naming the organization it is
	// scoped to. Empty for a file-based blueprint. An org blueprint is keyed
	// in BlueprintManager.rawBlueprints under orgBlueprintKey(Org, Name)
	// rather than its bare Name, so it can coexist with a file-based
	// blueprint of the same name.
	Org string
}

RawBlueprint represents an unprocessed blueprint with CEL expressions intact.

type ValidationIssue added in v0.16.0

type ValidationIssue struct {
	Line    int
	Column  int
	Field   string
	Message string
}

ValidationIssue is a single problem found while validating a raw blueprint YAML document. Line and Column are 1-indexed positions in the submitted YAML; both are 0 when the underlying check does not report a position (e.g. semantic checks that operate on the decoded blueprint rather than the YAML source).

type Watcher

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

Watcher watches a directory tree for YAML changes and calls onReload() debounced.

func NewWatcher

func NewWatcher(watchDir string, reloadDelay time.Duration, onReload func() error) *Watcher

NewWatcher constructs a watcher. Call w.Setup() to start.

func (*Watcher) Close

func (w *Watcher) Close() error

Close stops the watcher, cancels any pending reload timer, and waits for in-flight reload callbacks to finish before returning.

func (*Watcher) Setup

func (w *Watcher) Setup() error

Setup initializes fsnotify and starts the event loop.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL