env

package
v0.28.0 Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2026 License: Apache-2.0, BSD-3-Clause Imports: 7 Imported by: 5

Documentation

Overview

Package env provides a representation of a CEL environment.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	Name            string           `yaml:"name,omitempty"`
	Description     string           `yaml:"description,omitempty"`
	Container       string           `yaml:"container,omitempty"`
	Imports         []*Import        `yaml:"imports,omitempty"`
	StdLib          *LibrarySubset   `yaml:"stdlib,omitempty"`
	Extensions      []*Extension     `yaml:"extensions,omitempty"`
	ContextVariable *ContextVariable `yaml:"context_variable,omitempty"`
	Variables       []*Variable      `yaml:"variables,omitempty"`
	Functions       []*Function      `yaml:"functions,omitempty"`
	Validators      []*Validator     `yaml:"validators,omitempty"`
	Features        []*Feature       `yaml:"features,omitempty"`
	Limits          []*Limit         `yaml:"limits,omitempty"`
}

Config represents a serializable form of the CEL environment configuration.

Note: custom validations, feature flags, and performance tuning parameters are not (yet) considered part of the core CEL environment configuration and should be managed separately until a common convention for such settings is developed.

func NewConfig 

func NewConfig(name string) *Config

NewConfig creates an instance of a YAML serializable CEL environment configuration.

func (*Config) AddExtensions 

func (c *Config) AddExtensions(exts ...*Extension) *Config

AddExtensions appends a set of extensions to the config.

func (*Config) AddFeatures 

func (c *Config) AddFeatures(feats ...*Feature) *Config

AddFeatures appends one or more features to the config.

func (*Config) AddFunctionDecls 

func (c *Config) AddFunctionDecls(funcs ...*decls.FunctionDecl) *Config

AddFunctionDecls adds one or more functions to the config, converting them to serializable values first.

FunctionDecl inputs are expected to be well-formed.

func (*Config) AddFunctions 

func (c *Config) AddFunctions(funcs ...*Function) *Config

AddFunctions adds one or more functions to the config.

func (*Config) AddImports 

func (c *Config) AddImports(imps ...*Import) *Config

AddImports appends a set of imports to the config.

func (*Config) AddLimits added in v0.28.0 

func (c *Config) AddLimits(limits ...*Limit) *Config

AddLimits appends one or more limits to the config.

func (*Config) AddValidators 

func (c *Config) AddValidators(vals ...*Validator) *Config

AddValidators appends one or more validators to the config.

func (*Config) AddVariableDecls 

func (c *Config) AddVariableDecls(vars ...*decls.VariableDecl) *Config

AddVariableDecls adds one or more variables to the config, converting them to serializable values first.

VariableDecl inputs are expected to be well-formed.

func (*Config) AddVariables 

func (c *Config) AddVariables(vars ...*Variable) *Config

AddVariables adds one or more variables to the config.

func (*Config) SetContainer 

func (c *Config) SetContainer(container string) *Config

SetContainer configures the container name for this configuration.

func (*Config) SetContextVariable 

func (c *Config) SetContextVariable(ctx *ContextVariable) *Config

SetContextVariable configures the ContextVariable for this configuration.

func (*Config) SetStdLib 

func (c *Config) SetStdLib(subset *LibrarySubset) *Config

SetStdLib configures the LibrarySubset for the standard library.

func (*Config) Validate 

func (c *Config) Validate() error

Validate validates the whole configuration is well-formed.

type ContextVariable 

type ContextVariable struct {
	// TypeName represents the fully qualified typename of the context variable.
	// Currently, only protobuf types are supported.
	TypeName string `yaml:"type_name"`
}

ContextVariable represents a structured message whose fields are to be treated as the top-level variable identifiers within CEL expressions.

func NewContextVariable 

func NewContextVariable(typeName string) *ContextVariable

NewContextVariable returns a serializable context variable with a specific type name.

func (*ContextVariable) Validate 

func (ctx *ContextVariable) Validate() error

Validate validates the context-variable configuration is well-formed.

type Extension 

type Extension struct {
	// Name is either the LibraryName() or some short-hand simple identifier which is understood by the config-handler.
	Name string `yaml:"name"`

	// Version may either be an unsigned long value or the string 'latest'. If empty, the value is treated as '0'.
	Version string `yaml:"version,omitempty"`
}

Extension represents a named and optionally versioned extension library configured in the environment.

func NewExtension 

func NewExtension(name string, version uint32) *Extension

NewExtension creates a serializable Extension from a name and version string.

func (*Extension) Validate 

func (e *Extension) Validate() error

Validate validates the extension configuration is well-formed.

func (*Extension) VersionNumber 

func (e *Extension) VersionNumber() (uint32, error)

VersionNumber returns the parsed version string, or an error if the version cannot be parsed.

type Feature 

type Feature struct {
	Name    string `yaml:"name"`
	Enabled bool   `yaml:"enabled"`
}

Feature represents a named boolean feature flag supported by CEL.

func NewFeature 

func NewFeature(name string, enabled bool) *Feature

NewFeature creates a new feature flag with a boolean enablement flag.

func (*Feature) Validate 

func (feat *Feature) Validate() error

Validate validates whether the feature is well-configured.

type Function 

type Function struct {
	Name        string      `yaml:"name"`
	Description string      `yaml:"description,omitempty"`
	Overloads   []*Overload `yaml:"overloads,omitempty"`
}

Function represents the serializable format of a function and its overloads.

func NewFunction 

func NewFunction(name string, overloads ...*Overload) *Function

NewFunction creates a serializable function and overload set.

func NewFunctionWithDoc added in v0.25.0 

func NewFunctionWithDoc(name, doc string, overloads ...*Overload) *Function

NewFunctionWithDoc creates a serializable function and overload set.

func (*Function) AsCELFunction 

func (fn *Function) AsCELFunction(tp types.Provider) (*decls.FunctionDecl, error)

AsCELFunction converts the serializable form of the Function into CEL environment declaration.

func (*Function) Validate 

func (fn *Function) Validate() error

Validate validates the function configuration is well-formed.

type Import 

type Import struct {
	Name string `yaml:"name"`
}

Import represents a type name that will be appreviated by its simple name using the cel.Abbrevs() option.

func NewImport 

func NewImport(name string) *Import

NewImport returns a serializable import value from the qualified type name.

func (*Import) Validate 

func (imp *Import) Validate() error

Validate validates the import configuration is well-formed.

type LibrarySubset 

type LibrarySubset struct {
	// Disabled indicates whether the library has been disabled, typically only used for
	// default-enabled libraries like stdlib.
	Disabled bool `yaml:"disabled,omitempty"`

	// DisableMacros disables macros for the given library.
	DisableMacros bool `yaml:"disable_macros,omitempty"`

	// IncludeMacros specifies a set of macro function names to include in the subset.
	IncludeMacros []string `yaml:"include_macros,omitempty"`

	// ExcludeMacros specifies a set of macro function names to exclude from the subset.
	// Note: if IncludeMacros is non-empty, then ExcludeFunctions is ignored.
	ExcludeMacros []string `yaml:"exclude_macros,omitempty"`

	// IncludeFunctions specifies a set of functions to include in the subset.
	//
	// Note: the overloads specified in the subset need only specify their ID.
	// Note: if IncludeFunctions is non-empty, then ExcludeFunctions is ignored.
	IncludeFunctions []*Function `yaml:"include_functions,omitempty"`

	// ExcludeFunctions specifies the set of functions to exclude from the subset.
	//
	// Note: the overloads specified in the subset need only specify their ID.
	ExcludeFunctions []*Function `yaml:"exclude_functions,omitempty"`
}

LibrarySubset indicates a subset of the macros and function supported by a subsettable library.

func NewLibrarySubset 

func NewLibrarySubset() *LibrarySubset

NewLibrarySubset returns an empty library subsetting config which permits all library features.

func (*LibrarySubset) AddExcludedFunctions 

func (lib *LibrarySubset) AddExcludedFunctions(funcs ...*Function) *LibrarySubset

AddExcludedFunctions deny-lists one or more functions from the subset.

func (*LibrarySubset) AddExcludedMacros 

func (lib *LibrarySubset) AddExcludedMacros(macros ...string) *LibrarySubset

AddExcludedMacros deny-lists one or more macros by function name.

func (*LibrarySubset) AddIncludedFunctions 

func (lib *LibrarySubset) AddIncludedFunctions(funcs ...*Function) *LibrarySubset

AddIncludedFunctions allow-lists one or more functions from the subset.

Note, this option will override any excluded functions.

func (*LibrarySubset) AddIncludedMacros 

func (lib *LibrarySubset) AddIncludedMacros(macros ...string) *LibrarySubset

AddIncludedMacros allow-lists one or more macros by function name.

Note, this option will override any excluded macros.

func (*LibrarySubset) SetDisableMacros 

func (lib *LibrarySubset) SetDisableMacros(value bool) *LibrarySubset

SetDisableMacros disables the macros for the library.

func (*LibrarySubset) SetDisabled 

func (lib *LibrarySubset) SetDisabled(value bool) *LibrarySubset

SetDisabled disables or enables the library.

func (*LibrarySubset) SubsetFunction 

func (lib *LibrarySubset) SubsetFunction(fn *decls.FunctionDecl) (*decls.FunctionDecl, bool)

SubsetFunction produces a function declaration which matches the supported subset, or nil if the function is not supported by the LibrarySubset.

For IncludeFunctions, if the function does not specify a set of overloads to include, the whole function definition is included. If overloads are set, then a new function which includes only the specified overloads is produced.

For ExcludeFunctions, if the function does not specify a set of overloads to exclude, the whole function definition is excluded. If overloads are set, then a new function which includes only the permitted overloads is produced.

func (*LibrarySubset) SubsetMacro 

func (lib *LibrarySubset) SubsetMacro(macroFunction string) bool

SubsetMacro indicates whether the macro function should be included in the library subset.

func (*LibrarySubset) Validate 

func (lib *LibrarySubset) Validate() error

Validate validates the library configuration is well-formed.

For example, setting both the IncludeMacros and ExcludeMacros together could be confusing and create a broken expectation, likewise for IncludeFunctions and ExcludeFunctions.

type Limit added in v0.28.0 

type Limit struct {
	Name  string `yaml:"name"`
	Value int    `yaml:"value"`
}

Limit represents a named limit in the CEL environment. This is used to control the complexity tolerated before failing parsing, type checking, or planning.

func NewLimit added in v0.28.0 

func NewLimit(name string, value int) *Limit

NewLimit creates a new limit.

func (*Limit) Validate added in v0.28.0 

func (l *Limit) Validate() error

Validate validates a limit.

type Overload 

type Overload struct {
	ID       string      `yaml:"id"`
	Examples []string    `yaml:"examples,omitempty"`
	Target   *TypeDesc   `yaml:"target,omitempty"`
	Args     []*TypeDesc `yaml:"args,omitempty"`
	Return   *TypeDesc   `yaml:"return,omitempty"`
}

Overload represents the serializable format of a function overload.

func NewMemberOverload 

func NewMemberOverload(id string, target *TypeDesc, args []*TypeDesc, ret *TypeDesc, examples ...string) *Overload

NewMemberOverload returns a new serializable representation of a member (receiver) overload.

func NewOverload 

func NewOverload(id string, args []*TypeDesc, ret *TypeDesc, examples ...string) *Overload

NewOverload returns a new serializable representation of a global overload.

func (*Overload) AsFunctionOption 

func (od *Overload) AsFunctionOption(tp types.Provider) (decls.FunctionOpt, error)

AsFunctionOption converts the serializable form of the Overload into a function declaration option.

func (*Overload) Validate 

func (od *Overload) Validate() error

Validate validates the overload configuration is well-formed.

type TypeDesc 

type TypeDesc struct {
	TypeName    string      `yaml:"type_name"`
	Params      []*TypeDesc `yaml:"params,omitempty"`
	IsTypeParam bool        `yaml:"is_type_param,omitempty"`
}

TypeDesc represents the serializable format of a CEL *types.Type value.

func NewTypeDesc 

func NewTypeDesc(typeName string, params ...*TypeDesc) *TypeDesc

NewTypeDesc describes a simple or complex type with parameters.

func NewTypeParam 

func NewTypeParam(paramName string) *TypeDesc

NewTypeParam describe a type-param type.

func SerializeTypeDesc added in v0.25.0 

func SerializeTypeDesc(t *types.Type) *TypeDesc

SerializeTypeDesc converts a CEL native *types.Type to a serializable TypeDesc.

func (*TypeDesc) AsCELType 

func (td *TypeDesc) AsCELType(tp types.Provider) (*types.Type, error)

AsCELType converts the serializable object to a *types.Type value.

func (*TypeDesc) String 

func (td *TypeDesc) String() string

String implements the strings.Stringer interface method.

func (*TypeDesc) Validate 

func (td *TypeDesc) Validate() error

Validate validates the type configuration is well-formed.

type Validator 

type Validator struct {
	Name   string         `yaml:"name"`
	Config map[string]any `yaml:"config,omitempty"`
}

Validator represents a named validator with an optional map-based configuration object.

Note: the map-keys must directly correspond to the internal representation of the original validator, and should only use primitive scalar types as values at this time.

func NewValidator 

func NewValidator(name string) *Validator

NewValidator returns a named Validator instance.

func (*Validator) ConfigValue 

func (v *Validator) ConfigValue(name string) (any, bool)

ConfigValue retrieves the value associated with the config key name, if one exists.

func (*Validator) SetConfig 

func (v *Validator) SetConfig(config map[string]any) *Validator

SetConfig sets the set of map key-value pairs associated with this validator's configuration.

func (*Validator) Validate 

func (v *Validator) Validate() error

Validate validates the configuration of the validator object.

type Variable 

type Variable struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`

	// Type represents the type declaration for the variable.
	//
	// Deprecated: use the embedded *TypeDesc fields directly.
	Type *TypeDesc `yaml:"type,omitempty"`

	// TypeDesc is an embedded set of fields allowing for the specification of the Variable type.
	*TypeDesc `yaml:",inline"`
}

Variable represents a typed variable declaration which will be published via the cel.VariableDecls() option.

func NewVariable 

func NewVariable(name string, t *TypeDesc) *Variable

NewVariable returns a serializable variable from a name and type definition

func NewVariableWithDoc added in v0.25.0 

func NewVariableWithDoc(name string, t *TypeDesc, doc string) *Variable

NewVariableWithDoc returns a serializable variable from a name, type definition, and doc string.

func (*Variable) AsCELVariable 

func (v *Variable) AsCELVariable(tp types.Provider) (*decls.VariableDecl, error)

AsCELVariable converts the serializable form of the Variable into a CEL environment declaration.

func (*Variable) GetType 

func (v *Variable) GetType() *TypeDesc

GetType returns the variable type description.

Note, if both the embedded TypeDesc and the field Type are non-nil, the embedded TypeDesc will take precedence.

func (*Variable) Validate 

func (v *Variable) Validate() error

Validate validates the variable configuration is well-formed.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.