Skip to content

Commit 7f065d1

Browse files
dicejdicej
authored
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]>
1 parent 32da63e commit 7f065d1

35 files changed

+2704
-8
lines changed

‎imports.md

+12-8
Original file line numberDiff line numberDiff line change
@@ -810,11 +810,9 @@ http-related errors.</p>
810810
which have multiple values are represented by multiple entries in this
811811
list with the same key.</p>
812812
<p>The tuple is a pair of the field key, represented as a string, and
813-
Value, represented as a list of bytes. In a valid Fields, all keys
814-
and values are valid UTF-8 strings. However, values are not always
815-
well-formed, so they are represented as a raw list of bytes.</p>
816-
<p>An error result will be returned if any header or value was
817-
syntactically invalid, or if a header was forbidden.</p>
813+
Value, represented as a list of bytes.</p>
814+
<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
815+
syntactically invalid, or if a field is forbidden.</p>
818816
<h5>Params</h5>
819817
<ul>
820818
<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>
825823
</ul>
826824
<h4><a name="method_fields.get"></a><code>[method]fields.get: func</code></h4>
827825
<p>Get all of the values corresponding to a key. If the key is not present
828-
in this <a href="#fields"><code>fields</code></a>, an empty list is returned. However, if the key is
829-
present but empty, this is represented by a list with one or more
830-
empty field-values present.</p>
826+
in this <a href="#fields"><code>fields</code></a> or is syntactically invalid, an empty list is returned.
827+
However, if the key is present but empty, this is represented by a list
828+
with one or more empty field-values present.</p>
831829
<h5>Params</h5>
832830
<ul>
833831
<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>
853851
<p>Set all of the values for a key. Clears any existing values for that
854852
key, if they have been set.</p>
855853
<p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
854+
<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> or any of
855+
the <a href="#field_value"><code>field-value</code></a>s are syntactically invalid.</p>
856856
<h5>Params</h5>
857857
<ul>
858858
<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>
867867
<p>Delete all values for a key. Does nothing if no values for the key
868868
exist.</p>
869869
<p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
870+
<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> is
871+
syntactically invalid.</p>
870872
<h5>Params</h5>
871873
<ul>
872874
<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>
880882
<p>Append a value for a key. Does not change or delete any existing
881883
values for that key.</p>
882884
<p>Fails with <code>header-error.immutable</code> if the <a href="#fields"><code>fields</code></a> are immutable.</p>
885+
<p>Fails with <code>header-error.invalid-syntax</code> if the <a href="#field_key"><code>field-key</code></a> or
886+
<a href="#field_value"><code>field-value</code></a> are syntactically invalid.</p>
883887
<h5>Params</h5>
884888
<ul>
885889
<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

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
[cli]
2+
url = "https://github.com/WebAssembly/wasi-cli/archive/main.tar.gz"
3+
sha256 = "285865a31d777181b075f39e92bcfe59c89cd6bacce660be1b9a627646956258"
4+
sha512 = "da2622210a9e3eea82b99f1a5b8a44ce5443d009cb943f7bca0bf9cf4360829b289913d7ee727c011f0f72994ea7dc8e661ebcc0a6b34b587297d80cd9b3f7e8"
5+
6+
[clocks]
7+
url = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
8+
sha256 = "468b4d12892fe926b8eb5d398dbf579d566c93231fa44f415440572c695b7613"
9+
sha512 = "e6b53a07221f1413953c9797c68f08b815fdaebf66419bbc1ea3e8b7dece73731062693634731f311a03957b268cf9cc509c518bd15e513c318aa04a8459b93a"
10+
11+
[filesystem]
12+
url = "https://github.com/WebAssembly/wasi-filesystem/archive/main.tar.gz"
13+
sha256 = "498c465cfd04587db40f970fff2185daa597d074c20b68a8bcbae558f261499b"
14+
sha512 = "ead452f9b7bfb88593a502ec00d76d4228003d51c40fd0408aebc32d35c94673551b00230d730873361567cc209ec218c41fb4e95bad194268592c49e7964347"
15+
16+
[io]
17+
url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
18+
sha256 = "7210e5653539a15478f894d4da24cc69d61924cbcba21d2804d69314a88e5a4c"
19+
sha512 = "49184a1b0945a889abd52d25271172ed3dc2db6968fcdddb1bab7ee0081f4a3eeee0977ad2291126a37631c0d86eeea75d822fa8af224c422134500bf9f0f2bb"
20+
21+
[random]
22+
url = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz"
23+
sha256 = "7371d03c037d924caba2587fb2e7c5773a0d3c5fcecbf7971e0e0ba57973c53d"
24+
sha512 = "964c4e8925a53078e4d94ba907b54f89a0b7e154f46823a505391471466c17f53c8692682e5c85771712acd88b348686173fc07c53a3cfe3d301b8cd8ddd0de4"
25+
26+
[sockets]
27+
url = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"
28+
sha256 = "622bd28bbeb43736375dc02bd003fd3a016ff8ee91e14bab488325c6b38bf966"
29+
sha512 = "5a63c1f36de0c4548e1d2297bdbededb28721cbad94ef7825c469eae29d7451c97e00b4c1d6730ee1ec0c4a5aac922961a2795762d4a0c3bb54e30a391a84bae"

‎wit-0.3.0-draft/deps.toml

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

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

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
package wasi:cli@0.2.0;
2+
3+
world command {
4+
include imports;
5+
6+
export run;
7+
}

‎wit-0.3.0-draft/deps/cli/environment.wit

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
interface environment {
2+
/// Get the POSIX-style environment variables.
3+
///
4+
/// Each environment variable is provided as a pair of string variable names
5+
/// and string value.
6+
///
7+
/// Morally, these are a value import, but until value imports are available
8+
/// in the component model, this import function should return the same
9+
/// values each time it is called.
10+
get-environment: func() -> list<tuple<string, string>>;
11+
12+
/// Get the POSIX-style arguments to the program.
13+
get-arguments: func() -> list<string>;
14+
15+
/// Return a path that programs should use as their initial current working
16+
/// directory, interpreting `.` as shorthand for this.
17+
initial-cwd: func() -> option<string>;
18+
}

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

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

‎wit-0.3.0-draft/deps/cli/imports.wit

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
package wasi:cli@0.2.0;
2+
3+
world imports {
4+
include wasi:clocks/imports@0.2.0;
5+
include wasi:filesystem/imports@0.2.0;
6+
include wasi:sockets/imports@0.2.0;
7+
include wasi:random/imports@0.2.0;
8+
include wasi:io/imports@0.2.0;
9+
10+
import environment;
11+
import exit;
12+
import stdin;
13+
import stdout;
14+
import stderr;
15+
import terminal-input;
16+
import terminal-output;
17+
import terminal-stdin;
18+
import terminal-stdout;
19+
import terminal-stderr;
20+
}

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

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface run {
2+
/// Run the program.
3+
run: func() -> result;
4+
}

‎wit-0.3.0-draft/deps/cli/stdio.wit

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
interface stdin {
2+
use wasi:io/streams@0.2.0.{input-stream};
3+
4+
get-stdin: func() -> input-stream;
5+
}
6+
7+
interface stdout {
8+
use wasi:io/streams@0.2.0.{output-stream};
9+
10+
get-stdout: func() -> output-stream;
11+
}
12+
13+
interface stderr {
14+
use wasi:io/streams@0.2.0.{output-stream};
15+
16+
get-stderr: func() -> output-stream;
17+
}

‎wit-0.3.0-draft/deps/cli/terminal.wit

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/// Terminal input.
2+
///
3+
/// In the future, this may include functions for disabling echoing,
4+
/// disabling input buffering so that keyboard events are sent through
5+
/// immediately, querying supported features, and so on.
6+
interface terminal-input {
7+
/// The input side of a terminal.
8+
resource terminal-input;
9+
}
10+
11+
/// Terminal output.
12+
///
13+
/// In the future, this may include functions for querying the terminal
14+
/// size, being notified of terminal size changes, querying supported
15+
/// features, and so on.
16+
interface terminal-output {
17+
/// The output side of a terminal.
18+
resource terminal-output;
19+
}
20+
21+
/// An interface providing an optional `terminal-input` for stdin as a
22+
/// link-time authority.
23+
interface terminal-stdin {
24+
use terminal-input.{terminal-input};
25+
26+
/// If stdin is connected to a terminal, return a `terminal-input` handle
27+
/// allowing further interaction with it.
28+
get-terminal-stdin: func() -> option<terminal-input>;
29+
}
30+
31+
/// An interface providing an optional `terminal-output` for stdout as a
32+
/// link-time authority.
33+
interface terminal-stdout {
34+
use terminal-output.{terminal-output};
35+
36+
/// If stdout is connected to a terminal, return a `terminal-output` handle
37+
/// allowing further interaction with it.
38+
get-terminal-stdout: func() -> option<terminal-output>;
39+
}
40+
41+
/// An interface providing an optional `terminal-output` for stderr as a
42+
/// link-time authority.
43+
interface terminal-stderr {
44+
use terminal-output.{terminal-output};
45+
46+
/// If stderr is connected to a terminal, return a `terminal-output` handle
47+
/// allowing further interaction with it.
48+
get-terminal-stderr: func() -> option<terminal-output>;
49+
}

‎wit-0.3.0-draft/deps/clocks/monotonic-clock.wit

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
package wasi:clocks@0.2.0;
2+
/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
3+
/// time.
4+
///
5+
/// It is intended to be portable at least between Unix-family platforms and
6+
/// Windows.
7+
///
8+
/// A monotonic clock is a clock which has an unspecified initial value, and
9+
/// successive reads of the clock will produce non-decreasing values.
10+
///
11+
/// It is intended for measuring elapsed time.
12+
interface monotonic-clock {
13+
use wasi:io/poll@0.2.0.{pollable};
14+
15+
/// An instant in time, in nanoseconds. An instant is relative to an
16+
/// unspecified initial value, and can only be compared to instances from
17+
/// the same monotonic-clock.
18+
type instant = u64;
19+
20+
/// A duration of time, in nanoseconds.
21+
type duration = u64;
22+
23+
/// Read the current value of the clock.
24+
///
25+
/// The clock is monotonic, therefore calling this function repeatedly will
26+
/// produce a sequence of non-decreasing values.
27+
now: func() -> instant;
28+
29+
/// Query the resolution of the clock. Returns the duration of time
30+
/// corresponding to a clock tick.
31+
resolution: func() -> duration;
32+
33+
/// Create a `pollable` which will resolve once the specified instant
34+
/// occured.
35+
subscribe-instant: func(
36+
when: instant,
37+
) -> pollable;
38+
39+
/// Create a `pollable` which will resolve once the given duration has
40+
/// elapsed, starting at the time at which this function was called.
41+
/// occured.
42+
subscribe-duration: func(
43+
when: duration,
44+
) -> pollable;
45+
}

‎wit-0.3.0-draft/deps/clocks/wall-clock.wit

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
package wasi:clocks@0.2.0;
2+
/// WASI Wall Clock is a clock API intended to let users query the current
3+
/// time. The name "wall" makes an analogy to a "clock on the wall", which
4+
/// is not necessarily monotonic as it may be reset.
5+
///
6+
/// It is intended to be portable at least between Unix-family platforms and
7+
/// Windows.
8+
///
9+
/// A wall clock is a clock which measures the date and time according to
10+
/// some external reference.
11+
///
12+
/// External references may be reset, so this clock is not necessarily
13+
/// monotonic, making it unsuitable for measuring elapsed time.
14+
///
15+
/// It is intended for reporting the current date and time for humans.
16+
interface wall-clock {
17+
/// A time and date in seconds plus nanoseconds.
18+
record datetime {
19+
seconds: u64,
20+
nanoseconds: u32,
21+
}
22+
23+
/// Read the current value of the clock.
24+
///
25+
/// This clock is not monotonic, therefore calling this function repeatedly
26+
/// will not necessarily produce a sequence of non-decreasing values.
27+
///
28+
/// The returned timestamps represent the number of seconds since
29+
/// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch],
30+
/// also known as [Unix Time].
31+
///
32+
/// The nanoseconds field of the output is always less than 1000000000.
33+
///
34+
/// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
35+
/// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
36+
now: func() -> datetime;
37+
38+
/// Query the resolution of the clock.
39+
///
40+
/// The nanoseconds field of the output is always less than 1000000000.
41+
resolution: func() -> datetime;
42+
}

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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
package wasi:clocks@0.2.0;
2+
3+
world imports {
4+
import monotonic-clock;
5+
import wall-clock;
6+
}

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

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
package wasi:filesystem@0.2.0;
2+
3+
interface preopens {
4+
use types.{descriptor};
5+
6+
/// Return the set of preopened directories, and their path.
7+
get-directories: func() -> list<tuple<descriptor, string>>;
8+
}

0 commit comments

Comments
 (0)