Rough sketch: WASI manifests

The following is a very rough sketch for a WASI manifest design. This sketch takes the approach of encoding a manifest in WebAssembly custom sections. One of the goals here is just to get people thinking about what a manifest should be able to do and how it should work.

The basic idea here is to allow WASI-using modules to "request" certain capabilities (aka file descriptors) be pre-opened and provided to them. fd_prestat_get could then provide information about them.

The manifest section

This would be a WebAssembly custom section, which would be sequenced somewhere around the end of a module. For simplicity, this proposal encodes entries in the manifest as a sequence of varuint32 length + UTF-8 content strings. Requests consist of several strings, terminated by the string ".".

Resource requests

A resource request starts with an identifier of the type of resource being requested:

Name	Description
directory	a directory, which may contain files, directories, or other things, preopened
socket	openable sockets (network or otherwise, stream or otherwise), not pre-opened

directory resources

For directory resources, the next string is the logical name, which is a UTF-8 string. Note that this name is just a key, rather than being an actual file path. Mapping the key to a path is implementation-specific and may require input from the end user. There are no significant path separators, such as '/', in this name.

The following names are recognized and implementations may choose to streamline the user experience for these paths:

Name
Desktop
Documents
Downloads
Music
Pictures
Videos

This may be optionally followed by additional attribute strings:

Name	Description
list	can get a listing of this directory's contents (aka readdir)
write	can create or rename files

write depends on list.

Examples:

Resource request	Meaning
directory|Pictures|list	can list and read the contents of the user's Pictures folder
directory|logs|write	can write to log files (but not see the names of existing log files)

socket resources

For socket resources, the next string is the name, which is a UTF-8 string, interpreted as a key, in the same way as directory resource names.

The next string specifies the domain, which is one of the following:

Name	Description
ip	IPv4 or IPv6

The next string specifies the type, which is one of the following:

Name	Description
stream	connection-based socket
datagram	connectionless socket

This is followed by a mode, which is one of the following:

Name	Description
listen	listen for incoming connections or packets
connect	initiate a connection (for stream) or set a default destination (for datagram); see below for details

listen sockets

For listen socket resources, the next string is the arity, which is one of the following:

Name	Description
single	exactly one address will be provided by the implementation
multiple	the implementation may provide multiple addresses

This is optionally followed by a port suggestion, which for ip sockets is : followed by either a number, an IANA port name, or "*".

Examples:

Resource Request	Meaning
socket|ip|datagram|listen:ntp	Request a socket address that may be listened on for network datagrams, and suggest port 123
socket|ip|stream|listen:8080	Request a socket address that may be listened on for network streams, and suggest port 8080
socket|ip|stream|listen:*	Request a socket address that may be listened on for network streams, and suggest allowing any port

connect sockets

For connect socket resources, an optional destination suggestion may follow.

Destination description for ip sockets starts with an address set, which is either CIDR notation or a domain name in which components may be replaced by "*" to indicate that any name at that level is to be permitted. For IPV6 addresses, the CIDR notation is enclosed in brackets ("[" and "]"). It is followed by ":" and either a port number, an IANA port name, or "*".

Examples:

Resource Request	Meaning
socket|ip|stream|connect|*.example.com:20	Suggest allowing connecting to ftp ports on hosts under example.com
socket|ip|stream|connect|[2001:4860:4860::8888/125]:80	IPv6 CIDR notation with brackets, single port
socket|ip|datagram|connect|10.0.0.0/24:*	Suggest allowing sending datagrams to any port on addresses in 10.0.0.*

Note that WASI does not currently support sendto, so datagram sockets can't send packets to non-default addresses.

To make all this work:

The networking features here assume the addition of functions to create/bind/listen/connect sockets.

No implementation files, tests, or entry points are identified. Start by reading the manifest and socket-resource proposal in this issue, then check the current WASI specifications and discussions to determine whether this design is still applicable. Done would require an agreed manifest design and clearly scoped implementation work, which the issue does not define.