// Copyright 2022 Google LLC
//
// 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 google.cloud.networkmanagement.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/networkmanagement/v1/trace.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";

option csharp_namespace = "Google.Cloud.NetworkManagement.V1";
option go_package = "cloud.google.com/go/networkmanagement/apiv1/networkmanagementpb;networkmanagementpb";
option java_multiple_files = true;
option java_outer_classname = "TestOuterClass";
option java_package = "com.google.cloud.networkmanagement.v1";
option php_namespace = "Google\\Cloud\\NetworkManagement\\V1";
option ruby_package = "Google::Cloud::NetworkManagement::V1";

// A Connectivity Test for a network reachability analysis.
message ConnectivityTest {
  option (google.api.resource) = {
    type: "networkmanagement.googleapis.com/ConnectivityTest"
    pattern: "projects/{project}/locations/global/connectivityTests/{test}"
  };

  // Required. Unique name of the resource using the form:
  //     `projects/{project_id}/locations/global/connectivityTests/{test_id}`
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // The user-supplied description of the Connectivity Test.
  // Maximum of 512 characters.
  string description = 2;

  // Required. Source specification of the Connectivity Test.
  //
  // You can use a combination of source IP address, virtual machine
  // (VM) instance, or Compute Engine network to uniquely identify
  // the source location.
  //
  // Examples:
  // If the source IP address is an internal IP address within a Google Cloud
  // Virtual Private Cloud (VPC) network, then you must also specify the VPC
  // network. Otherwise, specify the VM instance, which already contains its
  // internal IP address and VPC network information.
  //
  // If the source of the test is within an on-premises network, then you must
  // provide the destination VPC network.
  //
  // If the source endpoint is a Compute Engine VM instance with multiple
  // network interfaces, the instance itself is not sufficient to identify the
  // endpoint. So, you must also specify the source IP address or VPC network.
  //
  // A reachability analysis proceeds even if the source location is
  // ambiguous. However, the test result may include endpoints that you don't
  // intend to test.
  Endpoint source = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. Destination specification of the Connectivity Test.
  //
  // You can use a combination of destination IP address, Compute Engine
  // VM instance, or VPC network to uniquely identify the destination
  // location.
  //
  // Even if the destination IP address is not unique, the source IP
  // location is unique. Usually, the analysis can infer the destination
  // endpoint from route information.
  //
  // If the destination you specify is a VM instance and the instance has
  // multiple network interfaces, then you must also specify either
  // a destination IP address  or VPC network to identify the destination
  // interface.
  //
  // A reachability analysis proceeds even if the destination location is
  // ambiguous. However, the result can include endpoints that you don't
  // intend to test.
  Endpoint destination = 4 [(google.api.field_behavior) = REQUIRED];

  // IP Protocol of the test. When not provided, "TCP" is assumed.
  string protocol = 5;

  // Other projects that may be relevant for reachability analysis.
  // This is applicable to scenarios where a test can cross project boundaries.
  repeated string related_projects = 6;

  // Output only. The display name of a Connectivity Test.
  string display_name = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Resource labels to represent user-provided metadata.
  map<string, string> labels = 8;

  // Output only. The time the test was created.
  google.protobuf.Timestamp create_time = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time the test's configuration was updated.
  google.protobuf.Timestamp update_time = 11
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The reachability details of this test from the latest run.
  // The details are updated when creating a new test, updating an
  // existing test, or triggering a one-time rerun of an existing test.
  ReachabilityDetails reachability_details = 12
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Source or destination of the Connectivity Test.
message Endpoint {
  // The type definition of an endpoint's network. Use one of the
  // following choices:
  enum NetworkType {
    // Default type if unspecified.
    NETWORK_TYPE_UNSPECIFIED = 0;

    // A network hosted within Google Cloud.
    // To receive more detailed output, specify the URI for the source or
    // destination network.
    GCP_NETWORK = 1;

    // A network hosted outside of Google Cloud.
    // This can be an on-premises network, or a network hosted by another cloud
    // provider.
    NON_GCP_NETWORK = 2;
  }

  // The IP address of the endpoint, which can be an external or internal IP.
  // An IPv6 address is only allowed when the test's destination is a
  // [global load balancer VIP](/load-balancing/docs/load-balancing-overview).
  string ip_address = 1;

  // The IP protocol port of the endpoint.
  // Only applicable when protocol is TCP or UDP.
  int32 port = 2;

  // A Compute Engine instance URI.
  string instance = 3;

  // A cluster URI for [Google Kubernetes Engine
  // master](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture).
  string gke_master_cluster = 7;

  // A [Cloud SQL](https://cloud.google.com/sql) instance URI.
  string cloud_sql_instance = 8;

  // A Compute Engine network URI.
  string network = 4;

  // Type of the network where the endpoint is located.
  // Applicable only to source endpoint, as destination network type can be
  // inferred from the source.
  NetworkType network_type = 5;

  // Project ID where the endpoint is located.
  // The Project ID can be derived from the URI if you provide a VM instance or
  // network URI.
  // The following are two cases where you must provide the project ID:
  // 1. Only the IP address is specified, and the IP address is within a Google
  // Cloud project.
  // 2. When you are using Shared VPC and the IP address that you provide is
  // from the service project. In this case, the network that the IP address
  // resides in is defined in the host project.
  string project_id = 6;
}

// Results of the configuration analysis from the last run of the test.
message ReachabilityDetails {
  // The overall result of the test's configuration analysis.
  enum Result {
    // No result was specified.
    RESULT_UNSPECIFIED = 0;

    // Possible scenarios are:
    //
    // * The configuration analysis determined that a packet originating from
    //   the source is expected to reach the destination.
    // * The analysis didn't complete because the user lacks permission for
    //   some of the resources in the trace. However, at the time the user's
    //   permission became insufficient, the trace had been successful so far.
    REACHABLE = 1;

    // A packet originating from the source is expected to be dropped before
    // reaching the destination.
    UNREACHABLE = 2;

    // The source and destination endpoints do not uniquely identify
    // the test location in the network, and the reachability result contains
    // multiple traces. For some traces, a packet could be delivered, and for
    // others, it would not be.
    AMBIGUOUS = 4;

    // The configuration analysis did not complete. Possible reasons are:
    //
    // * A permissions error occurred--for example, the user might not have
    //   read permission for all of the resources named in the test.
    // * An internal error occurred.
    // * The analyzer received an invalid or unsupported argument or was unable
    //   to identify a known endpoint.
    UNDETERMINED = 5;
  }

  // The overall result of the test's configuration analysis.
  Result result = 1;

  // The time of the configuration analysis.
  google.protobuf.Timestamp verify_time = 2;

  // The details of a failure or a cancellation of reachability analysis.
  google.rpc.Status error = 3;

  // Result may contain a list of traces if a test has multiple possible
  // paths in the network, such as when destination endpoint is a load balancer
  // with multiple backends.
  repeated Trace traces = 5;
}