Repository files navigation

Nginx + WebAssembly

This module enables the embedding ofWebAssembly runtimes inside ofNginx and aims at offering several host SDK abstractionsfor the purpose of extending and/or introspecting the Nginx web-server/proxyruntime.

Currently, the module implements aProxy-Wasmhost ABI, which allows the use of client SDKs written in multiple languages,such asRustandGo. Proxy-Wasm("WebAssembly for Proxies") is an emerging standard for Wasm filters,adopted by API Gateways such asKongandEnvoy.

WasmX aims at extending Nginx for the modern Web infrastructure. This includessupporting WebAssembly runtimes & SDKs (by way of ngx_wasm_module), andgenerally increasing the breadth of features relied upon by the API Gatewayuse-case (i.e. reverse-proxying). SeeCONTRIBUTING.mdfor additional background and roadmap information.

• Synopsis
• Examples
• Documentation
  • Usage
  • Installation
  • Development
  • Proxy-Wasm SDK
  • WebAssembly
  • WebAssembly Runtimes
• License

# nginx.confevents {}# nginx master process gets a default 'main' VM# a new top-level configuration block receives all configuration for this main VMwasm {#      [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 subsystemshttp {server {listen9000;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 directiveswasm_socket_connect_timeout 60s;wasm_socket_send_timeout    60s;wasm_socket_read_timeout    60s;wasm_socket_buffer_size     8k;wasm_socket_large_buffers   3216k;}

Back to TOC

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:

• AssemblyScriptexamples (temporary SDK fork)
• C++examples
• Go (TinyGo)examples
• Rustexamples

Note that all of the above examples may not yet be compatible withngx_wasm_module.

Last but not least, theWebAssemblyHub contains many other Proxy-Wasmfilters, some of which may not yet be compatible with ngx_wasm_module.

Back to TOC

See theuser documentation for resources on this module'susage.

Back to TOC

Releases are published in three distinct release channels:

• Release: Stable releases. Aprerelease is considered stable and promotedto arelease 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 latestmain branch. Presently, nightlyreleases are built every Monday. The release interval may change in thefuture. See theNightly releasetag to downloadreleased 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-compilednginx executablebuilt with ngx_wasm_module for the specified runtime/architecture/OS. Downloadthese releases and instantly use thenginx binary.

See theinstallation documentation for instructions on how toinstall this module or use one of the binary releases.

Back to TOC

See thedeveloper documentation for developer resources onbuilding this module from source and other general development processes.

See a term you are unfamiliar with? Consult thecodelexicon.

For a primer on the code's layout and architecture, see thecodelayout section.

Back to TOC

TheProxy-Wasm SDK is the initial focus ofWasmX/ngx_wasm_module development and is still a work in progress. You canbrowsePROXY_WASM.md for a guide on Proxy-Wasm support inngx_wasm_module.

For a reliable resource in an evolving ABI specification, you may also wish toconsult the SDK source of the language of your choice in theProxy-Wasm SDKslist.

Back to TOC

• 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

Back to TOC

• 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

Back to TOC

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.0Unless required by applicable law or agreed to in writing, softwaredistributed 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 andlimitations under the License.

Back to TOC