topdown

func (*BufferTracer) Config ¶ added in v0.21.0

func (b *BufferTracer) Config() TraceConfig

Config returns the Tracers standard configuration

func (*BufferTracer) Enabled ¶ added in v0.2.0

func (b *BufferTracer) Enabled() bool

Enabled always returns true if the BufferTracer is instantiated.

func (*BufferTracer) Trace ¶ added in v0.2.0

func (b *BufferTracer) Trace(evt *Event)

Trace adds the event to the buffer. Deprecated: Use TraceEvent instead.

func (*BufferTracer) TraceEvent ¶ added in v0.21.0

func (b *BufferTracer) TraceEvent(evt Event)

TraceEvent adds the event to the buffer.

func (*BuiltinContext) Rand ¶ added in v0.31.0

func (bctx *BuiltinContext) Rand() (*rand.Rand, error)

Rand returns a random number generator based on the Seed for this built-in context. The random number will be re-used across multiple calls to this function. If a random number generator cannot be created, an error is returned.

func (*Error) Error ¶

func (e *Error) Error() string

func (*Error) Is ¶ added in v0.29.0

func (e *Error) Is(target error) bool

Is allows matching topdown errors using errors.Is (see IsCancel).

func (*Error) Unwrap ¶ added in v0.54.0

func (e *Error) Unwrap() error

func (*Error) Wrap ¶ added in v0.54.0

func (e *Error) Wrap(err error) *Error

func (*Event) Equal ¶ added in v0.2.0

func (evt *Event) Equal(other *Event) bool

Equal returns true if this event is equal to the other event.

func (*Event) HasBody ¶ added in v0.2.0

func (evt *Event) HasBody() bool

HasBody returns true if the Event contains an ast.Body.

func (*Event) HasExpr ¶ added in v0.2.0

func (evt *Event) HasExpr() bool

HasExpr returns true if the Event contains an ast.Expr.

func (*Event) HasRule ¶ added in v0.2.0

func (evt *Event) HasRule() bool

HasRule returns true if the Event contains an ast.Rule.

func (*Event) Input ¶ added in v0.37.0

func (evt *Event) Input() *ast.Term

Input returns the input object as it was at the event.

func (*Event) Plug ¶ added in v0.37.0

func (evt *Event) Plug(term *ast.Term) *ast.Term

Plug plugs event bindings into the provided ast.Term. Because bindings are mutable, this only makes sense to do when the event is emitted rather than on recorded trace events as the bindings are going to be different by then.

func (*Event) String ¶ added in v0.2.0

func (evt *Event) String() string

func (Halt) Error ¶ added in v0.25.0

func (h Halt) Error() string

func (Halt) Unwrap ¶ added in v0.29.0

func (h Halt) Unwrap() error

func (*Query) Iter ¶ added in v0.5.11

func (q *Query) Iter(ctx context.Context, iter func(QueryResult) error) error

Iter executes the query and invokes the iter function with query results produced by evaluating the query.

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"

	"github.com/open-policy-agent/opa/ast"
	"github.com/open-policy-agent/opa/storage/inmem"
	"github.com/open-policy-agent/opa/topdown"
)

func main() {
	// Initialize context for the example. Normally the caller would obtain the
	// context from an input parameter or instantiate their own.
	ctx := context.Background()

	compiler := ast.NewCompiler()

	// Define a dummy query and some data that the query will execute against.
	query, err := compiler.QueryCompiler().Compile(ast.MustParseBody(`data.a[_] = x; x >= 2`))
	if err != nil {
		// Handle error.
	}

	var data map[string]interface{}

	// OPA uses Go's standard JSON library but assumes that numbers have been
	// decoded as json.Number instead of float64. You MUST decode with UseNumber
	// enabled.
	decoder := json.NewDecoder(bytes.NewBufferString(`{"a": [1,2,3,4]}`))
	decoder.UseNumber()

	if err := decoder.Decode(&data); err != nil {
		// Handle error.
	}

	// Instantiate the policy engine's storage layer.
	store := inmem.NewFromObject(data)

	// Create a new transaction. Transactions allow the policy engine to
	// evaluate the query over a consistent snapshot fo the storage layer.
	txn, err := store.NewTransaction(ctx)
	if err != nil {
		// Handle error.
	}

	defer store.Abort(ctx, txn)

	// Prepare the evaluation parameters. Evaluation executes against the policy
	// engine's storage. In this case, we seed the storage with a single array
	// of number. Other parameters such as the input, tracing configuration,
	// etc. can be set on the query object.
	q := topdown.NewQuery(query).
		WithCompiler(compiler).
		WithStore(store).
		WithTransaction(txn)

	result := []interface{}{}

	// Execute the query and provide a callback function to accumulate the results.
	err = q.Iter(ctx, func(qr topdown.QueryResult) error {

		// Each variable in the query will have an associated binding.
		x := qr[ast.Var("x")]

		// The bindings are ast.Value types so we will convert to a native Go value here.
		v, err := ast.JSON(x.Value)
		if err != nil {
			return err
		}

		result = append(result, v)
		return nil
	})

	// Inspect the query result.
	fmt.Println("result:", result)
	fmt.Println("err:", err)

}

Output:

result: [2 3 4]
err: <nil>

func (*Query) PartialRun ¶ added in v0.5.11

func (q *Query) PartialRun(ctx context.Context) (partials []ast.Body, support []*ast.Module, err error)

PartialRun executes partial evaluation on the query with respect to unknown values. Partial evaluation attempts to evaluate as much of the query as possible without requiring values for the unknowns set on the query. The result of partial evaluation is a new set of queries that can be evaluated once the unknown value is known. In addition to new queries, partial evaluation may produce additional support modules that should be used in conjunction with the partially evaluated queries.

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"

	"github.com/open-policy-agent/opa/ast"
	"github.com/open-policy-agent/opa/storage/inmem"
	"github.com/open-policy-agent/opa/topdown"
)

func main() {

	// Initialize context for the example. Normally the caller would obtain the
	// context from an input parameter or instantiate their own.
	ctx := context.Background()

	var data map[string]interface{}
	decoder := json.NewDecoder(bytes.NewBufferString(`{
		"roles": [
			{
				"permissions": ["read_bucket"],
				"groups": ["dev", "test", "sre"]
			},
			{
				"permissions": ["write_bucket", "delete_bucket"],
				"groups": ["sre"]
			}
		]
	}`))
	if err := decoder.Decode(&data); err != nil {
		// Handle error.
	}

	// Instantiate the policy engine's storage layer.
	store := inmem.NewFromObject(data)

	// Create a new transaction. Transactions allow the policy engine to
	// evaluate the query over a consistent snapshot fo the storage layer.
	txn, err := store.NewTransaction(ctx)
	if err != nil {
		// Handle error.
	}

	defer store.Abort(ctx, txn)

	// Define policy that searches for roles that match input request. If no
	// roles are found, allow is undefined and the caller will reject the
	// request. This is the user supplied policy that OPA will partially
	// evaluate.
	modules := map[string]*ast.Module{
		"authz.rego": ast.MustParseModule(`
			package example

			default allow = false

			allow {
				role = data.roles[i]
				input.group = role.groups[j]
				input.permission = role.permissions[k]
			}
		`),
	}

	// Compile policy.
	compiler := ast.NewCompiler()
	if compiler.Compile(modules); compiler.Failed() {
		// Handle error.
	}

	// Construct query and mark the entire input document as partial.
	q := topdown.NewQuery(ast.MustParseBody("data.example.allow = true")).
		WithCompiler(compiler).
		WithUnknowns([]*ast.Term{
			ast.MustParseTerm("input"),
		}).
		WithStore(store).
		WithTransaction(txn)

	// Execute partial evaluation.
	partial, _, err := q.PartialRun(ctx)
	if err != nil {
		// Handle error.
	}

	// Show result of partially evaluating the policy.
	fmt.Printf("# partial evaluation result (%d items):\n", len(partial))
	for i := range partial {
		fmt.Println(partial[i])
	}

	// Construct a new policy to contain the result of partial evaluation.
	module := ast.MustParseModule("package partial")

	for i := range partial {
		rule := &ast.Rule{
			Head: &ast.Head{
				Name:  ast.Var("allow"),
				Value: ast.BooleanTerm(true),
			},
			Body:   partial[i],
			Module: module,
		}
		module.Rules = append(module.Rules, rule)
	}

	// Compile the partially evaluated policy with the original policy.
	modules["partial"] = module

	if compiler.Compile(modules); compiler.Failed() {
		// Handle error.
	}

	// Test different inputs against partially evaluated policy.
	inputs := []string{
		`{"group": "dev", "permission": "read_bucket"}`,  // allow
		`{"group": "dev", "permission": "write_bucket"}`, // deny
		`{"group": "sre", "permission": "write_bucket"}`, // allow
	}

	fmt.Println()
	fmt.Println("# evaluation results:")

	for i := range inputs {

		// Query partially evaluated policy.
		q = topdown.NewQuery(ast.MustParseBody("data.partial.allow = true")).
			WithCompiler(compiler).
			WithStore(store).
			WithTransaction(txn).
			WithInput(ast.MustParseTerm(inputs[i]))

		qrs, err := q.Run(ctx)
		if err != nil {
			// Handle error.
		}

		// Check if input is allowed.
		allowed := len(qrs) == 1

		fmt.Printf("input %d allowed: %v\n", i+1, allowed)
	}

}

Output:


# partial evaluation result (5 items):
"dev" = input.group; "read_bucket" = input.permission
"test" = input.group; "read_bucket" = input.permission
"sre" = input.group; "read_bucket" = input.permission
"sre" = input.group; "write_bucket" = input.permission
"sre" = input.group; "delete_bucket" = input.permission

# evaluation results:
input 1 allowed: true
input 2 allowed: false
input 3 allowed: true

func (*Query) Run ¶ added in v0.5.11

func (q *Query) Run(ctx context.Context) (QueryResultSet, error)

Run is a wrapper around Iter that accumulates query results and returns them in one shot.

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"

	"github.com/open-policy-agent/opa/ast"
	"github.com/open-policy-agent/opa/storage/inmem"
	"github.com/open-policy-agent/opa/topdown"
)

func main() {
	// Initialize context for the example. Normally the caller would obtain the
	// context from an input parameter or instantiate their own.
	ctx := context.Background()

	compiler := ast.NewCompiler()

	// Define a dummy query and some data that the query will execute against.
	query, err := compiler.QueryCompiler().Compile(ast.MustParseBody(`data.a[_] = x; x >= 2`))
	if err != nil {
		// Handle error.
	}

	var data map[string]interface{}

	// OPA uses Go's standard JSON library but assumes that numbers have been
	// decoded as json.Number instead of float64. You MUST decode with UseNumber
	// enabled.
	decoder := json.NewDecoder(bytes.NewBufferString(`{"a": [1,2,3,4]}`))
	decoder.UseNumber()

	if err := decoder.Decode(&data); err != nil {
		// Handle error.
	}

	// Instantiate the policy engine's storage layer.
	store := inmem.NewFromObject(data)

	// Create a new transaction. Transactions allow the policy engine to
	// evaluate the query over a consistent snapshot fo the storage layer.
	txn, err := store.NewTransaction(ctx)
	if err != nil {
		// Handle error.
	}

	defer store.Abort(ctx, txn)

	// Prepare the evaluation parameters. Evaluation executes against the policy
	// engine's storage. In this case, we seed the storage with a single array
	// of number. Other parameters such as the input, tracing configuration,
	// etc. can be set on the query object.
	q := topdown.NewQuery(query).
		WithCompiler(compiler).
		WithStore(store).
		WithTransaction(txn)

	rs, err := q.Run(ctx)

	// Inspect the query result set.
	fmt.Println("len:", len(rs))
	for i := range rs {
		fmt.Printf("rs[%d][\"x\"]: %v\n", i, rs[i]["x"])
	}
	fmt.Println("err:", err)

}

Output:

len: 3
rs[0]["x"]: 2
rs[1]["x"]: 3
rs[2]["x"]: 4
err: <nil>

func (*Query) WithBuiltinErrorList ¶ added in v0.48.0

func (q *Query) WithBuiltinErrorList(list *[]Error) *Query

WithBuiltinErrorList supplies a pointer to an Error slice to store built-in function errors encountered during evaluation. This error slice can be inspected after evaluation to determine which built-in function errors occurred.

func (*Query) WithBuiltins ¶ added in v0.14.0

func (q *Query) WithBuiltins(builtins map[string]*Builtin) *Query

WithBuiltins adds a set of built-in functions that can be called by the query.

func (*Query) WithCancel ¶ added in v0.5.11

func (q *Query) WithCancel(cancel Cancel) *Query

WithCancel sets the cancellation object to use for the query. Set this if you need to abort queries based on a deadline. This is optional.

func (*Query) WithCompiler ¶ added in v0.5.11

func (q *Query) WithCompiler(compiler *ast.Compiler) *Query

WithCompiler sets the compiler to use for the query.

func (*Query) WithDisableInlining ¶ added in v0.13.0

func (q *Query) WithDisableInlining(paths []ast.Ref) *Query

WithDisableInlining adds a set of paths to the query that should be excluded from inlining. Inlining during partial evaluation can be expensive in some cases (e.g., when a cross-product is computed.) Disabling inlining avoids expensive computation at the cost of generating support rules.

func (*Query) WithDistributedTracingOpts ¶ added in v0.36.0

func (q *Query) WithDistributedTracingOpts(tr tracing.Options) *Query

WithDistributedTracingOpts sets the options to be used by distributed tracing.

func (*Query) WithEarlyExit ¶ added in v0.35.0

func (q *Query) WithEarlyExit(enabled bool) *Query

WithEarlyExit will enable or disable using 'early exit' for the evaluation of the query. The default is enabled.

func (*Query) WithIndexing ¶ added in v0.15.0

func (q *Query) WithIndexing(enabled bool) *Query

WithIndexing will enable or disable using rule indexing for the evaluation of the query. The default is enabled.

func (*Query) WithInput ¶ added in v0.5.11

func (q *Query) WithInput(input *ast.Term) *Query

WithInput sets the input object to use for the query. References rooted at input will be evaluated against this value. This is optional.

func (*Query) WithInstrumentation ¶ added in v0.7.0

func (q *Query) WithInstrumentation(instr *Instrumentation) *Query

WithInstrumentation sets the instrumentation configuration to enable on the evaluation process. By default, instrumentation is turned off.

func (*Query) WithInterQueryBuiltinCache ¶ added in v0.23.0

func (q *Query) WithInterQueryBuiltinCache(c cache.InterQueryCache) *Query

WithInterQueryBuiltinCache sets the inter-query cache that built-in functions can utilize.

func (*Query) WithMetrics ¶ added in v0.5.11

func (q *Query) WithMetrics(m metrics.Metrics) *Query

WithMetrics sets the metrics collection to add evaluation metrics to. This is optional.

func (*Query) WithNDBuiltinCache ¶ added in v0.44.0

func (q *Query) WithNDBuiltinCache(c builtins.NDBCache) *Query

WithNDBuiltinCache sets the non-deterministic builtin cache.

func (*Query) WithPartialNamespace ¶ added in v0.6.0

func (q *Query) WithPartialNamespace(ns string) *Query

WithPartialNamespace sets the namespace to use for supporting rules generated as part of the partial evaluation process. The ns value must be a valid package path component.

func (*Query) WithPrintHook ¶ added in v0.34.0

func (q *Query) WithPrintHook(h print.Hook) *Query

func (*Query) WithQueryCompiler ¶ added in v0.15.1

func (q *Query) WithQueryCompiler(queryCompiler ast.QueryCompiler) *Query

WithQueryCompiler sets the queryCompiler used for the query.

func (*Query) WithQueryTracer ¶ added in v0.21.0

func (q *Query) WithQueryTracer(tracer QueryTracer) *Query

WithQueryTracer adds a query tracer to use during evaluation. This is optional. Disabled QueryTracers will be ignored.

func (*Query) WithResolver ¶ added in v0.25.0

func (q *Query) WithResolver(ref ast.Ref, r resolver.Resolver) *Query

WithResolver configures an external resolver to use for the given ref.

func (*Query) WithRuntime ¶ added in v0.10.0

func (q *Query) WithRuntime(runtime *ast.Term) *Query

WithRuntime sets the runtime data to execute the query with. The runtime data can be returned by the `opa.runtime` built-in function.

func (*Query) WithSeed ¶ added in v0.20.0

func (q *Query) WithSeed(r io.Reader) *Query

WithSeed sets a reader that will seed randomization required by built-in functions. If a seed is not provided crypto/rand.Reader is used.

func (*Query) WithShallowInlining ¶ added in v0.22.0

func (q *Query) WithShallowInlining(yes bool) *Query

WithShallowInlining disables aggressive inlining performed during partial evaluation. When shallow inlining is enabled rules that depend (transitively) on unknowns are not inlined. Only rules/values that are completely known will be inlined.

func (*Query) WithSkipPartialNamespace ¶ added in v0.20.0

func (q *Query) WithSkipPartialNamespace(yes bool) *Query

WithSkipPartialNamespace disables namespacing of saved support rules that are generated from the original policy (rules which are completely synthetic are still namespaced.)

func (*Query) WithStore ¶ added in v0.5.11

func (q *Query) WithStore(store storage.Store) *Query

WithStore sets the store to use for the query.

func (*Query) WithStrictBuiltinErrors ¶ added in v0.25.0

func (q *Query) WithStrictBuiltinErrors(yes bool) *Query

WithStrictBuiltinErrors tells the evaluator to treat all built-in function errors as fatal errors.

func (*Query) WithStrictObjects ¶ added in v0.47.0

func (q *Query) WithStrictObjects(yes bool) *Query

WithStrictObjects tells the evaluator to avoid the "lazy object" optimization applied when reading objects from the store. It will result in higher memory usage and should only be used temporarily while adjusting code that breaks because of the optimization.

func (*Query) WithTime ¶ added in v0.23.0

func (q *Query) WithTime(x time.Time) *Query

WithTime sets the time that will be returned by the time.now_ns() built-in function.

func (*Query) WithTracer ¶ added in v0.5.11

func (q *Query) WithTracer(tracer Tracer) *Query

WithTracer adds a query tracer to use during evaluation. This is optional. Deprecated: Use WithQueryTracer instead.

func (*Query) WithTransaction ¶ added in v0.5.11

func (q *Query) WithTransaction(txn storage.Transaction) *Query

WithTransaction sets the transaction to use for the query. All queries should be performed over a consistent snapshot of the storage layer.

func (*Query) WithUnknowns ¶ added in v0.6.0

func (q *Query) WithUnknowns(terms []*ast.Term) *Query

WithUnknowns sets the initial set of variables or references to treat as unknown during query evaluation. This is required for partial evaluation.