Lua

Overview

The HTTP Lua filter allows Lua scripts to be run during both the request and response flows. LuaJIT is used as the runtime. Because of this, the supported Lua version is mostly 5.1 with some 5.2 features. See the LuaJIT documentation for more details.

The design of the filter and Lua support at a high level is as follows:

• All Lua environments are per worker thread. This means that there is no truly global data. Any globals created and populated at load time will be visible from each worker thread in isolation. True global support may be added via an API in the future.

• All scripts are run as coroutines. This means that they are written in a synchronous style even though they may perform complex asynchronous tasks. This makes the scripts substantially easier to write. All network/async processing is performed by Envoy via a set of APIs. Envoy will suspend execution of the script as appropriate and resume it when async tasks are complete.

• Do not perform blocking operations from scripts. It is critical for performance that Envoy APIs are used for all IO.

Currently supported high-level features

Note

It is expected that this list will expand over time as the filter is used in production. The API surface has been kept small on purpose. The goal is to make scripts extremely simple and safe to write. Very complex or high performance use cases are assumed to use the native C++ filter API.

• Inspection of headers, body, and trailers while streaming in either the request flow, response flow, or both.

• Modification of headers and trailers.

• Blocking and buffering the full request/response body for inspection.

• Performing an outbound async HTTP call to an upstream host. Such a call can be performed while buffering body data so that when the call completes upstream headers can be modified.

• Performing a direct response and skipping further filter iteration. For example, a script could make an upstream HTTP call for authentication, and then directly respond with a 403 response code.

Configuration

• This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua.

• v3 API reference

A simple example of configuring the Lua HTTP filter that contains only default source code is as follows:

lua-filter.yaml

          - name: lua-custom-name
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
              default_source_code:
                inline_string: |
                  -- Called on the request path.
                  function envoy_on_request(request_handle)
                    -- Do something.
                  end
                  -- Called on the response path.
                  function envoy_on_response(response_handle)
                    -- Do something.
                  end

By default, the Lua script defined in default_source_code will be treated as a default script. Envoy will execute it for every HTTP request. This default script is optional.

Per-Route Configuration

The Lua HTTP filter also can be disabled or overridden on a per-route basis by providing a LuaPerRoute configuration on the virtual host, route, or weighted cluster.

LuaPerRoute provides two ways of overriding the default Lua script:

• By providing a name reference to the defined named Lua source codes map.

• By providing inline source code (this allows the code to be sent through RDS).

As a concrete example, given the following Lua filter configuration:

lua-filter-override.yaml

          - name: envoy.filters.http.lua
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
              default_source_code:
                inline_string: |
                  function envoy_on_request(request_handle)
                    -- do something
                  end
              source_codes:
                hello.lua:
                  inline_string: |
                    function envoy_on_request(request_handle)
                      request_handle:logInfo("Hello World.")
                    end
                bye.lua:
                  inline_string: |
                    function envoy_on_response(response_handle)
                      response_handle:logInfo("Bye Bye.")
                    end

The HTTP Lua filter can be disabled on some virtual host, route, or weighted cluster by the LuaPerRoute configuration as follows:

lua-filter-override.yaml

                typed_per_filter_config:
                  envoy.filters.http.lua:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.LuaPerRoute
                    disabled: true

We can also refer to a Lua script in the filter configuration by specifying a name in LuaPerRoute. The default Lua script will be overridden by the referenced script:

lua-filter-override.yaml

                typed_per_filter_config:
                  envoy.filters.http.lua:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.LuaPerRoute
                    name: hello.lua

Or we can define a new Lua script in the LuaPerRoute configuration directly to override the default Lua script as follows:

lua-filter-override.yaml

                typed_per_filter_config:
                  envoy.filters.http.lua:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.LuaPerRoute
                    source_code:
                      inline_string: |
                        function envoy_on_response(response_handle)
                          response_handle:logInfo("Goodbye.")
                        end

Upstream Filter

The Lua filter can be used as an upstream filter. Upstream filters cannot clear the route cache (as the routing decision has already been made). Clearing the route cache will be a no-op in this case.

Statistics

The Lua filter outputs statistics in the .lua. namespace by default. When there are multiple Lua filters configured in a filter chain, stats from individual filter instance/script can be tracked by providing a per-filter stat prefix.

Name	Type	Description
error	Counter	Total script execution errors.

Script examples

This section provides some concrete examples of Lua scripts as a gentler introduction and quick start. Please refer to the stream handle API for more details on the supported API.

-- Called on the request path.
function envoy_on_request(request_handle)
  -- Wait for the entire request body and add a request header with the body size.
  request_handle:headers():add("request_body_size", request_handle:body():length())
end

-- Called on the response path.
function envoy_on_response(response_handle)
  -- Wait for the entire response body and add a response header with the body size.
  response_handle:headers():add("response_body_size", response_handle:body():length())
  -- Remove a response header named 'foo'
  response_handle:headers():remove("foo")
end

function envoy_on_request(request_handle)
  -- Make an HTTP call to an upstream host with the following headers, body, and timeout.
  local headers, body = request_handle:httpCall(
  "lua_cluster",
  {
    [":method"] = "POST",
    [":path"] = "/",
    [":authority"] = "lua_cluster"
  },
  "hello world",
  5000)

  -- Add information from the HTTP call into the headers that are about to be sent to the next
  -- filter in the filter chain.
  request_handle:headers():add("upstream_foo", headers["foo"])
  request_handle:headers():add("upstream_body_size", #body)
end

function envoy_on_request(request_handle)
  -- Make an HTTP call.
  local headers, body = request_handle:httpCall(
  "lua_cluster",
  {
    [":method"] = "POST",
    [":path"] = "/",
    [":authority"] = "lua_cluster",
    ["set-cookie"] = { "lang=lua; Path=/", "type=binding; Path=/" }
  },
  "hello world",
  5000)

  -- Response directly and set a header from the HTTP call. No further filter iteration
  -- occurs.
  request_handle:respond(
    {[":status"] = "403",
     ["upstream_foo"] = headers["foo"]},
    "nope")
end

function envoy_on_request(request_handle)
  -- Log information about the request
  request_handle:logInfo("Authority: "..request_handle:headers():get(":authority"))
  request_handle:logInfo("Method: "..request_handle:headers():get(":method"))
  request_handle:logInfo("Path: "..request_handle:headers():get(":path"))
end

function envoy_on_response(response_handle)
  -- Log response status code
  response_handle:logInfo("Status: "..response_handle:headers():get(":status"))
end

A common use case is to rewrite the upstream response body. For example: an upstream sends a non-2xx response with JSON data, but the application requires an HTML page to be sent to browsers.

There are two ways of doing this, the first one is via the body() API.

function envoy_on_response(response_handle)
  response_handle:body():setBytes("<html><b>Not Found<b></html>")
  response_handle:headers():replace("content-type", "text/html")
end

Or, through the bodyChunks() API, which lets Envoy skip buffering the upstream response data.

function envoy_on_response(response_handle)

  -- Sets the content-type.
  response_handle:headers():replace("content-type", "text/html")

  local last
  for chunk in response_handle:bodyChunks() do
    -- Clears each received chunk.
    chunk:setBytes("")
    last = chunk
  end

  last:setBytes("<html><b>Not Found<b></html>")
end

Complete example

A complete example using Docker is available in here.

Stream handle API

When Envoy loads the script in the configuration, it looks for two global functions defined by the script:

function envoy_on_request(request_handle)
end

function envoy_on_response(response_handle)
end

A script can define either or both of these functions. During the request path, Envoy will run envoy_on_request as a coroutine, passing a handle to the request API. During the response path, Envoy will run envoy_on_response as a coroutine, passing handle to the response API.

Attention

It is critical that all interaction with Envoy occur through the passed stream handle. The stream handle should not be assigned to any global variable and should not be used outside of the coroutine. Envoy will fail your script if the handle is used incorrectly.

The following methods on the stream handle are supported:

headers()

local headers = handle:headers()

Returns the stream’s headers. The headers can be modified as long as they have not been sent to the next filter in the filter chain. For example, they can be modified after an httpCall() or after a body() call returns. The script will fail if the headers are modified in any other situation.

Returns a header object.

body()

local body = handle:body(always_wrap_body)

Returns the stream’s body. This call will cause Envoy to suspend execution of the script until the entire body has been received in a buffer. Note that all buffering must adhere to the flow-control policies in place. Envoy will not buffer more data than is allowed by the connection manager.

An optional boolean argument always_wrap_body can be used to require that Envoy always returns a body object even if the body is empty. Therefore, we can modify the body regardless of whether the original body exists or not.

Returns a buffer object.

bodyChunks()

local iterator = handle:bodyChunks()

Returns an iterator that can be used to iterate through all received body chunks as they arrive. Envoy will suspend executing the script in between chunks, but will not buffer them. This can be used by a script to inspect data as it is streaming by.

for chunk in request_handle:bodyChunks() do
  request_handle:log(0, chunk:length())
end

Each chunk the iterator returns is a buffer object.

trailers()

local trailers = handle:trailers()

Returns the stream’s trailers. Before calling this method, the caller should call body() or bodyChunks() to consume the body; otherwise, the trailers will not be available. May return nil if there are no trailers. The trailers may be modified before they are sent to the next filter.

Returns a header object.

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

httpCall()

local headers, body = handle:httpCall(cluster, headers, body, timeout_ms, asynchronous)

-- Alternative function signature.
local headers, body = handle:httpCall(cluster, headers, body, options)

Makes an HTTP call to an upstream host. cluster is a string which maps to a configured cluster. headers is a table of key/value pairs to send (the value can be a string or table of strings). Note that the :method, :path, and :authority headers must be set. body is an optional string of body data to send. timeout_ms is an integer that specifies the call timeout in milliseconds.

asynchronous is a boolean flag. If async is set to true, Envoy will make the HTTP request and continue, regardless of the response success or failure. If this is set to false, or not set, Envoy will suspend executing the script until the call completes or has an error.

Returns headers, which is a table of response headers. Returns body, which is the string response body. May be nil if there is no body.

The alternative function signature allows the caller to specify options as a table. Currently, the supported keys are:

• asynchronous is a boolean flag that controls the asynchronicity of the HTTP call. It refers to the same asynchronous flag as the first function signature.

• timeout_ms is an integer that specifies the call timeout in milliseconds. It refers to the same timeout_ms argument as the first function signature.

• trace_sampled is a boolean flag that decides whether the produced trace span will be sampled or not. If not provided, the sampling decision of the parent span is used.

• return_duplicate_headers is a boolean flag that decides whether the repeated headers are allowed in response headers. If return_duplicate_headers is set to false (default), the returned headers is a table with value type of string. If return_duplicate_headers is set to true, the returned headers is a table with value type of string or value type of table.

• send_xff is a boolean flag that decides whether the x-forwarded-for header is sent to the target server. The default value is true.

  For example, the following upstream response headers have repeated headers.

  {
    { ":status", "200" },
    { "foo", "bar" },
    { "key", "value_0" },
    { "key", "value_1" },
    { "key", "value_2" },
  }
  

  Then if return_duplicate_headers is set to false, the returned headers will be:

  {
    [":status"] = "200",
    ["foo"] = "bar",
    ["key"] = "value_2",
  }
  

  If return_duplicate_headers is set to true, the returned headers will be:

  {
    [":status"] = "200",
    ["foo"] = "bar",
    ["key"] = { "value_0", "value_1", "value_2" },
  }
  

Some examples of specifying options are shown below:

-- Create a fire-and-forget HTTP call.
local request_options = {["asynchronous"] = true}

-- Create a synchronous HTTP call with 1000 ms timeout.
local request_options = {["timeout_ms"] = 1000}

-- Create a synchronous HTTP call, but do not sample the trace span.
local request_options = {["trace_sampled"] = false}

-- The same as above, but explicitly set the "asynchronous" flag to false.
local request_options = {["asynchronous"] = false, ["trace_sampled"] = false }

-- The same as above, but with 1000 ms timeout.
local request_options = {["asynchronous"] = false, ["trace_sampled"] = false, ["timeout_ms"] = 1000 }

respond()

handle:respond(headers, body)

Respond immediately and do not continue with further filter iteration. This call is only valid in the request flow. Additionally, a response is only possible if the request headers have not yet been passed to subsequent filters. Meaning, the following Lua code is invalid:

function envoy_on_request(request_handle)
  for chunk in request_handle:bodyChunks() do
    request_handle:respond(
      {[":status"] = "100"},
      "nope")
  end
end

headers is a table of key/value pairs to send (the value can be a string or table of strings). Note that the :status header must be set. body is a string and supplies an optional response body. May be nil.

metadata()

local metadata = handle:metadata()

Returns the current route entry metadata. Note that the metadata should be specified under the filter config name. If no entry could be found by the filter config name, then the filter canonical name i.e. envoy.filters.http.lua will be used as an alternative. Note that this downgrade will be deprecated in the future.

Below is an example of a metadata in a route entry.

lua-filter.yaml

              metadata:
                filter_metadata:
                  lua-custom-name:
                    foo: bar
                    baz:
                    - bad
                    - baz

Returns a metadata object.

streamInfo()

local streamInfo = handle:streamInfo()

Returns information related to the current request.

Returns a stream info object.

connection()

local connection = handle:connection()

Returns the current request’s underlying connection.

Returns a connection object.

connectionStreamInfo()

local connectionStreamInfo = handle:connectionStreamInfo()

Returns connection-level information related to the current request.

Returns a connection-level stream info object.

setUpstreamOverrideHost()

handle:setUpstreamOverrideHost(host, strict)

Sets an upstream address override for the request. When the overridden host is available and can be selected directly, the load balancer bypasses its algorithm and routes traffic directly to the specified host. The strict flag determines whether the HTTP request must strictly use the overridden destination. If the destination is unavailable and strict is set to true, Envoy responds with a 503 Service Unavailable error.

The function takes two arguments:

• host (string): The upstream host address to use for the request. This must be a valid IP address; otherwise, the Lua script will throw an error.

• strict (boolean, optional): Determines whether the HTTP request must be strictly routed to the requested destination. When set to true, if the requested destination is unavailable, Envoy will return a 503 status code. The default value is false, which allows Envoy to fall back to its load balancing mechanism. In this case, if the requested destination is not found, the request will be routed according to the load balancing algorithm.

Example:

function envoy_on_request(request_handle)
  -- Override upstream host without strict mode
  request_handle:setUpstreamOverrideHost("192.168.21.13", false)

  -- Override upstream host with strict mode
  request_handle:setUpstreamOverrideHost("192.168.21.13", true)
end

clearRouteCache()

handle:clearRouteCache()

Clears the route cache for the current request. This will force the route to be recomputed. If you updated the request headers, metadata, or other information that affects the route and expect the route to be recomputed, you can call this function to clear the route cache. Then the route will be recomputed when the route is accessed the next time.

Example:

function envoy_on_request(request_handle)
  -- Clear the route cache
  request_handle:clearRouteCache()
end

filterContext()

local filter_context = handle:filterContext()

Returns the filter context that is configured in the filter_context.

For example, given the following filter context in the route entry:

typed_per_filter_config:
  "lua-filter-name":
    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.LuaPerRoute
    filter_context:
      key: xxxxxx

The filter context can be accessed in the related Lua script as follows:

function envoy_on_request(request_handle)
  -- Get the filter context
  local filter_context = request_handle:filterContext()

  -- Access the filter context data
  local value = filter_context["key"]
end

importPublicKey()

local pubkey = handle:importPublicKey(keyder, keyderLength)

Returns a public key which is used by verifySignature to verify a digital signature.

verifySignature()

local ok, error = handle:verifySignature(hashFunction, pubkey, signature, signatureLength, data, dataLength)

Verifies a signature using the provided parameters. hashFunction is the variable for the hash function which will be used for verifying the signature. SHA1, SHA224, SHA256, SHA384 and SHA512 are supported. pubkey is the public key. signature is the signature to be verified. signatureLength is the length of the signature. data is the content which will be hashed. dataLength is the length of the data.

The function returns a pair. If the first element is true, the second element will be empty, which means the signature is verified; otherwise, the second element will store the error message.

base64Escape()

local base64_encoded = handle:base64Escape("input string")

Encodes the input string as base64. This can be useful for escaping binary data.

timestamp()

timestamp = handle:timestamp(format)

High-resolution timestamp function. format is an optional enum parameter to indicate the format of the timestamp. EnvoyTimestampResolution.MILLISECOND is supported. The function returns a timestamp in milliseconds since epoch by default if format is not set.

timestampString()

timestamp = handle:timestampString(resolution)

Timestamp function. The timestamp is returned as a string. It represents the integer value of the selected resolution since epoch. resolution is an optional enum parameter to indicate the resolution of the timestamp. Supported resolutions are EnvoyTimestampResolution.MILLISECOND and EnvoyTimestampResolution.MICROSECOND. The default resolution is millisecond if resolution is not set.

Header object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

add()

headers:add(key, value)

Adds a header. key is a string that supplies the header key. value is a string that supplies the header value.

get()

headers:get(key)

Gets a header. key is a string that supplies the header key. Returns a string that is the header value or nil if there is no such header. If there are multiple headers in the same case-insensitive key, their values will be combined with a , separator and returned as a string.

getAtIndex()

headers:getAtIndex(key, index)

Gets the header value at the given index. It can be used to fetch a specific value in case the given header has multiple values. key is a string that supplies the header key and index is an integer that supplies the position. It returns a string that is the header value or nil if there is no such header or if there is no value at the specified index.

getNumValues()

headers:getNumValues(key)

Gets the number of values of a given header. It can be used to fetch the total number of values in case the given header has multiple values. key is a string that supplies the header key. It returns an integer with the value size for the given header or 0 if there is no such header.

__pairs()

for key, value in pairs(headers) do
end

Iterates through every header. key is a string that supplies the header key. value is a string that supplies the header value.

Attention

In the current implementation, headers cannot be modified during iteration. Additionally, if it is necessary to modify headers after an iteration, the iteration must first be completed. This means that break or any other way to exit the loop early must not be used. This may be more flexible in the future.

remove()

headers:remove(key)

Removes a header. key supplies the header key to remove.

replace()

headers:replace(key, value)

Replaces a header. key is a string that supplies the header key. value is a string that supplies the header value. If the header does not exist, it is added as per the add() function.

setHttp1ReasonPhrase()

headers:setHttp1ReasonPhrase(reasonPhrase)

Sets a custom HTTP/1 response reason phrase. This call is only valid in the response flow. reasonPhrase is a string that supplies the reason phrase value. Additionally this call only affects HTTP/1 connections. It will have no effect if the client is HTTP/2 or HTTP/3.

Buffer API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

length()

local size = buffer:length()

Gets the size of the buffer in bytes. Returns an integer.

getBytes()

buffer:getBytes(index, length)

Gets bytes from the buffer. By default Envoy will not copy all buffer bytes to Lua. This will cause a buffer segment to be copied. index is an integer and supplies the buffer start index to copy. length is an integer and supplies the buffer length to copy. index + length must be less than the buffer length.

setBytes()

buffer:setBytes(string)

Set the content of wrapped buffer with the input string.

Metadata object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

get()

metadata:get(key)

Gets metadata. key is a string that supplies the metadata key. Returns the corresponding value of the given metadata key. The type of the value can be: nil, boolean, number, string and table.

__pairs()

for key, value in pairs(metadata) do
end

Iterates through every metadata entry. key is a string that supplies a metadata key. value is a metadata entry value.

Stream info object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

protocol()

streamInfo:protocol()

Returns the string representation of HTTP protocol used by the current request. The possible values are: HTTP/1.0, HTTP/1.1, HTTP/2 and HTTP/3.

routeName()

streamInfo:routeName()

Returns the name of the route matched by the filter chain. Returns an empty string if no route was matched.

Example usage:

function envoy_on_request(request_handle)
  local route_name = request_handle:streamInfo():routeName()
  request_handle:logInfo("Matched route: " .. route_name)
end

virtualClusterName()

streamInfo:virtualClusterName()

Returns the name of the virtual cluster matched for the current request. Returns an empty string if no virtual cluster was matched.

Example usage:

function envoy_on_request(request_handle)
  local virtual_cluster = request_handle:streamInfo():virtualClusterName()
  request_handle:logInfo("Matched virtual cluster: " .. virtual_cluster)
end

downstreamDirectLocalAddress()

streamInfo:downstreamDirectLocalAddress()

Returns the string representation of downstream direct local address used by the current request. This is always the physical local address of the connection.

downstreamLocalAddress()

streamInfo:downstreamLocalAddress()

Returns the string representation of downstream local address used by the current request.

downstreamDirectRemoteAddress()

streamInfo:downstreamDirectRemoteAddress()

Returns the string representation of downstream directly connected address used by the current request. This is equivalent to the address of the physical connection.

downstreamRemoteAddress()

streamInfo:downstreamRemoteAddress()

Returns the string representation of the downstream remote address for the current request. This may differ from downstreamDirectRemoteAddress() depending upon the setting of xff_num_trusted_hops.

dynamicMetadata()

streamInfo:dynamicMetadata()

Returns a dynamic metadata object.

downstreamSslConnection()

streamInfo:downstreamSslConnection()

Returns information related to the current SSL connection.

Returns a downstream SSL connection info object.

requestedServerName()

streamInfo:requestedServerName()

Returns the string representation of requested server name (e.g. SNI in TLS) for the current request if present.

Connection stream info object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

dynamicTypedMetadata()

connectionStreamInfo:dynamicTypedMetadata(filterName)

Returns dynamic metadata for a given filter name. Dynamic metadata provides type-safe access to metadata values that are stored as protocol buffer messages. This is particularly useful when working with filters that store structured data.

filterName is a string that supplies the filter name, e.g. envoy.lb. Returns a Lua table containing the unpacked protocol buffer message. Returns nil if no dynamic metadata exists for the given filter name or if the metadata cannot be unpacked.

Type Conversion Details:

The following rules apply when converting protocol buffer messages into Lua tables:

• Repeated fields are converted to Lua arrays (1-based indexing)

• Map fields become Lua tables with string keys

• Enums are represented as their numeric values

• Byte fields are translated to Lua strings

• Nested messages are converted to nested tables

• Optional fields that are not set are returned as nil

Error Handling:

This method ensures type-safe access to metadata but returns nil in the following scenarios:

• If the specified filter name does not exist. For example, trying to access dynamicTypedMetadata("envoy.filters.listener.proxy_protocol") when the proxy protocol filter isn’t configured.

• If the metadata exists but cannot be unpacked. It could happen if the filter state exists but is stored as a different type than ProtobufWkt::Struct.

• If the protocol buffer message is malformed. It could happen when the data in the filter state is corrupted or partially written.

Common Use Cases:

1. Accessing Proxy Protocol Metadata:

function envoy_on_request(request_handle)
  -- Access proxy protocol typed metadata
  local typed_meta = request_handle:connectionStreamInfo():dynamicTypedMetadata("envoy.filters.listener.proxy_protocol")

  -- Check if metadata exists
  if typed_meta then
    -- Access specific TLV values
    local tlv_type_authority = typed_meta.typed_metadata.tlv_type_authority  -- Authority identifier from proxy protocol TLV
    local tlv_value = typed_meta.typed_metadata.tlv_value                    -- Value from the proxy protocol TLV data

    request_handle:logInfo(string.format("TLV Authority: %s, Value: %s", tlv_type_authority or "none", tlv_value or "none"))
  else
    request_handle:logInfo("No proxy protocol metadata available")
  end
end

2. Working with Custom Filter Metadata:

function envoy_on_request(request_handle)
  local metadata = request_handle:connectionStreamInfo():dynamicTypedMetadata("custom.filter")

  -- Check if metadata exists before accessing
  if metadata then
    -- Safely access potentially nested fields
    if metadata.config then
      -- Access nested configuration
      if metadata.config.rules then
        for _, rule in ipairs(metadata.config.rules) do
          if rule.name and rule.value then
            request_handle:logInfo(string.format("Rule: %s = %s", rule.name, rule.value))
          end
        end
      end

      -- Access map fields
      if metadata.config.properties then
        for key, value in pairs(metadata.config.properties) do
          request_handle:logInfo(string.format("Property: %s = %s", key, value))
        end
      end
    end
  else
    request_handle:logInfo("No metadata available for custom.filter")
  end
end

Limitations:

1. Dynamic metadata is read-only and cannot be modified through this API

2. Raw protobuf message structure cannot be accessed directly

3. Extension types or unknown fields cannot be accessed through this API

4. Map keys must be strings or integers

5. Some protocol buffer features (like Any messages) may not be fully supported

dynamicMetadata()

connectionStreamInfo:dynamicMetadata()

Returns a dynamic metadata object.

Dynamic metadata object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

get()

dynamicMetadata:get(filterName)

-- to get a value from a returned table.
dynamicMetadata:get(filterName)[key]

Gets an entry in the dynamic metadata struct. filterName is a string that supplies the filter name, e.g. envoy.lb. Returns the corresponding table of a given filterName.

set()

dynamicMetadata:set(filterName, key, value)

Sets a key-value pair of a filterName’s metadata. filterName is a key specifying the target filter name, e.g. envoy.lb. The type of key is string. The type of value is any Lua type that can be mapped to a metadata value: table, numeric, boolean, string or nil. When using a table as an argument, its keys can only be string or numeric.

function envoy_on_request(request_handle)
  local headers = request_handle:headers()
  request_handle:streamInfo():dynamicMetadata():set("envoy.filters.http.lua", "request.info", {
    auth = headers:get("authorization"),
    token = headers:get("x-request-token"),
  })
end

function envoy_on_response(response_handle)
  local meta = response_handle:streamInfo():dynamicMetadata():get("envoy.filters.http.lua")["request.info"]
  response_handle:logInfo("Auth: "..meta.auth..", token: "..meta.token)
end

__pairs()

for key, value in pairs(dynamicMetadata) do
end

Iterates through every dynamicMetadata entry. key is a string that supplies a dynamicMetadata key. value is a dynamicMetadata entry value.

Connection object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

ssl()

if connection:ssl() == nil then
  print("plain")
else
  print("secure")
end

Returns SSL connection object when the connection is secured and nil when it is not.

Returns an SSL connection info object.

SSL connection object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

peerCertificatePresented()

if downstreamSslConnection:peerCertificatePresented() then
  print("peer certificate is presented")
end

Returns a bool representing whether the peer certificate is presented.

peerCertificateValidated()

if downstreamSslConnection:peerCertificateValidated() then
  print("peer certificate is validated")
end

Returns a bool whether the peer certificate was validated.

Warning

Client certificate validation is not currently performed upon TLS session resumption. For a resumed TLS session this method will return false, regardless of whether the peer certificate is valid.

The only known workaround for this issue is to disable TLS session resumption entirely, by setting both disable_stateless_session_resumption and disable_stateful_session_resumption on the DownstreamTlsContext.

uriSanLocalCertificate()

-- For example, uriSanLocalCertificate contains {"san1", "san2"}
local certs = downstreamSslConnection:uriSanLocalCertificate()

-- The following prints san1,san2
handle:logTrace(table.concat(certs, ","))

Returns the URIs (as a table) in the SAN field of the local certificate. Returns an empty table if there is no local certificate, or no SAN field, or no URI SAN entries.

sha256PeerCertificateDigest()

downstreamSslConnection:sha256PeerCertificateDigest()

Returns the SHA256 digest of the peer certificate. Returns "" if there is no peer certificate which can happen in TLS (non-mTLS) connections.

serialNumberPeerCertificate()

downstreamSslConnection:serialNumberPeerCertificate()

Returns the serial number field of the peer certificate. Returns "" if there is no peer certificate, or no serial number.

issuerPeerCertificate()

downstreamSslConnection:issuerPeerCertificate()

Returns the issuer field of the peer certificate in RFC 2253 format. Returns "" if there is no peer certificate, or no issuer.

subjectPeerCertificate()

downstreamSslConnection:subjectPeerCertificate()

Returns the subject field of the peer certificate in RFC 2253 format. Returns "" if there is no peer certificate, or no subject.

parsedSubjectPeerCertificate()

local parsedSubject = downstreamSslConnection:parsedSubjectPeerCertificate()
if parsedSubject then
  print("CN: " .. parsedSubject:commonName())
  print("O: " .. table.concat(parsedSubject:organizationName(), ","))
end

Returns connection parsed from the subject field of the peer certificate. Returns nil if there is no peer certificate.

Returns a parsed name object.

uriSanPeerCertificate()

downstreamSslConnection:uriSanPeerCertificate()

Returns the URIs (as a table) in the SAN field of the peer certificate. Returns an empty table if there is no peer certificate, or no SAN field, or no URI SAN entries.

subjectLocalCertificate()

downstreamSslConnection:subjectLocalCertificate()

Returns the subject field of the local certificate in RFC 2253 format. Returns "" if there is no local certificate, or no subject.

urlEncodedPemEncodedPeerCertificate()

downstreamSslConnection:urlEncodedPemEncodedPeerCertificate()

Returns the URL-encoded PEM-encoded representation of the peer certificate. Returns "" if there is no peer certificate or encoding fails.

urlEncodedPemEncodedPeerCertificateChain()

downstreamSslConnection:urlEncodedPemEncodedPeerCertificateChain()

Returns the URL-encoded PEM-encoded representation of the full peer certificate chain including the leaf certificate. Returns "" if there is no peer certificate or encoding fails.

dnsSansPeerCertificate()

downstreamSslConnection:dnsSansPeerCertificate()

Returns the DNS entries (as a table) in the SAN field of the peer certificate. Returns an empty table if there is no peer certificate, or no SAN field, or no DNS SAN entries.

dnsSansLocalCertificate()

downstreamSslConnection:dnsSansLocalCertificate()

Returns the DNS entries (as a table) in the SAN field of the local certificate. Returns an empty table if there is no local certificate, or no SAN field, or no DNS SAN entries.

oidsPeerCertificate()

downstreamSslConnection:oidsPeerCertificate()

Returns the string representation of OIDs (as a table) from the peer certificate. This is for reading the OID strings from the certificate, not the extension values associated with OIDs. Returns an empty table if there is no peer certificate or no OIDs.

oidsLocalCertificate()

downstreamSslConnection:oidsLocalCertificate()

Returns the string representation of OIDs (as a table) from the local certificate. This is for reading the OID strings from the certificate, not the extension values associated with OIDs. Returns an empty table if there is no local certificate or no OIDs.

validFromPeerCertificate()

downstreamSslConnection:validFromPeerCertificate()

Returns the time (timestamp-since-epoch in seconds) that the peer certificate was issued and should be considered valid from. Returns 0 if there is no peer certificate.

In Lua, we usually use os.time(os.date("!*t")) to get the current timestamp-since-epoch in seconds.

expirationPeerCertificate()

downstreamSslConnection:validFromPeerCertificate()

Returns the time (timestamp-since-epoch in seconds) that the peer certificate expires and should not be considered valid after. Returns 0 if there is no peer certificate.

In Lua, we usually use os.time(os.date("!*t")) to get the current timestamp-since-epoch in seconds.

sessionId()

downstreamSslConnection:sessionId()

Returns the hex-encoded TLS session ID as defined in RFC 5246.

ciphersuiteId()

downstreamSslConnection:ciphersuiteId()

Returns the standard ID (hex-encoded) for the ciphers used in the established TLS connection. Returns "0xffff" if there is no current negotiated ciphersuite.

ciphersuiteString()

downstreamSslConnection:ciphersuiteString()

Returns the OpenSSL name for the set of ciphers used in the established TLS connection. Returns "" if there is no current negotiated ciphersuite.

tlsVersion()

downstreamSslConnection:tlsVersion()

Returns the TLS version (e.g., TLSv1.2, TLSv1.3) used in the established TLS connection.

Parsed name object API

log*()

handle:logTrace(message)
handle:logDebug(message)
handle:logInfo(message)
handle:logWarn(message)
handle:logErr(message)
handle:logCritical(message)

Logs a message using Envoy’s application logging. message is a string to log.

These are supported on all objects that Envoy exposes to Lua.

commonName()

parsedSubject:commonName()

Returns the string representation of the CN field from the X.509 name. Returns "" if there is no such field or if the field can’t be converted to a UTF8 string.

organizationName()

parsedSubject:organizationName()

Returns the string representation of O fields (as a table) from the X.509 name. Returns an empty table if there is no such field or if the field can’t be converted to a UTF8 string.