---
title: "How Apache APISIX Enables Wasm Functionality - API7.ai"
description: "APISIX supports Wasm at the gateway level, allowing developers to use high-level programming languages to create Wasm plugins."
url: "https://api7.ai/blog/how-apisix-supports-wasm"
---

[Blog](https://api7.ai/blog)

[Products](https://api7.ai/category/products)[Technology](https://api7.ai/category/technology)[Ecosystem](https://api7.ai/category/ecosystem)[Case Study](https://api7.ai/category/usercase)[Team & Community](https://api7.ai/category/community)

Search

⌘ + K

[Blog](https://api7.ai/blog)

Products

# How Apache APISIX Enables Wasm Functionality

Xinxin Zhu

April 7, 2023

[Products](https://api7.ai/category/products)

> To enable high-performance applications to run in web browsers, Apache APISIX supports Wasm at the gateway level, a binary instruction format that enables efficient and secure execution of code on the web. Consequently, developers can use high-level programming languages such as C/C++/Go/Rust and adhere to the proxy-wasm specification to create Wasm plugins. The proxy-wasm specification ensures compatibility and interoperability with other systems. Let's get into this article and learn more details.

## What is Wasm

[WebAssembly](http://webassembly.org/) (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine.

Prior to the emergence of Wasm, only Javascript could be executed in web browsers. However, with the introduction of Wasm, high-level languages like C/C++/Golang can now be run in web browsers. Major browsers such as Chrome, Firefox, and Safari now all support Wasm. Moreover, due to the advancements made by the WASI (the WebAssembly System Interface) project, server-side environments can also support the execution of Wasm instructions.

At present, Apache APISIX supports Wasm at the gateway level. Developers can use high-level programming languages such as C/C++/Go/Rust and adhere to the [proxy-wasm](https://github.com/proxy-wasm/spec) specification to create Wasm plugins.

![wasm](https://static.api7.ai/uploads/2023/03/10/6ZI9czxe_whiteboard_exported_image.jpeg?imageMogr2/format/webp)

## Why Does APISIX Support Wasm Plugins?

Compared to native Lua plugins, Wasm plugins offer several advantages:

- Scalability: By supporting Wasm, APISIX can utilize the SDK provided by proxy-wasm to develop plugins in high-level programming languages such as C++, Golang, and Rust. These languages often have richer ecosystems, allowing developers to implement more feature-rich plugins.
- Security: Since the interaction between APISIX and Wasm relies on the Application Binary Interface (ABI) provided by proxy-wasm, this access is more secure. Wasm plugins can only make specific modifications to requests, ensuring that they cannot perform malicious actions. Furthermore, since Wasm plugins run in a separate VM, even if the plugin crashes, it will not affect the main APISIX process.

## How Does APISIX Support Wasm?

Now that we understand what Wasm is, let's take a top-down look at how APISIX supports Wasm plugins.

![apisix-wasm](https://static.api7.ai/uploads/2023/03/10/5t9ZpK7P_apisx-wasm.jpeg?imageMogr2/format/webp)

### APISIX Wasm Plugins

APISIX allows developers to create plugins using popular high-level programming languages such as C/C++, Go, and Rust. These plugins can be built using the corresponding SDK and following the proxy-wasm specification.

> proxy-wasm is a specification for ABIs between L4/L7 proxies, introduced by Envoy. This specification defines ABIs including memory management, L4 proxy, and L7 proxy extensions. For example, in HTTP(L7), the proxy-wasm specification defines ABIs such as proxy\_on\_http\_request\_headers, proxy\_on\_http\_request\_body, proxy\_on\_http\_request\_trailers, and proxy\_on\_http\_response\_headers, allowing modules to retrieve and modify request content at various stages.

For example, we will use Golang and [proxy-wasm-go-sdk](https://github.com/tetratelabs/proxy-wasm-go-sdk) to develop this plugin:

> The proxy-wasm-go-sdk is an SDK for the proxy-wasm specification that helps developers to create proxy-wasm plugins more easily using Golang. However, it's important to note that due to some issues with native Golang's support for WASI, this SDK is implemented based on TinyGo. For more information, you can [click here](https://github.com/tetratelabs/proxy-wasm-go-sdk/blob/main/doc/OVERVIEW.md#tinygo-vs-the-official-go-compiler) to view the details.

This plugin's main function is to modify the HTTP response status code and response body of an HTTP modification request, as referenced from the [APISIX link](https://github.com/apache/apisix/blob/master/t/wasm/fault-injection/main.go).

```
...
func (ctx *pluginContext) OnPluginStart(pluginConfigurationSize int) types.OnPluginStartStatus {
        data, err := proxywasm.GetPluginConfiguration()
        if err != nil {
                proxywasm.LogErrorf("error reading plugin configuration: %v", err)
                return types.OnPluginStartStatusFailed
        }

        var p fastjson.Parser
        v, err := p.ParseBytes(data)
        if err != nil {
                proxywasm.LogErrorf("error decoding plugin configuration: %v", err)
                return types.OnPluginStartStatusFailed
        }
        ctx.Body = v.GetStringBytes("body")
        ctx.HttpStatus = uint32(v.GetUint("http_status"))
        if v.Exists("percentage") {
                ctx.Percentage = v.GetInt("percentage")
        } else {
                ctx.Percentage = 100
        }

        // schema check
        if ctx.HttpStatus < 200 {
                proxywasm.LogError("bad http_status")
                return types.OnPluginStartStatusFailed
        }
        if ctx.Percentage < 0 || ctx.Percentage > 100 {
                proxywasm.LogError("bad percentage")
                return types.OnPluginStartStatusFailed
        }

        return types.OnPluginStartStatusOK
}

func (ctx *httpLifecycle) OnHttpRequestHeaders(numHeaders int, endOfStream bool) types.Action {
        plugin := ctx.parent
        if !sampleHit(plugin.Percentage) {
                return types.ActionContinue
        }

        err := proxywasm.SendHttpResponse(plugin.HttpStatus, nil, plugin.Body, -1)
        if err != nil {
                proxywasm.LogErrorf("failed to send local response: %v", err)
                return types.ActionContinue
        }
        return types.ActionPause
}
...
```

Afterwards, we use TinyGo to compile the above Golang code and generate a `.wasm` file.

```
tinygo build -o wasm_fault_injection.go.wasm -scheduler=none -target=wasi ./main.go
```

After the compilation is completed, we obtain the `fault_injection.go.wasm` file.

> If you're interested in the contents of the wasm file, you can use the [wasm-tool](https://github.com/bytecodealliance/wasm-tools) to view the specific contents of the wasm file. `wasm-tools dump hello.go.wasm`

Configure `wasm_fault_injection.go.wasm` in the `config.yaml` file of APISIX and name the plugin as wasm\_fault\_injection.

```
apisix:
        ...
wasm:
  plugins:
    - name: wasm_fault_injection
      priority: 7997
      file: wasm_fault_injection.go.wasm
```

Afterwards, we start APISIX and create a route that references the Wasm plugin:

```
curl  http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
    "uri":"/*",
    "upstream":{
        "type":"roundrobin",
        "timeout":{
            "connect":1,
            "read":1,
            "send":1
        },
        "nodes":{
            "httpbin.org:80":1
        }
    },
    "plugins":{
        "wasm_fault_injection":{
            "conf":"{\"http_status\":200, \"body\":\"Hello WebAssembly!\n\"}"
        }
    },
    "name":"wasm_fault_injection"
}'
```

After conducting an access test, we found that the response body has been modified to "Hello WebAssembly", indicating that the Wasm plugin is now effective.

```
curl 127.0.0.1:9080/get -v
*   Trying 127.0.0.1:9080...
* Connected to 127.0.0.1 (127.0.0.1) port 9080 (#0)
> GET /get HTTP/1.1
> Host: 127.0.0.1:9080
> User-Agent: curl/7.81.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Thu, 09 Feb 2023 07:46:50 GMT
< Content-Type: text/plain; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Server: APISIX/3.1.0
<
Hello WebAssembly!
```

### Wasm-nginx-module

After learning how Apache APISIX uses Wasm plugins, let's dive deeper into "why can we access and modify request contents in Wasm plugins?"

Since APISIX uses OpenResty as the underlying framework, to be able to access and modify request contents in Wasm plugins, we need to interact with APIs provided by OpenResty or NGINX. This is exactly what `wasm-nginx-module` does.

> wasm-nginx-module is an NGINX module that supports Wasm and was developed by [API7](https://api7.ai/). This module attempts to implement proxy-wasm-abi based on NGINX and encapsulates Lua API, allowing us to complete proxy-wasm-abi calls at the Lua level. For more information, please refer to [wasm-nginx-module](https://github.com/api7/wasm-nginx-module).

For example, when APISIX runs to the **access** phase, it calls the Lua method `on_http_request_headers` provided by `wasm-nginx-module`.

```
-- apisix/wasm.lua
...
local ok, err = wasm.on_http_request_headers(plugin_ctx)
   if not ok then
       core.log.error(name, ": failed to run wasm plugin: ", err)
       return 503
   end
end
...
```

Later in this method, the `ngx_http_wasm_on_http` method provided by `wasm-nginx-module` will be called.

```
ngx_int_t
ngx_http_wasm_on_http(ngx_http_wasm_plugin_ctx_t *hwp_ctx, ngx_http_request_t *r,
                      ngx_http_wasm_phase_t type, const u_char *body, size_t size,
                      int end_of_body)
{
    ...

    ctx = ngx_http_wasm_get_module_ctx(r);

    if (type == HTTP_REQUEST_HEADERS) {
        cb_name = &proxy_on_request_headers;
    } else if (type == HTTP_REQUEST_BODY) {
        cb_name = &proxy_on_request_body;
    } else if (type == HTTP_RESPONSE_HEADERS) {
        cb_name = &proxy_on_response_headers;
    } else {
        cb_name = &proxy_on_response_body;
    }

    if (type == HTTP_REQUEST_HEADERS || type == HTTP_RESPONSE_HEADERS) {
        if (hwp_ctx->hw_plugin->abi_version == PROXY_WASM_ABI_VER_010) {
            rc = ngx_wasm_vm->call(hwp_ctx->hw_plugin->plugin,
                                   cb_name,
                                   true, NGX_WASM_PARAM_I32_I32, http_ctx->id, 0);
        } else {
            rc = ngx_wasm_vm->call(hwp_ctx->hw_plugin->plugin,
                                   cb_name,
                                   true, NGX_WASM_PARAM_I32_I32_I32, http_ctx->id,
                                   0, 1);
        }

    } else {
        rc = ngx_wasm_vm->call(hwp_ctx->hw_plugin->plugin,
                              cb_name,
                              true, NGX_WASM_PARAM_I32_I32_I32, http_ctx->id,
                              size, end_of_body);
    }
    ...
}
```

In `wasm-nginx-module`, we set the `cb_name` based on different stages, such as `HTTP_REQUEST_HEADERS` corresponds to `proxy_on_request_headers`, and then call the method in the VM through `ngx_wasm_vm->call`, which is the `OnHttpRequestHeaders` method of the wasm plugin mentioned earlier in this article.

With this, the entire calling chain of APISIX calling wasm plugin and running Golang is completed. The calling chain is as follows:

### Wasm VM

Wasm VM is a virtual machine that is used to execute Wasm code. `wasm-nginx-module` implements two types of virtual machines, "wasmtime" and "wasmedge", for executing Wasm code. In APISIX, "wasmtime" is the default for running Wasm code.

> [Wasmtime](https://github.com/bytecodealliance/wasmtime) is a fast and secure runtime for WebAssembly and WASI, open-sourced by Bytecode Alliance. It can run WebAssembly code outside the web environment and can be used as a command-line tool or embedded as a WebAssembly runtime engine in other programs as a library. [Wasmedge](https://wasmedge.org/) is a lightweight, high-performance, and scalable WebAssembly (Wasm) virtual machine optimized for edge computing. It can be used for cloud-native, edge, and decentralized applications.

First, in the Wasm VM, we use the `load` method to load the `.wasm` file into memory. After that, we can use the `call` method of the VM to invoke these functions. The VM is based on the WASI interface implementation, which enables Wasm code to not only run on the browser-side but also support running on the server-side.

## Summary

We have gained an understanding of what Wasm is and how APISIX supports Wasm plugins. By offering support for Wasm plugins, APISIX not only enhances its capabilities in supporting multiple languages, such as C++, Rust, Golang, and AssemblyScript for plugin development but also benefits from the extensive ecosystem and use cases of WebAssembly, which is expanding beyond the browser to cloud-native environments.

As a result, APISIX can leverage Wasm to deliver more advanced features on the API gateway side, enabling it to address a wider range of usage scenarios.

Tags:

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[API Gateway Concept](https://api7.ai/tags/api-gateway-concept)

[WebAssembly](https://api7.ai/tags/webassembly)

Share article link

Share

Related Posts

[![Why Is Apache APISIX the Best API Gateway?](https://static.api7.ai/2022/10/03/633a3d046fa57.webp)](https://api7.ai/blog/why-is-apache-apisix-the-best-api-gateway)

## [Why Is Apache APISIX the Best API Gateway?](https://api7.ai/blog/why-is-apache-apisix-the-best-api-gateway)

[![How Does API7 Enterprise Proxy Applications in Kubernetes Clusters?](https://static.api7.ai/uploads/2024/01/27/BxF6o8n4_PA_Cover_ENG.png)](https://api7.ai/blog/api7-enterprise-proxy-applications)

## [How Does API7 Enterprise Proxy Applications in Kubernetes Clusters?](https://api7.ai/blog/api7-enterprise-proxy-applications)

Table of Contents

- [What is Wasm](#what-is-wasm)

- [Why Does APISIX Support Wasm Plugins?](#why-does-apisix-support-wasm-plugins)

- [How Does APISIX Support Wasm?](#how-does-apisix-support-wasm)

  - [APISIX Wasm Plugins](#apisix-wasm-plugins)
  - [Wasm-nginx-module](#wasm-nginx-module)
  - [Wasm VM](#wasm-vm)

- [Summary](#summary)

## Related Posts

[![What Is LuaJIT? Why Does APISIX Choose LuaJIT?](https://static.api7.ai/uploads/2024/09/06/n3fzQtjH_LuaJIT.png)](https://api7.ai/blog/apisix-chooses-luajit)

Products

April 14, 2023

#### [What Is LuaJIT? Why Does APISIX Choose LuaJIT?](https://api7.ai/blog/apisix-chooses-luajit)

APISIX, a cloud-native API gateway, chooses LuaJIT as its technology stack due to its high flexibility and performance.

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[API Gateway Concept](https://api7.ai/tags/api-gateway-concept)

[LuaJIT](https://api7.ai/tags/luajit)

[![Technical Explorations of Open-Source API Gateway Apache APISIX](https://static.api7.ai/2022/10/19/634f6677742a1.png)](https://api7.ai/blog/technical-explorations-of-open-source-api-gateway)

Products

October 24, 2022

#### [Technical Explorations of Open-Source API Gateway Apache APISIX](https://api7.ai/blog/technical-explorations-of-open-source-api-gateway)

By learning the explorations and innovations of Apache APISIX, we can learn about its data center, hot reloading, and dynamic orchestration of plugins.

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[API Gateway Concept](https://api7.ai/tags/api-gateway-concept)

[Technical Trends](https://api7.ai/tags/technical-trends)

[![Apache APISIX 3.0: 11 Highlights of Open Source API Gateway](https://static.api7.ai/2022/10/03/633a3d046fa57.webp)](https://api7.ai/blog/apache-apisix-3-0-11-highlights-of-open-source-api-gateway)

Products

September 22, 2022

#### [Apache APISIX 3.0: 11 Highlights of Open Source API Gateway](https://api7.ai/blog/apache-apisix-3-0-11-highlights-of-open-source-api-gateway)

The open source API Gateway Apache APISIX version 3.0 is coming! We have selected 11 essential features to give a brief overview.

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[API Gateway Concept](https://api7.ai/tags/api-gateway-concept)

[Core Concept](https://api7.ai/tags/core-concept)
