Documentation ¶
Overview ¶
Package adapter defines the types consumed by adapter implementations to interface with Mixer.
Index ¶
- func NewContextWithRequestData(ctx context.Context, reqData *RequestData) context.Context
- type AccessLogsAspect
- type AccessLogsBuilder
- type ApplicationLogsAspect
- type ApplicationLogsBuilder
- type Aspect
- type AttributesGenerator
- type AttributesGeneratorBuilder
- type Builder
- type CacheabilityInfo
- type CheckResult
- type Config
- type ConfigError
- type ConfigErrors
- type ConfigValidator
- type DaemonFunc
- type DefaultBuilder
- type DenialsAspect
- type DenialsBuilder
- type Env
- type Handler
- type HandlerBuilder
- type Info
- type InfoFn
- type LabelType
- type ListsAspect
- type ListsBuilder
- type LogEntry
- type Logger
- type NewBuilderFn
- type QuotaArgs
- type QuotaArgsLegacy
- type QuotaDefinition
- type QuotaResult
- type QuotaResultLegacy
- type QuotasAspect
- type QuotasBuilder
- type RegisterFn
- type Registrar
- type RequestData
- type Result
- type Service
- type Severity
- type VerbosityLevel
- type WorkFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewContextWithRequestData ¶
func NewContextWithRequestData(ctx context.Context, reqData *RequestData) context.Context
NewContextWithRequestData returns a new Context that carries the provided RequestData value.
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 ¶
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 ConfigError ¶
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 ¶
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 ¶
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 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 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.
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 RequestData ¶
type RequestData struct { // Details about the destination service. DestinationService Service }
RequestData defines information about a request, for example details about the destination service.
This data is delivered to the adapters through the passed in context object. Adapter can retrieve this data from the context by invoking `RequestDataFromContext`.
func RequestDataFromContext ¶
func RequestDataFromContext(ctx context.Context) (*RequestData, bool)
RequestDataFromContext retrieves the RequestData object contained inside the given context. Returns false if the given context does not contains a valid RequestData object.
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 Service ¶
type Service struct { // Fully qualified name of the service. FullName string }
Service defines the service specific details.
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 ¶
SeverityByName returns a logger.Severity based on the supplied string. Default (with false) is returned if the name is not found.
func (Severity) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
type VerbosityLevel ¶
type VerbosityLevel int32
VerbosityLevel is used to control the level of detailed logging for adapters.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package istio_mixer_v1_config_template is a generated protocol buffer package.
|
Package istio_mixer_v1_config_template is a generated protocol buffer package. |
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. |