{"id":15176365,"url":"https://github.com/nginx/unit-wasm","last_synced_at":"2025-10-13T04:35:27.884Z","repository":{"id":186129182,"uuid":"667504993","full_name":"nginx/unit-wasm","owner":"nginx","description":"Development libraries for writing WebAssembly modules for NGINX Unit","archived":false,"fork":false,"pushed_at":"2025-05-20T18:11:52.000Z","size":158,"stargazers_count":40,"open_issues_count":4,"forks_count":8,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-06-06T05:03:15.120Z","etag":null,"topics":["c","library","nginx","nginx-unit","rust","wasm","webassembly"],"latest_commit_sha":null,"homepage":"https://unit.nginx.org/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nginx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-17T16:51:28.000Z","updated_at":"2025-05-20T18:11:55.000Z","dependencies_parsed_at":"2024-01-11T06:38:03.946Z","dependency_job_id":"fe5b2436-81ca-435e-805e-41f4e896e496","html_url":"https://github.com/nginx/unit-wasm","commit_stats":null,"previous_names":["nginx/unit-wasm"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nginx/unit-wasm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Funit-wasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Funit-wasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Funit-wasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Funit-wasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nginx","download_url":"https://codeload.github.com/nginx/unit-wasm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Funit-wasm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013683,"owners_count":26085390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","library","nginx","nginx-unit","rust","wasm","webassembly"],"created_at":"2024-09-27T13:03:20.005Z","updated_at":"2025-10-13T04:35:27.844Z","avatar_url":"https://github.com/nginx.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C \u0026 Rust Library \u0026 Examples for Building WebAssembly Modules for NGINX Unit\n\nThis provides a C library (lbunit-wasm) and Rust crates based on that library\nto aid in the creation of WebAssembly modules in C and Rust.\n\nIt also has some demo WebAssembly modules written in C and Rust.\n\n1. [C \u0026 Rust Library \u0026 Examples for Building WebAssembly Modules for NGINX Unit](#c---rust-library---examples-for-building-webassembly-modules-for-nginx-unit)\n2. [Repository Layout](#repository-layout)\n3. [Setup a Suitable Environment](#setup-a-suitable-environment)\n    1. [Fedora](#fedora)\n    2. [Debian / Ubuntu](#debian--ubuntu)\n4. [Quickstart in Developing Rust WebAssembly Modules for Unit](#quickstart-in-developing-rust-webassembly-modules-for-unit)\n5. [Working With the Repository](#working-with-the-repository)\n6. [Using With Unit](#using-with-unit)\n7. [Consuming the C Library](#consuming-the-c-library)\n8. [License](#license)\n\n## Repository Layout\n\n**src/c** contains the main libunit-wasm library.\n\n**src/rust** contains the rust version of the above.\n\n**examples/c** contains some demo WebAssembly modules that show both the raw\ninterface to Unit (\\*-raw.c) and also the use of libunit-wasm (luw-\\*.c).\n\n**examples/rust** contains rust versions of the above C demo modules and more.\n\n**examples/docker** contains docker files for building Unit with WebAssembly\nsupport and the C examples.\n\n## Setup a Suitable Environment\n\nTo make full use of this repository you will require numerous tools/packages.\n\nExactly what you need and how to get it will depend on your Operating System.\n\nThis has been primarily developed and tested on Fedora \u0026 Ubuntu Linux.\n\n### Fedora\n\nOn Fedora make sure you have the following installed\n\n```\n# dnf install make clang llvm compiler-rt lld wasi-libc-devel \\\n              wasi-libc-static cargo rust rustfmt rust-std-static \\\n              rust-std-static-wasm32-unknown-unknown \\\n              rust-std-static-wasm32-wasi\n```\n\nOne last item you will need is the libclang wasm32-wasi runtime library, this\ncan be done with\n\n```\n# wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/libclang_rt.builtins-wasm32-wasi-20.0.tar.gz | tar --strip-components=1 -xvzf - -C $(dirname $(clang -print-runtime-dir))\n```\n\nThis will install the following, path may vary slightly\n\n```\n/usr/lib64/clang/16/lib/wasi/libclang_rt.builtins-wasm32.a\n```\n\nThe above should also work (perhaps with slight alterations) on recent\nCentOS/RHEL etc...\n\n**NOTE:** If you get a major Clang version update, you may need to repeat\nthat last task.\n\n### Debian / Ubuntu\n\nInstall the following as normal\n\n```\n# apt install wasi-libc make clang llvm lld\n```\n\nFor the rest you will likely need to use [rustup](https://rustup.rs). Caveat\nEmptor.\n\nAfter you've completed the _rustup_ installation by following the on screen\ninstructions as yourself (defaults are fine), do the following\n\n```shell\n$ rustup target add wasm32-wasi\n```\n\nYou will also need to grab the wasi-sysroot, this is essentially a C library\ntargeting WebAssembly (it is based partly on cloudlibc and musl libc) and\nis required for building server side WebAssembly modules.\n\nIt's up to you where you put this.\n\n```shell\n$ wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/wasi-sysroot-20.0.tar.gz | tar -xzf -\n```\n\nAnd finally similarly as Fedora (this requires a recentish clang)\n\n```\n# wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/libclang_rt.builtins-wasm32-wasi-20.0.tar.gz | tar --strip-components=1 -xvzf - -C $(dirname $(clang -print-runtime-dir))\n```\n\n## Quickstart in Developing Rust WebAssembly Modules for Unit\n\n1) Setup a suitable build environment as above.\n\n2) Create a new rust project\n\n```shell\n$ cargo init --lib my-wasm-example\n```\n\n3) Add the [unit-wasm crate](https://crates.io/crates/unit-wasm) as dependency\n\n```shell\n$ cd my-wasm-example\n$ cargo add unit-wasm\n```\n\n4) Set the crate type\n\n```shell\n$ printf '\\n[lib]\\ncrate-type = [\"cdylib\"]\\n' \u003e\u003eCargo.toml\n```\n\n5) Create an example application\n\nTo do this you can simply take a copy of our echo-request demo in this\nrepository\n\n```shell\n$ wget -O src/lib.rs https://raw.githubusercontent.com/nginx/unit-wasm/main/examples/rust/echo-request/src/lib.rs\n```\n\n6) Build it!\n\n```shell\n$ cargo build --target wasm32-wasi\n```\n\nYou should now have a *target/wasm32-wasi/debug/my_wasm_example.wasm* file\n(yes, hyphens will be turned to underscores)\n\nYou can now use this in Unit with the following config\n\n```JSON\n{\n    \"listeners\": {\n        \"[::1]:8888\": {\n            \"pass\": \"applications/my-wasm-example\"\n        }\n    },\n\n    \"applications\": {\n        \"my-wasm-example\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/my-wasm-example/target/wasm32-wasi/debug/my_wasm_example.wasm\",\n            \"request_handler\": \"uwr_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\",\n            \"module_init_handler\": \"uwr_module_init_handler\",\n            \"module_end_handler\": \"uwr_module_end_handler\"\n        }\n    }\n}\n```\n\nand curl command\n\n```shell\n$ curl http://localhost:8888/\n```\n\n7) Start writing your own Wasm modules in Rust!\n\nTo help you get started, you can check out the Rust examples under\n[examples/rust](https://github.com/nginx/unit-wasm/tree/main/examples/rust)\nand also the\n[API-Rust.md](https://github.com/nginx/unit-wasm/blob/main/API-Rust.md)\nfor an overview of the API.\n\n## Working With the Repository\n\nThe project uses good old _make(1)_ as the build system.\n\nTyping _make help_ will show the list of available targets and the various\nmake variables you can set. E.g\n\n```\n$ make help\nAvailable Targets:\n  default /\n  libunit-wasm   - Builds libunit-wasm C library\n  examples       - Builds the above as well as C examples\n  examples-raw   - Builds raw (non libunit-wasm) C examples\n  rust           - Builds the libunit-wasm rust crate\n  examples-rust  _ Builds the above and rust examples\n  all            - Builds all the above\n  docker         - Builds demo docker images\n  clean          - Removes auto generated artifacts\n  tags           - Generate ctags\n\nVariables:\n  make CC=            - Specify compiler to use\n                        Defaults to clang\n  make WASI_SYSROOT=  - Specify the path to the WASI sysroot\n                        Defaults to autodetected\n  make V=1            - Enables verbose output\n  make D=1            - Enables debug builds (-O0)\n  make E=1            - Enables Werror\n```\n\nIf you have previously followed the steps outlined above in\n[Setup a Suitable Environment](#setup-a-suitable-environment)\n\nYou can build the libunit-wasm C library, C example Wasm modules, the Rust\ncrates that provides Rust bindings for the libunit-wasm and the Rust example\nWasm modules.\n\nE.g\n\n```shell\n$ make                  # Build just the C library\n$ make examples         # Build the C library and C examples\n$ make rust             # Build the Rust crates\n$ make examples-rust    # Build the Rust examples\n$ make all              # Build all the above\n```\n\nThe C and Rust example Wasm modules will be located at\n\n```\nexamples/c/luw-echo-request.wasm\nexamples/c/luw-upload-reflector.wasm\nexamples/rust/echo-request/target/wasm32-wasi/debug/rust_echo_request.wasm\nexamples/rust/hello-world/target/wasm32-wasi/debug/rust_hello_world.wasm\nexamples/rust/upload-reflector/target/wasm32-wasi/debug/rust_upload_reflector.wasm\n```\n\n**NOTE:** To build the C library and examples you will need to specify the\nwasi-sysroot.\n\nE.g\n\n```shell\n$ make WASI_SYSROOT=/path/to/wasi-sysroot all\n```\n\n**However** if you are on Fedora and installed the _wasi-*_ packages listed\nabove in the [Setup a Suitable Environment](#fedora) then the wasi-sysroot\npath will be autodetected and set by the Makefile. You can override the\nautodetection by explicitly specifying it as above.\n\n## Using With Unit\n\nIf you have all the above built, you are now ready to test it out with Unit.\n\nWe won't go into the details of building Unit from source and enabling the Unit\nWebAssembly language module here (see the\n[HOWTO.md](https://github.com/nginx/unit-wasm/blob/main/HOWTO.md) in the\nrepository root for more details) but will instead assume you already have a\nUnit with the WebAssembly language module already running, perhaps installed\nvia a package.\n\nCreate the following Unit config (editing the module paths as appropriate)\n\n```JSON\n{\n    \"listeners\": {\n        \"[::1]:8888\": {\n            \"pass\": \"routes\"\n        }\n    },\n\n    \"settings\": {\n        \"http\": {\n            \"max_body_size\": 8589934592\n        }\n    },\n\n    \"routes\": [\n        {\n            \"match\": {\n                \"uri\": \"/echo*\"\n            },\n            \"action\": {\n                \"pass\": \"applications/luw-echo-request\"\n            }\n        },\n        {\n            \"match\": {\n                \"uri\": \"/upload*\"\n            },\n            \"action\": {\n                \"pass\": \"applications/luw-upload-reflector\"\n            }\n        },\n        {\n            \"match\": {\n                \"uri\": \"/large-upload*\"\n            },\n            \"action\": {\n                \"pass\": \"applications/large-upload\"\n            }\n        },\n        {\n            \"match\": {\n                \"uri\": \"/rust-echo*\"\n            },\n            \"action\": {\n                \"pass\": \"applications/rust-echo-request\"\n            }\n        },\n        {\n            \"match\": {\n                \"uri\": \"/rust-upload*\"\n            },\n            \"action\": {\n                \"pass\": \"applications/rust-upload-reflector\"\n            }\n        },\n        {\n            \"match\": {\n                \"uri\": \"/rust-large-upload*\"\n            },\n            \"action\": {\n                \"pass\": \"applications/rust-large-upload\"\n            }\n        },\n        {\n            \"match\": {\n                \"uri\": \"/rust-hello-world*\"\n            },\n            \"action\": {\n                \"pass\": \"applications/rust-hello-world\"\n            }\n        }\n    ],\n\n    \"applications\": {\n        \"luw-echo-request\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/unit-wasm/examples/c/luw-echo-request.wasm\",\n            \"request_handler\": \"luw_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\",\n            \"module_init_handler\": \"luw_module_init_handler\",\n            \"module_end_handler\": \"luw_module_end_handler\"\n        },\n        \"luw-upload-reflector\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/unit-wasm/examples/c/luw-upload-reflector.wasm\",\n            \"request_handler\": \"luw_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\",\n            \"request_end_handler\": \"luw_request_end_handler\",\n            \"response_end_handler\": \"luw_response_end_handler\"\n        },\n        \"large-upload\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/unit-wasm/examples/c/large-upload.wasm\",\n            \"request_handler\": \"luw_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\",\n            \"module_init_handler\": \"luw_module_init_handler\",\n            \"module_end_handler\": \"luw_module_end_handler\",\n            \"response_end_handler\": \"luw_response_end_handler\",\n            \"access\": {\n                \"filesystem\": [\n                    \"/var/tmp\"\n                ]\n            }\n        },\n        \"rust-echo-request\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/unit-wasm/examples/rust/echo-request/target/wasm32-wasi/debug/rust_echo_request.wasm\",\n            \"request_handler\": \"uwr_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\",\n            \"module_init_handler\": \"uwr_module_init_handler\",\n            \"module_end_handler\": \"uwr_module_end_handler\"\n        },\n        \"rust-upload-reflector\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/unit-wasm/examples/rust/upload-reflector/rust_upload_reflector.wasm\",\n            \"request_handler\": \"uwr_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\",\n            \"request_end_handler\": \"uwr_request_end_handler\",\n            \"response_end_handler\": \"uwr_response_end_handler\"\n        },\n        \"rust-large-upload\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/src/unit-wasm/examples/rust/large-upload/target/wasm32-wasi/debug/rust_large_upload.wasm\",\n            \"request_handler\": \"uwr_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\",\n            \"module_init_handler\": \"uwr_module_init_handler\",\n            \"module_end_handler\": \"uwr_module_end_handler\",\n            \"response_end_handler\": \"uwr_response_end_handler\",\n            \"access\": {\n                \"filesystem\": [\n                    \"/var/tmp\"\n                ]\n            }\n        },\n        \"rust-hello-world\": {\n            \"type\": \"wasm\",\n            \"module\": \"/path/to/unit-wasm/examples/rust/hello-world/target/wasm32-wasi/debug/rust_hello_world.wasm\",\n            \"request_handler\": \"uwr_request_handler\",\n            \"malloc_handler\": \"luw_malloc_handler\",\n            \"free_handler\": \"luw_free_handler\"\n        }\n    }\n}\n```\n\nLoad this config then you should be ready to try it.\n\n```\n$ curl -X POST -d \"Hello World\" --cookie \"mycookie=hmmm\" http://localhost:8888/echo/?q=a\n *** Welcome to WebAssembly on Unit! [libunit-wasm (0.1.0/0x00010000)] ***\n\n[Request Info]\nREQUEST_PATH = /echo/?q=a\nMETHOD       = POST\nVERSION      = HTTP/1.1\nQUERY        = q=a\nREMOTE       = ::1\nLOCAL_ADDR   = ::1\nLOCAL_PORT   = 8080\nSERVER_NAME  = localhost\n\n[Request Headers]\nHost = localhost:8080\nUser-Agent = curl/8.0.1\nAccept = */*\nCookie = mycookie=hmmm\nContent-Length = 11\nContent-Type = application/x-www-form-urlencoded\n\n[POST data]\nHello World\n```\n\n```\n$ curl -v -X POST --data-binary @audio.flac -H \"Content-Type: audio/flac\" http://localhost:8888/upload-reflector/ -o wasm-test.dat\n...\n\u003e Content-Type: audio/flac\n\u003e Content-Length: 60406273\n...\n  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n                                 Dload  Upload   Total   Spent    Left  Speed\n100  115M  100 57.6M  100 57.6M  47.6M  47.6M  0:00:01  0:00:01 --:--:-- 95.2M\n...\n\u003c Content-Type: audio/flac\n\u003c Content-Length: 60406273\n...\n$ sha1sum audio.flac wasm-test.dat\nef5c9c228544b237022584a8ac4612005cd6263e  audio.flac\nef5c9c228544b237022584a8ac4612005cd6263e  wasm-test.dat\n```\n\n## Consuming the C Library\n\nIf **unit/unit-wasm.h** and **libunit.a** are installed into standard\ninclude/library directories then\n\nInclude the libunit-wasm header file\n\n```C\n....\n#include \u003cunit/unit-wasm.h\u003e\n...\n```\n\nLink against libunit-wasm\n\n```shell\n$ clang ... -o myapp.wasm myapp.c -lunit-wasm\n```\n\nSee [API-C.md](https://github.com/nginx/unit-wasm/blob/main/API-C.md) for an\noverview of the API.\n\n## License\n\nThis project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx%2Funit-wasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnginx%2Funit-wasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx%2Funit-wasm/lists"}