transport capture: rename to tap (#5666)

This is a rename PR only. It renames the capture transport socket
and associated tools to the tap transport socket. It also updates
some documentation. In a subsequent PR I'm going to refactor the
tap transport socket to use the new common tap framework so that
the tap transport socket can be configured via admin, the HTTP
tap filter can write to a file, the tap transport socket can have
matching, etc.

Signed-off-by: Matt Klein <mklein@lyft.com>

Mirrored from https://github.com/envoyproxy/envoy @ 7a5849f2a8bcc55fa16da3eaee94d9c99a11147c

docs/BUILD

@@ -70,11 +70,11 @@ proto_library(
         "//envoy/config/resource_monitor/fixed_heap/v2alpha:fixed_heap",
         "//envoy/config/resource_monitor/injected_resource/v2alpha:injected_resource",
         "//envoy/config/trace/v2:trace",
-        "//envoy/config/transport_socket/capture/v2alpha:capture",
+        "//envoy/config/transport_socket/tap/v2alpha:tap",
         "//envoy/data/accesslog/v2:accesslog",
         "//envoy/data/core/v2alpha:health_check_event",
-        "//envoy/data/tap/v2alpha:capture",
         "//envoy/data/tap/v2alpha:http",
+        "//envoy/data/tap/v2alpha:transport",
         "//envoy/data/tap/v2alpha:wrapper",
         "//envoy/service/accesslog/v2:als",
         "//envoy/service/auth/v2:attribute_context",

envoy/config/transport_socket/tap/v2alpha/BUILD

@@ -3,8 +3,8 @@ load("//bazel:api_build_system.bzl", "api_proto_library_internal")
 licenses(["notice"])  # Apache 2
 
 api_proto_library_internal(
-    name = "capture",
-    srcs = ["capture.proto"],
+    name = "tap",
+    srcs = ["tap.proto"],
     deps = [
         "//envoy/api/v2/core:base",
     ],

envoy/config/transport_socket/tap/v2alpha/tap.proto

@@ -1,10 +1,10 @@
 syntax = "proto3";
 
-package envoy.config.transport_socket.capture.v2alpha;
-option java_package = "io.envoyproxy.envoy.config.transport_socket.capture.v2alpha";
+package envoy.config.transport_socket.tap.v2alpha;
+option java_package = "io.envoyproxy.envoy.config.transport_socket.tap.v2alpha";
 option go_package = "v2";
 
-// [#protodoc-title: Capture]
+// [#protodoc-title: Tap]
 
 import "envoy/api/v2/core/base.proto";
 
@@ -33,9 +33,9 @@ message FileSink {
   Format format = 2;
 }
 
-// Configuration for capture transport socket. This wraps another transport socket, providing the
+// Configuration for tap transport socket. This wraps another transport socket, providing the
 // ability to interpose and record in plain text any traffic that is surfaced to Envoy.
-message Capture {
+message Tap {
   oneof sink_selector {
     // Trace is to be written to a file sink.
     FileSink file_sink = 1;

envoy/data/tap/v2alpha/BUILD

@@ -3,8 +3,8 @@ load("//bazel:api_build_system.bzl", "api_proto_library_internal")
 licenses(["notice"])  # Apache 2
 
 api_proto_library_internal(
-    name = "capture",
-    srcs = ["capture.proto"],
+    name = "transport",
+    srcs = ["transport.proto"],
     deps = ["//envoy/api/v2/core:address"],
 )
 

envoy/data/tap/v2alpha/transport.proto

@@ -1,7 +1,7 @@
 syntax = "proto3";
 
-// [#protodoc-title: Common tap]
-// Trace capture format for the capture transport socket extension. This dumps plain text read/write
+// [#protodoc-title: Transport tap data]
+// Trace format for the tap transport socket extension. This dumps plain text read/write
 // sequences on a socket.
 
 package envoy.data.tap.v2alpha;
@@ -23,7 +23,7 @@ message Connection {
   envoy.api.v2.core.Address remote_address = 3;
 }
 
-// Event in a capture trace.
+// Event in a trace.
 message Event {
   // Timestamp for event.
   google.protobuf.Timestamp timestamp = 1;
@@ -47,7 +47,7 @@ message Event {
   }
 }
 
-// Sequence of read/write events that constitute a captured trace on a socket.
+// Sequence of read/write events that constitute a trace on a socket.
 // Multiple Trace messages might be emitted for a given connection ID, with the
 // sink (e.g. file set, network) responsible for later reassembly.
 message Trace {

tools/BUILD

@@ -1,27 +1,27 @@
 licenses(["notice"])  # Apache 2
 
 py_binary(
-    name = "capture2pcap",
-    srcs = ["capture2pcap.py"],
+    name = "tap2pcap",
+    srcs = ["tap2pcap.py"],
     licenses = ["notice"],  # Apache 2
     visibility = ["//visibility:public"],
     deps = [
-        "//envoy/data/tap/v2alpha:capture_py",
+        "//envoy/data/tap/v2alpha:transport_py",
     ],
 )
 
 py_test(
-    name = "capture2pcap_test",
-    srcs = ["capture2pcap_test.py"],
+    name = "tap2pcap_test",
+    srcs = ["tap2pcap_test.py"],
     data = [
-        "data/capture2pcap_h2_ipv4.pb_text",
-        "data/capture2pcap_h2_ipv4.txt",
+        "data/tap2pcap_h2_ipv4.pb_text",
+        "data/tap2pcap_h2_ipv4.txt",
     ],
     # Don't run this by default, since we don't want to force local dependency on Wireshark/tshark,
     # will explicitly invoke in CI.
     tags = ["manual"],
     visibility = ["//visibility:public"],
-    deps = [":capture2pcap"],
+    deps = [":tap2pcap"],
 )
 
 py_binary(

tools/tap2pcap.py

@@ -1,14 +1,14 @@
-"""Tool to convert Envoy capture trace format to PCAP.
+"""Tool to convert Envoy tap trace format to PCAP.
 
 Uses od and text2pcap (part of Wireshark) utilities to translate the Envoy
-capture trace proto format to a PCAP file suitable for consuming in Wireshark
+tap trace proto format to a PCAP file suitable for consuming in Wireshark
 and other tools in the PCAP ecosystem. The TCP stream in the output PCAP is
 synthesized based on the known IP/port/timestamps that Envoy produces in its
-capture files; it is not a literal wire capture.
+tap files; it is not a literal wire tap.
 
 Usage:
 
-bazel run @envoy_api//tools:capture2pcap <capture .pb/.pb_text> <pcap path>
+bazel run @envoy_api//tools:tap2pcap <tap .pb/.pb_text> <pcap path>
 
 Known issues:
 - IPv6 PCAP generation has malformed TCP packets. This appears to be a text2pcap
@@ -28,7 +28,7 @@ import time
 
 from google.protobuf import text_format
 
-from envoy.data.tap.v2alpha import capture_pb2
+from envoy.data.tap.v2alpha import transport_pb2
 
 
 def DumpEvent(direction, timestamp, data):
@@ -43,13 +43,13 @@ def DumpEvent(direction, timestamp, data):
   return dump.getvalue()
 
 
-def Capture2Pcap(capture_path, pcap_path):
-  trace = capture_pb2.Trace()
-  if capture_path.endswith('.pb_text'):
-    with open(capture_path, 'r') as f:
+def Tap2Pcap(tap_path, pcap_path):
+  trace = transport_pb2.Trace()
+  if tap_path.endswith('.pb_text'):
+    with open(tap_path, 'r') as f:
       text_format.Merge(f.read(), trace)
   else:
-    with open(capture_path, 'r') as f:
+    with open(tap_path, 'r') as f:
       trace.ParseFromString(f.read())
 
   local_address = trace.connection.local_address.socket_address.address
@@ -82,6 +82,6 @@ def Capture2Pcap(capture_path, pcap_path):
 
 if __name__ == '__main__':
   if len(sys.argv) != 3:
-    print('Usage: %s <capture .pb/.pb_text> <pcap path>' % sys.argv[0])
+    print('Usage: %s <tap .pb/.pb_text> <pcap path>' % sys.argv[0])
     sys.exit(1)
-  Capture2Pcap(sys.argv[1], sys.argv[2])
+  Tap2Pcap(sys.argv[1], sys.argv[2])

tools/tap2pcap_test.py

@@ -1,22 +1,22 @@
-"""Tests for capture2pcap."""
+"""Tests for tap2pcap."""
 from __future__ import print_function
 
 import os
 import subprocess as sp
 import sys
 
-import capture2pcap
+import tap2pcap
 
-# Validate that the captured trace when run through capture2cap | tshark matches
-# a golden output file for the tshark dump. Since we run capture2pcap in a
+# Validate that the tapped trace when run through tap2cap | tshark matches
+# a golden output file for the tshark dump. Since we run tap2pcap in a
 # subshell with a limited environment, the inferred time zone should be UTC.
 if __name__ == '__main__':
   srcdir = os.path.join(os.getenv('TEST_SRCDIR'), 'envoy_api')
-  capture_path = os.path.join(srcdir, 'tools/data/capture2pcap_h2_ipv4.pb_text')
-  expected_path = os.path.join(srcdir, 'tools/data/capture2pcap_h2_ipv4.txt')
+  tap_path = os.path.join(srcdir, 'tools/data/tap2pcap_h2_ipv4.pb_text')
+  expected_path = os.path.join(srcdir, 'tools/data/tap2pcap_h2_ipv4.txt')
   pcap_path = os.path.join(os.getenv('TEST_TMPDIR'), 'generated.pcap')
 
-  capture2pcap.Capture2Pcap(capture_path, pcap_path)
+  tap2pcap.Tap2Pcap(tap_path, pcap_path)
   actual_output = sp.check_output(['tshark', '-r', pcap_path, '-d', 'tcp.port==10000,http2', '-P'])
   with open(expected_path, 'r') as f:
     expected_output = f.read()