syntax = "proto3";

package envoy.api.v2.listener;

option java_outer_classname = "ListenerProto";
option java_multiple_files = true;
option java_package = "io.envoyproxy.envoy.api.v2.listener";
option csharp_namespace = "Envoy.Api.V2.ListenerNS";
option ruby_package = "Envoy.Api.V2.ListenerNS";

import "envoy/api/v2/auth/cert.proto";
import "envoy/api/v2/core/address.proto";
import "envoy/api/v2/core/base.proto";

import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

import "validate/validate.proto";

// [#protodoc-title: Listener components]
// Listener :ref:`configuration overview <config_listeners>`

message Filter {
  reserved 3;

  // The name of the filter to instantiate. The name must match a
  // :ref:`supported filter <config_network_filters>`.
  string name = 1 [(validate.rules).string = {min_bytes: 1}];

  // Filter specific configuration which depends on the filter being
  // instantiated. See the supported filters for further documentation.
  oneof config_type {
    google.protobuf.Struct config = 2;

    google.protobuf.Any typed_config = 4;
  }
}

// Specifies the match criteria for selecting a specific filter chain for a
// listener.
//
// In order for a filter chain to be selected, *ALL* of its criteria must be
// fulfilled by the incoming connection, properties of which are set by the
// networking stack and/or listener filters.
//
// The following order applies:
//
// 1. Destination port.
// 2. Destination IP address.
// 3. Server name (e.g. SNI for TLS protocol),
// 4. Transport protocol.
// 5. Application protocols (e.g. ALPN for TLS protocol).
// 6. Source type (e.g. any, local or external network).
// 7. Source IP address.
// 8. Source port.
//
// For criteria that allow ranges or wildcards, the most specific value in any
// of the configured filter chains that matches the incoming connection is going
// to be used (e.g. for SNI ``www.example.com`` the most specific match would be
// ``www.example.com``, then ``*.example.com``, then ``*.com``, then any filter
// chain without ``server_names`` requirements).
//
// [#comment: Implemented rules are kept in the preference order, with deprecated fields
// listed at the end, because that's how we want to list them in the docs.
//
// [#comment:TODO(PiotrSikora): Add support for configurable precedence of the rules]
message FilterChainMatch {
  enum ConnectionSourceType {
    // Any connection source matches.
    ANY = 0;

    // Match a connection originating from the same host.
    LOCAL = 1;

    // Match a connection originating from a different host.
    EXTERNAL = 2;
  }

  reserved 1;

  // Optional destination port to consider when use_original_dst is set on the
  // listener in determining a filter chain match.
  google.protobuf.UInt32Value destination_port = 8 [(validate.rules).uint32 = {lte: 65535 gte: 1}];

  // If non-empty, an IP address and prefix length to match addresses when the
  // listener is bound to 0.0.0.0/:: or when use_original_dst is specified.
  repeated core.CidrRange prefix_ranges = 3;

  // If non-empty, an IP address and suffix length to match addresses when the
  // listener is bound to 0.0.0.0/:: or when use_original_dst is specified.
  // [#not-implemented-hide:]
  string address_suffix = 4;

  // [#not-implemented-hide:]
  google.protobuf.UInt32Value suffix_len = 5;

  // Specifies the connection source IP match type. Can be any, local or external network.
  ConnectionSourceType source_type = 12 [(validate.rules).enum = {defined_only: true}];

  // The criteria is satisfied if the source IP address of the downstream
  // connection is contained in at least one of the specified subnets. If the
  // parameter is not specified or the list is empty, the source IP address is
  // ignored.
  repeated core.CidrRange source_prefix_ranges = 6;

  // The criteria is satisfied if the source port of the downstream connection
  // is contained in at least one of the specified ports. If the parameter is
  // not specified, the source port is ignored.
  repeated uint32 source_ports = 7
      [(validate.rules).repeated = {items {uint32 {lte: 65535 gte: 1}}}];

  // If non-empty, a list of server names (e.g. SNI for TLS protocol) to consider when determining
  // a filter chain match. Those values will be compared against the server names of a new
  // connection, when detected by one of the listener filters.
  //
  // The server name will be matched against all wildcard domains, i.e. ``www.example.com``
  // will be first matched against ``www.example.com``, then ``*.example.com``, then ``*.com``.
  //
  // Note that partial wildcards are not supported, and values like ``*w.example.com`` are invalid.
  //
  // .. attention::
  //
  //   See the :ref:`FAQ entry <faq_how_to_setup_sni>` on how to configure SNI for more
  //   information.
  repeated string server_names = 11;

  // If non-empty, a transport protocol to consider when determining a filter chain match.
  // This value will be compared against the transport protocol of a new connection, when
  // it's detected by one of the listener filters.
  //
  // Suggested values include:
  //
  // * ``raw_buffer`` - default, used when no transport protocol is detected,
  // * ``tls`` - set by :ref:`envoy.listener.tls_inspector <config_listener_filters_tls_inspector>`
  //   when TLS protocol is detected.
  string transport_protocol = 9;

  // If non-empty, a list of application protocols (e.g. ALPN for TLS protocol) to consider when
  // determining a filter chain match. Those values will be compared against the application
  // protocols of a new connection, when detected by one of the listener filters.
  //
  // Suggested values include:
  //
  // * ``http/1.1`` - set by :ref:`envoy.listener.tls_inspector
  //   <config_listener_filters_tls_inspector>`,
  // * ``h2`` - set by :ref:`envoy.listener.tls_inspector <config_listener_filters_tls_inspector>`
  //
  // .. attention::
  //
  //   Currently, only :ref:`TLS Inspector <config_listener_filters_tls_inspector>` provides
  //   application protocol detection based on the requested
  //   `ALPN <https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation>`_ values.
  //
  //   However, the use of ALPN is pretty much limited to the HTTP/2 traffic on the Internet,
  //   and matching on values other than ``h2`` is going to lead to a lot of false negatives,
  //   unless all connecting clients are known to use ALPN.
  repeated string application_protocols = 10;
}

// A filter chain wraps a set of match criteria, an option TLS context, a set of filters, and
// various other parameters.
message FilterChain {
  // The criteria to use when matching a connection to this filter chain.
  FilterChainMatch filter_chain_match = 1;

  // The TLS context for this filter chain.
  auth.DownstreamTlsContext tls_context = 2;

  // A list of individual network filters that make up the filter chain for
  // connections established with the listener. Order matters as the filters are
  // processed sequentially as connection events happen. Note: If the filter
  // list is empty, the connection will close by default.
  repeated Filter filters = 3;

  // Whether the listener should expect a PROXY protocol V1 header on new
  // connections. If this option is enabled, the listener will assume that that
  // remote address of the connection is the one specified in the header. Some
  // load balancers including the AWS ELB support this option. If the option is
  // absent or set to false, Envoy will use the physical peer address of the
  // connection as the remote address.
  google.protobuf.BoolValue use_proxy_proto = 4;

  // [#not-implemented-hide:] filter chain metadata.
  core.Metadata metadata = 5;

  // See :ref:`base.TransportSocket<envoy_api_msg_core.TransportSocket>` description.
  core.TransportSocket transport_socket = 6;

  // [#not-implemented-hide:] The unique name (or empty) by which this filter chain is known. If no
  // name is provided, Envoy will allocate an internal UUID for the filter chain. If the filter
  // chain is to be dynamically updated or removed via FCDS a unique name must be provided.
  string name = 7;
}

message ListenerFilter {
  // The name of the filter to instantiate. The name must match a
  // :ref:`supported filter <config_listener_filters>`.
  string name = 1 [(validate.rules).string = {min_bytes: 1}];

  // Filter specific configuration which depends on the filter being instantiated.
  // See the supported filters for further documentation.
  oneof config_type {
    google.protobuf.Struct config = 2;

    google.protobuf.Any typed_config = 3;
  }
}
