package topdown

import "github.com/open-policy-agent/opa/topdown"

Package topdown provides low-level query evaluation support.

The topdown implementation is a modified version of the standard top-down evaluation algorithm used in Datalog. References and comprehensions are evaluated eagerly while all other terms are evaluated lazily.

Deprecated: This package is intended for older projects transitioning from OPA v0.x and will remain for the lifetime of OPA v1.x, but its use is not recommended. For newer features and behaviours, such as defaulting to the Rego v1 syntax, use the corresponding components in the github.com/open-policy-agent/opa/v1 package instead. See https://www.openpolicyagent.org/docs/latest/v0-compatibility/ for more information.

Index ¶

• Constants
• func IsCancel(err error) bool
• func IsError(err error) bool
• func NewPrintHook(w io.Writer) print.Hook
• func PrettyEvent(w io.Writer, e *Event, opts PrettyEventOpts) error
• func PrettyTrace(w io.Writer, trace []*Event)
• func PrettyTraceWithLocation(w io.Writer, trace []*Event)
• func PrettyTraceWithOpts(w io.Writer, trace []*Event, opts PrettyTraceOptions)
• func RegisterBuiltinFunc(name string, f BuiltinFunc)
• func RegisterFunctionalBuiltin1(name string, fun FunctionalBuiltin1)
• func RegisterFunctionalBuiltin2(name string, fun FunctionalBuiltin2)
• func RegisterFunctionalBuiltin3(name string, fun FunctionalBuiltin3)
• func RegisterFunctionalBuiltin4(name string, fun FunctionalBuiltin4)
• type BufferTracer
• func NewBufferTracer() *BufferTracer
• type Builtin
• type BuiltinContext
• type BuiltinEmpty
• type BuiltinFunc
• func GetBuiltin(name string) BuiltinFunc
• type Cancel
• func NewCancel() Cancel
• type Error
• type Event
• type FunctionalBuiltin1
• type FunctionalBuiltin2
• type FunctionalBuiltin3
• type FunctionalBuiltin4
• type Halt
• type Instrumentation
• func NewInstrumentation(m metrics.Metrics) *Instrumentation
• type Op
• type PrettyEventOpts
• type PrettyTraceOptions
• type Query
• func NewQuery(query ast.Body) *Query
• type QueryResult
• type QueryResultSet
• type QueryTracer
• func WrapLegacyTracer(tracer Tracer) QueryTracer
• type TraceConfig
• type Tracer
• type VarMetadata
• type VirtualCache
• func NewVirtualCache() VirtualCache

Constants ¶

const (

	// InternalErr represents an unknown evaluation error.
	InternalErr = v1.InternalErr

	// CancelErr indicates the evaluation process was cancelled.
	CancelErr = v1.CancelErr

	// ConflictErr indicates a conflict was encountered during evaluation. For
	// instance, a conflict occurs if a rule produces multiple, differing values
	// for the same key in an object. Conflict errors indicate the policy does
	// not account for the data loaded into the policy engine.
	ConflictErr = v1.ConflictErr

	// TypeErr indicates evaluation stopped because an expression was applied to
	// a value of an inappropriate type.
	TypeErr = v1.TypeErr

	// BuiltinErr indicates a built-in function received a semantically invalid
	// input or encountered some kind of runtime error, e.g., connection
	// timeout, connection refused, etc.
	BuiltinErr = v1.BuiltinErr

	// WithMergeErr indicates that the real and replacement data could not be merged.
	WithMergeErr = v1.WithMergeErr
)

const (
	// HTTPSendInternalErr represents a runtime evaluation error.
	HTTPSendInternalErr = v1.HTTPSendInternalErr

	// HTTPSendNetworkErr represents a network error.
	HTTPSendNetworkErr = v1.HTTPSendNetworkErr
)

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

	// ExitOp is emitted when a query has evaluated to true.
	ExitOp = v1.ExitOp

	// EvalOp is emitted when an expression is about to be evaluated.
	EvalOp = v1.EvalOp

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

	// SaveOp is emitted when an expression is saved instead of evaluated
	// during partial evaluation.
	SaveOp = v1.SaveOp

	// FailOp is emitted when an expression evaluates to false.
	FailOp = v1.FailOp

	// DuplicateOp is emitted when a query has produced a duplicate value. The search
	// will stop at the point where the duplicate was emitted and backtrack.
	DuplicateOp = v1.DuplicateOp

	// NoteOp is emitted when an expression invokes a tracing built-in function.
	NoteOp = v1.NoteOp

	// IndexOp is emitted during an expression evaluation to represent lookup
	// matches.
	IndexOp = v1.IndexOp

	// WasmOp is emitted when resolving a ref using an external
	// Resolver.
	WasmOp = v1.WasmOp

	// UnifyOp is emitted when two terms are unified.  Node will be set to an
	// equality expression with the two terms.  This Node will not have location
	// info.
	UnifyOp           = v1.UnifyOp
	FailedAssertionOp = v1.FailedAssertionOp
)

Functions ¶

func IsCancel ¶

func IsCancel(err error) bool

IsCancel returns true if err was caused by cancellation.

func IsError ¶

func IsError(err error) bool

IsError returns true if the err is an Error.

func NewPrintHook ¶

func NewPrintHook(w io.Writer) print.Hook

func PrettyEvent ¶

func PrettyEvent(w io.Writer, e *Event, opts PrettyEventOpts) error

func PrettyTrace ¶

func PrettyTrace(w io.Writer, trace []*Event)

PrettyTrace pretty prints the trace to the writer.

func PrettyTraceWithLocation ¶

func PrettyTraceWithLocation(w io.Writer, trace []*Event)

PrettyTraceWithLocation prints the trace to the writer and includes location information

func PrettyTraceWithOpts ¶

func PrettyTraceWithOpts(w io.Writer, trace []*Event, opts PrettyTraceOptions)

func RegisterBuiltinFunc ¶

func RegisterBuiltinFunc(name string, f BuiltinFunc)

RegisterBuiltinFunc adds a new built-in function to the evaluation engine.

func RegisterFunctionalBuiltin1 ¶

func RegisterFunctionalBuiltin1(name string, fun FunctionalBuiltin1)

Deprecated: Functional-style builtins are deprecated. Use RegisterBuiltinFunc instead.

func RegisterFunctionalBuiltin2 ¶

func RegisterFunctionalBuiltin2(name string, fun FunctionalBuiltin2)

Deprecated: Functional-style builtins are deprecated. Use RegisterBuiltinFunc instead.

func RegisterFunctionalBuiltin3 ¶

func RegisterFunctionalBuiltin3(name string, fun FunctionalBuiltin3)

Deprecated: Functional-style builtins are deprecated. Use RegisterBuiltinFunc instead.

func RegisterFunctionalBuiltin4 ¶

func RegisterFunctionalBuiltin4(name string, fun FunctionalBuiltin4)

Deprecated: Functional-style builtins are deprecated. Use RegisterBuiltinFunc instead.

Types ¶

type BufferTracer ¶

type BufferTracer = v1.BufferTracer

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

func NewBufferTracer ¶

func NewBufferTracer() *BufferTracer

NewBufferTracer returns a new BufferTracer.

type Builtin ¶

type Builtin = v1.Builtin

Builtin represents a built-in function that queries can call.

type BuiltinContext ¶

type BuiltinContext = v1.BuiltinContext

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

type BuiltinEmpty ¶

type BuiltinEmpty = v1.Builtin

Deprecated: The BuiltinEmpty type is no longer needed. Use nil return values instead.

type BuiltinFunc ¶

type BuiltinFunc = v1.BuiltinFunc

BuiltinFunc defines an interface for implementing built-in functions. The built-in function is called with the plugged operands from the call (including the output operands.) The implementation should evaluate the operands and invoke the iterator for each successful/defined output value.

func GetBuiltin ¶

func GetBuiltin(name string) BuiltinFunc

GetBuiltin returns a built-in function implementation, nil if no built-in found.

type Cancel ¶

type Cancel = v1.Cancel

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

func NewCancel ¶

func NewCancel() Cancel

NewCancel returns a new Cancel object.

type Error ¶

type Error = v1.Error

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

type Event ¶

type Event = v1.Event

Event contains state associated with a tracing event.

type FunctionalBuiltin1 ¶

type FunctionalBuiltin1 = v1.FunctionalBuiltin1 //nolint:staticcheck // SA1019: Intentional use of deprecated type.

Deprecated: Functional-style builtins are deprecated. Use BuiltinFunc instead.

type FunctionalBuiltin2 ¶

type FunctionalBuiltin2 = v1.FunctionalBuiltin2 //nolint:staticcheck // SA1019: Intentional use of deprecated type.

Deprecated: Functional-style builtins are deprecated. Use BuiltinFunc instead.

type FunctionalBuiltin3 ¶

type FunctionalBuiltin3 = v1.FunctionalBuiltin3 //nolint:staticcheck // SA1019: Intentional use of deprecated type.

Deprecated: Functional-style builtins are deprecated. Use BuiltinFunc instead.

type FunctionalBuiltin4 ¶

type FunctionalBuiltin4 = v1.FunctionalBuiltin4 //nolint:staticcheck // SA1019: Intentional use of deprecated type.

Deprecated: Functional-style builtins are deprecated. Use BuiltinFunc instead.

type Halt ¶

type Halt = v1.Halt

Halt is a special error type that built-in function implementations return to indicate that policy evaluation should stop immediately.

type Instrumentation ¶

type Instrumentation = v1.Instrumentation

Instrumentation implements helper functions to instrument query evaluation to diagnose performance issues. Instrumentation may be expensive in some cases, so it is disabled by default.

func NewInstrumentation ¶

func NewInstrumentation(m metrics.Metrics) *Instrumentation

NewInstrumentation returns a new Instrumentation object. Performance diagnostics recorded on this Instrumentation object will stored in m.

type Op ¶

type Op = v1.Op

Op defines the types of tracing events.

type PrettyEventOpts ¶

type PrettyEventOpts = v1.PrettyEventOpts

type PrettyTraceOptions ¶

type PrettyTraceOptions = v1.PrettyTraceOptions

type Query ¶

type Query = v1.Query

Query provides a configurable interface for performing query evaluation.

func NewQuery ¶

func NewQuery(query ast.Body) *Query

NewQuery returns a new Query object that can be run.

type QueryResult ¶

type QueryResult = v1.QueryResult

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

type QueryResultSet ¶

type QueryResultSet = v1.QueryResultSet

QueryResultSet represents a collection of results returned by a query.

type QueryTracer ¶

type QueryTracer = v1.QueryTracer

QueryTracer defines the interface for tracing in the top-down evaluation engine. The implementation can provide additional configuration to modify the tracing behavior for query evaluations.

func WrapLegacyTracer ¶

func WrapLegacyTracer(tracer Tracer) QueryTracer

WrapLegacyTracer will create a new QueryTracer which wraps an older Tracer instance.

type TraceConfig ¶

type TraceConfig = v1.TraceConfig

TraceConfig defines some common configuration for Tracer implementations

type Tracer ¶

type Tracer = v1.Tracer

Tracer defines the interface for tracing in the top-down evaluation engine. Deprecated: Use QueryTracer instead.

type VarMetadata ¶

type VarMetadata = v1.VarMetadata

VarMetadata provides some user facing information about a variable in some policy.

type VirtualCache ¶

type VirtualCache = v1.VirtualCache

VirtualCache defines the interface for a cache that stores the results of evaluated virtual documents (rules). The cache is a stack of frames, where each frame is a mapping from references to values.

func NewVirtualCache ¶

func NewVirtualCache() VirtualCache

Source Files ¶

builtins.go cache.go cancel.go doc.go errors.go graphql.go http.go instrumentation.go print.go query.go trace.go

Directories ¶