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

-- 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必须小于缓冲区长度。

返回

results matching ""

    No results matching ""