Lua

注意：Lua脚本HTTP过滤器是实验性的。在生产中使用需要您自担风险。它正在被公布，以便对暴露的API进行初步反馈，并进行进一步的开发，测试和验证。当我们认为Lua过滤器已经受到足够的API稳定性测试，通常称其为生产准备就绪时，该警告将被移除。

概述

HTTP Lua过滤器允许在请求和响应流程中运行Lua脚本。在运行时使用LuaJIT。正因为如此，支持的Lua版本大部分是5.1，具有一些5.2的特性。有关更多详细信息，请参阅LuaJIT文档。

该过滤器仅支持在配置中直接加载Lua代码。如果需要本地文件系统代码，则可以使用简单的内联脚本从本地环境加载代码的其余部分。

过滤器和支持Lua是基于如下高级设计：

  • 所有Lua环境都是每个工作者线程。这意味着没有真正的全局数据。任何在加载时创建和填充的全局变量在工作线程之间相互隔离。真正的全局支持可能会在未来通过API添加。
  • 所有脚本都以协程运行。这意味着即使它们可能执行复杂的异步任务，它们也是以同步样式编写的。这使得脚本更容易编写。所有网络/异步处理由Envoy通过一组API执行。Envoy将酌情切换(yield)脚本，并在异步任务完成时恢复脚本。
  • 不要在脚本中执行阻塞操作。因为Envoy API会用于所有IO，以及性能相关的重要操作。

目前支持高级功能

注：预计随着Lua过滤器在生产中的应用，以下列表将随着时间的推移而扩大范围。这些API一直保持很小的用意。为了使脚本编写非常简单和安全。若存在非常复杂或更高性能的场景，请使用本地C++过滤器API。

  • 在传输的请求，响应流或两者同时，提供头部，正文和尾部的检查；
  • 对头部和尾部进行修改；
  • 阻止或者缓冲完整的请求/响应正文，进行检查；
  • 对上游主机执行异步HTTP调用。这样可以在缓冲正文数据的同时执行处理，以便当调用完成时，可以修改上行头部；
  • 直接执行响应并跳过接下来的迭代过滤器。例如，一个脚本可以创建一个上游HTTP认证调用，然后直接用403响应代码进行响应。

配置

脚本示例

本节提供了一些Lua脚本的一些具体的例子，作为一个更简单介绍和快速入门。有关支持的API的更多详细信息，请参阅流处理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

流处理API

当Envoy在配置中加载脚本时，它会查找脚本中定义的两个全局函数：

  1. function envoy_on_request(request_handle)
  2. end
  4. function envoy_on_response(response_handle)
  5. end

一个脚本可以定义这两个函数中的一个或两个。在请求路径中，Envoy将运行envoy_on_request函数作为一个协程，传递一个API句柄。在响应路径中，Envoy将运行envoy_on_response作为协程，传递一个API句柄。

注意：与Envoy的所有交互，都是通过传输流来实现的。流句柄不应该被保存到任何全局变量，不应该在协程之外使用。如果句柄使用不当，Envoy将会失败。

支持以下流处理方法：

  • headers()

    1. headers = handle:headers()

    返回流的头部对象。只要头部还没有被发送到下一个过滤器的头部链中，该头部就可以被修改。例如，可以在httpCall()之后或在body()调用返回之后修改它们。如果在任何其他情况下修改了头部，脚本将会失败。

    返回一个头部对象。

  • body()

    1. body = handle:body()

    返回流的主体（body）。这个调用将使的Envoy切换（yield）脚本，直到整个主体被缓冲。请注意，所有缓冲必须遵守流量控制政策。Envoy不会缓冲超过连接管理器所允许的数据范围。

    返回一个缓冲对象。

  • bodyChunks()

    1. iterator = handle:bodyChunks()

    返回一个迭代器，它可以用来迭代所有接收到的正文数据块。Envoy将在处理大块数据时，切换(yield)脚本，但不会缓冲它们。这可以用来检查数据流。

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

    每次迭代器返回都是一个缓冲对象。

  • trailers()

    1. trailers = handle:trailers()

    返回流的尾部。如果没有尾部，可能会返回零。尾部在发送到下一个过滤器之前可能会被修改。

    返回一个头标对象。

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

    使用Envoy的应用程序日志记录消息。参数message是需要记录的字符串。

  • httpCall()

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

    对上游主机进行HTTP调用。Envoy将切换脚本，直到调用完成或有错误。cluster是对应到群集管理器配置的群集字符串。headers是要发送的key/value键值对的列表。请注意，必须设置:method，:path和:authority头部。body是可选字符串，需要发送的数据主体。timeout是一个整数，指定以毫秒为单位的调用超时。

    返回是响应的headers，以及其body字符串。如果没有主体可能是null。

  • respond()

    1. handle:respond(headers, body)

    立即作出响应，不要进行进一步的过滤器迭代。此调用仅在请求流中有效。此外，只有在请求头还没有传递给后续过滤器的情况下，响应才是可能的。意思是，下面的Lua代码是错误的：

    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是要发送的键值对的列表。请注意，必须设置:status头部。body是一个字符串，作为可选的响应主体，可能是nil。

头部对象API

  • add()

    1. headers:add(key, value)

    为头部对象添加一个头部。key是提供头部键的字符串。value是一个提供头部值的字符串。

  • get()

    1. headers:get(key)

    获取头部对象头部值，参数key为所对应的头部键。返回一个字符串作为头部值，如果没有这样的头部则返回nil。

  • __pairs()

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

    遍历每个头部键。返回的key是头部键的字符串。返回的value是对应的头部值字符串。

    注意：在当前的实现中，在迭代期间不能修改头部。 另外，如果需要在迭代之后修改头部，则必须完成迭代。意味着，不要使用break或其他机制提前退出循环。但这可能会在未来版本中解除这个限制。

  • remove()

    1. headers:remove(key)

    删除头部键值对。入参key对应的头部键值将会被删除。

缓存API

  • length()

    1. size = buffer:length()

    获取缓冲区的大小（以字节为单位）。返回一个整数。

  • getBytes()

    1. buffer:getBytes(index, length)

    从缓冲区获取字节。默认情况下，Envoy不会将所有缓冲区字节复制到Lua中。这将导致一个缓冲区段被复制。index是一个整数，并提供要复制的缓冲区起始索引。length是一个整数并提供要复制的缓冲区长度。index+length必须小于缓冲区长度。

返回