Status
This library is under construction. See #25 to know the progress.
Description
A Nginx module which tries to implement proxy wasm ABI in Nginx. The Wasm integration of Apache APISIX is powered by this module.
Install dependencies
- Download the wasmtime C API package and rename it to
wasmtime-c-api/, with the./install-wasmtime.sh. Remember to add thewasmtime-c-api/libto the library search path when you build Nginx, for instance,
export wasmtime_prefix=/path/to/wasm-nginx-module/wasmtime-c-api
./configure ... \
--with-ld-opt="-Wl,-rpath,${wasmtime_prefix}/lib" \
Directives
wasm_vm
syntax: wasm_vm wasmtime
default: -
context: http
Select the Wasm VM. Currently, only wasmtime is supported. If the directive is not set, the Wasm VM won't be enabled.
Methods
Remember to set the wasm_vm directive!
load
syntax: plugin, err = proxy_wasm.load(name, path)
Load a .wasm file from the filesystem and return a Wasm plugin.
local plugin, err = proxy_wasm.load("plugin","t/testdata/plugin_lifecycle/main.go.wasm")on_configure
syntax: plugin_ctx, err = proxy_wasm.on_configure(plugin, conf)
Create a plugin ctx with the given plugin and conf.
local plugin, err = proxy_wasm.load("plugin","t/testdata/plugin_lifecycle/main.go.wasm")
if not plugin then
ngx.log(ngx.ERR, "failed to load wasm ", err)
return
end
local ctx, err = wasm.on_configure(plugin, '{"body":512}')
if not ctx then
ngx.log(ngx.ERR, "failed to create plugin ctx ", err)
return
endon_http_request_headers
syntax: ok, err = proxy_wasm.on_http_request_headers(plugin_ctx)
Run the HTTP request headers filter in the plugin of the given plugin ctx.
local plugin, err = proxy_wasm.load("plugin","t/testdata/plugin_lifecycle/main.go.wasm")
if not plugin then
ngx.log(ngx.ERR, "failed to load wasm ", err)
return
end
local ctx, err = wasm.on_configure(plugin, '{"body":512}')
if not ctx then
ngx.log(ngx.ERR, "failed to create plugin ctx ", err)
return
end
assert(wasm.on_http_request_headers(ctx))on_http_request_body
syntax: ok, err = proxy_wasm.on_http_request_body(plugin_ctx, body, end_of_body)
Run the HTTP request body filter in the plugin of the given plugin ctx.
local plugin, err = proxy_wasm.load("plugin","t/testdata/plugin_lifecycle/main.go.wasm")
if not plugin then
ngx.log(ngx.ERR, "failed to load wasm ", err)
return
end
local ctx, err = wasm.on_configure(plugin, '{"body":512}')
if not ctx then
ngx.log(ngx.ERR, "failed to create plugin ctx ", err)
return
end
-- get_body is a utility method to get the whole request body
local body = request.get_body()
-- if the body is not the whole request body, for example, it comes from
-- lua-resty-upload, remember to set end_of_body to false
assert(wasm.on_http_request_body(ctx, body, true))on_http_response_headers
syntax: ok, err = proxy_wasm.on_http_response_headers(plugin_ctx)
Run the HTTP response headers filter in the plugin of the given plugin ctx.
local plugin, err = proxy_wasm.load("plugin","t/testdata/http_lifecycle/main.go.wasm")
if not plugin then
ngx.log(ngx.ERR, "failed to load wasm ", err)
return
end
local ctx, err = wasm.on_configure(plugin, '{"body":512}')
if not ctx then
ngx.log(ngx.ERR, "failed to create plugin ctx ", err)
return
end
assert(wasm.on_http_response_headers(ctx))on_http_response_body
syntax: ok, err = proxy_wasm.on_http_response_body(plugin_ctx)
Run the HTTP response body filter in the plugin of the given plugin ctx.
This method need to be called in body_filter_by_lua phase and may be run
multiple times.
local plugin, err = proxy_wasm.load("plugin","t/testdata/http_lifecycle/main.go.wasm")
if not plugin then
ngx.log(ngx.ERR, "failed to load wasm ", err)
return
end
local ctx, err = wasm.on_configure(plugin, '{"body":512}')
if not ctx then
ngx.log(ngx.ERR, "failed to create plugin ctx ", err)
return
end
assert(wasm.on_http_response_body(ctx))proxy-wasm ABI
Implemented proxy-wasm ABI can be found in proxy_wasm_abi.