Document WebAssembly workload format

Fixes #17.

features/workload-package-format/README.md

@@ -0,0 +1,95 @@
+# workload-package-format
+- Authors: Daiki Ueno
+- Status: [PROPOSED](/README.md#proposed)
+- Since: 2020-05-19
+- Status Note: Under discussion
+- Supersedes: None
+- Start Date: 2020-05-19
+- Tags: feature, protocol
+
+## Summary
+
+Typical applications are accompanied with read-only resources used at
+run time, such as configuration files or precomputed binary data. This
+RFC proposes a way to provision those resources along with the
+application executable into a Keep.
+
+## Motivation
+
+Unlike normal applications running on the host, an application
+deployed in a Keep must take care of accessing external resources, so
+that it doesn't expose any confidential information to the host. On
+the other hand, applications practically require data files to achieve
+their tasks. There needs to be a way to provision data files into a
+Keep so that the applications can access those files in a secure
+manner.
+
+## Tutorial
+
+This RFC introduces a new [custom section] in WebAssembly binary
+format, identified as `.enarx.resources`. The payload of the custom
+section is in a `tar` file format that may contain any number of
+resource files.
+
+The name of each entry MUST be a canonical path name, meaning that it
+starts with `/`, and symbolic links or any special path components
+that affect directory traversal (`.` and `..`) are resolved.
+
+After parsing the custom section, each entry in the payload is mapped
+on an in-memory virtual filesystem in the WASI instance. The
+executable is supposed to access those files through the standard
+WASI system calls such as [`path_open`].
+
+## Reference
+
+[wasi-common] provides a way to expose in-memory data as a file on
+virtual filesystem with [VirtualDirEntry]. Once the bundled resources
+are mapped to a VirtualDirEntry, it can be associated with the WASI
+instance through `WasiCtxBuilder::preopened_virt()` call.
+
+To create a WebAssembly executable with those resources, we will
+provide a command-line tool that attaches a tar file to the
+executable, after proper checks on the path names of the contents.
+
+## Drawbacks
+
+No drawbacks currently known.
+
+## Rationale and alternatives
+
+For simplicity, this RFC is extending the WebAssembly binary format to
+embed all the resources in it. However, there is a possibility to use
+a container format directly for packaging, such as bundling the
+executable along with other data files in the same archive, or using
+the [OCI image format]. The benefits of this approach are:
+- The application bundle can be built using a standard tools
+- May bring additional flexiblity in composition, such as versioning
+
+## Prior art
+
+[GResource] in glib provides a similar mechanism bundling resource
+files in an ELF section (`.gresources.*`).
+
+## Unresolved questions
+
+This proposal assumes that bundled resources fit in the Keep's memory.
+It is still under discussion what approach should be taken to
+provision non-confidential data as well, in particular the sizes of such
+resources are large and cause unreasonable memory consumption.
+
+## Implementations
+
+No implementation yet available (2020-05-19).
+
+## Future Possibilities
+
+It might be useful to convey other information than the resources,
+such as environment variables or the default command-line arguments,
+as a new custom section holding metadata.
+
+[`path_open`]: https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#path_open
+[custom section]: https://webassembly.github.io/spec/core/binary/modules.html#custom-section
+[wasi-common]: https://crates.io/crates/wasi-common
+[VirtualDirEntry]: https://docs.rs/wasi-common/0.16.0/wasi_common/enum.VirtualDirEntry.html
+[GResource]: https://developer.gnome.org/gio/stable/glib-compile-resources.html
+[OCI image format]: https://github.com/opencontainers/image-spec