rego

README

Rego

A lightweight, super user-friendly wrapper for the Rego library built by OPA.

Provides easy, convenient methods for parsing, compiling and querying. Attempts to provide serialization of objects to avoid in-memory storage.

Get with:

go get github.com/vrnmthr/rego

See full documentation on GoDoc

Documentation

Overview

Example

Indicates how to use this package to parse, save the parsed representation to a file, compile the file, and query the final compiled representation.

package main

import (
	"fmt"
	"github.com/open-policy-agent/opa/ast"
	"github.com/open-policy-agent/opa/storage/inmem"
)

var PolicyDoc = `
	package example
	
	default rule = false
	rule = x {
		x := input.a + input.b + data.a + data.b
	}
`

// Indicates how to use this package to parse, save the parsed representation to a file,
// compile the file, and query the final compiled representation.
func main() {

	// Parse
	mod, _ := ParseBytes("example", []byte(PolicyDoc))

	// CHECK THAT MODULE CAN BE COMPILED BEFORE SERIALIZATION
	cmp := NewCompiler()
	if Compile(cmp, map[string]*ast.Module{"example": mod}) != nil {
		panic("compilation failed")
	}

	bytes, _ := SerializeModuleJson(mod)
	// ... do whatever here (store in database, maybe?)
	mod, _ = DeserializeModuleJson(bytes)

	// Compile the module
	cmp = NewCompiler()
	modules := map[string]*ast.Module{
		"example": mod,
	}
	Compile(cmp, modules)

	// Query
	inputs := map[string]interface{}{
		"a": 1,
		"b": 2,
	}

	data := map[string]interface{}{
		"a": 3,
		"b": 4,
	}

	store := inmem.NewFromObject(data)
	res, _ := QueryRule(cmp, "example", "rule", inputs, &store)
	fmt.Println(res)

}

Output:

10

Index

• Constants
• func Compile(cmp *ast.Compiler, modules map[string]*ast.Module) error
• func DeserializeModuleGob(data []byte) (*ast.Module, error)
• func DeserializeModuleJson(data []byte) (*ast.Module, error)
• func IsEvalErr(err error) bool
• func IsUndefined(err error) bool
• func NewCompiler() *ast.Compiler
• func ParseBytes(fname string, data []byte) (*ast.Module, error)
• func ParseFile(fpath string) (*ast.Module, error)
• func ParseFiles(fpaths []string) (map[string]*ast.Module, error)
• func Query(cmp *ast.Compiler, query string, inputs map[string]interface{}, ...) (rego.ResultSet, error)
• func QueryRule(cmp *ast.Compiler, pkg, rule string, inputs map[string]interface{}, ...) (interface{}, error)
• func RunTestFile(t *testing.T, inputs, data map[string]interface{}, file, rule, note string, ...)
• func SerializeModuleGob(module *ast.Module) ([]byte, error)
• func SerializeModuleJson(module *ast.Module) ([]byte, error)
• type ErrWriter
  • func (ew *ErrWriter) Error() error
  • func (ew *ErrWriter) Flush()
  • func (ew *ErrWriter) Write(data interface{})
• type Errors
  • func (e *Errors) Add(err error)
  • func (e *Errors) Error() string
  • func (e *Errors) NilIfEmpty() error
• type EvalErr
  • func NewEvalError(msg string) *EvalErr
  • func (e *EvalErr) Error() string
• type TestCase
  • func (test *TestCase) Run(t *testing.T, inputs, data map[string]interface{})
• type UndefinedErr
  • func NewUndefinedError(msg string) *UndefinedErr
  • func (e *UndefinedErr) Error() string

Examples

• Package

Constants

const (
	UNDEF = "---undefined---"
)

Functions

func Compile

func Compile(cmp *ast.Compiler, modules map[string]*ast.Module) error

Compile the modules with the specified compiler

func DeserializeModuleGob

func DeserializeModuleGob(data []byte) (*ast.Module, error)

DeserializeModuleGob uses Gob to deserialize. TODO: test this function

func DeserializeModuleJson

func DeserializeModuleJson(data []byte) (*ast.Module, error)

DeserializeModuleJson reads a module from a Json byte array. The AST produced has no location fields.

func IsEvalErr

func IsEvalErr(err error) bool

IsEvalErr returns true if the given error is an EvalErr

func IsUndefined

func IsUndefined(err error) bool

IsUndefined returns true if the given error is an UndefinedErr

func NewCompiler

func NewCompiler() *ast.Compiler

Creates a new Compiler

func ParseBytes

func ParseBytes(fname string, data []byte) (*ast.Module, error)

ParseBytes parses data. fname is used to write error messages.

func ParseFile

func ParseFile(fpath string) (*ast.Module, error)

ParseFile parses the file specified by fpath and returns a module

func ParseFiles

func ParseFiles(fpaths []string) (map[string]*ast.Module, error)

ParseFiles parses all the files in fpaths and returns a map[string]*ast.Module where the filenames are the keys

func Query

func Query(cmp *ast.Compiler, query string, inputs map[string]interface{}, store *storage.Store) (rego.ResultSet, error)

Query returns a ResultSet for the given query run on the given compiler

func QueryRule

func QueryRule(cmp *ast.Compiler, pkg, rule string, inputs map[string]interface{}, store *storage.Store) (interface{}, error)

QueryRule makes a query and returns a *single* value of any type that is produced by evaluation. If multiple objects are produced upon evaluation or no object is produced, error != nil.

func RunTestFile

func RunTestFile(t *testing.T, inputs, data map[string]interface{}, file, rule, note string, expected interface{})

RunTestFile ensures that the outcome of rule in file with inputs and data as provided is equal to expected. The comparison is done in the same way as TestCase.Run().

func SerializeModuleGob

func SerializeModuleGob(module *ast.Module) ([]byte, error)

SerializeModuleGob uses Gob to convert into a byte array. The disadvantage of this method is that it is less space efficient as it stores all the location fields TODO: test this function

func SerializeModuleJson

func SerializeModuleJson(module *ast.Module) ([]byte, error)

SerializeModuleJson converts into a JSON document. The document should always be pre-compiled and checked for correctness as the JSON document does not store the locations of any of the elements in the AST. This means that error messages during compilation post deserialization will be terrible. TODO: check that errors can still be produced

Types

type ErrWriter

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

ErrWriter wraps a writer

func (*ErrWriter) Error

func (ew *ErrWriter) Error() error

func (*ErrWriter) Flush

func (ew *ErrWriter) Flush()

func (*ErrWriter) Write

func (ew *ErrWriter) Write(data interface{})

type Errors

type Errors []error

Errors represents multiple errors

func (*Errors) Add

func (e *Errors) Add(err error)

func (*Errors) Error

func (e *Errors) Error() string

func (*Errors) NilIfEmpty

func (e *Errors) NilIfEmpty() error

type EvalErr

type EvalErr struct {
	Message string
}

EvalErr represents error generated during evaluation of a query

func NewEvalError

func NewEvalError(msg string) *EvalErr

NewEvalError creates a new EvalError with message msg

func (*EvalErr) Error

func (e *EvalErr) Error() string

type TestCase

type TestCase struct {
	Note     string
	Target   string
	Rules    []string
	Expected interface{}
}

TestCase represents a single test. Target is the rule to be queried for. It defaults to "t". Rules should be Rego rules.

func (*TestCase) Run

func (test *TestCase) Run(t *testing.T, inputs, data map[string]interface{})

RunTestCase runs the given test with the given inputs and data document. It annotates the test with note. To check for equality, under the hood test.Expected is converted to a JSON object and the result of the rego query is also converted into a JSON object. These two objects are then tested for deep equality. If the expected value cannot be converted to JSON, this function panics.

type UndefinedErr

type UndefinedErr struct {
	Message string
}

UndefinedErr represents error caused by no results in evaluation

func NewUndefinedError

func NewUndefinedError(msg string) *UndefinedErr

NewUndefinedError creates a new UndefinedErr with the given message

func (*UndefinedErr) Error

func (e *UndefinedErr) Error() string