runtime

README

runtime - an abstraction library on top of the Open Policy Agent (OPA)

Introduction

The "runtime" project is a library that sits on top of OPA.

The goal of the project is to allow you to quickly write code that builds, runs or tests OPA policies.

It uses the options pattern to facilitate construction of Runtime instances specific to your needs. You can start super simple, using it just to build some rego into a bundle, or you can get more complex, using it to start a runtime with plugins, built-ins and other features.

Install

go get -u github.com/aserto-dev/runtime

Usage

// Create a runtime
r, cleanup, err := runtime.NewRuntime(ctx, &logger, &runtime.Config{})
if err != nil {
  return errors.Wrap(err, "failed to create runtime")
}
defer cleanup()

// Use the runtime to build a bundle from the current directory
return r.Build(runtime.BuildParams{
  OutputFile: "my-bundle.tar.gz",
}, ".")

You can find a more complete example in the example directory.

Credits

Based on the awesome Open Policy Agent.

Documentation

Index

• type BuildParams
• type BuildTargetType
  • func (t BuildTargetType) String() string
• type BundleState
• type Config
• type LocalBundlesConfig
• type OPAConfig
• type PluginDefinition
• type Result
• type Runtime
  • func NewRuntime(ctx context.Context, logger *zerolog.Logger, cfg *Config, ...) (*Runtime, func(), error)
  • func (r *Runtime) Build(params BuildParams, paths []string) error
  • func (r *Runtime) BuiltinRequirements() (json.RawMessage, error)
  • func (r *Runtime) Query(ctx context.Context, qStr string, input map[string]interface{}, ...) (*Result, error)
  • func (r *Runtime) Status() *RuntimeState
  • func (r *Runtime) WaitForPlugins(ctx context.Context, maxWaitTime time.Duration) error
• type RuntimeOption
  • func WithBuiltin1(decl *rego.Function, impl rego.Builtin1) RuntimeOption
  • func WithBuiltin2(decl *rego.Function, impl rego.Builtin2) RuntimeOption
  • func WithBuiltin3(decl *rego.Function, impl rego.Builtin3) RuntimeOption
  • func WithBuiltin4(decl *rego.Function, impl rego.Builtin4) RuntimeOption
  • func WithBuiltinDyn(decl *rego.Function, impl rego.BuiltinDyn) RuntimeOption
  • func WithPlugin(name string, factory plugins.Factory) RuntimeOption
• type RuntimeState

Types

type BuildParams

type BuildParams struct {
	CapabilitiesJsonFile string
	Target               BuildTargetType
	OptimizationLevel    int
	Entrypoints          []string
	OutputFile           string
	Revision             string
	Ignore               []string
	Debug                bool
	Algorithm            string
	Key                  string
	Scope                string
	PubKey               string
	PubKeyID             string
	ClaimsFile           string
	ExcludeVerifyFiles   []string
}

BuildParams contains all parameters used for doing a build

type BuildTargetType

type BuildTargetType int

BuildTargetType represents the type of build target

const (
	Rego BuildTargetType = iota
	Wasm
)

func (BuildTargetType) String

func (t BuildTargetType) String() string

type BundleState

type BundleState struct {
	ID             string
	Revision       string
	LastDownload   time.Time
	LastActivation time.Time
	Errors         []error
}

type Config

type Config struct {
	LocalBundles                  LocalBundlesConfig `json:"local_bundles"`
	InstanceID                    string             `json:"instance_id"`
	PluginsErrorLimit             int                `json:"plugins_error_limit"`
	GracefulShutdownPeriodSeconds int                `json:"graceful_shutdown_period_seconds"`
	Store                         string             `json:"store"`
	Config                        OPAConfig          `json:"config"`
}

type LocalBundlesConfig

type LocalBundlesConfig struct {
	Watch              bool                       `json:"watch"`
	Paths              []string                   `json:"paths"`
	Ignore             []string                   `json:"ignore"`
	SkipVerification   bool                       `json:"skip_verification"`
	VerificationConfig *bundle.VerificationConfig `json:"verification_config"`
}

type OPAConfig

type OPAConfig struct {
	Services                     map[string]interface{}          `json:"services,omitempty"`
	Labels                       map[string]string               `json:"labels,omitempty"`
	Discovery                    *discovery.Config               `json:"discovery,omitempty"`
	Bundles                      map[string]*bundleplugin.Source `json:"bundles,omitempty"`
	DecisionLogs                 *logs.Config                    `json:"decision_logs,omitempty"`
	Status                       *status.Config                  `json:"status,omitempty"`
	Plugins                      map[string]interface{}          `json:"plugins,omitempty"`
	Keys                         map[string]*keys.Config         `json:"keys,omitempty"`
	DefaultDecision              *string                         `json:"default_decision,omitempty"`
	DefaultAuthorizationDecision *string                         `json:"default_authorization_decision,omitempty"`
	Caching                      *cache.Config                   `json:"caching,omitempty"`
	PersistenceDirectory         *string                         `json:"persistence_directory,omitempty"`
}

type PluginDefinition

type PluginDefinition struct {
	Name    string
	Factory plugins.Factory
}

type Result

type Result struct {
	Result      rego.ResultSet
	Metrics     map[string]interface{}
	Explanation types.TraceV1
	DecisionID  string
}

Result contains the results of a Query execution

type Runtime

type Runtime struct {
	Store           storage.Store
	Logger          *zerolog.Logger
	Config          *Config
	PluginsManager  *plugins.Manager
	InterQueryCache cache.InterQueryCache
	// contains filtered or unexported fields
}

Runtime manages the OPA runtime (plugins, store and info data)

func NewRuntime

func NewRuntime(ctx context.Context, logger *zerolog.Logger, cfg *Config, opts ...RuntimeOption) (*Runtime, func(), error)

func (*Runtime) Build

func (r *Runtime) Build(params BuildParams, paths []string) error

Build builds a bundle using the Aserto OPA Runtime

func (*Runtime) BuiltinRequirements

func (r *Runtime) BuiltinRequirements() (json.RawMessage, error)

func (*Runtime) Query

func (r *Runtime) Query(ctx context.Context, qStr string, input map[string]interface{}, pretty, includeMetrics, includeInstrumentation bool, explain types.ExplainModeV1) (*Result, error)

Query executes a REGO query against the Aserto OPA Runtime explain can be "notes", "full" or "off"

func (*Runtime) Status

func (r *Runtime) Status() *RuntimeState

func (*Runtime) WaitForPlugins

func (r *Runtime) WaitForPlugins(ctx context.Context, maxWaitTime time.Duration) error

WaitForPlugins waits for all plugins to be ready

type RuntimeOption

type RuntimeOption func(*Runtime)

func WithBuiltin1

func WithBuiltin1(decl *rego.Function, impl rego.Builtin1) RuntimeOption

func WithBuiltin2

func WithBuiltin2(decl *rego.Function, impl rego.Builtin2) RuntimeOption

func WithBuiltin3

func WithBuiltin3(decl *rego.Function, impl rego.Builtin3) RuntimeOption

func WithBuiltin4

func WithBuiltin4(decl *rego.Function, impl rego.Builtin4) RuntimeOption

func WithBuiltinDyn

func WithBuiltinDyn(decl *rego.Function, impl rego.BuiltinDyn) RuntimeOption

func WithPlugin

func WithPlugin(name string, factory plugins.Factory) RuntimeOption

type RuntimeState

type RuntimeState struct {
	Ready   bool
	Errors  []error
	Bundles []BundleState
}