syntax = "proto3";

package envoy.extensions.matching.common_inputs.transport_socket.v3;

import "udpa/annotations/status.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.extensions.matching.common_inputs.transport_socket.v3";
option java_outer_classname = "TransportSocketInputsProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/matching/common_inputs/transport_socket/v3;transport_socketv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Transport Socket Matching Inputs]

// Specifies that matching should be performed by the endpoint metadata.
// This input extracts metadata from the selected endpoint for transport socket selection.
// The metadata is extracted using a filter and path specification similar to
// :ref:`DynamicMetadataInput <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.DynamicMetadataInput>`.
//
// Example: Extract a metadata value for transport socket matching.
//
// .. code-block:: yaml
//
//   typed_config:
//     "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.transport_socket.v3.EndpointMetadataInput
//     filter: "envoy.transport_socket_match"
//     path:
//       - key: "socket_type"
//
// This configuration extracts the value at path ``["envoy.transport_socket_match"]["socket_type"]``
// from the endpoint metadata for use in transport socket selection.
//
// [#extension: envoy.matching.inputs.endpoint_metadata]
message EndpointMetadataInput {
  // Specifies the segment in a path to retrieve value from Metadata.
  // Note: Currently it's not supported to retrieve a value from a list in Metadata. This means that
  // if the segment key refers to a list, it has to be the last segment in a path.
  message PathSegment {
    oneof segment {
      option (validate.required) = true;

      // If specified, use the key to retrieve the value in a Struct.
      string key = 1 [(validate.rules).string = {min_len: 1}];
    }
  }

  // The filter name to retrieve the Struct from the endpoint metadata.
  // If not specified, defaults to ``envoy.lb`` which is commonly used for load balancing metadata.
  string filter = 1;

  // The path to retrieve the Value from the Struct.
  repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}];
}

// Specifies that matching should be performed by the locality metadata.
// This input extracts metadata from the endpoint's locality for transport socket selection.
// The metadata is extracted using a filter and path specification similar to
// :ref:`DynamicMetadataInput <envoy_v3_api_msg_extensions.matching.common_inputs.network.v3.DynamicMetadataInput>`.
//
// Example: Extract a metadata value from locality for transport socket matching.
//
// .. code-block:: yaml
//
//   typed_config:
//     "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.transport_socket.v3.LocalityMetadataInput
//     filter: "envoy.transport_socket_match"
//     path:
//       - key: "region"
//
// This configuration extracts the value at path ``["envoy.transport_socket_match"]["region"]``
// from the locality metadata for use in transport socket selection.
//
// [#extension: envoy.matching.inputs.locality_metadata]
message LocalityMetadataInput {
  // Specifies the segment in a path to retrieve value from Metadata.
  // Note: Currently it's not supported to retrieve a value from a list in Metadata. This means that
  // if the segment key refers to a list, it has to be the last segment in a path.
  message PathSegment {
    oneof segment {
      option (validate.required) = true;

      // If specified, use the key to retrieve the value in a Struct.
      string key = 1 [(validate.rules).string = {min_len: 1}];
    }
  }

  // The filter name to retrieve the Struct from the locality metadata.
  // If not specified, defaults to ``envoy.lb`` which is commonly used for load balancing metadata.
  string filter = 1;

  // The path to retrieve the Value from the Struct.
  repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}];
}

// Specifies that matching should be performed by filter state.
// This input extracts a value from filter state that was explicitly shared from the
// downstream connection to the upstream connection via ``TransportSocketOptions``.
// This enables flexible downstream-connection-based transport socket selection,
// such as matching on network namespace or any custom filter state data.
//
// Example: Match on network namespace stored in filter state.
//
// .. code-block:: yaml
//
//   typed_config:
//     "@type": type.googleapis.com/envoy.extensions.matching.common_inputs.transport_socket.v3.FilterStateInput
//     key: "envoy.network.namespace"
//
// [#extension: envoy.matching.inputs.transport_socket_filter_state]
message FilterStateInput {
  // The key of the filter state object to retrieve.
  // The object must implement serializeAsString() to be used for matching.
  string key = 1 [(validate.rules).string = {min_len: 1}];
}

// Configuration for the transport socket name action.
// This action sets the name of the transport socket to use when the matcher matches.
// [#extension: envoy.matching.action.transport_socket.name]
message TransportSocketNameAction {
  // The name of the transport socket to use.
  // This name must reference a named transport socket in the cluster's transport_socket_matches.
  string name = 1 [(validate.rules).string = {min_len: 1}];
}
