Nginx + WebAssembly
This module enables the embedding of WebAssembly runtimes inside of Nginx and aims at offering several host SDK abstractions for the purpose of extending and/or introspecting the Nginx web-server/proxy runtime.
Currently, the module implements a Proxy-Wasm host ABI, which allows the use of client SDKs written in multiple languages, such as Rust and Go. Proxy-Wasm ("WebAssembly for Proxies") is an emerging standard for Wasm filters, adopted by API Gateways such as Kong and Envoy.
WasmX aims at extending Nginx for the modern Web infrastructure. This includes supporting WebAssembly runtimes & SDKs (by way of ngx_wasm_module), and generally increasing the breadth of features relied upon by the API Gateway use-case (i.e. reverse-proxying). See CONTRIBUTING.md for additional background and roadmap information.
# nginx.conf
events {}
# nginx master process gets a default 'main' VM
# a new top-level configuration block receives all configuration for this main VM
wasm {
# [name] [path.{wasm,wat}]
module my_filter /path/to/filter.wasm;
module my_module /path/to/module.wasm;
}
# each nginx worker process is able to instantiate wasm modules in its subsystems
http {
server {
listen 9000;
location / {
# execute a proxy-wasm filter when proxying
# [module]
proxy_wasm my_filter;
# execute more WebAssembly during the access phase
# [phase] [module] [function]
wasm_call access my_module check_something;
proxy_pass ...;
}
}
# other directives
wasm_socket_connect_timeout 60s;
wasm_socket_send_timeout 60s;
wasm_socket_read_timeout 60s;
wasm_socket_buffer_size 8k;
wasm_socket_large_buffers 32 16k;
}Several "showcase filters" are provided as examples by authors of this module:
- proxy-wasm-rust-filter-echo: An httpbin/echo filter.
- proxy-wasm-rust-rate-limiting: Kong Gateway inspired rate-limiting in Rust.
- proxy-wasm-go-rate-limiting: Kong Gateway inspired rate-limiting in Go.
- proxy-wasm-assemblyscript-rate-limiting: Kong Gateway inspired rate-limiting in AssemblyScript.
More examples are available for each Proxy-Wasm SDK:
Note that all of the above examples may not yet be compatible with ngx_wasm_module.
Last but not least, the WebAssembly Hub contains many other Proxy-Wasm filters, some of which may not yet be compatible with ngx_wasm_module.
See the user documentation for resources on this module's usage.
Releases are published in three distinct release channels:
- Release: Stable releases. A prerelease is considered stable and promoted to a release based on usage mileage and feedback.
- Prerelease: Unstable releases. All new release versions (e.g.
release-1.0.0) are first introduced through prereleases (i.e.prerelease-1.0.0-beta1) before being promoted to a stable release. - Nightly: Releases cut from the latest
mainbranch. Presently, nightly releases are built every Monday. The release interval may change in the future. See the Nightly release tag to download released artifacts.
Each release channel produces the following artifacts for each release:
ngx_wasm_module-$release.tar.gz: a tarball of the ngx_wasm_module release. To be compiled alongside Nginx with--add-module=or--add-dynamic-module=.wasmx-$release-$runtime-$arch-$os.tar.gz: a pre-compilednginxexecutable built with ngx_wasm_module for the specified runtime/architecture/OS. Download these releases and instantly use thenginxbinary.
See the installation documentation for instructions on how to install this module or use one of the binary releases.
See the developer documentation for developer resources on building this module from source and other general development processes.
See a term you are unfamiliar with? Consult the code lexicon.
For a primer on the code's layout and architecture, see the code layout section.
The Proxy-Wasm SDK is the initial focus of WasmX/ngx_wasm_module development and is still a work in progress. You can browse PROXY_WASM.md for a guide on Proxy-Wasm support in ngx_wasm_module.
For a reliable resource in an evolving ABI specification, you may also wish to consult the SDK source of the language of your choice in the Proxy-Wasm SDKs list.
- WebAssembly Specification (Wasm): https://webassembly.github.io/spec/core/index.html
- WebAssembly System Interface (WASI): https://github.com/WebAssembly/WASI
- WebAssembly text format (
.wat): https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format
- Wasm C API: https://github.com/WebAssembly/wasm-c-api
- Wasmer C API: https://docs.rs/wasmer-c-api/
- Wasmtime C API: https://docs.wasmtime.dev/c-api/
- V8 embedding: https://v8.dev/docs/embed
Copyright 2020-2024 Kong Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent