| // Copyright 2019 Google LLC | |
| // | |
| // Licensed under the Apache License, Version 2.0 (the "License"); | |
| // you may not use this file except in compliance with the License. | |
| // You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, software | |
| // distributed under the License is distributed on an "AS IS" BASIS, | |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| // See the License for the specific language governing permissions and | |
| // limitations under the License. | |
| package cel | |
| import ( | |
| "errors" | |
| "fmt" | |
| "maps" | |
| "math" | |
| "slices" | |
| "strings" | |
| "sync" | |
| "cel.dev/cel-go/checker" | |
| chkdecls "cel.dev/cel-go/checker/decls" | |
| "cel.dev/cel-go/common" | |
| celast "cel.dev/cel-go/common/ast" | |
| "cel.dev/cel-go/common/containers" | |
| "cel.dev/cel-go/common/decls" | |
| "cel.dev/cel-go/common/env" | |
| "cel.dev/cel-go/common/functions" | |
| "cel.dev/cel-go/common/stdlib" | |
| "cel.dev/cel-go/common/types" | |
| "cel.dev/cel-go/common/types/ref" | |
| "cel.dev/cel-go/interpreter" | |
| "cel.dev/cel-go/parser" | |
| exprpb "google.golang.org/genproto/googleapis/api/expr/v1alpha1" | |
| "google.golang.org/protobuf/reflect/protoreflect" | |
| ) | |
| // Source interface representing a user-provided expression. | |
| type Source = common.Source | |
| // Ast representing the checked or unchecked expression, its source, and related metadata such as | |
| // source position information. | |
| type Ast struct { | |
| source Source | |
| impl *celast.AST | |
| // loadErr captures an error detected while loading the AST (e.g. an over-deep AST ingested via | |
| // ParsedExprToAst / CheckedExprToAst) so it can be surfaced when the Ast is checked or planned | |
| // instead of recursing into the checker or planner on adversarially deep input. | |
| loadErr error | |
| } | |
| // NativeRep converts the AST to a Go-native representation. | |
| func (ast *Ast) NativeRep() *celast.AST { | |
| if ast == nil { | |
| return nil | |
| } | |
| return ast.impl | |
| } | |
| // Expr returns the proto serializable instance of the parsed/checked expression. | |
| // | |
| // Deprecated: prefer cel.AstToCheckedExpr() or cel.AstToParsedExpr() and call GetExpr() | |
| // the result instead. | |
| func (ast *Ast) Expr() *exprpb.Expr { | |
| if ast == nil { | |
| return nil | |
| } | |
| pbExpr, _ := celast.ExprToProto(ast.NativeRep().Expr()) | |
| return pbExpr | |
| } | |
| // IsChecked returns whether the Ast value has been successfully type-checked. | |
| func (ast *Ast) IsChecked() bool { | |
| return ast.NativeRep().IsChecked() | |
| } | |
| // SourceInfo returns character offset and newline position information about expression elements. | |
| func (ast *Ast) SourceInfo() *exprpb.SourceInfo { | |
| if ast == nil { | |
| return nil | |
| } | |
| pbInfo, _ := celast.SourceInfoToProto(ast.NativeRep().SourceInfo()) | |
| return pbInfo | |
| } | |
| // ResultType returns the output type of the expression if the Ast has been type-checked, else | |
| // returns chkdecls.Dyn as the parse step cannot infer the type. | |
| // | |
| // Deprecated: use OutputType | |
| func (ast *Ast) ResultType() *exprpb.Type { | |
| out := ast.OutputType() | |
| t, err := TypeToExprType(out) | |
| if err != nil { | |
| return chkdecls.Dyn | |
| } | |
| return t | |
| } | |
| // OutputType returns the output type of the expression if the Ast has been type-checked, else | |
| // returns cel.DynType as the parse step cannot infer types. | |
| func (ast *Ast) OutputType() *Type { | |
| if ast == nil { | |
| return types.ErrorType | |
| } | |
| return ast.NativeRep().GetType(ast.NativeRep().Expr().ID()) | |
| } | |
| // Source returns a view of the input used to create the Ast. This source may be complete or | |
| // constructed from the SourceInfo. | |
| func (ast *Ast) Source() Source { | |
| if ast == nil { | |
| return nil | |
| } | |
| return ast.source | |
| } | |
| // FormatType converts a type message into a string representation. | |
| // | |
| // Deprecated: prefer FormatCELType | |
| func FormatType(t *exprpb.Type) string { | |
| return checker.FormatCheckedType(t) | |
| } | |
| // FormatCELType formats a cel.Type value to a string representation. | |
| // | |
| // The type formatting is identical to FormatType. | |
| func FormatCELType(t *Type) string { | |
| return checker.FormatCELType(t) | |
| } | |
| // Env encapsulates the context necessary to perform parsing, type checking, or generation of | |
| // evaluable programs for different expressions. | |
| type Env struct { | |
| Container *containers.Container | |
| variables []*decls.VariableDecl | |
| functions map[string]*decls.FunctionDecl | |
| macros []Macro | |
| contextProto protoreflect.MessageDescriptor | |
| adapter types.Adapter | |
| provider types.Provider | |
| features map[int]bool | |
| appliedFeatures map[int]bool | |
| limits map[limitID]int | |
| libraries map[string]SingletonLibrary | |
| validators []ASTValidator | |
| costOptions []checker.CostOption | |
| // Flags for copy-on-write behavior with env.Extend. | |
| funcsShared bool | |
| featuresShared bool | |
| appliedFeaturesShared bool | |
| limitsShared bool | |
| libsShared bool | |
| parent *Env | |
| // sharedDispatcher caches a dispatcher populated with the env's function | |
| // bindings, built once and reused across every Program() constructed from | |
| // this env. It is read-only after construction; each Program layers a thin | |
| // child over it for per-program Functions(). Extended envs reuse the parent's | |
| // dispatcher if functions are unchanged. | |
| sharedDispatcher interpreter.Dispatcher | |
| dispOnce sync.Once | |
| hasAsync bool | |
| dispErr error | |
| // Internal parser representation | |
| prsr *parser.Parser | |
| prsrOpts []parser.Option | |
| // Internal checker representation | |
| chkMutex sync.Mutex | |
| chk *checker.Env | |
| chkErr error | |
| chkOnce sync.Once | |
| chkOpts []checker.Option | |
| // Program options tied to the environment | |
| progOpts []ProgramOption | |
| } | |
| // ToConfig produces a YAML-serializable env.Config object from the given environment. | |
| // | |
| // The serialized configuration value is intended to represent a baseline set of config | |
| // options which could be used as input to an EnvOption to configure the majority of the | |
| // environment from a file. | |
| // | |
| // Note: validators, features, flags, and safe-guard settings are not yet supported by | |
| // the serialize method. Since optimizers are a separate construct from the environment | |
| // and the standard expression components (parse, check, evalute), they are also not | |
| // supported by the serialize method. | |
| func (e *Env) ToConfig(name string) (*env.Config, error) { | |
| conf := env.NewConfig(name) | |
| // Container settings | |
| if e.Container != containers.DefaultContainer { | |
| conf.SetContainer(e.Container.Name()) | |
| } | |
| for _, typeName := range e.Container.AliasSet() { | |
| conf.AddImports(env.NewImport(typeName)) | |
| } | |
| // Serialize features | |
| for featID, enabled := range e.features { | |
| featName, found := featureNameByID(featID) | |
| if !found { | |
| // If the feature isn't named, it isn't intended to be publicly exposed | |
| continue | |
| } | |
| conf.AddFeatures(env.NewFeature(featName, enabled)) | |
| } | |
| libOverloads := map[string][]string{} | |
| for libName, lib := range e.libraries { | |
| // Track the options which have been configured by a library and | |
| // then diff the library version against the configured function | |
| // to detect incremental overloads or rewrites. | |
| libEnv, _ := NewCustomEnv() | |
| libEnv, _ = Lib(lib)(libEnv) | |
| for fnName, fnDecl := range libEnv.Functions() { | |
| if len(fnDecl.OverloadDecls()) == 0 { | |
| continue | |
| } | |
| overloads, exist := libOverloads[fnName] | |
| if !exist { | |
| overloads = make([]string, 0, len(fnDecl.OverloadDecls())) | |
| } | |
| for _, o := range fnDecl.OverloadDecls() { | |
| overloads = append(overloads, o.ID()) | |
| } | |
| libOverloads[fnName] = overloads | |
| } | |
| subsetLib, canSubset := lib.(LibrarySubsetter) | |
| alias := "" | |
| if aliasLib, canAlias := lib.(LibraryAliaser); canAlias { | |
| alias = aliasLib.LibraryAlias() | |
| libName = alias | |
| } | |
| if libName == "stdlib" && canSubset { | |
| conf.SetStdLib(subsetLib.LibrarySubset()) | |
| continue | |
| } | |
| version := uint32(math.MaxUint32) | |
| if versionLib, isVersioned := lib.(LibraryVersioner); isVersioned { | |
| version = versionLib.LibraryVersion() | |
| } | |
| conf.AddExtensions(env.NewExtension(libName, version)) | |
| } | |
| // If this is a custom environment without the standard env, mark the stdlib as disabled. | |
| if conf.StdLib == nil && !e.HasLibrary("cel.lib.std") { | |
| conf.SetStdLib(env.NewLibrarySubset().SetDisabled(true)) | |
| } | |
| // Serialize the variables | |
| vars := make([]*decls.VariableDecl, 0, len(e.Variables())) | |
| stdTypeVars := map[string]*decls.VariableDecl{} | |
| for _, v := range stdlib.Types() { | |
| stdTypeVars[v.Name()] = v | |
| } | |
| for _, v := range e.Variables() { | |
| if _, isStdType := stdTypeVars[v.Name()]; isStdType { | |
| continue | |
| } | |
| vars = append(vars, v) | |
| } | |
| if e.contextProto != nil { | |
| conf.SetContextVariable(env.NewContextVariable(string(e.contextProto.FullName()))) | |
| skipVariables := map[string]bool{} | |
| fields := e.contextProto.Fields() | |
| for i := 0; i < fields.Len(); i++ { | |
| field := fields.Get(i) | |
| variable, err := fieldToVariable(field, e.HasFeature(featureJSONFieldNames)) | |
| if err != nil { | |
| return nil, fmt.Errorf("could not serialize context field variable %q, reason: %w", field.FullName(), err) | |
| } | |
| skipVariables[variable.Name()] = true | |
| } | |
| for _, v := range vars { | |
| if _, found := skipVariables[v.Name()]; !found { | |
| conf.AddVariableDecls(v) | |
| } | |
| } | |
| } else { | |
| conf.AddVariableDecls(vars...) | |
| } | |
| // Serialize functions which are distinct from the ones configured by libraries. | |
| for fnName, fnDecl := range e.Functions() { | |
| if excludedOverloads, found := libOverloads[fnName]; found { | |
| if newDecl := fnDecl.Subset(decls.ExcludeOverloads(excludedOverloads...)); newDecl != nil { | |
| conf.AddFunctionDecls(newDecl) | |
| } | |
| } else { | |
| conf.AddFunctionDecls(fnDecl) | |
| } | |
| } | |
| // Serialize validators | |
| for _, val := range e.Validators() { | |
| // Only add configurable validators to the env.Config as all others are | |
| // expected to be implicitly enabled via extension libraries. | |
| if confVal, ok := val.(ConfigurableASTValidator); ok { | |
| conf.AddValidators(confVal.ToConfig()) | |
| } | |
| } | |
| for id, val := range e.limits { | |
| limitName, found := limitNameByID(id) | |
| if !found || val == 0 { | |
| // skip if explicitly defaulted or not supported in config | |
| continue | |
| } | |
| conf.AddLimits(env.NewLimit(limitName, val)) | |
| } | |
| // Sort repeated fields in config where reasonable to make the export | |
| // stable. | |
| slices.SortFunc(conf.Imports, func(a *env.Import, b *env.Import) int { | |
| return strings.Compare(a.Name, b.Name) | |
| }) | |
| slices.SortFunc(conf.Extensions, func(a *env.Extension, b *env.Extension) int { | |
| return strings.Compare(a.Name, b.Name) | |
| }) | |
| slices.SortFunc(conf.Variables, func(a *env.Variable, b *env.Variable) int { | |
| return strings.Compare(a.Name, b.Name) | |
| }) | |
| slices.SortFunc(conf.Functions, func(a *env.Function, b *env.Function) int { | |
| return strings.Compare(a.Name, b.Name) | |
| }) | |
| slices.SortFunc(conf.Validators, func(a *env.Validator, b *env.Validator) int { | |
| return strings.Compare(a.Name, b.Name) | |
| }) | |
| slices.SortFunc(conf.Features, func(a *env.Feature, b *env.Feature) int { | |
| return strings.Compare(a.Name, b.Name) | |
| }) | |
| slices.SortFunc(conf.Limits, func(a *env.Limit, b *env.Limit) int { | |
| return strings.Compare(a.Name, b.Name) | |
| }) | |
| return conf, nil | |
| } | |
| // NewEnv creates a program environment configured with the standard library of CEL functions and | |
| // macros. The Env value returned can parse and check any CEL program which builds upon the core | |
| // features documented in the CEL specification. | |
| // | |
| // See the EnvOption helper functions for the options that can be used to configure the | |
| // environment. | |
| func NewEnv(opts ...EnvOption) (*Env, error) { | |
| // Extend the statically configured standard environment, disabling eager validation to ensure | |
| // the cost of setup for the environment is still just as cheap as it is in v0.11.x and earlier | |
| // releases. The user provided options can easily re-enable the eager validation as they are | |
| // processed after this default option. | |
| stdOpts := append([]EnvOption{EagerlyValidateDeclarations(false)}, opts...) | |
| env, err := getStdEnv() | |
| if err != nil { | |
| return nil, err | |
| } | |
| return env.Extend(stdOpts...) | |
| } | |
| // NewCustomEnv creates a custom program environment which is not automatically configured with the | |
| // standard library of functions and macros documented in the CEL spec. | |
| // | |
| // The purpose for using a custom environment might be for subsetting the standard library produced | |
| // by the cel.StdLib() function. Subsetting CEL is a core aspect of its design that allows users to | |
| // limit the compute and memory impact of a CEL program by controlling the functions and macros | |
| // that may appear in a given expression. | |
| // | |
| // See the EnvOption helper functions for the options that can be used to configure the | |
| // environment. | |
| func NewCustomEnv(opts ...EnvOption) (*Env, error) { | |
| registry, err := types.NewRegistry() | |
| if err != nil { | |
| return nil, err | |
| } | |
| return (&Env{ | |
| variables: []*decls.VariableDecl{}, | |
| functions: map[string]*decls.FunctionDecl{}, | |
| macros: []parser.Macro{}, | |
| Container: containers.DefaultContainer, | |
| adapter: registry, | |
| provider: registry, | |
| features: map[int]bool{}, | |
| appliedFeatures: map[int]bool{}, | |
| limits: map[limitID]int{}, | |
| libraries: map[string]SingletonLibrary{}, | |
| validators: []ASTValidator{}, | |
| progOpts: []ProgramOption{}, | |
| costOptions: []checker.CostOption{}, | |
| }).configure(opts) | |
| } | |
| // Check performs type-checking on the input Ast and yields a checked Ast and/or set of Issues. | |
| // If any `ASTValidators` are configured on the environment, they will be applied after a valid | |
| // type-check result. If any issues are detected, the validators will provide them on the | |
| // output Issues object. | |
| // | |
| // Either checking or validation has failed if the returned Issues value and its Issues.Err() | |
| // value are non-nil. Issues should be inspected if they are non-nil, but may not represent a | |
| // fatal error. | |
| // | |
| // It is possible to have both non-nil Ast and Issues values returned from this call: however, | |
| // the mere presence of an Ast does not imply that it is valid for use. | |
| func (e *Env) Check(ast *Ast) (*Ast, *Issues) { | |
| // Surface any error recorded while the Ast was loaded (e.g. an over-deep AST rejected by | |
| // ParsedExprToAst / CheckedExprToAst) before recursing into the type checker on it. | |
| if ast != nil && ast.loadErr != nil { | |
| errs := common.NewErrors(ast.Source()) | |
| errs.ReportErrorString(common.NoLocation, ast.loadErr.Error()) | |
| return nil, NewIssuesWithSourceInfo(errs, ast.NativeRep().SourceInfo()) | |
| } | |
| if nodeLimit := e.configuredExpressionNodeLimit(); nodeLimit > 0 && ast != nil && ast.NativeRep() != nil { | |
| if count := celast.NodeCount(ast.NativeRep()); count > nodeLimit { | |
| errs := common.NewErrors(ast.Source()) | |
| errs.ReportErrorString(common.NoLocation, fmt.Sprintf("expression node count exceeds limit: count %d, limit %d", count, nodeLimit)) | |
| return nil, NewIssuesWithSourceInfo(errs, ast.NativeRep().SourceInfo()) | |
| } | |
| } | |
| // Construct the internal checker env, erroring if there is an issue adding the declarations. | |
| chk, err := e.initChecker() | |
| if err != nil { | |
| errs := common.NewErrors(ast.Source()) | |
| errs.ReportErrorString(common.NoLocation, err.Error()) | |
| return nil, NewIssuesWithSourceInfo(errs, ast.NativeRep().SourceInfo()) | |
| } | |
| checked, errs := checker.Check(ast.NativeRep(), ast.Source(), chk) | |
| if len(errs.GetErrors()) > 0 { | |
| return nil, NewIssuesWithSourceInfo(errs, ast.NativeRep().SourceInfo()) | |
| } | |
| // Manually create the Ast to ensure that the Ast source information (which may be more | |
| // detailed than the information provided by Check), is returned to the caller. | |
| ast = &Ast{ | |
| source: ast.Source(), | |
| impl: checked} | |
| // Avoid creating a validator config if it's not needed. | |
| if len(e.validators) == 0 { | |
| return ast, nil | |
| } | |
| // Generate a validator configuration from the set of configured validators. | |
| vConfig := newValidatorConfig() | |
| for _, v := range e.validators { | |
| if cv, ok := v.(ASTValidatorConfigurer); ok { | |
| cv.Configure(vConfig) | |
| } | |
| } | |
| // Apply additional validators on the type-checked result. | |
| iss := NewIssuesWithSourceInfo(errs, ast.NativeRep().SourceInfo()) | |
| for _, v := range e.validators { | |
| v.Validate(e, vConfig, checked, iss) | |
| } | |
| if iss.Err() != nil { | |
| return nil, iss | |
| } | |
| return ast, nil | |
| } | |
| // configuredExpressionSizeLimit returns the effective expression size code point limit. | |
| // A zero value means "use the parser default". | |
| func (e *Env) configuredExpressionSizeLimit() int { | |
| if l := e.limits[limitCodePointSize]; l != 0 { | |
| return l | |
| } | |
| return 100_000 | |
| } | |
| // configuredExpressionNodeLimit returns the effective expression node limit. | |
| // A zero value means "use default". | |
| func (e *Env) configuredExpressionNodeLimit() int { | |
| if l := e.limits[limitExpressionNodeCount]; l != 0 { | |
| return l | |
| } | |
| return 100_000 | |
| } | |
| // Compile combines the Parse and Check phases CEL program compilation to produce an Ast and | |
| // associated issues. | |
| // | |
| // If an error is encountered during parsing the Compile step will not continue with the Check | |
| // phase. If non-error issues are encountered during Parse, they may be combined with any issues | |
| // discovered during Check. | |
| // | |
| // Note, for parse-only uses of CEL use Parse. | |
| func (e *Env) Compile(txt string) (*Ast, *Issues) { | |
| src, err := common.NewTextSourceWithLimit(txt, e.configuredExpressionSizeLimit()) | |
| if err != nil { | |
| return nil, ErrorAsIssues(err) | |
| } | |
| return e.CompileSource(src) | |
| } | |
| // CompileSource combines the Parse and Check phases CEL program compilation to produce an Ast and | |
| // associated issues. | |
| // | |
| // If an error is encountered during parsing the CompileSource step will not continue with the | |
| // Check phase. If non-error issues are encountered during Parse, they may be combined with any | |
| // issues discovered during Check. | |
| // | |
| // Note, for parse-only uses of CEL use Parse. | |
| func (e *Env) CompileSource(src Source) (*Ast, *Issues) { | |
| ast, iss := e.ParseSource(src) | |
| if iss.Err() != nil { | |
| return nil, iss | |
| } | |
| checked, iss2 := e.Check(ast) | |
| if iss2.Err() != nil { | |
| return nil, iss2 | |
| } | |
| return checked, iss2 | |
| } | |
| // Extend the current environment with additional options to produce a new Env. | |
| // | |
| // Note, the extended Env value should not share memory with the original. It is possible, however, | |
| // that a CustomTypeAdapter or CustomTypeProvider options could provide values which are mutable. | |
| // To ensure separation of state between extended environments either make sure the TypeAdapter and | |
| // TypeProvider are immutable, or that their underlying implementations are based on the | |
| // ref.TypeRegistry which provides a Copy method which will be invoked by this method. | |
| func (e *Env) Extend(opts ...EnvOption) (*Env, error) { | |
| if _, chkErr := e.getCheckerOrError(); chkErr != nil { | |
| return nil, chkErr | |
| } | |
| prsrOptsCopy := slices.Clone(e.prsrOpts) | |
| chkOptsCopy := slices.Clone(e.chkOpts) | |
| varsCopy := slices.Clone(e.variables) | |
| macsCopy := slices.Clone(e.macros) | |
| progOptsCopy := slices.Clone(e.progOpts) | |
| validatorsCopy := slices.Clone(e.validators) | |
| costOptsCopy := slices.Clone(e.costOptions) | |
| // Copy the adapter / provider if they appear to be mutable. | |
| adapter := e.adapter | |
| provider := e.provider | |
| adapterReg, isAdapterReg := e.adapter.(*types.Registry) | |
| providerReg, isProviderReg := e.provider.(*types.Registry) | |
| // In most cases the provider and adapter will be a ref.TypeRegistry; | |
| // however, in the rare cases where they are not, they are assumed to | |
| // be immutable. Since it is possible to set the TypeProvider separately | |
| // from the TypeAdapter, the possible configurations which could use a | |
| // TypeRegistry as the base implementation are captured below. | |
| if isAdapterReg && isProviderReg { | |
| reg := providerReg.Copy() | |
| provider = reg | |
| // If the adapter and provider are the same object, set the adapter | |
| // to the same ref.TypeRegistry as the provider. | |
| if adapterReg == providerReg { | |
| adapter = reg | |
| } else { | |
| // Otherwise, make a copy of the adapter. | |
| adapter = adapterReg.Copy() | |
| } | |
| } else if isProviderReg { | |
| provider = providerReg.Copy() | |
| } else if isAdapterReg { | |
| adapter = adapterReg.Copy() | |
| } | |
| ext := &Env{ | |
| parent: e, | |
| Container: e.Container, | |
| variables: varsCopy, | |
| functions: e.functions, | |
| macros: macsCopy, | |
| contextProto: e.contextProto, | |
| progOpts: progOptsCopy, | |
| adapter: adapter, | |
| features: e.features, | |
| limits: e.limits, | |
| appliedFeatures: e.appliedFeatures, | |
| libraries: e.libraries, | |
| validators: validatorsCopy, | |
| provider: provider, | |
| chkOpts: chkOptsCopy, | |
| prsrOpts: prsrOptsCopy, | |
| costOptions: costOptsCopy, | |
| // Copy-on-write flags. | |
| funcsShared: true, | |
| featuresShared: true, | |
| limitsShared: true, | |
| appliedFeaturesShared: true, | |
| libsShared: true, | |
| } | |
| return ext.configure(opts) | |
| } | |
| func (e *Env) ensureMutableFunctions() { | |
| if e.funcsShared { | |
| e.functions = maps.Clone(e.functions) | |
| e.funcsShared = false | |
| } | |
| } | |
| func (e *Env) ensureMutableLibraries() { | |
| if e.libsShared { | |
| e.libraries = maps.Clone(e.libraries) | |
| e.libsShared = false | |
| } | |
| } | |
| func (e *Env) ensureMutableFeatures() { | |
| if e.featuresShared { | |
| e.features = maps.Clone(e.features) | |
| e.featuresShared = false | |
| } | |
| } | |
| func (e *Env) ensureMutableAppliedFeatures() { | |
| if e.appliedFeaturesShared { | |
| e.appliedFeatures = maps.Clone(e.appliedFeatures) | |
| e.appliedFeaturesShared = false | |
| } | |
| } | |
| func (e *Env) ensureMutableLimits() { | |
| if e.limitsShared { | |
| e.limits = maps.Clone(e.limits) | |
| e.limitsShared = false | |
| } | |
| } | |
| // HasFeature checks whether the environment enables the given feature | |
| // flag, as enumerated in options.go. | |
| func (e *Env) HasFeature(flag int) bool { | |
| enabled, has := e.features[flag] | |
| return has && enabled | |
| } | |
| // HasLibrary returns whether a specific SingletonLibrary has been configured in the environment. | |
| func (e *Env) HasLibrary(libName string) bool { | |
| _, exists := e.libraries[libName] | |
| return exists | |
| } | |
| // Libraries returns a list of SingletonLibrary that have been configured in the environment. | |
| func (e *Env) Libraries() []string { | |
| libraries := make([]string, 0, len(e.libraries)) | |
| for libName := range e.libraries { | |
| libraries = append(libraries, libName) | |
| } | |
| return libraries | |
| } | |
| // HasFunction returns whether a specific function has been configured in the environment | |
| func (e *Env) HasFunction(functionName string) bool { | |
| _, ok := e.functions[functionName] | |
| return ok | |
| } | |
| // Functions returns a shallow copy of the Functions, keyed by function name, that have been configured in the environment. | |
| func (e *Env) Functions() map[string]*decls.FunctionDecl { | |
| return maps.Clone(e.functions) | |
| } | |
| // Variables returns a shallow copy of the variables associated with the environment. | |
| func (e *Env) Variables() []*decls.VariableDecl { | |
| return slices.Clone(e.variables) | |
| } | |
| // Macros returns a shallow copy of macros associated with the environment. | |
| func (e *Env) Macros() []Macro { | |
| return slices.Clone(e.macros) | |
| } | |
| // HasValidator returns whether a specific ASTValidator has been configured in the environment. | |
| func (e *Env) HasValidator(name string) bool { | |
| for _, v := range e.validators { | |
| if v.Name() == name { | |
| return true | |
| } | |
| } | |
| return false | |
| } | |
| // Validators returns a shallow copy of the set of ASTValidators configured on the environment. | |
| func (e *Env) Validators() []ASTValidator { | |
| return slices.Clone(e.validators) | |
| } | |
| // Parse parses the input expression value `txt` to a Ast and/or a set of Issues. | |
| // | |
| // This form of Parse creates a Source value for the input `txt` and forwards to the | |
| // ParseSource method. | |
| func (e *Env) Parse(txt string) (*Ast, *Issues) { | |
| src, err := common.NewTextSourceWithLimit(txt, e.configuredExpressionSizeLimit()) | |
| if err != nil { | |
| return nil, ErrorAsIssues(err) | |
| } | |
| return e.ParseSource(src) | |
| } | |
| // ParseSource parses the input source to an Ast and/or set of Issues. | |
| // | |
| // Parsing has failed if the returned Issues value and its Issues.Err() value is non-nil. | |
| // Issues should be inspected if they are non-nil, but may not represent a fatal error. | |
| // | |
| // It is possible to have both non-nil Ast and Issues values returned from this call; however, | |
| // the mere presence of an Ast does not imply that it is valid for use. | |
| func (e *Env) ParseSource(src Source) (*Ast, *Issues) { | |
| parsed, errs := e.prsr.Parse(src) | |
| if len(errs.GetErrors()) > 0 { | |
| return nil, &Issues{errs: errs} | |
| } | |
| return &Ast{source: src, impl: parsed}, nil | |
| } | |
| // Program generates an evaluable instance of the Ast within the environment (Env). | |
| func (e *Env) Program(ast *Ast, opts ...ProgramOption) (Program, error) { | |
| // Surface any error recorded while the Ast was loaded (e.g. an over-deep AST rejected by | |
| // ParsedExprToAst / CheckedExprToAst) rather than recursing into the planner on it. This is a | |
| // cheap field read; the depth traversal itself runs once at conversion time, not here. | |
| if ast != nil && ast.loadErr != nil { | |
| return nil, ast.loadErr | |
| } | |
| return e.PlanProgram(ast.NativeRep(), opts...) | |
| } | |
| // PlanProgram generates an evaluable instance of the AST in the go-native representation within | |
| // the environment (Env). | |
| func (e *Env) PlanProgram(a *celast.AST, opts ...ProgramOption) (Program, error) { | |
| optSet := e.progOpts | |
| if len(opts) != 0 { | |
| mergedOpts := []ProgramOption{} | |
| mergedOpts = append(mergedOpts, e.progOpts...) | |
| mergedOpts = append(mergedOpts, opts...) | |
| optSet = mergedOpts | |
| } | |
| return newProgram(e, a, optSet) | |
| } | |
| func (e *Env) initDispatcher() (interpreter.Dispatcher, bool, error) { | |
| e.dispOnce.Do(func() { | |
| if e.parent != nil && e.funcsShared { | |
| // The dispatcher setup is skipped when the child has mutated the function set. | |
| // As the child function set contains a copy of all parent function declarations | |
| // by virtue of copy on write semantics. | |
| d, hasAsync, err := e.parent.initDispatcher() | |
| e.sharedDispatcher = d | |
| e.hasAsync = hasAsync | |
| e.dispErr = err | |
| return | |
| } | |
| hasAsync := false | |
| var bindings []*functions.Overload | |
| for _, fn := range e.functions { | |
| bs, err := fn.Bindings() | |
| if err != nil { | |
| e.dispErr = err | |
| return | |
| } | |
| for _, b := range bs { | |
| if b.Async != nil { | |
| hasAsync = true | |
| } | |
| } | |
| bindings = append(bindings, bs...) | |
| } | |
| d := interpreter.NewDispatcher() | |
| e.dispErr = d.Add(bindings...) | |
| e.sharedDispatcher = d | |
| e.hasAsync = hasAsync | |
| }) | |
| return e.sharedDispatcher, e.hasAsync, e.dispErr | |
| } | |
| // CELTypeAdapter returns the `types.Adapter` configured for the environment. | |
| func (e *Env) CELTypeAdapter() types.Adapter { | |
| return e.adapter | |
| } | |
| // CELTypeProvider returns the `types.Provider` configured for the environment. | |
| func (e *Env) CELTypeProvider() types.Provider { | |
| return e.provider | |
| } | |
| // TypeAdapter returns the `ref.TypeAdapter` configured for the environment. | |
| // | |
| // Deprecated: use CELTypeAdapter() | |
| func (e *Env) TypeAdapter() ref.TypeAdapter { | |
| return e.adapter | |
| } | |
| // TypeProvider returns the `ref.TypeProvider` configured for the environment. | |
| // | |
| // Deprecated: use CELTypeProvider() | |
| func (e *Env) TypeProvider() ref.TypeProvider { | |
| if legacyProvider, ok := e.provider.(ref.TypeProvider); ok { | |
| return legacyProvider | |
| } | |
| return &interopLegacyTypeProvider{Provider: e.provider} | |
| } | |
| // UnknownVars returns a PartialActivation which marks all variables declared in the Env as | |
| // unknown AttributePattern values. | |
| // | |
| // Note, the UnknownVars will behave the same as an cel.NoVars() unless the PartialAttributes | |
| // option is provided as a ProgramOption. | |
| func (e *Env) UnknownVars() PartialActivation { | |
| act := interpreter.EmptyActivation() | |
| part, _ := PartialVars(act, e.computeUnknownVars(act)...) | |
| return part | |
| } | |
| // PartialVars returns a PartialActivation where all variables not in the input variable | |
| // set, but which have been configured in the environment, are marked as unknown. | |
| // | |
| // The `vars` value may either be an Activation or any valid input to the cel.NewActivation call. | |
| // | |
| // Note, this is equivalent to calling cel.PartialVars and manually configuring the set of unknown | |
| // variables. For more advanced use cases of partial state where portions of an object graph, rather | |
| // than top-level variables, are missing the PartialVars() method may be a more suitable choice. | |
| // | |
| // Note, the PartialVars will behave the same as cel.NoVars() unless the PartialAttributes | |
| // option is provided as a ProgramOption. | |
| func (e *Env) PartialVars(vars any) (PartialActivation, error) { | |
| act, err := NewActivation(vars) | |
| if err != nil { | |
| return nil, err | |
| } | |
| return PartialVars(act, e.computeUnknownVars(act)...) | |
| } | |
| // ResidualAst takes an Ast and its EvalDetails to produce a new Ast which only contains the | |
| // attribute references which are unknown. | |
| // | |
| // Residual expressions are beneficial in a few scenarios: | |
| // | |
| // - Optimizing constant expression evaluations away. | |
| // - Indexing and pruning expressions based on known input arguments. | |
| // - Surfacing additional requirements that are needed in order to complete an evaluation. | |
| // - Sharing the evaluation of an expression across multiple machines/nodes. | |
| // | |
| // For example, if an expression targets a 'resource' and 'request' attribute and the possible | |
| // values for the resource are known, a PartialActivation could mark the 'request' as an unknown | |
| // interpreter.AttributePattern and the resulting ResidualAst would be reduced to only the parts | |
| // of the expression that reference the 'request'. | |
| // | |
| // Note, the expression ids within the residual AST generated through this method have no | |
| // correlation to the expression ids of the original AST. | |
| // | |
| // See the PartialVars helper for how to construct a PartialActivation. | |
| // | |
| // TODO: Consider adding an option to generate a Program.Residual to avoid round-tripping to an | |
| // Ast format and then Program again. | |
| func (e *Env) ResidualAst(a *Ast, details *EvalDetails) (*Ast, error) { | |
| ast := a.NativeRep() | |
| pruned := interpreter.PruneAst(ast.Expr(), ast.SourceInfo().MacroCalls(), details.State()) | |
| newAST := &Ast{source: a.Source(), impl: pruned} | |
| expr, err := AstToString(newAST) | |
| if err != nil { | |
| return nil, err | |
| } | |
| parsed, iss := e.Parse(expr) | |
| if iss != nil && iss.Err() != nil { | |
| return nil, iss.Err() | |
| } | |
| if !a.IsChecked() { | |
| return parsed, nil | |
| } | |
| checked, iss := e.Check(parsed) | |
| if iss != nil && iss.Err() != nil { | |
| return nil, iss.Err() | |
| } | |
| return checked, nil | |
| } | |
| // EstimateCost estimates the cost of a type checked CEL expression using the length estimates of input data and | |
| // extension functions provided by estimator. | |
| func (e *Env) EstimateCost(ast *Ast, estimator checker.CostEstimator, opts ...checker.CostOption) (checker.CostEstimate, error) { | |
| extendedOpts := make([]checker.CostOption, 0, len(e.costOptions)) | |
| extendedOpts = append(extendedOpts, opts...) | |
| extendedOpts = append(extendedOpts, e.costOptions...) | |
| return checker.Cost(ast.NativeRep(), estimator, extendedOpts...) | |
| } | |
| // configure applies a series of EnvOptions to the current environment. | |
| func (e *Env) configure(opts []EnvOption) (*Env, error) { | |
| // Customized the environment using the provided EnvOption values. If an error is | |
| // generated at any step this, will be returned as a nil Env with a non-nil error. | |
| var err error | |
| for _, opt := range opts { | |
| e, err = opt(e) | |
| if err != nil { | |
| return nil, err | |
| } | |
| } | |
| // If the default UTC timezone has been disabled, configure the legacy overloads | |
| if utcTime, isSet := e.features[featureDefaultUTCTimeZone]; isSet && !utcTime { | |
| if !e.appliedFeatures[featureDefaultUTCTimeZone] { | |
| e.ensureMutableAppliedFeatures() | |
| e.appliedFeatures[featureDefaultUTCTimeZone] = true | |
| e, err = Lib(timeLegacyLibrary{})(e) | |
| if err != nil { | |
| return nil, err | |
| } | |
| } | |
| } | |
| // Configure the parser. | |
| prsrOpts := []parser.Option{} | |
| prsrOpts = append(prsrOpts, e.prsrOpts...) | |
| prsrOpts = append(prsrOpts, parser.Macros(e.macros...)) | |
| if e.HasFeature(featureEnableMacroCallTracking) { | |
| prsrOpts = append(prsrOpts, parser.PopulateMacroCalls(true)) | |
| } | |
| if e.HasFeature(featureVariadicLogicalASTs) { | |
| prsrOpts = append(prsrOpts, parser.EnableVariadicOperatorASTs(true)) | |
| } | |
| if e.HasFeature(featureIdentEscapeSyntax) { | |
| prsrOpts = append(prsrOpts, parser.EnableIdentEscapeSyntax(true)) | |
| } | |
| if l := e.limits[limitParseErrorRecovery]; l != 0 { | |
| prsrOpts = append(prsrOpts, parser.ErrorRecoveryLimit(l)) | |
| } | |
| if l := e.limits[limitCodePointSize]; l != 0 { | |
| prsrOpts = append(prsrOpts, parser.ExpressionSizeCodePointLimit(l)) | |
| } | |
| if l := e.limits[limitParseRecursionDepth]; l != 0 { | |
| prsrOpts = append(prsrOpts, parser.MaxRecursionDepth(l)) | |
| } | |
| if l := e.limits[limitExpressionNodeCount]; l != 0 { | |
| prsrOpts = append(prsrOpts, parser.MaxExpressionNodeCount(l)) | |
| } | |
| e.prsr, err = parser.NewParser(prsrOpts...) | |
| if err != nil { | |
| return nil, err | |
| } | |
| // Enable JSON field names is using a proto-based *types.Registry | |
| if e.HasFeature(featureJSONFieldNames) { | |
| reg, isReg := e.provider.(*types.Registry) | |
| if !isReg { | |
| return nil, fmt.Errorf("JSONFieldNames() option is only compatible with *types.Registry providers") | |
| } | |
| err := reg.WithJSONFieldNames(true) | |
| if err != nil { | |
| return nil, err | |
| } | |
| } | |
| // Ensure that the checker init happens eagerly rather than lazily. | |
| if e.HasFeature(featureEagerlyValidateDeclarations) { | |
| _, err := e.initChecker() | |
| if err != nil { | |
| return nil, err | |
| } | |
| } | |
| return e, nil | |
| } | |
| func (e *Env) initChecker() (*checker.Env, error) { | |
| e.chkOnce.Do(func() { | |
| chkOpts := []checker.Option{} | |
| chkOpts = append(chkOpts, e.chkOpts...) | |
| chkOpts = append(chkOpts, | |
| checker.CrossTypeNumericComparisons( | |
| e.HasFeature(featureCrossTypeNumericComparisons))) | |
| chkOpts = append(chkOpts, | |
| checker.JSONFieldNames(e.HasFeature(featureJSONFieldNames))) | |
| if e.parent != nil && e.funcsShared { | |
| parentChk, err := e.parent.initChecker() | |
| if err != nil { | |
| e.setCheckerOrError(nil, err) | |
| return | |
| } | |
| chkOpts = append(chkOpts, checker.ValidatedDeclarations(parentChk)) | |
| } | |
| ce, err := checker.NewEnv(e.Container, e.provider, chkOpts...) | |
| if err != nil { | |
| e.setCheckerOrError(nil, err) | |
| return | |
| } | |
| // Add the statically configured declarations. | |
| err = ce.AddIdents(e.variables...) | |
| if err != nil { | |
| e.setCheckerOrError(nil, err) | |
| return | |
| } | |
| // Add the function declarations which are derived from the FunctionDecl instances. | |
| if e.parent == nil || !e.funcsShared { | |
| for _, fn := range e.functions { | |
| if fn.IsDeclarationDisabled() { | |
| continue | |
| } | |
| err = ce.AddFunctions(fn) | |
| if err != nil { | |
| e.setCheckerOrError(nil, err) | |
| return | |
| } | |
| } | |
| } | |
| // Add function declarations here separately. | |
| e.setCheckerOrError(ce, nil) | |
| }) | |
| return e.getCheckerOrError() | |
| } | |
| // setCheckerOrError sets the checker.Env or error state in a concurrency-safe manner | |
| func (e *Env) setCheckerOrError(chk *checker.Env, chkErr error) { | |
| e.chkMutex.Lock() | |
| e.chk = chk | |
| e.chkErr = chkErr | |
| e.chkMutex.Unlock() | |
| } | |
| // getCheckerOrError gets the checker.Env or error state in a concurrency-safe manner | |
| func (e *Env) getCheckerOrError() (*checker.Env, error) { | |
| e.chkMutex.Lock() | |
| defer e.chkMutex.Unlock() | |
| return e.chk, e.chkErr | |
| } | |
| // computeUnknownVars determines a set of missing variables based on the input activation and the | |
| // environment's configured declaration set. | |
| func (e *Env) computeUnknownVars(vars Activation) []*interpreter.AttributePattern { | |
| var unknownPatterns []*interpreter.AttributePattern | |
| for _, v := range e.variables { | |
| varName := v.Name() | |
| if _, found := vars.ResolveName(varName); found { | |
| continue | |
| } | |
| unknownPatterns = append(unknownPatterns, interpreter.NewAttributePattern(varName)) | |
| } | |
| return unknownPatterns | |
| } | |
| // Error type which references an expression id, a location within source, and a message. | |
| type Error = common.Error | |
| // Issues defines methods for inspecting the error details of parse and check calls. | |
| // | |
| // Note: in the future, non-fatal warnings and notices may be inspectable via the Issues struct. | |
| type Issues struct { | |
| errs *common.Errors | |
| info *celast.SourceInfo | |
| } | |
| // ErrorAsIssues wraps a Golang error into a CEL common error and issue set. | |
| // | |
| // This is a convenience method for early returning from an expression validation call path due to | |
| // internal state or configuration which is unrelated to the source being validated. | |
| func ErrorAsIssues(err error) *Issues { | |
| errs := common.NewErrors(common.NewTextSource("")) | |
| errs.ReportErrorString(common.NoLocation, err.Error()) | |
| return NewIssues(errs) | |
| } | |
| // NewIssues returns an Issues struct from a common.Errors object. | |
| func NewIssues(errs *common.Errors) *Issues { | |
| return NewIssuesWithSourceInfo(errs, nil) | |
| } | |
| // NewIssuesWithSourceInfo returns an Issues struct from a common.Errors object with SourceInfo metatata | |
| // which can be used with the `ReportErrorAtID` method for additional error reports within the context | |
| // information that's inferred from an expression id. | |
| func NewIssuesWithSourceInfo(errs *common.Errors, info *celast.SourceInfo) *Issues { | |
| return &Issues{ | |
| errs: errs, | |
| info: info, | |
| } | |
| } | |
| // Err returns an error value if the issues list contains one or more errors. | |
| func (i *Issues) Err() error { | |
| if i == nil { | |
| return nil | |
| } | |
| if len(i.Errors()) > 0 { | |
| return errors.New(i.String()) | |
| } | |
| return nil | |
| } | |
| // Errors returns the collection of errors encountered in more granular detail. | |
| func (i *Issues) Errors() []*Error { | |
| if i == nil { | |
| return []*Error{} | |
| } | |
| return i.errs.GetErrors() | |
| } | |
| // Append collects the issues from another Issues struct into a new Issues object. | |
| func (i *Issues) Append(other *Issues) *Issues { | |
| if i == nil { | |
| return other | |
| } | |
| if other == nil || i == other { | |
| return i | |
| } | |
| return NewIssuesWithSourceInfo(i.errs.Append(other.errs.GetErrors()), i.info) | |
| } | |
| // String converts the issues to a suitable display string. | |
| func (i *Issues) String() string { | |
| if i == nil { | |
| return "" | |
| } | |
| return i.errs.ToDisplayString() | |
| } | |
| // ReportErrorAtID reports an error message with an optional set of formatting arguments. | |
| // | |
| // The source metadata for the expression at `id`, if present, is attached to the error report. | |
| // To ensure that source metadata is attached to error reports, use NewIssuesWithSourceInfo. | |
| func (i *Issues) ReportErrorAtID(id int64, message string, args ...any) { | |
| i.errs.ReportErrorAtID(id, i.info.GetStartLocation(id), message, args...) | |
| } | |
| // getStdEnv lazy initializes the CEL standard environment. | |
| func getStdEnv() (*Env, error) { | |
| stdEnvInit.Do(func() { | |
| stdEnv, stdEnvErr = NewCustomEnv(StdLib(), EagerlyValidateDeclarations(true)) | |
| }) | |
| return stdEnv, stdEnvErr | |
| } | |
| // interopCELTypeProvider layers support for the types.Provider interface on top of a ref.TypeProvider. | |
| type interopCELTypeProvider struct { | |
| ref.TypeProvider | |
| } | |
| // FindStructType returns a types.Type instance for the given fully-qualified typeName if one exists. | |
| // | |
| // This method proxies to the underlying ref.TypeProvider's FindType method and converts protobuf type | |
| // into a native type representation. If the conversion fails, the type is listed as not found. | |
| func (p *interopCELTypeProvider) FindStructType(typeName string) (*types.Type, bool) { | |
| if et, found := p.FindType(typeName); found { | |
| t, err := types.ExprTypeToType(et) | |
| if err != nil { | |
| return nil, false | |
| } | |
| return t, true | |
| } | |
| return nil, false | |
| } | |
| // FindStructFieldNames returns an empty set of field for the interop provider. | |
| // | |
| // To inspect the field names, migrate to a `types.Provider` implementation. | |
| func (p *interopCELTypeProvider) FindStructFieldNames(typeName string) ([]string, bool) { | |
| return []string{}, false | |
| } | |
| // FindStructFieldType returns a types.FieldType instance for the given fully-qualified typeName and field | |
| // name, if one exists. | |
| // | |
| // This method proxies to the underlying ref.TypeProvider's FindFieldType method and converts protobuf type | |
| // into a native type representation. If the conversion fails, the type is listed as not found. | |
| func (p *interopCELTypeProvider) FindStructFieldType(structType, fieldName string) (*types.FieldType, bool) { | |
| if ft, found := p.FindFieldType(structType, fieldName); found { | |
| t, err := types.ExprTypeToType(ft.Type) | |
| if err != nil { | |
| return nil, false | |
| } | |
| return &types.FieldType{ | |
| Type: t, | |
| IsSet: ft.IsSet, | |
| GetFrom: ft.GetFrom, | |
| IsJSONField: ft.IsJSONField, | |
| }, true | |
| } | |
| return nil, false | |
| } | |
| // interopLegacyTypeProvider layers support for the ref.TypeProvider interface on top of a types.Provider. | |
| type interopLegacyTypeProvider struct { | |
| types.Provider | |
| } | |
| // FindType retruns the protobuf Type representation for the input type name if one exists. | |
| // | |
| // This method proxies to the underlying types.Provider FindStructType method and converts the types.Type | |
| // value to a protobuf Type representation. | |
| // | |
| // Failure to convert the type will result in the type not being found. | |
| func (p *interopLegacyTypeProvider) FindType(typeName string) (*exprpb.Type, bool) { | |
| if t, found := p.FindStructType(typeName); found { | |
| et, err := types.TypeToExprType(t) | |
| if err != nil { | |
| return nil, false | |
| } | |
| return et, true | |
| } | |
| return nil, false | |
| } | |
| // FindFieldType returns the protobuf-based FieldType representation for the input type name and field, | |
| // if one exists. | |
| // | |
| // This call proxies to the types.Provider FindStructFieldType method and converts the types.FIeldType | |
| // value to a protobuf-based ref.FieldType representation if found. | |
| // | |
| // Failure to convert the FieldType will result in the field not being found. | |
| func (p *interopLegacyTypeProvider) FindFieldType(structType, fieldName string) (*ref.FieldType, bool) { | |
| if cft, found := p.FindStructFieldType(structType, fieldName); found { | |
| et, err := types.TypeToExprType(cft.Type) | |
| if err != nil { | |
| return nil, false | |
| } | |
| return &ref.FieldType{ | |
| Type: et, | |
| IsSet: cft.IsSet, | |
| GetFrom: cft.GetFrom, | |
| }, true | |
| } | |
| return nil, false | |
| } | |
| var ( | |
| stdEnvInit sync.Once | |
| stdEnv *Env | |
| stdEnvErr error | |
| ) |