wasi: add documentation

[cjihrig]

No description provided.

[benjamingr]

I think an explanation that WASI is basically a thing that lets us use file and socket I/O from WASM in Node.js might be useful here.

Most of our users probably aren't even sure what POSIX or system calls are.

[cjihrig]

@benjamingr any chance you could provide the specific text you'd like to see? You can leave it as a comment or push directly to the branch as you see fit.

[cjihrig]

ping @benjamingr

[guybedford]

Seems very clear to me. A complete end-to-end example of loading a real WASI command might be a nice to have for those who don't want to strain to fill in the gaps themselves.

[cjihrig]

@guybedford do you mean the line const wasm = getWebAssemblyModuleSomehow();? That's the only part that isn't "real." I did that because there are a number of ways to "get" a wasm module, and that's how our streams docs do things. Do you have a preference on what you'd like to see there instead?

[guybedford]

@cjihrig I was just thinking for users who aren't familiar with WASI if they were curious and this were their first introduction of playing around with it, a very simple:

const module = await WebAssembly.compile(fs.readFileSync('./binary.wasm'));

might just help.

Btw what is the status of stdout handling? Is it possible to setup piping or does it default to the same stdout as the Node.js process still?

Edit: removed the unnecessary base64 from my copy-paste example.

[cjihrig]

Is it possible to setup piping or does it default to the same stdout as the Node.js process still?

stdio currently uses the real file descriptors. However, I think it would be pretty straightforward to pass alternative file descriptors to uvwasi_init() and use those instead.

[cjihrig]

I've added @guybedford's suggested line of code to the example.

[guybedford]

👍

stdio currently uses the real file descriptors. However, I think it would be pretty straightforward to pass alternative file descriptors to uvwasi_init() and use those instead.

It would be great to see an approach here further, as this is important to the command virtualization.

[cjihrig]

@guybedford I've added the file descriptor mapping piece to the checklist in #21 so it doesn't get forgotten about.

[cjihrig]

Landed in 41a2360. Thanks for the reviews!

@benjamingr please open a PR for any docs changes/additions you'd like to see.