Documentation ¶
Overview ¶
Package rego exposes high level APIs for evaluating Rego policies.
Index ¶
- func BuiltinErrorList(list *[]topdown.Error) func(r *Rego)
- func Capabilities(c *ast.Capabilities) func(r *Rego)
- func Compiler(c *ast.Compiler) func(r *Rego)
- func DisableInlining(paths []string) func(r *Rego)
- func DistributedTracingOpts(tr tracing.Options) func(r *Rego)
- func Dump(w io.Writer) func(r *Rego)
- func EnablePrintStatements(yes bool) func(r *Rego)
- func Function1(decl *Function, f Builtin1) func(*Rego)
- func Function2(decl *Function, f Builtin2) func(*Rego)
- func Function3(decl *Function, f Builtin3) func(*Rego)
- func Function4(decl *Function, f Builtin4) func(*Rego)
- func FunctionDecl(decl *Function) func(*Rego)
- func FunctionDyn(decl *Function, f BuiltinDyn) func(*Rego)
- func GenerateJSON(f func(*ast.Term, *EvalContext) (interface{}, error)) func(r *Rego)
- func Imports(p []string) func(r *Rego)
- func Input(x interface{}) func(r *Rego)
- func Instrument(yes bool) func(r *Rego)
- func InterQueryBuiltinCache(c cache.InterQueryCache) func(r *Rego)
- func InterQueryBuiltinValueCache(c cache.InterQueryValueCache) func(r *Rego)
- func IsPartialEvaluationNotEffectiveErr(err error) bool
- func Load(paths []string, filter loader.Filter) func(r *Rego)
- func LoadBundle(path string) func(r *Rego)
- func Metrics(m metrics.Metrics) func(r *Rego)
- func Module(filename, input string) func(r *Rego)
- func NDBuiltinCache(c builtins.NDBCache) func(r *Rego)
- func NewHaltError(err error) error
- func Package(p string) func(r *Rego)
- func ParsedBundle(name string, b *bundle.Bundle) func(r *Rego)
- func ParsedImports(imp []*ast.Import) func(r *Rego)
- func ParsedInput(x ast.Value) func(r *Rego)
- func ParsedModule(module *ast.Module) func(*Rego)
- func ParsedPackage(pkg *ast.Package) func(r *Rego)
- func ParsedQuery(q ast.Body) func(r *Rego)
- func ParsedUnknowns(unknowns []*ast.Term) func(r *Rego)
- func PartialNamespace(ns string) func(r *Rego)
- func PrintHook(h print.Hook) func(r *Rego)
- func PrintTrace(w io.Writer, r *Rego)
- func PrintTraceWithLocation(w io.Writer, r *Rego)
- func Query(q string) func(r *Rego)
- func QueryTracer(t topdown.QueryTracer) func(r *Rego)
- func RegisterBuiltin1(decl *Function, impl Builtin1)
- func RegisterBuiltin2(decl *Function, impl Builtin2)
- func RegisterBuiltin3(decl *Function, impl Builtin3)
- func RegisterBuiltin4(decl *Function, impl Builtin4)
- func RegisterBuiltinDyn(decl *Function, impl BuiltinDyn)
- func RegisterPlugin(name string, p TargetPlugin)
- func Resolver(ref ast.Ref, r resolver.Resolver) func(r *Rego)
- func Runtime(term *ast.Term) func(r *Rego)
- func Schemas(x *ast.SchemaSet) func(r *Rego)
- func Seed(r io.Reader) func(*Rego)
- func SetRegoVersion(version ast.RegoVersion) func(r *Rego)
- func ShallowInlining(yes bool) func(r *Rego)
- func SkipBundleVerification(yes bool) func(r *Rego)
- func SkipPartialNamespace(yes bool) func(r *Rego)
- func Store(s storage.Store) func(r *Rego)
- func StoreReadAST(enabled bool) func(r *Rego)
- func Strict(yes bool) func(r *Rego)
- func StrictBuiltinErrors(yes bool) func(r *Rego)
- func Target(t string) func(r *Rego)
- func Time(x time.Time) func(r *Rego)
- func Trace(yes bool) func(r *Rego)
- func Tracer(t topdown.Tracer) func(r *Rego)
- func Transaction(txn storage.Transaction) func(r *Rego)
- func Unknowns(unknowns []string) func(r *Rego)
- func UnsafeBuiltins(unsafeBuiltins map[string]struct{}) func(r *Rego)
- type Builtin1
- type Builtin2
- type Builtin3
- type Builtin4
- type BuiltinContext
- type BuiltinDyn
- type CompileContext
- type CompileOption
- type CompileResult
- type ErrorDetails
- type Errors
- type EvalContext
- func (e *EvalContext) Capabilities() *ast.Capabilities
- func (e *EvalContext) CompiledQuery() ast.Body
- func (e *EvalContext) InterQueryBuiltinCache() cache.InterQueryCache
- func (e *EvalContext) InterQueryBuiltinValueCache() cache.InterQueryValueCache
- func (e *EvalContext) Metrics() metrics.Metrics
- func (e *EvalContext) NDBCache() builtins.NDBCache
- func (e *EvalContext) ParsedInput() ast.Value
- func (e *EvalContext) PrintHook() print.Hook
- func (e *EvalContext) RawInput() *interface{}
- func (e *EvalContext) Seed() io.Reader
- func (e *EvalContext) StrictBuiltinErrors() bool
- func (e *EvalContext) Time() time.Time
- func (e *EvalContext) Transaction() storage.Transaction
- type EvalOption
- func EvalCopyMaps(yes bool) EvalOption
- func EvalDisableInlining(paths []ast.Ref) EvalOption
- func EvalEarlyExit(enabled bool) EvalOption
- func EvalInput(input interface{}) EvalOption
- func EvalInstrument(instrument bool) EvalOption
- func EvalInterQueryBuiltinCache(c cache.InterQueryCache) EvalOption
- func EvalInterQueryBuiltinValueCache(c cache.InterQueryValueCache) EvalOption
- func EvalMetrics(metric metrics.Metrics) EvalOption
- func EvalNDBuiltinCache(c builtins.NDBCache) EvalOption
- func EvalParsedInput(input ast.Value) EvalOption
- func EvalParsedUnknowns(unknowns []*ast.Term) EvalOption
- func EvalPartialNamespace(ns string) EvalOption
- func EvalPrintHook(ph print.Hook) EvalOption
- func EvalQueryTracer(tracer topdown.QueryTracer) EvalOption
- func EvalResolver(ref ast.Ref, r resolver.Resolver) EvalOption
- func EvalRuleIndexing(enabled bool) EvalOption
- func EvalSeed(r io.Reader) EvalOption
- func EvalSortSets(yes bool) EvalOption
- func EvalTime(x time.Time) EvalOption
- func EvalTracer(tracer topdown.Tracer) EvalOption
- func EvalTransaction(txn storage.Transaction) EvalOption
- func EvalUnknowns(unknowns []string) EvalOption
- func EvalVirtualCache(vc topdown.VirtualCache) EvalOption
- type ExpressionValue
- type Function
- type HaltError
- type Location
- type PartialQueries
- type PartialResult
- type PrepareConfig
- type PrepareOption
- type PreparedEvalQuery
- type PreparedPartialQuery
- type Rego
- func (r *Rego) Compile(ctx context.Context, opts ...CompileOption) (*CompileResult, error)
- func (r *Rego) Eval(ctx context.Context) (ResultSet, error)
- func (r *Rego) Partial(ctx context.Context) (*PartialQueries, error)
- func (r *Rego) PartialEval(ctx context.Context) (PartialResult, error)
- func (r *Rego) PartialResult(ctx context.Context) (PartialResult, error)
- func (r *Rego) PrepareForEval(ctx context.Context, opts ...PrepareOption) (PreparedEvalQuery, error)
- func (r *Rego) PrepareForPartial(ctx context.Context, opts ...PrepareOption) (PreparedPartialQuery, error)
- type Result
- type ResultSet
- type TargetPlugin
- type TargetPluginEval
- type Vars
Examples ¶
- Rego (Custom_function_caching)
- Rego (Custom_function_global)
- Rego (Custom_function_nondeterministic)
- Rego (Custom_functional_builtin)
- Rego (Print_statements)
- Rego.Eval (Allowed)
- Rego.Eval (Compiler)
- Rego.Eval (Errors)
- Rego.Eval (Input)
- Rego.Eval (MultipleBindings)
- Rego.Eval (MultipleDocuments)
- Rego.Eval (Persistent_storage)
- Rego.Eval (Simple)
- Rego.Eval (SingleDocument)
- Rego.Eval (Storage)
- Rego.Eval (Trace_simple)
- Rego.Eval (Tracer)
- Rego.Eval (Transactions)
- Rego.Partial
- Rego.PartialResult
- Rego.PrepareForEval
- Rego.PrepareForPartial
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuiltinErrorList ¶ added in v0.48.0
BuiltinErrorList supplies an error slice to store built-in function errors.
func Capabilities ¶ added in v0.32.0
func Capabilities(c *ast.Capabilities) func(r *Rego)
Capabilities configures the underlying compiler's capabilities. This option is ignored for module compilation if the caller supplies the compiler.
func DisableInlining ¶ added in v0.13.0
DisableInlining adds a set of paths to exclude from partial evaluation inlining.
func DistributedTracingOpts ¶ added in v0.36.0
DistributedTracingOpts sets the options to be used by distributed tracing.
func Dump ¶ added in v0.10.0
Dump returns an argument that sets the writer to dump debugging information to.
func EnablePrintStatements ¶ added in v0.34.0
EnablePrintStatements enables print() calls. If this option is not provided, print() calls will be erased from the policy. This option only applies to queries and policies that passed as raw strings, i.e., this function will not have any affect if the caller supplies the ast.Compiler instance.
func Function1 ¶ added in v0.14.0
Function1 returns an option that adds a built-in function to the Rego object.
func Function2 ¶ added in v0.14.0
Function2 returns an option that adds a built-in function to the Rego object.
func Function3 ¶ added in v0.14.0
Function3 returns an option that adds a built-in function to the Rego object.
func Function4 ¶ added in v0.14.0
Function4 returns an option that adds a built-in function to the Rego object.
func FunctionDecl ¶ added in v0.15.1
FunctionDecl returns an option that adds a custom-built-in function __declaration__. NO implementation is provided. This is used for non-interpreter execution envs (e.g., Wasm).
func FunctionDyn ¶ added in v0.14.0
func FunctionDyn(decl *Function, f BuiltinDyn) func(*Rego)
FunctionDyn returns an option that adds a built-in function to the Rego object.
func GenerateJSON ¶ added in v0.32.0
func GenerateJSON(f func(*ast.Term, *EvalContext) (interface{}, error)) func(r *Rego)
GenerateJSON sets the AST to JSON converter for the results.
func Input ¶
func Input(x interface{}) func(r *Rego)
Input returns an argument that sets the Rego input document. Input should be a native Go value representing the input document.
func Instrument ¶ added in v0.7.0
Instrument returns an argument that enables instrumentation for diagnosing performance issues.
func InterQueryBuiltinCache ¶ added in v0.23.0
func InterQueryBuiltinCache(c cache.InterQueryCache) func(r *Rego)
InterQueryBuiltinCache sets the inter-query cache that built-in functions can utilize during evaluation.
func InterQueryBuiltinValueCache ¶ added in v0.69.0
func InterQueryBuiltinValueCache(c cache.InterQueryValueCache) func(r *Rego)
InterQueryBuiltinValueCache sets the inter-query value cache that built-in functions can utilize during evaluation.
func IsPartialEvaluationNotEffectiveErr ¶ added in v0.21.0
IsPartialEvaluationNotEffectiveErr returns true if err is an error returned by this package to indicate that partial evaluation was ineffective.
func Load ¶ added in v0.14.0
Load returns an argument that adds a filesystem path to load data and Rego modules from. Any file with a *.rego, *.yaml, or *.json extension will be loaded. The path can be either a directory or file, directories are loaded recursively. The optional ignore string patterns can be used to filter which files are used. The Load option can only be used once. Note: Loading files will require a write transaction on the store.
func LoadBundle ¶ added in v0.14.0
LoadBundle returns an argument that adds a filesystem path to load a bundle from. The path can be a compressed bundle file or a directory to be loaded as a bundle. Note: Loading bundles will require a write transaction on the store.
func NDBuiltinCache ¶ added in v0.44.0
NDBuiltinCache sets the non-deterministic builtins cache.
func NewHaltError ¶ added in v0.31.0
NewHaltError wraps an error such that the evaluation process will stop when it occurs.
func ParsedBundle ¶ added in v0.14.0
ParsedBundle returns an argument that adds a bundle to be loaded.
func ParsedImports ¶ added in v0.7.0
ParsedImports returns an argument that adds Rego imports to the query's context.
func ParsedInput ¶ added in v0.7.0
ParsedInput returns an argument that sets the Rego input document.
func ParsedModule ¶ added in v0.13.0
ParsedModule returns an argument that adds a parsed Rego module. If a string module with the same filename name is added, it will override the parsed module.
func ParsedPackage ¶ added in v0.7.0
ParsedPackage returns an argument that sets the Rego package on the query's context.
func ParsedQuery ¶ added in v0.7.0
ParsedQuery returns an argument that sets the Rego query.
func ParsedUnknowns ¶ added in v0.9.0
ParsedUnknowns returns an argument that sets the values to treat as unknown during partial evaluation.
func PartialNamespace ¶ added in v0.7.0
PartialNamespace returns an argument that sets the namespace to use for partial evaluation results. The namespace must be a valid package path component.
func PrintHook ¶ added in v0.34.0
PrintHook sets the object to use for handling print statement outputs.
func PrintTrace ¶ added in v0.10.2
PrintTrace is a helper function to write a human-readable version of the trace to the writer w.
func PrintTraceWithLocation ¶ added in v0.20.0
PrintTraceWithLocation is a helper function to write a human-readable version of the trace to the writer w.
func QueryTracer ¶ added in v0.22.0
func QueryTracer(t topdown.QueryTracer) func(r *Rego)
QueryTracer returns an argument that adds a query tracer to r.
func RegisterBuiltin1 ¶ added in v0.19.0
RegisterBuiltin1 adds a built-in function globally inside the OPA runtime.
func RegisterBuiltin2 ¶ added in v0.19.0
RegisterBuiltin2 adds a built-in function globally inside the OPA runtime.
func RegisterBuiltin3 ¶ added in v0.19.0
RegisterBuiltin3 adds a built-in function globally inside the OPA runtime.
func RegisterBuiltin4 ¶ added in v0.19.0
RegisterBuiltin4 adds a built-in function globally inside the OPA runtime.
func RegisterBuiltinDyn ¶ added in v0.19.0
func RegisterBuiltinDyn(decl *Function, impl BuiltinDyn)
RegisterBuiltinDyn adds a built-in function globally inside the OPA runtime.
func RegisterPlugin ¶ added in v0.53.0
func RegisterPlugin(name string, p TargetPlugin)
func Runtime ¶ added in v0.10.0
Runtime returns an argument that sets the runtime data to provide to the evaluation engine.
func Seed ¶ added in v0.30.0
Seed sets a reader that will seed randomization required by built-in functions. If a seed is not provided crypto/rand.Reader is used.
func SetRegoVersion ¶ added in v0.60.0
func SetRegoVersion(version ast.RegoVersion) func(r *Rego)
func ShallowInlining ¶ added in v0.22.0
ShallowInlining prevents rules that depend on unknown values from being inlined. Rules that only depend on known values are inlined.
func SkipBundleVerification ¶ added in v0.22.0
SkipBundleVerification skips verification of a signed bundle.
func SkipPartialNamespace ¶ added in v0.20.0
SkipPartialNamespace disables namespacing of partial evalution results for support rules generated from policy. Synthetic support rules are still namespaced.
func Store ¶ added in v0.5.0
Store returns an argument that sets the policy engine's data storage layer.
If using the Load, LoadBundle, or ParsedBundle options then a transaction must also be provided via the Transaction() option. After loading files or bundles the transaction should be aborted or committed.
func StoreReadAST ¶ added in v0.70.0
StoreReadAST returns an argument that sets whether the store should eagerly convert data to AST values.
Only applicable when no store has been set on the Rego object through the Store option.
func StrictBuiltinErrors ¶ added in v0.25.0
StrictBuiltinErrors tells the evaluator to treat all built-in function errors as fatal errors.
func Time ¶ added in v0.23.0
Time sets the wall clock time to use during policy evaluation. Prepared queries do not inherit this parameter. Use EvalTime to set the wall clock time when executing a prepared query.
func Tracer ¶ added in v0.5.3
Tracer returns an argument that adds a query tracer to r. Deprecated: Use QueryTracer instead.
func Transaction ¶ added in v0.5.2
func Transaction(txn storage.Transaction) func(r *Rego)
Transaction returns an argument that sets the transaction to use for storage layer operations.
Requires the store associated with the transaction to be provided via the Store() option. If using Load(), LoadBundle(), or ParsedBundle() options the transaction will likely require write params.
func Unknowns ¶ added in v0.7.0
Unknowns returns an argument that sets the values to treat as unknown during partial evaluation.
func UnsafeBuiltins ¶ added in v0.13.0
UnsafeBuiltins sets the built-in functions to treat as unsafe and not allow. This option is ignored for module compilation if the caller supplies the compiler. This option is always honored for query compilation. Provide an empty (non-nil) map to disable checks on queries.
Types ¶
type BuiltinContext ¶ added in v0.14.0
type BuiltinContext = topdown.BuiltinContext
BuiltinContext contains additional attributes from the evaluator that built-in functions can use, e.g., the request context.Context, caches, etc.
type BuiltinDyn ¶ added in v0.14.0
BuiltinDyn defines a built-in function that accepts a list of arguments.
type CompileContext ¶ added in v0.11.0
type CompileContext struct {
// contains filtered or unexported fields
}
CompileContext contains options for Compile calls.
type CompileOption ¶ added in v0.11.0
type CompileOption func(*CompileContext)
CompileOption defines a function to set options on Compile calls.
func CompilePartial ¶ added in v0.11.0
func CompilePartial(yes bool) CompileOption
CompilePartial defines an option to control whether partial evaluation is run before the query is planned and compiled.
type CompileResult ¶ added in v0.10.0
type CompileResult struct {
Bytes []byte `json:"bytes"`
}
CompileResult represents the result of compiling a Rego query, zero or more Rego modules, and arbitrary contextual data into an executable.
type ErrorDetails ¶ added in v0.32.0
type ErrorDetails interface {
Lines() []string
}
ErrorDetails interface is satisfied by an error that provides further details.
type Errors ¶
type Errors []error
Errors represents a collection of errors returned when evaluating Rego.
type EvalContext ¶ added in v0.11.0
type EvalContext struct {
// contains filtered or unexported fields
}
EvalContext defines the set of options allowed to be set at evaluation time. Any other options will need to be set on a new Rego object.
func (*EvalContext) Capabilities ¶ added in v0.53.0
func (e *EvalContext) Capabilities() *ast.Capabilities
func (*EvalContext) CompiledQuery ¶ added in v0.53.0
func (e *EvalContext) CompiledQuery() ast.Body
func (*EvalContext) InterQueryBuiltinCache ¶ added in v0.53.0
func (e *EvalContext) InterQueryBuiltinCache() cache.InterQueryCache
func (*EvalContext) InterQueryBuiltinValueCache ¶ added in v0.69.0
func (e *EvalContext) InterQueryBuiltinValueCache() cache.InterQueryValueCache
func (*EvalContext) Metrics ¶ added in v0.53.0
func (e *EvalContext) Metrics() metrics.Metrics
func (*EvalContext) NDBCache ¶ added in v0.53.0
func (e *EvalContext) NDBCache() builtins.NDBCache
func (*EvalContext) ParsedInput ¶ added in v0.53.0
func (e *EvalContext) ParsedInput() ast.Value
func (*EvalContext) PrintHook ¶ added in v0.53.0
func (e *EvalContext) PrintHook() print.Hook
func (*EvalContext) RawInput ¶ added in v0.53.0
func (e *EvalContext) RawInput() *interface{}
func (*EvalContext) Seed ¶ added in v0.53.0
func (e *EvalContext) Seed() io.Reader
func (*EvalContext) StrictBuiltinErrors ¶ added in v0.53.0
func (e *EvalContext) StrictBuiltinErrors() bool
func (*EvalContext) Time ¶ added in v0.53.0
func (e *EvalContext) Time() time.Time
func (*EvalContext) Transaction ¶ added in v0.53.0
func (e *EvalContext) Transaction() storage.Transaction
type EvalOption ¶ added in v0.11.0
type EvalOption func(*EvalContext)
EvalOption defines a function to set an option on an EvalConfig
func EvalCopyMaps ¶ added in v0.47.0
func EvalCopyMaps(yes bool) EvalOption
EvalCopyMaps causes the evaluator to copy `map[string]interface{}`s before returning them.
func EvalDisableInlining ¶ added in v0.13.0
func EvalDisableInlining(paths []ast.Ref) EvalOption
EvalDisableInlining returns an argument that adds a set of paths to exclude from partial evaluation inlining.
func EvalEarlyExit ¶ added in v0.35.0
func EvalEarlyExit(enabled bool) EvalOption
EvalEarlyExit will disable 'early exit' optimizations for the evaluation. This should only be used when tracing in debug mode.
func EvalInput ¶ added in v0.11.0
func EvalInput(input interface{}) EvalOption
EvalInput configures the input for a Prepared Query's evaluation
func EvalInstrument ¶ added in v0.11.0
func EvalInstrument(instrument bool) EvalOption
EvalInstrument enables or disables instrumenting for a Prepared Query's evaluation
func EvalInterQueryBuiltinCache ¶ added in v0.23.0
func EvalInterQueryBuiltinCache(c cache.InterQueryCache) EvalOption
EvalInterQueryBuiltinCache sets the inter-query cache that built-in functions can utilize during evaluation.
func EvalInterQueryBuiltinValueCache ¶ added in v0.69.0
func EvalInterQueryBuiltinValueCache(c cache.InterQueryValueCache) EvalOption
EvalInterQueryBuiltinValueCache sets the inter-query value cache that built-in functions can utilize during evaluation.
func EvalMetrics ¶ added in v0.11.0
func EvalMetrics(metric metrics.Metrics) EvalOption
EvalMetrics configures the metrics for a Prepared Query's evaluation
func EvalNDBuiltinCache ¶ added in v0.44.0
func EvalNDBuiltinCache(c builtins.NDBCache) EvalOption
EvalNDBuiltinCache sets the non-deterministic builtin cache that built-in functions can use during evaluation.
func EvalParsedInput ¶ added in v0.11.0
func EvalParsedInput(input ast.Value) EvalOption
EvalParsedInput configures the input for a Prepared Query's evaluation
func EvalParsedUnknowns ¶ added in v0.11.0
func EvalParsedUnknowns(unknowns []*ast.Term) EvalOption
EvalParsedUnknowns returns an argument that sets the values to treat as unknown during partial evaluation.
func EvalPartialNamespace ¶ added in v0.11.0
func EvalPartialNamespace(ns string) EvalOption
EvalPartialNamespace returns an argument that sets the namespace to use for partial evaluation results. The namespace must be a valid package path component.
func EvalPrintHook ¶ added in v0.35.0
func EvalPrintHook(ph print.Hook) EvalOption
EvalPrintHook sets the object to use for handling print statement outputs.
func EvalQueryTracer ¶ added in v0.22.0
func EvalQueryTracer(tracer topdown.QueryTracer) EvalOption
EvalQueryTracer configures a tracer for a Prepared Query's evaluation
func EvalResolver ¶ added in v0.25.0
func EvalResolver(ref ast.Ref, r resolver.Resolver) EvalOption
EvalResolver sets a Resolver for a specified ref path for this evaluation.
func EvalRuleIndexing ¶ added in v0.15.0
func EvalRuleIndexing(enabled bool) EvalOption
EvalRuleIndexing will disable indexing optimizations for the evaluation. This should only be used when tracing in debug mode.
func EvalSeed ¶ added in v0.30.0
func EvalSeed(r io.Reader) EvalOption
EvalSeed sets a reader that will seed randomization required by built-in functions. If a seed is not provided crypto/rand.Reader is used.
func EvalSortSets ¶ added in v0.27.1
func EvalSortSets(yes bool) EvalOption
EvalSortSets causes the evaluator to sort sets before returning them as JSON arrays.
func EvalTime ¶ added in v0.23.0
func EvalTime(x time.Time) EvalOption
EvalTime sets the wall clock time to use during policy evaluation. time.now_ns() calls will return this value.
func EvalTracer ¶ added in v0.11.0
func EvalTracer(tracer topdown.Tracer) EvalOption
EvalTracer configures a tracer for a Prepared Query's evaluation Deprecated: Use EvalQueryTracer instead.
func EvalTransaction ¶ added in v0.11.0
func EvalTransaction(txn storage.Transaction) EvalOption
EvalTransaction configures the Transaction for a Prepared Query's evaluation
func EvalUnknowns ¶ added in v0.11.0
func EvalUnknowns(unknowns []string) EvalOption
EvalUnknowns returns an argument that sets the values to treat as unknown during partial evaluation.
func EvalVirtualCache ¶ added in v0.68.0
func EvalVirtualCache(vc topdown.VirtualCache) EvalOption
EvalVirtualCache sets the topdown.VirtualCache to use for evaluation. This is optional, and if not set, the default cache is used.
type ExpressionValue ¶
type ExpressionValue struct { Value interface{} `json:"value"` Text string `json:"text"` Location *Location `json:"location"` }
ExpressionValue defines the value of an expression in a Rego query.
func (*ExpressionValue) String ¶ added in v0.10.2
func (ev *ExpressionValue) String() string
type Function ¶ added in v0.14.0
type Function struct { Name string Description string Decl *types.Function Memoize bool Nondeterministic bool }
Function represents a built-in function that is callable in Rego.
type HaltError ¶ added in v0.31.0
type HaltError struct {
// contains filtered or unexported fields
}
HaltError is an error type to return from a custom function implementation that will abort the evaluation process (analogous to topdown.Halt).
type PartialQueries ¶ added in v0.9.0
type PartialQueries struct { Queries []ast.Body `json:"queries,omitempty"` Support []*ast.Module `json:"modules,omitempty"` }
PartialQueries contains the queries and support modules produced by partial evaluation.
type PartialResult ¶ added in v0.7.0
type PartialResult struct {
// contains filtered or unexported fields
}
PartialResult represents the result of partial evaluation. The result can be used to generate a new query that can be run when inputs are known.
func (PartialResult) Rego ¶ added in v0.7.0
func (pr PartialResult) Rego(options ...func(*Rego)) *Rego
Rego returns an object that can be evaluated to produce a query result.
type PrepareConfig ¶ added in v0.11.0
type PrepareConfig struct {
// contains filtered or unexported fields
}
PrepareConfig holds settings to control the behavior of the Prepare call.
func (*PrepareConfig) BuiltinFuncs ¶ added in v0.56.0
func (p *PrepareConfig) BuiltinFuncs() map[string]*topdown.Builtin
BuiltinFuncs allows retrieving the builtin funcs set via PrepareOption WithBuiltinFuncs.
type PrepareOption ¶ added in v0.11.0
type PrepareOption func(*PrepareConfig)
PrepareOption defines a function to set an option to control the behavior of the Prepare call.
func WithBuiltinFuncs ¶ added in v0.56.0
func WithBuiltinFuncs(bis map[string]*topdown.Builtin) PrepareOption
WithBuiltinFuncs carries the rego.Function{1,2,3} per-query function definitions to the target plugins.
func WithNoInline ¶ added in v0.13.0
func WithNoInline(paths []string) PrepareOption
WithNoInline adds a set of paths to exclude from partial evaluation inlining.
func WithPartialEval ¶ added in v0.11.0
func WithPartialEval() PrepareOption
WithPartialEval configures an option for PrepareForEval which will have it perform partial evaluation while preparing the query (similar to rego.Rego#PartialResult)
type PreparedEvalQuery ¶ added in v0.11.0
type PreparedEvalQuery struct {
// contains filtered or unexported fields
}
PreparedEvalQuery holds the prepared Rego state that has been pre-processed for subsequent evaluations.
func (PreparedEvalQuery) Eval ¶ added in v0.11.0
func (pq PreparedEvalQuery) Eval(ctx context.Context, options ...EvalOption) (ResultSet, error)
Eval evaluates this PartialResult's Rego object with additional eval options and returns a ResultSet. If options are provided they will override the original Rego options respective value. The original Rego object transaction will *not* be re-used. A new transaction will be opened if one is not provided with an EvalOption.
type PreparedPartialQuery ¶ added in v0.11.0
type PreparedPartialQuery struct {
// contains filtered or unexported fields
}
PreparedPartialQuery holds the prepared Rego state that has been pre-processed for partial evaluations.
func (PreparedPartialQuery) Partial ¶ added in v0.11.0
func (pq PreparedPartialQuery) Partial(ctx context.Context, options ...EvalOption) (*PartialQueries, error)
Partial runs partial evaluation on the prepared query and returns the result. The original Rego object transaction will *not* be re-used. A new transaction will be opened if one is not provided with an EvalOption.
type Rego ¶
type Rego struct {
// contains filtered or unexported fields
}
Rego constructs a query and can be evaluated to obtain results.
Example (Custom_function_caching) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/ast" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/topdown" "github.com/open-policy-agent/opa/types" ) func main() { i := 0 r := rego.New( // An example query that uses a custom function. rego.Query(`x = mycounter("foo"); y = mycounter("foo")`), // A custom function that uses caching. rego.FunctionDyn( ®o.Function{ Name: "mycounter", Memoize: true, Decl: types.NewFunction( types.Args(types.S), // one string input types.N, // one number output ), }, func(_ topdown.BuiltinContext, args []*ast.Term) (*ast.Term, error) { i++ return ast.IntNumberTerm(i), nil }, ), ) rs, err := r.Eval(context.Background()) if err != nil { // handle error } fmt.Println("x:", rs[0].Bindings["x"]) fmt.Println("y:", rs[0].Bindings["y"]) }
Output: x: 1 y: 1
Example (Custom_function_global) ¶
package main import ( "context" "fmt" "strings" "github.com/open-policy-agent/opa/ast" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/types" ) func main() { decl := ®o.Function{ Name: "trim_and_split", Decl: types.NewFunction( types.Args(types.S, types.S), // two string inputs types.NewArray(nil, types.S), // variable-length string array output ), } impl := func(_ rego.BuiltinContext, a, b *ast.Term) (*ast.Term, error) { str, ok1 := a.Value.(ast.String) delim, ok2 := b.Value.(ast.String) // The function is undefined for non-string inputs. Built-in // functions should only return errors in unrecoverable cases. if !ok1 || !ok2 { return nil, nil } result := strings.Split(strings.Trim(string(str), string(delim)), string(delim)) arr := make([]*ast.Term, len(result)) for i := range result { arr[i] = ast.StringTerm(result[i]) } return ast.ArrayTerm(arr...), nil } // The rego package exports helper functions for different arities and a // special version of the function that accepts a dynamic number. rego.RegisterBuiltin2(decl, impl) r := rego.New( // An example query that uses a custom function. rego.Query(`x = trim_and_split("/foo/bar/baz/", "/")`), ) rs, err := r.Eval(context.Background()) if err != nil { // handle error } fmt.Println(rs[0].Bindings["x"]) }
Output: [foo bar baz]
Example (Custom_function_nondeterministic) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/topdown/builtins" "github.com/open-policy-agent/opa/ast" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/topdown" "github.com/open-policy-agent/opa/types" ) func main() { ndbCache := builtins.NDBCache{} r := rego.New( // An example query that uses a custom function. rego.Query(`x = myrandom()`), // A custom function that uses caching. rego.FunctionDyn( ®o.Function{ Name: "myrandom", Memoize: true, Nondeterministic: true, Decl: types.NewFunction( nil, // one string input types.N, // one number output ), }, func(_ topdown.BuiltinContext, args []*ast.Term) (*ast.Term, error) { i := 55555 return ast.IntNumberTerm(i), nil }, ), rego.NDBuiltinCache(ndbCache), ) rs, err := r.Eval(context.Background()) if err != nil { // handle error } // Check the binding, and what the NDBCache saw. // This ensures the Nondeterministic flag propagated through correctly. fmt.Println("x:", rs[0].Bindings["x"]) fmt.Println("NDBCache:", ndbCache["myrandom"]) }
Output: x: 55555 NDBCache: {[]: 55555}
Example (Custom_functional_builtin) ¶
package main import ( "context" "fmt" "strings" "github.com/open-policy-agent/opa/ast" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/types" ) func main() { r := rego.New( // An example query that uses a custom function. rego.Query(`x = trim_and_split("/foo/bar/baz/", "/")`), // A custom function that trims and splits strings on the same delimiter. rego.Function2( ®o.Function{ Name: "trim_and_split", Decl: types.NewFunction( types.Args(types.S, types.S), // two string inputs types.NewArray(nil, types.S), // variable-length string array output ), }, func(_ rego.BuiltinContext, a, b *ast.Term) (*ast.Term, error) { str, ok1 := a.Value.(ast.String) delim, ok2 := b.Value.(ast.String) // The function is undefined for non-string inputs. Built-in // functions should only return errors in unrecoverable cases. if !ok1 || !ok2 { return nil, nil } result := strings.Split(strings.Trim(string(str), string(delim)), string(delim)) arr := make([]*ast.Term, len(result)) for i := range result { arr[i] = ast.StringTerm(result[i]) } return ast.ArrayTerm(arr...), nil }, ), ) rs, err := r.Eval(context.Background()) if err != nil { // handle error } fmt.Println(rs[0].Bindings["x"]) }
Output: [foo bar baz]
Example (Print_statements) ¶
package main import ( "bytes" "context" "fmt" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/topdown" ) func main() { var buf bytes.Buffer r := rego.New( rego.Query("data.example.rule_containing_print_call"), rego.Module("example.rego", ` package example import rego.v1 rule_containing_print_call if { print("input.foo is:", input.foo, "and input.bar is:", input.bar) } `), rego.Input(map[string]interface{}{ "foo": 7, }), rego.EnablePrintStatements(true), rego.PrintHook(topdown.NewPrintHook(&buf)), ) _, err := r.Eval(context.Background()) if err != nil { // handle error } fmt.Println("buf:", buf.String()) }
Output: buf: input.foo is: 7 and input.bar is: <undefined>
func (*Rego) Compile ¶ added in v0.10.0
func (r *Rego) Compile(ctx context.Context, opts ...CompileOption) (*CompileResult, error)
Compile returns a compiled policy query.
func (*Rego) Eval ¶
Eval evaluates this Rego object and returns a ResultSet.
Example (Allowed) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Create query that returns a single boolean value. rego := rego.New( rego.Query("data.authz.allow"), rego.Module("example.rego", `package authz import rego.v1 default allow = false allow if { input.open == "sesame" }`, ), rego.Input(map[string]interface{}{"open": "sesame"}), ) // Run evaluation. rs, err := rego.Eval(ctx) if err != nil { panic(err) } // Inspect result. fmt.Println("allowed:", rs.Allowed()) }
Output: allowed: true
Example (Compiler) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/ast" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Define a simple policy. module := ` package example import rego.v1 default allow = false allow if { input.identity = "admin" } allow if { input.method = "GET" } ` // Compile the module. The keys are used as identifiers in error messages. compiler, err := ast.CompileModules(map[string]string{ "example.rego": module, }) // Create a new query that uses the compiled policy from above. rego := rego.New( rego.Query("data.example.allow"), rego.Compiler(compiler), rego.Input( map[string]interface{}{ "identity": "bob", "method": "GET", }, ), ) // Run evaluation. rs, err := rego.Eval(ctx) if err != nil { // Handle error. } // Inspect results. fmt.Println("len:", len(rs)) fmt.Println("value:", rs[0].Expressions[0].Value) fmt.Println("allowed:", rs.Allowed()) // helper method }
Output: len: 1 value: true allowed: true
Example (Errors) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/ast" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() r := rego.New( rego.Query("data.example.p"), rego.Module("example_error.rego", `package example import rego.v1 p = true if { not q[x] } q = {1, 2, 3} if { true }`, )) _, err := r.Eval(ctx) switch err := err.(type) { case ast.Errors: for _, e := range err { fmt.Println("code:", e.Code) fmt.Println("row:", e.Location.Row) fmt.Println("filename:", e.Location.File) } default: // Some other error occurred. } }
Output: code: rego_unsafe_var_error row: 4 filename: example_error.rego
Example (Input) ¶
package main import ( "bytes" "context" "encoding/json" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Raw input data that will be used in evaluation. raw := `{"users": [{"id": "bob"}, {"id": "alice"}]}` d := json.NewDecoder(bytes.NewBufferString(raw)) // Numeric values must be represented using json.Number. d.UseNumber() var input interface{} if err := d.Decode(&input); err != nil { panic(err) } // Create a simple query over the input. rego := rego.New( rego.Query("input.users[idx].id = user_id"), rego.Input(input)) //Run evaluation. rs, err := rego.Eval(ctx) if err != nil { // Handle error. } // Inspect results. fmt.Println("len:", len(rs)) fmt.Println("bindings.idx:", rs[1].Bindings["idx"]) fmt.Println("bindings.user_id:", rs[1].Bindings["user_id"]) }
Output: len: 2 bindings.idx: 1 bindings.user_id: alice
Example (MultipleBindings) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Create query that produces multiple bindings for variable. rego := rego.New( rego.Query(`a = ["ex", "am", "ple"]; x = a[_]; not p[x]`), rego.Package(`example`), rego.Module("example.rego", `package example import rego.v1 p contains "am" if { true } `), ) // Run evaluation. rs, err := rego.Eval(ctx) // Inspect results. fmt.Println("len:", len(rs)) fmt.Println("err:", err) for i := range rs { fmt.Printf("bindings[\"x\"]: %v (i=%d)\n", rs[i].Bindings["x"], i) } }
Output: len: 2 err: <nil> bindings["x"]: ex (i=0) bindings["x"]: ple (i=1)
Example (MultipleDocuments) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Create query that produces multiple documents. rego := rego.New( rego.Query("data.example.p[x]"), rego.Module("example.rego", `package example import rego.v1 p = {"hello": "alice", "goodbye": "bob"} if { true }`, )) // Run evaluation. rs, err := rego.Eval(ctx) // Inspect results. fmt.Println("len:", len(rs)) fmt.Println("err:", err) for i := range rs { fmt.Printf("bindings[\"x\"]: %v (i=%d)\n", rs[i].Bindings["x"], i) fmt.Printf("value: %v (i=%d)\n", rs[i].Expressions[0].Value, i) } }
Output: len: 2 err: <nil> bindings["x"]: goodbye (i=0) value: bob (i=0) bindings["x"]: hello (i=1) value: alice (i=1)
Example (Persistent_storage) ¶
package main import ( "context" "fmt" "os" "github.com/open-policy-agent/opa/logging" "github.com/open-policy-agent/opa/storage/disk" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/storage" "github.com/open-policy-agent/opa/util" ) func main() { ctx := context.Background() data := `{ "example": { "users": { "alice": { "likes": ["dogs", "clouds"] }, "bob": { "likes": ["pizza", "cats"] } } } }` var json map[string]interface{} err := util.UnmarshalJSON([]byte(data), &json) if err != nil { // Handle error. } // Manually create a persistent storage-layer in a temporary directory. rootDir, err := os.MkdirTemp("", "rego_example") if err != nil { panic(err) } defer os.RemoveAll(rootDir) // Configure the store to partition data at `/example/users` so that each // user's data is stored on a different row. Assuming the policy only reads // data for a single user to process the policy query, OPA can avoid loading // _all_ user data into memory this way. store, err := disk.New(ctx, logging.NewNoOpLogger(), nil, disk.Options{ Dir: rootDir, Partitions: []storage.Path{{"example", "user"}}, }) if err != nil { // Handle error. } err = storage.WriteOne(ctx, store, storage.AddOp, storage.Path{}, json) if err != nil { // Handle error } // Run a query that returns the value rs, err := rego.New( rego.Query(`data.example.users["alice"].likes`), rego.Store(store)).Eval(ctx) if err != nil { // Handle error. } // Inspect the result. fmt.Println("value:", rs[0].Expressions[0].Value) // Re-open the store in the same directory. store.Close(ctx) store2, err := disk.New(ctx, logging.NewNoOpLogger(), nil, disk.Options{ Dir: rootDir, Partitions: []storage.Path{{"example", "user"}}, }) if err != nil { // Handle error. } // Run the same query with a new store. rs, err = rego.New( rego.Query(`data.example.users["alice"].likes`), rego.Store(store2)).Eval(ctx) if err != nil { // Handle error. } // Inspect the result and observe the same result. fmt.Println("value:", rs[0].Expressions[0].Value) }
Output: value: [dogs clouds] value: [dogs clouds]
Example (Simple) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Create very simple query that binds a single variable. rego := rego.New(rego.Query("x = 1")) // Run evaluation. rs, err := rego.Eval(ctx) // Inspect results. fmt.Println("len:", len(rs)) fmt.Println("bindings:", rs[0].Bindings) fmt.Println("err:", err) }
Output: len: 1 bindings: map[x:1] err: <nil>
Example (SingleDocument) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Create query that produces a single document. rego := rego.New( rego.Query("data.example.p"), rego.Module("example.rego", `package example import rego.v1 p = ["hello", "world"] if { true }`, )) // Run evaluation. rs, err := rego.Eval(ctx) // Inspect result. fmt.Println("value:", rs[0].Expressions[0].Value) fmt.Println("err:", err) }
Output: value: [hello world] err: <nil>
Example (Storage) ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/storage/inmem" "github.com/open-policy-agent/opa/util" ) func main() { ctx := context.Background() data := `{ "example": { "users": [ { "name": "alice", "likes": ["dogs", "clouds"] }, { "name": "bob", "likes": ["pizza", "cats"] } ] } }` var json map[string]interface{} err := util.UnmarshalJSON([]byte(data), &json) if err != nil { // Handle error. } // Manually create the storage layer. inmem.NewFromObject returns an // in-memory store containing the supplied data. store := inmem.NewFromObject(json) // Create new query that returns the value rego := rego.New( rego.Query("data.example.users[0].likes"), rego.Store(store)) // Run evaluation. rs, err := rego.Eval(ctx) if err != nil { // Handle error. } // Inspect the result. fmt.Println("value:", rs[0].Expressions[0].Value) }
Output: value: [dogs clouds]
Example (Trace_simple) ¶
package main import ( "context" "os" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Create very simple query that binds a single variable and enables tracing. r := rego.New( rego.Query("x = 1"), rego.Trace(true), ) // Run evaluation. r.Eval(ctx) // Inspect results. rego.PrintTraceWithLocation(os.Stdout, r) }
Output: query:1 Enter x = 1 query:1 | Eval x = 1 query:1 | Unify x = 1 query:1 | Exit x = 1 query:1 Redo x = 1 query:1 | Redo x = 1
Example (Tracer) ¶
package main import ( "context" "os" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/topdown" ) func main() { ctx := context.Background() buf := topdown.NewBufferTracer() // Create very simple query that binds a single variable and provides a tracer. rego := rego.New( rego.Query("x = 1"), rego.QueryTracer(buf), ) // Run evaluation. rego.Eval(ctx) // Inspect results. topdown.PrettyTraceWithLocation(os.Stdout, *buf) }
Output: query:1 Enter x = 1 query:1 | Eval x = 1 query:1 | Unify x = 1 query:1 | Exit x = 1 query:1 Redo x = 1 query:1 | Redo x = 1
Example (Transactions) ¶
package main import ( "bytes" "context" "fmt" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/storage" "github.com/open-policy-agent/opa/storage/inmem" ) func main() { ctx := context.Background() // Create storage layer and load dummy data. store := inmem.NewFromReader(bytes.NewBufferString(`{ "favourites": { "pizza": "cheese", "colour": "violet" } }`)) // Open a write transaction on the store that will perform write operations. txn, err := store.NewTransaction(ctx, storage.WriteParams) if err != nil { // Handle error. } // Create rego query that uses the transaction created above. inside := rego.New( rego.Query("data.favourites.pizza"), rego.Store(store), rego.Transaction(txn), ) // Create rego query that DOES NOT use the transaction created above. Under // the hood, the rego package will create it's own transaction to // ensure it evaluates over a consistent snapshot of the storage layer. outside := rego.New( rego.Query("data.favourites.pizza"), rego.Store(store), ) // Write change to storage layer inside the transaction. err = store.Write(ctx, txn, storage.AddOp, storage.MustParsePath("/favourites/pizza"), "pepperoni") if err != nil { // Handle error. } // Run evaluation INSIDE the transaction. rs, err := inside.Eval(ctx) if err != nil { // Handle error. } fmt.Println("value (inside txn):", rs[0].Expressions[0].Value) // Run evaluation OUTSIDE the transaction. rs, err = outside.Eval(ctx) if err != nil { // Handle error. } fmt.Println("value (outside txn):", rs[0].Expressions[0].Value) if err := store.Commit(ctx, txn); err != nil { // Handle error. } // Run evaluation AFTER the transaction commits. rs, err = outside.Eval(ctx) if err != nil { // Handle error. } fmt.Println("value (after txn):", rs[0].Expressions[0].Value) }
Output: value (inside txn): pepperoni value (outside txn): cheese value (after txn): pepperoni
func (*Rego) Partial ¶ added in v0.9.0
func (r *Rego) Partial(ctx context.Context) (*PartialQueries, error)
Partial runs partial evaluation on r and returns the result.
Example ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Define a simple policy for example purposes. module := `package test import rego.v1 allow if { input.method = read_methods[_] input.path = ["reviews", user] input.user = user } allow if { input.method = read_methods[_] input.path = ["reviews", _] input.is_admin } read_methods = ["GET"] ` r := rego.New(rego.Query("data.test.allow == true"), rego.Module("example.rego", module)) pq, err := r.Partial(ctx) if err != nil { // Handle error. } // Inspect result. for i := range pq.Queries { fmt.Printf("Query #%d: %v\n", i+1, pq.Queries[i]) } }
Output: Query #1: "GET" = input.method; input.path = ["reviews", _]; input.is_admin Query #2: "GET" = input.method; input.path = ["reviews", user3]; user3 = input.user
func (*Rego) PartialEval ¶ added in v0.7.0
func (r *Rego) PartialEval(ctx context.Context) (PartialResult, error)
PartialEval has been deprecated and renamed to PartialResult.
func (*Rego) PartialResult ¶ added in v0.9.0
func (r *Rego) PartialResult(ctx context.Context) (PartialResult, error)
PartialResult partially evaluates this Rego object and returns a PartialResult.
Example ¶
package main import ( "bytes" "context" "fmt" "github.com/open-policy-agent/opa/rego" "github.com/open-policy-agent/opa/storage/inmem" ) func main() { ctx := context.Background() // Define a role-based access control (RBAC) policy that decides whether to // allow or deny requests. Requests are allowed if the user is bound to a // role that grants permission to perform the operation on the resource. module := ` package example import rego.v1 import data.bindings import data.roles default allow = false allow if { user_has_role[role_name] role_has_permission[role_name] } user_has_role contains role_name if { b = bindings[_] b.role = role_name b.user = input.subject.user } role_has_permission contains role_name if { r = roles[_] r.name = role_name match_with_wildcard(r.operations, input.operation) match_with_wildcard(r.resources, input.resource) } match_with_wildcard(allowed, value) if { allowed[_] = "*" } match_with_wildcard(allowed, value) if { allowed[_] = value } ` // Define dummy roles and role bindings for the example. In real-world // scenarios, this data would be pushed or pulled into the service // embedding OPA either from an external API or configuration file. store := inmem.NewFromReader(bytes.NewBufferString(`{ "roles": [ { "resources": ["documentA", "documentB"], "operations": ["read"], "name": "analyst" }, { "resources": ["*"], "operations": ["*"], "name": "admin" } ], "bindings": [ { "user": "bob", "role": "admin" }, { "user": "alice", "role": "analyst" } ] }`)) // Prepare and run partial evaluation on the query. The result of partial // evaluation can be cached for performance. When the data or policy // change, partial evaluation should be re-run. r := rego.New( rego.Query("data.example.allow"), rego.Module("example.rego", module), rego.Store(store), ) pr, err := r.PartialResult(ctx) if err != nil { // Handle error. } // Define example inputs (representing requests) that will be used to test // the policy. examples := []map[string]interface{}{ { "resource": "documentA", "operation": "write", "subject": map[string]interface{}{ "user": "bob", }, }, { "resource": "documentB", "operation": "write", "subject": map[string]interface{}{ "user": "alice", }, }, { "resource": "documentB", "operation": "read", "subject": map[string]interface{}{ "user": "alice", }, }, } for i := range examples { // Prepare and run normal evaluation from the result of partial // evaluation. r := pr.Rego( rego.Input(examples[i]), ) rs, err := r.Eval(ctx) if err != nil || len(rs) != 1 || len(rs[0].Expressions) != 1 { // Handle erorr. } else { fmt.Printf("input %d allowed: %v\n", i+1, rs[0].Expressions[0].Value) } } }
Output: input 1 allowed: true input 2 allowed: false input 3 allowed: true
func (*Rego) PrepareForEval ¶ added in v0.11.0
func (r *Rego) PrepareForEval(ctx context.Context, opts ...PrepareOption) (PreparedEvalQuery, error)
PrepareForEval will parse inputs, modules, and query arguments in preparation of evaluating them.
Example ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Create a simple query r := rego.New( rego.Query("input.x == 1"), ) // Prepare for evaluation pq, err := r.PrepareForEval(ctx) if err != nil { // Handle error. } // Raw input data that will be used in the first evaluation input := map[string]interface{}{"x": 2} // Run the evaluation rs, err := pq.Eval(ctx, rego.EvalInput(input)) if err != nil { // Handle error. } // Inspect results. fmt.Println("initial result:", rs[0].Expressions[0]) // Update input input["x"] = 1 // Run the evaluation with new input rs, err = pq.Eval(ctx, rego.EvalInput(input)) if err != nil { // Handle error. } // Inspect results. fmt.Println("updated result:", rs[0].Expressions[0]) }
Output: initial result: false updated result: true
func (*Rego) PrepareForPartial ¶ added in v0.11.0
func (r *Rego) PrepareForPartial(ctx context.Context, opts ...PrepareOption) (PreparedPartialQuery, error)
PrepareForPartial will parse inputs, modules, and query arguments in preparation of partially evaluating them.
Example ¶
package main import ( "context" "fmt" "github.com/open-policy-agent/opa/rego" ) func main() { ctx := context.Background() // Define a simple policy for example purposes. module := `package test import rego.v1 allow if { input.method = read_methods[_] input.path = ["reviews", user] input.user = user } allow if { input.method = read_methods[_] input.path = ["reviews", _] input.is_admin } read_methods = ["GET"] ` r := rego.New( rego.Query("data.test.allow == true"), rego.Module("example.rego", module), ) pq, err := r.PrepareForPartial(ctx) if err != nil { // Handle error. } pqs, err := pq.Partial(ctx) if err != nil { // Handle error. } // Inspect result fmt.Println("First evaluation") for i := range pqs.Queries { fmt.Printf("Query #%d: %v\n", i+1, pqs.Queries[i]) } // Evaluate with specified input exampleInput := map[string]string{ "method": "GET", } // Evaluate again with different input and unknowns pqs, err = pq.Partial(ctx, rego.EvalInput(exampleInput), rego.EvalUnknowns([]string{"input.user", "input.is_admin", "input.path"}), ) if err != nil { // Handle error. } // Inspect result fmt.Println("Second evaluation") for i := range pqs.Queries { fmt.Printf("Query #%d: %v\n", i+1, pqs.Queries[i]) } }
Output: First evaluation Query #1: "GET" = input.method; input.path = ["reviews", _]; input.is_admin Query #2: "GET" = input.method; input.path = ["reviews", user3]; user3 = input.user Second evaluation Query #1: input.path = ["reviews", _]; input.is_admin Query #2: input.path = ["reviews", user3]; user3 = input.user
type Result ¶
type Result struct { Expressions []*ExpressionValue `json:"expressions"` Bindings Vars `json:"bindings,omitempty"` }
Result defines the output of Rego evaluation.
type ResultSet ¶
type ResultSet []Result
ResultSet represents a collection of output from Rego evaluation. An empty result set represents an undefined query.
func (ResultSet) Allowed ¶ added in v0.32.0
Allowed is a helper method that'll return true if all of these conditions hold: - the result set only has one element - there is only one expression in the result set's only element - that expression has the value `true` - there are no bindings.
If bindings are present, this will yield `false`: it would be a pitfall to return `true` for a query like `data.authz.allow = x`, which always has result set element with value true, but could also have a binding `x: false`.
type TargetPlugin ¶ added in v0.53.0
type TargetPlugin interface { IsTarget(string) bool PrepareForEval(context.Context, *ir.Policy, ...PrepareOption) (TargetPluginEval, error) }
type TargetPluginEval ¶ added in v0.53.0
type Vars ¶
type Vars map[string]interface{}
Vars represents a collection of variable bindings. The keys are the variable names and the values are the binding values.
func (Vars) WithoutWildcards ¶ added in v0.5.3
WithoutWildcards returns a copy of v with wildcard variables removed.