Skip to content

Commit

Permalink
Convert tabs to whitespaces
Browse files Browse the repository at this point in the history
  • Loading branch information
@badeend
badeend committed Nov 6, 2023
1 parent 0cd8492 commit b35f908
Show file tree
Hide file tree
Showing 10 changed files with 744 additions and 720 deletions.
10 changes: 5 additions & 5 deletions Posix-compatibility.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,12 +135,12 @@ Additionally, most columns have been populated semi-automatically by grepping th
Columns:
- "Socket option": The native option constant.
- "WASI":
- ✅ = Included in proposal.
- ⛔ = Consciously decided _not_ to include in WASI. See notes for explanation.
- ❔ = Not included (yet), for no particular reason.
- ✅ = Included in proposal.
- ⛔ = Consciously decided _not_ to include in WASI. See notes for explanation.
- ❔ = Not included (yet), for no particular reason.
- The rest:
- ✅ = Option is provided by the platform / depended upon by the application.
- ❌ = Option is not provided / not used.
- ✅ = Option is provided by the platform / depended upon by the application.
- ❌ = Option is not provided / not used.

> Note: GitHub clips the table content. Scroll left and right to see all columns, or use the Code View.
Expand Down
44 changes: 22 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,13 +88,13 @@ finish-operation: func(this) -> result<the-outputs..., error-code>

The semantics are as follows:
- When `start-*` completes successfully:
- The operation should be considered "in progress".
- This is the POSIX equivalent of EINPROGRESS.
- The socket can be polled for completion of the just started operation, using `wasi-poll`.
- Its corresponding `finish-*` function can be called until it returns something other than the `would-block` error code.
- The operation should be considered "in progress".
- This is the POSIX equivalent of EINPROGRESS.
- The socket can be polled for completion of the just started operation, using `wasi-poll`.
- Its corresponding `finish-*` function can be called until it returns something other than the `would-block` error code.
- When `finish-*` returns anything other than `would-block`:
- The asynchronous operation should be considered "finished" (either successful or failed)
- Future calls to `finish-*` return the `not-in-progress` error code.
- The asynchronous operation should be considered "finished" (either successful or failed)
- Future calls to `finish-*` return the `not-in-progress` error code.

Runtimes that don't need asynchrony, can simply validate the arguments provided to the `start` function and stash them on their internal socket instance and perform the actual syscall in the `finish` function. Conveniently, sockets only allow one of these `start/finish` asynchronous operation to be active at a time.

Expand All @@ -103,22 +103,22 @@ Example of how to recover blocking semantics in guest code:
```rs
// Pseudo code:
fn blocking-connect(sock: tcp-socket, addr: ip-socket-address) -> result<tuple<input-stream, output-stream>, error-code> {
let pollable = tcp::subscribe(tcp-socket);

let start-result = tcp::start-connect(sock, addr);
if (start-result is error) {
return error;
}

while (true) {
poll::poll-oneoff([ pollable ]);

let finish-result = tcp::finish-connect(sock);
if (finish-result is NOT error(would-block)) {
return finish-result;
}
}
let pollable = tcp::subscribe(tcp-socket);

let start-result = tcp::start-connect(sock, addr);
if (start-result is error) {
return error;
}

while (true) {
poll::poll-oneoff([ pollable ]);

let finish-result = tcp::finish-connect(sock);
if (finish-result is NOT error(would-block)) {
return finish-result;
}
}
}

```
Expand Down
32 changes: 28 additions & 4 deletions imports.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@
<hr />
<h3>Types</h3>
<h4><a name="network"><code>resource network</code></a></h4>
<p>An opaque resource that represents access to (a subset of) the network.
This enables context-based security for networking.
There is no need for this to map 1:1 to a physical network interface.</p>
<h4><a name="error_code"><code>enum error-code</code></a></h4>
<p>Error codes.</p>
<p>In theory, every API can return any error code.
Expand Down Expand Up @@ -246,7 +249,7 @@ at once.</p>
<hr />
<h3>Types</h3>
<h4><a name="pollable"><code>resource pollable</code></a></h4>
<hr />
<h2><a href="#pollable"><code>pollable</code></a> epresents a single I/O event which may be ready, or not.</h2>
<h3>Functions</h3>
<h4><a name="method_pollable.ready"><code>[method]pollable.ready: func</code></a></h4>
<p>Return the readiness of a pollable. This function never blocks.</p>
Expand Down Expand Up @@ -315,7 +318,7 @@ being reaedy for I/O.</p>
<li><a name="datagram.remote_address"><code>remote-address</code></a>: <a href="#ip_socket_address"><a href="#ip_socket_address"><code>ip-socket-address</code></a></a></li>
</ul>
<h4><a name="udp_socket"><code>resource udp-socket</code></a></h4>
<hr />
<h2>A UDP socket handle.</h2>
<h3>Functions</h3>
<h4><a name="method_udp_socket.start_bind"><code>[method]udp-socket.start-bind: func</code></a></h4>
<p>Bind the socket to a specific network on the provided IP address and port.</p>
Expand Down Expand Up @@ -708,6 +711,14 @@ when it does, they are expected to subsume this API.</p>
<p><a href="#pollable"><a href="#pollable"><code>pollable</code></a></a></p>
<p>
#### <a name="error">`resource error`</a>
<p>Contextual error information about the last failure that happened on
a read, write, or flush from an <a href="#input_stream"><code>input-stream</code></a> or <a href="#output_stream"><code>output-stream</code></a>.</p>
<p>This type is returned through the <a href="#stream_error"><code>stream-error</code></a> type whenever an
operation on a stream directly fails or an error is discovered
after-the-fact, for example when a write's failure shows up through a
later <code>flush</code> or <code>check-write</code>.</p>
<p>Interfaces such as <code>wasi:filesystem/types</code> provide functionality to
further &quot;downcast&quot; this error into interface-specific error information.</p>
<h4><a name="stream_error"><code>variant stream-error</code></a></h4>
<p>An error for input-stream and output-stream operations.</p>
<h5>Variant Cases</h5>
Expand All @@ -725,8 +736,21 @@ future operations.
</li>
</ul>
<h4><a name="input_stream"><code>resource input-stream</code></a></h4>
<p>An input bytestream.</p>
<p><a href="#input_stream"><code>input-stream</code></a>s are <em>non-blocking</em> to the extent practical on underlying
platforms. I/O operations always return promptly; if fewer bytes are
promptly available than requested, they return the number of bytes promptly
available, which could even be zero. To wait for data to be available,
use the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be polled
for using <a href="#wasi:io_poll"><code>wasi:io/poll</code></a>.</p>
<h4><a name="output_stream"><code>resource output-stream</code></a></h4>
<hr />
<p>An output bytestream.</p>
<h2><a href="#output_stream"><code>output-stream</code></a>s are <em>non-blocking</em> to the extent practical on
underlying platforms. Except where specified otherwise, I/O operations also
always return promptly, after the number of bytes that can be written
promptly, which could even be zero. To wait for the stream to be ready to
accept data, the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be
polled for using <a href="#wasi:io_poll"><code>wasi:io/poll</code></a>.</h2>
<h3>Functions</h3>
<h4><a name="method_error.to_debug_string"><code>[method]error.to-debug-string: func</code></a></h4>
<p>Returns a string that's suitable to assist humans in debugging this
Expand Down Expand Up @@ -1053,7 +1077,7 @@ is ready for reading, before performing the <code>splice</code>.</p>
</li>
</ul>
<h4><a name="tcp_socket"><code>resource tcp-socket</code></a></h4>
<hr />
<h2>A TCP socket handle.</h2>
<h3>Functions</h3>
<h4><a name="method_tcp_socket.start_bind"><code>[method]tcp-socket.start-bind: func</code></a></h4>
<p>Bind the socket to a specific network on the provided IP address and port.</p>
Expand Down
6 changes: 3 additions & 3 deletions wit/instance-network.wit
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@

/// This interface provides a value-export of the default network handle..
interface instance-network {
use network.{network};
use network.{network};

/// Get a handle to the default network.
instance-network: func() -> network;
/// Get a handle to the default network.
instance-network: func() -> network;

}
108 changes: 54 additions & 54 deletions wit/ip-name-lookup.wit
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,61 @@

interface ip-name-lookup {
use wasi:io/poll.{pollable};
use network.{network, error-code, ip-address, ip-address-family};
use wasi:io/poll.{pollable};
use network.{network, error-code, ip-address, ip-address-family};


/// Resolve an internet host name to a list of IP addresses.
///
/// See the wasi-socket proposal README.md for a comparison with getaddrinfo.
///
/// # Parameters
/// - `name`: The name to look up. IP addresses are not allowed. Unicode domain names are automatically converted
/// to ASCII using IDNA encoding.
/// - `address-family`: If provided, limit the results to addresses of this specific address family.
/// - `include-unavailable`: When set to true, this function will also return addresses of which the runtime
/// thinks (or knows) can't be connected to at the moment. For example, this will return IPv6 addresses on
/// systems without an active IPv6 interface. Notes:
/// - Even when no public IPv6 interfaces are present or active, names like "localhost" can still resolve to an IPv6 address.
/// - Whatever is "available" or "unavailable" is volatile and can change everytime a network cable is unplugged.
///
/// This function never blocks. It either immediately fails or immediately returns successfully with a `resolve-address-stream`
/// that can be used to (asynchronously) fetch the results.
///
/// At the moment, the stream never completes successfully with 0 items. Ie. the first call
/// to `resolve-next-address` never returns `ok(none)`. This may change in the future.
///
/// # Typical errors
/// - `invalid-name`: `name` is a syntactically invalid domain name.
/// - `invalid-name`: `name` is an IP address.
/// - `address-family-not-supported`: The specified `address-family` is not supported. (EAI_FAMILY)
///
/// # References:
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
/// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
/// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
resolve-addresses: func(network: borrow<network>, name: string, address-family: option<ip-address-family>, include-unavailable: bool) -> result<resolve-address-stream, error-code>;
/// Resolve an internet host name to a list of IP addresses.
///
/// See the wasi-socket proposal README.md for a comparison with getaddrinfo.
///
/// # Parameters
/// - `name`: The name to look up. IP addresses are not allowed. Unicode domain names are automatically converted
/// to ASCII using IDNA encoding.
/// - `address-family`: If provided, limit the results to addresses of this specific address family.
/// - `include-unavailable`: When set to true, this function will also return addresses of which the runtime
/// thinks (or knows) can't be connected to at the moment. For example, this will return IPv6 addresses on
/// systems without an active IPv6 interface. Notes:
/// - Even when no public IPv6 interfaces are present or active, names like "localhost" can still resolve to an IPv6 address.
/// - Whatever is "available" or "unavailable" is volatile and can change everytime a network cable is unplugged.
///
/// This function never blocks. It either immediately fails or immediately returns successfully with a `resolve-address-stream`
/// that can be used to (asynchronously) fetch the results.
///
/// At the moment, the stream never completes successfully with 0 items. Ie. the first call
/// to `resolve-next-address` never returns `ok(none)`. This may change in the future.
///
/// # Typical errors
/// - `invalid-name`: `name` is a syntactically invalid domain name.
/// - `invalid-name`: `name` is an IP address.
/// - `address-family-not-supported`: The specified `address-family` is not supported. (EAI_FAMILY)
///
/// # References:
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
/// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
/// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
resolve-addresses: func(network: borrow<network>, name: string, address-family: option<ip-address-family>, include-unavailable: bool) -> result<resolve-address-stream, error-code>;

resource resolve-address-stream {
/// Returns the next address from the resolver.
///
/// This function should be called multiple times. On each call, it will
/// return the next address in connection order preference. If all
/// addresses have been exhausted, this function returns `none`.
///
/// This function never returns IPv4-mapped IPv6 addresses.
///
/// # Typical errors
/// - `name-unresolvable`: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
/// - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN)
/// - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL)
/// - `would-block`: A result is not available yet. (EWOULDBLOCK, EAGAIN)
resolve-next-address: func() -> result<option<ip-address>, error-code>;
resource resolve-address-stream {
/// Returns the next address from the resolver.
///
/// This function should be called multiple times. On each call, it will
/// return the next address in connection order preference. If all
/// addresses have been exhausted, this function returns `none`.
///
/// This function never returns IPv4-mapped IPv6 addresses.
///
/// # Typical errors
/// - `name-unresolvable`: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
/// - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN)
/// - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL)
/// - `would-block`: A result is not available yet. (EWOULDBLOCK, EAGAIN)
resolve-next-address: func() -> result<option<ip-address>, error-code>;

/// Create a `pollable` which will resolve once the stream is ready for I/O.
///
/// Note: this function is here for WASI Preview2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
subscribe: func() -> pollable;
}
/// Create a `pollable` which will resolve once the stream is ready for I/O.
///
/// Note: this function is here for WASI Preview2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
subscribe: func() -> pollable;
}
}
Loading

0 comments on commit b35f908

Please sign in to comment.