syntax = "proto3";

package envoy.api.v2;

import "envoy/api/v2/base.proto";

import "google/protobuf/duration.proto";

import "validate/validate.proto";

// [#protodoc-title: gRPC services]
// [#proto-status: draft]

// gRPC service configuration. This is used by :ref:`ApiConfigSource
// <envoy_api_msg_ApiConfigSource>` and filter configurations.
message GrpcService {
  message EnvoyGrpc {
    // The name of the upstream gRPC cluster. SSL credentials will be supplied
    // in the :ref:`Cluster <envoy_api_msg_cluster.Cluster>` :ref:`tls_context
    // <envoy_api_field_cluster.Cluster.tls_context>`.
    string cluster_name = 1 [(validate.rules).string.min_bytes = 1];
  }

  message GoogleGrpc {
    // The target URI when using the `Google C++ gRPC client
    // <https://github.com/grpc/grpc>`_. SSL credentials will be supplied in
    // :ref:`credentials <envoy_api_field_GrpcService.credentials>`.
    string target_uri = 1 [(validate.rules).string.min_bytes = 1];

    // See https://grpc.io/grpc/cpp/structgrpc_1_1_ssl_credentials_options.html.
    message SslCredentials {
      // PEM encoded server root certificates.
      DataSource root_certs = 1;

      // PEM encoded client private key.
      DataSource private_key = 2;

      // PEM encoded client certificate chain.
      DataSource cert_chain = 3;
    }
    SslCredentials ssl_credentials = 2;

    // The human readable prefix to use when emitting statistics for the gRPC
    // service.
    //
    // .. csv-table::
    //    :header: Name, Type, Description
    //    :widths: 1, 1, 2
    //
    //    streams_total, Counter, Total number of streams opened
    //    streams_closed_<gRPC status code>, Counter, Total streams closed with <gRPC status code>
    string stat_prefix = 3 [(validate.rules).string.min_bytes = 1];
  }

  oneof target_specifier {
    option (validate.required) = true;

    // Envoy's in-built gRPC client.
    // See the :ref:`gRPC services overview <arch_overview_grpc_services>`
    // documentation for discussion on gRPC client selection.
    EnvoyGrpc envoy_grpc = 1;

    // `Google C++ gRPC client <https://github.com/grpc/grpc>`_
    // See the :ref:`gRPC services overview <arch_overview_grpc_services>`
    // documentation for discussion on gRPC client selection.
    GoogleGrpc google_grpc = 2;
  }

  // The timeout for the gRPC request. This is the timeout for a specific
  // request.
  google.protobuf.Duration timeout = 3;

  // gRPC credentials as described at
  // https://grpc.io/docs/guides/auth.html#credential-types.
  //
  // .. note::
  //
  //   Credentials are only currently implemented for the Google gRPC client.
  message Credentials {
    oneof credential_specifier {
      option (validate.required) = true;

      // OAuth2 access token, see
      // https://grpc.io/grpc/cpp/namespacegrpc.html#ad3a80da696ffdaea943f0f858d7a360d.
      string access_token = 1;
      // [#comment: TODO(htuch): other gRPC auth types, e.g. IAM credentials, JWT, etc.]
    }
  }
  // A set of credentials that will be composed to form the `channel credentials
  // <https://grpc.io/docs/guides/auth.html#credential-types>`_.
  repeated Credentials credentials = 4;
}