request_id: allow disabling trace reason packing (#15248)

1) Promote the default UUID request_id implementation to
   an actual extension that is required in the build and wire
   up all documentation.
2) Add a configuration option to the extension that allows trace
   reason packing to be disabled (the default continues to be for it
   to be enabled to match existing behavior).
3) Update all documentation for the new behavior.
4) Substantial cleanup of these code paths for clarity and robustness.

Fixes https://github.com/envoyproxy/envoy/issues/11532

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

Mirrored from https://github.com/envoyproxy/envoy @ 07c4c17be61c77d87d2c108b0775f2e606a7ae12

BUILD

@@ -245,6 +245,7 @@ proto_library(
         "//envoy/extensions/internal_redirect/safe_cross_scheme/v3:pkg",
         "//envoy/extensions/network/socket_interface/v3:pkg",
         "//envoy/extensions/rate_limit_descriptors/expr/v3:pkg",
+        "//envoy/extensions/request_id/uuid/v3:pkg",
         "//envoy/extensions/resource_monitors/fixed_heap/v3:pkg",
         "//envoy/extensions/resource_monitors/injected_resource/v3:pkg",
         "//envoy/extensions/retry/host/omit_canary_hosts/v3:pkg",

envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto

@@ -528,15 +528,21 @@ message HttpConnectionManager {
   bool merge_slashes = 33;
 
   // The configuration of the request ID extension. This includes operations such as
-  // generation, validation, and associated tracing operations.
+  // generation, validation, and associated tracing operations. If empty, the
+  // :ref:`UuidRequestIdConfig <envoy_v3_api_msg_extensions.request_id.uuid.v3.UuidRequestIdConfig>`
+  // default extension is used with default parameters. See the documentation for that extension
+  // for details on what it does. Customizing the configuration for the default extension can be
+  // achieved by configuring it explicitly here. For example, to disable trace reason packing,
+  // the following configuration can be used:
   //
-  // If not set, Envoy uses the default UUID-based behavior:
-  //
-  // 1. Request ID is propagated using *x-request-id* header.
+  // .. validated-code-block:: yaml
+  //   :type-name: envoy.extensions.filters.network.http_connection_manager.v3.RequestIDExtension
   //
-  // 2. Request ID is a universally unique identifier (UUID).
+  //   typed_config:
+  //     "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
+  //     pack_trace_reason: false
   //
-  // 3. Tracing decision (sampled, forced, etc) is set in 14th byte of the UUID.
+  // [#extension-category: envoy.request_id]
   RequestIDExtension request_id_extension = 36;
 
   // The configuration to customize local reply returned by Envoy. It can customize status code,

envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto

@@ -527,15 +527,21 @@ message HttpConnectionManager {
   bool merge_slashes = 33;
 
   // The configuration of the request ID extension. This includes operations such as
-  // generation, validation, and associated tracing operations.
+  // generation, validation, and associated tracing operations. If empty, the
+  // :ref:`UuidRequestIdConfig <envoy_v3_api_msg_extensions.request_id.uuid.v3.UuidRequestIdConfig>`
+  // default extension is used with default parameters. See the documentation for that extension
+  // for details on what it does. Customizing the configuration for the default extension can be
+  // achieved by configuring it explicitly here. For example, to disable trace reason packing,
+  // the following configuration can be used:
   //
-  // If not set, Envoy uses the default UUID-based behavior:
-  //
-  // 1. Request ID is propagated using *x-request-id* header.
+  // .. validated-code-block:: yaml
+  //   :type-name: envoy.extensions.filters.network.http_connection_manager.v3.RequestIDExtension
   //
-  // 2. Request ID is a universally unique identifier (UUID).
+  //   typed_config:
+  //     "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
+  //     pack_trace_reason: false
   //
-  // 3. Tracing decision (sampled, forced, etc) is set in 14th byte of the UUID.
+  // [#extension-category: envoy.request_id]
   RequestIDExtension request_id_extension = 36;
 
   // The configuration to customize local reply returned by Envoy. It can customize status code,

envoy/extensions/request_id/uuid/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_udpa//udpa/annotations:pkg"],
+)

envoy/extensions/request_id/uuid/v3/uuid.proto

@@ -0,0 +1,43 @@
+syntax = "proto3";
+
+package envoy.extensions.request_id.uuid.v3;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.request_id.uuid.v3";
+option java_outer_classname = "UuidProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: UUID]
+// [#extension: envoy.request_id.uuid]
+
+// Configuration for the default UUID request ID extension which has the following behavior:
+//
+// 1. Request ID is propagated using the :ref:`x-request-id
+//    <config_http_conn_man_headers_x-request-id>` header.
+//
+// 2. Request ID is a universally unique identifier `(UUID4)
+//    <https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)>`_.
+//
+// 3. Tracing decision (sampled, forced, etc) is set in 14th nibble of the UUID. By default this will
+//    overwrite existing UUIDs received in the *x-request-id* header if the trace sampling decision
+//    is changed. The 14th nibble of the UUID4 has been chosen because it is fixed to '4' by the
+//    standard. Thus, '4' indicates a default UUID and no trace status. This nibble is swapped to:
+//
+//      a. '9': Sampled.
+//      b. 'a': Force traced due to server-side override.
+//      c. 'b': Force traced due to client-side request ID joining.
+//
+//    See the :ref:`x-request-id <config_http_conn_man_headers_x-request-id>` documentation for
+//    more information.
+message UuidRequestIdConfig {
+  // Whether the implementation alters the UUID to contain the trace sampling decision as per the
+  // `UuidRequestIdConfig` message documentation. This defaults to true. If disabled no
+  // modification to the UUID will be performed. It is important to note that if disabled,
+  // stable sampling of traces, access logs, etc. will no longer work and only random sampling will
+  // be possible.
+  google.protobuf.BoolValue pack_trace_reason = 1;
+}

versioning/BUILD

@@ -128,6 +128,7 @@ proto_library(
         "//envoy/extensions/internal_redirect/safe_cross_scheme/v3:pkg",
         "//envoy/extensions/network/socket_interface/v3:pkg",
         "//envoy/extensions/rate_limit_descriptors/expr/v3:pkg",
+        "//envoy/extensions/request_id/uuid/v3:pkg",
         "//envoy/extensions/resource_monitors/fixed_heap/v3:pkg",
         "//envoy/extensions/resource_monitors/injected_resource/v3:pkg",
         "//envoy/extensions/retry/host/omit_canary_hosts/v3:pkg",