feat(examples): update hono examples import separation, better docs

Author: vados-cosmonic

examples/components/http-server-hono-with-bindings/README.md

@@ -1,8 +1,12 @@
-# Hono HTTP server example
+# Hono HTTP server with host bindings
 
 This repository showcases using a WebAssembly component built with the Javascript WebAssembly Component
 toolchain (`jco`) to respond to web requests using the [Hono][hono] web framework.
 
+In addition to simply running a transpiled web component (see `scripts/demo.mjs`),
+we introduce a host binding for the [`wasi:config/[email protected]` API][wasi-config]
+(see [`src/host/bindings/config.ts`](./src/host/bindings/config.ts)).
+
 ## How it works
 
 Handling web requests is part of [WebAssembly System Interface (WASI)][wasi], under an interface called [`wasi:http`][wasi-http]
@@ -23,6 +27,13 @@ that handles incoming HTTP requests (`wasi:http/incoming-handler`).
 > If you don't know what any of the above means, don't worry about it -- check out the [Component Model Book][cm-book],
 > or keep following along and experiment!
 
+**All of this is made easier to use by [`@bytecodealliance/jco-std`][jco-std]**, a package that offers
+easy to use exports to running on WebAssembly more Hono-native.
+
+*In addition* to using `wasi:http/incoming-handler`, this project uses `jco-std`'s support for [`wasi:cli/environment`][wasi-cli-environment]
+to enable reading environment variables and [`wasi:config/store`][wasi-config-store], to easily access ENV variables and
+custom configuration on the WebAssembly + WASI platform.
+
 [hono]: https://hono.dev
 [sm]: https://github.com/bytecodealliance/StarlingMonkey
 [wasi]: https://github.com/WebAssembly/WASI/tree/main
@@ -31,6 +42,9 @@ that handles incoming HTTP requests (`wasi:http/incoming-handler`).
 [p2-shims]: https://www.npmjs.com/package/@bytecodealliance/preview2-shim
 [cm-book]: https://component-model.bytecodealliance.org/
 [wintertc]: https://wintertc.org/
+[jco-std]: https://www.npmjs.com/package/@bytecodealliance/jco-std
+[wasi-config-store]: https://github.com/WebAssembly/wasi-config/blob/main/wit/store.wit
+[wasi-cli-environment]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/environment.wit
 
 ## Quickstart
 

examples/components/http-server-hono-with-bindings/generated/types/wit.d.ts

@@ -6,7 +6,7 @@
 /// <reference path="./interfaces/wasi-io-error.d.ts" />
 /// <reference path="./interfaces/wasi-io-poll.d.ts" />
 /// <reference path="./interfaces/wasi-io-streams.d.ts" />
-declare module 'example:hono/component' {
+declare module 'example:http-server-hono-with-bindings/component' {
   export type * as WasiCliEnvironment026 from 'wasi:cli/[email protected]'; // import wasi:cli/[email protected]
   export type * as WasiClocksMonotonicClock026 from 'wasi:clocks/[email protected]'; // import wasi:clocks/[email protected]
   export type * as WasiConfigStore020Rc1 from 'wasi:config/[email protected]'; // import wasi:config/[email protected]

examples/components/http-server-hono-with-bindings/package.json

@@ -7,10 +7,10 @@
   "scripts": {
     "gen:types": "jco guest-types wit -o generated/types",
     "build:ts": "rolldown -c rolldown.config.mjs",
-    "build:component": "jco componentize -w wit -o dist/component.wasm dist/component.js",
+    "build:component": "jco componentize -w wit -o dist/guest/component.wasm dist/guest/component.js",
     "build": "npm run gen:types && npm run build:ts && npm run build:component",
-    "transpile": "jco transpile -o dist/transpiled dist/component.wasm",
-    "serve": "jco serve dist/component.wasm",
+    "transpile": "jco transpile -o dist/transpiled dist/guest/component.wasm",
+    "serve": "jco serve dist/guest/component.wasm",
     "demo": "node scripts/demo.mjs",
     "all": "npm run build && npm run demo"
   },

examples/components/http-server-hono-with-bindings/rolldown.config.mjs

@@ -10,7 +10,7 @@ export default defineConfig([
         },
     },
     {
-        input: "src/host/bindings/*.ts",
+        input: "src/host/bindings/config.ts",
         external: /wasi:.*/,
         output: {
             dir: "dist/host/bindings",

examples/components/http-server-hono-with-bindings/scripts/demo.mjs

@@ -18,12 +18,12 @@ const JCO_PATH = env.JCO_PATH ?? "jco";
 
 /** Path to the WASM file to be used */
 const WASM_PATH = fileURLToPath(
-    new URL(env.WASM_PATH ?? "../dist/component.wasm", import.meta.url),
+    new URL(env.WASM_PATH ?? "../dist/guest/component.wasm", import.meta.url),
 );
 
 /** Path to the `wasi:config` bindings file to be used */
 const WASI_CONFIG_BINDINGS_PATH = fileURLToPath(
-    new URL(env.WASM_PATH ?? "../host-binding-wasi-config-store.mjs", import.meta.url),
+    new URL(env.WASM_PATH ?? "../dist/host/bindings/config.js", import.meta.url),
 );
 
 async function main() {

examples/components/http-server-hono-with-bindings/src/guest/component.ts

@@ -8,7 +8,10 @@ import { logger } from 'hono/logger';
  *
  * @see https://github.com/WebAssembly/wasi-http
  */
-import { fire, buildLogger } from '@bytecodealliance/jco-std/wasi/0.2.6/http/adapters/hono/server';
+import { fire, buildLogger } from '@bytecodealliance/jco-std/wasi/0.2.x/http/adapters/hono/server';
+
+import { wasiEnvMiddleware, type WasiEnvHelper } from '@bytecodealliance/jco-std/wasi/0.2.x/http/adapters/hono/middleware/env';
+import { wasiConfigMiddleware, type WasiConfigHelper } from '@bytecodealliance/jco-std/wasi/0.2.x/http/adapters/hono/middleware/config';
 
 const app = new Hono();
 
@@ -17,14 +20,38 @@ const log = buildLogger();
 
 app.use(logger(log));
 
+// Enable the wasi env middleware which will populate c.get('env')
+// with environment variables provided by the platform underneath
+app.use(wasiEnvMiddleware());
+
+// Enable the wasi config middleware which will populate c.get('config')
+// with config variables provided by the platform underneath
+app.use(wasiConfigMiddleware());
+
 app.get("/", (c) => {
+    const env: WasiEnvHelper = c.get('env');
+    if (!env) { return c.json({ status: 'error', msg: 'missing env helper'}); }
+    const config: WasiConfigHelper = c.get('config');
+    if (!config) { return c.json({ status: 'error', msg: 'missing config helper'}); }
+
+    // NOTE: To control what is available via these interfaces
+    //
+    // see:
+    //  - scripts/demo.mjs (host/platform setup, 'wasi:cli/environment' configuration via `jco serve`)
+    //  - src/host/bindings/config/env.ts (config builtin)
+
+    // Retrieve values from ENV/config
+    const username = env.getAllObject()['USER'] ?? 'unknown';
+    // see: host/bindings/config.js
+    const testKeyValue = config.get("test-key");
+
     log.debug('entered handler');
-    return c.text("Hello World!!!!");
+    return c.json({ status: 'success', data: { username, testKeyValue }});
 });
 
 fire(app);
 
 // Although we've called `fire()` with wasi HTTP configured for use above,
 // we still need to actually export the `wasi:http/incoming-handler` interface object,
 // as jco will be looking for the ES module export.
-export { incomingHandler } from '@bytecodealliance/jco-std/wasi/0.2.6/http/adapters/hono/server';
+export { incomingHandler } from '@bytecodealliance/jco-std/wasi/0.2.x/http/adapters/hono/server';

examples/components/http-server-hono-with-bindings/src/host/bindings/config.ts

@@ -11,14 +11,17 @@
  * see: https://github.com/WebAssembly/wasi-config/blob/main/wit/store.wit
  */
 
+const HARDCODED = {
+    "test-key": "test-value",
+};
+
 /** wasi:config/store.get */
-export const get = () => {
-    // TODO: read from a real config source
+export const get = (key: string) => {
+    if (key == "test-key") { return HARDCODED["test-key"]; }
     return undefined;
 };
 
 /** wasi:config/store.getAll */
 export const getAll = () => {
-    // TODO: read from a real config source
-    return [];
+    return Object.entries(HARDCODED);
 };

examples/components/http-server-hono-with-bindings/wit/component.wit

@@ -1,8 +1,10 @@
-package example:hono;
+package example:http-server-hono-with-bindings;
 
 world component {
-    // NOTE: Since jco-std can enable ENV and config middlewares,
-    // we include WASI interfaces for environment variables and config
+    // NOTE: Unlike the simple http-server-hono example,
+    // since we use middlewares that depend on 'wasi:cli/environment'
+    // and 'wasi:config/store', we must declare those WASI interfaces
+    // as imports for this component.
     import wasi:cli/environment@0.2.6;
     import wasi:config/store@0.2.0-rc.1;
 

examples/components/http-server-hono/generated/types/wit.d.ts

@@ -1,15 +1,11 @@
-/// <reference path="./interfaces/wasi-cli-environment.d.ts" />
 /// <reference path="./interfaces/wasi-clocks-monotonic-clock.d.ts" />
-/// <reference path="./interfaces/wasi-config-store.d.ts" />
 /// <reference path="./interfaces/wasi-http-incoming-handler.d.ts" />
 /// <reference path="./interfaces/wasi-http-types.d.ts" />
 /// <reference path="./interfaces/wasi-io-error.d.ts" />
 /// <reference path="./interfaces/wasi-io-poll.d.ts" />
 /// <reference path="./interfaces/wasi-io-streams.d.ts" />
-declare module 'example:hono/component' {
-  export type * as WasiCliEnvironment026 from 'wasi:cli/[email protected]'; // import wasi:cli/[email protected]
+declare module 'example:http-server-hono/component' {
   export type * as WasiClocksMonotonicClock026 from 'wasi:clocks/[email protected]'; // import wasi:clocks/[email protected]
-  export type * as WasiConfigStore020Rc1 from 'wasi:config/[email protected]'; // import wasi:config/[email protected]
   export type * as WasiHttpTypes026 from 'wasi:http/[email protected]'; // import wasi:http/[email protected]
   export type * as WasiIoError026 from 'wasi:io/[email protected]'; // import wasi:io/[email protected]
   export type * as WasiIoPoll026 from 'wasi:io/[email protected]'; // import wasi:io/[email protected]

examples/components/http-server-hono/scripts/demo.mjs

@@ -21,11 +21,6 @@ const WASM_PATH = fileURLToPath(
     new URL(env.WASM_PATH ?? "../dist/component.wasm", import.meta.url),
 );
 
-/** Path to the `wasi:config` bindings file to be used */
-const WASI_CONFIG_BINDINGS_PATH = fileURLToPath(
-    new URL(env.WASM_PATH ?? "../host-binding-wasi-config-store.mjs", import.meta.url),
-);
-
 async function main() {
     // Determine paths to jco and output wasm
     const wasmPathExists = await stat(WASM_PATH)
@@ -44,9 +39,7 @@ async function main() {
         "serve",
         "--port",
         randomPort,
-        `--jco-map=wasi:config/store=${WASI_CONFIG_BINDINGS_PATH}`,
         WASM_PATH,
-
     ];
     // Spawn jco serve
     const proc = spawn(JCO_PATH, jcoArgs, {