sdk

Documentation

Overview

Package sdk contains a high-level API for embedding OPA inside of Go programs.

Index

• Constants
• func IsUndefinedErr(err error) bool
• type ConfigOptions
• type DecisionOptions
• type DecisionResult
• type Error
  • func (err *Error) Error() string
• type OPA
  • func New(ctx context.Context, opts Options) (*OPA, error)
  • func (opa *OPA) Configure(ctx context.Context, opts ConfigOptions) error
  • func (opa *OPA) Decision(ctx context.Context, options DecisionOptions) (*DecisionResult, error)
  • func (opa *OPA) Partial(ctx context.Context, options PartialOptions) (*PartialResult, error)
  • func (opa *OPA) Plugin(name string) plugins.Plugin
  • func (opa *OPA) Stop(ctx context.Context)
• type Options
• type PartialOptions
• type PartialQueryMapper
• type PartialResult
• type RawMapper
  • func (e *RawMapper) MapResults(pq *rego.PartialQueries) (interface{}, error)
  • func (e *RawMapper) ResultToJSON(results interface{}) (interface{}, error)

Constants

const (
	// UndefinedErr indicates that the queried decision was undefined.
	UndefinedErr = "opa_undefined_error"
)

Functions

func IsUndefinedErr

func IsUndefinedErr(err error) bool

IsUndefinedErr returns true of the err represents an undefined decision error.

Types

type ConfigOptions

type ConfigOptions struct {

	// Config provides the OPA configuration for this instance. The config can
	// be supplied as a YAML or JSON byte stream. See
	// https://www.openpolicyagent.org/docs/latest/configuration/ for detailed
	// description of the supported configuration.
	Config io.Reader

	// Ready sets a channel to notify when the OPA instance is ready. If this
	// field is not set, the Configure() function will block until ready. The
	// channel is closed to signal readiness.
	Ready chan struct{}
	// contains filtered or unexported fields
}

ConfigOptions contains parameters to (re-)configure OPA.

type DecisionOptions

type DecisionOptions struct {
	Now                 time.Time           // specifies wallclock time used for time.now_ns(), decision log timestamp, etc.
	Path                string              // specifies name of policy decision to evaluate (e.g., example/allow)
	Input               interface{}         // specifies value of the input document to evaluate policy with
	NDBCache            interface{}         // specifies the non-deterministic builtins cache to use for evaluation.
	StrictBuiltinErrors bool                // treat built-in function errors as fatal
	Tracer              topdown.QueryTracer // specifies the tracer to use for evaluation, optional
	Metrics             metrics.Metrics     // specifies the metrics to use for preparing and evaluation, optional
	Profiler            topdown.QueryTracer // specifies the profiler to use, optional
	Instrument          bool                // if true, instrumentation will be enabled
	DecisionID          string              // the identifier for this decision; if not set, a globally unique identifier will be generated
}

DecisionOptions contains parameters for query evaluation.

type DecisionResult

type DecisionResult struct {
	ID         string             // provides the identifier for this decision (which is included in the decision log.)
	Result     interface{}        // provides the output of query evaluation.
	Provenance types.ProvenanceV1 // wraps the bundle build/version information
}

DecisionResult contains the output of query evaluation.

type Error

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message,omitempty"`
}

Error represents an internal error in the SDK.

func (*Error) Error

func (err *Error) Error() string

type OPA

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

OPA represents an instance of the policy engine. OPA can be started with several options that control configuration, logging, and lifecycle.

func New

func New(ctx context.Context, opts Options) (*OPA, error)

New returns a new OPA object. This function should minimally be called with options that specify an OPA configuration file.

func (*OPA) Configure

func (opa *OPA) Configure(ctx context.Context, opts ConfigOptions) error

Configure updates the configuration of the OPA in-place. This function should be called in response to configuration updates in the environment. This function is atomic. If the configuration update cannot be successfully applied, the old configuration will remain intact.

func (*OPA) Decision

func (opa *OPA) Decision(ctx context.Context, options DecisionOptions) (*DecisionResult, error)

Decision returns a named decision. This function is threadsafe.

func (*OPA) Partial

func (opa *OPA) Partial(ctx context.Context, options PartialOptions) (*PartialResult, error)

Partial returns a named decision. This function is threadsafe. Note(philipc): The NDBCache is unused here, because non-deterministic builtins are not run during partial evaluation.

func (*OPA) Plugin

func (opa *OPA) Plugin(name string) plugins.Plugin

Plugin returns the named plugin. If the plugin does not exist, this function returns nil.

func (*OPA) Stop

func (opa *OPA) Stop(ctx context.Context)

Stop closes the OPA. The OPA cannot be restarted.

type Options

type Options struct {

	// Config provides the OPA configuration for this instance. The config can
	// be supplied as a YAML or JSON byte stream. See
	// https://www.openpolicyagent.org/docs/latest/configuration/ for detailed
	// description of the supported configuration.
	Config io.Reader

	// Logger sets the logging implementation to use for standard logs emitted
	// by OPA. By default, standard logging is disabled.
	Logger logging.Logger

	// ConsoleLogger sets the logging implementation to use for emitting Status
	// and Decision Logs to the console. By default, console logging is enabled.
	ConsoleLogger logging.Logger

	// Ready sets a channel to notify when the OPA instance is ready. If this
	// field is not set, the New() function will block until ready. The channel
	// is closed to signal readiness.
	Ready chan struct{}

	// Plugins provides a set of plugins.Factory instances that will be
	// registered with the OPA SDK instance.
	Plugins map[string]plugins.Factory

	// ID provides an option to set a static ID for the OPA system, avoiding
	// the need to generate a random one at initialization. Setting a static ID
	// is recommended, as it makes it easier to track the system over time.
	ID string

	// Store sets the store to be used by the SDK instance. If nil, it'll use OPA's
	// inmem store.
	Store storage.Store

	// Hooks allows hooking into the internals of SDK operations (TODO(sr): find better words)
	Hooks hooks.Hooks

	// V0Compatible enables v0 compatibility mode when set to true.
	// This is an opt-in to OPA features and behaviors that were enabled by default in OPA v0.x.
	// Takes precedence over V1Compatible.
	V0Compatible bool

	// V1Compatible enables v1 compatibility mode when set to true.
	// This is an opt-in to OPA features and behaviors that will be enabled by default in OPA v1.0 and later.
	// See https://www.openpolicyagent.org/docs/latest/opa-1/ for more information.
	// If V0Compatible is set to true, this field is ignored.
	V1Compatible bool

	// RegoVersion sets the version of the Rego language to use.
	// If V0Compatible or V1Compatible is set to true, this field is ignored.
	RegoVersion ast.RegoVersion

	// ManagerOpts allows customization of the plugin manager.
	// The given options get appended to the list of options already provided by the SDK and eventually
	// overriding them.
	ManagerOpts []func(manager *plugins.Manager)
	// contains filtered or unexported fields
}

Options contains parameters to setup and configure OPA.

type PartialOptions

type PartialOptions struct {
	Now                 time.Time           // specifies wallclock time used for time.now_ns(), decision log timestamp, etc.
	Input               interface{}         // specifies value of the input document to evaluate policy with
	Query               string              // specifies the query to be partially evaluated
	Unknowns            []string            // specifies the unknown elements of the policy
	Mapper              PartialQueryMapper  // specifies the mapper to use when processing results
	StrictBuiltinErrors bool                // treat built-in function errors as fatal
	Tracer              topdown.QueryTracer // specifies the tracer to use for evaluation, optional
	Metrics             metrics.Metrics     // specifies the metrics to use for preparing and evaluation, optional
	Profiler            topdown.QueryTracer // specifies the profiler to use, optional
	Instrument          bool                // if true, instrumentation will be enabled
	DecisionID          string              // the identifier for this decision; if not set, a globally unique identifier will be generated
}

PartialOptions contains parameters for partial query evaluation.

type PartialQueryMapper

type PartialQueryMapper interface {
	// The first interface being returned is the type that will be used for further processing
	MapResults(pq *rego.PartialQueries) (interface{}, error)
	// This should be able to take the Result object from MapResults and return a type that can be logged as JSON
	ResultToJSON(result interface{}) (interface{}, error)
}

type PartialResult

type PartialResult struct {
	ID         string               // decision ID
	Result     interface{}          // mapped result
	AST        *rego.PartialQueries // raw result
	Provenance types.ProvenanceV1   // wraps the bundle build/version information
}

type RawMapper

type RawMapper struct {
}

func (*RawMapper) MapResults

func (e *RawMapper) MapResults(pq *rego.PartialQueries) (interface{}, error)

func (*RawMapper) ResultToJSON

func (e *RawMapper) ResultToJSON(results interface{}) (interface{}, error)