Envoy extensions for reverse connections

Commit Message: This commit collates the envoy extensions for reverse connections. A detailed description of the changes is provided in examples/reverse_connection/README.md
Additional Description:
Risk Level:
Testing:
Docs Changes:
Release Notes:
Platform Specific Features:
[Optional Runtime guard:]
[Optional Fixes #Issue]
[Optional Fixes commit #PR or SHA]
[Optional Deprecated:]
[Optional [API Considerations](https://github.com/envoyproxy/envoy/blob/main/api/review_checklist.md):]

Signed-off-by: Basundhara Chakrabarty <basundhara.c@nutanix.com>
Co-authored-by: Arun Vasudevan <arun.vasudevan@nutanix.com>
Co-authored-by: Tejas Sangol <tejas.sangol@nutanix.com>
Co-authored-by: Aditya Jaltade <aditya.jaltade@nutanix.com>

api/BUILD

@@ -28,6 +28,8 @@ proto_library(
         "//envoy/config/filter/http/gzip/v2:pkg",
         "//envoy/config/filter/http/rate_limit/v2:pkg",
         "//envoy/config/filter/http/rbac/v2:pkg",
+        "//envoy/config/filter/http/reverse_conn/v2:pkg",
+        "//envoy/config/filter/listener/reverse_connection/v2:pkg",
         "//envoy/config/filter/network/dubbo_proxy/v2alpha1:pkg",
         "//envoy/config/filter/network/http_connection_manager/v2:pkg",
         "//envoy/config/filter/network/rate_limit/v2:pkg",
@@ -136,6 +138,7 @@ proto_library(
         "//envoy/extensions/access_loggers/stream/v3:pkg",
         "//envoy/extensions/access_loggers/wasm/v3:pkg",
         "//envoy/extensions/bootstrap/internal_listener/v3:pkg",
+        "//envoy/extensions/bootstrap/reverse_connection/v3:pkg",
         "//envoy/extensions/clusters/aggregate/v3:pkg",
         "//envoy/extensions/clusters/dynamic_forward_proxy/v3:pkg",
         "//envoy/extensions/clusters/redis/v3:pkg",
@@ -208,6 +211,7 @@ proto_library(
         "//envoy/extensions/filters/http/rate_limit_quota/v3:pkg",
         "//envoy/extensions/filters/http/ratelimit/v3:pkg",
         "//envoy/extensions/filters/http/rbac/v3:pkg",
+        "//envoy/extensions/filters/http/reverse_conn/v3:pkg",
         "//envoy/extensions/filters/http/router/v3:pkg",
         "//envoy/extensions/filters/http/set_filter_state/v3:pkg",
         "//envoy/extensions/filters/http/set_metadata/v3:pkg",
@@ -221,6 +225,7 @@ proto_library(
         "//envoy/extensions/filters/listener/original_dst/v3:pkg",
         "//envoy/extensions/filters/listener/original_src/v3:pkg",
         "//envoy/extensions/filters/listener/proxy_protocol/v3:pkg",
+        "//envoy/extensions/filters/listener/reverse_connection/v3:pkg",
         "//envoy/extensions/filters/listener/tls_inspector/v3:pkg",
         "//envoy/extensions/filters/network/connection_limit/v3:pkg",
         "//envoy/extensions/filters/network/direct_response/v3:pkg",
@@ -325,6 +330,7 @@ proto_library(
         "//envoy/extensions/retry/host/omit_host_metadata/v3:pkg",
         "//envoy/extensions/retry/host/previous_hosts/v3:pkg",
         "//envoy/extensions/retry/priority/previous_priorities/v3:pkg",
+        "//envoy/extensions/reverse_connection/reverse_connection_listener_config/v3:pkg",
         "//envoy/extensions/router/cluster_specifiers/lua/v3:pkg",
         "//envoy/extensions/stat_sinks/graphite_statsd/v3:pkg",
         "//envoy/extensions/stat_sinks/open_telemetry/v3:pkg",

api/envoy/config/cluster/v3/cluster.proto

@@ -74,6 +74,10 @@ message Cluster {
     // type<arch_overview_service_discovery_types_original_destination>`
     // for an explanation.
     ORIGINAL_DST = 4;
+
+    // Using below cluster type, ensures envoy can dynamically pick a connected upstream endpoint
+    // by using downstream request headers.
+    REVERSE_CONNECTION = 5;
   }
 
   // Refer to :ref:`load balancer type <arch_overview_load_balancing_types>` architecture
@@ -558,6 +562,16 @@ message Cluster {
     type.metadata.v3.MetadataKey metadata_key = 4;
   }
 
+  // Specific configuration for a cluster configured as REVERSE_CONNECTION cluster.
+  message RevConClusterConfig {
+    // List of HTTP headers to look for in downstream request headers, to deduce the
+    // upstream endpoint.
+    repeated string http_header_names = 1;
+
+    // Time interval after which envoy attempts to clean the stale host entries.
+    google.protobuf.Duration cleanup_interval = 2;
+  }
+
   // Common configuration for all load balancer implementations.
   // [#next-free-field: 9]
   message CommonLbConfig {
@@ -1086,6 +1100,9 @@ message Cluster {
 
     // Optional configuration for the RoundRobin load balancing policy.
     RoundRobinLbConfig round_robin_lb_config = 56;
+
+    // Optional configuration for the ReverseConnectionLB load balancing policy.
+    RevConClusterConfig rev_con_cluster_config = 57;
   }
 
   // Common configuration for all load balancer implementations.

api/envoy/config/filter/http/reverse_conn/v2/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+)

api/envoy/config/filter/http/reverse_conn/v2/reverse_conn.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package envoy.config.filter.http.reverse_conn.v2;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.config.filter.http.reverse_conn.v2";
+option java_outer_classname = "ReverseConnProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/filter/http/reverse_conn/v2;reverse_connv2";
+option (udpa.annotations.file_migrate).move_to_package =
+    "envoy.extensions.filters.http.reverse_conn.v3";
+option (udpa.annotations.file_status).package_version_status = FROZEN;
+
+// [#protodoc-title: ReverseConn]
+// ReverseConn :ref:`configuration overview <config_http_filters_reverse_conn>`.
+// [#extension: envoy.filters.http.reverse_conn]
+
+message ReverseConn {
+  google.protobuf.UInt32Value ping_interval = 1;
+}

api/envoy/config/filter/listener/reverse_connection/v2/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+)

api/envoy/config/filter/listener/reverse_connection/v2/reverse_connection.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package envoy.config.filter.listener.reverse_connection.v2;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.config.filter.listener.reverse_connection.v2";
+option java_outer_classname = "ReverseConnectionProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/filter/listener/reverse_connection/v2;reverse_connectionv2";
+option (udpa.annotations.file_migrate).move_to_package =
+    "envoy.extensions.filters.listener.reverse_connection.v3";
+option (udpa.annotations.file_status).package_version_status = FROZEN;
+
+message ReverseConnection {
+  google.protobuf.UInt32Value ping_wait_timeout = 1;
+}

api/envoy/config/listener/v3/listener.proto

@@ -12,6 +12,7 @@ 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/any.proto";
 import "google/protobuf/wrappers.proto";
 
 import "xds/annotations/v3/status.proto";
@@ -53,7 +54,7 @@ message ListenerCollection {
   repeated xds.core.v3.CollectionEntry entries = 1;
 }
 
-// [#next-free-field: 36]
+// [#next-free-field: 37]
 message Listener {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Listener";
 
@@ -378,6 +379,11 @@ message Listener {
     // * :ref:`freebind <envoy_v3_api_field_config.listener.v3.Listener.freebind>`
     // * :ref:`transparent <envoy_v3_api_field_config.listener.v3.Listener.transparent>`
     InternalListenerConfig internal_listener = 27;
+
+    // Used to represent a reverse connection listener which, instead of binding to a port and listening,
+    // initiates reverse connections to a remote endpoint. The used sockets are cached on the remote
+    // endpoint and can be used to send request to local services.
+    google.protobuf.Any reverse_connection_listener_config = 36;
   }
 
   // Enable MPTCP (multi-path TCP) on this listener. Clients will be allowed to establish

api/envoy/extensions/bootstrap/reverse_connection/v3/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+)

api/envoy/extensions/bootstrap/reverse_connection/v3/reverse_connection.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package envoy.extensions.bootstrap.reverse_connection.v3;
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.bootstrap.reverse_connection.v3";
+option java_outer_classname = "ReverseConnectionProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/bootstrap/reverse_connection/v3;reverse_connectionv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Bootstrap settings for Reverse Connections]
+// [#extension: envoy.bootstrap.reverse_connection]
+
+// All the future reverse connection settings should be added here.
+message ReverseConnection {
+    // Stat prefix to be used for reverse connection stats.
+    string stat_prefix = 1;
+}

api/envoy/extensions/filters/http/reverse_conn/v3/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+)

api/envoy/extensions/filters/http/reverse_conn/v3/reverse_conn.proto

@@ -0,0 +1,55 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.reverse_conn.v3;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.reverse_conn.v3";
+option java_outer_classname = "ReverseConnProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/reverse_conn/v3;reverse_connv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: ReverseConn]
+// ReverseConn :ref:`configuration overview <config_http_filters_reverse_conn>`.
+// [#extension: envoy.filters.http.reverse_conn]
+
+message ReverseConn {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.filter.http.reverse_conn.v2.ReverseConn";
+
+  google.protobuf.UInt32Value ping_interval = 1;
+}
+
+// Config sent by the local cluster as part of the Initiation workflow.
+// This message combined with message 'ReverseConnHandshakeRet' which is
+// sent as a response can be used to transfer/negotiate parameter between the
+// two envoys.
+message ReverseConnHandshakeArg {
+  // Tenant UUID of the local cluster.
+  string tenant_uuid = 1;
+
+  // Cluster UUID of the local cluster.
+  string cluster_uuid = 2;
+
+  // Node UUID of the local cluster.
+  string node_uuid = 3;
+}
+
+// Config used by the remote cluser in response to the above 'ReverseConnHandshakeArg'.
+message ReverseConnHandshakeRet {
+  enum ConnectionStatus {
+    ACCEPTED = 0;
+    REJECTED = 1;
+  }
+
+  // Tracks the status of the reverse connection initiation workflow.
+  ConnectionStatus status = 1;
+
+  // This field can be used to transmit success/warning/error messages
+  // describing the status of the reverse connection, if needed.
+  string status_message = 2;
+}

api/envoy/extensions/filters/listener/reverse_connection/v3/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+)

api/envoy/extensions/filters/listener/reverse_connection/v3/reverse_connection.proto

@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.listener.reverse_connection.v3;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.listener.reverse_connection.v3";
+option java_outer_classname = "ReverseConnectionProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/listener/reverse_connection/v3;reverse_connectionv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Reverse Connection Filter]
+// PROXY protocol listener filter.
+// [#extension: envoy.filters.listener.reverse_connection]
+
+message ReverseConnection {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.filter.listener.reverse_connection.v2.ReverseConnection";
+
+  google.protobuf.UInt32Value ping_wait_timeout = 1;
+}

api/envoy/extensions/reverse_connection/reverse_connection_listener_config/v3/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+)

api/envoy/extensions/reverse_connection/reverse_connection_listener_config/v3/reverse_connection_listener_config.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+package envoy.extensions.reverse_connection.reverse_connection_listener_config.v3;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.reverse_connection.reverse_connection_listener_config.v3";
+option java_outer_classname = "ReverseConnectionListenerConfigProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/reverse_connection/reverse_connection_listener_config/v3;reverse_connection_listener_configv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Listener Config for Reverse Connections]
+// [#extension: envoy.reverse_connection.reverse_connection_listener_config]
+
+message ReverseConnectionCluster {
+  // Name of the cluster to initiate reverse connections to.
+  string cluster_name = 1 [(validate.rules).string = {min_len: 1}];
+
+  // Number of reverse connections need to cluster. Atleast one reverse connection
+  // has to be requested.
+  google.protobuf.UInt32Value reverse_connection_count = 2 [(validate.rules).uint32 = {gte: 1}];
+}
+
+// Configuration for envoy reverse connection listener. All the future reverse connection listener features
+// should be added here.
+message ReverseConnectionListenerConfig {
+  // The unique name for the initiator envoy while initiating reverse connections. This is
+  // a required field for reverse connections.
+  string src_node_id = 1 [(validate.rules).string = {min_len: 1}];
+
+  // The cluster ID (optional) of the initiator envoy.
+  string src_cluster_id = 2;
+
+  // Tenant ID (optional) of the initiator envoy.
+  string src_tenant_id = 3;
+
+  repeated ReverseConnectionCluster remote_cluster_to_conn_count = 4;
+}