Initial commitv0.1.0

libunit-wasm and example C and Rust WebAssembly modules for NGINX Unit.

Co-developed-by: Timo Stark <t.stark@nginx.com>
Co-developed-by: Liam Crilly <liam@nginx.com>
Signed-off-by: Andrew Clayton <a.clayton@nginx.com>

12 files changed, 168 insertions, 0 deletions

diff --git a/src/rust/.gitignore b/src/rust/.gitignore
new file mode 100644
index 0000000..6c481e2
--- /dev/null
+++ b/src/rust/.gitignore
@@ -0,0 +1,4 @@
+bindings.rs
+Cargo.lock
+
+target/
diff --git a/src/rust/Cargo.toml b/src/rust/Cargo.toml
new file mode 100644
index 0000000..2e0bba2
--- /dev/null
+++ b/src/rust/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "unit-wasm"
+version = "0.1.0"
+authors = ["Timo Stark <t.stark@f5.com>", "Andrew Clayton <a.clayton@f5.com>"]
+description = "WASM SDK for NGINX Unit"
+license = "Apache-2.0"
+keywords = ["nginx", "unit", "wasm", "wasi"]
+
+[lib]
+crate-type = ["rlib"]
+path = "src/lib.rs"
+
+
+[dependencies]
+unit-wasm-sys = { path = "unit-wasm-sys", version = "0.1.1" }
diff --git a/src/rust/Makefile b/src/rust/Makefile
new file mode 100644
index 0000000..d2e705a
--- /dev/null
+++ b/src/rust/Makefile
@@ -0,0 +1,11 @@
+include ../../shared.mk
+
+SDIR = src/rust
+
+rustlib:
+	$(PP_GEN) $(SDIR)/target/wasm32-wasi
+	$(v)cargo build --target=wasm32-wasi
+
+clean:
+	rm -f Cargo.lock unit-wasm-sys/Cargo.lock
+	rm -rf target/ unit-wasm-sys/target/
diff --git a/src/rust/README.md b/src/rust/README.md
new file mode 100644
index 0000000..a48e2cd
--- /dev/null
+++ b/src/rust/README.md
@@ -0,0 +1,18 @@
+# Quickstart in Developing Rust WebAssembly Modules for Unit
+
+The current version is published to crates.io. To get started with the SDK
+include `unit-wasm` as dependency.
+
+```
+cargo add unit-wasm
+```
+
+## Prerequisites
+
+- target add wasm32-wasi. `rustup target add wasm32-wasi`
+
+## From Source
+
+The Rust implementation is in an early stage. If you would like to build the
+crate by yourself, we have to generate the `libunit-wasm` first. This step is
+NOT included in the build process.
diff --git a/src/rust/src/ffi/mod.rs b/src/rust/src/ffi/mod.rs
new file mode 100644
index 0000000..087148a
--- /dev/null
+++ b/src/rust/src/ffi/mod.rs
@@ -0,0 +1,3 @@
+// @todo: Check if this is valid?!
+extern crate unit_wasm_sys;
+pub use self::unit_wasm_sys::*;
diff --git a/src/rust/src/lib.rs b/src/rust/src/lib.rs
new file mode 100644
index 0000000..dface32
--- /dev/null
+++ b/src/rust/src/lib.rs
@@ -0,0 +1,8 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+
+/*
+ * Copyright (C) Timo Stark
+ * Copyright (C) F5, Inc.
+ */
+
+pub mod ffi;
diff --git a/src/rust/unit-wasm-sys/Cargo.toml b/src/rust/unit-wasm-sys/Cargo.toml
new file mode 100644
index 0000000..d8f64a3
--- /dev/null
+++ b/src/rust/unit-wasm-sys/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+name = "unit-wasm-sys"
+version = "0.1.1"
+edition = "2021"
+authors = ["Timo Stark <t.stark@nginx.com>", "Andrew Clayton <a.clayton@nginx.com>"]
+links = "unit-wasm"
+description = "Native bindings for the libunit-wasm C API"
+license = "Apache-2.0"
+keywords = ["nginx", "unit", "ffi", "sys"]
+
+[lib]
+name = "unit_wasm_sys"
+path = "lib.rs"
+crate-type = ["staticlib", "rlib"]
+
+
+[build-dependencies]
+bindgen = "0.66.1"
diff --git a/src/rust/unit-wasm-sys/README.md b/src/rust/unit-wasm-sys/README.md
new file mode 100644
index 0000000..fbc53f0
--- /dev/null
+++ b/src/rust/unit-wasm-sys/README.md
@@ -0,0 +1,4 @@
+# unit-wasm sys crate
+
+The symbolic link is beeing used to share the c code with cargo during
+buildtime.
diff --git a/src/rust/unit-wasm-sys/build.rs b/src/rust/unit-wasm-sys/build.rs
new file mode 100644
index 0000000..bd2ebd5
--- /dev/null
+++ b/src/rust/unit-wasm-sys/build.rs
@@ -0,0 +1,52 @@
+// buildscript for the unit-wasm-sys crate.
+
+use std::env;
+use std::path::{Path, PathBuf};
+
+fn main() {
+    // Tell rustc where to find the libunit-wasm library.
+    let libunit_wasm_dir = "libunit-wasm";
+
+    let dir = env::var("CARGO_MANIFEST_DIR").unwrap();
+
+    // Some generics
+    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-changed=wrapper.h");
+
+    // The rustc-link-search tells Cargo to pass the `-L` flag to the
+    // compiler to add a directory to the library search plugin. The
+    // `native` keyword means "only looking for `native libraries` in
+    // this directory".
+    println!(
+        "cargo:rustc-link-search=native={}",
+        Path::new(&dir).join(libunit_wasm_dir).display()
+    );
+
+    // The rustc-link-lib tells Cargo to link the given library using
+    // the compiler's `-l` flag. This is needed to start building our
+    // FFIs.
+    println!("cargo:rustc-link-lib=static=unit-wasm");
+
+    generate_bindings();
+}
+
+fn generate_bindings() {
+    let wasi_sysroot = "--sysroot=".to_owned() + &env::var("WASI_SYSROOT").unwrap();
+    let bindings = bindgen::Builder::default()
+        // The input header file.
+        .header("libunit-wasm/include/unit/unit-wasm.h")
+        .allowlist_function("^luw_.*")
+        .allowlist_var("^luw_.*")
+        .allowlist_type("^luw_.*")
+        .clang_args(vec![wasi_sysroot]) // Needed for strings.h
+        .generate()
+        .expect("Unable to generate bindings");
+
+    let out_dir_env =
+        env::var("OUT_DIR").expect("The required environment variable OUT_DIR was not set");
+    let out_path = PathBuf::from(out_dir_env);
+
+    bindings
+        .write_to_file(out_path.join("bindings.rs"))
+        .expect("Couldn't write bindings!");
+}
diff --git a/src/rust/unit-wasm-sys/lib.rs b/src/rust/unit-wasm-sys/lib.rs
new file mode 100644
index 0000000..9ef60f6
--- /dev/null
+++ b/src/rust/unit-wasm-sys/lib.rs
@@ -0,0 +1,19 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+
+/*
+ * Copyright (C) Timo Stark
+ * Copyright (C) F5, Inc.
+ */
+
+#[doc(hidden)]
+mod bindings {
+    #![allow(non_upper_case_globals)]
+    #![allow(non_camel_case_types)]
+    #![allow(dead_code)]
+
+    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+    include!("macros.rs");
+}
+
+#[doc(no_inline)]
+pub use bindings::*;
diff --git a/src/rust/unit-wasm-sys/libunit-wasm b/src/rust/unit-wasm-sys/libunit-wasm
new file mode 120000
index 0000000..2fcc511
--- /dev/null
+++ b/src/rust/unit-wasm-sys/libunit-wasm
@@ -0,0 +1 @@
+../../c
\ No newline at end of file
diff --git a/src/rust/unit-wasm-sys/macros.rs b/src/rust/unit-wasm-sys/macros.rs
new file mode 100644
index 0000000..d7fde22
--- /dev/null
+++ b/src/rust/unit-wasm-sys/macros.rs
@@ -0,0 +1,15 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+
+/*
+ * Copyright (C) Andrew Clayton
+ * Copyright (C) F5, Inc.
+ */
+
+pub const LUW_VERSION_MAJOR: i32 = 0;
+pub const LUW_VERSION_MINOR: i32 = 1;
+pub const LUW_VERSION_PATCH: i32 = 0;
+
+pub const LUW_VERSION_NUMBER: i32 =
+    (LUW_VERSION_MAJOR << 24) |
+    (LUW_VERSION_MINOR << 16) |
+    (LUW_VERSION_PATCH << 8);