tap: introduce HTTP tap filter

api/docs/BUILD

@@ -18,6 +18,7 @@ proto_library(
         "//envoy/admin/v2alpha:memory",
         "//envoy/admin/v2alpha:mutex_stats",
         "//envoy/admin/v2alpha:server_info",
+        "//envoy/admin/v2alpha:tap",
         "//envoy/api/v2:cds",
         "//envoy/api/v2:discovery",
         "//envoy/api/v2:eds",
@@ -46,6 +47,7 @@ proto_library(
         "//envoy/config/filter/http/rbac/v2:rbac",
         "//envoy/config/filter/http/router/v2:router",
         "//envoy/config/filter/http/squash/v2:squash",
+        "//envoy/config/filter/http/tap/v2alpha:tap",
         "//envoy/config/filter/http/transcoder/v2:transcoder",
         "//envoy/config/filter/network/client_ssl_auth/v2:client_ssl_auth",
         "//envoy/config/filter/network/ext_authz/v2:ext_authz",
@@ -71,13 +73,15 @@ proto_library(
         "//envoy/data/accesslog/v2:accesslog",
         "//envoy/data/core/v2alpha:health_check_event",
         "//envoy/data/tap/v2alpha:capture",
+        "//envoy/data/tap/v2alpha:http",
         "//envoy/service/accesslog/v2:als",
         "//envoy/service/auth/v2alpha:attribute_context",
         "//envoy/service/auth/v2alpha:external_auth",
         "//envoy/service/discovery/v2:ads",
         "//envoy/service/load_stats/v2:lrs",
         "//envoy/service/metrics/v2:metrics_service",
         "//envoy/service/ratelimit/v2:rls",
+        "//envoy/service/tap/v2alpha:common",
         "//envoy/type:percent",
         "//envoy/type:range",
         "//envoy/type/matcher:metadata",

api/envoy/admin/v2alpha/BUILD

@@ -55,3 +55,11 @@ api_proto_library_internal(
     srcs = ["server_info.proto"],
     visibility = ["//visibility:public"],
 )
+
+api_proto_library_internal(
+    name = "tap",
+    srcs = ["tap.proto"],
+    deps = [
+        "//envoy/service/tap/v2alpha:common",
+    ],
+)

api/envoy/admin/v2alpha/tap.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+import "envoy/service/tap/v2alpha/common.proto";
+import "validate/validate.proto";
+
+package envoy.admin.v2alpha;
+option java_package = "io.envoyproxy.envoy.admin.v2alpha";
+option java_multiple_files = true;
+
+// The /tap admin request body that is used to configure an active tap session.
+message TapRequest {
+  // The opaque configuration ID used to match the configuration to a loaded extension.
+  // A tap extension configures a similar opaque ID that is used to match.
+  string config_id = 1 [(validate.rules).string.min_bytes = 1];
+
+  // The tap configuration to load.
+  service.tap.v2alpha.TapConfig tap_config = 2 [(validate.rules).message.required = true];
+}

api/envoy/config/filter/http/tap/v2alpha/BUILD

@@ -0,0 +1,11 @@
+load("//bazel:api_build_system.bzl", "api_proto_library_internal")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_library_internal(
+    name = "tap",
+    srcs = ["tap.proto"],
+    deps = [
+        "//envoy/service/tap/v2alpha:common",
+    ],
+)

api/envoy/config/filter/http/tap/v2alpha/tap.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+
+import "envoy/service/tap/v2alpha/common.proto";
+
+import "validate/validate.proto";
+
+package envoy.config.filter.http.tap.v2alpha;
+option java_package = "io.envoyproxy.envoy.config.filter.http.tap.v2alpha";
+option java_multiple_files = true;
+
+// [#protodoc-title: Tap]
+// Tap :ref:`configuration overview <config_http_filters_tap>`.
+
+// Top level configuration for the tap filter.
+message Tap {
+  oneof config_type {
+    option (validate.required) = true;
+
+    // If specified, the tap filter will be configured via an admin handler.
+    AdminConfig admin_config = 1;
+  }
+}
+
+// Configuration for the admin handler. See :ref:`here <config_http_filters_tap_admin_handler>` for
+// more information.
+message AdminConfig {
+  // Opaque configuration ID. When requests are made to the admin handler, the passed opaque ID is
+  // matched to the configured filter opaque ID to determine which filter to configure.
+  string config_id = 1 [(validate.rules).string.min_bytes = 1];
+}

api/envoy/data/tap/v2alpha/BUILD

@@ -7,3 +7,8 @@ api_proto_library_internal(
     srcs = ["capture.proto"],
     deps = ["//envoy/api/v2/core:address"],
 )
+
+api_proto_library_internal(
+    name = "http",
+    srcs = ["http.proto"],
+)

api/envoy/data/tap/v2alpha/http.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package envoy.data.tap.v2alpha;
+option java_package = "io.envoyproxy.envoy.data.tap.v2alpha";
+option java_multiple_files = true;
+
+// [#protodoc-title: HTTP tap data]
+
+// A fully buffered HTTP trace message.
+message HttpBufferedTrace {
+  message Header {
+    // Header key.
+    string key = 1;
+
+    // Header value.
+    string value = 2;
+  }
+
+  // The match ID specified in the :ref:`match_id
+  // <envoy_api_field_service.tap.v2alpha.MatchConfig.match_id>` field.
+  string match_id = 1;
+
+  // Request headers.
+  repeated Header request_headers = 2;
+
+  // Response headers.
+  repeated Header response_headers = 3;
+}

api/envoy/service/tap/v2alpha/BUILD

@@ -0,0 +1,12 @@
+load("//bazel:api_build_system.bzl", "api_proto_library_internal")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_library_internal(
+    name = "common",
+    srcs = ["common.proto"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "//envoy/api/v2/route",
+    ],
+)

api/envoy/service/tap/v2alpha/common.proto

@@ -0,0 +1,88 @@
+syntax = "proto3";
+
+import "envoy/api/v2/route/route.proto";
+
+import "validate/validate.proto";
+
+package envoy.service.tap.v2alpha;
+option java_package = "io.envoyproxy.envoy.service.tap.v2alpha";
+option java_multiple_files = true;
+
+// [#protodoc-title: Common tap configuration]
+
+// Tap configuration.
+message TapConfig {
+  // The match conditions. One or more match configurations can be specified. If any of them
+  // match the data source being tapped, a tap will occur, with the result written to the
+  // configured output.
+  repeated MatchConfig match_configs = 1 [(validate.rules).repeated .min_items = 1];
+
+  // The tap output configuration. If a match configuration matches a data source being tapped,
+  // a tap will occur and the data will be written to the configured output.
+  OutputConfig output_config = 2 [(validate.rules).message.required = true];
+
+  // [#comment:TODO(mattklein123): Rate limiting]
+}
+
+// Tap match configuration. Within a single match configuration, all conditions are evaluated as
+// a logical AND. Logical OR matching can be implemented via multiple match configurations in the
+// top level tap configuration.
+message MatchConfig {
+  // Match ID used for correlating tap data with the match that produced it.
+  string match_id = 1 [(validate.rules).string.min_bytes = 1];
+
+  // HTTP match configuration. Only useful for HTTP aware tap extensions such as the
+  // :ref:`HTTP tap filter <config_http_filters_tap>`.
+  HttpMatchConfig http_match_config = 2;
+}
+
+// HTTP match configuration.
+message HttpMatchConfig {
+  // HTTP request match configuration.
+  HttpRequestMatchConfig request_match_config = 1;
+
+  // HTTP response match configuration.
+  HttpResponseMatchConfig response_match_config = 2;
+}
+
+// HTTP request match configuration.
+message HttpRequestMatchConfig {
+  // HTTP request headers to match.
+  repeated api.v2.route.HeaderMatcher headers = 1;
+}
+
+// HTTP response match configuration.
+message HttpResponseMatchConfig {
+  // HTTP response headers to match.
+  repeated api.v2.route.HeaderMatcher headers = 1;
+}
+
+// Tap output configuration.
+message OutputConfig {
+  // Output sinks for tap data. Currently a single sink is allowed in the list. Once multiple
+  // sink types are supported this constraint will be relaxed.
+  repeated OutputSink sinks = 1 [(validate.rules).repeated = {min_items: 1, max_items: 1}];
+
+  // [#comment:TODO(mattklein123): Output filtering. E.g., certain headers, truncated body, etc.]
+}
+
+// Tap output sink configuration.
+message OutputSink {
+  oneof output_sink_type {
+    option (validate.required) = true;
+
+    // Tap output will be streamed out the :http:post:`/tap` admin endpoint.
+    //
+    // .. attention::
+    //
+    //   It is only allowed to specify the streaming admin output sink if the tap is being
+    //   configured from the :http:post:`/tap` admin endpoint. Thus, if an extension has
+    //   been configured to receive tap configuration from some other source (e.g., static
+    //   file, XDS, etc.) configuring the streaming admin output type will fail.
+    StreamingAdminSink streaming_admin = 1;
+  }
+}
+
+// Streaming admin sink configuration.
+message StreamingAdminSink {
+}

docs/build.sh

@@ -54,6 +54,7 @@ PROTO_RST="
   /envoy/admin/v2alpha/clusters/envoy/admin/v2alpha/metrics.proto.rst
   /envoy/admin/v2alpha/mutex_stats/envoy/admin/v2alpha/mutex_stats.proto.rst
   /envoy/admin/v2alpha/server_info/envoy/admin/v2alpha/server_info.proto.rst
+  /envoy/admin/v2alpha/tap/envoy/admin/v2alpha/tap.proto.rst
   /envoy/api/v2/core/address/envoy/api/v2/core/address.proto.rst
   /envoy/api/v2/core/base/envoy/api/v2/core/base.proto.rst
   /envoy/api/v2/core/http_uri/envoy/api/v2/core/http_uri.proto.rst
@@ -95,6 +96,7 @@ PROTO_RST="
   /envoy/config/filter/http/rbac/v2/rbac/envoy/config/filter/http/rbac/v2/rbac.proto.rst
   /envoy/config/filter/http/router/v2/router/envoy/config/filter/http/router/v2/router.proto.rst
   /envoy/config/filter/http/squash/v2/squash/envoy/config/filter/http/squash/v2/squash.proto.rst
+  /envoy/config/filter/http/tap/v2alpha/tap/envoy/config/filter/http/tap/v2alpha/tap.proto.rst
   /envoy/config/filter/http/transcoder/v2/transcoder/envoy/config/filter/http/transcoder/v2/transcoder.proto.rst
   /envoy/config/filter/network/client_ssl_auth/v2/client_ssl_auth/envoy/config/filter/network/client_ssl_auth/v2/client_ssl_auth.proto.rst
   /envoy/config/filter/network/ext_authz/v2/ext_authz/envoy/config/filter/network/ext_authz/v2/ext_authz.proto.rst
@@ -117,10 +119,12 @@ PROTO_RST="
   /envoy/data/accesslog/v2/accesslog/envoy/data/accesslog/v2/accesslog.proto.rst
   /envoy/data/core/v2alpha/health_check_event/envoy/data/core/v2alpha/health_check_event.proto.rst
   /envoy/data/tap/v2alpha/capture/envoy/data/tap/v2alpha/capture.proto.rst
+  /envoy/data/tap/v2alpha/http/envoy/data/tap/v2alpha/http.proto.rst
   /envoy/service/accesslog/v2/als/envoy/service/accesslog/v2/als.proto.rst
   /envoy/service/auth/v2alpha/external_auth/envoy/service/auth/v2alpha/attribute_context.proto.rst
   /envoy/service/auth/v2alpha/external_auth/envoy/service/auth/v2alpha/external_auth.proto.rst
   /envoy/service/ratelimit/v2/rls/envoy/service/ratelimit/v2/rls.proto.rst
+  /envoy/service/tap/v2alpha/common/envoy/service/tap/v2alpha/common.proto.rst
   /envoy/type/http_status/envoy/type/http_status.proto.rst
   /envoy/type/percent/envoy/type/percent.proto.rst
   /envoy/type/range/envoy/type/range.proto.rst

docs/root/api-v2/admin/admin.rst

@@ -5,10 +5,4 @@ Admin
   :glob:
   :maxdepth: 2
 
-  ../admin/v2alpha/certs.proto
-  ../admin/v2alpha/config_dump.proto
-  ../admin/v2alpha/clusters.proto
-  ../admin/v2alpha/memory.proto
-  ../admin/v2alpha/metrics.proto
-  ../admin/v2alpha/mutex_stats.proto
-  ../admin/v2alpha/server_info.proto
+  ../admin/v2alpha/*

docs/root/api-v2/data/tap/tap.rst

@@ -5,4 +5,4 @@ Tap
   :glob:
   :maxdepth: 2
 
-  v2alpha/capture.proto
+  v2alpha/*

docs/root/api-v2/service/service.rst

@@ -7,3 +7,4 @@ Services
 
   accesslog/v2/*
   ratelimit/v2/*
+  tap/v2alpha/*

docs/root/configuration/http_filters/http_filters.rst

@@ -25,3 +25,4 @@ HTTP filters
   rbac_filter
   router_filter
   squash_filter
+  tap_filter