Server-side rendering

Frontend web frameworks allow developers to create web apps in a high level language and component model. The web app is built into a static web site to be rendered in the browser. While many frontend web frameworks are based on JavaScript, such as React and Vue, Rust-based frameworks are also emerging as the Rust language gains traction among developers. Those web frameworks render the HTML DOM UI using the WebAssembly, which is compiled from Rust source code. They use wasm-bindgen to tie the Rust to the HTML DOM. While all of these frameworks send .wasm files to the browser to render the UI on the client-side, some provide the additional choice for Server-side rendering. That is to run the WebAssembly code and build the HTML DOM UI on the server, and stream the HTML content to the browser for faster performance and startup time on slow devices and networks.

If you are interested in JavaScript-based Jamstack and SSR frameworks, such as React, please checkout our JavaScript SSR chapter.

This article will explore how to render the web UI on the server using WasmEdge. We pick Percy as our framework because it is relatively mature in SSR and Hydration). Percy already provides an example for SSR. It’s highly recommended to read it first to understand how it works. The default SSR setup with Percy utilizes a native Rust web server. The Rust code is compiled to machine native code for the server. However, in order to host user applications on the server, we need a sandbox. While we could run native code inside a Linux container (Docker), a far more efficient (and safer) approach is to run the compiled code in a WebAssembly VM on the server, especially considerring the rendering code is already compiled into WebAssembly.

Now, let’s go through the steps to run a Percy SSR service in a WasmEdge server.

Assuming we are in the examples/isomorphic directory, make a new crate beside the existing server.

cargo new server-wasmedge

You’ll receive a warning to let you put the new crate into the workspace, so insert below into members of [workspace]. The file is ../../Cargo.toml.

"examples/isomorphic/server-wasmedge"

With the file open, put these two lines in the bottom:

[patch.crates-io] wasm-bindgen = { git = "https://github.com/KernelErr/wasm-bindgen.git", branch = "wasi-compat" }

Why do we need a forked wasm-bindgen? That is because wasm-bindgen is the required glue between Rust and HTML in the browser. On the server, however, we need to build the Rust code to the wasm32-wasi target, which is incompatible with wasm-bindgen. Our forked wasm-bindgen has conditional configs that removes browser-specific code in the generated .wasm file for the wasm32-wasi target.

Then replace the crate’s Cargo.toml with following content.

[package] name = "isomorphic-server-wasmedge" version = "0.1.0" edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] wasmedge_wasi_socket = "0" querystring = "1.1.0" parsed = { version = "0.3", features = ["http"] } anyhow = "1" serde = { version = "1.0", features = ["derive"] } isomorphic-app = { path = "../app" }

The wasmedge_wasi_socket crate is the socket API of WasmEdge. This project is under development. Next copy the index.html file into the crate’s root.

cp server/src/index.html server-wasmedge/src/

Then let’s create some Rust code to start a web service in WasmEdge! The main.rs program listens to the request and sends the response via the stream.

  1. use std::io::Write;
  2. use wasmedge_wasi_socket::{Shutdown, TcpListener};
  4. mod handler;
  5. mod mime;
  6. mod response;
  8. fn main() {
  9.     let server = TcpListener::bind("127.0.0.1:3000", false).unwrap();
  10.     println!("Server listening on 127.0.0.1:3000");
  12.     // Simple single thread HTTP server
  13.     // For server with Pool support, see https://github.com/second-state/wasmedge_wasi_socket/tree/main/examples/poll_http_server
  14.     loop {
  15.         let (mut stream, addr) = server.accept(0).unwrap();
  16.         println!("Accepted connection from {}", addr);
  17.         match handler::handle_req(&mut stream, addr) {
  18.             Ok((res, binary)) => {
  19.                 let res: String = res.into();
  20.                 let bytes = res.as_bytes();
  21.                 stream.write_all(bytes).unwrap();
  22.                 if let Some(binary) = binary {
  23.                     stream.write_all(&binary).unwrap();
  24.                 }
  25.             }
  26.             Err(e) => {
  27.                 println!("Error: {:?}", e);
  28.             }
  29.         };
  30.         stream.shutdown(Shutdown::Both).unwrap();
  31.     }
  32. }

The handler.rs parses the received data to the path and query objects and return the corresponding response.

  2. #![allow(unused)]
  3. fn main() {
  4. use crate::response;
  5. use anyhow::Result;
  6. use parsed::http::Response;
  7. use std::io::Read;
  8. use wasmedge_wasi_socket::{SocketAddr, TcpStream};
  10. pub fn handle_req(stream: &mut TcpStream, addr: SocketAddr) -> Result<(Response, Option<Vec<u8>>)> {
  11.     let mut buf = [0u8; 1024];
  12.     let mut received_data: Vec<u8> = Vec::new();
  14.     loop {
  15.         let n = stream.read(&mut buf)?;
  16.         received_data.extend_from_slice(&buf[..n]);
  17.         if n < 1024 {
  18.             break;
  19.         }
  20.     }
  22.     let mut bs: parsed::stream::ByteStream = match String::from_utf8(received_data) {
  23.         Ok(s) => s.into(),
  24.         Err(_) => return Ok((response::bad_request(), None)),
  25.     };
  27.     let req = match parsed::http::parse_http_request(&mut bs) {
  28.         Some(req) => req,
  29.         None => return Ok((response::bad_request(), None)),
  30.     };
  32.     println!("{:?} request: {:?} {:?}", addr, req.method, req.path);
  34.     let mut path_split = req.path.split("?");
  35.     let path = path_split.next().unwrap_or("/");
  36.     let query_str = path_split.next().unwrap_or("");
  37.     let query = querystring::querify(&query_str);
  38.     let mut init_count: Option<u32> = None;
  39.     for (k, v) in query {
  40.         if k.eq("init") {
  41.             match v.parse::<u32>() {
  42.                 Ok(v) => init_count = Some(v),
  43.                 Err(_) => return Ok((response::bad_request(), None)),
  44.             }
  45.         }
  46.     }
  48.     let (res, binary) = if path.starts_with("/static") {
  49.         response::file(&path)
  50.     } else {
  51.         // render page
  52.         response::ssr(&path, init_count)
  53.     }
  54.     .unwrap_or_else(|_| response::internal_error());
  56.     Ok((res, binary))
  57. }
  58. }

The response.rs program packs the response object for static assets and for server rendered content. For the latter, you could see that SSR happens at app.render().to_string(), the result string is put into HTML by replacing the placeholder text.

  2. #![allow(unused)]
  3. fn main() {
  4. use crate::mime::MimeType;
  5. use anyhow::Result;
  6. use parsed::http::{Header, Response};
  7. use std::fs::{read};
  8. use std::path::Path;
  9. use isomorphic_app::App;
  11. const HTML_PLACEHOLDER: &str = "#HTML_INSERTED_HERE_BY_SERVER#";
  12. const STATE_PLACEHOLDER: &str = "#INITIAL_STATE_JSON#";
  14. pub fn ssr(path: &str, init: Option<u32>) -> Result<(Response, Option<Vec<u8>>)> {
  15.     let html = format!("{}", include_str!("./index.html"));
  17.     let app = App::new(init.unwrap_or(1001), path.to_string());
  18.     let state = app.store.borrow();
  20.     let html = html.replace(HTML_PLACEHOLDER, &app.render().to_string());
  21.     let html = html.replace(STATE_PLACEHOLDER, &state.to_json());
  23.     Ok((Response {
  24.         protocol: "HTTP/1.0".to_string(),
  25.         code: 200,
  26.         message: "OK".to_string(),
  27.         headers: vec![
  28.             Header {
  29.                 name: "content-type".to_string(),
  30.                 value: MimeType::from_ext("html").get(),
  31.             },
  32.             Header {
  33.                 name: "content-length".to_string(),
  34.                 value: html.len().to_string(),
  35.             },
  36.         ],
  37.         content: html.into_bytes(),
  38.     }, None))
  39. }
  41. /// Get raw file content
  42. pub fn file(path: &str) -> Result<(Response, Option<Vec<u8>>)> {
  43.     let path = Path::new(&path);
  44.     if path.exists() {
  45.         let content_type: MimeType = match path.extension() {
  46.             Some(ext) => MimeType::from_ext(ext.to_str().get_or_insert("")),
  47.             None => MimeType::from_ext(""),
  48.         };
  49.         let content = read(path)?;
  51.         Ok((Response {
  52.             protocol: "HTTP/1.0".to_string(),
  53.             code: 200,
  54.             message: "OK".to_string(),
  55.             headers: vec![
  56.                 Header {
  57.                     name: "content-type".to_string(),
  58.                     value: content_type.get(),
  59.                 },
  60.                 Header {
  61.                     name: "content-length".to_string(),
  62.                     value: content.len().to_string(),
  63.                 },
  64.             ],
  65.             content: vec![],
  66.         }, Some(content)))
  67.     } else {
  68.         Ok((Response {
  69.             protocol: "HTTP/1.0".to_string(),
  70.             code: 404,
  71.             message: "Not Found".to_string(),
  72.             headers: vec![],
  73.             content: vec![],
  74.         }, None))
  75.     }
  76. }
  78. /// Bad Request
  79. pub fn bad_request() -> Response {
  80.     Response {
  81.         protocol: "HTTP/1.0".to_string(),
  82.         code: 400,
  83.         message: "Bad Request".to_string(),
  84.         headers: vec![],
  85.         content: vec![],
  86.     }
  87. }
  89. /// Internal Server Error
  90. pub fn internal_error() -> (Response, Option<Vec<u8>>) {
  91.     (Response {
  92.         protocol: "HTTP/1.0".to_owned(),
  93.         code: 500,
  94.         message: "Internal Server Error".to_owned(),
  95.         headers: vec![],
  96.         content: vec![],
  97.     }, None)
  98. }
  99. }

The mime.rs program is a map for assets’ extension name and the Mime type.

  2. #![allow(unused)]
  3. fn main() {
  4. pub struct MimeType {
  5.     pub r#type: String,
  6. }
  8. impl MimeType {
  9.     pub fn new(r#type: &str) -> Self {
  10.         MimeType {
  11.             r#type: r#type.to_string(),
  12.         }
  13.     }
  15.     pub fn from_ext(ext: &str) -> Self {
  16.         match ext {
  17.             "html" => MimeType::new("text/html"),
  18.             "css" => MimeType::new("text/css"),
  19.             "map" => MimeType::new("application/json"),
  20.             "js" => MimeType::new("application/javascript"),
  21.             "json" => MimeType::new("application/json"),
  22.             "svg" => MimeType::new("image/svg+xml"),
  23.             "wasm" => MimeType::new("application/wasm"),
  24.             _ => MimeType::new("text/plain"),
  25.         }
  26.     }
  28.     pub fn get(self) -> String {
  29.         self.r#type
  30.     }
  31. }
  32. }

That’s it! Now let’s build and run the web application. If you have tested the original example, you probably have already built the client WebAssembly.

cd client ./build-wasm.sh

Next, build and run the server.

cd ../server-wasmedge cargo build --target wasm32-wasi OUTPUT_CSS="$(pwd)/../client/build/app.css" wasmedge --dir /static:../client/build ../../../target/wasm32-wasi/debug/isomorphic-server-wasmedge.wasm

Navigate to http://127.0.0.1:3000 and you will see the web application in action.

Furthermore, you can place all the steps into a shell script ../start-wasmedge.sh.

#!/bin/bash cd $(dirname $0) cd ./client ./build-wasm.sh cd ../server-wasmedge OUTPUT_CSS="$(pwd)/../client/build/app.css" cargo run -p isomorphic-server-wasmedge

Add the following to the .cargo/config.toml file.

[build] target = "wasm32-wasi" [target.wasm32-wasi] runner = "wasmedge --dir /static:../client/build"

After that, a single CLI command ./start-wasmedge.sh would perform all the tasks to build and run the web application!

We forked the Percy repository and made a ready-to-build server-wasmedge example project for you. Happy coding!