feat(examples): add fs write file example

Author: vados-cosmonic

examples/components/README.md

@@ -9,6 +9,7 @@ A brief description of the examples contained in this folder:
 |------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
 | [`add`](./add)                                             | `export`s basic functionality with simple types with a bare function export (deprectaed)         |
 | [`adder`](./adder)                                         | `export`s basic functionality with simple types with an interface (recommended)                  |
+| [`fs-write-file`](./fs-write-file)                         | Example of using `wasi:filesystem` (p2) to write a file to disk                                  |
 | [`host-logging`](./host-logging)                           | Showcases the use of the `wasi:logging` interface with a custom embedder ("host") function       |
 | [`http-hello-world`](./http-hello-world)                   | HTTP server using the [`wasi:http/incoming-handler`][wasi-http], the hard way.                   |
 | [`http-server-fetch-handler`](./http-server-fetch-handler) | HTTP server using standards-forward `fetch()` event handling built into [StarlingMonkey][sm]     |
@@ -24,7 +25,8 @@ A brief description of the examples contained in this folder:
 [hono]: https://hono.dev
 [nodejs]: https://nodejs.org
 [sm]: https://github.com/bytecodealliance/StarlingMonkey
-[wasi-http]: https://github.com/WebAssembly/wasi-http
+[wasi-http]: https://github.com/WebAssembly/WASI/tree/main/proposals/http
 [wasi-logging]: https://github.com/WebAssembly/wasi-logging
+[wasi-fs]: https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem
 [webidl2wit]: https://github.com/wasi-gfx/webidl2wit
 [webidl]: https://developer.mozilla.org/en-US/docs/Glossary/WebIDL

examples/components/fs-write-file/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+*.wasm
+pnpm-lock.yaml
+output.txt

examples/components/fs-write-file/.nvmrc

@@ -0,0 +1 @@
+v22.5.1

examples/components/fs-write-file/README.md

@@ -0,0 +1,216 @@
+# WASI `fs-write-file` in JavaScript
+
+This folder contains a WebAssembly Javascript component that uses [`wasi:filesystem`][wasi-fs] to write
+a file to a pre-opened directory.
+
+It uses [`jco`][jco] to:
+
+- Generate a WebAssembly component (via `jco componentize`) that can be executed by a WebAssembly runtime (ex. [`wasmtime serve`][wasmtime])
+- Transpile the component (via `jco transpile`) into one that can run on NodeJS
+
+[nodejs]: https://nodejs.org
+[jco]: https://bytecodealliance.github.io/jco/
+[wasi-fs]: https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem
+[wasmtime]: https://github.com/bytecodealliance/wasmtime
+
+# Quickstart
+
+## Dependencies
+
+First, install required dependencies:
+
+```console
+npm install
+```
+
+> [!NOTE]
+> As this is a regular NodeJS project, you can use your package manager of choice (e.g. `yarn`, `pnpm`)
+
+At this point, since this project is *just* NodeJS, you could use the module from any NodeJS project or browser project where appropriate.
+
+That said, we'll be focusing on building the JS code we've written so far into a WebAssembly binary, which can run *anywhere*
+WebAssembly runtimes are supported, including in other languages, and the browser (experimental support).
+
+## Building the WebAssembly component
+
+To turn our JS into a WebAssembly component, we can use `jco componentize`:
+
+```console
+jco componentize component.js --wit wit --world-name component --out dist/component.wasm
+```
+
+> [!NOTE]
+> For ease, you can do all of this with `pnpm build` or `npm run build`, or your npm-compatible build tool of choice.
+
+You should see output like the following:
+
+```
+pnpm build
+
+> build
+> jco componentize component.js --wit wit --world-name component --out dist/component.wasm
+
+OK Successfully written dist/component.wasm.
+```
+
+Now that your component has been built, we can do *alot* of things to inspect it.
+
+You can recognize a WebAssemblyc omponent versus a module via the magic strings recognized by tools like `file`:
+
+```
+$ file dist/component.wasm
+dist/component.wasm: WebAssembly (wasm) binary version 0x1000d (component)
+```
+
+
+We can do all this quickly with the `build` script:
+
+```console
+npm run build
+```
+
+## Transpiling the WebAssembly component
+
+To convert the component we built to a form in which it is runnable by any JS runtime with `WebAssembly` support, we use
+`jco transpile`:
+
+```console
+jco transpile dist/component.wasm --instantiation=async -o dist/transpiled
+```
+
+This command takes `dist/component.wasm` and converts it into a folder with multiple files:
+
+```
+dist/transpiled
+├── component.core2.wasm
+├── component.core3.wasm
+├── component.core4.wasm
+├── component.core.wasm
+├── component.d.ts
+├── component.js
+└── interfaces
+    ├── jco-test-test.d.ts
+    ├── wasi-cli-stderr.d.ts
+    ├── wasi-cli-stdin.d.ts
+    ├── wasi-cli-stdout.d.ts
+    ├── wasi-cli-terminal-input.d.ts
+    ├── wasi-cli-terminal-output.d.ts
+    ├── wasi-cli-terminal-stderr.d.ts
+    ├── wasi-cli-terminal-stdin.d.ts
+    ├── wasi-cli-terminal-stdout.d.ts
+    ├── wasi-clocks-monotonic-clock.d.ts
+    ├── wasi-clocks-wall-clock.d.ts
+    ├── wasi-filesystem-preopens.d.ts
+    ├── wasi-filesystem-types.d.ts
+    ├── wasi-http-outgoing-handler.d.ts
+    ├── wasi-http-types.d.ts
+    ├── wasi-io-error.d.ts
+    ├── wasi-io-poll.d.ts
+    ├── wasi-io-streams.d.ts
+    └── wasi-random-random.d.ts
+
+2 directories, 25 files
+```
+
+The files in this folder contain WebAssembly modules (i.e. what is supported by `WebAssembly` out of the box today), along with
+glue code, and typescript necessary to interact with the interfaces that are used by your component.
+
+We can do all of this quickly with the `transpile` script:
+
+```console
+npm run transpile
+```
+
+## Running the transpiled WebAssembly component
+
+As we have now transpiled our WebAssembly Component into it's constituent modules and glue code, we can instantiate it
+and use it from JS.
+
+See the code in `run-transpiled.js`, importantly the following lines:
+
+```js
+import { instantiate } from "./dist/transpiled/component.js";
+
+// ...
+
+const instance = await instantiate(...);
+```
+
+Another set of important lines are the import and usage of a WASI Shim, which controls the sandbox in which
+your WebAssembly component will execute:
+
+```js
+import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation";
+
+// ...
+
+const shim = new WASIShim({
+    sandbox: {
+        preopens: {
+            '/': CURRENT_PATH,
+        },
+    }
+});
+
+const instance = await instantiate(undefined, shim.getImportObject());
+```
+
+As WebAssembly has a capability-driven security model, all access to the filesytem must be provided explicitly.
+
+To run the demo all at once:
+
+```
+npm run transpiled-js
+```
+
+# How it works
+
+## Exploring this Component WIT
+
+As WebAssembly components are powered by a [WebAssembly Interface Types ("WIT")][wit]-first workflow, making
+a HTTP handler component in WebAssembly requires creating a WIT contract to represent that component.
+
+This folder contains a `wit` directory (by convention) with the following content in `component.wit`:
+
+```wit
+package jco:test;
+
+interface test {
+    run: func() -> string;
+}
+
+world component {
+    import wasi:filesystem/types@0.2.8;
+    import wasi:filesystem/preopens@0.2.8;
+
+    export test;
+}
+```
+
+> [!NOTE]
+> See [`wit/component.wit`](./wit/component.wit)
+>
+> For more information on the WIT syntax, see [WIT design docs][wit]
+
+We make use of the [WebAssembly System Interface ("WASI") for filesystems][wasi-fs] interface here, pulling in
+pre-established interfaces interfaces for getting a list of pre-opened directories.
+
+[wasi-http]: https://github.com/WebAssembly/wasi-http
+[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md
+
+## Resolving references WebAssembly types
+
+As we intend to use the WASI FS interface, we need to pull in WIT interface(s) and types that are referred to by
+the `wasi:filesystem/preopens` interface.
+
+One way fo doing this is *downloading* the WIT from Bytecode Alliance repositories, using [`wkg`, from the `bytecodealliance/wasm-pkg-tools`][wkg].
+
+With a top level world in `wit/component.wit`, we can easily fetch all automatically-resolvable interfaces:
+
+```console
+wkg wit fetch
+```
+
+> [!NOTE]
+> Standard interfaces are automatically resolvable, but if custom interfaces are used, you'll need to configure `wkg`
+> so it knows where to find the relevant WIT information.

examples/components/fs-write-file/component.js

@@ -0,0 +1,35 @@
+// For more information on how to use WASI filesystem interfaces
+//
+// see: https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem/wit
+import { getDirectories } from "wasi:filesystem/preopens@0.2.8";
+
+// This text encoder will be created at compile & JS VM snapshot time,
+// it will not be re-created on every call of the `run` export.
+const TEXT_ENCODER = new TextEncoder();
+
+const FILENAME = "output.txt";
+
+export const test = {
+    run() {
+        const preopens = getDirectories();
+        if (preopens.length === 0) { throw "ERROR: no preopens"; }
+
+        // We expect that we have at least one preopen, and take the first one,
+        // in which we will write the output file
+        const dirDescriptor = preopens[0][0];
+
+        // NOTE: fs operations (open, write, sync) will throw if they fail
+        const f = dirDescriptor.openAt(
+            {symlinkFollow: false},
+            FILENAME,
+            { create: true },
+            { write: true },
+        );
+
+        f.write(TEXT_ENCODER.encode("Hello world, from component!"), 0);
+
+        f.sync();
+
+        return "SUCCESS: wrote file";
+    }
+};

examples/components/fs-write-file/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "fs-write-file",
+    "description": "Codebase showcasing a simple use of wasi:filesystem (p2)",
+    "type": "module",
+    "scripts": {
+        "build": "jco componentize component.js --wit wit --world-name component --out dist/component.wasm",
+        "transpile": "jco transpile dist/component.wasm --instantiation=async -o dist/transpiled",
+        "transpiled-js": "node run-transpiled.js",
+        "all": "npm run build; npm run transpile; npm run transpiled-js"
+    },
+    "devDependencies": {
+        "@bytecodealliance/jco": "^1.17.6"
+    },
+    "dependencies": {
+        "@bytecodealliance/preview2-shim": "^0.17.8"
+    }
+}

examples/components/fs-write-file/run-transpiled.js

@@ -0,0 +1,48 @@
+import { readFile, stat, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { URL, fileURLToPath } from "node:url";
+import assert from "node:assert/strict";
+
+import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation";
+
+// If this import listed below is missing, please run `npm run transpile`
+import { instantiate } from "./dist/transpiled/component.js";
+
+const CURRENT_PATH = fileURLToPath(new URL("./", import.meta.url));
+
+async function fileExists(p) {
+    return stat(p).then(f => f.isFile()).catch(() => false);
+}
+
+async function main() {
+    let expectedPath = join(CURRENT_PATH, "output.txt");
+    if (await fileExists(expectedPath)) {
+        console.log("detected existing file at path, removing...");
+        await rm(expectedPath);
+    }
+
+    // Create the environment the transpiled component will use
+    const shim = new WASIShim({
+        sandbox: {
+            preopens: {
+                '/': CURRENT_PATH,
+            },
+        }
+    });
+
+    // Create an instance of the transpiled component, with environment
+    const instance = await instantiate(undefined, shim.getImportObject());
+
+    // Run the actual component function
+    const res = instance.test.run();
+    assert.strictEqual(res, "SUCCESS: wrote file");
+
+    assert(await fileExists(expectedPath), "expected output file exists");
+
+    const contents = await readFile(expectedPath);
+    assert.strictEqual(contents.toString(), "Hello world, from component!", "expected output file exists");
+
+    console.log("successfully wrote output file");
+}
+
+await main();

examples/components/fs-write-file/wit/component.wit

@@ -0,0 +1,12 @@
+package jco:test;
+
+interface test {
+    run: func() -> string;
+}
+
+world component {
+    import wasi:filesystem/types@0.2.8;
+    import wasi:filesystem/preopens@0.2.8;
+
+    export test;
+}

examples/components/fs-write-file/wit/deps/wasi-clocks-0.2.8/package.wit

@@ -0,0 +1,13 @@
+package wasi:clocks@0.2.8;
+
+interface wall-clock {
+  record datetime {
+    seconds: u64,
+    nanoseconds: u32,
+  }
+
+  now: func() -> datetime;
+
+  resolution: func() -> datetime;
+}
+