add draft of wasi:[email protected] (#106)

* add draft of wasi:[email protected]

This adds a `wit-0.3.0-draft` directory so we can iterate on the 0.3.0 design in
parallel with the 0.2.x work.  It's currently an exact copy of the `wit`
directory except for the `handler.wit`, `proxy.wit`, and `types.wit` files,
which have been updated to assume Component Model async, `stream`s, and
`future`s are available.

High level description:

- The incoming-handler and outgoing-handler interfaces have been combined into a single handler interface.
- The incoming- and outgoing- variations of request, response, and body have been combined.
- I've added a option<request-options> field to request since it would be awkward to leave it as a parameter of handler.handle (e.g. what would it mean to receive such a parameter for an incoming request or for a request passed from one component to the other without any use of the network?).
- I've added a request-options-error (analogous to header-error) to distinguish between unsupported fields and immutable handles.
- We use `stream<u8>` and `future<trailers>` where appropriate.

You can find a working implementation of this API, plus several examples, in the
[isyswasfa](https://github.com/dicej/isyswasfa) repository.

Signed-off-by: Joel Dice <[email protected]>

* regenerate markdown files

Signed-off-by: Joel Dice <[email protected]>

---------

Signed-off-by: Joel Dice <[email protected]>

imports.md

@@ -810,11 +810,9 @@ http-related errors.</p>
 which have multiple values are represented by multiple entries in this
 list with the same key.</p>
 <p>The tuple is a pair of the field key, represented as a string, and
-Value, represented as a list of bytes. In a valid Fields, all keys
-and values are valid UTF-8 strings. However, values are not always
-well-formed, so they are represented as a raw list of bytes.</p>
-<p>An error result will be returned if any header or value was
-syntactically invalid, or if a header was forbidden.</p>
+Value, represented as a list of bytes.</p>
+<p>An error result will be returned if any <a href="#field_key"><code>field-key</code></a> or <a href="#field_value"><code>field-value</code></a> is
+syntactically invalid, or if a field is forbidden.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="static_fields.from_list.entries"></a><code>entries</code>: list&lt;(<a href="#field_key"><a href="#field_key"><code>field-key</code></a></a>, <a href="#field_value"><a href="#field_value"><code>field-value</code></a></a>)&gt;</li>
@@ -825,9 +823,9 @@ syntactically invalid, or if a header was forbidden.</p>
 </ul>
 <h4><a name="method_fields.get"></a><code>[method]fields.get: func</code></h4>
 <p>Get all of the values corresponding to a key. If the key is not present
-in this <a href="#fields"><code>fields</code></a>, an empty list is returned. However, if the key is
-present but empty, this is represented by a list with one or more
-empty field-values present.</p>
+in this <a href="#fields"><code>fields</code></a> or is syntactically invalid, an empty list is returned.
+However, if the key is present but empty, this is represented by a list
+with one or more empty field-values present.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.get.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>
@@ -853,6 +851,8 @@ syntactically invalid, <code>false</code> is returned.</p>
 <p>Set all of the values for a key. Clears any existing values for that
 key, if they have been set.</p>
 <p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
+<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> or any of
+the <a href="#field_value"><code>field-value</code></a>s are syntactically invalid.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.set.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>
@@ -867,6 +867,8 @@ key, if they have been set.</p>
 <p>Delete all values for a key. Does nothing if no values for the key
 exist.</p>
 <p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
+<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> is
+syntactically invalid.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.delete.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>
@@ -880,6 +882,8 @@ exist.</p>
 <p>Append a value for a key. Does not change or delete any existing
 values for that key.</p>
 <p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
+<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> or
+<a href="#field_value"><code>field-value</code></a> are syntactically invalid.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_fields.append.self"></a><code>self</code>: borrow&lt;<a href="#fields"><a href="#fields"><code>fields</code></a></a>&gt;</li>

wit-0.3.0-draft/deps.lock

@@ -0,0 +1,29 @@
+[cli]
+url = "https://github.com/WebAssembly/wasi-cli/archive/main.tar.gz"
+sha256 = "285865a31d777181b075f39e92bcfe59c89cd6bacce660be1b9a627646956258"
+sha512 = "da2622210a9e3eea82b99f1a5b8a44ce5443d009cb943f7bca0bf9cf4360829b289913d7ee727c011f0f72994ea7dc8e661ebcc0a6b34b587297d80cd9b3f7e8"
+
+[clocks]
+url = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
+sha256 = "468b4d12892fe926b8eb5d398dbf579d566c93231fa44f415440572c695b7613"
+sha512 = "e6b53a07221f1413953c9797c68f08b815fdaebf66419bbc1ea3e8b7dece73731062693634731f311a03957b268cf9cc509c518bd15e513c318aa04a8459b93a"
+
+[filesystem]
+url = "https://github.com/WebAssembly/wasi-filesystem/archive/main.tar.gz"
+sha256 = "498c465cfd04587db40f970fff2185daa597d074c20b68a8bcbae558f261499b"
+sha512 = "ead452f9b7bfb88593a502ec00d76d4228003d51c40fd0408aebc32d35c94673551b00230d730873361567cc209ec218c41fb4e95bad194268592c49e7964347"
+
+[io]
+url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
+sha256 = "7210e5653539a15478f894d4da24cc69d61924cbcba21d2804d69314a88e5a4c"
+sha512 = "49184a1b0945a889abd52d25271172ed3dc2db6968fcdddb1bab7ee0081f4a3eeee0977ad2291126a37631c0d86eeea75d822fa8af224c422134500bf9f0f2bb"
+
+[random]
+url = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz"
+sha256 = "7371d03c037d924caba2587fb2e7c5773a0d3c5fcecbf7971e0e0ba57973c53d"
+sha512 = "964c4e8925a53078e4d94ba907b54f89a0b7e154f46823a505391471466c17f53c8692682e5c85771712acd88b348686173fc07c53a3cfe3d301b8cd8ddd0de4"
+
+[sockets]
+url = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"
+sha256 = "622bd28bbeb43736375dc02bd003fd3a016ff8ee91e14bab488325c6b38bf966"
+sha512 = "5a63c1f36de0c4548e1d2297bdbededb28721cbad94ef7825c469eae29d7451c97e00b4c1d6730ee1ec0c4a5aac922961a2795762d4a0c3bb54e30a391a84bae"

wit-0.3.0-draft/deps.toml

@@ -0,0 +1,7 @@
+io = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
+cli = "https://github.com/WebAssembly/wasi-cli/archive/main.tar.gz"
+random = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz"
+clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
+# not used by http/proxy, but included to allow full contents of wasi-cli to validate
+filesystem = "https://github.com/WebAssembly/wasi-filesystem/archive/main.tar.gz"
+sockets = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"

wit-0.3.0-draft/deps/cli/command.wit

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

wit-0.3.0-draft/deps/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>;
+}

wit-0.3.0-draft/deps/cli/exit.wit

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

wit-0.3.0-draft/deps/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;
+}

wit-0.3.0-draft/deps/cli/run.wit

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

wit-0.3.0-draft/deps/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;
+}

wit-0.3.0-draft/deps/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>;
+}

wit-0.3.0-draft/deps/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;
+}

wit-0.3.0-draft/deps/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;
+}

wit-0.3.0-draft/deps/clocks/world.wit

@@ -0,0 +1,6 @@
+package wasi:clocks@0.2.0;
+
+world imports {
+    import monotonic-clock;
+    import wall-clock;
+}

wit-0.3.0-draft/deps/filesystem/preopens.wit

@@ -0,0 +1,8 @@
+package wasi:filesystem@0.2.0;
+
+interface preopens {
+    use types.{descriptor};
+
+    /// Return the set of preopened directories, and their path.
+    get-directories: func() -> list<tuple<descriptor, string>>;
+}