adapter

package
v0.0.0-...-5253b6b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 27, 2017 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AccessLogsAspect 

type AccessLogsAspect interface {
	Aspect

	// LogAccess directs a backend adapter to process a batch of
	// access log entries derived from potentially several Report()
	// calls. LogEntries generated for this Aspect will only have
	// the fields LogName, Labels, and TextPayload populated.
	// TextPayload will contain the generated access log string,
	// based on the aspect configuration.
	LogAccess([]LogEntry) error
}

AccessLogsAspect handles access log data within Mixer.

type AccessLogsBuilder 

type AccessLogsBuilder interface {
	Builder

	// NewAccessLogsAspect returns a new instance of the AccessLogger aspect.
	NewAccessLogsAspect(env Env, c Config) (AccessLogsAspect, error)
}

AccessLogsBuilder builds instances of the AccessLogger aspect.

type ApplicationLogsAspect 

type ApplicationLogsAspect interface {
	Aspect

	// Log directs a backend adapter to process a batch of
	// log entries derived from potentially several Report() calls.
	Log([]LogEntry) error
}

ApplicationLogsAspect handles log data within Mixer.

type ApplicationLogsBuilder 

type ApplicationLogsBuilder interface {
	Builder

	// NewApplicationLogsAspect returns a new instance of the Logger aspect.
	NewApplicationLogsAspect(env Env, c Config) (ApplicationLogsAspect, error)
}

ApplicationLogsBuilder builds instances of the Logger aspect.

type Aspect 

type Aspect interface {
	io.Closer
}

Aspect represents a type of end-user functionality with particular semantics. Adapters expose functionality to Mixer by implementing one or more aspects.

type AttributesGenerator 

type AttributesGenerator interface {
	Aspect

	// Generate takes a map of named input values and produces an
	// output map of named values. The input values will be
	// populated via configured attribute expressions. The output
	// map will be used to create new attribute values for use by
	// the rest of Mixer, as controlled by aspect config.
	Generate(map[string]interface{}) (map[string]interface{}, error)
}

AttributesGenerator provides the interface for the Attributes aspect. Implementors generate attribute values for consumption by other aspects within Mixer.

type AttributesGeneratorBuilder 

type AttributesGeneratorBuilder interface {
	Builder

	// BuildAttributesGenerator creates a new AttributesGenerator
	// based on the supplied configuration and environment.
	BuildAttributesGenerator(env Env, c Config) (AttributesGenerator, error)
}

An AttributesGeneratorBuilder is responsible for producing new instances that implement the AttributesGenerator aspect.

type Builder 

type Builder interface {
	io.Closer
	ConfigValidator

	// Name returns the official name of the aspects produced by this builder.
	Name() string

	// Description returns a user-friendly description of the aspects produced by this builder.
	Description() string
}

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

type CacheabilityInfo 

type CacheabilityInfo struct {
	// ValidDuration represents amount of time for which this result can be considered valid.
	ValidDuration time.Duration
	// ValidUseCount represent the number of uses for which this result can be considered valid.
	ValidUseCount int64
}

CacheabilityInfo represents information about when to refresh the cache.

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
}

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

func (*CheckResult) Combine 

func (r *CheckResult) Combine(otherPtr interface{}) interface{}

Combine combines other result with self. It does not handle Status.

func (*CheckResult) GetStatus 

func (r *CheckResult) GetStatus() rpc.Status

GetStatus gets status embedded in the result.

func (*CheckResult) SetStatus 

func (r *CheckResult) SetStatus(s rpc.Status)

SetStatus embeds status in result.

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 ConfigValidator 

type ConfigValidator interface {
	// DefaultConfig returns 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 NewAspect method.
	DefaultConfig() (c Config)

	// ValidateConfig determines whether the given configuration meets all correctness requirements.
	ValidateConfig(c Config) *ConfigErrors
}

ConfigValidator handles adapter configuration defaults and validation.

type DaemonFunc 

type DaemonFunc func()

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

type DefaultBuilder 

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

DefaultBuilder provides default adapter builder behavior for adapters. TODO: rename to DefaultFactory

func NewDefaultBuilder 

func NewDefaultBuilder(name, desc string, config Config) DefaultBuilder

NewDefaultBuilder creates a new builder struct with the supplied params.

func (DefaultBuilder) Close 

func (DefaultBuilder) Close() error

Close provides a hook for behavior used to cleanup a builder when it is removed.

func (DefaultBuilder) DefaultConfig 

func (b DefaultBuilder) DefaultConfig() Config

DefaultConfig returns a default configuration struct for the adapters built by this builder.

func (DefaultBuilder) Description 

func (b DefaultBuilder) Description() string

Description returns the official description of the adapter produced by this builder.

func (DefaultBuilder) Name 

func (b DefaultBuilder) Name() string

Name returns the official name of the adapter produced by this builder.

func (DefaultBuilder) ValidateConfig 

func (DefaultBuilder) ValidateConfig(c Config) (ce *ConfigErrors)

ValidateConfig determines whether the given configuration meets all correctness requirements.

type DenialsAspect 

type DenialsAspect interface {
	Aspect

	// Deny always returns an error
	Deny() rpc.Status
}

DenialsAspect always fail with an error.

type DenialsBuilder 

type DenialsBuilder interface {
	Builder

	// NewDenialsAspect returns a new instance of the DenyChecker aspect.
	NewDenialsAspect(env Env, c Config) (DenialsAspect, error)
}

DenialsBuilder builds instances of the DenyChecker aspect.

type Env 

type Env interface {
	// Logger returns the logger for the aspect 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 aspect 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/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 expressess 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. TODO change this to Info when we delete the ApplicationLog.Info enum.

type InfoFn 

type InfoFn func() Info

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

type LabelType 

type LabelType int

LabelType defines the set of known label types that can be generated by Mixer. 

const (
	String LabelType = iota
	Int64
	Float64
	Bool
	Time
	Duration
	IPAddress
	EmailAddress
	URI
	DNSName
	StringMap
)

Supported types of labels.

type ListsAspect 

type ListsAspect interface {
	Aspect

	// CheckList verifies whether the given symbol is on the list.
	CheckList(symbol string) (bool, error)
}

ListsAspect checks the presence of a given symbol against a list.

type ListsBuilder 

type ListsBuilder interface {
	Builder

	// NewListsAspect returns a new instance of the ListChecker aspect.
	NewListsAspect(env Env, c Config) (ListsAspect, error)
}

ListsBuilder builds instances of the ListChecker aspect.

type LogEntry 

type LogEntry struct {
	// LogName is the name of the log in which to record this entry.
	LogName string `json:"logName,omitempty"`
	// Labels are a set of metadata associated with this entry.
	// For instance, Labels can be used to describe the monitored
	// resource that corresponds to the log entry.
	Labels map[string]interface{} `json:"labels,omitempty"`
	// Timestamp is the time value for the log entry
	Timestamp string `json:"timestamp,omitempty"`
	// Severity indicates the log level for the log entry.
	Severity Severity `json:"severity,omitempty"`
	// TextPayload is textual logs data for which the entry is being
	// generated. For Access Logs, this will be the formatted access
	// log string generated by mixer, based on the aspect config.
	TextPayload string `json:"textPayload,omitempty"`
	// StructPayload is a structured set of data, extracted from
	// a serialized JSON Object, that represent the actual data
	// for which the entry is being generated.
	StructPayload map[string]interface{} `json:"structPayload,omitempty"`
}

LogEntry is the set of data that together constitutes a log entry.

type Logger 

type Logger interface {
	// Used to determine if the supplied verbosity level is enabled.
	// Example:
	//
	// if env.Logger().VerbosityLevel(4) {
	//   env.Logger().Infof(...)
	// }
	VerbosityLevel(level VerbosityLevel) bool

	// 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
}

Logger defines where aspects should output their log state to.

This log information 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 QuotaArgsLegacy 

type QuotaArgsLegacy struct {
	// The metadata describing the quota.
	Definition *QuotaDefinition

	// 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

	// Labels determine the identity of the quota cell.
	Labels map[string]interface{}
}

QuotaArgsLegacy supplies the arguments for quota operations.

type QuotaDefinition 

type QuotaDefinition struct {
	// Name of this quota definition.
	Name string

	// DisplayName is an optional user-friendly name for this quota.
	DisplayName string

	// Description is an optional user-friendly description for this quota.
	Description string

	// MaxAmount defines the upper limit for the quota
	MaxAmount int64

	// Expiration determines the size of rolling window. A value of 0 means no rolling window,
	// allocated quota remains allocated until explicitly released.
	Expiration time.Duration

	// Labels are the names of keys for dimensional data that will
	// be generated at runtime and passed along with quota values.
	Labels map[string]LabelType
}

QuotaDefinition is used to describe an individual quota that the aspect will encounter at runtime.

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) GetStatus 

func (r QuotaResult) GetStatus() rpc.Status

GetStatus gets status embedded in the result.

func (*QuotaResult) SetStatus 

func (r *QuotaResult) SetStatus(s rpc.Status)

SetStatus embeds status in result.

type QuotaResultLegacy 

type QuotaResultLegacy struct {
	// The amount of time until which the returned quota expires, this is 0 for non-expiring quotas.
	Expiration time.Duration

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

QuotaResultLegacy provides return values from quota allocation calls

type QuotasAspect 

type QuotasAspect interface {
	Aspect

	// Alloc allocates the specified amount or fails when not available.
	Alloc(QuotaArgsLegacy) (QuotaResultLegacy, error)

	// AllocBestEffort allocates from 0 to the specified amount, based on availability.
	AllocBestEffort(QuotaArgsLegacy) (QuotaResultLegacy, error)

	// ReleaseBestEffort releases from 0 to the specified amount, based on current usage.
	ReleaseBestEffort(QuotaArgsLegacy) (int64, error)
}

QuotasAspect handles quotas and rate limits within Mixer.

type QuotasBuilder 

type QuotasBuilder interface {
	Builder

	// NewQuotasAspect returns a new instance of the Quota aspect.
	NewQuotasAspect(env Env, c Config, quotas map[string]*QuotaDefinition) (QuotasAspect, error)
}

QuotasBuilder builds new instances of the Quota aspect.

type RegisterFn 

type RegisterFn func(Registrar)

RegisterFn is a function Mixer invokes to trigger adapters to register their aspect builders. It must succeed or panic().

type Registrar 

type Registrar interface {
	// RegisterAttributesGeneratorBuilder registers a new builder for the
	// AttributeGenerators aspect.
	RegisterAttributesGeneratorBuilder(AttributesGeneratorBuilder)

	// RegisterQuotasBuilder registers a new Quota builder.
	RegisterQuotasBuilder(QuotasBuilder)
}

Registrar is used by adapters to register aspect builders.

type Result 

type Result interface {
	// Get status embedded in the result.
	GetStatus() rpc.Status

	// Set status embeds status in result.
	SetStatus(rpc.Status)
}

Result is the common interface supported by Results.

type Severity 

type Severity int

Severity provides a set of logging levels for logger.Entry. 

const (
	// Default indicates that the log entry has no assigned severity level.
	Default Severity = iota
	// Debug indicates that the log entry has debug or trace information.
	Debug
	// InfoLegacy indicates that the log entry has routine info, including rpc or performance data
	InfoLegacy
	// Notice indicates that the log entry has normal, but significant events, such as config changes.
	Notice
	// Warning indicates that the log entry has data on events that might cause issues.
	Warning
	// Error indicates that the log entry has data on events that are likely to cause issues.
	Error
	// Critical indicates that the log entry has data on events related to severe problems or outages.
	Critical
	// Alert indicates that the log entry has data on which human action should be taken immediately.
	Alert
	// Emergency indicates that the log entry has data on one (or more) systems that are unusable.
	Emergency
)

func SeverityByName 

func SeverityByName(s string) (Severity, bool)

SeverityByName returns a logger.Severity based on the supplied string. Default (with false) is returned if the name is not found.

func (Severity) MarshalJSON 

func (s Severity) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (Severity) String 

func (s Severity) String() string

type VerbosityLevel 

type VerbosityLevel int32

VerbosityLevel is used to control the level of detailed logging for adapters.

type WorkFunc 

type WorkFunc func()

WorkFunc represents a function to invoke.

Source Files

View all Source files

Directories

Path Synopsis
Package test provides utility functions to assist in creating quality tests for adapters.
 Package test provides utility functions to assist in creating quality tests for adapters.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.