attribute

Documentation

Overview

Package attribute provides the low-level mechanisms to manipulate mixer attributes.

Attributes are name/value pairs providing metadata about an operation. In the Istio system, Envoy supplies a potentially large number of attributes to Mixer for every request and Mixer sends a modest number of attributes back to the proxy with its responses.

There is an 'attribute protocol' between Envoy and Mixer which this package implements.

The general use of this package is that there is a single Manager instance created for Mixer as a whole. Each incoming gRPC stream uses the manager to create a pair of Trackers which are each responsible for implementing 1/2 of the aforementioned attribute protocol (one for the input side, one for the output side)

Index

• func NewContext(ctx context.Context, bag *MutableBag) context.Context
• type Bag
• type Manager
  • func NewManager() *Manager
  • func (am *Manager) NewTracker() Tracker
• type MutableBag
  • func CopyBag(b Bag) *MutableBag
  • func FromContext(ctx context.Context) (*MutableBag, bool)
  • func GetMutableBag(parent Bag) *MutableBag
  • func (mb *MutableBag) Child() *MutableBag
  • func (mb *MutableBag) Done()
  • func (mb *MutableBag) Get(name string) (interface{}, bool)
  • func (mb *MutableBag) Merge(bags ...*MutableBag) error
  • func (mb *MutableBag) Names() []string
  • func (mb *MutableBag) Reset()
  • func (mb *MutableBag) Set(name string, value interface{})
• type Tracker

Functions

func NewContext

func NewContext(ctx context.Context, bag *MutableBag) context.Context

NewContext returns a new Context carrying the supplied bag.

Types

type Bag

type Bag interface {
	// Get returns an attribute value.
	Get(name string) (value interface{}, found bool)

	// Names return the names of all the attributes known to this bag.
	Names() []string

	// Done indicates the bag can be reclaimed.
	Done()
}

Bag is a generic mechanism to access a set of attributes.

type Manager

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

Manager provides support for attributes in Mixer.

func NewManager

func NewManager() *Manager

NewManager allocates a fresh Manager.

func (*Manager) NewTracker

func (am *Manager) NewTracker() Tracker

NewTracker returns a Tracker.

This method is thread-safe

type MutableBag

type MutableBag struct {
	sync.Mutex
	// contains filtered or unexported fields
}

MutableBag is a generic mechanism to read and write a set of attributes.

Bags can be chained together in a parent/child relationship. A child bag represents a delta over a parent. By default a child looks identical to the parent. But as mutations occur to the child, the two start to diverge. Resetting a child makes it look identical to its parent again.

func CopyBag

func CopyBag(b Bag) *MutableBag

CopyBag makes a deep copy of MutableBag.

func FromContext

func FromContext(ctx context.Context) (*MutableBag, bool)

FromContext extracts the bag from ctx, if present.

func GetMutableBag

func GetMutableBag(parent Bag) *MutableBag

GetMutableBag returns an initialized bag.

Bags can be chained in a parent/child relationship. You can pass nil if the bag has no parent.

When you are done using the mutable bag, call the Done method to recycle it.

func (*MutableBag) Child

func (mb *MutableBag) Child() *MutableBag

Child allocates a derived mutable bag.

func (*MutableBag) Done

func (mb *MutableBag) Done()

Done indicates the bag can be reclaimed.

func (*MutableBag) Get

func (mb *MutableBag) Get(name string) (interface{}, bool)

Get returns an attribute value.

func (*MutableBag) Merge

func (mb *MutableBag) Merge(bags ...*MutableBag) error

Merge combines an array of bags into the current bag.

The individual bags may not contain any conflicting attribute values. If that happens, then the merge fails and no mutation will have occurred to the current bag.

func (*MutableBag) Names

func (mb *MutableBag) Names() []string

Names return the names of all the attributes known to this bag.

func (*MutableBag) Reset

func (mb *MutableBag) Reset()

Reset removes all local state.

func (*MutableBag) Set

func (mb *MutableBag) Set(name string, value interface{})

Set creates an override for a named attribute.

type Tracker

type Tracker interface {
	// ApplyProto refreshes the set of attributes based on an update proto.
	//
	// This returns a Bag that reflects the current state of the attribute context
	// that the proto targeted.
	//
	// If this returns a non-nil error, it indicates there was a problem in the
	// supplied Attributes proto. When this happens, none of the tracked attribute
	// state will have been affected.
	ApplyProto(attrs *mixerpb.Attributes) (*MutableBag, error)

	// ApplyBag refreshes the tracked attributes with the content of the supplied bag and fills-in an
	// output proto representing the change in state.
	//
	// An error indicates the attribute bag contained some invalid attribute
	// type. In such a case, the output struct will have been left partially updated
	// and be in an effective unusable state.
	ApplyBag(bag *MutableBag, context int32, output *mixerpb.Attributes) error

	// Done indicates the tracker can be reclaimed.
	Done()
}

Tracker is responsible for implementing Mixer's attribute protocol.

This tracks a set of attributes over time. The tracker keeps a current set of attributes which can be mutated in one of two ways. The first way is by applying an attribute proto using the ApplyProto method. The second way is by applying a bag of attributes.