adapter

Documentation

Overview

Package adapter defines the types consumed by adapter implementations to interface with Mixer.

Index

• func StringEquals(a interface{}, b interface{}) bool
• func Stringify(v interface{}) string
• type CheckResult
  • func (r *CheckResult) IsDefault() bool
  • func (r *CheckResult) String() string
• type Config
• type ConfigError
  • func (e ConfigError) Error() string
  • func (e ConfigError) String() string
• type ConfigErrors
  • func (e *ConfigErrors) Append(field string, err error) *ConfigErrors
  • func (e *ConfigErrors) Appendf(field, format string, args ...interface{}) *ConfigErrors
  • func (e *ConfigErrors) Error() string
  • func (e *ConfigErrors) Extend(ee *ConfigErrors) *ConfigErrors
  • func (e *ConfigErrors) String() string
• type DNSName
• type DaemonFunc
• type EmailAddress
• type EncodedInstance
• type Env
• type Handler
• type HandlerBuilder
• type Info
• type InfoFn
• type Logger
• type NewBuilderFn
• type QuotaArgs
• type QuotaResult
  • func (r *QuotaResult) IsDefault() bool
• type RemoteCheckHandler
• type RemoteGenerateAttributesHandler
• type RemoteQuotaHandler
• type RemoteReportHandler
• type URI
• type WorkFunc

Functions

func StringEquals

func StringEquals(a interface{}, b interface{}) bool

StringEquals compares if string representations of two basic data types, supported by `istio.mixer.v1.config.descriptor.ValueType`, are equal. Note:

• string representation of nil object is an empty string, so StringEquals with a nil object and a string of value empty "", will evaluate to true.
• This code is optimized for the case when one of the values is of string type. For other cases, this code does reflect.DeepEquals which is not performant.
• For comparing a map to string representation of map, the string must be of the format a=b&c=d, where a and c are keys in the map, and b and d are their corresponding values.

func Stringify

func Stringify(v interface{}) string

Stringify converts basic data types, supported by `istio.mixer.v1.config.descriptor.ValueType`, into string. Note nil object is converted into empty "" string.

Types

type CheckResult

type CheckResult struct {
	// The outcome status of the operation.
	Status rpc.Status
	// ValidDuration represents amount of time for which this result can be considered valid.
	ValidDuration time.Duration
	// ValidUseCount represents the number of uses for which this result can be considered valid.
	ValidUseCount int32
	// RouteDirective represents the route directive return result
	RouteDirective *mixerpb.RouteDirective
}

CheckResult provides return value from check request call on the handler.

func (*CheckResult) IsDefault

func (r *CheckResult) IsDefault() bool

IsDefault returns true if the CheckResult is in its zero state

func (*CheckResult) String

func (r *CheckResult) String() string

type Config

type Config proto.Message

Config represents a chunk of adapter configuration state

type ConfigError

type ConfigError struct {
	Field      string
	Underlying error
}

ConfigError represents an error encountered while validating a block of configuration state.

func (ConfigError) Error

func (e ConfigError) Error() string

Error returns a string representation of the configuration error.

func (ConfigError) String

func (e ConfigError) String() string

type ConfigErrors

type ConfigErrors struct {
	// Multi is the accumulator of errors
	Multi *me.Error
}

ConfigErrors is a collection of configuration errors

The usage pattern for this type is pretty simple:

func (a *adapterState) ValidateConfig(cfg adapter.AspectConfig) (ce *adapter.ConfigErrors) {
    c := cfg.(*Config)
    if c.Url == nil {
        ce = ce.Appendf("url", "Must have a valid URL")
    }
    if c.RetryCount < 0 {
        ce = ce.Appendf("retryCount", "Expecting >= 0, got %d", cfg.RetryCount)
    }
    return
 }

func (*ConfigErrors) Append

func (e *ConfigErrors) Append(field string, err error) *ConfigErrors

Append adds a ConfigError to a multierror. This function is intended to be used by adapter's ValidateConfig method to report errors in configuration. The field parameter indicates the name of the specific configuration field name that is problematic.

func (*ConfigErrors) Appendf

func (e *ConfigErrors) Appendf(field, format string, args ...interface{}) *ConfigErrors

Appendf adds a ConfigError to a multierror. This function is intended to be used by adapter's ValidateConfig method to report errors in configuration. The field parameter indicates the name of the specific configuration field name that is problematic.

func (*ConfigErrors) Error

func (e *ConfigErrors) Error() string

func (*ConfigErrors) Extend

func (e *ConfigErrors) Extend(ee *ConfigErrors) *ConfigErrors

Extend joins 2 configErrors together.

func (*ConfigErrors) String

func (e *ConfigErrors) String() string

type DNSName

type DNSName string

DNSName is associated with template field type istio.policy.v1beta1.DNSName

type DaemonFunc

type DaemonFunc func()

DaemonFunc represents a function to invoke asynchronously to run a long-running background processing loop.

type EmailAddress

type EmailAddress string

EmailAddress is associated with template field type istio.policy.v1beta1.EmailAddress

type EncodedInstance

type EncodedInstance struct {
	Name string
	Data []byte
}

EncodedInstance stores byte encoded data with the instance name

type Env

type Env interface {
	// Logger returns the logger for the adapter to use at runtime.
	Logger() Logger

	// ScheduleWork records a function for execution.
	//
	// Under normal circumstances, this method executes the
	// function on a separate goroutine. But when Mixer is
	// running in single-threaded mode, then the function
	// will be invoked synchronously on the same goroutine.
	//
	// Adapters should not spawn 'naked' goroutines, they should
	// use this method or ScheduleDaemon instead.
	ScheduleWork(fn WorkFunc)

	// ScheduleDaemon records a function for background execution.
	// Unlike ScheduleWork, this method guarantees execution on a
	// different goroutine. Use ScheduleDaemon for long-running
	// background operations, whereas ScheduleWork is for bursty
	// one-shot kind of things.
	//
	// Adapters should not spawn 'naked' goroutines, they should
	// use this method or ScheduleWork instead.
	ScheduleDaemon(fn DaemonFunc)
}

Env defines the environment in which an adapter executes.

type Handler

type Handler interface {
	io.Closer
}

Handler represents default functionality every Adapter must implement.

type HandlerBuilder

type HandlerBuilder interface {
	// SetAdapterConfig gives the builder the adapter-level configuration state.
	SetAdapterConfig(Config)

	// Validate is responsible for ensuring that all the configuration state given to the builder is
	// correct. The Build method is only invoked when Validate has returned success.
	Validate() *ConfigErrors

	// Build must return a handler that implements all the template-specific runtime request serving
	// interfaces that the Builder was configured for.
	// This means the Handler returned by the Build method must implement all the runtime interfaces for all the
	// template the Adapter supports.
	// If the returned Handler fails to implement the required interface that builder was registered for, Mixer will
	// report an error and stop serving runtime traffic to the particular Handler.
	Build(context.Context, Env) (Handler, error)
}

HandlerBuilder represents a factory of handlers. Adapters register builders with Mixer in order to allow Mixer to instantiate handlers on demand.

For a given builder, Mixer calls the various template-specific SetXXX methods, the SetAdapterConfig method, and once done then Mixer calls the Validate followed by the Build method. The Build method returns a handler, which Mixer invokes during request processing.

type Info

type Info struct {
	// Name returns the official name of the adapter, it must be RFC 1035 compatible DNS label.
	// Regex: "^[a-z]([-a-z0-9]*[a-z0-9])?$"
	// Name is used in Istio configuration, therefore it should be descriptive but short.
	// example: denier
	// Vendor adapters should use a vendor prefix.
	// example: mycompany-denier
	Name string
	// Impl is the package implementing the adapter.
	// example: "istio.io/istio/mixer/adapter/denier"
	Impl string
	// Description returns a user-friendly description of the adapter.
	Description string
	// NewBuilder is a function that creates a Builder which implements Builders associated
	// with the SupportedTemplates.
	NewBuilder NewBuilderFn
	// SupportedTemplates expresses all the templates the Adapter wants to serve.
	SupportedTemplates []string
	// DefaultConfig is a default configuration struct for this
	// adapter. This will be used by the configuration system to establish
	// the shape of the block of configuration state passed to the HandlerBuilder.Build method.
	DefaultConfig proto.Message
}

Info describes the Adapter and provides a function to a Handler Builder method.

type InfoFn

type InfoFn func() Info

InfoFn returns an AdapterInfo object that Mixer will use to create HandlerBuilder

type Logger

type Logger interface {
	// Infof logs optional information.
	Infof(format string, args ...interface{})

	// Warningf logs suspect situations and recoverable errors
	Warningf(format string, args ...interface{})

	// Errorf logs error conditions.
	// In addition to generating a log record for the error, this also returns
	// an error instance for convenience.
	Errorf(format string, args ...interface{}) error

	// Debugf logs potentially verbose debug-time data
	Debugf(format string, args ...interface{})

	// InfoEnabled returns whether output of messages at the info level is currently enabled.
	InfoEnabled() bool

	// InfoEnabled returns whether output of messages at the warn level is currently enabled.
	WarnEnabled() bool

	// ErrorEnabled returns whether output of messages at the wanr level is currently enabled.
	ErrorEnabled() bool

	// DebugEnabled returns whether output of messages at the debug level is currently enabled.
	DebugEnabled() bool
}

Logger defines where adapters should output their log state to.

This log is funneled to Mixer which augments it with desirable metadata and then routes it to the right place.

type NewBuilderFn

type NewBuilderFn func() HandlerBuilder

NewBuilderFn is a function that creates a Builder.

type QuotaArgs

type QuotaArgs struct {
	// DeduplicationID is used for deduplicating quota allocation/free calls in the case of
	// failed RPCs and retries. This should be a UUID per call, where the same
	// UUID is used for retries of the same quota allocation or release call.
	DeduplicationID string

	// The amount of quota being allocated or released.
	QuotaAmount int64

	// If true, allows a response to return less quota than requested. When
	// false, the exact requested amount is returned or 0 if not enough quota
	// was available.
	BestEffort bool
}

QuotaArgs supplies the arguments for quota operations.

type QuotaResult

type QuotaResult struct {
	// The outcome status of the operation.
	Status rpc.Status

	// The amount of time until which the returned quota expires, this is 0 for non-expiring quotas.
	ValidDuration time.Duration

	// The total amount of quota returned, may be less than requested.
	Amount int64
}

QuotaResult provides return values from quota allocation calls on the handler

func (*QuotaResult) IsDefault

func (r *QuotaResult) IsDefault() bool

IsDefault returns true if the QuotaResult is in its zero state

type RemoteCheckHandler

type RemoteCheckHandler interface {
	Handler

	// HandleRemoteCheck performs check call based on pre a encoded instance.
	HandleRemoteCheck(ctx context.Context, encodedInstance *EncodedInstance, out *attribute.MutableBag, outPrefix string) (*CheckResult, error)
}

RemoteCheckHandler calls remote check adapter.

type RemoteGenerateAttributesHandler

type RemoteGenerateAttributesHandler interface {
	Handler

	// HandleRemoteGenAttrs performs APA call based on pre encoded instances and returns the decoded output into an attribute bag.
	HandleRemoteGenAttrs(ctx context.Context, encodedInstance *EncodedInstance, out *attribute.MutableBag) error
}

RemoteGenerateAttributesHandler calls remote APA adapter

type RemoteQuotaHandler

type RemoteQuotaHandler interface {
	Handler

	// HandleRemoteQuota performs quota call based on pre encoded instances.
	HandleRemoteQuota(ctx context.Context, encodedInstance *EncodedInstance, args *QuotaArgs) (*QuotaResult, error)
}

RemoteQuotaHandler calls remote report adapter.

type RemoteReportHandler

type RemoteReportHandler interface {
	Handler

	// HandleRemoteReport performs report call based on pre encoded instances.
	HandleRemoteReport(ctx context.Context, encodedInstances []*EncodedInstance) error
}

RemoteReportHandler calls remote report adapter.

type URI

type URI string

URI is associated with template field type istio.policy.v1beta1.Uri

type WorkFunc

type WorkFunc func()

WorkFunc represents a function to invoke.