syntax = "proto3";

package envoy.config.listener.v3;

import "envoy/config/accesslog/v3/accesslog.proto";
import "envoy/config/core/v3/address.proto";
import "envoy/config/core/v3/base.proto";
import "envoy/config/core/v3/socket_option.proto";
import "envoy/config/listener/v3/api_listener.proto";
import "envoy/config/listener/v3/listener_components.proto";
import "envoy/config/listener/v3/udp_listener_config.proto";

import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";

import "xds/core/v3/collection_entry.proto";

import "envoy/annotations/deprecation.proto";
import "validate/validate.proto";

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

// Listener list collections. Entries are *Listener* resources or references.
// [#not-implemented-hide:]
message ListenerCollection { repeated xds.core.v3.CollectionEntry entries = 1; }

// [#next-free-field: 32]
message Listener {
  enum DrainType {
    // Drain in response to calling /healthcheck/fail admin endpoint (along with
    // the health check filter), listener removal/modification, and hot restart.
    DEFAULT = 0;

    // Drain in response to listener removal/modification and hot restart. This
    // setting does not include /healthcheck/fail. This setting may be desirable
    // if Envoy is hosting both ingress and egress listeners.
    MODIFY_ONLY = 1;
  }

  // [#not-implemented-hide:]
  message DeprecatedV1 {
    // Whether the listener should bind to the port. A listener that doesn't
    // bind can only receive connections redirected from other listeners that
    // set use_original_dst parameter to true. Default is true.
    //
    // This is deprecated. Use :ref:`Listener.bind_to_port
    // <envoy_v3_api_field_config.listener.v3.Listener.bind_to_port>`
    google.protobuf.BoolValue bind_to_port = 1;
  }

  // Configuration for listener connection balancing.
  message ConnectionBalanceConfig {
    // A connection balancer implementation that does exact balancing. This
    // means that a lock is held during balancing so that connection counts are
    // nearly exactly balanced between worker threads. This is "nearly" exact in
    // the sense that a connection might close in parallel thus making the
    // counts incorrect, but this should be rectified on the next accept. This
    // balancer sacrifices accept throughput for accuracy and should be used
    // when there are a small number of connections that rarely cycle (e.g.,
    // service mesh gRPC egress).
    message ExactBalance {}

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

      // If specified, the listener will use the exact connection balancer.
      ExactBalance exact_balance = 1;
    }
  }

  // Configuration for envoy internal listener. All the future internal listener
  // features should be added here.
  // [#not-implemented-hide:]
  message InternalListenerConfig {}

  reserved 14, 23;

  // The unique name by which this listener is known. If no name is provided,
  // Envoy will allocate an internal UUID for the listener. If the listener is
  // to be dynamically updated or removed via :ref:`LDS <config_listeners_lds>`
  // a unique name must be provided.
  string name = 1;

  // The address that the listener should listen on. In general, the address
  // must be unique, though that is governed by the bind rules of the OS. E.g.,
  // multiple listeners can listen on port 0 on Linux as the actual port will be
  // allocated by the OS.
  core.v3.Address address = 2 [ (validate.rules).message = {required : true} ];

  // Optional prefix to use on listener stats. If empty, the stats will be
  // rooted at `listener.<address as string>.`. If non-empty, stats will be
  // rooted at `listener.<stat_prefix>.`.
  string stat_prefix = 28;

  // A list of filter chains to consider for this listener. The
  // :ref:`FilterChain <envoy_v3_api_msg_config.listener.v3.FilterChain>` with
  // the most specific :ref:`FilterChainMatch
  // <envoy_v3_api_msg_config.listener.v3.FilterChainMatch>` criteria is used on
  // a connection.
  //
  // Example using SNI for filter chain selection can be found in the
  // :ref:`FAQ entry <faq_how_to_setup_sni>`.
  repeated FilterChain filter_chains = 3;

  // If a connection is redirected using *iptables*, the port on which the proxy
  // receives it might be different from the original destination address. When
  // this flag is set to true, the listener hands off redirected connections to
  // the listener associated with the original destination address. If there is
  // no listener associated with the original destination address, the
  // connection is handled by the listener that receives it. Defaults to false.
  google.protobuf.BoolValue use_original_dst = 4;

  // The default filter chain if none of the filter chain matches. If no default
  // filter chain is supplied, the connection will be closed. The filter chain
  // match is ignored in this field.
  FilterChain default_filter_chain = 25;

  // Soft limit on size of the listener’s new connection read and write buffers.
  // If unspecified, an implementation defined default is applied (1MiB).
  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;

  // Listener metadata.
  core.v3.Metadata metadata = 6;

  // [#not-implemented-hide:]
  DeprecatedV1 deprecated_v1 = 7 [
    deprecated = true,
    (envoy.annotations.deprecated_at_minor_version) = "3.0"
  ];

  // The type of draining to perform at a listener-wide level.
  DrainType drain_type = 8;

  // Listener filters have the opportunity to manipulate and augment the
  // connection metadata that is used in connection filter chain matching, for
  // example. These filters are run before any in :ref:`filter_chains
  // <envoy_v3_api_field_config.listener.v3.Listener.filter_chains>`. Order
  // matters as the filters are processed sequentially right after a socket has
  // been accepted by the listener, and before a connection is created. UDP
  // Listener filters can be specified when the protocol in the listener socket
  // address in :ref:`protocol
  // <envoy_v3_api_field_config.core.v3.SocketAddress.protocol>` is :ref:`UDP
  // <envoy_v3_api_enum_value_config.core.v3.SocketAddress.Protocol.UDP>`.
  repeated ListenerFilter listener_filters = 9;

  // The timeout to wait for all listener filters to complete operation. If the
  // timeout is reached, the accepted socket is closed without a connection
  // being created unless `continue_on_listener_filters_timeout` is set to true.
  // Specify 0 to disable the timeout. If not specified, a default timeout of
  // 15s is used.
  google.protobuf.Duration listener_filters_timeout = 15;

  // Whether a connection should be created when listener filters timeout.
  // Default is false.
  //
  // .. attention::
  //
  //   Some listener filters, such as :ref:`Proxy Protocol filter
  //   <config_listener_filters_proxy_protocol>`, should not be used with this
  //   option. It will cause unexpected behavior when a connection is created.
  bool continue_on_listener_filters_timeout = 17;

  // Whether the listener should be set as a transparent socket.
  // When this flag is set to true, connections can be redirected to the
  // listener using an *iptables* *TPROXY* target, in which case the original
  // source and destination addresses and ports are preserved on accepted
  // connections. This flag should be used in combination with :ref:`an
  // original_dst <config_listener_filters_original_dst>` :ref:`listener filter
  // <envoy_v3_api_field_config.listener.v3.Listener.listener_filters>` to mark
  // the connections' local addresses as "restored." This can be used to hand
  // off each redirected connection to another listener associated with the
  // connection's destination address. Direct connections to the socket without
  // using *TPROXY* cannot be distinguished from connections redirected using
  // *TPROXY* and are therefore treated as if they were redirected. When this
  // flag is set to false, the listener's socket is explicitly reset as
  // non-transparent. Setting this flag requires Envoy to run with the
  // *CAP_NET_ADMIN* capability. When this flag is not set (default), the socket
  // is not modified, i.e. the transparent option is neither set nor reset.
  google.protobuf.BoolValue transparent = 10;

  // Whether the listener should set the *IP_FREEBIND* socket option. When this
  // flag is set to true, listeners can be bound to an IP address that is not
  // configured on the system running Envoy. When this flag is set to false, the
  // option *IP_FREEBIND* is disabled on the socket. When this flag is not set
  // (default), the socket is not modified, i.e. the option is neither enabled
  // nor disabled.
  google.protobuf.BoolValue freebind = 11;

  // Additional socket options that may not be present in Envoy source code or
  // precompiled binaries.
  repeated core.v3.SocketOption socket_options = 13;

  // Whether the listener should accept TCP Fast Open (TFO) connections.
  // When this flag is set to a value greater than 0, the option TCP_FASTOPEN is
  // enabled on the socket, with a queue length of the specified size (see
  // `details in RFC7413 <https://tools.ietf.org/html/rfc7413#section-5.1>`_).
  // When this flag is set to 0, the option TCP_FASTOPEN is disabled on the
  // socket. When this flag is not set (default), the socket is not modified,
  // i.e. the option is neither enabled nor disabled.
  //
  // On Linux, the net.ipv4.tcp_fastopen kernel parameter must include flag 0x2
  // to enable TCP_FASTOPEN. See `ip-sysctl.txt
  // <https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt>`_.
  //
  // On macOS, only values of 0, 1, and unset are valid; other values may result
  // in an error. To set the queue length on macOS, set the
  // net.inet.tcp.fastopen_backlog kernel parameter.
  google.protobuf.UInt32Value tcp_fast_open_queue_length = 12;

  // Specifies the intended direction of the traffic relative to the local
  // Envoy. This property is required on Windows for listeners using the
  // original destination filter, see :ref:`Original Destination
  // <config_listener_filters_original_dst>`.
  core.v3.TrafficDirection traffic_direction = 16;

  // If the protocol in the listener socket address in :ref:`protocol
  // <envoy_v3_api_field_config.core.v3.SocketAddress.protocol>` is :ref:`UDP
  // <envoy_v3_api_enum_value_config.core.v3.SocketAddress.Protocol.UDP>`, this
  // field specifies UDP listener specific configuration.
  UdpListenerConfig udp_listener_config = 18;

  // Used to represent an API listener, which is used in non-proxy clients. The
  // type of API exposed to the non-proxy application depends on the type of API
  // listener. When this field is set, no other field except for
  // :ref:`name<envoy_v3_api_field_config.listener.v3.Listener.name>` should be
  // set.
  //
  // .. note::
  //
  //  Currently only one ApiListener can be installed; and it can only be done
  //  via bootstrap config, not LDS.
  //
  // [#next-major-version: In the v3 API, instead of this messy approach where
  // the socket listener fields are directly in the top-level Listener message
  // and the API listener types are in the ApiListener message, the socket
  // listener messages should be in their own message, and the top-level
  // Listener should essentially be a oneof that selects between the socket
  // listener and the various types of API listener. That way, a given Listener
  // message can structurally only contain the fields of the relevant type.]
  ApiListener api_listener = 19;

  // The listener's connection balancer configuration, currently only applicable
  // to TCP listeners. If no configuration is specified, Envoy will not attempt
  // to balance active connections between worker threads.
  //
  // In the scenario that the listener X redirects all the connections to the
  // listeners Y1 and Y2 by setting :ref:`use_original_dst
  // <envoy_v3_api_field_config.listener.v3.Listener.use_original_dst>` in X and
  // :ref:`bind_to_port
  // <envoy_v3_api_field_config.listener.v3.Listener.bind_to_port>` to false in
  // Y1 and Y2, it is recommended to disable the balance config in listener X to
  // avoid the cost of balancing, and enable the balance config in Y1 and Y2 to
  // balance the connections among the workers.
  ConnectionBalanceConfig connection_balance_config = 20;

  // Deprecated. Use `enable_reuse_port` instead.
  bool reuse_port = 21 [
    deprecated = true,
    (envoy.annotations.deprecated_at_minor_version) = "3.0"
  ];

  // When this flag is set to true, listeners set the *SO_REUSEPORT* socket
  // option and create one socket for each worker thread. This makes inbound
  // connections distribute among worker threads roughly evenly in cases where
  // there are a high number of connections. When this flag is set to false, all
  // worker threads share one socket. This field defaults to true.
  //
  // .. attention::
  //
  //   Although this field defaults to true, it has different behavior on
  //   different platforms. See the following text for more information.
  //
  // * On Linux, reuse_port is respected for both TCP and UDP listeners. It also
  // works correctly
  //   with hot restart.
  // * On macOS, reuse_port for TCP does not do what it does on Linux. Instead
  // of load balancing,
  //   the last socket wins and receives all connections/packets. For TCP,
  //   reuse_port is force disabled and the user is warned. For UDP, it is
  //   enabled, but only one worker will receive packets. For QUIC/H3, SW
  //   routing will send packets to other workers. For "raw" UDP, only a single
  //   worker will currently receive packets.
  // * On Windows, reuse_port for TCP has undefined behavior. It is force
  // disabled and the user
  //   is warned similar to macOS. It is left enabled for UDP with undefined
  //   behavior currently.
  google.protobuf.BoolValue enable_reuse_port = 29;

  // Configuration for :ref:`access logs <arch_overview_access_logs>`
  // emitted by this listener.
  repeated accesslog.v3.AccessLog access_log = 22;

  // The maximum length a tcp listener's pending connections queue can grow to.
  // If no value is provided net.core.somaxconn will be used on Linux and 128
  // otherwise.
  google.protobuf.UInt32Value tcp_backlog_size = 24;

  // Whether the listener should bind to the port. A listener that doesn't
  // bind can only receive connections redirected from other listeners that set
  // :ref:`use_original_dst
  // <envoy_v3_api_field_config.listener.v3.Listener.use_original_dst>` to true.
  // Default is true.
  google.protobuf.BoolValue bind_to_port = 26;

  // The exclusive listener type and the corresponding config.
  // TODO(lambdai): https://github.com/envoyproxy/envoy/issues/15372
  // Will create and add TcpListenerConfig. Will add UdpListenerConfig and
  // ApiListener.
  // [#not-implemented-hide:]
  oneof listener_specifier {
    // Used to represent an internal listener which does not listen on OSI L4
    // address but can be used by the :ref:`envoy cluster
    // <envoy_v3_api_msg_config.cluster.v3.Cluster>` to create a user space
    // connection to. The internal listener acts as a tcp listener. It supports
    // listener filters and network filter chains. The internal listener require
    // :ref:`address <envoy_v3_api_field_config.listener.v3.Listener.address>`
    // has field `envoy_internal_address`.
    //
    // There are some limitations are derived from the implementation. The known
    // limitations include
    //
    // * :ref:`ConnectionBalanceConfig
    // <envoy_v3_api_msg_config.listener.v3.Listener.ConnectionBalanceConfig>`
    // is not
    //   allowed because both cluster connection and listener connection must be
    //   owned by the same dispatcher.
    // * :ref:`tcp_backlog_size
    // <envoy_v3_api_field_config.listener.v3.Listener.tcp_backlog_size>`
    // * :ref:`freebind
    // <envoy_v3_api_field_config.listener.v3.Listener.freebind>`
    // * :ref:`transparent
    // <envoy_v3_api_field_config.listener.v3.Listener.transparent>`
    // [#not-implemented-hide:]
    InternalListenerConfig internal_listener = 27;
  }

  // Enable MPTCP (multi-path TCP) on this listener. Clients will be allowed to
  // establish MPTCP connections. Non-MPTCP clients will fall back to regular
  // TCP.
  bool enable_mptcp = 30;

  // Whether the listener should limit connections based upon the value of
  // :ref:`global_downstream_max_connections
  // <config_overload_manager_limiting_connections>`.
  bool ignore_global_conn_limit = 31;
}