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 ¶
- Variables
- func CanonicalizeRawBlueprint(data []byte) ([]byte, error)
- func NormalizeDNSLabel(s string) string
- func ParseBlueprintMeta(data []byte) (name, description, template string, isTemplate bool, err error)
- type BlueprintManager
- func (bm *BlueprintManager) Compose(customBlueprint *models.CustomBlueprint, org string) (interface{}, error)
- func (bm *BlueprintManager) ComposeRaw(customBlueprint *models.CustomBlueprint, org string) (*RawBlueprint, error)
- func (bm *BlueprintManager) ComposeWithScope(customBlueprint *models.CustomBlueprint, scope *BlueprintScope) (*models.Blueprint, string, error)
- func (bm *BlueprintManager) GetAllBlueprints(scope *BlueprintScope) (map[string]*models.Blueprint, error)
- func (bm *BlueprintManager) GetBlueprint(name string, scope *BlueprintScope) (*models.Blueprint, error)
- func (bm *BlueprintManager) GetBlueprintChain(org, name string) []string
- func (bm *BlueprintManager) GetBlueprintRevision(org, name string) string
- func (bm *BlueprintManager) GetBlueprintTemplate(org, name string) (string, error)
- func (bm *BlueprintManager) GetBlueprintsSummary() ([]*models.BlueprintSummary, error)
- func (bm *BlueprintManager) GetDefaultUserBlueprint(user *models.User) (string, error)
- func (bm *BlueprintManager) GetRawBlueprint(name string) (interface{}, error)
- func (bm *BlueprintManager) GetRawBlueprintOwn(name string) (interface{}, error)
- func (bm *BlueprintManager) GetRawBlueprintScoped(org, name string) (merged, own interface{}, template, revision string, err error)
- func (bm *BlueprintManager) HasGlobalBlueprint(name string) bool
- func (bm *BlueprintManager) ListBlueprintNames() []string
- func (bm *BlueprintManager) OrgBlueprintRevision(ob *models.OrgBlueprint) (string, error)
- func (bm *BlueprintManager) QueryBlueprints(payload *queryv1.Payload) ([]*models.BlueprintSummary, error)
- func (bm *BlueprintManager) ReloadOrgBlueprints() error
- func (bm *BlueprintManager) ValidateRawBlueprint(data []byte) ([]ValidationIssue, interface{}, error)
- func (bm *BlueprintManager) ValidateRawBlueprintForOrg(org string, data []byte) ([]ValidationIssue, interface{}, error)
- type BlueprintScope
- type LoadOptions
- type MergeStrategies
- type OrgBlueprintStore
- type RawBlueprint
- type ValidationIssue
- type Watcher
Constants ¶
This section is empty.
Variables ¶
var BlueprintsQueryDescriptor = query.NewDescriptor("blueprints"). Field("name", queryv1.FieldType_FIELD_TYPE_STRING, queryv1.Operator_OPERATOR_EQ, queryv1.Operator_OPERATOR_NE, queryv1.Operator_OPERATOR_IN). Field("org", queryv1.FieldType_FIELD_TYPE_STRING, queryv1.Operator_OPERATOR_EQ, queryv1.Operator_OPERATOR_NE, queryv1.Operator_OPERATOR_IN). Field("global", queryv1.FieldType_FIELD_TYPE_BOOLEAN, queryv1.Operator_OPERATOR_EQ, queryv1.Operator_OPERATOR_NE). Field("created", queryv1.FieldType_FIELD_TYPE_DATETIME, queryv1.Operator_OPERATOR_EQ, queryv1.Operator_OPERATOR_NE, queryv1.Operator_OPERATOR_GT, queryv1.Operator_OPERATOR_GTE, queryv1.Operator_OPERATOR_LT, queryv1.Operator_OPERATOR_LTE). Field("updated", queryv1.FieldType_FIELD_TYPE_DATETIME, queryv1.Operator_OPERATOR_EQ, queryv1.Operator_OPERATOR_NE, queryv1.Operator_OPERATOR_GT, queryv1.Operator_OPERATOR_GTE, queryv1.Operator_OPERATOR_LT, queryv1.Operator_OPERATOR_LTE). Field("revision", queryv1.FieldType_FIELD_TYPE_STRING, queryv1.Operator_OPERATOR_EQ, queryv1.Operator_OPERATOR_NE, queryv1.Operator_OPERATOR_IN, queryv1.Operator_OPERATOR_EXISTS). DefaultSort("name", queryv1.SortDir_SORT_DIR_ASC). Build()
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.
var ErrBlueprintNotFound = errors.New("blueprint not found")
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
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 ¶
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.
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
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 ¶
NewWatcher constructs a watcher. Call w.Setup() to start.