package storage

import "github.com/open-policy-agent/opa/v1/storage"

Package storage exposes the policy engine's storage layer.

Index ¶

• Constants
• Variables
• func IsIndexingNotSupported(error) bool
• func IsInvalidPatch(err error) bool
• func IsInvalidTransaction(err error) bool
• func IsNotFound(err error) bool
• func IsWriteConflictError(err error) bool
• func MakeDir(ctx context.Context, store Store, txn Transaction, path Path) error
• func NonEmpty(ctx context.Context, store Store, txn Transaction) func([]string) (bool, error)
• func ReadOne(ctx context.Context, store Store, path Path) (interface{}, error)
• func Txn(ctx context.Context, store Store, params TransactionParams, f func(Transaction) error) error
• func WriteOne(ctx context.Context, store Store, op PatchOp, path Path, value interface{}) error
• type Context
• func NewContext() *Context
• func (ctx *Context) Get(key interface{}) interface{}
• func (ctx *Context) Metrics() metrics.Metrics
• func (ctx *Context) Put(key, value interface{})
• func (ctx *Context) WithMetrics(m metrics.Metrics) *Context
• type DataEvent
• type Error
• func (err *Error) Error() string
• type Iterator
• type MakeDirer
• type PatchOp
• type Path
• func MustParsePath(s string) Path
• func NewPathForRef(ref ast.Ref) (path Path, err error)
• func ParsePath(str string) (path Path, ok bool)
• func ParsePathEscaped(str string) (path Path, ok bool)
• func (p Path) Compare(other Path) (cmp int)
• func (p Path) Equal(other Path) bool
• func (p Path) HasPrefix(other Path) bool
• func (p Path) Ref(head *ast.Term) (ref ast.Ref)
• func (p Path) String() string
• type Policy
• type PolicyEvent
• type PolicyNotSupported
• func (PolicyNotSupported) DeletePolicy(context.Context, Transaction, string) error
• func (PolicyNotSupported) GetPolicy(context.Context, Transaction, string) ([]byte, error)
• func (PolicyNotSupported) ListPolicies(context.Context, Transaction) ([]string, error)
• func (PolicyNotSupported) UpsertPolicy(context.Context, Transaction, string, []byte) error
• type Store
• type Transaction
• func NewTransactionOrDie(ctx context.Context, store Store, params ...TransactionParams) Transaction
• type TransactionParams
• type Trigger
• type TriggerConfig
• type TriggerEvent
• func (e TriggerEvent) DataChanged() bool
• func (e TriggerEvent) IsZero() bool
• func (e TriggerEvent) PolicyChanged() bool
• type TriggerHandle
• type TriggersNotSupported
• func (TriggersNotSupported) Register(context.Context, Transaction, TriggerConfig) (TriggerHandle, error)
• type Update
• type WritesNotSupported
• func (WritesNotSupported) Write(context.Context, Transaction, PatchOp, Path, interface{}) error

Constants ¶

const (
	// InternalErr indicates an unknown, internal error has occurred.
	InternalErr = "storage_internal_error"

	// NotFoundErr indicates the path used in the storage operation does not
	// locate a document.
	NotFoundErr = "storage_not_found_error"

	// WriteConflictErr indicates a write on the path enocuntered a conflicting
	// value inside the transaction.
	WriteConflictErr = "storage_write_conflict_error"

	// InvalidPatchErr indicates an invalid patch/write was issued. The patch
	// was rejected.
	InvalidPatchErr = "storage_invalid_patch_error"

	// InvalidTransactionErr indicates an invalid operation was performed
	// inside of the transaction.
	InvalidTransactionErr = "storage_invalid_txn_error"

	// TriggersNotSupportedErr indicates the caller attempted to register a
	// trigger against a store that does not support them.
	TriggersNotSupportedErr = "storage_triggers_not_supported_error"

	// WritesNotSupportedErr indicate the caller attempted to perform a write
	// against a store that does not support them.
	WritesNotSupportedErr = "storage_writes_not_supported_error"

	// PolicyNotSupportedErr indicate the caller attempted to perform a policy
	// management operation against a store that does not support them.
	PolicyNotSupportedErr = "storage_policy_not_supported_error"
)

const (
	AddOp     PatchOp = iota
	RemoveOp          = iota
	ReplaceOp         = iota
)

Patch supports add, remove, and replace operations.

Variables ¶

var WriteParams = TransactionParams{
	Write: true,
}

WriteParams specifies the TransactionParams for a write transaction.

Functions ¶

func IsIndexingNotSupported ¶

func IsIndexingNotSupported(error) bool

IsIndexingNotSupported is a stub for backwards-compatibility.

Deprecated: We no longer return IndexingNotSupported errors, so it is unnecessary to check for them.

func IsInvalidPatch ¶

func IsInvalidPatch(err error) bool

IsInvalidPatch returns true if this error is a InvalidPatchErr.

func IsInvalidTransaction ¶

func IsInvalidTransaction(err error) bool

IsInvalidTransaction returns true if this error is a InvalidTransactionErr.

func IsNotFound ¶

func IsNotFound(err error) bool

IsNotFound returns true if this error is a NotFoundErr.

func IsWriteConflictError ¶

func IsWriteConflictError(err error) bool

IsWriteConflictError returns true if this error a WriteConflictErr.

func MakeDir ¶

func MakeDir(ctx context.Context, store Store, txn Transaction, path Path) error

MakeDir inserts an empty object at path. If the parent path does not exist, MakeDir will create it recursively.

func NonEmpty ¶

func NonEmpty(ctx context.Context, store Store, txn Transaction) func([]string) (bool, error)

NonEmpty returns a function that tests if a path is non-empty. A path is non-empty if a Read on the path returns a value or a Read on any of the path prefixes returns a non-object value.

func ReadOne ¶

func ReadOne(ctx context.Context, store Store, path Path) (interface{}, error)

ReadOne is a convenience function to read a single value from the provided Store. It will create a new Transaction to perform the read with, and clean up after itself should an error occur.

func Txn ¶

func Txn(ctx context.Context, store Store, params TransactionParams, f func(Transaction) error) error

Txn is a convenience function that executes f inside a new transaction opened on the store. If the function returns an error, the transaction is aborted and the error is returned. Otherwise, the transaction is committed and the result of the commit is returned.

func WriteOne ¶

func WriteOne(ctx context.Context, store Store, op PatchOp, path Path, value interface{}) error

WriteOne is a convenience function to write a single value to the provided Store. It will create a new Transaction to perform the write with, and clean up after itself should an error occur.

Types ¶

type Context ¶

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

Context is a simple container for key/value pairs.

func NewContext ¶

func NewContext() *Context

NewContext returns a new context object.

func (*Context) Get ¶

func (ctx *Context) Get(key interface{}) interface{}

Get returns the key value in the context.

func (*Context) Metrics ¶

func (ctx *Context) Metrics() metrics.Metrics

Metrics() allows using a Context's metrics. Returns nil if metrics were not attached to the Context.

func (*Context) Put ¶

func (ctx *Context) Put(key, value interface{})

Put adds a key/value pair to the context.

func (*Context) WithMetrics ¶

func (ctx *Context) WithMetrics(m metrics.Metrics) *Context

WithMetrics allows passing metrics via the Context. It puts the metrics object in the ctx, and returns the same ctx (not a copy) for convenience.

type DataEvent ¶

type DataEvent struct {
	Path    Path
	Data    interface{}
	Removed bool
}

DataEvent describes a change to a base data document.

type Error ¶

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

Error is the error type returned by the storage layer.

func (*Error) Error ¶

func (err *Error) Error() string

type Iterator ¶

type Iterator interface {
	Next() (*Update, error)
}

Iterator defines the interface that can be used to read files from a directory starting with files at the base of the directory, then sub-directories etc.

type MakeDirer ¶

type MakeDirer interface {
	MakeDir(context.Context, Transaction, Path) error
}

MakeDirer defines the interface a Store could realize to override the generic MakeDir functionality in storage.MakeDir

type PatchOp ¶

type PatchOp int

PatchOp is the enumeration of supposed modifications.

type Path ¶

type Path []string

Path refers to a document in storage.

func MustParsePath ¶

func MustParsePath(s string) Path

MustParsePath returns a new Path for s. If s cannot be parsed, this function will panic. This is mostly for test purposes.

func NewPathForRef ¶

func NewPathForRef(ref ast.Ref) (path Path, err error)

NewPathForRef returns a new path for the given ref.

func ParsePath ¶

func ParsePath(str string) (path Path, ok bool)

ParsePath returns a new path for the given str.

func ParsePathEscaped ¶

func ParsePathEscaped(str string) (path Path, ok bool)

ParsePathEscaped returns a new path for the given escaped str.

func (Path) Compare ¶

func (p Path) Compare(other Path) (cmp int)

Compare performs lexigraphical comparison on p and other and returns -1 if p is less than other, 0 if p is equal to other, or 1 if p is greater than other.

func (Path) Equal ¶

func (p Path) Equal(other Path) bool

Equal returns true if p is the same as other.

func (Path) HasPrefix ¶

func (p Path) HasPrefix(other Path) bool

HasPrefix returns true if p starts with other.

func (Path) Ref ¶

func (p Path) Ref(head *ast.Term) (ref ast.Ref)

Ref returns a ref that represents p rooted at head.

func (Path) String ¶

func (p Path) String() string

type Policy ¶

type Policy interface {
	ListPolicies(context.Context, Transaction) ([]string, error)
	GetPolicy(context.Context, Transaction, string) ([]byte, error)
	UpsertPolicy(context.Context, Transaction, string, []byte) error
	DeletePolicy(context.Context, Transaction, string) error
}

Policy defines the interface for policy module storage.

type PolicyEvent ¶

type PolicyEvent struct {
	ID      string
	Data    []byte
	Removed bool
}

PolicyEvent describes a change to a policy.

type PolicyNotSupported ¶

type PolicyNotSupported struct{}

PolicyNotSupported provides a default implementation of the policy interface which may be used if the backend does not support policy storage.

func (PolicyNotSupported) DeletePolicy ¶

func (PolicyNotSupported) DeletePolicy(context.Context, Transaction, string) error

DeletePolicy always returns a PolicyNotSupportedErr.

func (PolicyNotSupported) GetPolicy ¶

func (PolicyNotSupported) GetPolicy(context.Context, Transaction, string) ([]byte, error)

GetPolicy always returns a PolicyNotSupportedErr.

func (PolicyNotSupported) ListPolicies ¶

func (PolicyNotSupported) ListPolicies(context.Context, Transaction) ([]string, error)

ListPolicies always returns a PolicyNotSupportedErr.

func (PolicyNotSupported) UpsertPolicy ¶

func (PolicyNotSupported) UpsertPolicy(context.Context, Transaction, string, []byte) error

UpsertPolicy always returns a PolicyNotSupportedErr.

type Store ¶

type Store interface {
	Trigger
	Policy

	// NewTransaction is called create a new transaction in the store.
	NewTransaction(context.Context, ...TransactionParams) (Transaction, error)

	// Read is called to fetch a document referred to by path.
	Read(context.Context, Transaction, Path) (interface{}, error)

	// Write is called to modify a document referred to by path.
	Write(context.Context, Transaction, PatchOp, Path, interface{}) error

	// Commit is called to finish the transaction. If Commit returns an error, the
	// transaction must be automatically aborted by the Store implementation.
	Commit(context.Context, Transaction) error

	// Truncate is called to make a copy of the underlying store, write documents in the new store
	// by creating multiple transactions in the new store as needed and finally swapping
	// over to the new storage instance. This method must be called within a transaction on the original store.
	Truncate(context.Context, Transaction, TransactionParams, Iterator) error

	// Abort is called to cancel the transaction.
	Abort(context.Context, Transaction)
}

Store defines the interface for the storage layer's backend.

type Transaction ¶

type Transaction interface {
	ID() uint64
}

Transaction defines the interface that identifies a consistent snapshot over the policy engine's storage layer.

func NewTransactionOrDie ¶

func NewTransactionOrDie(ctx context.Context, store Store, params ...TransactionParams) Transaction

NewTransactionOrDie is a helper function to create a new transaction. If the storage layer cannot create a new transaction, this function will panic. This function should only be used for tests.

type TransactionParams ¶

type TransactionParams struct {

	// BasePaths indicates the top-level paths where write operations will be performed in this transaction.
	BasePaths []string

	// RootOverwrite is deprecated. Use BasePaths instead.
	RootOverwrite bool

	// Write indicates if this transaction will perform any write operations.
	Write bool

	// Context contains key/value pairs passed to triggers.
	Context *Context
}

TransactionParams describes a new transaction.

type Trigger ¶

type Trigger interface {
	Register(context.Context, Transaction, TriggerConfig) (TriggerHandle, error)
}

Trigger defines the interface that stores implement to register for change notifications when the store is changed.

type TriggerConfig ¶

type TriggerConfig struct {

	// OnCommit is invoked when a transaction is successfully committed. The
	// callback is invoked with a handle to the write transaction that
	// successfully committed before other clients see the changes.
	OnCommit func(context.Context, Transaction, TriggerEvent)
}

TriggerConfig contains the trigger registration configuration.

type TriggerEvent ¶

type TriggerEvent struct {
	Policy  []PolicyEvent
	Data    []DataEvent
	Context *Context
}

TriggerEvent describes the changes that caused the trigger to be invoked.

func (TriggerEvent) DataChanged ¶

func (e TriggerEvent) DataChanged() bool

DataChanged returns true if the trigger was caused by a data change.

func (TriggerEvent) IsZero ¶

func (e TriggerEvent) IsZero() bool

IsZero returns true if the TriggerEvent indicates no changes occurred. This function is primarily for test purposes.

func (TriggerEvent) PolicyChanged ¶

func (e TriggerEvent) PolicyChanged() bool

PolicyChanged returns true if the trigger was caused by a policy change.

type TriggerHandle ¶

type TriggerHandle interface {
	Unregister(context.Context, Transaction)
}

TriggerHandle defines the interface that can be used to unregister triggers that have been registered on a Store.

type TriggersNotSupported ¶

type TriggersNotSupported struct{}

TriggersNotSupported provides default implementations of the Trigger interface which may be used if the backend does not support triggers.

func (TriggersNotSupported) Register ¶

func (TriggersNotSupported) Register(context.Context, Transaction, TriggerConfig) (TriggerHandle, error)

Register always returns an error indicating triggers are not supported.

type Update ¶

type Update struct {
	Path     Path
	Value    []byte
	IsPolicy bool
}

Update contains information about a file

type WritesNotSupported ¶

type WritesNotSupported struct{}

WritesNotSupported provides a default implementation of the write interface which may be used if the backend does not support writes.

func (WritesNotSupported) Write ¶

func (WritesNotSupported) Write(context.Context, Transaction, PatchOp, Path, interface{}) error

Source Files ¶

doc.go errors.go interface.go path.go storage.go

Directories ¶