Launch Preview 2 (#577)

* preview2 README: describe launched Preview 2

* preview2: add contents of each proposal wit

Author: Pat Hickey

preview2/README.md

@@ -1,18 +1,7 @@
 # WASI Preview 2
 
-At this time, Preview 2 is in development and has not yet launched.
-
-## Launch criteria
-
-WASI Preview 2 will be considered launched when at least two independent
-proposals which define worlds, and all their dependencies, have met the
-requirements for inclusion listed below, and the WASI Subgroup has voted
-to launch it.
-
 ## Introduction
 
-*The following is a draft of an introduction for WASI Preview 2 when it launches.*
-
 WASI Preview 2 represents a major milestone for WASI. It marks the moment
 when WASI has fully rebased on the [Wit IDL] and the [component model]
 type system and semantics, making it modular, fully virtualizable, and
@@ -25,8 +14,41 @@ accessible to a wide variety of source languages.
 
 WASI Preview 2 contains the following APIs:
 
-| Proposal                                                                       | Versions |
-| ------------------------------------------------------------------------------ | -------- |
+| Proposal           | Versions |
+| ------------------ | -------- |
+| [wasi-io]          | 0.2.0 |
+| [wasi-clocks]      | 0.2.0 |
+| [wasi-random]      | 0.2.0 |
+| [wasi-filesystem]  | 0.2.0 |
+| [wasi-sockets]     | 0.2.0 |
+| [wasi-cli]         | 0.2.0 |
+| [wasi-http]        | 0.2.0 |
+
+[wasi-io]: https://github.com/WebAssembly/wasi-io
+[wasi-clocks]: https://github.com/WebAssembly/wasi-clocks
+[wasi-random]: https://github.com/WebAssembly/wasi-random
+[wasi-filesystem]: https://github.com/WebAssembly/wasi-filesystem
+[wasi-sockets]: https://github.com/WebAssembly/wasi-sockets
+[wasi-cli]: https://github.com/WebAssembly/wasi-cli
+[wasi-http]: https://github.com/WebAssembly/wasi-http
+
+## WASI Preview 2 Implementations
+
+The portability criteria of the WASI Preview 2 proposals were met by the
+following implementations, which were demonstrated to be interoperable by
+each passing [Wasmtime's WASI Preview 2 test suite][test-suite].
+
+* [Wasmtime]
+* [JCO]
+
+[Wasmtime]: https://github.com/BytecodeAlliance/wasmtime
+[JCO]: https://github.com/BytecodeAlliance/jco
+
+We plan to promote the Preview 2 test suite to live in the [wasi-testsuite]
+project soon, and add more interoperable implementations to this list when
+they are complete.
+
+[wasi-testsuite]: https://github.com/WebAssembly/wasi-testsuite
 
 ## Proposal requirements for inclusion in WASI Preview 2.
 

preview2/cli/command.wit

@@ -0,0 +1,7 @@
+package wasi:cli@0.2.0;
+
+world command {
+  include imports;
+
+  export run;
+}

preview2/cli/environment.wit

@@ -0,0 +1,18 @@
+interface environment {
+  /// Get the POSIX-style environment variables.
+  ///
+  /// Each environment variable is provided as a pair of string variable names
+  /// and string value.
+  ///
+  /// Morally, these are a value import, but until value imports are available
+  /// in the component model, this import function should return the same
+  /// values each time it is called.
+  get-environment: func() -> list<tuple<string, string>>;
+
+  /// Get the POSIX-style arguments to the program.
+  get-arguments: func() -> list<string>;
+
+  /// Return a path that programs should use as their initial current working
+  /// directory, interpreting `.` as shorthand for this.
+  initial-cwd: func() -> option<string>;
+}

preview2/cli/exit.wit

@@ -0,0 +1,4 @@
+interface exit {
+  /// Exit the current instance and any linked instances.
+  exit: func(status: result);
+}

preview2/cli/imports.wit

@@ -0,0 +1,20 @@
+package wasi:cli@0.2.0;
+
+world imports {
+  include wasi:clocks/imports@0.2.0;
+  include wasi:filesystem/imports@0.2.0;
+  include wasi:sockets/imports@0.2.0;
+  include wasi:random/imports@0.2.0;
+  include wasi:io/imports@0.2.0;
+
+  import environment;
+  import exit;
+  import stdin;
+  import stdout;
+  import stderr;
+  import terminal-input;
+  import terminal-output;
+  import terminal-stdin;
+  import terminal-stdout;
+  import terminal-stderr;
+}

preview2/cli/run.wit

@@ -0,0 +1,4 @@
+interface run {
+  /// Run the program.
+  run: func() -> result;
+}

preview2/cli/stdio.wit

@@ -0,0 +1,17 @@
+interface stdin {
+  use wasi:io/streams@0.2.0.{input-stream};
+
+  get-stdin: func() -> input-stream;
+}
+
+interface stdout {
+  use wasi:io/streams@0.2.0.{output-stream};
+
+  get-stdout: func() -> output-stream;
+}
+
+interface stderr {
+  use wasi:io/streams@0.2.0.{output-stream};
+
+  get-stderr: func() -> output-stream;
+}

preview2/cli/terminal.wit

@@ -0,0 +1,49 @@
+/// Terminal input.
+///
+/// In the future, this may include functions for disabling echoing,
+/// disabling input buffering so that keyboard events are sent through
+/// immediately, querying supported features, and so on.
+interface terminal-input {
+    /// The input side of a terminal.
+    resource terminal-input;
+}
+
+/// Terminal output.
+///
+/// In the future, this may include functions for querying the terminal
+/// size, being notified of terminal size changes, querying supported
+/// features, and so on.
+interface terminal-output {
+    /// The output side of a terminal.
+    resource terminal-output;
+}
+
+/// An interface providing an optional `terminal-input` for stdin as a
+/// link-time authority.
+interface terminal-stdin {
+    use terminal-input.{terminal-input};
+
+    /// If stdin is connected to a terminal, return a `terminal-input` handle
+    /// allowing further interaction with it.
+    get-terminal-stdin: func() -> option<terminal-input>;
+}
+
+/// An interface providing an optional `terminal-output` for stdout as a
+/// link-time authority.
+interface terminal-stdout {
+    use terminal-output.{terminal-output};
+
+    /// If stdout is connected to a terminal, return a `terminal-output` handle
+    /// allowing further interaction with it.
+    get-terminal-stdout: func() -> option<terminal-output>;
+}
+
+/// An interface providing an optional `terminal-output` for stderr as a
+/// link-time authority.
+interface terminal-stderr {
+    use terminal-output.{terminal-output};
+
+    /// If stderr is connected to a terminal, return a `terminal-output` handle
+    /// allowing further interaction with it.
+    get-terminal-stderr: func() -> option<terminal-output>;
+}

preview2/clocks/monotonic-clock.wit

@@ -0,0 +1,45 @@
+package wasi:clocks@0.2.0;
+/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
+/// time.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A monotonic clock is a clock which has an unspecified initial value, and
+/// successive reads of the clock will produce non-decreasing values.
+///
+/// It is intended for measuring elapsed time.
+interface monotonic-clock {
+    use wasi:io/poll@0.2.0.{pollable};
+
+    /// An instant in time, in nanoseconds. An instant is relative to an
+    /// unspecified initial value, and can only be compared to instances from
+    /// the same monotonic-clock.
+    type instant = u64;
+
+    /// A duration of time, in nanoseconds.
+    type duration = u64;
+
+    /// Read the current value of the clock.
+    ///
+    /// The clock is monotonic, therefore calling this function repeatedly will
+    /// produce a sequence of non-decreasing values.
+    now: func() -> instant;
+
+    /// Query the resolution of the clock. Returns the duration of time
+    /// corresponding to a clock tick.
+    resolution: func() -> duration;
+
+    /// Create a `pollable` which will resolve once the specified instant
+    /// occured.
+    subscribe-instant: func(
+        when: instant,
+    ) -> pollable;
+
+    /// Create a `pollable` which will resolve once the given duration has
+    /// elapsed, starting at the time at which this function was called.
+    /// occured.
+    subscribe-duration: func(
+        when: duration,
+    ) -> pollable;
+}

preview2/clocks/wall-clock.wit

@@ -0,0 +1,42 @@
+package wasi:clocks@0.2.0;
+/// WASI Wall Clock is a clock API intended to let users query the current
+/// time. The name "wall" makes an analogy to a "clock on the wall", which
+/// is not necessarily monotonic as it may be reset.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A wall clock is a clock which measures the date and time according to
+/// some external reference.
+///
+/// External references may be reset, so this clock is not necessarily
+/// monotonic, making it unsuitable for measuring elapsed time.
+///
+/// It is intended for reporting the current date and time for humans.
+interface wall-clock {
+    /// A time and date in seconds plus nanoseconds.
+    record datetime {
+        seconds: u64,
+        nanoseconds: u32,
+    }
+
+    /// Read the current value of the clock.
+    ///
+    /// This clock is not monotonic, therefore calling this function repeatedly
+    /// will not necessarily produce a sequence of non-decreasing values.
+    ///
+    /// The returned timestamps represent the number of seconds since
+    /// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch],
+    /// also known as [Unix Time].
+    ///
+    /// The nanoseconds field of the output is always less than 1000000000.
+    ///
+    /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
+    /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
+    now: func() -> datetime;
+
+    /// Query the resolution of the clock.
+    ///
+    /// The nanoseconds field of the output is always less than 1000000000.
+    resolution: func() -> datetime;
+}