http-server-hono

Hono HTTP server example

This repository showcases using a WebAssembly component built with the Javascript WebAssembly Component toolchain (jco) to respond to web requests using the Hono web framework.

How it works

Handling web requests is part of WebAssembly System Interface (WASI), under an interface called wasi:http (in particular wasi:http/incoming-handler), thanks to StarlingMonkey which is used when running jco componentize.

Hono works with WASI without any major changes because it is extraordinarily standards compliant. Since StarlingMonkey supports web standards (pushed forward by the WinterCG/WinterTC), Hono works easily with WASI standard compatible runtimes like StarlingMonkey.

To use our request handling component from NodeJS environments, we can use jco transpile to run the component. This serves as a "virtual" WebAssembly + WASI host (see @bytecodealliance/preview2-shim) that handles incoming HTTP requests (wasi:http/incoming-handler).

Note

WebAssembly components are not the same as WebAssembly Modules (asm.js, emscripten, etc), they are much more powerful and support many more features.

If you don't know what any of the above means, don't worry about it -- check out the Component Model Book, or keep following along and experiment!

Quickstart

To build this example into a demo page that you can visit, run:

npm install
npm run all

Note

Feel free to replace npm with whatever npm-compatible tooling you prefer.

The all script will:

• Build the component
• Transpile it
• Serve the WebAssembly component (via demo.js), using the jco serve (do not use this in production!)
• Send a single request to trigger the output

Expected output

> [email protected] all
> npm run build && npm run demo


> [email protected] build
> npm run gen:types && npm run build:js && npm run build:component


> [email protected] gen:types
> jco guest-types wit -o generated/types


  Generated Guest Typescript Definition Files (.d.ts):

 - generated/types/interfaces/wasi-cli-environment.d.ts         0.76 KiB
 - generated/types/interfaces/wasi-clocks-monotonic-clock.d.ts  0.42 KiB
 - generated/types/interfaces/wasi-http-incoming-handler.d.ts   0.92 KiB
 - generated/types/interfaces/wasi-http-types.d.ts              26.8 KiB
 - generated/types/interfaces/wasi-io-error.d.ts                0.19 KiB
 - generated/types/interfaces/wasi-io-poll.d.ts                 0.26 KiB
 - generated/types/interfaces/wasi-io-streams.d.ts               1.3 KiB
 - generated/types/wit.d.ts                                     1.19 KiB


> [email protected] build:js
> rollup -c


src/component.ts → dist/component.js...
(!) Circular dependency
../../../node_modules/hono/dist/request.js -> ../../../node_modules/hono/dist/utils/body.js -> ../../../node_modules/hono/dist/request.js
created dist/component.js in 1s

> [email protected] build:component
> jco componentize -w wit -o dist/component.wasm dist/component.js

ALL  /*
       logger2
GET  /
       [handler]
OK Successfully written dist/component.wasm.

> [email protected] demo
> node scripts/demo.js

fetch() OUTPUT:
Hello world!

Step-by-step

Want to go through it step-by-step? Read along from here.

Install dependencies

Similar to any other NodeJS project, you can install dependencies with npm install:

npm install

Note

Feel free to replace npm with whatever npm-compatible tooling you prefer.

Install WIT dependencies

Note

This step is already done for you (the files are present in this repo). But the following steps are useful if you need to add / modify the component.wit and need to update the wit/deps to correspond.

This project makes use of the wasi:http and wasi:cli interfaces, and they have to be installed from the central repository.

If using wkg (standard ecosystem tooling for pulling WIT interfaces), you can do this in one step:

wkg wit fetch

Note

Generally, files in wit/deps are usually third party dependencies managed by WebAssembly ecosystem tooling, contrasted with the first party WIT for your component (ex. wit/component.wit).

Build the WebAssembly component

You can build the Javascript code in component.js into a WebAssembly component by running:

npm run build

Expected output

You should see output like the following:

> [email protected] build
> npm run gen:types && npm run build:js && npm run build:component


> [email protected] gen:types
> jco guest-types wit -o generated/types


  Generated Guest Typescript Definition Files (.d.ts):

 - generated/types/interfaces/wasi-cli-environment.d.ts         0.76 KiB
 - generated/types/interfaces/wasi-clocks-monotonic-clock.d.ts  0.42 KiB
 - generated/types/interfaces/wasi-http-incoming-handler.d.ts   0.92 KiB
 - generated/types/interfaces/wasi-http-types.d.ts              26.8 KiB
 - generated/types/interfaces/wasi-io-error.d.ts                0.19 KiB
 - generated/types/interfaces/wasi-io-poll.d.ts                 0.26 KiB
 - generated/types/interfaces/wasi-io-streams.d.ts               1.3 KiB
 - generated/types/wit.d.ts                                     1.19 KiB


> [email protected] build:js
> rollup -c


src/component.ts → dist/component.js...
(!) Circular dependency
../../../node_modules/hono/dist/request.js -> ../../../node_modules/hono/dist/utils/body.js -> ../../../node_modules/hono/dist/request.js
created dist/component.js in 1s

> [email protected] build:component
> jco componentize -w wit -o dist/component.wasm dist/component.js

ALL  /*
       logger2
GET  /
       [handler]
OK Successfully written dist/component.wasm.

Aside: Components & WebAssembly System Interface (WASI)

WebAssembly Components are built against the system interfaces available in WASI.

For example, using a tool called wasm-tools we can see the imports and exports of the component we've just built:

wasm-tools component wit dist/component.wasm

You should see output that looks something like this:

package root:component;

world root {
  import wasi:cli/environment@0.2.3;
  import wasi:io/poll@0.2.3;
  import wasi:clocks/monotonic-clock@0.2.3;
  import wasi:io/error@0.2.3;
  import wasi:io/streams@0.2.3;
  import wasi:http/types@0.2.3;
  import wasi:cli/stdin@0.2.3;
  import wasi:cli/stdout@0.2.3;
  import wasi:cli/stderr@0.2.3;
  import wasi:cli/terminal-input@0.2.3;
  import wasi:cli/terminal-output@0.2.3;
  import wasi:cli/terminal-stdin@0.2.3;
  import wasi:cli/terminal-stdout@0.2.3;
  import wasi:cli/terminal-stderr@0.2.3;
  import wasi:clocks/wall-clock@0.2.3;
  import wasi:filesystem/types@0.2.3;
  import wasi:filesystem/preopens@0.2.3;
  import wasi:random/random@0.2.3;
  import wasi:http/outgoing-handler@0.2.3; /// <---- This import is used by `fetch()`!

  export wasi:http/incoming-handler@0.2.3; /// <---- This export enables responding to HTTP requests
}

/// ... elided ...

Note

The meaning of all of these imports and exports is somewhat out of scope for this example, so we won't discuss further, but please check out the Component Model Book for more details.

Transpile the WebAssembly component for NodeJS

As we noted earlier, WebAssembly Components are built against the system interfaces available in WASI.

One of the benefits of using components and WASI is that we can reimplement those interfaces when the platform changes (this is sometimes called "virtual platform layering"). The host running the WebAssembly component can provide dependencies as necessary.

Thanks to jco transpile we can take our WebAssembly component (or any other WebAssembly component) and use it on NodeJS, by converting the WebAssembly component into code that node can run today and providing shims/polyfills for WASI functionality as necessary.

In practice this means producing a bundle of JS + WebAssembly Modules that can run in NodeJS:

npm run transpile

Expected output

You should see output like the following:

> [email protected] transpile
> jco transpile -o dist/transpiled dist/component.wasm


  Transpiled JS Component Files:

 - dist/transpiled/component.core.wasm                          11.3 MiB
 - dist/transpiled/component.core2.wasm                         16.1 KiB
 - dist/transpiled/component.core3.wasm                         6.37 KiB
 - dist/transpiled/component.d.ts                               2.37 KiB
 - dist/transpiled/component.js                                  265 KiB
 - dist/transpiled/interfaces/wasi-cli-environment.d.ts          0.2 KiB
 - dist/transpiled/interfaces/wasi-cli-stderr.d.ts              0.16 KiB
 - dist/transpiled/interfaces/wasi-cli-stdin.d.ts               0.15 KiB
 - dist/transpiled/interfaces/wasi-cli-stdout.d.ts              0.16 KiB
 - dist/transpiled/interfaces/wasi-cli-terminal-input.d.ts      0.17 KiB
 - dist/transpiled/interfaces/wasi-cli-terminal-output.d.ts     0.17 KiB
 - dist/transpiled/interfaces/wasi-cli-terminal-stderr.d.ts      0.2 KiB
 - dist/transpiled/interfaces/wasi-cli-terminal-stdin.d.ts       0.2 KiB
 - dist/transpiled/interfaces/wasi-cli-terminal-stdout.d.ts      0.2 KiB
 - dist/transpiled/interfaces/wasi-clocks-monotonic-clock.d.ts  0.37 KiB
 - dist/transpiled/interfaces/wasi-clocks-wall-clock.d.ts        0.2 KiB
 - dist/transpiled/interfaces/wasi-filesystem-preopens.d.ts     0.19 KiB
 - dist/transpiled/interfaces/wasi-filesystem-types.d.ts        2.93 KiB
 - dist/transpiled/interfaces/wasi-http-incoming-handler.d.ts    0.3 KiB
 - dist/transpiled/interfaces/wasi-http-outgoing-handler.d.ts   0.47 KiB
 - dist/transpiled/interfaces/wasi-http-types.d.ts              9.88 KiB
 - dist/transpiled/interfaces/wasi-io-error.d.ts                0.18 KiB
 - dist/transpiled/interfaces/wasi-io-poll.d.ts                 0.25 KiB
 - dist/transpiled/interfaces/wasi-io-streams.d.ts              1.14 KiB
 - dist/transpiled/interfaces/wasi-random-random.d.ts           0.14 KiB

The most important file in the generated bundle is dist/transpiled/component.js -- this is the entrypoint for a (NodeJS, browser)script that wants to use the component we've just built.

Run the Demo

To be able to use our transpiled component, the included demo.js script which uses jco serve to serve the component.

To run the demo:

npm run demo

Expected output

You should see output like the following:

> demo
> node demo.js

fetch() OUTPUT:
Hello World

Potential Issues

Much of the Hono ecosystem just works, due to how Hono is built, so you can start to build more complex apps.

Where you might run into trouble is building/bundling the following:

• Leveraging adapter-specific features where support has not been added (i.e. env())
• Leveraging third-party middleware or JS libraries that require runtime-specific features (Node built-ins, node-gyp, etc)