Allow different Handles to act as stdio (#1600)

* Allow any type which implements Handle to act as stdio

There have been requests to allow more than just raw OS handles to
act as stdio in `wasi-common`. This commit makes this possible by
loosening the requirement of the `WasiCtxBuilder` to accept any
type `T: Handle + 'static` to act as any of the stdio handles.

A couple words about correctness of this approach. Currently, since
we only have a single `Handle` super-trait to represent all possible
WASI handle types (files, dirs, stdio, pipes, virtual, etc.), it
is possible to pass in any type to act as stdio which can be wrong.
However, I envision this being a problem only in the near(est) future
until we work out how to split `Handle` into several traits, each
representing a different type of WASI resource. In this particular
case, this would be a resource which would implement the interface
required for a handle to act as a stdio (with appropriate rights, etc.).

* Use OsFile in c-api

* Add some documention to the types exposed by this PR, and a few others

Signed-off-by: Jakub Konka <kubkon@jakubkonka.com>

* Add construction examples and missing docs for Handle trait

* Fix example on Windows

* Merge wasi_preview_builder into create_preview1_instance

Co-authored-by: Pat Hickey <pat@moreproductive.org>

crates/c-api/src/wasi.rs

@@ -201,63 +201,77 @@ enum WasiInstance {
     Snapshot0(WasiSnapshot0),
 }
 
-macro_rules! config_to_builder {
-    ($builder:ident, $config:ident) => {{
-        let mut builder = $builder::new();
-
-        if $config.inherit_args {
-            builder.inherit_args();
-        } else if !$config.args.is_empty() {
-            builder.args($config.args);
-        }
-
-        if $config.inherit_env {
-            builder.inherit_env();
-        } else if !$config.env.is_empty() {
-            builder.envs($config.env);
-        }
-
-        if $config.inherit_stdin {
-            builder.inherit_stdin();
-        } else if let Some(file) = $config.stdin {
-            builder.stdin(file);
-        }
-
-        if $config.inherit_stdout {
-            builder.inherit_stdout();
-        } else if let Some(file) = $config.stdout {
-            builder.stdout(file);
-        }
-
-        if $config.inherit_stderr {
-            builder.inherit_stderr();
-        } else if let Some(file) = $config.stderr {
-            builder.stderr(file);
-        }
-
-        for preopen in $config.preopens {
-            builder.preopened_dir(preopen.0, preopen.1);
-        }
-
-        builder
-    }};
-}
-
-fn create_snapshot0_instance(store: &Store, config: wasi_config_t) -> Result<WasiInstance, String> {
+fn create_snapshot0_instance(store: &Store, config: wasi_config_t) -> Result<WasiInstance> {
+    let mut builder = WasiSnapshot0CtxBuilder::new();
+    if config.inherit_args {
+        builder.inherit_args();
+    } else if !config.args.is_empty() {
+        builder.args(config.args);
+    }
+    if config.inherit_env {
+        builder.inherit_env();
+    } else if !config.env.is_empty() {
+        builder.envs(config.env);
+    }
+    if config.inherit_stdin {
+        builder.inherit_stdin();
+    } else if let Some(file) = config.stdin {
+        builder.stdin(file);
+    }
+    if config.inherit_stdout {
+        builder.inherit_stdout();
+    } else if let Some(file) = config.stdout {
+        builder.stdout(file);
+    }
+    if config.inherit_stderr {
+        builder.inherit_stderr();
+    } else if let Some(file) = config.stderr {
+        builder.stderr(file);
+    }
+    for preopen in config.preopens {
+        builder.preopened_dir(preopen.0, preopen.1);
+    }
     Ok(WasiInstance::Snapshot0(WasiSnapshot0::new(
         store,
-        config_to_builder!(WasiSnapshot0CtxBuilder, config)
-            .build()
-            .map_err(|e| e.to_string())?,
+        builder.build()?,
     )))
 }
 
-fn create_preview1_instance(store: &Store, config: wasi_config_t) -> Result<WasiInstance, String> {
+fn create_preview1_instance(store: &Store, config: wasi_config_t) -> Result<WasiInstance> {
+    use std::convert::TryFrom;
+    use wasi_common::OsFile;
+    let mut builder = WasiPreview1CtxBuilder::new();
+    if config.inherit_args {
+        builder.inherit_args();
+    } else if !config.args.is_empty() {
+        builder.args(config.args);
+    }
+    if config.inherit_env {
+        builder.inherit_env();
+    } else if !config.env.is_empty() {
+        builder.envs(config.env);
+    }
+    if config.inherit_stdin {
+        builder.inherit_stdin();
+    } else if let Some(file) = config.stdin {
+        builder.stdin(OsFile::try_from(file)?);
+    }
+    if config.inherit_stdout {
+        builder.inherit_stdout();
+    } else if let Some(file) = config.stdout {
+        builder.stdout(OsFile::try_from(file)?);
+    }
+    if config.inherit_stderr {
+        builder.inherit_stderr();
+    } else if let Some(file) = config.stderr {
+        builder.stderr(OsFile::try_from(file)?);
+    }
+    for preopen in config.preopens {
+        builder.preopened_dir(preopen.0, preopen.1);
+    }
     Ok(WasiInstance::Preview1(WasiPreview1::new(
         store,
-        config_to_builder!(WasiPreview1CtxBuilder, config)
-            .build()
-            .map_err(|e| e.to_string())?,
+        builder.build()?,
     )))
 }
 
@@ -286,8 +300,10 @@ pub unsafe extern "C" fn wasi_instance_new(
     let store = &store.store;
 
     let result = match CStr::from_ptr(name).to_str().unwrap_or("") {
-        "wasi_snapshot_preview1" => create_preview1_instance(store, *config),
-        "wasi_unstable" => create_snapshot0_instance(store, *config),
+        "wasi_snapshot_preview1" => {
+            create_preview1_instance(store, *config).map_err(|e| e.to_string())
+        }
+        "wasi_unstable" => create_snapshot0_instance(store, *config).map_err(|e| e.to_string()),
         _ => Err("unsupported WASI version".into()),
     };