Lua

Attention

By default Envoy is built without exporting symbols that you may need when interacting with Lua modules installed as shared objects. Envoy may need to be built with support for exported symbols. Please see the Bazel docs for more information.

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 filter only supports loading Lua code in-line in the configuration. If local filesystem code is desired, a trivial in-line script can be used to load the rest of the code from the local environment.

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 create 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 yield 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

Script examples

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

  1. -- Called on the request path.
  2. function envoy_on_request(request_handle)
  3.   -- Wait for the entire request body and add a request header with the body size.
  4.   request_handle:headers():add("request_body_size", request_handle:body():length())
  5. end
  7. -- Called on the response path.
  8. function envoy_on_response(response_handle)
  9.   -- Wait for the entire response body and a response header with the the body size.
  10.   response_handle:headers():add("response_body_size", response_handle:body():length())
  11.   -- Remove a response header named 'foo'
  12.   response_handle:headers():remove("foo")
  13. end
  1. function envoy_on_request(request_handle)
  2.   -- Make an HTTP call to an upstream host with the following headers, body, and timeout.
  3.   local headers, body = request_handle:httpCall(
  4.   "lua_cluster",
  5.   {
  6.     [":method"] = "POST",
  7.     [":path"] = "/",
  8.     [":authority"] = "lua_cluster"
  9.   },
  10.   "hello world",
  11.   5000)
  13.   -- Add information from the HTTP call into the headers that are about to be sent to the next
  14.   -- filter in the filter chain.
  15.   request_handle:headers():add("upstream_foo", headers["foo"])
  16.   request_handle:headers():add("upstream_body_size", #body)
  17. end
  1. function envoy_on_request(request_handle)
  2.   -- Make an HTTP call.
  3.   local headers, body = request_handle:httpCall(
  4.   "lua_cluster",
  5.   {
  6.     [":method"] = "POST",
  7.     [":path"] = "/",
  8.     [":authority"] = "lua_cluster"
  9.   },
  10.   "hello world",
  11.   5000)
  13.   -- Response directly and set a header from the HTTP call. No further filter iteration
  14.   -- occurs.
  15.   request_handle:respond(
  16.     {[":status"] = "403",
  17.      ["upstream_foo"] = headers["foo"]},
  18.     "nope")
  19. end

Complete example

A complete example using Docker is available in /examples/lua.

Stream handle API

When Envoy loads the script in the configuration, it looks for two global functions that the script defines:

  1. function envoy_on_request(request_handle)
  2. end
  4. function envoy_on_response(response_handle)
  5. 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 an API handle. During the response path, Envoy will run envoy_on_response as a coroutine, passing an API handle.

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()

  1. 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 header 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()

  1. body = handle:body()

Returns the stream’s body. This call will cause Envoy to yield the script until the entire body has been buffered. 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.

Returns a buffer object.

bodyChunks()

  1. iterator = handle:bodyChunks()

Returns an iterator that can be used to iterate through all received body chunks as they arrive. Envoy will yield 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.

  1. for chunk in request_handle:bodyChunks() do
  2.   request_handle:log(0, chunk:length())
  3. end

Each chunk the iterator returns is a buffer object.

trailers()

  1. trailers = handle:trailers()

Returns the stream’s trailers. 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*()

  1. handle:logTrace(message)
  2. handle:logDebug(message)
  3. handle:logInfo(message)
  4. handle:logWarn(message)
  5. handle:logErr(message)
  6. handle:logCritical(message)

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

httpCall()

  1. headers, body = handle:httpCall(cluster, headers, body, timeout)

Makes an HTTP call to an upstream host. Envoy will yield the script until the call completes or has an error. cluster is a string which maps to a configured cluster manager cluster. headers is a table of key/value pairs to send. Note that the :method, :path, and :authority headers must be set. body is an optional string of body data to send. timeout is an integer that specifies the call timeout in milliseconds.

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.

respond()

  1. handle:respond(headers, body)

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

  1. function envoy_on_request(request_handle)
  2.   for chunk in request_handle:bodyChunks() do
  3.     request_handle:respond(
  4.       {[":status"] = "100"},
  5.       "nope")
  6.   end
  7. end

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

metadata()

  1. metadata = handle:metadata()

Returns the current route entry metadata. Note that the metadata should be specified under the filter name i.e. envoy.lua. Below is an example of a metadata in a route entry.

  1. metadata:
  2.   filter_metadata:
  3.     envoy.lua:
  4.       foo: bar
  5.       baz:
  6.         - bad
  7.         - baz

Returns a metadata object.

streamInfo()

  1. streamInfo = handle:streamInfo()

Returns information related to the current request.

Returns a stream info object.

connection()

  1. connection = handle:connection()

Returns the current request’s underlying connection.

Returns a connection object.

Header object API

add()

  1. 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()

  1. 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.

__pairs()

  1. for key, value in pairs(headers) do
  2. 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 currently implementation, headers cannot be modified during iteration. Additionally, if it is desired to modify headers after iteration, the iteration must be completed. Meaning, do not use break or any other mechanism to exit the loop early. This may be relaxed in the future.

remove()

  1. headers:remove(key)

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

replace()

  1. 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.

Buffer API

length()

  1. size = buffer:length()

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

getBytes()

  1. buffer:getBytes(index, length)

Get 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.

Metadata object API

get()

  1. metadata:get(key)

Gets a 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()

  1. for key, value in pairs(metadata) do
  2. end

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

Stream info object API

protocol()

  1. streamInfo:protocol()

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

dynamicMetadata()

  1. streamInfo:dynamicMetadata()

Returns a dynamic metadata object.

Dynamic metadata object API

get()

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

Gets an entry in 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()

  1. dynamicMetadata:set(filterName, key, value)

Sets 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 and value is string.

__pairs()

  1. for key, value in pairs(dynamicMetadata) do
  2. end

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

Connection object API

ssl()

  1. if connection:ssl() == nil then
  2.   print("plain")
  3. else
  4.   print("secure")
  5. end

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

Note

Currently the SSL connection object has no exposed APIs.