access_log: add a new COALESCE substitution formatter (#42711)

agrawroh · web-flow · commit 7b1c7b10fe6e · 2025-12-23T10:12:59.000+08:00
## Description

This PR adds a new `COALESCE` substitution formatter that evaluates
multiple formatter operators in sequence and returns the first non-null
result. This could be used to have a fallback behavior such as using SNI
when available but falling back to the `:authority` header when SNI is
not available.

**Example:**

```
%COALESCE(
  {
    "operators": [
      "REQUESTED_SERVER_NAME",
      {"command": "REQ", "param": ":authority"},
      {"command": "REQ", "param": "x-envoy-original-host"}
    ]
  }
)%
```

---

**Commit Message:** access_log: add a new **COALESCE** substitution
formatter
**Additional Description:** Adds a new `COALESCE` substitution formatter
that evaluates multiple formatter operators in sequence and returns the
first non-null result.
**Risk Level:** Low
**Testing:** Added Unit + Integration Tests
**Docs Changes:** Added
**Release Notes:** Added

Signed-off-by: Rohit Agrawal &lt;rohit.agrawal@databricks.com&gt;
diff --git a/changelogs/current.yaml b/changelogs/current.yaml
@@ -277,6 +277,11 @@ new_features:
   change: |
     Added process-level rate limiting on access log emission via
     :ref:`ProcessRateLimitFilter <envoy_v3_api_msg_extensions.access_loggers.filters.process_ratelimit.v3.ProcessRateLimitFilter>`.
+- area: access_log
+  change: |
+    Added :ref:`COALESCE <config_access_log_format_coalesce>` substitution formatter operator that evaluates multiple
+    formatter operators in sequence and returns the first non-null result. This enables fallback behavior such as
+    using SNI when available but falling back to the ``:authority`` header when SNI is not set.
 - area: listener_filters
   change: |
     Added :ref:`Postgres Inspector <config_listener_filters_postgres_inspector>` listener filter for detecting
diff --git a/docs/root/configuration/observability/access_log/usage.rst b/docs/root/configuration/observability/access_log/usage.rst
@@ -1487,3 +1487,61 @@ UDP
 %CUSTOM_FLAGS%
   Custom flags set into the stream info. This could be used to log any custom event from the filters.
   Multiple flags are separated by comma.
+
+.. _config_access_log_format_coalesce:
+
+%COALESCE(JSON_CONFIG):Z%
+  HTTP
+    A higher-order formatter operator that evaluates multiple formatter operators in sequence and
+    returns the first non-null, non-empty result. This is useful for implementing fallback behavior,
+    such as using SNI when available but falling back to the ``:authority`` header when SNI is not set.
+
+    The ``JSON_CONFIG`` parameter is a JSON object with an ``operators`` array. Each operator can be
+    specified as either:
+
+    * A string representing a simple command name that does not require a parameter.
+    * An object with the following fields:
+
+      * ``command`` (required): The command name (e.g., ``REQ``, ``REQUESTED_SERVER_NAME``).
+      * ``param`` (optional): The command parameter (e.g., ``:authority`` for the ``REQ`` command).
+      * ``max_length`` (optional): Maximum length for this operator's output.
+
+    ``Z`` is an optional parameter denoting string truncation up to ``Z`` characters for the final output.
+
+    .. note::
+
+      The JSON parameter cannot contain literal ``)`` characters as they would interfere with the
+      command parser. If you need a ``)`` character in a string value, use the Unicode escape
+      sequence ``\u0029``.
+
+    **Example: SNI with fallback to authority header**
+
+    .. code-block:: none
+
+      %COALESCE({"operators": ["REQUESTED_SERVER_NAME", {"command": "REQ", "param": ":authority"}]})%
+
+    This returns the Server Name Indication (SNI) if available, otherwise falls back to the
+    ``:authority`` header.
+
+    **Example: Cascade fallback with multiple headers**
+
+    .. code-block:: none
+
+      %COALESCE({"operators": ["REQUESTED_SERVER_NAME", {"command": "REQ", "param": ":authority"}, {"command": "REQ", "param": "x-envoy-original-host"}]})%
+
+    This tries SNI first, then ``:authority``, then ``x-envoy-original-host``.
+
+    **Example: With length truncation**
+
+    .. code-block:: none
+
+      %COALESCE({"operators": [{"command": "REQ", "param": ":authority"}]}):50%
+
+    This returns the ``:authority`` header value truncated to 50 characters.
+
+    **Supported Commands**
+
+    The ``COALESCE`` operator supports any built-in formatter command.
+
+  TCP/UDP
+    Not implemented ("-").
diff --git a/source/common/formatter/BUILD b/source/common/formatter/BUILD
@@ -63,11 +63,27 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "coalesce_formatter_lib",
+    srcs = ["coalesce_formatter.cc"],
+    hdrs = ["coalesce_formatter.h"],
+    deps = [
+        ":substitution_format_utility_lib",
+        "//envoy/formatter:substitution_formatter_interface",
+        "//envoy/json:json_object_interface",
+        "//envoy/stream_info:stream_info_interface",
+        "//source/common/common:fmt_lib",
+        "//source/common/common:statusor_lib",
+        "//source/common/json:json_loader_lib",
+    ],
+)
+
 envoy_cc_library(
     name = "http_speicific_formatter_extension_lib",
     srcs = ["http_specific_formatter.cc"],
     hdrs = ["http_specific_formatter.h"],
     deps = [
+        ":coalesce_formatter_lib",
         "//envoy/api:api_interface",
         "//envoy/formatter:substitution_formatter_interface",
         "//envoy/runtime:runtime_interface",
diff --git a/source/common/formatter/coalesce_formatter.cc b/source/common/formatter/coalesce_formatter.cc
@@ -0,0 +1,154 @@
+#include "source/common/formatter/coalesce_formatter.h"
+
+#include "source/common/common/fmt.h"
+#include "source/common/json/json_loader.h"
+
+namespace Envoy {
+namespace Formatter {
+
+absl::StatusOr<FormatterProviderPtr> CoalesceFormatter::create(absl::string_view json_config,
+                                                               absl::optional<size_t> max_length) {
+  if (json_config.empty()) {
+    return absl::InvalidArgumentError("COALESCE requires a JSON configuration parameter");
+  }
+
+  auto json_or_error = Json::Factory::loadFromString(std::string(json_config));
+  if (!json_or_error.ok()) {
+    return absl::InvalidArgumentError(fmt::format(
+        "COALESCE: failed to parse JSON configuration: {}", json_or_error.status().message()));
+  }
+
+  const auto& json = *json_or_error.value();
+
+  if (!json.hasObject("operators")) {
+    return absl::InvalidArgumentError(
+        "COALESCE: JSON configuration must contain 'operators' array");
+  }
+
+  auto operators_or_error = json.getObjectArray("operators");
+  if (!operators_or_error.ok()) {
+    return absl::InvalidArgumentError(fmt::format("COALESCE: 'operators' must be an array: {}",
+                                                  operators_or_error.status().message()));
+  }
+
+  const auto& operators = operators_or_error.value();
+  if (operators.empty()) {
+    return absl::InvalidArgumentError("COALESCE: 'operators' array must not be empty");
+  }
+
+  std::vector<FormatterProviderPtr> formatters;
+  formatters.reserve(operators.size());
+
+  for (size_t i = 0; i < operators.size(); ++i) {
+    const auto& entry = operators[i];
+    auto formatter_or_error = parseOperatorEntry(*entry);
+    if (!formatter_or_error.ok()) {
+      return absl::InvalidArgumentError(
+          fmt::format("COALESCE: failed to parse operator at index {}: {}", i,
+                      formatter_or_error.status().message()));
+    }
+    formatters.push_back(std::move(formatter_or_error.value()));
+  }
+
+  return std::make_unique<CoalesceFormatter>(std::move(formatters), max_length);
+}
+
+absl::StatusOr<FormatterProviderPtr>
+CoalesceFormatter::parseOperatorEntry(const Json::Object& entry) {
+  // Check if this is a simple string command with command-only and no parameters.
+  auto string_value = entry.asString();
+  if (string_value.ok()) {
+    return createFormatterForCommand(string_value.value(), "", absl::nullopt);
+  }
+
+  // Otherwise, it should be an object with "command" field.
+  if (!entry.isObject()) {
+    return absl::InvalidArgumentError(
+        "operator entry must be either a string (command name) or an object with 'command' field");
+  }
+
+  auto command_or_error = entry.getString("command");
+  if (!command_or_error.ok()) {
+    return absl::InvalidArgumentError(fmt::format("operator object must have 'command' field: {}",
+                                                  command_or_error.status().message()));
+  }
+
+  std::string param;
+  if (entry.hasObject("param")) {
+    auto param_or_error = entry.getString("param");
+    if (!param_or_error.ok()) {
+      return absl::InvalidArgumentError(
+          fmt::format("'param' field must be a string: {}", param_or_error.status().message()));
+    }
+    param = param_or_error.value();
+  }
+
+  absl::optional<size_t> entry_max_length;
+  if (entry.hasObject("max_length")) {
+    auto max_length_or_error = entry.getInteger("max_length");
+    if (!max_length_or_error.ok()) {
+      return absl::InvalidArgumentError(fmt::format("'max_length' field must be an integer: {}",
+                                                    max_length_or_error.status().message()));
+    }
+    if (max_length_or_error.value() <= 0) {
+      return absl::InvalidArgumentError("'max_length' must be a positive integer");
+    }
+    entry_max_length = static_cast<size_t>(max_length_or_error.value());
+  }
+
+  return createFormatterForCommand(command_or_error.value(), param, entry_max_length);
+}
+
+absl::StatusOr<FormatterProviderPtr>
+CoalesceFormatter::createFormatterForCommand(absl::string_view command, absl::string_view param,
+                                             absl::optional<size_t> max_length) {
+  // Try built-in command parsers to create the formatter.
+  for (const auto& parser : BuiltInCommandParserFactoryHelper::commandParsers()) {
+    auto formatter = parser->parse(command, param, max_length);
+    if (formatter != nullptr) {
+      return formatter;
+    }
+  }
+
+  return absl::InvalidArgumentError(fmt::format("unknown command: '{}'", command));
+}
+
+absl::optional<std::string>
+CoalesceFormatter::format(const Context& context, const StreamInfo::StreamInfo& stream_info) const {
+  for (const auto& formatter : formatters_) {
+    auto result = formatter->format(context, stream_info);
+    if (result.has_value() && !result.value().empty()) {
+      if (max_length_.has_value()) {
+        SubstitutionFormatUtils::truncate(result.value(), max_length_.value());
+      }
+      return result;
+    }
+  }
+  return absl::nullopt;
+}
+
+Protobuf::Value CoalesceFormatter::formatValue(const Context& context,
+                                               const StreamInfo::StreamInfo& stream_info) const {
+  for (const auto& formatter : formatters_) {
+    auto result = formatter->formatValue(context, stream_info);
+    // Check if this is a valid non-null value.
+    if (result.kind_case() != Protobuf::Value::KIND_NOT_SET &&
+        result.kind_case() != Protobuf::Value::kNullValue) {
+      // For string values, also check if empty.
+      if (result.kind_case() == Protobuf::Value::kStringValue) {
+        if (!result.string_value().empty()) {
+          if (max_length_.has_value() && result.string_value().size() > max_length_.value()) {
+            result.set_string_value(result.string_value().substr(0, max_length_.value()));
+          }
+          return result;
+        }
+      } else {
+        return result;
+      }
+    }
+  }
+  return SubstitutionFormatUtils::unspecifiedValue();
+}
+
+} // namespace Formatter
+} // namespace Envoy
diff --git a/source/common/formatter/coalesce_formatter.h b/source/common/formatter/coalesce_formatter.h
@@ -0,0 +1,84 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "envoy/formatter/substitution_formatter.h"
+#include "envoy/json/json_object.h"
+#include "envoy/stream_info/stream_info.h"
+
+#include "source/common/common/statusor.h"
+#include "source/common/formatter/substitution_format_utility.h"
+
+#include "absl/types/optional.h"
+
+namespace Envoy {
+namespace Formatter {
+
+/**
+ * CoalesceFormatter provides a higher-order formatter that evaluates multiple
+ * formatter operators in sequence and returns the first non-null result.
+ *
+ * This formatter accepts a JSON configuration specifying an array of operators
+ * to evaluate. Each operator can be either:
+ * - A string representing a simple command (e.g., "REQUESTED_SERVER_NAME")
+ * - An object with "command" and optional "param" and "max_length" fields
+ *
+ * Example JSON configuration:
+ * {
+ *   "operators": [
+ *     "REQUESTED_SERVER_NAME",
+ *     {"command": "REQ", "param": ":authority"},
+ *     {"command": "REQ", "param": "host"}
+ *   ]
+ * }
+ *
+ * Note that the JSON parameter cannot contain literal ')' characters as they would
+ * interfere with the command parser regex.
+ */
+class CoalesceFormatter : public FormatterProvider {
+public:
+  /**
+   * Creates a CoalesceFormatter from a JSON configuration string.
+   * @param json_config the JSON configuration string.
+   * @param max_length optional maximum length for the output.
+   * @return StatusOr containing the formatter or an error.
+   */
+  static absl::StatusOr<FormatterProviderPtr> create(absl::string_view json_config,
+                                                     absl::optional<size_t> max_length);
+
+  CoalesceFormatter(std::vector<FormatterProviderPtr>&& formatters,
+                    absl::optional<size_t> max_length)
+      : formatters_(std::move(formatters)), max_length_(max_length) {}
+
+  // FormatterProvider interface.
+  absl::optional<std::string> format(const Context& context,
+                                     const StreamInfo::StreamInfo& stream_info) const override;
+  Protobuf::Value formatValue(const Context& context,
+                              const StreamInfo::StreamInfo& stream_info) const override;
+
+private:
+  /**
+   * Parses a single operator entry from the JSON configuration.
+   * @param entry the JSON object representing an operator entry.
+   * @return StatusOr containing the formatter or an error.
+   */
+  static absl::StatusOr<FormatterProviderPtr> parseOperatorEntry(const Json::Object& entry);
+
+  /**
+   * Creates a formatter for the given command using built-in command parsers.
+   * @param command the command name.
+   * @param param the command parameter (may be empty).
+   * @param max_length optional maximum length.
+   * @return StatusOr containing the formatter or an error.
+   */
+  static absl::StatusOr<FormatterProviderPtr>
+  createFormatterForCommand(absl::string_view command, absl::string_view param,
+                            absl::optional<size_t> max_length);
+
+  std::vector<FormatterProviderPtr> formatters_;
+  absl::optional<size_t> max_length_;
+};
+
+} // namespace Formatter
+} // namespace Envoy
diff --git a/source/common/formatter/http_specific_formatter.cc b/source/common/formatter/http_specific_formatter.cc
@@ -6,6 +6,7 @@
 #include "source/common/common/thread.h"
 #include "source/common/common/utility.h"
 #include "source/common/config/metadata.h"
+#include "source/common/formatter/coalesce_formatter.h"
 #include "source/common/grpc/common.h"
 #include "source/common/grpc/status.h"
 #include "source/common/http/header_map_impl.h"
@@ -502,6 +503,12 @@ BuiltInHttpCommandParser::getKnownFormatters() {
            SubstitutionFormatUtils::parseSubcommand(format, ':', query, option);
            return THROW_OR_RETURN_VALUE(PathFormatter::create(query, option, max_length),
                                         FormatterProviderPtr);
+         }}},
+       {"COALESCE",
+        {CommandSyntaxChecker::PARAMS_REQUIRED | CommandSyntaxChecker::LENGTH_ALLOWED,
+         [](absl::string_view format, absl::optional<size_t> max_length) {
+           return THROW_OR_RETURN_VALUE(CoalesceFormatter::create(format, max_length),
+                                        FormatterProviderPtr);
          }}}});
 }
 
diff --git a/test/common/formatter/substitution_formatter_test.cc b/test/common/formatter/substitution_formatter_test.cc
diff --git a/test/integration/access_log_integration_test.cc b/test/integration/access_log_integration_test.cc
