Lua

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。

-- 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 a response header with the 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"
  },
  "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

流处理API

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

function envoy_on_request(request_handle)
end

function envoy_on_response(response_handle)
end

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

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

支持以下流处理方法：

• headers()

  headers = handle:headers()

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

  返回一个头部对象。
• body()

  body = handle:body()

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

  返回一个缓冲对象。
• bodyChunks()

  iterator = handle:bodyChunks()

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

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

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

  trailers = handle:trailers()

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

  返回一个头标对象。
• log*()

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

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

• httpCall()

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

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

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

• respond()

  handle:respond(headers, body)

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

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

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

头部对象API

• add()

  headers:add(key, value)

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

• get()

  headers:get(key)

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

• __pairs()

  for key, value in pairs(headers) do
  end

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

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

• remove()

  headers:remove(key)

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

缓存API

• length()

  size = buffer:length()

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

• getBytes()

  buffer:getBytes(index, length)

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

返回

• 上一级
• 首页目录