syntax = "proto3";

package envoy.extensions.formatter.cel.v3;

import "udpa/annotations/status.proto";

option java_package = "io.envoyproxy.envoy.extensions.formatter.cel.v3";
option java_outer_classname = "CelProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/formatter/cel/v3;celv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Formatter extension for printing CEL expressions]
// [#extension: envoy.formatter.cel]

// CEL formatter extension implements CEL command operator that evaluates configured
// symbolic Common Expression Language expressions to generate an access log.
//
// See :ref:`here <config_access_log>` for more information on access log configuration.

// %CEL(EXPRESSION):Z%
// Expressions are based on the set of Envoy :ref:`attributes <arch_overview_attributes>`.
// Expression errors are considered `-`. Z is an optional parameter denoting string
// truncation up to Z characters long.
//
// Examples:
//
// * ``%CEL(response.code)%``
// * ``%CEL(connection.mtls)%``
// * ``%CEL(request.headers['x-envoy-original-path']):10%``
// * ``%CEL(request.headers['x-log-mtls'] || request.url_path.contains('v1beta3'))%``

// Alternatively: %TYPED_CEL(EXPRESSION):Z%
// When using a non-text access log format like JSON, this format command is
// able to emit values of non-string types, like number, boolean, and null,
// based on the output of the CEL expression. It otherwise functions the same as
// %CEL%. CEL types not native to JSON are coerced as follows:
//
// * Bytes are base64 encoded to produce a string.
// * Durations are stringified as a count of seconds, e.g. `duration("1h30m")`
//   becomes "5400s".
// * Timestamps are formatted to UTC, e.g.
//   `timestamp("2023-08-26T12:39:00-07:00")` becomes
//   "2023-08-26T19:39:00+00:00"
// * Maps become objects, provided all keys can be coerced to strings and that
//   all values can coerce to types representable in JSON.
// * Lists become lists, provided all values can coerce to types representable
//   in JSON.

// Configuration for the CEL formatter.
//
// .. warning::
//   This extension is treated as built-in extension and will be enabled by default now.
//   It is unnecessary to configure this extension.
message Cel {
}
