topdown

type BufferTracer ¶ added in v0.2.0

type BufferTracer []*Event

BufferTracer implements the Tracer interface by simply buffering all events received.

func NewBufferTracer() *BufferTracer

func (b *BufferTracer) Enabled() bool

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

type BuiltinContext ¶ added in v0.5.11

type BuiltinContext struct {
	Cache    builtins.Cache
	Location *ast.Location
}

BuiltinContext contains context from the evaluator that may be used by built-in functions.

type BuiltinEmpty ¶ added in v0.4.0

type BuiltinEmpty struct{}

BuiltinEmpty is used to signal that the built-in function evaluated, but the result is undefined so evaluation should not continue.

func (BuiltinEmpty) Error() string

type BuiltinFunc ¶

type BuiltinFunc func(BuiltinContext, []*ast.Term, func(*ast.Term) error) error

BuiltinFunc defines a generic interface for built-in functions.

type Cancel ¶ added in v0.5.1

type Cancel interface {
	Cancel()
	Cancelled() bool
}

Cancel defines the interface for cancelling topdown queries. Cancel operations are thread-safe and idempotent.

func NewCancel() Cancel

type Error ¶

type Error struct {
	Code     string        `json:"code"`
	Message  string        `json:"message"`
	Location *ast.Location `json:"location,omitempty"`
}

Error is the error type returned by the Eval and Query functions when an evaluation error occurs.

func (e *Error) Error() string

type Event ¶ added in v0.2.0

type Event struct {
	Op       Op            // Identifies type of event.
	Node     interface{}   // Contains AST node relevant to the event.
	QueryID  uint64        // Identifies the query this event belongs to.
	ParentID uint64        // Identifies the parent query this event belongs to.
	Locals   *ast.ValueMap // Contains local variable bindings from the query context.
}

Event contains state associated with a tracing event.

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

func (evt *Event) HasBody() bool

func (evt *Event) HasExpr() bool

func (evt *Event) HasRule() bool

func (evt *Event) String() string

type FunctionalBuiltin1 ¶ added in v0.4.0

type FunctionalBuiltin1 func(op1 ast.Value) (output ast.Value, err error)

FunctionalBuiltin1 defines an interface for simple functional built-ins.

Implement this interface if your built-in function takes one input and produces one output.

If an error occurs, the functional built-in should return a descriptive message. The message should not be prefixed with the built-in name as the framework takes care of this.

type FunctionalBuiltin2 ¶ added in v0.4.0

type FunctionalBuiltin2 func(op1, op2 ast.Value) (output ast.Value, err error)

FunctionalBuiltin2 defines an interface for simple functional built-ins.

Implement this interface if your built-in function takes two inputs and produces one output.

If an error occurs, the functional built-in should return a descriptive message. The message should not be prefixed with the built-in name as the framework takes care of this.

type FunctionalBuiltin3 ¶ added in v0.4.0

type FunctionalBuiltin3 func(op1, op2, op3 ast.Value) (output ast.Value, err error)

FunctionalBuiltin3 defines an interface for simple functional built-ins.

Implement this interface if your built-in function takes three inputs and produces one output.

If an error occurs, the functional built-in should return a descriptive message. The message should not be prefixed with the built-in name as the framework takes care of this.

type FunctionalBuiltinVoid1 ¶ added in v0.5.0

type FunctionalBuiltinVoid1 func(op1 ast.Value) (err error)

FunctionalBuiltinVoid1 defines an interface for simple functional built-ins.

Implement this interface if your built-in function takes one input and produces no outputs.

If an error occurs, the functional built-in should return a descriptive message. The message should not be prefixed with the built-in name as the framework takes care of this.

type Op ¶ added in v0.2.0

type Op string

Op defines the types of tracing events.

const (
	// EnterOp is emitted when a new query is about to be evaluated.
	EnterOp Op = "Enter"

	// ExitOp is emitted when a query has evaluated to true.
	ExitOp Op = "Exit"

	// EvalOp is emitted when an expression is about to be evaluated.
	EvalOp Op = "Eval"

	// RedoOp is emitted when an expression, rule, or query is being re-evaluated.
	RedoOp Op = "Redo"

	// FailOp is emitted when an expression evaluates to false.
	FailOp Op = "Fail"
)

type Query ¶

type Query struct {
	// contains filtered or unexported fields
}

Query provides a configurable interface for performing query evaluation.

func NewQuery(query ast.Body) *Query

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

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 (q *Query) PartialIter(ctx context.Context, iter func(ast.Body) error) error

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

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

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

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

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

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

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

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

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

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

type QueryResult ¶ added in v0.2.1

type QueryResult map[ast.Var]*ast.Term

QueryResult represents a single result returned by a query. The result contains bindings for all variables that appear in the query.

type QueryResultSet ¶ added in v0.2.1

type QueryResultSet []QueryResult

QueryResultSet represents a collection of results returned by a query.

type Tracer ¶

type Tracer interface {
	Enabled() bool
	Trace(*Event)
}

Tracer defines the interface for tracing in the top-down evaluation engine.