watch

Documentation

Overview

Package watch provides the ability to set a watch on a Rego query. A watch will monitor the query and determine when any of it's dependencies change, notifying the client of the new results of the query evaluation whenever this occurs.

Index

• type Event
• type Handle
  • func (h *Handle) Stop()
• type Watcher
  • func New(ctx context.Context, s storage.Store, c *ast.Compiler, txn storage.Transaction) (w *Watcher, err error)
  • func (w *Watcher) Close(txn storage.Transaction)
  • func (w *Watcher) Migrate(c *ast.Compiler, txn storage.Transaction) (*Watcher, error)
  • func (w *Watcher) Query(query string) (*Handle, error)

Examples

• Watcher.Migrate
• Watcher.Query

Types

type Event

type Event struct {
	Query string         `json:"query"`
	Value rego.ResultSet `json:"value"`
	Error error          `json:"error,omitempty"`

	Metrics metrics.Metrics      `json:"-"`
	Tracer  topdown.BufferTracer `json:"-"`
}

Event represents a change to a query. Query is the query in question and Value is the JSON encoded results of the new query evaluation. Error will be populated if evaluating the new query results encountered an error for any reason. If Error is not nil, the contents of Value are undefined.

Metrics and Tracer represent the metrics and trace from the evaluation of the query.

type Handle

type Handle struct {
	C <-chan Event
	// contains filtered or unexported fields
}

Handle allows a user to listen to and end a watch on a query.

func (*Handle) Stop

func (h *Handle) Stop()

Stop ends the watch on the query associated with the Handle. It will close the channel that was delivering notifications through the Handle. This may happen before or after Stop returns.

type Watcher

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

Watcher allows for watches to be registed on queries.

func New

func New(ctx context.Context, s storage.Store, c *ast.Compiler, txn storage.Transaction) (w *Watcher, err error)

New creates and returns a new Watcher on the store using the compiler provided. Once a compiler is provided to create a Watcher, it must not be modified, or else the results produced by the Watcher are undefined.

func (*Watcher) Close

func (w *Watcher) Close(txn storage.Transaction)

Close ends the watches on all queries this Watcher has.

Further attempts to register or end watches will result in an error after Close() is called.

func (*Watcher) Migrate

func (w *Watcher) Migrate(c *ast.Compiler, txn storage.Transaction) (*Watcher, error)

Migrate creates a new Watcher with the same watches as w, but using the new compiler. Like when creating a Watcher with New, the provided compiler must not be modified after being passed to Migrate, or else behavior is undefined.

After Migrate returns, the old watcher will be closed, and the new will be ready for use. All Handles from the old watcher will still be active, via the returned Watcher, with the exception of those Handles who's query is no longer valid with the new compiler. Such Handles will be shutdown and a final Event sent along their channel indicating the cause of the error.

If an error occurs creating the new Watcher, the state of the old Watcher will not be changed.

Example

Output:


x = data.y: [] (<nil>)
x = data.y: map[x:map[r:[1 2 3 4]]] (<nil>)
cannot start query watch with closed Watcher
y = data.a: map[y:[1 2 3 4]] (<nil>)
x = data.y: map[x:map[r:[0 2 3 4]]] (<nil>)
y = data.a: map[y:[0 2 3 4]] (<nil>)
x = data.y: map[x:map[r:[0 1 3 4]]] (<nil>)
y = data.a: map[y:[0 1 3 4]] (<nil>)
x = data.y: map[x:map[r:[0 1 2 4]]] (<nil>)
y = data.a: map[y:[0 1 2 4]] (<nil>)
x = data.y: map[x:map[r:[0 1 2 3]]] (<nil>)
y = data.a: map[y:[0 1 2 3]] (<nil>)

func (*Watcher) Query

func (w *Watcher) Query(query string) (*Handle, error)

Query registers a watch on the provided Rego query. Whenever changes are made to a base or virtual document that the query depends on, an Event describing the new result of the query will be sent through the Handle.

Query will return an error if registering the watch fails for any reason.

Example

Output:


x = data.y: map[x:map[r:[1 2 3 4]]] (<nil>)
x = data.y: map[x:map[r:[0 2 3 4]]] (<nil>)
x = data.y: map[x:map[r:[0 1 3 4]]] (<nil>)
x = data.y: map[x:map[r:[0 1 2 4]]] (<nil>)
x = data.y: map[x:map[r:[0 1 2 3]]] (<nil>)