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

    // 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.
    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 reconstitued 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 {
}