Merge pull request #333 from gwsystems/wasi-networking-docs

Wasi networking docs

docs/WASI.md

@@ -0,0 +1,59 @@
+SLEdge only implemented a subset of the WASI syscall interface 
+
+## Arguments
+
+The WASI calls `args_sizes_get` and `args_get` are supported. HTTP query parameters are captured and passed as arguments.
+
+## Environment Variables
+
+The WASI calls `environ_get` and `environ_sizes_get` are supported, but mostly unused. The current behavior is to to pass the runtime's environment variables into the sandbox. This is likely undesirable.
+
+Presumably, the runtime should provide a standard set of environment variables and also allow the JSON spec to set additional function-specific environment variables. 
+
+See the reference of environment variables generated by WAGI for details: https://github.com/deislabs/wagi/blob/main/docs/environment_variables.md
+
+## Clocks
+
+`clock_time_get` is implemented but untested. `clock_res_get` is unimplemented.
+
+## File System
+
+SLEdge only supports `fd_read` from stdin and `fd_write` to stderr or stdout.
+
+stdin is populated with the body of an HTTP POST request. stdout and stderr are both written in an interleaved fashion into a buffer and sent back to the client as the response body.
+
+Actual access to the file system is unsupported, and sandboxes are not provided any preopened descriptors.
+
+## Poll
+
+`poll_oneoff` is unsupposed because SLEdge serverless functions are short lived. Sandboxed functions are assumed to make blocking reads/writes to stdin/stdout/stderr, and the serverless runtime is responsible for causing serverless functions to sleep and wake.
+
+## Exit
+
+`proc_exit` is supported and causes a sandbox to terminate execution.
+
+## Signals
+
+`proc_raise` is not supported. Signals are used by the runtime to provide preemption and context switching. It would be dangerous to trigger actual host signals from a sandbox. 
+
+However, the function could be implemented by creating a switch on the wasi signal and either ignoring or handling the signal within the `proc_raise` function itself.
+
+`SIGABRT` could trigger the sandbox to exit in an abnormal condition.
+
+The default ignore behavior could log the unexpected signal and return.
+
+## Random
+
+`random_get` is supported but largely untested.
+
+## Yield
+
+`sched_yield` is unsupported. This does not match with the run-to-completion nature of serverless. 
+
+In the case of EDF, a sandbox would always yield to itself. However, in the case of FIFO, we could enable this call to allow for a worker to "round robin" within a runqueue. However, it is unclear what the rationale would be to allow a serverless function to impact the scheduler.
+
+## Sockets
+
+All socket syscalls are unimplemented because the current logic around `sock_accept` and `sock_shutdown` seems to be focused on long-lived daemon nanoprocesses that handle multiple requests. The `poll_oneoff` call also seems to be based on this usecase. 
+
+Generally, a serverless function is expected to only make outbound network requests. However, this use case does not seem to be currently supported by WASI.

runtime/include/wasi.h

@@ -2181,6 +2181,14 @@ __wasi_errno_t wasi_snapshot_preview1_backing_sock_send(wasi_context_t *context,
                                                          */
                                                         __wasi_siflags_t si_flags, __wasi_size_t *retptr0)
   __attribute__((__warn_unused_result__));
+
+/**
+ * Accept a new incoming connection.
+ * Note: This is similar to `accept` in POSIX.
+ */
+__wasi_errno_t wasi_snapshot_preview1_backing_sock_accept(wasi_context_t *wasi_context, __wasi_fd_t fd,
+                                                          __wasi_fdflags_t how) __attribute__((__warn_unused_result__));
+
 /**
  * Shut down socket send and receive channels.
  * Note: This is similar to `shutdown` in POSIX.

runtime/src/libc/wasi_impl_serverless.c

@@ -1126,6 +1126,8 @@ wasi_snapshot_preview1_backing_sched_yield(wasi_context_t *context)
  * Note: This is similar to `recv` in POSIX, though it also supports reading
  * the data into multiple buffers in the manner of `readv`.
  *
+ * Unimplemented because receiving sockets is unsuitable for short-lived serverless functions
+ *
  * @param fd
  * @param ri_data_baseretptr List of scatter/gather vectors to which to store data.
  * @param ri_data_len The length of the array pointed to by `ri_data`.
@@ -1147,6 +1149,8 @@ wasi_snapshot_preview1_backing_sock_recv(wasi_context_t *context, __wasi_fd_t fd
  * Note: This is similar to `send` in POSIX, though it also supports writing
  * the data from multiple buffers in the manner of `writev`.
  *
+ * Unimplemented because receiving sockets is unsuitable for short-lived serverless functions
+ *
  * @param fd
  * @param si_data_baseptr List of scatter/gather vectors to which to retrieve data
  * @param si_data_len The length of the array pointed to by `si_data`.
@@ -1161,8 +1165,27 @@ wasi_snapshot_preview1_backing_sock_send(wasi_context_t *context, __wasi_fd_t fd
 	return wasi_unsupported_syscall(__func__);
 }
 
+/**
+ * Accept a new incoming connection.
+ * Note: This is similar to `accept` in POSIX.
+ *
+ * Unimplemented because receiving sockets is unsuitable for short-lived serverless functions
+ *
+ * @param fd The listening socket.
+ * @param flags The desired values of the file descriptor flags.
+ * @return New socket connection
+ */
+__wasi_errno_t
+wasi_snapshot_preview1_backing_sock_accept(wasi_context_t *context, __wasi_fd_t fd, __wasi_fdflags_t how)
+{
+	return wasi_unsupported_syscall(__func__);
+}
+
 /**
  * Shut down socket send and receive channels.
+ * Note: This is similar to `shutdown` in POSIX.
+ *
+ * Unimplemented because receiving sockets is unsuitable for short-lived serverless functions
  *
  * @param fd
  * @param how Which channels on the socket to shut down.
@@ -1171,6 +1194,5 @@ wasi_snapshot_preview1_backing_sock_send(wasi_context_t *context, __wasi_fd_t fd
 __wasi_errno_t
 wasi_snapshot_preview1_backing_sock_shutdown(wasi_context_t *context, __wasi_fd_t fd, __wasi_sdflags_t how)
 {
-	/* similar to `shutdown` in POSIX. */
 	return wasi_unsupported_syscall(__func__);
 }