• Lua
    • 概述
    • 目前支持高级功能
    • 配置
    • 脚本示例
    • 流处理API
    • 头部对象API
    • 缓存API
  • 返回

    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响应代码进行响应。

    配置

    • v1 API 参考
    • v2 API 参考

    脚本示例

    本节提供了一些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必须小于缓冲区长度。

    返回

    • 上一级
    • 首页目录