// Copyright 2017 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";

package istio.mixer.v1.config.client;

option go_package="istio.io/api/mixer/v1/config/client";

import "gogoproto/gogo.proto";

import "mixer/v1/attributes.proto";
import "mixer/v1/config/client/service.proto";

option (gogoproto.goproto_getters_all) = false;
option (gogoproto.equal_all) = false;
option (gogoproto.gostring_all) = false;

// HTTPAPISpec defines the canonical configuration for generating
// API-related attributes from HTTP requests based on the method and
// uri templated path matches. It is sufficient for defining the API
// surface of a service for the purposes of API attribute
// generation. It is not intended to represent auth, quota,
// documentation, or other information commonly found in other API
// specifications, e.g. OpenAPI.
//
// Existing standards that define operations (or methods) in terms of
// HTTP methods and paths can be normalized to this format for use in
// Istio. For example, a simple petstore API described by OpenAPIv2
// [here](https://github.com/googleapis/gnostic/blob/master/examples/v2.0/yaml/petstore-simple.yaml)
// can be represented with the following HTTPAPISpec.
//
//     apiVersion: config.istio.io/v1alpha2
//     kind: HTTPAPISpec
//     metadata:
//       name: petstore
//       namespace: default
//     spec:
//       attributes:
//         api.service: petstore.swagger.io
//         api.version: 1.0.0
//       patterns:
//       - attributes:
//           api.operation: findPets
//         httpMethod: GET
//         uriTemplate: /api/pets
//       - attributes:
//           api.operation: addPet
//         httpMethod: POST
//         uriTemplate: /api/pets
//       - attributes:
//           api.operation: findPetById
//         httpMethod: GET
//         uriTemplate: /api/pets/{id}
//       - attributes:
//           api.operation: deletePet
//         httpMethod: DELETE
//         uriTemplate: /api/pets/{id}
//       api_keys:
//       - query: api-key
//
message HTTPAPISpec {
  // List of attributes that are generated when *any* of the HTTP
  // patterns match. This list typically includes the "api.service"
  // and "api.version" attributes.
  Attributes attributes = 1;

  // List of HTTP patterns to match.
  repeated HTTPAPISpecPattern patterns = 2;

  // List of APIKey that describes how to extract an API-KEY from an
  // HTTP request. The first API-Key match found in the list is used,
  // i.e. 'OR' semantics.
  //
  // The following default policies are used to generate the
  // `request.api_key` attribute if no explicit APIKey is defined.
  //
  //     `query: key, `query: api_key`, and then `header: x-api-key`
  //
  repeated APIKey api_keys = 3;
}

// HTTPAPISpecPattern defines a single pattern to match against
// incoming HTTP requests. The per-pattern list of attributes is
// generated if both the http_method and uri_template match. In
// addition, the top-level list of attributes in the HTTPAPISpec is also
// generated.
//
//     pattern:
//     - attributes
//         api.operation: doFooBar
//       httpMethod: GET
//       uriTemplate: /foo/bar
//
message HTTPAPISpecPattern {
  // List of attributes that are generated if the HTTP request matches
  // the specified http_method and uri_template. This typically
  // includes the "api.operation" attribute.
  Attributes attributes = 1;

  // HTTP request method to match against as defined by
  // [rfc7231](https://tools.ietf.org/html/rfc7231#page-21). For
  // example: GET, HEAD, POST, PUT, DELETE.
  string http_method = 2;

  oneof pattern {
    // URI template to match against as defined by
    // [rfc6570](https://tools.ietf.org/html/rfc6570). For example, the
    // following are valid URI templates:
    //
    //     /pets
    //     /pets/{id}
    //     /dictionary/{term:1}/{term}
    //     /search{?q*,lang}
    //
    string uri_template = 3;

    // EXPERIMENTAL:
    //
    // ecmascript style regex-based match as defined by
    // [EDCA-262](http://en.cppreference.com/w/cpp/regex/ecmascript). For
    // example,
    //
    //     "^/pets/(.*?)?"
    //
    string regex = 4;
  }
}

// APIKey defines the explicit configuration for generating the
// `request.api_key` attribute from HTTP requests.
//
// See https://swagger.io/docs/specification/authentication/api-keys
// for a general overview of API keys as defined by OpenAPI.
message APIKey {
  oneof key {
    // API Key is sent as a query parameter. `query` represents the
    // query string parameter name.
    //
    // For example, `query=api_key` should be used with the
    // following request:
    //
    //     GET /something?api_key=abcdef12345
    //
    string query = 1;

    // API key is sent in a request header. `header` represents the
    // header name.
    //
    // For example, `header=X-API-KEY` should be used with the
    // following request:
    //
    //     GET /something HTTP/1.1
    //     X-API-Key: abcdef12345
    //
    string header = 2;

    // API key is sent in a
    // [cookie](https://swagger.io/docs/specification/authentication/cookie-authentication),
    //
    // For example, `cookie=X-API-KEY` should be used for the
    // following request:
    //
    //     GET /something HTTP/1.1
    //     Cookie: X-API-KEY=abcdef12345
    //
    string cookie = 3;
  }
}

// HTTPAPISpecReference defines a reference to an HTTPAPISpec. This is
// typically used for establishing bindings between an HTTPAPISpec and an
// IstioService. For example, the following defines an
// HTTPAPISpecReference for service `foo` in namespace `bar`.
//
//     - name: foo
//       namespace: bar
//
message HTTPAPISpecReference {
  // REQUIRED. The short name of the HTTPAPISpec. This is the resource
  // name defined by the metadata name field.
  string name = 1;

  // Optional namespace of the HTTPAPISpec. Defaults to the encompassing
  // HTTPAPISpecBinding's metadata namespace field.
  string namespace = 2;
}

// HTTPAPISpecBinding defines the binding between HTTPAPISpecs and one or more
// IstioService. For example, the following establishes a binding
// between the HTTPAPISpec `petstore` and service `foo` in namespace `bar`.
//
//     apiVersion: config.istio.io/v1alpha2
//     kind: HTTPAPISpecBinding
//     metadata:
//       name: my-binding
//       namespace: default
//     spec:
//       services:
//       - name: foo
//         namespace: bar
//       api_specs:
//       - name: petstore
//         namespace: default
//
message HTTPAPISpecBinding {
  // REQUIRED. One or more services to map the listed HTTPAPISpec onto.
  repeated IstioService services = 1;

  // REQUIRED. One or more HTTPAPISpec references that should be mapped to
  // the specified service(s). The aggregate collection of match
  // conditions defined in the HTTPAPISpecs should not overlap.
  repeated HTTPAPISpecReference api_specs = 2;
}
