271 lines
11 KiB
Protocol Buffer
271 lines
11 KiB
Protocol Buffer
// Copyright 2016 Istio Authors
|
||
//
|
||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
// you may not use this file except in compliance with the License.
|
||
// You may obtain a copy of the License at
|
||
//
|
||
// http://www.apache.org/licenses/LICENSE-2.0
|
||
//
|
||
// Unless required by applicable law or agreed to in writing, software
|
||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
// See the License for the specific language governing permissions and
|
||
// limitations under the License.
|
||
|
||
syntax = "proto3";
|
||
|
||
// This package defines the Mixer API that the sidecar proxy uses to perform
|
||
// precondition checks, manage quotas, and report telemetry.
|
||
package istio.mixer.v1;
|
||
|
||
option go_package = "istio.io/api/mixer/v1";
|
||
option cc_generic_services = true;
|
||
|
||
import "gogoproto/gogo.proto";
|
||
import "google/protobuf/duration.proto";
|
||
import "google/rpc/status.proto";
|
||
import "mixer/v1/attributes.proto";
|
||
|
||
option (gogoproto.goproto_getters_all) = false;
|
||
option (gogoproto.equal_all) = false;
|
||
option (gogoproto.gostring_all) = false;
|
||
option cc_enable_arenas = true;
|
||
|
||
// Mixer provides three core features:
|
||
//
|
||
// - *Precondition Checking*. Enables callers to verify a number of preconditions
|
||
// before responding to an incoming request from a service consumer.
|
||
// Preconditions can include whether the service consumer is properly
|
||
// authenticated, is on the service’s whitelist, passes ACL checks, and more.
|
||
//
|
||
// - *Quota Management*. Enables services to allocate and free quota on a number
|
||
// of dimensions, Quotas are used as a relatively simple resource management tool
|
||
// to provide some fairness between service consumers when contending for limited
|
||
// resources. Rate limits are examples of quotas.
|
||
//
|
||
// - *Telemetry Reporting*. Enables services to report logging and monitoring.
|
||
// In the future, it will also enable tracing and billing streams intended for
|
||
// both the service operator as well as for service consumers.
|
||
service Mixer {
|
||
// Checks preconditions and allocate quota before performing an operation.
|
||
// The preconditions enforced depend on the set of supplied attributes and
|
||
// the active configuration.
|
||
rpc Check(CheckRequest) returns (CheckResponse) {}
|
||
|
||
// Reports telemetry, such as logs and metrics.
|
||
// The reported information depends on the set of supplied attributes and the
|
||
// active configuration.
|
||
rpc Report(ReportRequest) returns (ReportResponse) {}
|
||
}
|
||
|
||
// Used to get a thumbs-up/thumbs-down before performing an action.
|
||
message CheckRequest {
|
||
// parameters for a quota allocation
|
||
message QuotaParams {
|
||
// Amount of quota to allocate
|
||
int64 amount = 1;
|
||
|
||
// When true, supports returning less quota than what was requested.
|
||
bool best_effort = 2;
|
||
}
|
||
|
||
// The attributes to use for this request.
|
||
//
|
||
// Mixer's configuration determines how these attributes are used to
|
||
// establish the result returned in the response.
|
||
CompressedAttributes attributes = 1 [(gogoproto.nullable) = false];
|
||
|
||
// The number of words in the global dictionary, used with to populate the attributes.
|
||
// This value is used as a quick way to determine whether the client is using a dictionary that
|
||
// the server understands.
|
||
uint32 global_word_count = 2;
|
||
|
||
// Used for deduplicating `Check` 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 call.
|
||
string deduplication_id = 3;
|
||
|
||
// The individual quotas to allocate
|
||
map<string, QuotaParams> quotas = 4 [(gogoproto.nullable) = false];
|
||
}
|
||
|
||
// The response generated by the Check method.
|
||
message CheckResponse {
|
||
|
||
// Expresses the result of a precondition check.
|
||
message PreconditionResult {
|
||
reserved 4;
|
||
|
||
// A status code of OK indicates all preconditions were satisfied. Any other code indicates not
|
||
// all preconditions were satisfied and details describe why.
|
||
google.rpc.Status status = 1 [(gogoproto.nullable) = false];
|
||
|
||
// The amount of time for which this result can be considered valid.
|
||
google.protobuf.Duration valid_duration = 2 [(gogoproto.nullable) = false, (gogoproto.stdduration) = true];
|
||
|
||
// The number of uses for which this result can be considered valid.
|
||
int32 valid_use_count = 3;
|
||
|
||
// The total set of attributes that were used in producing the result
|
||
// along with matching conditions.
|
||
ReferencedAttributes referenced_attributes = 5;
|
||
|
||
// An optional routing directive, used to manipulate the traffic metadata
|
||
// whenever all preconditions are satisfied.
|
||
RouteDirective route_directive = 6;
|
||
}
|
||
|
||
// Expresses the result of a quota allocation.
|
||
message QuotaResult {
|
||
// The amount of time for which this result can be considered valid.
|
||
google.protobuf.Duration valid_duration = 1 [(gogoproto.nullable) = false, (gogoproto.stdduration) = true];
|
||
|
||
// The amount of granted quota. When `QuotaParams.best_effort` is true, this will be >= 0.
|
||
// If `QuotaParams.best_effort` is false, this will be either 0 or >= `QuotaParams.amount`.
|
||
int64 granted_amount = 2;
|
||
|
||
// A status code of OK indicates quota was fetched successfully.
|
||
// Any other code indicates error in fetching quota.
|
||
google.rpc.Status status = 6 [(gogoproto.nullable) = false];
|
||
|
||
// The total set of attributes that were used in producing the result
|
||
// along with matching conditions.
|
||
ReferencedAttributes referenced_attributes = 5 [(gogoproto.nullable) = false];
|
||
}
|
||
|
||
// The precondition check results.
|
||
PreconditionResult precondition = 2 [(gogoproto.nullable) = false];
|
||
|
||
// The resulting quota, one entry per requested quota.
|
||
map<string, QuotaResult> quotas = 3 [(gogoproto.nullable) = false];
|
||
}
|
||
|
||
// Describes the attributes that were used to determine the response.
|
||
// This can be used to construct a response cache.
|
||
message ReferencedAttributes {
|
||
// How an attribute's value was matched
|
||
enum Condition {
|
||
CONDITION_UNSPECIFIED = 0; // should not occur
|
||
ABSENCE = 1; // match when attribute doesn't exist
|
||
EXACT = 2; // match when attribute value is an exact byte-for-byte match
|
||
REGEX = 3; // match when attribute value matches the included regex
|
||
}
|
||
|
||
// Describes a single attribute match.
|
||
message AttributeMatch {
|
||
// The name of the attribute. This is a dictionary index encoded in a manner identical
|
||
// to all strings in the [CompressedAttributes][istio.mixer.v1.CompressedAttributes] message.
|
||
sint32 name = 1;
|
||
|
||
// The kind of match against the attribute value.
|
||
Condition condition = 2;
|
||
|
||
// If a REGEX condition is provided for a STRING_MAP attribute,
|
||
// clients should use the regex value to match against map keys.
|
||
// RE2 style regex-based match (https://github.com/google/re2/wiki/Syntax).
|
||
string regex = 3;
|
||
|
||
// A key in a STRING_MAP. When multiple keys from a STRING_MAP
|
||
// attribute were referenced, there will be multiple AttributeMatch
|
||
// messages with different map_key values. Values for map_key SHOULD
|
||
// be ignored for attributes that are not STRING_MAP.
|
||
//
|
||
// Indices for the keys are used (taken either from the
|
||
// message dictionary from the `words` field or the global dictionary).
|
||
//
|
||
// If no map_key value is provided for a STRING_MAP attribute, the
|
||
// entire STRING_MAP will be used.
|
||
sint32 map_key = 4;
|
||
}
|
||
|
||
// The message-level dictionary. Refer to [CompressedAttributes][istio.mixer.v1.CompressedAttributes] for information
|
||
// on using dictionaries.
|
||
repeated string words = 1;
|
||
|
||
// Describes a set of attributes.
|
||
repeated AttributeMatch attribute_matches = 2 [(gogoproto.nullable) = false];
|
||
}
|
||
|
||
// Operation on HTTP headers to replace, append, or remove a header. Header
|
||
// names are normalized to lower-case with dashes, e.g. "x-request-id".
|
||
// Pseudo-headers ":path", ":authority", and ":method" are supported to modify
|
||
// the request headers.
|
||
message HeaderOperation {
|
||
// Operation type.
|
||
enum Operation {
|
||
REPLACE = 0; // replaces the header with the given name
|
||
REMOVE = 1; // removes the header with the given name (the value is ignored)
|
||
APPEND = 2; // appends the value to the header value, or sets it if not present
|
||
}
|
||
// Header name.
|
||
string name = 1;
|
||
|
||
// Header value.
|
||
string value = 2;
|
||
|
||
// Header operation.
|
||
Operation operation = 3;
|
||
}
|
||
|
||
// Expresses the routing manipulation actions to be performed on behalf of
|
||
// Mixer in response to a precondition check.
|
||
message RouteDirective {
|
||
// Operations on the request headers.
|
||
repeated HeaderOperation request_header_operations = 1 [(gogoproto.nullable) = false];
|
||
|
||
// Operations on the response headers.
|
||
repeated HeaderOperation response_header_operations = 2 [(gogoproto.nullable) = false];
|
||
|
||
// If set, enables a direct response without proxying the request to the routing
|
||
// destination. Required to be a value in the 2xx or 3xx range.
|
||
uint32 direct_response_code = 3;
|
||
|
||
// Supplies the response body for the direct response.
|
||
// If this setting is omitted, no body is included in the generated response.
|
||
string direct_response_body = 4;
|
||
}
|
||
|
||
// Used to report telemetry after performing one or more actions.
|
||
message ReportRequest {
|
||
// next value: 5
|
||
|
||
// Used to signal how the sets of compressed attributes should be reconstituted server-side.
|
||
enum RepeatedAttributesSemantics {
|
||
// Use delta encoding between sets of compressed attributes to reduce the overall on-wire
|
||
// request size. Each individual set of attributes is used to modify the previous set.
|
||
// NOTE: There is no way with this encoding to specify attribute value deletion. This
|
||
// option should be used with extreme caution.
|
||
DELTA_ENCODING = 0;
|
||
|
||
// Treat each set of compressed attributes as complete - independent from other sets
|
||
// in this request. This will result in on-wire duplication of attributes and values, but
|
||
// will allow for proper accounting of absent values in overall encoding.
|
||
INDEPENDENT_ENCODING = 1;
|
||
}
|
||
|
||
// The attributes to use for this request.
|
||
//
|
||
// Each `Attributes` element represents the state of a single action. Multiple actions
|
||
// can be provided in a single message in order to improve communication efficiency. The
|
||
// client can accumulate a set of actions and send them all in one single message.
|
||
repeated CompressedAttributes attributes = 1 [(gogoproto.nullable) = false];
|
||
|
||
// Indicates how to decode the attributes sets in this request.
|
||
RepeatedAttributesSemantics repeated_attributes_semantics = 4;
|
||
|
||
// The default message-level dictionary for all the attributes.
|
||
// Individual attribute messages can have their own dictionaries, but if they don't
|
||
// then this set of words, if it is provided, is used instead.
|
||
//
|
||
// This makes it possible to share the same dictionary for all attributes in this
|
||
// request, which can substantially reduce the overall request size.
|
||
repeated string default_words = 2;
|
||
|
||
// The number of words in the global dictionary.
|
||
// To detect global dictionary out of sync between client and server.
|
||
uint32 global_word_count = 3;
|
||
}
|
||
|
||
// Used to carry responses to telemetry reports
|
||
message ReportResponse {
|
||
}
|