topdown

Documentation

Overview

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