README
¶
pkg/controller/helpers
Shared utility for constructing a template engine from a *config.Config.
Overview
Several code paths need to build a template engine from the controller's loaded config: the reconciliation wiring (pkg/controller/reconciliation.go), the webhook wiring (pkg/controller/webhook.go), the template validator (pkg/controller/validator/template.go), the CRD admission webhook (pkg/controller/webhook/configvalidator.go), and the haptic-controller validate CLI command. This package consolidates the construction so a change to template-extraction or filter-registration policy lands in one place.
This is a utility package — pure functions, no event-bus dependency, no goroutines.
Quick Start
import "gitlab.com/haproxy-haptic/haptic/pkg/controller/helpers"
// Default — Scriggo engine, all standard filters auto-registered, fail()
// auto-registered, post-processors auto-extracted from cfg.
engine, err := helpers.NewEngineFromConfig(cfg, nil, nil)
// Full-featured: pass custom filters / globals / post-processor overrides,
// add domain-specific Scriggo type declarations, enable include profiling.
engine, err = helpers.NewEngineFromConfigWithOptions(
cfg,
customGlobals,
nil, // nil → auto-extract from cfg
map[string]any{"someType": (*someType)(nil)}, // additional Scriggo declarations
helpers.EngineOptions{EnableProfiling: true},
)
The standard filter set (sort_by, glob_match, b64decode, strip, trim, debug) and the fail() function are registered inside the engine itself — pass nil for the corresponding parameters unless you have additional custom filters or globals.
ExtractTemplatesFromConfig
Used when a caller needs the list of templates without instantiating an engine — e.g. for logging the template count at startup, or for tooling that inspects the loaded config:
extraction := helpers.ExtractTemplatesFromConfig(cfg)
// extraction.AllTemplates → map[string]string for the engine's filesystem
// extraction.EntryPoints → []string of explicitly-compiled templates
For Scriggo with inherit_context, only entry points are compiled explicitly; snippets are compiled on demand when referenced via render / render_glob.
See Also
pkg/templating— the engine this helper constructspkg/controller/reconciliation.go/webhook.go/validator/template.go— the main production callerspkg/controller/helpers/CLAUDE.md— design notes (why all filters live inside the engine, etc.)
License
Apache-2.0 — see root LICENSE.
Documentation
¶
Overview ¶
Package helpers provides shared utility functions for the controller layer.
Index ¶
- func BuildAdditionalDeclarations(cfg *config.Config, result *typebootstrap.Result) map[string]any
- func ExtractPostProcessorConfigs(cfg *config.Config) map[string][]templating.PostProcessorConfig
- func NewEngineFromConfigWithOptions(cfg *config.Config, globalFunctions map[string]templating.GlobalFunc, ...) (templating.Engine, error)
- type EngineOptions
- type TemplateExtraction
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildAdditionalDeclarations ¶
BuildAdditionalDeclarations returns the additionalDeclarations map that every template engine constructed by this controller needs at compile time. Single source of truth — folds together the static `currentConfig` slot (needed by BackendServers and other slot-preservation logic) with one typed-resource global per watched-resource entry derived from typebootstrap.
`result` MUST be non-nil and reflect a successful bootstrap against the cluster (or the embedded builtin set, for offline validate). Callers that don't have a real Result yet — e.g. the Stage-1 template validator — must obtain one via the injected TypeBootstrapper before calling this helper rather than passing nil. The previous envelope-only fallback path was removed because it false-positively rejected charts that used typed Spec/Status access (envelope only carries Metadata) and silently bound them to a mismatched shape elsewhere.
Adding a new engine consumer ¶
Call this function with the Result your caller obtained from typebootstrap.Bootstrap (or runTypeBootstrap in production), then pass the returned map straight into `templating.Options.Declarations` (or `helpers.NewEngineFromConfigWithOptions`'s `additionalDeclarations` parameter). Don't hand-merge — every site that did that previously had to be updated independently when the contract grew (Phase 4 added currentConfig; Phase 10–11 added typed globals); the helper bundles both.
func ExtractPostProcessorConfigs ¶
func ExtractPostProcessorConfigs(cfg *config.Config) map[string][]templating.PostProcessorConfig
ExtractPostProcessorConfigs extracts post-processor configurations from all templates.
This includes post-processors for:
- Main HAProxy configuration (haproxy.cfg)
- Map file templates
- General file templates
- SSL certificate templates
Returns a map of template names to their post-processor configurations.
func NewEngineFromConfigWithOptions ¶
func NewEngineFromConfigWithOptions( cfg *config.Config, globalFunctions map[string]templating.GlobalFunc, postProcessorConfigs map[string][]templating.PostProcessorConfig, additionalDeclarations map[string]any, options EngineOptions, ) (templating.Engine, error)
NewEngineFromConfigWithOptions creates a template engine from configuration.
This is a convenience function that handles the common pattern of:
- Extracting templates from configuration
- Parsing the engine type from configuration
- Creating the template engine
All standard filters (sort_by, glob_match, b64decode, strip, trim, debug) and the fail() function are registered internally by each engine. Callers only need to pass custom filters/functions if they have additional ones beyond the standard set (globalFunctions can be nil).
If postProcessorConfigs is nil, post-processors are automatically extracted from the configuration. Pass an explicit empty map to disable post-processing.
For Scriggo engines: Only entry points are compiled explicitly. Template snippets are discovered and compiled automatically when referenced via render/render_glob with inherit_context.
The additionalDeclarations parameter allows callers to inject domain-specific type declarations for Scriggo templates without the templating package needing to know about those types. This maintains clean architecture boundaries.
Types ¶
type EngineOptions ¶
type EngineOptions struct {
// EnableProfiling enables include timing profiling for the engine.
// When true, RenderWithProfiling() returns actual timing statistics.
EnableProfiling bool
}
EngineOptions configures template engine creation.
type TemplateExtraction ¶
type TemplateExtraction struct {
// AllTemplates contains all template content (entry points + snippets).
// This is provided to the template engine's filesystem so all templates are accessible.
AllTemplates map[string]string
// EntryPoints lists template names that should be compiled explicitly.
// Only these are compiled; snippets are compiled on-demand.
EntryPoints []string
}
TemplateExtraction contains templates and entry points extracted from configuration.
For Scriggo engines with inherit_context support, only entry points are compiled explicitly. Snippet templates are discovered and compiled automatically by Scriggo when referenced via render/render_glob statements.
func ExtractTemplatesFromConfig ¶
func ExtractTemplatesFromConfig(cfg *config.Config) TemplateExtraction
ExtractTemplatesFromConfig extracts all templates from the configuration structure.
Returns:
- AllTemplates: All template content (entry points + snippets)
- EntryPoints: Templates that should be compiled explicitly (main config + auxiliary files)
Entry points are:
- Main HAProxy configuration (haproxy.cfg)
- Map file templates
- General file templates
- SSL certificate templates
Template snippets are NOT entry points - they are discovered and compiled automatically by Scriggo when referenced via render/render_glob statements with inherit_context.
Source Files